visaljs 0.0.4 → 0.0.6

package/node/prelude/fs.js

@@ -1,7 +1,10 @@
-// node:fs (ADR 0012, layer 3): the synchronous file API, over the host primitives. Contents are
-// Buffers without an encoding, else strings in any of Buffer's encodings.
-import { errnoName, fsExists, fsReadFile, fsUnlink, fsWriteFile } from "visaljs:host";
-import { codeError, invalidArgType, invalidArgValue, notSupported, systemError } from "./internal/errors.js";
+// node:fs (ADR 0012, layer 3): the synchronous file API, over the host primitives, and the
+// callback API, stat's and readdir's, and read streams over it. Contents are Buffers without an
+// encoding, else strings in any of Buffer's encodings. A callback runs on a later tick, as
+// Node's, though the I/O itself happened synchronously (so do node:fs/promises').
+import { errnoName, fsExists, fsReadAt, fsReaddir, fsReadFile, fsStat, fsUnlink, fsWriteFile } from "visaljs:host";
+import { codeError, invalidArgType, invalidArgValue, notSupported, systemError, validateFunction } from "./internal/errors.js";
+import { Readable } from "./stream.js";
 
 function validatePath(path) {
   if (typeof path !== "string") {
@@ -76,4 +79,173 @@ export function unlinkSync(path) {
   check(fsUnlink(path), "unlink", path);
 }
 
-export default { readFileSync, writeFileSync, appendFileSync, existsSync, unlinkSync };
+/* ---- stat ------------------------------------------------------------------------- */
+
+const S_IFMT = 0o170000, S_IFREG = 0o100000, S_IFDIR = 0o040000, S_IFLNK = 0o120000, S_IFIFO = 0o010000,
+  S_IFSOCK = 0o140000, S_IFCHR = 0o020000, S_IFBLK = 0o060000;
+
+export class Stats {
+  constructor(dev, mode, nlink, uid, gid, rdev, blksize, ino, size, blocks, atimeMs, mtimeMs, ctimeMs, birthtimeMs) {
+    Object.assign(this, { dev, mode, nlink, uid, gid, rdev, blksize, ino, size, blocks, atimeMs, mtimeMs, ctimeMs, birthtimeMs });
+    this.atime = new Date(atimeMs);
+    this.mtime = new Date(mtimeMs);
+    this.ctime = new Date(ctimeMs);
+    this.birthtime = new Date(birthtimeMs);
+  }
+
+  isFile() { return (this.mode & S_IFMT) === S_IFREG; }
+  isDirectory() { return (this.mode & S_IFMT) === S_IFDIR; }
+  isSymbolicLink() { return (this.mode & S_IFMT) === S_IFLNK; }
+  isFIFO() { return (this.mode & S_IFMT) === S_IFIFO; }
+  isSocket() { return (this.mode & S_IFMT) === S_IFSOCK; }
+  isCharacterDevice() { return (this.mode & S_IFMT) === S_IFCHR; }
+  isBlockDevice() { return (this.mode & S_IFMT) === S_IFBLK; }
+}
+
+function statOf(path, options, follow, syscall) {
+  validatePath(path);
+  const r = fsStat(path, follow);
+  if (typeof r === "number") {
+    if (options?.throwIfNoEntry === false && errnoName(r) === "ENOENT") return undefined;
+    throw systemError(r, syscall, path);
+  }
+  const [mode, size, mtimeMs, atimeMs, ctimeMs, birthtimeMs, ino, dev, nlink, uid, gid, rdev, blksize, blocks] = r;
+  return new Stats(dev, mode, nlink, uid, gid, rdev, blksize, ino, size, blocks, atimeMs, mtimeMs, ctimeMs, birthtimeMs);
+}
+
+export function statSync(path, options) {
+  return statOf(path, options, true, "stat");
+}
+
+export function lstatSync(path, options) {
+  return statOf(path, options, false, "lstat");
+}
+
+/* ---- readdir ---------------------------------------------------------------------- */
+
+/* libuv's uv_dirent_type_t */
+const UV_DIRENT_FILE = 1, UV_DIRENT_DIR = 2, UV_DIRENT_LINK = 3, UV_DIRENT_FIFO = 4, UV_DIRENT_SOCKET = 5, UV_DIRENT_CHAR = 6,
+  UV_DIRENT_BLOCK = 7;
+const kType = Symbol("type");
+
+export class Dirent {
+  constructor(name, type, path) {
+    this.name = name;
+    this.parentPath = path;
+    this.path = path;
+    this[kType] = type;
+  }
+
+  isFile() { return this[kType] === UV_DIRENT_FILE; }
+  isDirectory() { return this[kType] === UV_DIRENT_DIR; }
+  isSymbolicLink() { return this[kType] === UV_DIRENT_LINK; }
+  isFIFO() { return this[kType] === UV_DIRENT_FIFO; }
+  isSocket() { return this[kType] === UV_DIRENT_SOCKET; }
+  isCharacterDevice() { return this[kType] === UV_DIRENT_CHAR; }
+  isBlockDevice() { return this[kType] === UV_DIRENT_BLOCK; }
+}
+
+export function readdirSync(path, options) {
+  validatePath(path);
+  if (options?.recursive) throw notSupported("readdir's recursive option");
+  const encoding = encodingOf(options);
+  validateEncodingName(encoding);
+  const r = check(fsReaddir(path), "scandir", path);
+  const names = [], types = [];
+  for (let i = 0; i < r.length; i += 2) {
+    names.push(r[i]);
+    types.push(r[i + 1]);
+  }
+  /* in libuv's order, as Node's (it lists them through libuv too) */
+  const named = (name) => (encoding === undefined || isUtf8(encoding) ? name : encoding === "buffer" ? Buffer.from(name) : Buffer.from(name).toString(encoding));
+  if (options?.withFileTypes) return names.map((name, i) => new Dirent(named(name), types[i], path));
+  return names.map(named);
+}
+
+/* ---- the callback API: the synchronous call, its outcome on a later tick ------------ */
+
+function later(fn, args, callback) {
+  validateFunction(callback, "cb");
+  let result, error = null;
+  try {
+    result = fn(...args);
+  } catch (e) {
+    error = e;
+  }
+  process.nextTick(() => (error ? callback(error) : callback(null, result)));
+}
+
+const withCallback = (fn) => (path, options, callback) => {
+  if (typeof options === "function") later(fn, [path], options);
+  else later(fn, [path, options], callback);
+};
+
+export const readFile = withCallback(readFileSync);
+export const stat = withCallback(statSync);
+export const lstat = withCallback(lstatSync);
+export const readdir = withCallback(readdirSync);
+
+export function writeFile(path, data, options, callback) {
+  if (typeof options === "function") later(writeFileSync, [path, data], options);
+  else later(writeFileSync, [path, data, options], callback);
+}
+
+export function unlink(path, callback) {
+  later(unlinkSync, [path], callback);
+}
+
+/* ---- read streams --------------------------------------------------------------- */
+
+/** A file read a chunk at a time, from `start` to `end` (inclusive), as Node's. */
+export class ReadStream extends Readable {
+  constructor(path, options) {
+    if (typeof options === "string") options = { encoding: options };
+    options = { ...options };
+    super({ highWaterMark: options.highWaterMark ?? 64 * 1024, encoding: options.encoding, emitClose: options.emitClose ?? true, autoDestroy: options.autoClose ?? true });
+    validatePath(path);
+    this.path = path;
+    this.start = options.start;
+    this.end = options.end ?? Infinity;
+    this.pos = options.start ?? 0;
+    this.bytesRead = 0;
+    this.pending = true;
+    /* opened on the next tick, as Node's: a missing file is an error even if nothing reads */
+    process.nextTick(() => {
+      const r = fsStat(path, true);
+      if (typeof r === "number") return this.destroy(systemError(r, "open", path));
+      this.pending = false;
+      this.emit("open");
+      this.emit("ready");
+    });
+  }
+
+  /* a chunk on a later tick, as Node's read (on libuv's thread pool) delivers it: each read a chunk */
+  _read() {
+    const want = Math.min(this.readableHighWaterMark, this.end + 1 - this.pos);
+    if (want <= 0) return this.push(null);
+    const chunk = fsReadAt(this.path, this.pos, want);
+    process.nextTick(() => {
+      if (typeof chunk === "number") return this.destroy(systemError(chunk, "read", this.path));
+      if (chunk.length === 0) return this.push(null);
+      this.pos += chunk.length;
+      this.bytesRead += chunk.length;
+      this.push(chunk);
+    });
+  }
+}
+
+export function createReadStream(path, options) {
+  return new ReadStream(path, options);
+}
+
+/* node:fs/promises, which imports this module: read when used, not while the modules load */
+export { default as promises } from "./fs_promises.js";
+import promises from "./fs_promises.js";
+
+export default {
+  readFileSync, writeFileSync, appendFileSync, existsSync, unlinkSync, statSync, lstatSync, readdirSync, readFile, writeFile,
+  unlink, stat, lstat, readdir, createReadStream, ReadStream, Stats, Dirent,
+  get promises() {
+    return promises;
+  },
+};

package/node/prelude/fs_promises.js

@@ -0,0 +1,24 @@
+// node:fs/promises (ADR 0012, layer 3): node:fs's synchronous calls, their outcome as a promise.
+// The I/O happens when the function is called, not on libuv's thread pool as in Node.
+import {
+  appendFileSync, existsSync, lstatSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync,
+} from "./fs.js";
+
+const promised = (fn) => async (...args) => fn(...args);
+
+export const readFile = promised(readFileSync);
+export const writeFile = promised(writeFileSync);
+export const appendFile = promised(appendFileSync);
+export const stat = promised(statSync);
+export const lstat = promised(lstatSync);
+export const readdir = promised(readdirSync);
+export const unlink = promised(unlinkSync);
+
+/** Whether the path exists (the mode isn't checked). */
+export async function access(path) {
+  if (!existsSync(path)) {
+    statSync(path);  /* throws Node's ENOENT (or the error that stopped it) */
+  }
+}
+
+export default { readFile, writeFile, appendFile, stat, lstat, readdir, unlink, access };

package/node/prelude/http.js

@@ -8,6 +8,7 @@
 // connections close after keepAliveTimeout; server.timeout and setTimeout are the sockets'.
 // Not yet: the client, headersTimeout and requestTimeout, trailers.
 import { httpAttach, httpDate, httpDetach, httpExpired, httpFlush, httpParsers, httpWrite, timerUnref } from "visaljs:host";
+import { bindContext, currentContext, runInContext } from "./internal/async_context.js";
 import { codeError, invalidArgType, outOfRange, validateInteger, validateString } from "./internal/errors.js";
 import { Agent, globalAgent } from "./internal/http_agent.js";
 import { createConnection, Server as NetServer } from "./net.js";
@@ -543,7 +544,8 @@ export class Server extends NetServer {
   /* a connection: its bytes go to llhttp; its end, timeout, errors and close are the requests' */
   _onSocket(socket) {
     if (this._parsers === -1) {
-      this._parsers = httpParsers(
+      /* in the async context of the connection's (ADR 0020), as the server's sockets' callbacks */
+      this._parsers = httpParsers(...[
         (conn, method, url, raw, major, minor, keepAlive, upgrade) => this._onRequest(conn, method, url, raw, major, minor, keepAlive, upgrade),
         (conn, chunk) => this._states.get(conn)?.req?._push(chunk),
         (conn, trailers) => {
@@ -567,7 +569,7 @@ export class Server extends NetServer {
           e.reason = reason;
           socketOnError.call(state.socket, e);
         },
-      );
+      ].map(bindContext));
     }
     const conn = socket._handle;
     if (conn === null) return;
@@ -704,10 +706,16 @@ function urlToHttpOptions(url) {
 const clientSockets = new Map();
 let clientParsers = -1;
 
+/* the async context a request was made in (ADR 0020): its response's callbacks run in it, as in
+ * Node, whichever request's the socket was */
+const kAsyncContext = Symbol("kAsyncContext");
+const inRequestContext = (fn) => (conn, ...args) =>
+  runInContext(clientSockets.get(conn)?._httpMessage?.[kAsyncContext], fn, undefined, [conn, ...args]);
+
 function clientParsersId() {
   if (clientParsers !== -1) return clientParsers;
   const reqOf = (conn) => clientSockets.get(conn)?._httpMessage;
-  clientParsers = httpParsers(
+  clientParsers = httpParsers(...[
     (conn, statusCode, statusMessage, raw, major, minor, keepAlive, upgrade) => {
       const socket = clientSockets.get(conn);
       const req = socket?._httpMessage;
@@ -759,7 +767,7 @@ function clientParsersId() {
         req.emit("error", e);
       }
     },
-  );
+  ].map(inRequestContext));
   return clientParsers;
 }
 
@@ -945,6 +953,7 @@ const INVALID_PATH_REGEX = /[^!-ÿ]/;
 export class ClientRequest extends OutgoingMessage {
   constructor(input, options, cb) {
     super();
+    this[kAsyncContext] = currentContext();
     if (typeof input === "string") input = urlToHttpOptions(new URL(input));
     else if (input instanceof URL) input = urlToHttpOptions(input);
     else {

package/node/prelude/internal/async_context.js

@@ -0,0 +1,27 @@
+// The async context (ADR 0020): the value the runtime carries through jobs, timers and promise
+// reactions, which node:async_hooks' AsyncLocalStorage keeps its stores in (a frame: a Map from
+// each storage to its store, never changed once current). I/O callbacks run under none: the
+// prelude binds each to the context it was registered in, as Node runs a handle's callbacks in
+// the context of its resource.
+import { asyncContextGet, asyncContextSet } from "visaljs:host";
+
+export { asyncContextGet as currentContext, asyncContextSet as setContext };
+
+/** fn.apply(thisArg, args) under `context`, then the current one again. */
+export function runInContext(context, fn, thisArg, args) {
+  const prior = asyncContextGet();
+  if (prior === context) return Reflect.apply(fn, thisArg, args);
+  asyncContextSet(context);
+  try {
+    return Reflect.apply(fn, thisArg, args);
+  } finally {
+    asyncContextSet(prior);
+  }
+}
+
+/** A host callback (it runs under no context) that runs under the current one: fn itself when
+ *  there's none. */
+export function bindContext(fn) {
+  const context = asyncContextGet();
+  return context === undefined ? fn : (...args) => runInContext(context, fn, undefined, args);
+}

package/node/prelude/internal/errors.js

@@ -56,6 +56,17 @@ export function systemError(errno, syscall, path) {
   return error;
 }
 
+/** A failed libuv call as Node's errnoException builds it: `kill ESRCH`, with errno, code and
+ *  syscall. */
+export function errnoException(errno, syscall) {
+  const code = errnoName(errno);
+  const error = new Error(syscall + " " + code);
+  error.errno = errno;
+  error.code = code;
+  error.syscall = syscall;
+  return error;
+}
+
 export function validateString(value, name) {
   if (typeof value !== "string") throw invalidArgType(name, "of type string", value);
 }

package/node/prelude/internal/process_events.js

@@ -0,0 +1,14 @@
+// process as an EventEmitter (ADR 0012): the runtime's process, in every binary, is a plain
+// object. A program that may call its emitter methods gets this module first (the driver adds it:
+// implicitModules in node/index.ts), and the runtime emits process's events through its emit.
+import { EventEmitter } from "../events.js";
+
+const p = globalThis.process;
+
+/* its prototype is process.constructor.prototype, an EventEmitter's, as in Node */
+function process() {}
+process.prototype = Object.create(EventEmitter.prototype, {
+  constructor: { value: process, writable: true, configurable: true },
+});
+Object.setPrototypeOf(p, process.prototype);
+EventEmitter.init.call(p);

package/node/prelude/internal/process_signals.js

@@ -0,0 +1,42 @@
+// process's signal events and process.kill (ADR 0012): Node's startListeningIfSignal and
+// stopListeningIfSignal, on libuv's signal handles (src/host_signal.c). A program gets this
+// module when its code names process and a signal ("SIGINT") or kill (implicitModules in
+// node/index.ts); apart from process_events.js, as it links libuv.
+import { osConstants, processKill, signalStart, signalStop } from "visaljs:host";
+import { codeError, errnoException, invalidArgType } from "./errors.js";
+import "./process_events.js";
+
+const p = globalThis.process;
+const signals = Object.create(null);  // "SIGINT" → 2, as os.constants.signals
+const [table] = osConstants();
+for (let i = 0; i < table.length; i += 2) signals[table[i]] = table[i + 1];
+const watched = Object.create(null);
+
+/* the first listener of a signal replaces its default action; listeners get (name, number) */
+p.on("newListener", (type) => {
+  if (typeof type !== "string" || signals[type] === undefined || watched[type]) return;
+  const err = signalStart(signals[type], (signum) => p.emit(type, type, signum));
+  if (err < 0) throw errnoException(err, "uv_signal_start");
+  watched[type] = true;
+});
+
+/* the last one gone, the default action again */
+p.on("removeListener", (type) => {
+  if (typeof type !== "string" || !watched[type] || p.listenerCount(type) > 0) return;
+  signalStop(signals[type]);
+  watched[type] = false;
+});
+
+p.kill = function kill(pid, sig) {
+  if (pid != (pid | 0)) throw invalidArgType("pid", "of type number", pid);
+  let signum;
+  if (sig === (sig | 0)) signum = sig;
+  else {
+    sig = sig || "SIGTERM";
+    signum = signals[sig];
+    if (signum === undefined) throw codeError(TypeError, "ERR_UNKNOWN_SIGNAL", "Unknown signal: " + sig);
+  }
+  const err = processKill(pid, signum);
+  if (err < 0) throw errnoException(err, "kill");
+  return true;
+};

package/node/prelude/internal/timers.js

@@ -0,0 +1,233 @@
+// node:timers' core (ADR 0012): Timeout and Immediate on the runtime's timers (timerStart and
+// friends, runtime/src/jobs.c). Each object holds one native one-shot timer, armed under one id
+// (also its primitive), which an interval re-arms after its callback. node:timers and
+// node:timers/promises build on it; a program that uses them gets them as its globals too
+// (timers_global.js).
+import { timerClear, timerRef, timerStart } from "visaljs:host";
+import { validateFunction } from "./errors.js";
+
+export const TIMEOUT_MAX = 2 ** 31 - 1;
+
+export const kId = Symbol("timerId");          /* its native timer's id, which is also its primitive */
+export const kFire = Symbol("fire");           /* the native timer's callback: one per object */
+export const kPending = Symbol("pending");     /* a native timer is armed */
+export const kRefed = Symbol("refed");
+const kHasPrimitive = Symbol("kHasPrimitive");
+
+/* the ids of timers whose primitive was taken: clearTimeout(id) finds them (Node's knownTimersById) */
+const knownTimersById = new Map();
+/* every armed Timeout: a number that names one whose primitive wasn't taken clears nothing */
+export const armed = new Map();
+
+function emitWarning(message) {
+  if (typeof process.emitWarning === "function") process.emitWarning(message, "TimeoutOverflowWarning");
+}
+
+/* the delay as Node takes it: 1 when below 1 ms, not a number or past 2^31 - 1 */
+export function duration(after) {
+  after *= 1;
+  if (!(after >= 1 && after <= TIMEOUT_MAX)) {
+    if (after > TIMEOUT_MAX) emitWarning(`${after} does not fit into a 32-bit signed integer.\nTimeout duration was set to 1.`);
+    after = 1;
+  }
+  return after;
+}
+
+/* (re)arms the native timer under the item's id: a pending one starts over */
+export function arm(item, refed) {
+  item[kId] = timerStart(item[kFire], item._idleTimeout, refed, item[kId] ?? 0);
+  item[kPending] = true;
+  armed.set(item[kId], item);
+}
+
+function disarm(item) {
+  if (item[kPending]) timerClear(item[kId]);
+  item[kPending] = false;
+  armed.delete(item[kId]);
+}
+
+export class Timeout {
+  constructor(callback, after, args, isRepeat, isRefed) {
+    after = duration(after);
+    this._idleTimeout = after;
+    this._idlePrev = this;
+    this._idleNext = this;
+    this._idleStart = null;
+    this._onTimeout = callback;
+    this._timerArgs = args;
+    this._repeat = isRepeat ? after : null;
+    this._destroyed = false;
+    this[kRefed] = isRefed;
+    this[kHasPrimitive] = false;
+    this[kPending] = false;
+    this[kFire] = () => fireTimeout(this);
+  }
+
+  /* the timer starts over from now; one that already fired runs again */
+  refresh() {
+    if (this._idleTimeout >= 0) {
+      this._destroyed = false;
+      arm(this, this[kRefed]);
+    }
+    return this;
+  }
+
+  unref() {
+    if (this[kRefed]) {
+      this[kRefed] = false;
+      if (this[kPending]) timerRef(this[kId], false);
+    }
+    return this;
+  }
+
+  ref() {
+    if (!this[kRefed]) {
+      this[kRefed] = true;
+      if (this[kPending]) timerRef(this[kId], true);
+    }
+    return this;
+  }
+
+  hasRef() {
+    return this[kRefed];
+  }
+
+  close() {
+    clearTimeout(this);
+    return this;
+  }
+
+  [Symbol.toPrimitive]() {
+    const id = this[kId];
+    if (!this[kHasPrimitive]) {
+      this[kHasPrimitive] = true;
+      knownTimersById.set(id, this);
+    }
+    return id;
+  }
+}
+if (typeof Symbol.dispose === "symbol") {
+  Timeout.prototype[Symbol.dispose] = function () {
+    clearTimeout(this);
+  };
+}
+
+function fireTimeout(timer) {
+  timer[kPending] = false;
+  armed.delete(timer[kId]);
+  const args = timer._timerArgs;
+  try {
+    if (args === undefined) timer._onTimeout();
+    else Reflect.apply(timer._onTimeout, timer, args);
+  } finally {
+    if (timer._repeat && timer._idleTimeout !== -1) {
+      timer._idleTimeout = timer._repeat;
+      if (!timer[kPending]) arm(timer, timer[kRefed]);
+    } else if (!timer[kPending] && !timer._destroyed) {  /* not refreshed by its callback */
+      timer._destroyed = true;
+      if (timer[kHasPrimitive]) knownTimersById.delete(timer[kId]);
+    }
+  }
+}
+
+export function unenrollTimeout(item) {
+  if (item._destroyed) return;
+  item._destroyed = true;
+  if (item[kHasPrimitive]) knownTimersById.delete(item[kId]);
+  disarm(item);
+  item._idleTimeout = -1;
+}
+
+export function setTimeout(callback, after, ...args) {
+  validateFunction(callback, "callback");
+  const timeout = new Timeout(callback, after, args.length ? args : undefined, false, true);
+  arm(timeout, true);
+  return timeout;
+}
+
+export function setInterval(callback, repeat, ...args) {
+  validateFunction(callback, "callback");
+  const timeout = new Timeout(callback, repeat, args.length ? args : undefined, true, true);
+  arm(timeout, true);
+  return timeout;
+}
+
+/* a Timeout, a primitive one gave, or a native timer's id (the runtime's and the prelude's) */
+export function clearTimeout(timer) {
+  if (timer && timer._onTimeout) {
+    timer._onTimeout = null;
+    unenrollTimeout(timer);
+    return;
+  }
+  if (typeof timer === "number" || typeof timer === "string") {
+    const known = knownTimersById.get(Number(timer));
+    if (known !== undefined) {
+      known._onTimeout = null;
+      unenrollTimeout(known);
+    } else if (typeof timer === "number" && !armed.has(timer)) {
+      timerClear(timer);
+    }
+  }
+}
+
+export function clearInterval(timer) {
+  clearTimeout(timer);
+}
+
+export class Immediate {
+  constructor(callback, args) {
+    this._idleNext = null;
+    this._idlePrev = null;
+    this._onImmediate = callback;
+    this._argv = args;
+    this._destroyed = false;
+    this[kRefed] = true;
+    this[kId] = timerStart(() => runImmediate(this), -1, true, 0);
+  }
+
+  ref() {
+    if (this[kRefed] === false) {
+      this[kRefed] = true;
+      timerRef(this[kId], true);
+    }
+    return this;
+  }
+
+  unref() {
+    if (this[kRefed] === true) {
+      this[kRefed] = false;
+      timerRef(this[kId], false);
+    }
+    return this;
+  }
+
+  hasRef() {
+    return !!this[kRefed];
+  }
+}
+if (typeof Symbol.dispose === "symbol") {
+  Immediate.prototype[Symbol.dispose] = function () {
+    clearImmediate(this);
+  };
+}
+
+function runImmediate(immediate) {
+  immediate._destroyed = true;
+  immediate[kRefed] = null;
+  const argv = immediate._argv;
+  if (argv === undefined) immediate._onImmediate();
+  else immediate._onImmediate(...argv);
+}
+
+export function setImmediate(callback, ...args) {
+  validateFunction(callback, "callback");
+  return new Immediate(callback, args.length ? args : undefined);
+}
+
+export function clearImmediate(immediate) {
+  if (!immediate || immediate._destroyed) return;
+  immediate._destroyed = true;
+  immediate[kRefed] = null;
+  immediate._onImmediate = null;
+  timerClear(immediate[kId]);
+}

package/node/prelude/internal/timers_global.js

@@ -0,0 +1,9 @@
+// The Node timer globals (ADR 0012): the runtime's setTimeout and friends, in every binary,
+// return numbers. A program that may use what Node's return (a Timeout's unref(), refresh(),
+// hasRef(), or node:timers itself, whose clearTimeout must take the globals' timers) gets this
+// module first (implicitModules in node/index.ts), so that setTimeout === timers.setTimeout.
+import { clearImmediate, clearInterval, clearTimeout, setImmediate, setInterval, setTimeout } from "../timers.js";
+
+for (const [name, fn] of Object.entries({ setTimeout, clearTimeout, setInterval, clearInterval, setImmediate, clearImmediate })) {
+  Object.defineProperty(globalThis, name, { value: fn, writable: true, enumerable: true, configurable: true });
+}

package/node/prelude/internal/zlib_brotli.js

@@ -0,0 +1,6 @@
+// node:zlib's Brotli streams' host primitives, for programs whose code names Brotli
+// (internal/zlib_engines.js).
+import { brotliClose, brotliInit, brotliNew, brotliReset, brotliWrite } from "visaljs:host";
+import { engines } from "./zlib_engines.js";
+
+engines.brotli = { new: brotliNew, init: brotliInit, write: brotliWrite, reset: brotliReset, close: brotliClose };

package/node/prelude/internal/zlib_engines.js

@@ -0,0 +1,4 @@
+// node:zlib's optional libraries (ADR 0012): Brotli's and zstd's host primitives are registered
+// here by internal/zlib_brotli.js and internal/zlib_zstd.js, implicit modules a program gets when
+// its own code names them, so a program that only gzips links neither (~800 and ~600 KB).
+export const engines = { brotli: null, zstd: null };

package/node/prelude/internal/zlib_zstd.js

@@ -0,0 +1,6 @@
+// node:zlib's zstd streams' host primitives, for programs whose code names zstd
+// (internal/zlib_engines.js).
+import { zstdClose, zstdInit, zstdNew, zstdReset, zstdWrite } from "visaljs:host";
+import { engines } from "./zlib_engines.js";
+
+engines.zstd = { new: zstdNew, init: zstdInit, write: zstdWrite, reset: zstdReset, close: zstdClose };