JS stdlib — runtime API

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

Runtime identity and process-level operations.

Node, Bun, Deno, and browser implementations are selected through package export conditions. Browser imports are safe: identity, arguments, flags, platform fields, and memory queries have explicit browser values; process, filesystem, package, and module-resolution operations throw unimplemented.

import runtime from "@rcompat/runtime";
import type {
  Flags, MemoryUsage, Resolve, Runtime, Unsubscribe,
} from "@rcompat/runtime";

runtime.name#

Current runtime name: node, bun, deno, or browser.

runtime.name: string;

runtime.bin#

Runtime executable path, or an empty string in browsers.

runtime.bin: string;

runtime.script#

Current script path or URL, or an empty string in browsers.

runtime.script: string;

runtime.cwd#

Returns the current working directory as a file reference.

Throws: In browsers, always throws unimplemented.

runtime.cwd: () => FileRef;

runtime.args#

Program arguments with the runtime and script entries removed.

runtime.args: string[];

runtime.exit#

Exits the process with an optional status code.

Throws: In browsers, always throws unimplemented.

runtime.exit: (code?: number) => never;

runtime.on#

Subscribe to current-process termination signals. Each registration, including duplicates, has its own idempotent unsubscribe function.

Throws: In browsers, each method throws unimplemented.

runtime.on: {
    // Subscribe to SIGINT.
    interrupt: (callback: () => void) => Unsubscribe;
    // Subscribe to SIGTERM.
    terminate: (callback: () => void) => Unsubscribe;
    // Subscribe to SIGHUP.
    hangup: (callback: () => void) => Unsubscribe;
  };

runtime.on.interrupt#

Subscribe to SIGINT.

runtime.on.interrupt: (callback: () => void) => Unsubscribe;

runtime.on.terminate#

Subscribe to SIGTERM.

runtime.on.terminate: (callback: () => void) => Unsubscribe;

runtime.on.hangup#

Subscribe to SIGHUP.

runtime.on.hangup: (callback: () => void) => Unsubscribe;

runtime.before#

Natural process lifecycle events.

runtime.before: {
    // Subscribe once to natural event-loop exhaustion. Removes the listener
    // before invoking the callback and keeps the process alive until its
    // returned promise settles. Consumers must bound cleanup and handle
    // errors. Not called for forced or explicit exits.
    exit: (callback: () => void | Promise<void>) => Unsubscribe;
  };

runtime.before.exit#

Subscribe once to natural event-loop exhaustion. Removes the listener before invoking the callback and keeps the process alive until its returned promise settles. Consumers must bound cleanup and handle errors. Not called for forced or explicit exits.

Throws: In browsers, throws unimplemented.

runtime.before.exit: (callback: () => void | Promise<void>) => Unsubscribe;

runtime.interrupt#

Send SIGINT to this process without removing other listeners. Default termination requires all intercepting listeners to be removed first.

Throws: In browsers, throws unimplemented.

runtime.interrupt: () => void;

runtime.terminate#

Send SIGTERM; follows the same listener semantics as interrupt.

runtime.terminate: () => void;

runtime.hangup#

Send SIGHUP; follows the same listener semantics as interrupt.

runtime.hangup: () => void;

runtime.resolve#

Resolves a path or ESM package specifier from a directory.

Throws: In browsers, always throws unimplemented.

runtime.resolve: Resolve;

runtime.toRequire#

Creates a CommonJS-compatible require function anchored at a path.

Throws: In browsers, always throws unimplemented.

runtime.toRequire: (path: Path) => NodeJS.Require;

runtime.packageJSON#

Reads the nearest project manifest.

Parameters

from — Starting path; defaults to the current working directory.

Throws: In browsers, always throws unimplemented.

runtime.packageJSON: (from?: Path) => Promise<PackageJSON>;

runtime.projectRoot#

Finds the nearest ancestor containing package.json.

Parameters

from — Starting path; defaults to the current working directory.

Returns: A reference to the project directory.

Throws: In browsers, always throws unimplemented.

runtime.projectRoot: (from?: Path) => Promise<FileRef>;

runtime.conditions#

Collects active CLI and TypeScript custom conditions without duplicates.

Reads repeated --conditions flags and compilerOptions.customConditions from tsconfig.json, following string extends chains. Inherited TypeScript conditions precede local ones; circular chains throw.

Parameters

from — Project directory; otherwise the project root is discovered.

Throws: In browsers, always throws unimplemented.

runtime.conditions: (from?: Path) => Promise<string[]>;

runtime.flags#

Parsed command-line flags; empty in browsers.

runtime.flags: Flags;

runtime.os#

Operating system, or undefined when unavailable or unknown.

runtime.os: OS | undefined;

runtime.arch#

CPU architecture, or undefined when unavailable or unknown.

runtime.arch: Arch | undefined;

runtime.memoryUsage#

Returns an instantaneous aggregate process-memory sample when available.

Values are bytes. Node and Bun expose every field. Deno reports arrayBuffers as undefined. Browsers return undefined and do not use the non-standard Chromium-only performance.memory API.

runtime.memoryUsage: () => MemoryUsage | undefined;

Types#

Flags#

Parsed command-line flags.

Extends Bag with many(), which returns every value supplied for a repeated key. Flags accept --key=value, --key value, and bare --key forms; a bare flag has an empty-string value.

type Flags = Bag & {
  // Returns all values supplied for a key, in argument order.
  many(key: string): string[];
};

MemoryUsage#

Aggregate process-memory values measured in bytes.

interface MemoryUsage {
  // Resident set size, or `undefined` when unavailable.
  readonly rss: number | undefined;
  // Allocated JavaScript heap, or `undefined` when unavailable.
  readonly heapTotal: number | undefined;
  // Used JavaScript heap, or `undefined` when unavailable.
  readonly heapUsed: number | undefined;
  // Native memory attached to JavaScript objects, when available.
  readonly external: number | undefined;
  // Memory allocated for `ArrayBuffer` values, when available.
  readonly arrayBuffers: number | undefined;
}

Resolve#

Resolves a path or ESM package specifier from a directory.

Package resolution observes host import conditions and npm exports, imports, self references, and nested package ownership.

Parameters

specifier — Relative path, absolute path, or package specifier.
from — Directory from which to resolve.

Returns: The resolved filesystem path.

type Resolve = (specifier: string, from: string) => string;

Runtime#

Runtime identity and process-level operations.

interface Runtime {
  // Current runtime name: `node`, `bun`, `deno`, or `browser`.
  name: string;
  // Runtime executable path, or an empty string in browsers.
  bin: string;
  // Current script path or URL, or an empty string in browsers.
  script: string;
  // Returns the current working directory as a file reference.
  cwd: () => FileRef;
  // Program arguments with the runtime and script entries removed.
  args: string[];
  // Exits the process with an optional status code.
  exit: (code?: number) => never;
  // Subscribe to current-process termination signals. Each registration,
  // including duplicates, has its own idempotent unsubscribe function.
  on: {
    // Subscribe to SIGINT.
    interrupt: (callback: () => void) => Unsubscribe;
    // Subscribe to SIGTERM.
    terminate: (callback: () => void) => Unsubscribe;
    // Subscribe to SIGHUP.
    hangup: (callback: () => void) => Unsubscribe;
  };
  // Natural process lifecycle events.
  before: {
    // Subscribe once to natural event-loop exhaustion. Removes the listener
    // before invoking the callback and keeps the process alive until its
    // returned promise settles. Consumers must bound cleanup and handle
    // errors. Not called for forced or explicit exits.
    exit: (callback: () => void | Promise<void>) => Unsubscribe;
  };
  // Send SIGINT to this process without removing other listeners. Default
  // termination requires all intercepting listeners to be removed first.
  interrupt: () => void;
  // Send SIGTERM; follows the same listener semantics as `interrupt`.
  terminate: () => void;
  // Send SIGHUP; follows the same listener semantics as `interrupt`.
  hangup: () => void;
  // Resolves a path or ESM package specifier from a directory.
  resolve: Resolve;
  // Creates a CommonJS-compatible `require` function anchored at a path.
  toRequire: (path: Path) => NodeJS.Require;
  // Reads the nearest project manifest.
  packageJSON: (from?: Path) => Promise<PackageJSON>;
  // Finds the nearest ancestor containing `package.json`.
  projectRoot: (from?: Path) => Promise<FileRef>;
  // Collects active CLI and TypeScript custom conditions without duplicates.
  conditions: (from?: Path) => Promise<string[]>;
  // Parsed command-line flags; empty in browsers.
  flags: Flags;
  // Operating system, or `undefined` when unavailable or unknown.
  os: OS | undefined;
  // CPU architecture, or `undefined` when unavailable or unknown.
  arch: Arch | undefined;
  // Returns an instantaneous aggregate process-memory sample when available.
  memoryUsage: () => MemoryUsage | undefined;
}

Unsubscribe#

Removes one lifecycle callback; safe to call more than once.

type Unsubscribe = () => void;