diff --git a/npmextra.json b/npmextra.json index b1ea13a..32e067c 100644 --- a/npmextra.json +++ b/npmextra.json @@ -5,17 +5,24 @@ "githost": "code.foss.global", "gitscope": "push.rocks", "gitrepo": "smartexit", - "description": "do things before one exists a process", + "description": "A library to perform cleanup operations before exiting a Node.js process.", "npmPackagename": "@push.rocks/smartexit", "license": "MIT", - "projectDomain": "push.rocks" + "projectDomain": "push.rocks", + "keywords": [ + "process exit", + "cleanup", + "node.js", + "signal handling", + "child process management" + ] } }, "npmci": { "npmGlobalTools": [], "npmAccessLevel": "public" }, - "tsdocs": { + "tsdoc": { "legal": "\n## License and Legal Information\n\nThis 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. \n\n**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.\n\n### Trademarks\n\nThis 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.\n\n### Company Information\n\nTask Venture Capital GmbH \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy 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.\n" } } \ No newline at end of file diff --git a/package.json b/package.json index 501253c..671d4d2 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "@push.rocks/smartexit", "version": "1.0.21", "private": false, - "description": "do things before one exists a process", + "description": "A library to perform cleanup operations before exiting a Node.js process.", "main": "dist_ts/index.js", "typings": "dist_ts/index.d.ts", "author": "Lossless GmbH", @@ -38,5 +38,12 @@ "npmextra.json", "readme.md" ], - "type": "module" -} + "type": "module", + "keywords": [ + "process exit", + "cleanup", + "node.js", + "signal handling", + "child process management" + ] +} \ No newline at end of file diff --git a/readme.hints.md b/readme.hints.md new file mode 100644 index 0000000..0519ecb --- /dev/null +++ b/readme.hints.md @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/readme.md b/readme.md index 4d4cee5..3d953ec 100644 --- a/readme.md +++ b/readme.md @@ -1,40 +1,137 @@ # @push.rocks/smartexit do things before one exists a process -## Availabililty and Links -* [npmjs.org (npm package)](https://www.npmjs.com/package/@push.rocks/smartexit) -* [gitlab.com (source)](https://gitlab.com/push.rocks/smartexit) -* [github.com (source mirror)](https://github.com/push.rocks/smartexit) -* [docs (typedoc)](https://push.rocks.gitlab.io/smartexit/) +## Install -## Status for master +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: -Status Category | Status Badge --- | -- -GitLab Pipelines | [![pipeline status](https://gitlab.com/push.rocks/smartexit/badges/master/pipeline.svg)](https://lossless.cloud) -GitLab Pipline Test Coverage | [![coverage report](https://gitlab.com/push.rocks/smartexit/badges/master/coverage.svg)](https://lossless.cloud) -npm | [![npm downloads per month](https://badgen.net/npm/dy/@push.rocks/smartexit)](https://lossless.cloud) -Snyk | [![Known Vulnerabilities](https://badgen.net/snyk/push.rocks/smartexit)](https://lossless.cloud) -TypeScript Support | [![TypeScript](https://badgen.net/badge/TypeScript/>=%203.x/blue?icon=typescript)](https://lossless.cloud) -node Support | [![node](https://img.shields.io/badge/node->=%2010.x.x-blue.svg)](https://nodejs.org/dist/latest-v10.x/docs/api/) -Code Style | [![Code Style](https://badgen.net/badge/style/prettier/purple)](https://lossless.cloud) -PackagePhobia (total standalone install weight) | [![PackagePhobia](https://badgen.net/packagephobia/install/@push.rocks/smartexit)](https://lossless.cloud) -PackagePhobia (package size on registry) | [![PackagePhobia](https://badgen.net/packagephobia/publish/@push.rocks/smartexit)](https://lossless.cloud) -BundlePhobia (total size when bundled) | [![BundlePhobia](https://badgen.net/bundlephobia/minzip/@push.rocks/smartexit)](https://lossless.cloud) +```bash +npm install @push.rocks/smartexit --save +``` + +or if you are using yarn: + +```bash +yarn add @push.rocks/smartexit +``` ## Usage -## Contribution +`@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. -We are always happy for code contributions. If you are not the code contributing type that is ok. Still, maintaining Open Source repositories takes considerable time and thought. If you like the quality of what we do and our modules are useful to you we would appreciate a little monthly contribution: You can [contribute one time](https://lossless.link/contribute-onetime) or [contribute monthly](https://lossless.link/contribute). :) +### Getting Started with TypeScript +First, make sure to import `SmartExit` from `@push.rocks/smartexit` at the top of your TypeScript file: -## Contribution +```typescript +import { SmartExit } from '@push.rocks/smartexit'; +``` -We are always happy for code contributions. If you are not the code contributing type that is ok. Still, maintaining Open Source repositories takes considerable time and thought. If you like the quality of what we do and our modules are useful to you we would appreciate a little monthly contribution: You can [contribute one time](https://lossless.link/contribute-onetime) or [contribute monthly](https://lossless.link/contribute). :) +### Instantiating SmartExit -For further information read the linked docs at the top of this readme. +You should create a single instance of `SmartExit` that will be used throughout your application. This instance will manage all processes and cleanup functions. -## Legal -> MIT licensed | **©** [Task Venture Capital GmbH](https://task.vc) -| By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy) +```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.