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,
} 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.resolve#
Resolves a path or 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.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 package specifier from a directory.
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.
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.
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;
// Resolves a path or 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;
}