bare-subprocess

stable

bare-subprocess — Native process spawning for JavaScript. It is a native addon and requires Bare >=1.7.0.

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

Subprocess

`channel: SubprocessChannel`

The SubprocessChannel instance backing the IPC channel, or undefined when no channel exists. For serialization: 'binary', this is always undefined.

`Subprocess.connected: boolean`

true while an IPC channel exists between parent and child.

`Subprocess.disconnect(): void`

Close the IPC channel. A 'disconnect' event is emitted once the channel is fully closed.

`exitCode: number | null`

The exit code of the child, or null if the child has not exited or was terminated by a signal.

`kill(signum?: number): void`

Send a signal to the child. signum may be a signal number or a name (for example 'SIGTERM'). Defaults to SIGTERM.

Parameters

Parameter	Type	Default	Description
`signum?`	`number`	—	Signal to send, as a signal number or name (for example `'SIGTERM'`); defaults to `SIGTERM`.

Throws

UNKNOWN_SIGNAL — thrown if signum is a string that isn't a recognized signal name.

`killed: boolean`

true if subprocess.kill() has been called, otherwise false.

`ref(): void`

Reference the subprocess and its stdio pipes against the event loop.

`Subprocess.send(message: unknown, handle?: unknown, cb?: (err: Error | null) => void): boolean`

Send message to the child over the IPC channel. handle may be a bare-pipe Pipe or a bare-tcp Socket to transfer ownership of along with the message. callback is invoked with (err) after the message has been written.

Overloads:

send(message: unknown, handle?: unknown, cb?: (err: Error | null) => void): boolean
send(message: unknown, cb: (err: Error | null) => void): boolean

Parameters

Parameter	Type	Default	Description
`message`	`unknown`	—	The value to send to the child over the IPC channel.
`handle?`	`unknown`	—	A `bare-pipe` `Pipe` or `bare-tcp` `Socket` to transfer to the child along with `message`.
`cb?`	`(err: Error \| null) => void`	—	Called with `(err)` once `message` has been written, or with an error if there is no connected IPC channel.

Returns boolean — false if the subprocess has no IPC channel or it has disconnected (cb, if given, is then invoked asynchronously with an error); otherwise the underlying pipe write result.

`signalCode: string | null`

The name of the signal the child was terminated with, or null.

`spawnargs: string[]`

The arguments the child was spawned with.

`spawnfile: string`

The file that was spawned.

`stderr: Pipe | null`

Convenience accessor for subprocess.stdio[2].

`stdin: Pipe | null`

Convenience accessor for subprocess.stdio[0].

`stdio: (Pipe | null)[]`

An array of bare-pipe instances corresponding to the configured stdio slots. Slots configured as 'inherit', 'ignore', or backed by an inherited fd are null.

`stdout: Pipe | null`

Convenience accessor for subprocess.stdio[1].

`unref(): void`

Unreference the subprocess and its stdio pipes against the event loop.

Functions

`spawn(file: string, args?: string[] | null, opts?: SpawnOptions): Subprocess`

Spawn file as a new subprocess with the given args. Returns a Subprocess instance. args may be null or omitted to spawn with no arguments. If args is omitted, the second argument is treated as options.

Overloads:

spawn(file: string, args?: string[] | null, opts?: SpawnOptions): Subprocess
spawn(file: string, opts?: SpawnOptions): Subprocess

Synchronous form: spawnSync(file: string, args?: string[] | null, opts?: SpawnSyncOptions): SpawnSyncResult

Parameters

Parameter	Type	Default	Description
`file`	`string`	—	The executable to spawn; a string path or a `file://` URL.
`args?`	`string[]` \| `null`	—	Arguments to pass to `file`; may be `null` or omitted to spawn with none. If omitted, the second argument is treated as `opts`.
`opts?`	`SpawnOptions`	—	Options controlling the environment, stdio, and behavior of the new subprocess; see `SpawnOptions`.

Throws

UNKNOWN_SERIALIZATION_MODE — thrown if opts.serialization is not 'json', 'advanced', or 'binary'.
IPC_CHANNEL_ALREADY_DEFINED — thrown if opts.stdio requests more than one 'ipc' slot.

Types

`SubprocessChannel`

interface SubprocessChannel {
  readonly connected: boolean

  send(message: unknown, handle?: unknown, cb?: (err: Error | null) => void): boolean
  send(message: unknown, cb: (err: Error | null) => void): boolean

  disconnect(): void

  ref(): this
  unref(): this
}

`SubprocessEvents`

interface SubprocessEvents extends EventMap {
  exit: [code: number | null, signalCode: string | null]
  message: [message: unknown, handle: unknown]
  disconnect: []
  error: [err: Error]
}

`IO`

type IO = 'inherit' | 'pipe' | 'overlapped' | 'ignore' | 'ipc'

`SerializationMode`

type SerializationMode = 'json' | 'advanced' | 'binary'

`SpawnOptions`

interface SpawnOptions {
  cwd?: string
  stdio?: [stdin?: IO, stdout?: IO, stderr?: IO, ...fds: IO[]] | IO | null
  shell?: boolean | string
  detached?: boolean
  uid?: number
  gid?: number
  env?: Record<string, string>
  windowsHide?: boolean
  windowsVerbatimArguments?: boolean
  serialization?: SerializationMode
}

`SpawnSyncOptions`

interface SpawnSyncOptions extends SpawnOptions {
  input?: string | Buffer
  maxBuffer?: number
}

`SpawnSyncResult`

interface SpawnSyncResult {
  output: (Buffer | null)[] | null
  pid: number
  signal: number
  status: number
  stdout: Buffer | null
  stderr: Buffer | null
  error?: Error
}

Classes

`errors`

class errors {
  code: string
}

class SubprocessError {
  code: string
}

NO_IPC_CHANNEL — thrown if the BARE_CHANNEL_FD environment variable is not set.
UNKNOWN_SERIALIZATION_MODE — thrown if BARE_CHANNEL_SERIALIZATION_MODE is set to something other than 'json' or 'advanced'.

send(message: unknown, handle?: unknown, cb?: (err: Error | null) => void): boolean
send(message: unknown, cb: (err: Error | null) => void): boolean

Parameters

Parameter	Type	Default	Description
`message`	`unknown`	—	The value to send to the parent process over the IPC channel.
`handle?`	`unknown`	—	A `bare-pipe` `Pipe` or `bare-tcp` `Socket` to transfer to the parent along with `message`.
`cb?`	`(err: Error \| null) => void`	—	Called with `(err)` once `message` has been written, or with an error if the channel is disconnected.

Returns boolean — false if the channel is disconnected (cb, if given, is then invoked asynchronously with a CHANNEL_DISCONNECTED error); otherwise the underlying pipe write result.

`unref(): this`

Unreference the subprocess and its stdio pipes against the event loop.

bare-subprocess

On this page