background-process

Run a process in the background, disconnected from the main process.

Install

Install with npm:

$ npm install --save background-process

Install with yarn:

$ yarn add background-process

Usage

The api has two methods that can be used. The first method is .start and should be used in an application that runs the background script. This application is the runner.

The second method is .ready and should be used inside background scripts to know when they should start executing. The runner will use process.send to send an options object to the background script. The options object is passed as the second argument to the callback function passed to .ready.

The .ready method is not required to be used in the background script since the runner will "fire and forget" when it sends the options object. It's recommended to use .ready since it'll be easier to configure your background scripts.

Runner

This is an example of running a background script called my-script.js and passing an options object.

var background = require('background-process');
 
// start a background script and pass options to the script
var options = { foo: 'bar' };
background.start('my-script.js', options);

Script

This is an example of a background script called my-script.js that was passed an options object.

var background = require('background-process');
 
// wait for the options to be sent from the runner
background.ready(function(err, options) {
  if (err) return console.error(err);
  console.log(options);
});

One thing to note is that the stdio streams are not available in this example since the runner disconnects from the background script. To setup stdio streams for the background script, they may be specified on the options object as an array:

// setup stdio streams for the background script to write to
var stdout = fs.openSync('path/to/stdout.txt', 'a');
var stderr = fs.openSync('path/to/stderr.txt', 'a');
 
var options = { stdio: [stdout, stderr] };
background.start('my-script.js', options);

See the example for more information.

API

.start

Start a background script and send the new child process the given options before disconnecting from the child process.

Params

• fp {String}: filepath to the background script
• options {Object}: Additional options to send to the child process
• returns {Number}: Returns the child process ID.

Example

background.start('worker.js', { timeout: 5000 });

.ready

Use in a child script to know when to start running. The callback function will recieve a possible Error object and an options object. This is a wrapper for doing process.on('message', ...). This is not something that's required since the runner process will not wait for a response and disconnect. This is a way to send options from the runner to the background script.

Params

• cb {Function}: Callback function that will be executed when the options are recieved from the runner.

Example

background.ready(function(err, options) {
  if (err) return;
  // do something
});

Acknowledgements

My main goal was to run background scripts from a parent process and still let the parent process exit before the background process finished. In researching how to achieve my goal, I learned a lot from code in forever and forever-monitor.

About

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Please read the contributing guide for advice on opening issues, pull requests, and coding standards.

Building docs

(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

To generate the readme, run the following command:

$ npm install -g verbose/verb#dev verb-generate-readme && verb

Running tests

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

$ npm install && npm test

Author

Brian Woodward

• github/doowb
• twitter/doowb

License

Copyright © 2017, Brian Woodward. Released under the MIT License.

---

This file was generated by verb-generate-readme, v0.6.0, on May 08, 2017.