bare-subprocess

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

npm i bare-subprocess

UsageCopy Anchor Link

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

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

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

APICopy Anchor Link

SubprocessCopy Anchor Link

channel: SubprocessChannelCopy Anchor Link

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

Subprocess.connected: booleanCopy Anchor Link

true while an IPC channel exists between parent and child.

Subprocess.disconnect(): voidCopy Anchor Link

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

exitCode: number | nullCopy Anchor Link

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

kill(signum?: number): booleanCopy Anchor Link

Send a signal to the child. signum may be a signal number or a name (for example 'SIGTERM'). Defaults to SIGTERM. kill() can be called more than once, and each call on a running child sends its signal. A signum of 0 does not stop the child, which keeps running, but the call still returns true and sets killed while the child is alive. Before v6.2.2, kill() returned undefined and ignored every call after the first, so a kill(0) followed by kill('SIGKILL') left the child running.

Parameters

Returns boolean — true if the signal was sent, or false if the child has already exited, in which case no signal is sent.

Throws

• UNKNOWN_SIGNAL — thrown if signum is a string that isn't a recognized signal name.
• EINVAL — signum is a number outside the range of signal numbers, such as 9999.

killed: booleanCopy Anchor Link

true once a call to subprocess.kill() has returned true, including kill(0), otherwise false. It does not mean the child has exited. A kill() call on a child that has already exited returns false and leaves killed unchanged. Before v6.2.2, every kill() call set it, even after the child had exited.

pid: numberCopy Anchor Link

The process ID of the child.

ref(): voidCopy Anchor Link

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

Subprocess.send(message: unknown, handle?: unknown, cb?: (err: Error | null) => void): booleanCopy Anchor Link

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

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 | nullCopy Anchor Link

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

spawnargs: string[]Copy Anchor Link

The arguments the child was spawned with.

spawnfile: stringCopy Anchor Link

The file that was spawned.

stderr: Pipe | nullCopy Anchor Link

Convenience accessor for subprocess.stdio[2].

stdin: Pipe | nullCopy Anchor Link

Convenience accessor for subprocess.stdio[0].

stdio: (Pipe | null)[]Copy Anchor Link

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 | nullCopy Anchor Link

Convenience accessor for subprocess.stdio[1].

unref(): voidCopy Anchor Link

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

FunctionsCopy Anchor Link

spawn(file: string, args?: string[] | null, opts?: SpawnOptions): SubprocessCopy Anchor Link

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

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.

Constants and variablesCopy Anchor Link

constants: Record<string, number>Copy Anchor Link

TypesCopy Anchor Link

SubprocessChannelCopy Anchor Link

interface SubprocessChannel {
  readonly connected: boolean
  send(message: unknown, handle?: unknown, cb?: (err: Error | null) => void): boolean
  disconnect(): void
  ref(): this
  unref(): this
}

SubprocessEventsCopy Anchor Link

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

IOCopy Anchor Link

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

SerializationModeCopy Anchor Link

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

SpawnOptionsCopy Anchor Link

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
}

SpawnSyncOptionsCopy Anchor Link

interface SpawnSyncOptions {
  input?: string | Buffer
  maxBuffer?: number
  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
}

SpawnSyncResultCopy Anchor Link

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

ClassesCopy Anchor Link

errorsCopy Anchor Link

class errors {
  code: string
}

bare-subprocess/constantsCopy Anchor Link

Constants and variablesCopy Anchor Link

signals: Record<string, number>Copy Anchor Link

bare-subprocess/errorsCopy Anchor Link

ClassesCopy Anchor Link

SubprocessErrorCopy Anchor Link

class SubprocessError {
  code: string
}

bare-subprocess/parentCopy Anchor Link

SubprocessParentChannelCopy Anchor Link

new SubprocessParentChannel()Copy Anchor Link

Throws

• 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'.

SubprocessParentChannel.connected: booleanCopy Anchor Link

true while an IPC channel exists between parent and child.

SubprocessParentChannel.disconnect(): voidCopy Anchor Link

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

ref(): thisCopy Anchor Link

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

SubprocessParentChannel.send(message: unknown, handle?: unknown, cb?: (err: Error | null) => void): booleanCopy Anchor Link

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

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(): thisCopy Anchor Link

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

TypesCopy Anchor Link

SubprocessParentChannelEventsCopy Anchor Link

interface SubprocessParentChannelEvents {
  message: [message: unknown, handle: unknown]
  disconnect: []
  error: [err: Error]
}

See alsoCopy Anchor Link

• Builds on bare-env, bare-events, bare-os, bare-pipe, bare-structured-clone, bare-tcp, and bare-url.
• It's a native addon and requires Bare >=1.7.0; it's available on desktop (Windows, macOS, Linux).
• From v6.2.0 it depends on bare-structured-clone v2, which frames serialization: 'advanced' messages. v6.2.0 has no API change.
• v6.2.1 fixes spawn() when the child fails to launch, such as a missing executable. Before it, tearing down the failed subprocess could signal the process group of the parent. There is no API change.
• v6.2.2 aligns subprocess.kill() with Node.js: it returns a boolean, sets killed only when it returns true, and can be called repeatedly. It also fixes a parent that stayed alive at teardown after kill(0), because the child was then never sent SIGTERM.
• Bare modules — the full bare-* catalog.
• Bare runtime API — the runtime these modules extend.