138 lines
5.4 KiB
Markdown
138 lines
5.4 KiB
Markdown
# @push.rocks/smartexit
|
|
do things before one exists a process
|
|
|
|
## Install
|
|
|
|
To include `@push.rocks/smartexit` in your project, you need to install it via npm or yarn. Run either of the following commands in your terminal:
|
|
|
|
```bash
|
|
npm install @push.rocks/smartexit --save
|
|
```
|
|
|
|
or if you are using yarn:
|
|
|
|
```bash
|
|
yarn add @push.rocks/smartexit
|
|
```
|
|
|
|
## Usage
|
|
|
|
`@push.rocks/smartexit` aims to facilitate graceful exits for Node.js processes, ensuring that all your cleanup functions are executed and child processes are terminated before the process exits. This can be particularly useful in long-running applications or applications that spawn child processes that also need to be correctly shutdown.
|
|
|
|
### Getting Started with TypeScript
|
|
|
|
First, make sure to import `SmartExit` from `@push.rocks/smartexit` at the top of your TypeScript file:
|
|
|
|
```typescript
|
|
import { SmartExit } from '@push.rocks/smartexit';
|
|
```
|
|
|
|
### Instantiating SmartExit
|
|
|
|
You should create a single instance of `SmartExit` that will be used throughout your application. This instance will manage all processes and cleanup functions.
|
|
|
|
```typescript
|
|
const smartExitInstance = new SmartExit();
|
|
```
|
|
|
|
### Adding Child Processes
|
|
|
|
If your application spawns child processes that should be gracefully terminated upon exit, you can add them to the `SmartExit` instance. This makes sure they are terminated before your main process exits.
|
|
|
|
```typescript
|
|
import { spawn } from 'child_process';
|
|
|
|
const childProcess = spawn('some_long_running_process');
|
|
|
|
// Adding the child process to SmartExit for graceful termination
|
|
smartExitInstance.addProcess(childProcess);
|
|
```
|
|
|
|
### Adding Cleanup Functions
|
|
|
|
For custom cleanup logic, such as closing database connections or completing file operations, you can add asynchronous cleanup functions. These will be awaited during the exit process.
|
|
|
|
```typescript
|
|
smartExitInstance.addCleanupFunction(async () => {
|
|
console.log('Performing some cleanup operations...');
|
|
await someAsyncCleanupFunction();
|
|
console.log('Cleanup completed.');
|
|
});
|
|
```
|
|
|
|
### Removing Child Processes
|
|
|
|
If a child process completes its work before the application is ready to exit, or if for some reason you no longer want SmartExit to track it, you can remove it from the monitoring list.
|
|
|
|
```typescript
|
|
smartExitInstance.removeProcess(childProcess);
|
|
```
|
|
|
|
### Custom Exit Scenarios
|
|
|
|
While `SmartExit` hooks into process exit and uncaught exceptions by default, you can manually trigger the cleanup and exit process in custom scenarios.
|
|
|
|
```typescript
|
|
async function customShutdown() {
|
|
await smartExitInstance.killAll();
|
|
process.exit(0); // or use another appropriate exit code
|
|
}
|
|
```
|
|
|
|
### Complete Example
|
|
|
|
Here is a complete example demonstrating how `@push.rocks/smartexit` can be integrated into a Node.js application that spawns a child process and has custom cleanup logic.
|
|
|
|
```typescript
|
|
import { SmartExit } from '@push.rocks/smartexit';
|
|
import { spawn } from 'child_process';
|
|
|
|
// Instantiate SmartExit
|
|
const smartExit = new SmartExit();
|
|
|
|
// Spawn a child process
|
|
const childProc = spawn('long_running_task');
|
|
|
|
// Add the child process to SmartExit
|
|
smartExit.addProcess(childProc);
|
|
|
|
// Add a cleanup function
|
|
smartExit.addCleanupFunction(async () => {
|
|
console.log('Closing resources...');
|
|
// Add your resource closing logic here
|
|
console.log('Resources closed.');
|
|
});
|
|
|
|
process.on('SIGINT', async () => {
|
|
console.log('Custom shutdown initiated...');
|
|
await smartExit.killAll(); // Ensure all processes and cleanup functions are addressed
|
|
console.log('Graceful shutdown completed.');
|
|
process.exit(0);
|
|
});
|
|
```
|
|
|
|
This setup ensures that your Node.js application can gracefully handle shutdowns, whether they are initiated by the system or manually by you. It's especially useful in microservices, web servers, or any application that needs to clean up resources properly before shutting down.
|
|
|
|
### Licensing
|
|
|
|
For licensing details, please check the `package.json` and npm documentation associated with `@push.rocks/smartexit`. The code examples provided above assume you comply with the MIT license under which `@push.rocks/smartexit` is distributed.
|
|
|
|
## 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.
|
|
|
|
### Trademarks
|
|
|
|
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.
|
|
|
|
### Company Information
|
|
|
|
Task Venture Capital GmbH
|
|
Registered at District court Bremen HRB 35230 HB, Germany
|
|
|
|
For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
|
|
|
|
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.
|