@strv/heimdall
v2.2.0
Published
A simple process signal manager
Downloads
1,631
Keywords
Readme
@strv/heimdall
The process lifecycle gatekeeper.
Built with ❤️ at STRV
Heimdall takes control over the Node.js process' signal handling and provides a simple way to respond to various process lifecycle events.
Installation
npm i --save @strv/heimdall
Usage
import { heimdall } from '@strv/heimdall'
// Import something important. Maybe a Koa server? Or Atlas.js instance?
import { app } from './app'
heimdall({
/**
* The execute method is invoked by Heimdall immediately after calling `heimdall()`. You can
* start your servers and set up any other important tasks here.
* @return {Promise}
*/
async execute() {
// Start whatever you need to start in this process. Whatever you return from this function, you
// will receive it in the .exit() method below.
return await app.start(process.env.PORT)
},
/**
* This method will be invoked by Heimdall when the process receives a `SIGINT` or `SIGTERM`
* signal. This method is also invoked when Node.js' event loop will empty and Node determines
* that it can safely exit itself.
* @return {Promise}
*/
async exit({ runtime }) {
// Stop your servers, close down your open sockets or other activities that might be
// keeping the Node process running.
await app.stop()
// runtime is exactly what you returned in .execute(), in this case it is the Koa instance
app === runtime
},
/**
* This optional method will be invoked by Heimdall when the process receives a second `SIGINT` or
* `SIGTERM` signal (ie. the user pressing ctrl+c twice). You can log something to the console or
* perform synchronous cleanup, but the Node process will be terminated shortly and any async I/O
* operations are not guaranteed to complete in time.
* @return {void}
*/
didReceiveForcequit() {
// This is a synchronous method call. Running async I/O operations is not guaranteed to work.
},
/**
* This optional method will be used by Heimdall when one of the Delegate's methods throws an
* error. Heimdall logs these errors to the stderr output stream but if you implement this method,
* it will let you log the error using your logging solution of choice.
*
* The log should be synchronous as the process will be terminated in the next event loop.
*/
logError(err) {
pino.error({ err }, 'heimdall received error')
}
/**
* Set this to true to let Heimdall call the exit handler as soon as the execute handler finishes
*
* This is ideal for one-off scripts, commands or other utilities where you want to do a task and
* then let the process exit gracefully.
*/
exitAfterExecute?: false
})
License
See the LICENSE file for information.