IF Commons GitHub

proc

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-system FR-009

The process and the programs it runs (commons 0001-system FR-009 to FR-011), on node:process, node:child_process and node:os, the same on Bun and on Node 26. The names are short and plain (env.get, args, exit, cwd, build.os, build.target, ppid, output, spawn, unrefTimer); selfCommand gives the argument vector for a program that runs itself again, from a script or from a compiled binary. A program is always run by its argument vector, never through a shell; one that cannot be found throws NotFound, and a non-zero exit is an outcome, not an error. Taken from erga's lib/ts/process, Stolos's src/archon/core/exec.ts and the setup's proc.ts.

import { run } from "./proc.ts";
const r = await run(["git", "--version"]);
if (r.success) console.log(r.stdout.trim());

Source: commons/system/src/proc.ts

6 of 103 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

procnamespace
namespace proc
proc.ProcessTracertypeno test imports it
type ProcessTracer = <T extends { readonly code: number }>(
  argv: readonly string[],
  run: (env: Readonly<Record<string, string>>) => Promise<T>,
) => Promise<T>;

What runs a program inside a trace: it is given the program's argument vector and a function that runs it with the environment to add (TRACEPARENT and TRACESTATE), and gives that function's outcome. The telemetry of commons installs one when its module is loaded (commons 0032-libraries-by-concern: this library does not import the telemetry); with none installed a program is run with nothing added.

proc.setProcessTracerfunctionno test imports it
function setProcessTracer(t: ProcessTracer | undefined): void

Installs the function that traces the programs this module runs (or, with undefined, removes it): a program is a process span where one is installed (0006-signals FR-018).

proc.envconstno test imports it
const env: { readonly get: (key: string) => string | undefined; readonly set: (key: string, value: string) => void; readonly delete: (key: string) => void; readonly has: (key: string) => boolean; readonly toObject: () => Record<string, string>; }

The process's environment.

proc.argsconstno test imports it
const args: readonly string[]

The arguments the program was given, after the runtime's own and the script's path.

proc.exitfunctionno test imports it
function exit(code?: number): never

The process ends now with code (0 by default).

proc.cwdfunctionno test imports it
function cwd(): string

The process's working folder.

proc.chdirfunctionno test imports it
function chdir(path: string): void

The process's working folder changed.

proc.pidconstno test imports it
const pid: number

The process's id.

proc.ppidfunctionno test imports it
function ppid(): number

The id of the process's parent (FR-053); a function, as the parent changes where the first one ends.

proc.execPathfunctionno test imports it
function execPath(): string

The path of the runtime's executable (bun or node).

proc.hostnamefunctionno test imports it
function hostname(): string

The computer's name.

proc.homeDirfunctionno test imports it
function homeDir(): string

The account's home folder.

proc.uidfunctionno test imports it
function uid(): number | undefined

The account's user id, or undefined on Windows.

proc.isRootfunctionno test imports it
function isRoot(): boolean

Whether the process runs as root (never on Windows).

proc.Ostypeno test imports it
type Os = "linux" | "darwin" | "windows" | "freebsd" | "netbsd" | "openbsd" | "solaris" | "aix" | "android" | "other";

An operating system, by the names build.os gives.

proc.Archtypeno test imports it
type Arch = "x86_64" | "aarch64" | "arm" | "riscv64" | "s390x" | "ppc64" | "other";

A processor, by the names build.arch gives.

proc.osOffunctionno test imports it
function osOf(platform: string): Os

The operating system's name for node:process's platform.

proc.archOffunctionno test imports it
function archOf(arch: string): Arch

The processor's name for node:process's arch.

proc.tripleOffunctionno test imports it
function tripleOf(os: Os, arch: Arch): string

The target triple (as Rust and Bun name it) for an operating system and a processor (FR-053): x86_64-unknown-linux-gnu, aarch64-apple-darwin, x86_64-pc-windows-msvc, aarch64-linux-android, and <arch>-unknown-<os> for the rest.

proc.buildconstno test imports it
const build: { readonly os: Os; readonly arch: Arch; readonly target: string; }

The platform this process runs on, with the target triple (FR-053).

proc.RuntimeNametypeno test imports it
type RuntimeName = "bun" | "node";

Which runtime runs this code.

proc.runtimeNamefunctionno test imports it
function runtimeName(): RuntimeName

Which runtime runs this code, from process.versions, which each of them fills: Bun, the default, or Node 26, the backup.

proc.runtimeVersionfunctionno test imports it
function runtimeVersion(): string

The version of the runtime that runs this code.

proc.isExecutablefunctionno test imports it
function isExecutable(path: string): boolean

Whether a path is a file this account may run (on Windows, any file).

proc.whichfunctionno test imports it
function which(name: string, path?: string): string | undefined

The program name on PATH (or the path itself where name has a separator), as command -v finds it; undefined where there is none.

proc.Stdiotypeno test imports it
type Stdio = "piped" | "inherit" | "null";

Where a stream of a program goes: kept (piped), shared with this process (inherit) or thrown away (null).

proc.RunOptionstypeno test imports it
type RunOptions = { /** Its working folder. */ readonly cwd?: string; /** Variables added to its environment (or i… (1223 characters)
type RunOptions = {
  /** Its working folder. */
  readonly cwd?: string;
  /** Variables added to its environment (or its whole environment, with `clearEnv`). */
  readonly env?: Readonly<Record<string, string>>;
  /** Start it with no variable but those of `env`. */
  readonly clearEnv?: boolean;
  /** Text or bytes it reads as its standard input; without it, `stdin` says what it gets. */
  readonly input?: string | Uint8Array;
  /** Its standard input where there is no `input`: this process's own (`inherit`), or none (`null`, the default). */
  readonly stdin?: "inherit" | "null";
  /** Its standard output: kept (the default), shared, or thrown away. */
  readonly stdout?: Stdio;
  /** Its standard error: kept (the default), shared, or thrown away. */
  readonly stderr?: Stdio;
  /** Each line it writes, as it writes it, without its line ending; the output is kept as well. */
  readonly onLine?: (stream: "stdout" | "stderr", line: string) => void;
  /** Stopping it: SIGTERM when the signal aborts, then SIGKILL after `killAfterMs`. */
  readonly signal?: AbortSignal;
  /** How long a program stopped by `signal` has between SIGTERM and SIGKILL (5000 ms by default). */
  readonly killAfterMs?: number;
};

How to run a program.

proc.Statustypeno test imports it
type Status = {
  /** Its exit status; 128 plus the signal's number where a signal ended it, as a shell reports it. */
  readonly code: number;
  /** Whether its exit status was 0. */
  readonly success: boolean;
  /** The signal that ended it (`SIGTERM`), or null. */
  readonly signal: string | null;
};

How a program ended.

proc.Outputtypeno test imports it
type Output = { /** Its exit status; 128 plus the signal's number where a signal ended it, as a shell reports it. */ … (490 characters)
type Output = {
  /** Its exit status; 128 plus the signal's number where a signal ended it, as a shell reports it. */
  readonly code: number;
  /** Whether its exit status was 0. */
  readonly success: boolean;
  /** The signal that ended it (`SIGTERM`), or null. */
  readonly signal: string | null;
  /** What it wrote to standard output, where it was kept. */
  readonly stdout: Uint8Array;
  /** What it wrote to standard error, where it was kept. */
  readonly stderr: Uint8Array;
};

What a program did, with its output as bytes.

proc.TextOutputtypeno test imports it
type TextOutput = Omit<Output, "stdout" | "stderr"> & { readonly stdout: string; readonly stderr: string };

What a program did, with its output as text.

proc.signalNumberfunctionno test imports it
function signalNumber(name: string): number

The number of a signal by its name (1 for one it does not know).

proc.outputfunctionno test imports it
function output(argv: readonly string[], options?: RunOptions): Promise<Output>

A program run to its end, by its argument vector and never through a shell, with what it did. NotFound where there is no such program. Where a telemetry pipeline is installed, the run is a process span and the program is given its TRACEPARENT (0006-signals FR-018).

proc.runfunctionno test imports it
function run(argv: readonly string[], options?: RunOptions): Promise<TextOutput>

A program run to its end, with its output as text (UTF-8). NotFound where there is no such program.

proc.mustfunctionno test imports it
function must(argv: readonly string[], options?: RunOptions): Promise<string>

A program's standard output, where it succeeds; an Error naming the program, its status and what it said, where it does not.

proc.firstLinefunctionno test imports it
function firstLine(argv: readonly string[], options?: RunOptions): Promise<string>

The first line a program prints, trimmed; "" where it fails or cannot be found.

proc.KillSignaltypeno test imports it
type KillSignal = Signal | "SIGKILL" | "SIGABRT" | "SIGALRM" | "SIGSTOP" | "SIGCONT" | "SIGPIPE";

A signal a program can be sent.

proc.SpawnOptionstypeno test imports it
type SpawnOptions = { /** Its working folder. */ readonly cwd?: string; /** Variables added to its environment (or… (988 characters)
type SpawnOptions = {
  /** Its working folder. */
  readonly cwd?: string;
  /** Variables added to its environment (or its whole environment, with `clearEnv`). */
  readonly env?: Readonly<Record<string, string>>;
  /** Start it with no variable but those of `env`. */
  readonly clearEnv?: boolean;
  /** Its standard input: a `WritableStream` (`piped`), this process's own (the default), or none. */
  readonly stdin?: Stdio;
  /** Its standard output: a `ReadableStream` (`piped`), this process's own (the default), or thrown away. */
  readonly stdout?: Stdio;
  /** Its standard error: a `ReadableStream` (`piped`), this process's own (the default), or thrown away. */
  readonly stderr?: Stdio;
  /** Stopping it: SIGTERM when the signal aborts, then SIGKILL after `killAfterMs`. */
  readonly signal?: AbortSignal;
  /** How long a program being stopped has between SIGTERM and SIGKILL (5000 ms by default), by `signal` or by `await using`. */
  readonly killAfterMs?: number;
};

How to start a program that runs beside this one; each stream is this process's own (inherit) unless asked.

proc.Childtypeno test imports it
type Child = AsyncDisposable & { /** Its process id. */ readonly pid: number; /** Its standard input, where it is … (998 characters)
type Child = AsyncDisposable & {
  /** Its process id. */
  readonly pid: number;
  /** Its standard input, where it is piped; closing the stream closes its input. */
  readonly stdin: WritableStream<Uint8Array> | null;
  /** Its standard output, where it is piped. */
  readonly stdout: ReadableStream<Uint8Array> | null;
  /** Its standard error, where it is piped. */
  readonly stderr: ReadableStream<Uint8Array> | null;
  /** How it ended, once it ends; rejected with the runtime's error where it could not be started. */
  readonly status: Promise<Status>;
  /** Sends it a signal (SIGTERM by default); nothing where it has already ended. */
  kill(signal?: KillSignal): void;
  /** Its whole output and error, read from the piped streams (empty where not piped), and its status, once it ends. */
  output(): Promise<Output>;
  /** It keeps this process alive until it ends (the default). */
  ref(): void;
  /** It no longer keeps this process alive; nor do its pipes. */
  unref(): void;
};

A program while it runs await using stops it (SIGTERM, then SIGKILL) where it still runs, and waits for it.

proc.spawnfunctionno test imports it
function spawn(argv: readonly string[], options?: SpawnOptions): Child

Starts a program by its argument vector, never through a shell, and gives its handle while it runs (FR-052). A program that cannot be found throws NotFound at once: a path that is not an executable file, or a name not on the PATH of the environment it is given. Where a telemetry pipeline is installed, the run is a process span that ends when the program does, and the program is given its TRACEPARENT (0006-signals FR-018), as for output.

import { spawn } from "./proc.ts";
await using child = spawn(["gzip", "-dc"], { stdin: "piped", stdout: "piped" });
proc.Signaltypeno test imports it
type Signal = "SIGINT" | "SIGTERM" | "SIGHUP" | "SIGQUIT" | "SIGUSR1" | "SIGUSR2" | "SIGWINCH" | "SIGBREAK";

A signal this process can listen for.

proc.addSignalListenerfunctionno test imports it
function addSignalListener(signal: Signal, handler: () => void): void

A function called when the process receives the signal.

proc.removeSignalListenerfunctionno test imports it
function removeSignalListener(signal: Signal, handler: () => void): void

A function no longer called for the signal.

proc.sleepfunctionno test imports it
function sleep(ms: number, signal?: AbortSignal | undefined): Promise<void>

A promise that settles after ms milliseconds; an aborted signal rejects it early with the signal's reason.

proc.Timertypeno test imports it
type Timer = Disposable & {
  /** The timer cleared: its function is not called. */
  clear(): void;
};

A timer that can be cleared, by call or by using.

proc.unrefTimerfunctionno test imports it
function unrefTimer(callback: () => void, ms: number): Timer

Calls callback after ms milliseconds, with a timer that never keeps the process alive (FR-053): where nothing else is left to do, the process ends without waiting for it. It is made on node:timers, whose timers can be unreferenced on each runtime.

proc.SelfFactstypeno test imports it
type SelfFacts = {
  readonly runtime: RuntimeName;
  readonly execPath: string;
  readonly argv: readonly string[];
  readonly execArgv: readonly string[];
};

What selfCommand reads of the running process: process.execPath, process.argv and process.execArgv, and the runtime.

proc.selfFactsfunctionno test imports it
function selfFacts(): SelfFacts

The facts of this process, for selfCommandOf.

proc.isCompiledfunctionno test imports it
function isCompiled(facts: SelfFacts): boolean

Whether the running program is a binary that holds its own code (FR-053), so that running it again needs no script. Either is enough:

  • Bun's own mark of a binary it compiled: the script's path, process.argv[1], is in Bun's embedded file system (/$bunfs/..., or B:\~BUN\... on Windows), where it keeps the code it compiled in;
  • the executable, process.execPath, is not named as a runtime is (bun, node, with any version or .exe): the binaries that bun build --compile and Node's single executable applications make are named after the program.
proc.selfCommandOffunctionno test imports it
function selfCommandOf(facts: SelfFacts, args?: readonly string[]): readonly string[]

The argument vector that runs the program again with args (FR-053): from a compiled binary, the binary alone; on Bun and Node, the runtime with its own options (process.execArgv) and the script. With no script (code given on the command line), the runtime alone.

proc.selfCommandfunctionno test imports it
function selfCommand(args?: readonly string[]): readonly string[]

The argument vector that runs this program again with args, on Bun and Node and from a binary Bun compiled (FR-053).

proc.NetworkInterfaceInfotypeno test imports it
type NetworkInterfaceInfo = { /** The interface's name (`lo`, `eth0`, `en0`, `Ethernet`). */ readonly name: string; … (676 characters)
type NetworkInterfaceInfo = {
  /** The interface's name (`lo`, `eth0`, `en0`, `Ethernet`). */
  readonly name: string;
  /** The address's family. */
  readonly family: "IPv4" | "IPv6";
  /** The address. */
  readonly address: string;
  /** Its netmask. */
  readonly netmask: string;
  /** The address with its prefix length (`127.0.0.1/8`), where known. */
  readonly cidr: string | null;
  /** The IPv6 scope, where there is one. */
  readonly scopeid: number | null;
  /** The hardware address (`00:00:00:00:00:00` where there is none). */
  readonly mac: string;
  /** Whether it is internal (a loopback), not reachable from outside. */
  readonly internal: boolean;
};

One address of one network interface.

proc.networkInterfacesfunctionno test imports it
function networkInterfaces(): readonly NetworkInterfaceInfo[]

Every address of every network interface of this computer (0001-net FR-007).

ProcessTracertypeno test imports it
type ProcessTracer = <T extends { readonly code: number }>(
  argv: readonly string[],
  run: (env: Readonly<Record<string, string>>) => Promise<T>,
) => Promise<T>;

What runs a program inside a trace: it is given the program's argument vector and a function that runs it with the environment to add (TRACEPARENT and TRACESTATE), and gives that function's outcome. The telemetry of commons installs one when its module is loaded (commons 0032-libraries-by-concern: this library does not import the telemetry); with none installed a program is run with nothing added.

setProcessTracerfunctionno test imports it
function setProcessTracer(t: ProcessTracer | undefined): void

Installs the function that traces the programs this module runs (or, with undefined, removes it): a program is a process span where one is installed (0006-signals FR-018).

envconstno test imports it
const env: { readonly get: (key: string) => string | undefined; readonly set: (key: string, value: string) => void; readonly delete: (key: string) => void; readonly has: (key: string) => boolean; readonly toObject: () => Record<string, string>; }

The process's environment.

argsconstno test imports it
const args: readonly string[]

The arguments the program was given, after the runtime's own and the script's path.

exitfunctionno test imports it
function exit(code?: number): never

The process ends now with code (0 by default).

cwdfunctionno test imports it
function cwd(): string

The process's working folder.

chdirfunctionno test imports it
function chdir(path: string): void

The process's working folder changed.

pidconstno test imports it
const pid: number

The process's id.

ppidfunctionno test imports it
function ppid(): number

The id of the process's parent (FR-053); a function, as the parent changes where the first one ends.

execPathfunctionno test imports it
function execPath(): string

The path of the runtime's executable (bun or node).

hostnamefunctionno test imports it
function hostname(): string

The computer's name.

homeDirfunctionno test imports it
function homeDir(): string

The account's home folder.

uidfunctionno test imports it
function uid(): number | undefined

The account's user id, or undefined on Windows.

isRootfunctionno test imports it
function isRoot(): boolean

Whether the process runs as root (never on Windows).

Archtypeno test imports it
type Arch = "x86_64" | "aarch64" | "arm" | "riscv64" | "s390x" | "ppc64" | "other";

A processor, by the names build.arch gives.

osOffunctionno test imports it
function osOf(platform: string): Os

The operating system's name for node:process's platform.

archOffunctionno test imports it
function archOf(arch: string): Arch

The processor's name for node:process's arch.

tripleOffunctionno test imports it
function tripleOf(os: Os, arch: Arch): string

The target triple (as Rust and Bun name it) for an operating system and a processor (FR-053): x86_64-unknown-linux-gnu, aarch64-apple-darwin, x86_64-pc-windows-msvc, aarch64-linux-android, and <arch>-unknown-<os> for the rest.

buildconst
const build: { readonly os: Os; readonly arch: Arch; readonly target: string; }

The platform this process runs on, with the target triple (FR-053).

Imported by 27 tests of the run (27 passed, 0 failed): the library's results

RuntimeNametypeno test imports it
type RuntimeName = "bun" | "node";

Which runtime runs this code.

runtimeNamefunctionno test imports it
function runtimeName(): RuntimeName

Which runtime runs this code, from process.versions, which each of them fills: Bun, the default, or Node 26, the backup.

runtimeVersionfunctionno test imports it
function runtimeVersion(): string

The version of the runtime that runs this code.

isExecutablefunctionno test imports it
function isExecutable(path: string): boolean

Whether a path is a file this account may run (on Windows, any file).

whichfunction
function which(name: string, path?: string): string | undefined

The program name on PATH (or the path itself where name has a separator), as command -v finds it; undefined where there is none.

Imported by 3 tests of the run (3 passed, 0 failed): the library's results

Stdiotypeno test imports it
type Stdio = "piped" | "inherit" | "null";

Where a stream of a program goes: kept (piped), shared with this process (inherit) or thrown away (null).

RunOptionstypeno test imports it
type RunOptions = { /** Its working folder. */ readonly cwd?: string; /** Variables added to its environment (or i… (1223 characters)
type RunOptions = {
  /** Its working folder. */
  readonly cwd?: string;
  /** Variables added to its environment (or its whole environment, with `clearEnv`). */
  readonly env?: Readonly<Record<string, string>>;
  /** Start it with no variable but those of `env`. */
  readonly clearEnv?: boolean;
  /** Text or bytes it reads as its standard input; without it, `stdin` says what it gets. */
  readonly input?: string | Uint8Array;
  /** Its standard input where there is no `input`: this process's own (`inherit`), or none (`null`, the default). */
  readonly stdin?: "inherit" | "null";
  /** Its standard output: kept (the default), shared, or thrown away. */
  readonly stdout?: Stdio;
  /** Its standard error: kept (the default), shared, or thrown away. */
  readonly stderr?: Stdio;
  /** Each line it writes, as it writes it, without its line ending; the output is kept as well. */
  readonly onLine?: (stream: "stdout" | "stderr", line: string) => void;
  /** Stopping it: SIGTERM when the signal aborts, then SIGKILL after `killAfterMs`. */
  readonly signal?: AbortSignal;
  /** How long a program stopped by `signal` has between SIGTERM and SIGKILL (5000 ms by default). */
  readonly killAfterMs?: number;
};

How to run a program.

Statustypeno test imports it
type Status = {
  /** Its exit status; 128 plus the signal's number where a signal ended it, as a shell reports it. */
  readonly code: number;
  /** Whether its exit status was 0. */
  readonly success: boolean;
  /** The signal that ended it (`SIGTERM`), or null. */
  readonly signal: string | null;
};

How a program ended.

Outputtypeno test imports it
type Output = { /** Its exit status; 128 plus the signal's number where a signal ended it, as a shell reports it. */ … (490 characters)
type Output = {
  /** Its exit status; 128 plus the signal's number where a signal ended it, as a shell reports it. */
  readonly code: number;
  /** Whether its exit status was 0. */
  readonly success: boolean;
  /** The signal that ended it (`SIGTERM`), or null. */
  readonly signal: string | null;
  /** What it wrote to standard output, where it was kept. */
  readonly stdout: Uint8Array;
  /** What it wrote to standard error, where it was kept. */
  readonly stderr: Uint8Array;
};

What a program did, with its output as bytes.

TextOutputtypeno test imports it
type TextOutput = Omit<Output, "stdout" | "stderr"> & { readonly stdout: string; readonly stderr: string };

What a program did, with its output as text.

signalNumberfunctionno test imports it
function signalNumber(name: string): number

The number of a signal by its name (1 for one it does not know).

outputfunctionno test imports it
function output(argv: readonly string[], options?: RunOptions): Promise<Output>

A program run to its end, by its argument vector and never through a shell, with what it did. NotFound where there is no such program. Where a telemetry pipeline is installed, the run is a process span and the program is given its TRACEPARENT (0006-signals FR-018).

runfunction
function run(argv: readonly string[], options?: RunOptions): Promise<TextOutput>

A program run to its end, with its output as text (UTF-8). NotFound where there is no such program.

Imported by 3 tests of the run (3 passed, 0 failed): the library's results

mustfunctionno test imports it
function must(argv: readonly string[], options?: RunOptions): Promise<string>

A program's standard output, where it succeeds; an Error naming the program, its status and what it said, where it does not.

firstLinefunctionno test imports it
function firstLine(argv: readonly string[], options?: RunOptions): Promise<string>

The first line a program prints, trimmed; "" where it fails or cannot be found.

KillSignaltypeno test imports it
type KillSignal = Signal | "SIGKILL" | "SIGABRT" | "SIGALRM" | "SIGSTOP" | "SIGCONT" | "SIGPIPE";

A signal a program can be sent.

SpawnOptionstypeno test imports it
type SpawnOptions = { /** Its working folder. */ readonly cwd?: string; /** Variables added to its environment (or… (988 characters)
type SpawnOptions = {
  /** Its working folder. */
  readonly cwd?: string;
  /** Variables added to its environment (or its whole environment, with `clearEnv`). */
  readonly env?: Readonly<Record<string, string>>;
  /** Start it with no variable but those of `env`. */
  readonly clearEnv?: boolean;
  /** Its standard input: a `WritableStream` (`piped`), this process's own (the default), or none. */
  readonly stdin?: Stdio;
  /** Its standard output: a `ReadableStream` (`piped`), this process's own (the default), or thrown away. */
  readonly stdout?: Stdio;
  /** Its standard error: a `ReadableStream` (`piped`), this process's own (the default), or thrown away. */
  readonly stderr?: Stdio;
  /** Stopping it: SIGTERM when the signal aborts, then SIGKILL after `killAfterMs`. */
  readonly signal?: AbortSignal;
  /** How long a program being stopped has between SIGTERM and SIGKILL (5000 ms by default), by `signal` or by `await using`. */
  readonly killAfterMs?: number;
};

How to start a program that runs beside this one; each stream is this process's own (inherit) unless asked.

Childtypeno test imports it
type Child = AsyncDisposable & { /** Its process id. */ readonly pid: number; /** Its standard input, where it is … (998 characters)
type Child = AsyncDisposable & {
  /** Its process id. */
  readonly pid: number;
  /** Its standard input, where it is piped; closing the stream closes its input. */
  readonly stdin: WritableStream<Uint8Array> | null;
  /** Its standard output, where it is piped. */
  readonly stdout: ReadableStream<Uint8Array> | null;
  /** Its standard error, where it is piped. */
  readonly stderr: ReadableStream<Uint8Array> | null;
  /** How it ended, once it ends; rejected with the runtime's error where it could not be started. */
  readonly status: Promise<Status>;
  /** Sends it a signal (SIGTERM by default); nothing where it has already ended. */
  kill(signal?: KillSignal): void;
  /** Its whole output and error, read from the piped streams (empty where not piped), and its status, once it ends. */
  output(): Promise<Output>;
  /** It keeps this process alive until it ends (the default). */
  ref(): void;
  /** It no longer keeps this process alive; nor do its pipes. */
  unref(): void;
};

A program while it runs await using stops it (SIGTERM, then SIGKILL) where it still runs, and waits for it.

spawnfunctionno test imports it
function spawn(argv: readonly string[], options?: SpawnOptions): Child

Starts a program by its argument vector, never through a shell, and gives its handle while it runs (FR-052). A program that cannot be found throws NotFound at once: a path that is not an executable file, or a name not on the PATH of the environment it is given. Where a telemetry pipeline is installed, the run is a process span that ends when the program does, and the program is given its TRACEPARENT (0006-signals FR-018), as for output.

import { spawn } from "./proc.ts";
await using child = spawn(["gzip", "-dc"], { stdin: "piped", stdout: "piped" });
Signaltypeno test imports it
type Signal = "SIGINT" | "SIGTERM" | "SIGHUP" | "SIGQUIT" | "SIGUSR1" | "SIGUSR2" | "SIGWINCH" | "SIGBREAK";

A signal this process can listen for.

addSignalListenerfunctionno test imports it
function addSignalListener(signal: Signal, handler: () => void): void

A function called when the process receives the signal.

removeSignalListenerfunctionno test imports it
function removeSignalListener(signal: Signal, handler: () => void): void

A function no longer called for the signal.

sleepfunction
function sleep(ms: number, signal?: AbortSignal | undefined): Promise<void>

A promise that settles after ms milliseconds; an aborted signal rejects it early with the signal's reason.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

Timertypeno test imports it
type Timer = Disposable & {
  /** The timer cleared: its function is not called. */
  clear(): void;
};

A timer that can be cleared, by call or by using.

unrefTimerfunctionno test imports it
function unrefTimer(callback: () => void, ms: number): Timer

Calls callback after ms milliseconds, with a timer that never keeps the process alive (FR-053): where nothing else is left to do, the process ends without waiting for it. It is made on node:timers, whose timers can be unreferenced on each runtime.

SelfFactstypeno test imports it
type SelfFacts = {
  readonly runtime: RuntimeName;
  readonly execPath: string;
  readonly argv: readonly string[];
  readonly execArgv: readonly string[];
};

What selfCommand reads of the running process: process.execPath, process.argv and process.execArgv, and the runtime.

selfFactsfunctionno test imports it
function selfFacts(): SelfFacts

The facts of this process, for selfCommandOf.

isCompiledfunctionno test imports it
function isCompiled(facts: SelfFacts): boolean

Whether the running program is a binary that holds its own code (FR-053), so that running it again needs no script. Either is enough:

  • Bun's own mark of a binary it compiled: the script's path, process.argv[1], is in Bun's embedded file system (/$bunfs/..., or B:\~BUN\... on Windows), where it keeps the code it compiled in;
  • the executable, process.execPath, is not named as a runtime is (bun, node, with any version or .exe): the binaries that bun build --compile and Node's single executable applications make are named after the program.
selfCommandOffunctionno test imports it
function selfCommandOf(facts: SelfFacts, args?: readonly string[]): readonly string[]

The argument vector that runs the program again with args (FR-053): from a compiled binary, the binary alone; on Bun and Node, the runtime with its own options (process.execArgv) and the script. With no script (code given on the command line), the runtime alone.

selfCommandfunctionno test imports it
function selfCommand(args?: readonly string[]): readonly string[]

The argument vector that runs this program again with args, on Bun and Node and from a binary Bun compiled (FR-053).

NetworkInterfaceInfotype
type NetworkInterfaceInfo = { /** The interface's name (`lo`, `eth0`, `en0`, `Ethernet`). */ readonly name: string; … (676 characters)
type NetworkInterfaceInfo = {
  /** The interface's name (`lo`, `eth0`, `en0`, `Ethernet`). */
  readonly name: string;
  /** The address's family. */
  readonly family: "IPv4" | "IPv6";
  /** The address. */
  readonly address: string;
  /** Its netmask. */
  readonly netmask: string;
  /** The address with its prefix length (`127.0.0.1/8`), where known. */
  readonly cidr: string | null;
  /** The IPv6 scope, where there is one. */
  readonly scopeid: number | null;
  /** The hardware address (`00:00:00:00:00:00` where there is none). */
  readonly mac: string;
  /** Whether it is internal (a loopback), not reachable from outside. */
  readonly internal: boolean;
};

One address of one network interface.

Imported by 1 test of the run (1 passed, 0 failed): the library's results

networkInterfacesfunction
function networkInterfaces(): readonly NetworkInterfaceInfo[]

Every address of every network interface of this computer (0001-net FR-007).

Imported by 1 test of the run (1 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.