little-process-box

A little toolkit for running and managing child processes

Installation

$ npm install little-process-box

Status

Development/Testing/Documentation

Usage

const { Supervisor } = require('little-process-box')

const supervisor = new Supervisor()
const pool = supervisor.pool()

supervisor.service('http-server', {
  pool,
  exec: 'node',
  args: ['server.js'],
  env: { PORT: 3000 }
})

supervisor.service('discovery', {
  pool,
  exec: 'node',
  args: ['discovery.js'],
  env: { PORT: 9000 },
})

supervisor.start((err) => {
  // http + discovery should both started
  supervisor.stat({name: 'http-server'}, (err, stats) => {
    console.log(stats)
  })

  supervisor.stat({name: 'discovery'}, (err, stats) => {
    console.log(stats)
  })

  supervisor.stop() // stops all services
})

API

const pool = new ProcessPool([Factory])

The ProcessPool class represents a container of running processes managed by the instance. This class extends the Pool class from the nanoresource-pool module. You can override the default factory by supplying your own Factory that should implement the nanoresource

pool.spawn(command[, args[, opts]])

Creates and spawns a command in a new process managed by the pool.

pool.stat([where], callback)

Collects the stats of all running process calling callback(err, stats) upon success or error. The where object can be used to filter the results that get queried for stats.

pool.launch(pathspec[, opts])

Launches a program by way of an input pathspec that may be an application URL, path to an application directory, or something suitable for the operating system to launch ("open").

const supervisor = new Supervisor()

The Supervisor class represents a higher level container for ProcessPool instances in which it provides abilities to manage processes as services with consolidated logging, mutex locks, graceful shutdowns, and connected message channels.

supervisor.pools

A list of all pools.

supervisor.pool(opts)

Creates a new SupervisorProcessPool instance.

supervisor.service(name, opts)

Creates a named service with options from a new or given pool (opts.pool).

supervisor.stat([where], callback)

Queries all services in all process pools based on an optional where filter calling callback(err, results) upon success or error.

supervisor.start([callback])

Starts all services in all pools calling callback(err) upon success or error.

supervisor.stop([callback])

Stops all services in all pools calling callback(err) upon success or error.

supervisor.restart([callback])

Restarts all services in all pools calling callback(err) upon success or error.

const pool = new SupervisorProcessPool([opts])

The SupervisorProcessPool class represents an extended ProcessPool that creates Service instances as the process resource.

const service = new Service(options)

The Service class represents a named process that can be started, restarted, and stopped. The Service class inherits all properties from the Process class.

service.env

Environment object for the service.

service.pool

The pool that created this service.

service.type

The service type. This can be anything.

service.name

The service name. This can be anything.

service.exec

The command used to execute the service.

service.args

The command arguments used to execute the service.

service.description

A description of the service.

service.stdin

A Writable stream for the service's stdin.

service.stdout

A Readable stream for the service's stdout.

service.stderr

A Readable stream for the service's stderr.

service.started

true if the service has successfully started.

service.starting

true if the service is in the middle of starting.

service.stopped

true if the service is stopped.

service.start([callback])

Starts the services calling callback(err) upon success or error.

service.stop([callback])

Stops the services calling callback(err) upon success or error. This function will reset the nanoresource state (opened, opening, closed, closing, actives) to their initial values.

service.restart([callback])

Restarts the services calling callback(err) upon success or error. This function will call service.stop(callback)

service.stat([callback])

Same as [Process#stat()][nanoprocess#stat].

service.createLogStream()

Returns a readable stream to the caller that pipes stderr from the running service to the stream. If the service does not have a readable stderr stream, then the returned stream will automatically end.

const childProcess = new Process(command[, args[, opts]])

The Process class exported from nanoprocess.

const channel = new Channel(process)

The Channel class represents a channel for a running process that leverages IPC channels falling back to stdin and stdout streams to send and receive messages on where process can be a Process instance, a ChildProcess instance, or the global process object.

channel.send(buffer[, opts])

Sends a buffer to the process through the message channel where opts can be:

{
  id: 0, // The channel ID to send this on
  type: 0, // The message type
}

channel.close(callback)

Closes channel calling callback(err) upon success or error.

channel.destroy([err])

Close process message channel and cleans up all resources.

channel.on('message', message, id, type)

Emitted when a message a sent over the process channel where message is a Buffer of the message sent, id is the channel identifier and type is the message type.

channel.on('error', err)

Emitted when an error occurs on the channel process during the life time of the Channel instance.

channel.on('close')

Emitted when the channel closes.

License

MIT

See Also

• open
• nanoprocess
• nanoresource
• nanoresource-pool