bellpull
API reference

bellpull

Every export of bellpull, with its signature and doc comment: ambientRuntime, DEFAULT_GRACE, DEFAULT_TIMEOUT, escapeArgument, escapeCommand, extensionCandidates and 20 more, plus 9 types.

bellpull — run another program and get back a result you can read.

import { ambientRuntime, DEFAULT_GRACE, DEFAULT_TIMEOUT, … } from 'bellpull';

Functions

ambientRuntime

The runtime of the process this is running in, or a runtime that admits it knows nothing.

function ambientRuntime(): Runtime;

Returns Runtime

escapeArgument

Escape one argument so cmd.exe and then the callee's argv parser both give it back unchanged.

function escapeArgument(argument: unknown, doubleEscape?: boolean): string;
ParameterType
argumentunknown
doubleEscape (optional)boolean

Returns string

escapeCommand

Escape a command name for cmd.exe.

function escapeCommand(command: string): string;
ParameterType
commandstring

Returns string

format

How a result reads to a person: one line, and the failure's output when there is one.

function format(result: Result): string;
ParameterType
resultResult

Returns string

isWindows

Whether this runtime plays by Windows' rules. Cygwin and msys announce themselves in OSTYPE.

function isWindows(runtime: Runtime): boolean;
ParameterType
runtimeRuntime

Returns boolean

pathDelimiter

The separator between PATH entries: ; on Windows, : everywhere else.

function pathDelimiter(runtime: Runtime): string;
ParameterType
runtimeRuntime

Returns string

pathKey

The key PATH is spelled under in this environment.

function pathKey(runtime: Runtime): string;
ParameterType
runtimeRuntime

Returns string

pathOf

The PATH value for this runtime, under whichever key it is spelled.

function pathOf(runtime: Runtime): string;
ParameterType
runtimeRuntime

Returns string

readShebang

The interpreter the file at file declares, or undefined — for a file that is not there, is not readable, is a directory, or simply has no shebang.

function readShebang(file: string): string | undefined;
ParameterType
filestring

Returns string \| undefined

run

Run a program and come back with a {@link Result}.

function run(command: string, args: readonly unknown[] | undefined, options: RunOptions): Promise<Result>;
ParameterType
commandstring
argsreadonly unknown[] | undefined
optionsRunOptions

Returns Promise<Result>

shebangCommand

The interpreter a #! line names, or undefined.

function shebangCommand(source: string): string | undefined;
ParameterType
sourcestring

Returns string \| undefined

toEvent

The agent form: {@link outcomeOf}'s one word, plus the record's own fields.

function toEvent(result: Result): RunEvent;
ParameterType
resultResult

Returns RunEvent

toJson

The --json envelope: the record, flat, with nothing computed that is not in it.

function toJson(result: Result): Record<string, unknown>;
ParameterType
resultResult

Returns Record<string, unknown>

Classes

SpawnError

Spawning failed for a reason that is not a missing executable.

class SpawnError extends Error {
    readonly command: string;
    readonly cause: unknown;
    readonly code = "ERR_SPAWN_FAILED";
    constructor(command: string, cause: unknown);
}

Constants

DEFAULT_GRACE

Milliseconds between SIGTERM and SIGKILL, for a child that declines to leave.

const DEFAULT_GRACE = 5000;

DEFAULT_TIMEOUT

Milliseconds a child may take before it is killed. Finite by default — Y10.

const DEFAULT_TIMEOUT = 30000;

name

The package's own name, kept from the reserved-name release so nothing that read it breaks.

const name: "bellpull";

Interfaces

ExitHost

A host that can register work to run when the process is shutting down.

interface ExitHost {
    /** Register; the returned function unregisters. `closeout`'s `Registry.add` fits as-is. */
    add(handler: () => unknown, spec?: unknown): () => void;
}

Result

What a run produced. One value, three renderings (see project.ts).

interface Result {
    /** The exit was 0 and the run was not killed. The only field most callers branch on. */
    ok: boolean;
    /** The exit code, or `null` when the child died of a signal — the shape Node reports. */
    code: number | null;
    /** The signal that killed it, or `null`. */
    signal: NodeJS.Signals | null;
    /** Everything the child wrote to stdout. `''` when stdio was not captured. */
    stdout: string;
    /** Everything the child wrote to stderr. */
    stderr: string;
    /**
     * Wall-clock milliseconds from spawn to close — **including Node's own scheduling**, not
     * the child's CPU time (design R11). Stated here rather than in a README because the
     * caveat is what makes the number usable: it is the right figure for "how long did the
     * user wait" and the wrong one for "how expensive is this program".
     */
    duration: number;
    /** The command as the caller wrote it. */
    command: string;
    /** The arguments as the caller wrote them. */
    args: readonly string[];
    /**
     * The file that actually ran, and the `PATH` entry it came from — the field that answers
     * "which binary was this" without a second investigation. `undefined` when resolution was
     * skipped (`shell: true`, where the shell resolves).
     */
    executable: {
        path: string;
        from: string;
    } | undefined;
    /** The deadline fired and the child was killed. `ok` is `false`. */
    timedOut: boolean;
}

RunEvent

One event on an agent stream. type is what a consumer switches on.

interface RunEvent {
    type: 'run';
    outcome: Outcome;
    command: string;
    args: readonly string[];
    code: number | null;
    signal: string | null;
    durationMs: number;
    executable: string | null;
    /** Where the executable came from, so an agent can report a `PATH` surprise itself. */
    from: string | null;
}

RunOptions

interface RunOptions extends SpawnOptions {
    /** The ambient state. Required: nothing here reads `process` (Y9). */
    runtime: Runtime;
    /** Milliseconds before the child is killed. `0` disables the deadline, deliberately. */
    timeout?: number | undefined;
    /** Milliseconds between `SIGTERM` and `SIGKILL` on a breach. */
    grace?: number | undefined;
    /**
     * Where to register the child's kill so it is not orphaned if the parent is shut down.
     */
    exitHost?: ExitHost | undefined;
    /** Passed to `child_process`. `'inherit'` is what a pass-through subcommand wants. */
    stdio?: 'pipe' | 'inherit' | 'ignore' | readonly unknown[] | undefined;
}

Runtime

The ambient state this package reads. Structural on purpose: a caller may pass Node's own process, a fake, or an object assembled from a container's environment.

interface Runtime {
    /** `process.platform`. `win32` selects `PATHEXT`, backslashes and the cmd.exe rules. */
    readonly platform: Platform;
    /** The environment. `PATH` (or whichever case Windows used) is read out of it. */
    readonly env: Readonly<Record<string, string | undefined>>;
    /** The working directory a relative command or `cwd` option is resolved against. */
    readonly cwd: string;
    /** Effective uid, where the platform has one. Absent means "do not check ownership". */
    readonly uid?: number | undefined;
    /** Effective gid, where the platform has one. */
    readonly gid?: number | undefined;
}

Types

Platform

A platform string, as process.platform spells it. Only win32 is ever special-cased.

type Platform = string;

Re-exported

Documented on the page of the entry point that declares them.

ExportKindDocumented in
extensionCandidatesfunctionbellpull/which
pathExtensionsfunctionbellpull/which
resolveExecutablefunctionbellpull/which
runPathfunctionbellpull/which
searchPathfunctionbellpull/which
whichAllSyncfunctionbellpull/which
whichOrThrowSyncfunctionbellpull/which
whichSyncfunctionbellpull/which
NotFoundErrorclassbellpull/which
Resolutioninterfacebellpull/which
SearchEntryinterfacebellpull/which
WhichOptionsinterfacebellpull/which

On this page