# single-child

> Spawn a single child process which kills itself on restart

Latest version **0.3.4** (published 2013-07-29) · 0 weekly downloads

## Install

```sh
npm install single-child
pnpm add single-child
yarn add single-child
bun add single-child
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.3.4 |
| Published | 2013-07-29 |
| First published | 2013-06-27 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 0.6.0 |
| Dependencies | 1 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Author | Todd Wolfson |
| Maintainers | twolfson |
| Keywords | single, singleton, spawn, child, child process |

## Links

- npm: https://www.npmjs.com/package/single-child
- Repository: https://github.com/twolfson/single-child
- Issues: https://github.com/twolfson/single-child/issues
- npm.io page: https://npm.io/package/single-child

## Dependencies (1)

- [nimble](https://npm.io/package/nimble.md) 0.0.2

## Recent versions

- 0.3.4 (latest) — 2013-07-29
- 0.3.3 — 2013-07-24
- 0.3.2 — 2013-07-24
- 0.3.1 — 2013-07-23
- 0.3.0 — 2013-07-23
- 0.2.0 — 2013-06-28
- 0.1.2 — 2013-06-27
- 0.1.1 — 2013-06-27
- 0.1.0 — 2013-06-27

## README

# single-child [![Build status](https://travis-ci.org/twolfson/single-child.png?branch=master)](https://travis-ci.org/twolfson/single-child)

Spawn a single child process which kills itself on restart.

This was built as a module of [listen-spawn][listen-spawn], a CLI tool that starts a server and runs a command every time it is pinged; a [nodemon][nodemon] over HTTP.

Supported and tested on Linux and Windows.

Donations accepted: [![Gittip](http://badgr.co/gittip/twolfson.png)](https://www.gittip.com/twolfson/)

[listen-spawn]: https://github.com/twolfson/listen-spawn
[nodemon]: https://github.com/remy/nodemon

## Getting Started
Install the module with: `npm install single-child`

Below is a simplified implementation of [listen-spawn][listen-spawn]:

```javascript
// Inside of app-restarter.js
// Create a new child which starts my app
var SingleChild = require('single-child'),
    child = new SingleChild('npm', ['start'], {stdio: [0,1,2]});

// Start my child (and hence my app)
child.start();

// Begin a server which restarts the app when hit
var http = require('http');
http.createServer(function (req, res) {
  // We received a ping, restart the child
  child.restart();

  // Send a NO CONTENT response
  res.writeHead(204);
  res.end();
}).listen(3000);

// Notify the user the server is up
console.log('App Restarter is listening at http://localhost:3000/');
```

```sh
$ # Inside of a shell
$ # Start and fork our App Restarter
$ node app-restarter.js &
App restarter is listening at http://localhost:3000/

> my-app@0.1.0 start /home/todd/github/my-app
> echo 'Running app...'

Running app...

$ # Ping the App Restarter (which restarts the app)
$ curl http://localhost:3000/

> my-app@0.1.0 start /home/todd/github/my-app
> echo 'Running app...'

Running app...
```

## Documentation
`SingleChild` acts as a constructor and accepts the same parameters as [child_process#spawn][spawn] with a few extras.

[spawn]: http://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options

```js
new SingleChild(cmd, [args], [options]);
/**
 * Spawn for a single child. Always guarantees only one child exists
 * @see child_process.spawn
 * @param {String} cmd Command to run
 * @param {String[]} [args] Array of arguments to pass with cmd
 * @param {Object} [options] Options to pass to `spawn` and for ourselves
 * @param {Mixed} [options.killSignal] Signal to pass to `kill` executions
 */
```

### Methods
`SingleChild#start` and `SingleChild#restart` are how we start children. These are aliases.

```js
child.start([cb]);
child.restart([cb]);
/**
 * Stop the currently running child and start a new one
 * @param {Function} [cb] Error-first callback that returns *before* the child starts
 * @callback {Error|Null} err Error if there was one
 * @callback {ChildProcess} child Child that was started. Generated by node's child_process#spawn
 */
```

`SingleChild#stop` and `SingleChild#kill` are how we stop children. `stop` invokes `kill` with `SIGINT` rather than allowing for input.

```js
child.stop([cb]);
child.kill([options], [cb]);
/**
 * Stop the currently running program
 * @param {Object} [options] Options for the kill action
 * @param {Mixed} [options.signal] Signal to use when killing
 * @param {Function} [cb] Callback to run when process has been killed.
 *     Receives same params as node's ChildProcess#exit event
 */
```

### Events
`SingleChild` fires the following events over its lifecycle:

- `starting()` is run before a child is spawned
- `started(child)` is run after a child is spawned (does not mean process is running)
- `exited(code, signal)` is run when a child exits
- `killing(child)` is run before a child is killed
- `killed(code, signal)` is run after a child is killed

## Examples
Below is the same example as before but utilizing events for better notifications.

```js
// Create a new child which starts my app
var SingleChild = require('single-child'),
    child = new SingleChild('npm', ['start'], {stdio: [0,1,2]});

// Start my child (and hence my app)
child.start();

// Notify user on start and exit events
child.on('starting', function () {
  console.log('Starting app!');
});
child.on('exited', function () {
  console.log('App exited!');
});

// Begin a server which restarts the app when hit
var http = require('http');
http.createServer(function (req, res) {
  // We received a ping, restart the server
  child.restart();

  // Send a NO CONTENT response
  res.writeHead(204);
  res.end();
}).listen(3000);

// Notify the user the server is up
console.log('App restarter is listening at http://localhost:3000/');
```

```sh
$ # Start and fork our App Restarter
$ node app-restarter.js &
App restarter is listening at http://localhost:3000/
Starting app!

> my-app@0.1.0 start /home/todd/github/my-app
> echo 'Running app...'

Running app...
App exited!

$ # Ping the App Restarter (which restarts the app)
$ curl http://localhost:3000/
Starting app!

> my-app@0.1.0 start /home/todd/github/my-app
> echo 'Running app...'

Running app...
App exited!
```
## Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint via [grunt](https://github.com/gruntjs/grunt) and test via `npm test`.

## License
Copyright (c) 2013 Todd Wolfson

Licensed under the MIT license.

---
_Source: https://npm.io/package/single-child · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._