# background-process [![NPM version](https://img.shields.io/npm/v/background-process.svg?style=flat)](https://www.npmjs.com/package/background-process) [![NPM monthly downloads](https://img.shields.io/npm/dm/background-process.svg?style=flat)](https://npmjs.org/package/background-process)  [![NPM total downloads](https://img.shields.io/npm/dt/background-process.svg?style=flat)](https://npmjs.org/package/background-process) [![Linux Build Status](https://img.shields.io/travis/doowb/background-process.svg?style=flat&label=Travis)](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._