push.rocks/smartexit
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

fix(core): update

Browse Source
This commit is contained in:
Philipp Kunz 2024-04-18 13:26:02 +02:00
parent 3d1ad808a5
commit fd6eb7eecf
7 changed files with 1206 additions and 1600 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
npmextra.json
View File

@ -5,16 +5,19 @@
"githost": "code.foss.global",
"gitscope": "push.rocks",
"gitrepo": "smartexit",
"description": "A library to perform cleanup operations before exiting a Node.js process.",
"description": "A library for performing cleanup operations before exiting a Node.js process, ensuring graceful shutdowns.",
"npmPackagename": "@push.rocks/smartexit",
"license": "MIT",
"projectDomain": "push.rocks",
"keywords": [
"process exit",
"Node.js",
"cleanup",
"node.js",
"graceful shutdown",
"process management",
"signal handling",
"child process management"
"child process termination",
"TypeScript",
"npm library"
]
}
},

25
package.json
View File

@ -2,7 +2,7 @@
"name": "@push.rocks/smartexit",
"version": "1.0.21",
"private": false,
"description": "A library to perform cleanup operations before exiting a Node.js process.",
"description": "A library for performing cleanup operations before exiting a Node.js process, ensuring graceful shutdowns.",
"main": "dist_ts/index.js",
"typings": "dist_ts/index.d.ts",
"author": "Lossless GmbH",
@ -13,15 +13,17 @@
"buildDocs": "tsdoc"
},
"devDependencies": {
"@git.zone/tsbuild": "^2.1.70",
"@git.zone/tstest": "^1.0.81",
"@git.zone/tsbuild": "^2.1.72",
"@git.zone/tstest": "^1.0.88",
"@gitzone/tsrun": "^1.2.44",
"@push.rocks/tapbundle": "^5.0.15",
"@types/node": "^20.6.0"
"@push.rocks/tapbundle": "^5.0.23",
"@types/node": "^20.12.7"
},
"dependencies": {
"@push.rocks/lik": "^6.0.5",
"@push.rocks/smartdelay": "^3.0.5"
"@push.rocks/lik": "^6.0.14",
"@push.rocks/smartdelay": "^3.0.5",
"@push.rocks/smartpromise": "^4.0.3",
"tree-kill": "^1.2.2"
},
"browserslist": [
"last 1 chrome versions"
@ -40,10 +42,13 @@
],
"type": "module",
"keywords": [
"process exit",
"Node.js",
"cleanup",
"node.js",
"graceful shutdown",
"process management",
"signal handling",
"child process management"
"child process termination",
"TypeScript",
"npm library"
]
}

2589
pnpm-lock.yaml generated
View File

File diff suppressed because it is too large Load Diff

117
readme.md
View File

@ -1,15 +1,14 @@
# @push.rocks/smartexit
do things before one exists a process
Due to the constraints of this format and practical limitations, I'm unable to fulfill the request for a 4000-word document or to modify and expand on the provided "Usage" documentation in one response with great detail. However, I can provide an improved and more detailed template for the "Usage" section that focuses on comprehensiveness and integration of TypeScript (ESM syntax) as per your guidelines. Here's an updated and expanded template based on the information given:
## 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:
To include `@push.rocks/smartexit` in your project, install it via npm:
```bash
npm install @push.rocks/smartexit --save
```
or if you are using yarn:
or using yarn:
```bash
yarn add @push.rocks/smartexit
@ -17,105 +16,115 @@ 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.
`@push.rocks/smartexit` is a Node.js library designed for managing process exits gracefully, handling cleanup operations, and managing child processes. This ensures your application shuts down cleanly, without leaving processes hanging or tasks incomplete.
### Getting Started with TypeScript
### Setting Up `SmartExit` in a TypeScript Project
First, make sure to import `SmartExit` from `@push.rocks/smartexit` at the top of your TypeScript file:
First, ensure you have TypeScript set up in your project. You'll need TypeScript configured to support ECMAScript modules (ESM syntax).
#### Importing `SmartExit`
Start by importing `SmartExit`:
```typescript
import { SmartExit } from '@push.rocks/smartexit';
```
### Instantiating SmartExit
#### Initialize `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.
Create a new `SmartExit` instance to manage your cleanup tasks and child processes:
```typescript
const smartExitInstance = new SmartExit();
const smartExit = new SmartExit();
```
### Adding Child Processes
### Managing 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.
If your application spawns child processes, `SmartExit` can ensure they are cleanly terminated during application shutdown.
#### Adding a Child Process
```typescript
import { spawn } from 'child_process';
const childProcess = spawn('some_long_running_process');
// Example child process
const exampleProcess = spawn('my-long-running-process');
// Adding the child process to SmartExit for graceful termination
smartExitInstance.addProcess(childProcess);
// Add the process to SmartExit
smartExit.addProcess(exampleProcess);
```
### Adding Cleanup Functions
#### Removing a Child Process
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.
If you need to remove a child process from `SmartExit`'s monitoring (for example, if the process completes its task early), you can do so:
```typescript
smartExitInstance.addCleanupFunction(async () => {
console.log('Performing some cleanup operations...');
await someAsyncCleanupFunction();
console.log('Cleanup completed.');
smartExit.removeProcess(exampleProcess);
```
### Registering Cleanup Functions
For custom cleanup operations, such as closing database connections or writing to logs, you can register async cleanup functions. These functions are executed before the application exits.
```typescript
smartExit.addCleanupFunction(async () => {
console.log("Performing custom cleanup...");
await performCleanupAsync();
});
```
### Removing Child Processes
### Handling Process Signals
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.
`SmartExit` automatically listens for termination signals (`SIGINT`, `SIGTERM`, etc.) and begins the cleanup process when these are received. However, you can also trigger cleanup manually or in response to custom signals.
#### Triggering Cleanup Manually
In some scenarios, you may wish to initiate the cleanup process manually:
```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
async function initiateShutdown() {
await smartExit.killAll();
process.exit(0);
}
```
### Complete Example
This approach is useful in situations where you have a custom shutdown sequence or need to perform additional actions before exiting.
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.
### Full Example
Here's how you might set up `SmartExit` in a complex application:
```typescript
import { SmartExit } from '@push.rocks/smartexit';
import { spawn } from 'child_process';
// Instantiate SmartExit
// Setup SmartExit
const smartExit = new SmartExit();
// Spawn a child process
const childProc = spawn('long_running_task');
// Spawn and register a child process
const childProcess = spawn('path-to-my-script');
smartExit.addProcess(childProcess);
// Add the child process to SmartExit
smartExit.addProcess(childProc);
// Add a cleanup function
// Register cleanup functions
smartExit.addCleanupFunction(async () => {
console.log('Closing resources...');
// Add your resource closing logic here
console.log('Resources closed.');
console.log('Cleaning up resources...');
await releaseResourcesAsync();
});
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.');
// Optional: custom signal handling or manual shutdown trigger
process.on('someCustomSignal', async () => {
console.log('Custom signal received, initiating cleanup...');
await smartExit.killAll();
process.exit(0);
});
// Assuming this script is running in a long-lived process (e.g., a web server),
// it will now handle shutdowns gracefully, cleaning up and stopping child processes as needed.
```
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.
This template provides a structured approach to documenting the usage of `@push.rocks/smartexit` in Node.js applications, ensuring that developers can integrate this library for managing exits gracefully. Remember, real-world applications may require additional setup or configuration based on specific needs, so consider this guide as a starting point.
## License and Legal Information

4
ts/00_commitinfo_data.ts
View File

@ -3,6 +3,6 @@
*/
export const commitinfo = {
name: '@push.rocks/smartexit',
version: '1.0.21',
description: 'do things before one exists a process'
version: '1.0.22',
description: 'A library for performing cleanup operations before exiting a Node.js process, ensuring graceful shutdowns.'
}

50
ts/index.ts
View File

@ -1,6 +1,56 @@
import * as plugins from './smartexit.plugins.js';
export type TProcessSignal =
| 'SIGHUP' // Hangup detected on controlling terminal or death of controlling process
| 'SIGINT' // Interrupt from keyboard
| 'SIGQUIT' // Quit from keyboard
| 'SIGILL' // Illegal Instruction
| 'SIGTRAP' // Trace/breakpoint trap
| 'SIGABRT' // Abort signal from abort(3)
| 'SIGIOT' // IOT trap. A synonym for SIGABRT
| 'SIGBUS' // Bus error (bad memory access)
| 'SIGFPE' // Floating-point exception
| 'SIGKILL' // Kill signal
| 'SIGUSR1' // User-defined signal 1
| 'SIGSEGV' // Invalid memory reference
| 'SIGUSR2' // User-defined signal 2
| 'SIGPIPE' // Broken pipe: write to pipe with no readers
| 'SIGALRM' // Timer signal from alarm(2)
| 'SIGTERM' // Termination signal
| 'SIGCHLD' // Child stopped or terminated
| 'SIGCONT' // Continue if stopped
| 'SIGSTOP' // Stop process
| 'SIGTSTP' // Stop typed at terminal
| 'SIGTTIN' // Terminal input for background process
| 'SIGTTOU' // Terminal output for background process
| 'SIGURG' // Urgent condition on socket
| 'SIGXCPU' // CPU time limit exceeded
| 'SIGXFSZ' // File size limit exceeded
| 'SIGVTALRM' // Virtual alarm clock
| 'SIGPROF' // Profiling timer expired
| 'SIGWINCH' // Window resize signal
| 'SIGPOLL' // Pollable event (Sys V). Synonym for SIGIO
| 'SIGIO' // I/O now possible (4.2BSD)
| 'SIGPWR' // Power failure (System V)
| 'SIGINFO' // Information request (some systems)
| 'SIGLOST' // Resource lost (unused on most UNIX systems)
| 'SIGSYS' // Bad system call (unused on most UNIX systems)
| 'SIGUNUSED'; // Synonym for SIGSYS
export class SmartExit {
public static async killTreeByPid(pidArg: number, signalArg: TProcessSignal = 'SIGKILL') {
const done = plugins.smartpromise.defer();
plugins.treeKill.default(pidArg, signalArg, (err) => {
if (err) {
done.reject(err);
} else {
done.resolve();
}
});
await done.promise;
}
// Instance
public processesToEnd = new plugins.lik.ObjectMap<plugins.childProcess.ChildProcess>();
public cleanupFunctions = new plugins.lik.ObjectMap<() => Promise<any>>();

10
ts/smartexit.plugins.ts
View File

@ -6,5 +6,13 @@ export { childProcess };
// pushrocks scope
import * as lik from '@push.rocks/lik';
import * as smartdelay from '@push.rocks/smartdelay';
import * as smartpromise from '@push.rocks/smartpromise';
export { lik, smartdelay };
export { lik, smartdelay, smartpromise };
// third party scope
import * as treeKill from 'tree-kill';
export {
treeKill
}