smartexit/readme.md

127 lines
4.8 KiB
Markdown
Raw Permalink Normal View History

2024-04-18 11:36:09 +00:00
# @push.rocks/smartexit
A library for performing cleanup operations before exiting a Node.js process, ensuring graceful shutdowns.
2019-05-16 16:48:45 +00:00
2024-04-14 15:33:39 +00:00
## Install
2024-04-18 11:36:09 +00:00
To install `@push.rocks/smartexit`, use npm or Yarn as follows:
2024-04-14 15:33:39 +00:00
```bash
npm install @push.rocks/smartexit --save
```
2024-04-18 11:36:09 +00:00
or
2024-04-14 15:33:39 +00:00
```bash
yarn add @push.rocks/smartexit
```
2019-05-16 16:48:45 +00:00
## Usage
2024-04-18 11:36:09 +00:00
This library is designed to facilitate graceful shutdowns in Node.js applications by allowing developers to easily perform cleanup operations (like closing database connections or stopping child processes) before the process exits. Below is a guide on integrating `@push.rocks/smartexit` using TypeScript.
2024-04-14 15:33:39 +00:00
2024-04-18 11:36:09 +00:00
### Basic Setup
2024-04-14 15:33:39 +00:00
2024-04-18 11:36:09 +00:00
First, import `SmartExit` from the package:
2024-04-18 11:26:02 +00:00
2024-04-18 11:36:09 +00:00
```typescript
import { SmartExit } from '@push.rocks/smartexit';
```
2024-04-18 11:26:02 +00:00
2024-04-18 11:36:09 +00:00
Create an instance of `SmartExit`:
2024-04-14 15:33:39 +00:00
```typescript
2024-04-18 11:36:09 +00:00
const smartExit = new SmartExit();
2024-04-14 15:33:39 +00:00
```
2024-04-18 11:36:09 +00:00
### Registering Cleanup Functions
2024-04-14 15:33:39 +00:00
2024-04-18 11:36:09 +00:00
`SmartExit` enables you to define custom cleanup functions that are executed before the process exits. These functions should return a promise to ensure all asynchronous cleanup operations complete successfully.
2024-04-14 15:33:39 +00:00
```typescript
2024-04-18 11:36:09 +00:00
smartExit.addCleanupFunction(async () => {
console.log("Performing custom cleanup...");
// Your cleanup operations here
});
2024-04-14 15:33:39 +00:00
```
2024-04-18 11:26:02 +00:00
### Managing Child Processes
2024-04-18 11:36:09 +00:00
It's common for a Node.js application to spawn child processes. `SmartExit` can also manage these, ensuring all child processes cleanly exit before the parent process exits.
2024-04-14 15:33:39 +00:00
2024-04-18 11:36:09 +00:00
To add a child process to the management list:
2024-04-14 15:33:39 +00:00
```typescript
import { spawn } from 'child_process';
2024-04-18 11:36:09 +00:00
const childProcess = spawn('your_child_process');
smartExit.addProcess(childProcess);
2024-04-14 15:33:39 +00:00
```
2024-04-18 11:36:09 +00:00
If necessary, you can remove a previously added child process:
2024-04-14 15:33:39 +00:00
```typescript
2024-04-18 11:36:09 +00:00
smartExit.removeProcess(childProcess);
2024-04-14 15:33:39 +00:00
```
2024-04-18 11:36:09 +00:00
### Triggering Cleanup
2024-04-14 15:33:39 +00:00
2024-04-18 11:36:09 +00:00
`SmartExit` automatically hooks into several process signal events (like `SIGTERM` and `SIGINT`) to start the cleanup procedure. However, you can manually trigger the cleanup and exit processes:
2024-04-14 15:33:39 +00:00
```typescript
2024-04-18 11:36:09 +00:00
await smartExit.killAll();
process.exit(0); // or process.exit(1) to indicate an error state if needed
2024-04-14 15:33:39 +00:00
```
2024-04-18 11:36:09 +00:00
### Advanced Usage
2024-04-14 15:33:39 +00:00
2024-04-18 11:36:09 +00:00
In more complex scenarios, you might need to conditionally add or remove cleanup functions and child processes, or integrate `SmartExit` with other libraries and frameworks for more comprehensive process management and shutdown procedures. Here you can leverage the full flexibility of JavaScript and TypeScript to tailor the shutdown behavior to your application's specific needs.
2024-04-18 11:26:02 +00:00
2024-04-18 11:36:09 +00:00
#### Example: Shutdown on Uncaught Exceptions
2024-04-14 15:33:39 +00:00
```typescript
2024-04-18 11:36:09 +00:00
process.on('uncaughtException', async (error) => {
console.error("Uncaught Exception:", error);
await smartExit.killAll(); // Ensures all cleanup functions and child processes are managed
process.exit(1); // Exits with error
});
2024-04-14 15:33:39 +00:00
```
2024-04-18 11:36:09 +00:00
#### Integrating with Express
2024-04-18 11:26:02 +00:00
2024-04-18 11:36:09 +00:00
If your application uses Express, you might want to close the server gracefully:
2024-04-14 15:33:39 +00:00
```typescript
2024-04-18 11:36:09 +00:00
const server = app.listen(port, () => {
console.log(`Server started on port ${port}`);
2024-04-14 15:33:39 +00:00
});
2024-04-18 11:36:09 +00:00
smartExit.addCleanupFunction(async () => {
console.log("Closing Express server...");
await new Promise((resolve) => server.close(resolve));
2024-04-14 15:33:39 +00:00
});
2024-04-18 11:26:02 +00:00
```
2024-04-14 15:33:39 +00:00
2024-04-18 11:26:02 +00:00
---
2024-04-14 15:33:39 +00:00
2024-04-18 11:36:09 +00:00
This documentation provides a foundational understanding of how to utilize `@push.rocks/smartexit` for managing graceful shutdowns in Node.js applications with TypeScript. Remember to adjust the code examples as necessary to fit your specific project requirements.
2024-04-14 15:33:39 +00:00
## License and Legal Information
This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
2023-09-11 08:29:01 +00:00
2024-04-14 15:33:39 +00:00
### Trademarks
2023-09-11 08:29:01 +00:00
2024-04-14 15:33:39 +00:00
This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
2021-07-27 11:42:13 +00:00
2024-04-14 15:33:39 +00:00
### Company Information
2021-07-27 11:42:13 +00:00
2024-04-14 15:33:39 +00:00
Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany
2021-07-27 11:42:13 +00:00
2024-04-14 15:33:39 +00:00
For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
2019-05-16 16:48:45 +00:00
2024-04-14 15:33:39 +00:00
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.