JS stdlib — io API

Member signatures use schematic object.member(...) API notation. Exported type declarations are valid TypeScript.

Standard streams, process execution, and async context across runtimes.

Node, Deno, and Bun provide the complete API. Browser bundles can import the package, but every utility throws because standard streams and child processes are unavailable.

import io from "@rcompat/io";
import type {
  ChildProcess, ExitStatus, ProcessSignal, RunOptions, RunResult,
  SpawnOptions, Stdio, StdioInput, StdioOptions,
} from "@rcompat/io";

The default input/output utility aggregate.

io.async#

Asynchronous context utilities.

Async members#

io.async.Context#

The runtime-compatible AsyncLocalStorage constructor.

io.async.Context: typeof AsyncLocalStorage;

io.isatty()#

Tests whether standard output is attached to a terminal.

io.isatty(): boolean;

io.run()#

Runs a shell command and captures its complete text output.

Nonzero exit codes resolve normally with success: false. Startup and stream failures reject. A timeout covers both process exit and complete output capture.

Parameters

command — Platform-shell command to execute.
options — Working directory, environment, timeout, and timeout signal.

Returns: Captured output and exit status.

io.run(
  command: string,
  options?: RunOptions,
): Promise<RunResult>;

Example

const result = await io.run("echo hello");
result.success; // true
result.stdout.trim(); // "hello"

io.spawn()#

Spawns a platform-shell command or directly executes an argument vector.

String commands use the platform shell. Supplying an argument array bypasses the shell and passes every argument verbatim. On POSIX systems the child is placed in an isolated process group so kill and timeouts terminate its descendants as well.

io.spawn: {
  <S extends StdioInput = "pipe">(
    command: string,
    options?: SpawnOptions<S>,
  ): ChildProcess<S>;
  <S extends StdioInput = "pipe">(
    executable: string,
    args: readonly string[],
    options?: SpawnOptions<S>,
  ): ChildProcess<S>;
};

io.stderr#

Standard error as a Node-compatible writable stream.

io.stderr: NodeJS.WriteStream & { readonly fd: 2 };

io.stdin#

Standard input as a Node-compatible readable stream.

io.stdin: NodeJS.ReadStream & { readonly fd: 0 };

io.stdout#

Standard output as a Node-compatible writable stream.

io.stdout: NodeJS.WriteStream & { readonly fd: 1 };

io.which()#

Resolves an executable with the platform's which or where utility.

Parameters

command — Executable name to locate.

Returns: The first non-empty path reported by the locator.

Throws: When the executable cannot be found or the locator fails.

io.which(command: string): Promise<string>;

Types#

RunOptions#

Spawn options accepted by io.run, excluding stream configuration.

type RunOptions = Omit<SpawnOptions, "stdio">;

RunResult#

Captured text output and final process status from io.run.

type RunResult = ExitStatus & {
  // Captured standard error decoded as text.
  stderr: string;
  // Captured standard output decoded as text.
  stdout: string;
};

ChildProcess#

A spawned process and its configured Web Streams.

type ChildProcess<S extends StdioInput = StdioInput> = {
  // Sends a signal, defaulting to `SIGTERM`.
  kill(signal?: ProcessSignal): void;
  // Runtime process identifier.
  pid: number;
  // Final status, including nonzero exits and timeout state.
  status: Promise<ExitStatus>;
  // Piped standard error, or `null` for `inherit` and `ignore`.
  stderr: Stream<Mode<S, "stderr">, ReadableStream<Uint8Array>>;
  // Piped standard input, or `null` for `inherit` and `ignore`.
  stdin: Stream<Mode<S, "stdin">, WritableStream<Uint8Array>>;
  // Piped standard output, or `null` for `inherit` and `ignore`.
  stdout: Stream<Mode<S, "stdout">, ReadableStream<Uint8Array>>;
};

ExitStatus#

Final child-process status.

type ExitStatus = {
  // Exit code, or `null` when terminated by a signal.
  code: number | null;
  // Terminating signal, or `null` after a normal exit.
  signal: ProcessSignal | null;
  // Whether the process exited with code zero without a signal or timeout.
  success: boolean;
  // Whether the configured timeout terminated the process.
  timedOut: boolean;
};

SpawnOptions#

Options for io.spawn.

type SpawnOptions<S extends StdioInput = StdioInput> = {
  // Child working directory.
  cwd?: string;
  // Child environment variables.
  env?: Environment;
  // Signal sent when `timeout` expires.
  // Default: `"SIGKILL"`
  killSignal?: ProcessSignal;
  // Standard-stream modes.
  // Default: `"pipe"`
  stdio?: S;
  // Milliseconds before terminating the process group.
  timeout?: number;
};

ProcessSignal#

Portable process signals accepted by process controls.

type ProcessSignal =
  | "SIGABRT"
  | "SIGALRM"
  | "SIGHUP"
  | "SIGINT"
  | "SIGKILL"
  | "SIGPIPE"
  | "SIGQUIT"
  | "SIGTERM"
  | "SIGUSR1"
  | "SIGUSR2";

Stdio#

Standard-stream handling mode.

type Stdio = "ignore" | "inherit" | "pipe";

StdioInput#

One mode for every stream or independent per-stream modes.

type StdioInput = Stdio | StdioOptions;

StdioOptions#

Per-stream handling modes.

type StdioOptions = {
  // Standard-error mode.
  // Default: `"pipe"`
  stderr?: Stdio;
  // Standard-input mode.
  // Default: `"pipe"`
  stdin?: Stdio;
  // Standard-output mode.
  // Default: `"pipe"`
  stdout?: Stdio;
};

Supporting contracts#

These contracts support public signatures but are not named root exports.

DefaultPipe#

Resolves an omitted stream mode to "pipe".

type DefaultPipe<M> = [Exclude<M, undefined>] extends [never]
  ? "pipe"
  : Exclude<M, undefined>;

Environment#

Environment variables supplied to a child process.

type Environment = Record<string, string | undefined>;

Mode#

Resolves the effective mode for one configured standard stream.

type Mode<S extends StdioInput, K extends keyof StdioOptions> =
  S extends Stdio ? S
    : K extends keyof S ? DefaultPipe<S[K]>
    : "pipe";

Stream#

Selects a Web Stream for "pipe", or null otherwise.

type Stream<M extends Stdio, T> = M extends "pipe" ? T : null;