bare-sidecar
Start and manage Bare sidecar processes from Node.js and Electron
v0.5.16bare-sidecar — Start and manage Bare sidecar processes from Node.js and Electron.
npm i bare-sidecarUsage
In the host process:
const Sidecar = require('bare-sidecar')
const sidecar = new Sidecar(require.resolve('./entry'))
sidecar
.on('exit', (code, status) => {
// The sidecar process exited
})
.on('data', (data) => {
// Received data from the sidecar over IPC
})
.write('Hello sidecar')In the sidecar entry (entry.js), the IPC channel is available as a stream on Bare.IPC:
Bare.IPC.on('data', (data) => Bare.IPC.write(data))Standard streams
By default, the standard input, output, and error of the sidecar process are pipes, exposed on the Sidecar as stdin, stdout, and stderr. Piped output must be read, or the sidecar blocks once the pipe buffer fills. The stdio option, added in v0.5.8, lets the sidecar share the streams of the host instead, or discard them:
// Share the standard input, output, and error of the host
const verbose = new Sidecar(require.resolve('./entry'), { stdio: 'inherit' })
// Discard the standard input, output, and error
const quiet = new Sidecar(require.resolve('./entry'), { stdio: 'ignore' })
// Set up each stream on its own, as [stdin, stdout, stderr]
const mixed = new Sidecar(require.resolve('./entry'), { stdio: ['ignore', 'pipe', 'inherit'] })A stream that is not piped is null on the Sidecar. The IPC channel is not affected by stdio.
API
Sidecar
new Sidecar(entry: string | URL, args?: string[], opts?: SidecarOptions)
Spawn a bundled Bare runtime running entry and return a Sidecar. entry is the path to the module to run, typically resolved with require.resolve(). args is an array of additional command line arguments passed to the process. opts controls how the process is spawned, see SidecarOptions.
Overloads:
new Sidecar(entry: string | URL, args?: string[], opts?: SidecarOptions)
new Sidecar(entry: string | URL, opts?: SidecarOptions)Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
entry | string | URL | — | Path to the module the sidecar process runs, typically resolved with require.resolve(). |
args? | string[] | — | Additional command-line arguments passed to the process (default []). |
opts? | SidecarOptions | — | Spawn options: detached, and, added in v0.5.8, stdio. |
stderr: Pipe | null
The readable standard error stream of the underlying process. It is null when stdio sets the stream to 'inherit' or 'ignore'.
stdin: Pipe | null
The writable standard input stream of the underlying process. It is null when stdio sets the stream to 'inherit' or 'ignore'.
stdout: Pipe | null
The readable standard output stream of the underlying process. It is null when stdio sets the stream to 'inherit' or 'ignore'.
Types
SidecarEvents
interface SidecarEvents {
exit: [code: number | null, signalCode: string | null]
data: [data: unknown]
end: []
readable: []
piping: [dest: Writable]
close: []
error: [err: Error]
drain: []
finish: []
pipe: [src: Readable]
}SidecarOptions
interface SidecarOptions {
detached?: boolean
stdio?: SidecarStdio | [stdin?: SidecarStdio, stdout?: SidecarStdio, stderr?: SidecarStdio]
}Options for new Sidecar().
detached: Let the sidecar process lead its own process group. Added in v0.5.6.stdio: How to set up the standard input, output, and error of the sidecar process, either for all three with oneSidecarStdiovalue or per stream with an array of[stdin, stdout, stderr]. Defaults to'pipe', and so does any array entry that is left out. Added in v0.5.8.
Sidecar.SidecarStdio
type SidecarStdio = 'pipe' | 'inherit' | 'ignore'How one standard stream of the sidecar process is set up. 'pipe' exposes the stream on the Sidecar, and a piped output stream must be read, or the sidecar blocks once the pipe buffer fills. 'inherit' connects the stream to the matching stream of the host. 'ignore' discards it. Added in v0.5.8.
Sidecar
kill(signal?: string | number): boolean
Send signal to the underlying process, such as 'SIGKILL' to force down a sidecar that destroy() is still waiting on. The sidecar closes once the process has exited.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
signal? | string | number | — | The signal to send, by name or number (default 'SIGTERM'). |
Returns boolean — Whether the signal was sent.
Sidecar.versions: SidecarVersions
The versions of the components bundled with the sidecar, such as the Bare runtime.
Types
SidecarVersions
interface SidecarVersions {
readonly bare: string
}See also
- Builds on
bare-fs,bare-module,bare-path,bare-pipe,bare-stream,bare-subprocess, andbare-url. - The instance extends a duplex stream: writing to it sends data to the sidecar over its IPC channel, data received from the sidecar is emitted as
'data'events, and destroying the stream kills the sidecar process. - The
'close'event is emitted after the sidecar process has exited and its underlying stream has been destroyed. - The sidecar runs the Bare runtime that ships inside the package, which
Sidecar.versions.barereports: v1.37.1 as of v0.5.16, and v1.36.2 in v0.5.15. bare-subprocess— the lower-level process API.- One core, many platforms — running a Bare core beside a host.
- Bare modules — the full
bare-*catalog. - Bare runtime API — the runtime these modules extend.
Last updated on