bare-subprocess

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

Subprocess.addListener<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this

Parameters

Subprocess.addOnceListener<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this

Parameters

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.

Subprocess.emit<E extends keyof M>(name: E, ...args: M[E]): boolean

Parameters

Subprocess.eventNames(): (keyof M)[]

exitCode: number | null

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

Subprocess.getMaxListeners(): number

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

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.

Subprocess.listenerCount<E extends keyof M>(name: E): number

Parameters

Subprocess.listeners<E extends keyof M>(name: E): EventHandler<M[E]>[]

Parameters

Subprocess.off<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this

Parameters

Subprocess.on<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this

Parameters

Subprocess.once<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this

Parameters

pid: number

The process ID of the child.

Subprocess.prependListener<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this

Parameters

Subprocess.prependOnceListener<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this

Parameters

Subprocess.rawListeners<E extends keyof M>(name: E): EventHandler<M[E]>[]

Parameters

ref(): void

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

Subprocess.removeAllListeners<E extends keyof M>(name?: E): this

Parameters

Subprocess.removeListener<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this

Parameters

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

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.

Subprocess.setMaxListeners(n: number): this

Parameters

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

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 variables

constants: Record<string, number>

Types

SubprocessChannel

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

SubprocessEvents

interface SubprocessEvents {
  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 {
  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
}

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
}

bare-subprocess/constants

Constants and variables

signals: Record<string, number>

bare-subprocess/errors

Classes

SubprocessError

class SubprocessError {
  code: string
}

bare-subprocess/parent

SubprocessParentChannel

new SubprocessParentChannel()

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

parent.SubprocessParentChannel.addListener<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this

Parameters

parent.SubprocessParentChannel.addOnceListener<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this

Parameters

parent.SubprocessParentChannel.connected: boolean

true while an IPC channel exists between parent and child.

parent.SubprocessParentChannel.disconnect(): void

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

parent.SubprocessParentChannel.emit<E extends keyof M>(name: E, ...args: M[E]): boolean

Parameters

parent.SubprocessParentChannel.eventNames(): (keyof M)[]

parent.SubprocessParentChannel.getMaxListeners(): number

parent.SubprocessParentChannel.listenerCount<E extends keyof M>(name: E): number

Parameters

parent.SubprocessParentChannel.listeners<E extends keyof M>(name: E): EventHandler<M[E]>[]

Parameters

parent.SubprocessParentChannel.off<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this

Parameters

parent.SubprocessParentChannel.on<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this

Parameters

parent.SubprocessParentChannel.once<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this

Parameters

parent.SubprocessParentChannel.prependListener<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this

Parameters

parent.SubprocessParentChannel.prependOnceListener<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this

Parameters

parent.SubprocessParentChannel.rawListeners<E extends keyof M>(name: E): EventHandler<M[E]>[]

Parameters

ref(): this

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

parent.SubprocessParentChannel.removeAllListeners<E extends keyof M>(name?: E): this

Parameters

parent.SubprocessParentChannel.removeListener<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this

Parameters

parent.SubprocessParentChannel.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

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.

parent.SubprocessParentChannel.setMaxListeners(n: number): this

Parameters

unref(): this

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

Types

SubprocessParentChannelEvents

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

See also

• 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.
• Bare modules — the full bare-* catalog.
• Bare runtime API — the runtime these modules extend.