Usage

$3

``sh
npm install terminate --save
`

$3

`js
const terminate = require('terminate');

terminate(process.pid, function (err) {
if (err) { // you will get an error if you did not supply a valid process.pid
console.log('Oopsy:', err); // handle errors in your preferred way.
}
else {
console.log('done'); // terminating the Processes succeeded.
// NOTE: The above won't be run in this example as the process itself will be killed before.
}
});
`

$3

All the available parameters and their descriptions are viewable in the TypeScript definition file: index.d.ts.

`ts
// Function signature
terminate(pid: number, signal?: string, opts?: TerminateOptions, callback?: DoneCallback): void

// Function signature of the Promise version
terminate(pid: number, signal?: string, opts?: TerminateOptions): Promise
`

- pid - The Process ID you want to terminate.
- signal - The signal to kill the processes with. Defaults to "SIGKILL" if it's empty or not defined.
- opts.pollInterval - Interval to poll whether pid and all of the childs pids have been killed. Defaults to 500 (0.5s).
- opts.timeout - Max time (in milliseconds) to wait for process to exit before timing out and calling back with an error. Defaults to 5000 (5s).
- callback - The callback function to call when the termination is done. It has this signature: (error: Error | null): void whereas error will be null if the operation succeeds.

$3

If you are using Node.js 8+, you can load the Promise version importing the module terminate/promise.js like this:

`js
const terminate = require('terminate/promise');

(async () => {
try {
await terminate(process.pid);
console.log('done');
} catch (err) {
console.log('Oopsy:', err);
}
})();
``

tl;dr

Why?

In our Faster project
we run the server using Child Process(es).
When we want to re-start the server,
we needed to ensure the process (and any Child Processes)
were Terminated before attempting to re-start.

Prevents Zombie Processes

Imagine you are running your Node.js app on a Multi-Core Processor
and don't want to "waste" the CPU by only using one of those cores
(remember: one of Node's selling points is that its single-process running on a single-core),
you can "farm out" tasks to the other cores using Child Process(es)

If you then want to restart your app you naively (we did this!)
terminate the "main" process and expect all the "child" processes to
be ended too.

Sadly this results in Zombie Processes
which you would have to either manually kill or restart the machine/VM to clear.
Instead you need to find all the Process IDs for the child processes
that your app created and terminate those before you can re-start your app.

Using terminate you no longer have this problem.

Dependencies 

While researching how to get a list of child processes given a
Process ID we found ps-tree: https://github.com/indexzero/ps-tree
it was un-maintained and had no tests
so we submitted an issue
offering to update the module with tests.
Charlie
replied welcoming an update so we submitted
a Pull Request
with 100% test coverage which was Merged by Charlie
ps-tree in turn uses event-stream
(by Dominc Tarr) for streaming the result
of its process lookups.
event-stream does not publish its' code coverage,
but is tested (and more importantly used by millions of people)
has had many itterations and has been stable for a while:


While we don't like the fact that event-stream has dependencies which have
limited automated tests,
we are willing to place reliance on the module given how
"real-world tested" it is.

If at any point we find that relying event-stream or its underlying
dependencies is the source of a bug or sleepless nights,
we can either make time
to contribute the tests or write our own version of ps-tree
without dependencies
(which should "only" take a day but won't be as elegant...)

Research

$3

+ How to terminate node processes: https://github.com/joyent/node/issues/1172 (history lesson)
+ nodejs exec command failing with no useful error message:
https://github.com/joyent/node/issues/4590

$3

+ spawning node.js child processes results in zombie processes on cloud foundry
+ Why does my node app process keep getting stopped when I use forever?
+ kill all child_process when node process is killed
+ Why doesn't my Node.js process terminate once all listeners have been removed?
+ nodejs exec command failing with no useful error message
+ How many child processes can a node.js cluster spawn on a 64bit Wintel PC?
+ Why is Node.js single threaded?

Other potential modules we could have used:

+ node-ps: https://github.com/neekey/ps (has basic tests but no coverage / unmaintained?)
+ tree-kill: https://www.npmjs.com/package/tree-kill (no tests!!)
+ nexpect: https://github.com/nodejitsu/nexpect (spawn and control child processes
looks really good, but we wanted less abstraction)

$3

Terminate
seemed like the best (of the available) name,
if you have a better suggestion, please share!

This Project Reminded me of Two xkcd Comics:

!xkcd terminate

!xkcd time robot