Using UniPty

Swapping engines is a one-line change — acquire a different Backend and everything else stays identical:

import { UniPty } from "unipty";
import { createNodePtyBackend } from "@unipty/backend-node-pty";
import { createZigptyBackend } from "@unipty/backend-zigpty";
import { createBunBackend } from "@unipty/backend-bun";
import { createDenoSigmaPtyFfiBackend } from "@unipty/backend-deno-sigma__pty-ffi";

// Pick the engine by acquiring a different Backend — every line below the
// constructor is identical on all four routes:
const unipty = new UniPty({ backend: await createZigptyBackend() });

Engine-specific options (encoding, writeDecode, queue tuning, FFI permissions) and behavioral limits live in each package's README, linked from the route table below.

Construct with a ready Backend

A factory (or .ready()) performs one-time runtime loading first; then Core accepts the ready instance. The concrete Backend type is preserved and exposed read-only.

import { UniPty } from "unipty";
import { createNodePtyBackend, NodePtyBackend } from "@unipty/backend-node-pty";

const backend: NodePtyBackend = await createNodePtyBackend();
const unipty = new UniPty({ backend });

unipty.backend === backend; // readonly, concrete type preserved

Spawn with structured argv

The launch entry is unipty.spawn(argv, options): argv is non-empty, its first value is the executable, and there is no string-command overload. Core never implicitly invokes a shell. Initial geometry lives under terminal: { cols, rows } in character cells; omitted dimensions resolve independently from the value, COLUMNS/LINES, a trusted host TTY probe, then 80 × 24.

const pty = unipty.spawn(["/bin/sh", "-i", "-l"], {
  terminal: { cols: 120, rows: 40 },
  env: { TERM: "xterm-256color" }, // launch context; never overrides geometry
});

One stream per PTY

stream() selects the representation: Terminal Text (ReadableStream<string>) or Terminal Bytes (ReadableStream<Uint8Array>). One active stream per PTY — a second call fails with the active-stream code; use caller-owned tee() for fan-out. Cancelling the stream detaches that view only: it never closes input and never terminates the child. Startup output is preserved in a bounded bootstrap buffer until the first view attaches.

const text = pty.stream({ encoding: "utf8" }); // ReadableStream<string>
const bytes = pty.stream({ encoding: "bytes" }); // only after the first detaches

const reader = text.getReader();
for (;;) {
  const { done, value } = await reader.read();
  if (done) break;
  render(value);
}

Write with boolean readiness

write() accepts string | Uint8Array and returns a boolean. Either return value means the whole value was accepted exactly once; false only means “pause and drain”. Backpressure is advisory, but saturation rejects one whole value with the backpressure code — never a partial accept, silent drop, or unbounded queue.

if (!pty.write("ls -la\r")) {
  await pty.drain(); // readiness recovery, not a physical flush
}

Resize

resize(cols, rows) takes positive integer character cells only. Pixel dimensions stay Backend-specific; a Backend that cannot resize reports unsupported explicitly.

pty.resize(120, 40);

Terminate and close are non-cascading

terminate() is an idempotent synchronous termination request. close() is an idempotent synchronous logical close: it publishes closed before returning, invalidates all I/O surfaces, and lets an active stream complete normally — but it does not terminate the child, and terminate does not close the transport.

pty.terminate(); // request only; exit is observed independently
pty.close();     // publishes closed; further write/resize/stream() reject with "closed"
console.log(pty.closed);

Exit is an independent observation

exited is a repeatable promise for { exitCode, signal }. It is independent of transport EOF, stream cancellation, and close: an already-established exit observation survives close, and signal records the observed termination cause, not a general kill(signal) vocabulary. Exec failures surface as an exit observation (never a spawn exception) on every route; signalled deaths keep the engine's own shape — see the capability matrix for what each route reports.

const result = await pty.exited;
console.log(result.exitCode, result.signal); // number | null, string | null

Capabilities and error codes

Backend extensions ride on opaque capability tokens looked up by object identity — no string registry, no fallback. Operational failures carry stable codes: unsupported, closed, backpressure, invalid-argument, active-stream.

import { defineCapabilityToken } from "unipty";

// Capability tokens are Backend-owned singletons; Core matches object
// identity only (no string registry, no name fallback). No official
// Backend ships a token yet — this is the intended shape when one does:
interface SignalsCapability { kill(signal: string): void }
const signalsCapability = defineCapabilityToken<SignalsCapability>();

const signals = pty.capability(signalsCapability);
if (signals) signals.kill("SIGHUP"); // Backend vocabulary; explicit, never silent

Dispose the Backend owner

UniPty.dispose() blocks new spawns, keeps existing PTYs caller-owned, waits for them to close, then releases shared Backend resources exactly once. Repeated calls reuse one promise.

await unipty.dispose();

Manual import — the first-class path

const { createBunBackend } = await import("@unipty/backend-bun");
const backend = await createBunBackend();
const unipty = new UniPty({ backend });

AutoResolve

autoResolveUniPtyBackend analyzes the current runtime, processes your explicit candidates first (unavailable candidates emit a structured warning), then falls back to candidates inferred from your package.json dependencies. Fallback requires exactly one compatible result; several produce ambiguous. The selected candidate’s initialization is terminal — a failure is reported with the structured backend-initialization code, never silently retried with the next Backend.

import { autoResolveUniPtyBackend } from "@unipty/backend";

const backend = await autoResolveUniPtyBackend({
  candidates: ["@unipty/backend-node-pty", "@unipty/backend-bun"],
  from: import.meta.url, // caller-rooted base
  onWarning: (warning) => console.warn(warning.code, warning.packageName),
});

Pure resolution and inspection

resolveUniPtyBackend resolves one package location at a time and requires an explicit caller from: URL; inspectUniPtyBackend imports only the side-effect-free metadata subpath — never the Backend entry module or factory. Neither stage initializes anything.

import { resolveUniPtyBackend, inspectUniPtyBackend } from "@unipty/backend";

const report = await resolveUniPtyBackend("@unipty/backend-deno-sigma__pty-ffi", {
  from: import.meta.url,
});
if (report.status === "resolved") {
  const inspection = await inspectUniPtyBackend(report);
  if (inspection.status === "compatible") {
    /* metadata-compatible with this Core; still no native initialization */
  }
}

Bundled deployments: explicit manifest

Bundlers cannot resolve runtime package graphs. Generate an explicit build-time manifest with the helper CLI, then let AutoResolve select from it. Generated modules default-export one manifest, statically import each package’s ./unipty.metadata, and keep Backend entry imports inside deferred loaders — evaluating the manifest imports no Backend entry and initializes nothing.

pnpm unipty-helper-backend manifest \
  --candidate @unipty/backend-node-pty \
  --candidate @unipty/backend-bun \
  --candidate @unipty/backend-deno-sigma__pty-ffi \
  --out src/unipty-backends.manifest.ts

import backendManifest from "./unipty-backends.manifest";

const backend = await autoResolveUniPtyBackend({
  manifest: backendManifest,
  candidates: ["@unipty/backend-node-pty"],
});