bare-subprocess

bare-subprocess spawns and manages child processes from Bare. The API follows the Node.js child_process module. It's a native addon and requires Bare >=1.7.0; it's available on desktop (Windows, macOS, Linux).

npm i bare-subprocess

Usage

const { spawn } = require('bare-subprocess')

const subprocess = spawn('echo', ['hello', 'world'], { stdio: 'inherit' })

subprocess.on('exit', () => console.log('done'))

API

Spawning

const subprocess = spawn(file[, args][, options])

Spawn file as a new subprocess with the given args. Returns a Subprocess. args may be null or omitted; if omitted, the second argument is treated as options.

Options include:

options = {
  cwd: os.cwd(),
  env: process.env,
  stdio: [],
  shell: false,
  detached: false,
  uid: -1,
  gid: -1,
  windowsHide: false,
  windowsVerbatimArguments: false,
  serialization: 'json'
}

stdio may be an array of slot descriptors or a single string applied to all of stdin, stdout, and stderr. Each slot may be one of:

serialization selects how IPC messages are framed:

shell may be a string identifying the shell to use, or true to use the platform default (/bin/sh, /system/bin/sh on Android, or cmd.exe on Windows).

const result = spawnSync(file[, args][, options])

Synchronously spawn file and wait for it to exit. Returns an object:

result = {
  pid,
  status,
  signal,
  output,
  stdout,
  stderr,
  error
}

Accepts all spawn options plus:

options = {
  input: null,
  maxBuffer: 1024 * 1024
}

input is written to the child's stdin before it starts. maxBuffer is the size of the buffer allocated to capture each 'pipe' stdio slot.

Subprocess

A Subprocess exposes pid, spawnfile, spawnargs, stdio, stdin, stdout, stderr, exitCode, signalCode, killed, connected, and channel.

subprocess.kill([signum])

Send a signal to the child (default SIGTERM).

subprocess.send(message[, handle][, callback]) · subprocess.disconnect()

Send a message (and optionally a handle) over the IPC channel, or close it.

subprocess.ref() · subprocess.unref()

Keep the event loop alive for the child, or release it.

A Subprocess emits exit, close, message, disconnect, and error.

class SubprocessParentChannel

Available as require('bare-subprocess/parent'). Constructed inside the child process to access the parent end of the IPC channel. The serialization mode is selected automatically from the BARE_CHANNEL_SERIALIZATION_MODE environment variable, which is set by spawn in the parent.

const ParentChannel = require('bare-subprocess/parent')

const parent = new ParentChannel()

parent.on('message', (message, handle) => {
  parent.send({ echoed: message })
})

parent.connected

true while the channel is open.

parent.send(message[, handle][, callback]) · parent.disconnect()

Same semantics as the corresponding Subprocess method.

parent.ref() · parent.unref()

Same semantics as the corresponding Subprocess method.

A SubprocessParentChannel emits message, disconnect, and error — the same semantics as the corresponding Subprocess events.

constants

Re-exports the signal constants from bare-os (os.constants.signals). Also available as require('bare-subprocess/constants').

Related modules

Builds on bare-env, bare-events, bare-os, bare-pipe, bare-structured-clone, bare-tcp, and bare-url (see Bare modules).

See also

• Bare modules—the full bare-* catalog.
• bare-os—process IDs, signals, and environment.
• Bare runtime API—Bare.Thread for in-process concurrency instead of child processes.