background-process
Version:
Run a process in the background, disconnected from the main process.
145 lines (90 loc) • 5.5 kB
Markdown
# background-process [](https://www.npmjs.com/package/background-process) [](https://npmjs.org/package/background-process) [](https://npmjs.org/package/background-process) [](https://travis-ci.org/doowb/background-process)
> Run a process in the background, disconnected from the main process.
## Install
Install with [npm](https://www.npmjs.com/):
```sh
$ npm install --save background-process
```
Install with [yarn](https://yarnpkg.com):
```sh
$ yarn add background-process
```
## Usage
The api has two methods that can be used. The first method is [.start](#start) and should be used in an application that runs the background script. This application is the [runner](#runner).
The second method is [.ready](#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](#ready).
The [.ready](#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](#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.
```js
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.
```js
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:
```js
// 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](example) for more information.
## API
### [.start](index.js#L24)
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**
```js
background.start('worker.js', { timeout: 5000 });
```
### [.ready](index.js#L60)
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**
```js
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](https://github.com/foreverjs/forever) and [forever-monitor](https://github.com/nodejitsu/forever-monitor).
## About
### Contributing
Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
Please read the [contributing guide](.github/contributing.md) for advice on opening issues, pull requests, and coding standards.
### Building docs
_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_
To generate the readme, run the following command:
```sh
$ 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:
```sh
$ npm install && npm test
```
### Author
**Brian Woodward**
* [github/doowb](https://github.com/doowb)
* [twitter/doowb](https://twitter.com/doowb)
### License
Copyright © 2017, [Brian Woodward](https://github.com/doowb).
Released under the [MIT License](LICENSE).
***
_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on May 08, 2017._