runtime:process

Host process information: environment, arguments, working directory, platform, signals, and exit. Aligned in spirit with the WinterTC CLI-API proposal.

Import

import { env, args, parseArgs, stdin, platform, arch, cwd, exit, unmask } from "runtime:process";

// Or the default aggregate:
import process from "runtime:process";

Exports

env — reading and writing

import { env } from "runtime:process";

console.log(env.HOME);      // read
env.FEATURE_FLAG = "on";    // write (in-process only)
delete env.SECRET;          // delete (in-process only)

args — program arguments

// esrun app.js build --watch
import { args } from "runtime:process";

console.log(args); // ["build", "--watch"]

parseArgs — options and flags

Node's util.parseArgs, reading args by default:

// esrun server.js start -p 3000 --verbose
import { parseArgs } from "runtime:process";

const { values, positionals } = parseArgs({
  options: {
    port: { type: "string", short: "p", default: "8080" },
    verbose: { type: "boolean", short: "v" },
  },
  allowPositionals: true,
});

console.log(values.port, values.verbose, positionals); // "3000" true ["start"]

values has no prototype. --name=value, -nvalue, -abc groups and -- (everything after it is positional) are understood.

signals — graceful shutdown

Watching a signal suppresses its default action, which is what lets a SIGTERM drain instead of kill.

import { onSignal, offSignal } from "runtime:process";

const shutdown = async (signal) => {
  offSignal(signal, shutdown);   // a second ^C should kill, not queue
  await server.stop();
};
onSignal("SIGINT", shutdown);
onSignal("SIGTERM", shutdown);

exit — stopping the run

import { exit } from "runtime:process";

if (failed) exit(1); // records the code and halts immediately
exit();              // defaults to 0

stdin — reading input

import { stdin } from "runtime:process";

// A question on standard error, the answer from standard input.
const name = await stdin.question("Name? ");

// A filter: `cat data.txt | esrun count.js`
let count = 0;
for await (const line of stdin.lines()) count++;
console.log(count);

All of these, and the global prompt(), read from one buffer, so a line one of them read past is not lost to the next. The runtime restores the terminal from raw mode when the program ends, however it ends.

// One keypress, without Enter.
stdin.setRawMode(true);
const { value } = await stdin.readable.getReader().read();
stdin.setRawMode(false);

For a quick synchronous question, the web's prompt(), confirm() and alert() are globals. When stdin is not a terminal, they return at once rather than wait.

No capability is needed. A worker cannot read stdin, because a process has one input.

stdout — drawing on a terminal

console.log formats a value, appends a newline, and goes wherever the host pointed it. That is right for a log line and wrong for a display: a spinner is a carriage return and no newline, and a progress bar rewrites the line it is already on.

import { stdout } from "runtime:process";

if (stdout.isTTY) {
  stdout.write(`\r${bar(done / total, stdout.columns ?? 60)}`);
} else {
  console.log(`${done}/${total}`);
}

Ask isTTY before you draw. A spinner redrawn with \r into a log file is a file of spinner frames, and colour escapes in a pipe are noise in somebody's grep.

The size comes from the terminal, not from $COLUMNS — a shell exports that to itself rather than to a child, and it is stale the moment the window is dragged. Where the host cannot answer it says so rather than reporting a plausible 80.

Neither needs a capability, for the reason console.log does not: writing to the stream this program was started with reaches nothing it was not already handed, so --deny-all still leaves a program able to say what it is doing.

permissions — what this run may reach

Fixed at launch by esrun's permission flags, so has() is a synchronous boolean: there is nothing to request and no prompt to await.

import { permissions } from "runtime:process";

permissions.denied; // ["read", "write"] — [] when nothing is denied
permissions.has("net"); // true

if (permissions.has("write")) await fs.write("cache.json", data);

PermissionName is "read", "write", "imports", "net", "listen", "env", "run", "signals" — the same words the --deny-<name> flags use. Needs no capability, so it answers with everything denied too.

A scoped grant reports true: --allow-env=PORT grants the env capability and narrows what it yields, so has("env") means "you may read an environment variable", not "you may read this one". The same holds for --allow-net=<hosts> and the rest.

There is no per-value form — has("read", "/etc/passwd") throws. Which paths and hosts are allowed is set by the deployment, not asked about by the application, and the exact answer for one value is to make the call and catch ERR_PERMISSION_DENIED. A path is judged after the runtime resolves it, so an answer given in advance could be stale by the time the call happens.

Secrets — masked by default

Secret-bearing keys are exposed as a Secret that renders as [redacted] in console, strings, and JSON. A key qualifies if it ends in _KEY, _TOKEN, _SECRET, _PASS(WORD), or contains CREDENTIAL/AUTH.

import { env, unmask } from "runtime:process";

// Keys ending in *_SECRET(S) / *_PASSWORD(S) are masked by default.
console.log(env.DB_PASSWORD);        // [redacted]
console.log(`${env.DB_PASSWORD}`);   // [redacted]
JSON.stringify(env);                 // ..."DB_PASSWORD":"[redacted]"...

const pw = unmask(env.DB_PASSWORD);  // real value, explicit
unmask(env.DB_HOST);                 // plain strings pass through

Load values from a file with esrun --env-file=.env (no auto-discovery; the OS environment wins unless --env-override is passed).

Timers that do not hold the process

A setInterval for a heartbeat or a periodic flush keeps a program running for ever. unrefTimer lets it go: the timer still fires while anything else keeps the program alive, but no longer keeps it alive on its own. refTimer undoes it.

import { unrefTimer } from "runtime:process";

unrefTimer(setInterval(flushMetrics, 10_000));

id is what setTimeout or setInterval returned. A cleared or fired timer is left alone. In a worker they apply to that worker's own timers; the worker itself stays until it is terminated, or until its parent calls worker.unref(). These match Deno's Deno.unrefTimer and Deno.refTimer; Node puts unref() on the timer object, and setTimeout returns a number here, as on the web.

Reporting on yourself

import { cpuTime, memoryUsage, uptime } from "runtime:process";

const { heapUsed, heapLimit } = memoryUsage();
if (heapLimit - heapUsed < 32 * 1024 * 1024) shedLoad();

heapLimit - heapUsed is real headroom: exceed it and the heap guard ends this agent. Per isolate, so a worker answers for itself:

// in a worker started with { memory: 64 }
memoryUsage().heapLimit;   // 67108864, not the parent's
cpuTime();                 // CPU burned by *this worker's* thread
uptime();                  // ms since *this worker* started

uptime() is not performance.now(). A worker is handed its parent's clock, so performance.now() counts from when the process's runtime was built and reads the same in every agent.

Utilisation is two reads and a division:

const [cpu0, t0] = [cpuTime(), uptime()];
await work();
const busy = (cpuTime() - cpu0) / (uptime() - t0);

cpuTime() is total CPU, not a user/system split. The split needs Mach on macOS, where a wrong struct layout is a memory-safety bug rather than a wrong number, so it is reported nowhere rather than on two platforms out of three.

Errors