@scriptc/compiler 0.4.6 → 0.4.8

package/ambient/node-fallback/child_process.d.ts

@@ -1,13 +1,16 @@
+/// <reference path="./stream.d.ts" />
+
 /* node:child_process — the synchronous slice: spawnSync(command, args?)
  * runs the child to completion (posix_spawn + waitpid) with stdout/stderr
  * captured as utf8 strings. `status` is the exit code, or null when the
  * child died to a signal OR could not be spawned at all (nonexistent
- * binary, permission denied) — Node reports spawn failure through the
- * result's `error` property, which this surface does not carry, and types
- * stdout/stderr null there where scriptc returns "" (SEMANTICS.md).
- * No shell, no options object: the command runs directly (PATH-searched,
- * like Node). */
+ * binary, permission denied). A spawn failure is DATA on the result, never
+ * a throw: `error` is the Error Node builds ("spawnSync <file> ENOENT",
+ * `code` stamped, or ETIMEDOUT after a timeout kill) and both outputs are
+ * "" where Node types them null (SEMANTICS.md). */
 declare module "child_process" {
+  import type { Readable, Writable } from "stream";
+
   export interface SpawnSyncReturns {
     readonly status: number | null;
     readonly stdout: string;
@@ -29,7 +32,15 @@ declare module "child_process" {
    * the signal, never a throw), killSignal (a signal NAME literal),
    * stdio ("ignore"/"inherit"/"pipe" or a 3-tuple of those — captures
    * read "" for non-piped streams), env (replaces the child's
-   * environment), and windowsHide (a POSIX no-op). */
+   * environment), cwd (the child's directory), input (the string piped
+   * to its stdin — `| undefined` means the option is absent, "" pipes an
+   * empty stdin), shell (the complete command line in `command`, with a
+   * statically empty args list, run by /bin/sh -c), and windowsHide (a
+   * POSIX no-op).
+   * The shell form takes no separate args: Node warns DEP0190 because it
+   * concatenates them unescaped, and a native build has no warning
+   * channel, so the compiler REFUSES `shell: true` with a non-empty args
+   * list. */
   export function spawnSync(
     command: string,
     args?: string[],
@@ -39,10 +50,42 @@ declare module "child_process" {
       killSignal?: string;
       stdio?: "pipe" | "ignore" | "inherit" | ("pipe" | "ignore" | "inherit")[];
       env?: { [k: string]: string | undefined };
+      cwd?: string;
+      /* Piped to the child's stdin. undefined is an ABSENT option (no
+       * pipe, fd 0 is /dev/null or inherited per stdio); "" is an EMPTY
+       * stdin, which the child reads as immediate EOF — Node's reading. */
+      input?: string | undefined;
       windowsHide?: boolean;
+      /* Node's shell form: the complete command line in `command`, with
+       * an empty args list, runs through /bin/sh -c, so quoting and
+       * operators follow the shell's rules. A non-empty args list with
+       * shell: true is a compile error (Node warns DEP0190 for unescaped
+       * shell arguments). */
+      shell?: boolean;
     },
   ): SpawnSyncReturns;
 
+  /* The named options interface for the string-encoding spawnSync form —
+   * @types/node's SpawnSyncOptionsWithStringEncoding, narrowed to the
+   * honestly-implemented members (env and killSignal keep the inline
+   * literal form: a runtime record cannot carry a replacement
+   * environment). VALUES of this type are a real record (type-mapper.ts
+   * interns the shape), so a typed const or a runner function's options
+   * parameter flows to spawnSync at runtime with its members read at the
+   * call. */
+  export interface SpawnSyncOptionsWithStringEncoding {
+    encoding: "utf8" | "utf-8";
+    cwd?: string;
+    input?: string;
+    stdio?: "pipe" | "ignore" | "inherit" | ("pipe" | "ignore" | "inherit")[];
+    timeout?: number;
+    windowsHide?: boolean;
+    /* Read at the call. The call then takes the command-line form only:
+     * a statically non-empty args list is a compile error (Node warns
+     * DEP0190 for unescaped shell arguments). */
+    shell?: boolean;
+  }
+
   /* The asynchronous slice: spawn with stdio "ignore"/"inherit"/fd/"pipe"
    * tuples (piped stdin is writable through child.stdin; piped stdout/stderr
    * deliver through child.stdout/stderr) and the terminal events. "exit"
@@ -57,18 +100,19 @@ declare module "child_process" {
    * loop quiescence (SEMANTICS.md documents the divergence). An "error"
    * event with no registered listener prints the error and exits 1,
    * exactly the unhandled-'error' EventEmitter behavior. */
-  export interface ChildStdin {
-    readonly writable: boolean;
-    write(chunk: string | Uint8Array): boolean;
-    end(): void;
-    destroy(): void;
-    on(event: "drain" | "finish", listener: () => void): void;
-    on(event: "error", listener: (err: Error) => void): void;
-    on(event: string, listener: (...args: any[]) => void): void;
-    once(event: "drain" | "finish", listener: () => void): void;
-    once(event: "error", listener: (err: Error) => void): void;
-    once(event: string, listener: (...args: any[]) => void): void;
-  }
+  /* The piped child stdin is the node:stream Writable Node's typings give
+   * it, so it flows into any Writable slot and back. Members the direct
+   * handle does not lower (the underscored hooks, cork, an encoding, a
+   * third argument) typecheck and need the general stream
+   * representation. */
+  export interface ChildStdin extends Writable {}
+
+  /* The piped child output is the node:stream Readable Node's typings
+   * give it. The direct handle delivers one chunk per pipe read (a
+   * Buffer, or a string after setEncoding); the rest of the Readable
+   * surface typechecks and needs the general stream representation to
+   * lower. */
+  export interface ChildStdout extends Readable {}
 
   export interface ChildProcess extends Disposable {
     ref(): void;
@@ -125,10 +169,11 @@ declare module "child_process" {
     disconnect(): void;
     [Symbol.dispose](): void;
     /* The piped streams — non-null exactly when the matching stdio slot
-     * was "pipe" (Node's shape). */
+     * was "pipe" (Node's shape; the node:stream classes, narrowed to the
+     * members the direct handles deliver). */
     readonly stdin: ChildStdin | null;
-    readonly stdout: NodeJS.ReadableStream | null;
-    readonly stderr: NodeJS.ReadableStream | null;
+    readonly stdout: ChildStdout | null;
+    readonly stderr: ChildStdout | null;
   }
   export interface SpawnOptions {
     /* The 3-tuple form admits number fds in the stdout/stderr slots —
@@ -140,7 +185,9 @@ declare module "child_process" {
     /* detached gives the child its own session and process group
      * (POSIX_SPAWN_SETSID); env REPLACES the child environment; cwd
      * sets its working directory; windowsHide is a POSIX no-op; shell
-     * runs the complete command string through /bin/sh or cmd.exe. */
+     * runs the complete command string through /bin/sh or cmd.exe (with
+     * an empty args list — a non-empty one is a compile error, because
+     * Node warns DEP0190 for unescaped shell arguments). */
     detached?: boolean;
     env?: { [k: string]: string | undefined };
     cwd?: string;
@@ -186,6 +233,8 @@ declare module "child_process" {
     maxBuffer?: number;
     killSignal?: string;
     windowsHide?: boolean;
+    /* Runs the complete command line through /bin/sh -c; it takes an
+     * empty args list (Node warns DEP0190 for unescaped shell args). */
     shell?: boolean;
   }
   /* The named options interface for the string-encoding exec form —

package/ambient/node-fallback/crypto.d.ts

@@ -277,14 +277,20 @@ declare module "crypto" {
     copy(options?: HashOptions): Hash;
     update(data: string | ArrayBufferView): Hash;
     update(data: string, inputEncoding: Encoding): Hash;
+    /* A digest is Buffer.toString(encoding): Node answers every Buffer
+     * encoding, the character and legacy ones included (a hash's bytes are
+     * arbitrary, so utf8 spells the undecodable sequences U+FFFD).
+     * @types/node narrows this parameter to BinaryToTextEncoding (a cast
+     * there); the runtime decodes each spelling listed in Encoding and no
+     * other, so the parameter admits exactly that set. */
     digest(): Buffer;
-    digest(encoding: BinaryToTextEncoding): string;
+    digest(encoding: Encoding): string;
   }
   export interface Hmac extends Transform {
     update(data: string | ArrayBufferView): Hmac;
     update(data: string, inputEncoding: Encoding): Hmac;
     digest(): Buffer;
-    digest(encoding: BinaryToTextEncoding): string;
+    digest(encoding: Encoding): string;
   }
   export function createHash(algorithm: string, options?: HashOptions): Hash;
   export function createHmac(
@@ -292,12 +298,14 @@ declare module "crypto" {
     key: BinaryLike | KeyObject,
     options?: { encoding?: BufferEncoding | undefined },
   ): Hmac;
+  /* crypto.hash's output encoding is the same Buffer conversion digest()
+   * makes, so it takes the same Encoding set. */
   export interface OneShotDigestOptions {
-    outputEncoding?: BinaryToTextEncoding | "buffer" | undefined;
+    outputEncoding?: Encoding | "buffer" | undefined;
     outputLength?: number | undefined;
   }
   export interface OneShotDigestOptionsWithStringEncoding extends OneShotDigestOptions {
-    outputEncoding?: BinaryToTextEncoding | undefined;
+    outputEncoding?: Encoding | undefined;
   }
   export interface OneShotDigestOptionsWithBufferEncoding extends OneShotDigestOptions {
     outputEncoding: "buffer";
@@ -305,7 +313,7 @@ declare module "crypto" {
   export function hash(
     algorithm: string,
     data: string | ArrayBufferView,
-    options?: OneShotDigestOptionsWithStringEncoding | BinaryToTextEncoding,
+    options?: OneShotDigestOptionsWithStringEncoding | Encoding,
   ): string;
   export function hash(
     algorithm: string,
@@ -315,7 +323,7 @@ declare module "crypto" {
   export function hash(
     algorithm: string,
     data: string | ArrayBufferView,
-    options: OneShotDigestOptions | BinaryToTextEncoding | "buffer",
+    options: OneShotDigestOptions | Encoding | "buffer",
   ): string | Buffer;
   export function timingSafeEqual(
     a: ArrayBufferView | ArrayBufferLike,
@@ -771,7 +779,7 @@ declare module "crypto" {
    * stance). Every ACCESS bakes as its literal at lowering; the object
    * itself never materializes (bare crypto.constants value uses fence). */
   export interface CryptoConstants {
-    readonly OPENSSL_VERSION_NUMBER: 810549376;
+    readonly OPENSSL_VERSION_NUMBER: 810549392;
     readonly SSL_OP_ALL: 2147485776;
     readonly SSL_OP_ALLOW_NO_DHE_KEX: 1024;
     readonly SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION: 262144;

package/ambient/node-fallback/events.d.ts

@@ -5,7 +5,12 @@
  * checks annotated listener parameters against it (unannotated non-empty
  * parameter lists have no static types and fence at the registration). */
 declare module "events" {
-  class EventEmitter {
+  /* Generic like @types/node's class: the type argument is the listener
+   * MAP, a pure typing aid with no runtime layout (Node erases it too), so
+   * `class Sink extends EventEmitter<Map>` adopts the same emitter base.
+   * The map stays unconstrained here — the members below are the untyped
+   * `...args: any[]` surface either way. */
+  class EventEmitter<EventMap = Record<string, any[]>> {
     constructor();
     static defaultMaxListeners: number;
     /* Listeners registered under this symbol observe 'error' emits first
@@ -45,11 +50,29 @@ declare module "events" {
       options?: { signal?: AbortSignal },
     ): Promise<unknown[]>;
     /* The emitter's own listenerCount/getMaxListeners/setMaxListeners/
-     * listeners, over EventEmitter instances. */
-    export function listenerCount(emitter: EventEmitter, eventName: string | symbol): number;
-    export function getMaxListeners(emitter: EventEmitter): number;
-    export function setMaxListeners(n?: number, ...eventTargets: EventEmitter[]): void;
-    export function getEventListeners(emitter: EventEmitter, name: string): Array<() => void>;
+     * listeners, over EventEmitter instances and EventTargets. */
+    export function listenerCount(
+      emitterOrTarget: EventEmitter | EventTarget,
+      eventName: string | symbol,
+    ): number;
+    export function getMaxListeners(emitterOrTarget: EventEmitter | EventTarget): number;
+    export function setMaxListeners(
+      n?: number,
+      ...eventTargets: Array<EventEmitter | EventTarget>
+    ): void;
+    /* An EventEmitter's listeners are functions, so their array is
+     * statically consumable. An EventTarget's listeners come back as
+     * registered (Node's `Function[]`): a listener object with
+     * handleEvent is itself, not a function, so that array's elements
+     * stay checked-dynamic. */
+    export function getEventListeners(
+      emitter: EventEmitter,
+      name: string | symbol,
+    ): Array<() => void>;
+    export function getEventListeners(
+      emitterOrTarget: EventEmitter | EventTarget,
+      name: string | symbol,
+    ): Array<any>;
   }
   export = EventEmitter;
 }

package/ambient/node-fallback/fs-promises.d.ts

@@ -210,7 +210,7 @@ declare module "fs/promises" {
   export function access(path: string | URL, mode?: number): Promise<void>;
   export function truncate(path: string | URL, len?: number): Promise<void>;
   export function appendFile(path: string | URL, data: string | Uint8Array): Promise<void>;
-  export function copyFile(src: string | URL, dest: string | URL): Promise<void>;
+  export function copyFile(src: string | URL, dest: string | URL, mode?: number): Promise<void>;
   export function mkdtemp(prefix: string | URL): Promise<string>;
   export function rmdir(path: string | URL): Promise<void>;
   export function rename(oldPath: string | URL, newPath: string | URL): Promise<void>;

package/ambient/node-fallback/fs.d.ts

@@ -30,8 +30,10 @@ declare module "node:fs" {
   export function writeFileSync(
     path: string | URL,
     data: string,
-    /* The options-record stance (see http.RequestOptions): flag fences
-     * by name at the call site; undocumented keys drop like Node. */
+    /* The options-record stance (see http.RequestOptions): an unsupported
+     * flag fences by name at the call site; undocumented keys drop like
+     * Node. The lowered flags are "w" (truncate-or-create) and "wx"
+     * (exclusive create). */
     options?: {
       mode?: number;
       encoding?: "utf8" | "utf-8";
@@ -157,9 +159,11 @@ declare module "node:fs" {
   export function lchownSync(path: string | URL, uid: number, gid: number): void;
   export function fchownSync(fd: number, uid: number, gid: number): void;
   export function truncateSync(path: string | URL, len?: number): void;
-  /* The 2-argument form only (Node's mode flags have no lowering). The
-   * destination is created or truncated carrying the SOURCE's mode. */
-  export function copyFileSync(src: string | URL, dest: string | URL): void;
+  /* The destination is created or truncated carrying the SOURCE's mode.
+   * `mode` is libuv's copyfile flag bits: COPYFILE_EXCL (1) fails when the
+   * destination exists, COPYFILE_FICLONE (2) requests a reflink and falls
+   * back to a copy, COPYFILE_FICLONE_FORCE (4) requires one. */
+  export function copyFileSync(src: string | URL, dest: string | URL, mode?: number): void;
   export function rename(
     oldPath: string,
     newPath: string,
@@ -467,8 +471,9 @@ declare module "node:fs" {
   ): BigIntStats;
   export function lstatSync(path: string | URL, options: StatSyncOptions): Stats | undefined;
   /* The fd pair behind spawn's fd-stdio form: openSync(path, flags) →
-   * the raw fd. Numeric flags use an inline OR of the O_* constants. */
-  export function openSync(path: string | URL, flags: string): number;
+   * the raw fd. Numeric flags use an inline OR of the O_* constants. The
+   * mode is open(2)'s creation mode and applies to both flag forms. */
+  export function openSync(path: string | URL, flags: string, mode?: number): number;
   export function openSync(path: string | URL, flags: number, mode?: number): number;
   export function closeSync(fd: number): void;
   export function fdatasyncSync(fd: number): void;
@@ -604,11 +609,29 @@ declare module "node:fs" {
   ): void;
   /* fs.watch — the file-watching slice (scr_watch.c, kqueue EVFILT_VNODE):
    * "rename"/"change" events on ONE path, watcher.close() to stop. The
-   * listener takes zero parameters or the eventType string (the filename
-   * parameter has no lowering); an open watcher keeps the loop alive. A
-   * path that cannot be opened THROWS Node's fs error synchronously. */
+   * listener takes (), (eventType) or (eventType, filename); an open
+   * watcher keeps the loop alive. A path that cannot be opened THROWS
+   * Node's fs error synchronously. */
+  export type WatchEventType = "rename" | "change";
+  /* (eventType, filename): filename is the changed entry's name (null when
+   * the platform does not provide one). */
+  export type WatchListener<T> = (event: WatchEventType, filename: T | null) => void;
   export interface FSWatcher {
     close(): void;
+    on(event: "change", listener: (eventType: string, filename: string | Buffer) => void): this;
+    on(event: "error", listener: (error: Error) => void): this;
+    on(event: "close", listener: () => void): this;
+    once(event: "change", listener: (eventType: string, filename: string | Buffer) => void): this;
+    once(event: "error", listener: (error: Error) => void): this;
+    once(event: "close", listener: () => void): this;
+    addListener(
+      event: "change",
+      listener: (eventType: string, filename: string | Buffer) => void,
+    ): this;
+    addListener(event: "error", listener: (error: Error) => void): this;
+    addListener(event: "close", listener: () => void): this;
+    off(event: "change" | "error" | "close", listener: (...args: any[]) => void): this;
+    removeListener(event: "change" | "error" | "close", listener: (...args: any[]) => void): this;
   }
   /* The options-record stance (see http.RequestOptions): persistent: true,
    * recursive: false, and encoding: "utf8" state the lowered behavior and
@@ -620,12 +643,34 @@ declare module "node:fs" {
     encoding?: string;
     [option: string]: unknown;
   }
-  export function watch(path: string, listener?: (eventType: string) => void): FSWatcher;
+  export function watch(path: string, listener?: WatchListener<string>): FSWatcher;
   export function watch(
     path: string,
     options: WatchOptions,
-    listener?: (eventType: string) => void,
+    listener?: WatchListener<string>,
   ): FSWatcher;
+  /* fs.watchFile — stat polling (scr_watch_file.c, libuv's uv_fs_poll
+   * shape): the listener runs with (current, previous) Stats when a poll
+   * sees a difference, the first poll only records the baseline, and a
+   * path that cannot be stat'd polls as all-zero Stats. One poller per
+   * resolved path is shared by every listener on it. interval defaults to
+   * 5007 ms, persistent defaults to true; bigint: true (BigIntStats) has
+   * no lowering. The call is a statement: Node's StatWatcher has no
+   * lowering. */
+  export interface StatWatcher {}
+  export function watchFile(
+    filename: string,
+    options: { interval?: number; persistent?: boolean; bigint?: false },
+    listener: (current: Stats, previous: Stats) => void,
+  ): StatWatcher;
+  export function watchFile(
+    filename: string,
+    listener: (current: Stats, previous: Stats) => void,
+  ): StatWatcher;
+  export function unwatchFile(
+    filename: string,
+    listener?: (current: Stats, previous: Stats) => void,
+  ): void;
   /* fs.promises IS the fs/promises module (Node's rule) — the namespace-
    * import form `fs.promises.readFile(...)` lowers through the same
    * fs/promises table as `import { readFile } from "node:fs/promises"`. */

package/ambient/node-fallback/http.d.ts

@@ -70,6 +70,7 @@ declare module "http" {
     readonly httpVersion: string;
     readonly complete: boolean;
     readonly aborted: boolean;
+    readonly destroyed: boolean;
     readonly statusCode: number | undefined;
     readonly statusMessage: string | undefined;
     readonly socket: Socket;
@@ -110,6 +111,7 @@ declare module "http" {
     readonly finished: boolean;
     readonly writableFinished: boolean;
     readonly writableCorked: number;
+    readonly destroyed: boolean;
     readonly req: IncomingMessage;
     readonly socket: Socket | null;
     readonly connection: Socket | null;
@@ -133,7 +135,7 @@ declare module "http" {
     writeHead(statusCode: number, headers?: OutgoingHttpHeaders | string[]): ServerResponse;
     writeHead(
       statusCode: number,
-      statusMessage: string,
+      statusMessage?: string,
       headers?: OutgoingHttpHeaders | string[],
     ): ServerResponse;
     writeContinue(callback?: () => void): void;
@@ -263,31 +265,32 @@ declare module "http" {
     end(data?: string | Uint8Array): void;
     destroy(error?: Error): void;
     abort(): void;
-    on(event: "response", listener: (res: IncomingMessage) => void): void;
-    on(event: "socket", listener: (socket: Socket) => void): void;
+    on(event: "response", listener: (res: IncomingMessage) => void): this;
+    on(event: "socket", listener: (socket: Socket) => void): this;
     on(
       event: "upgrade",
       listener: (res: IncomingMessage, socket: Socket, head: Buffer) => void,
-    ): void;
-    on(event: "timeout" | "close" | "finish" | "abort" | "continue", listener: () => void): void;
-    on(event: "error", listener: (err: Error) => void): void;
-    /* addListener IS on (Node aliases them) — the suite spells both. */
-    addListener(event: "response", listener: (res: IncomingMessage) => void): void;
-    addListener(event: "socket", listener: (socket: Socket) => void): void;
+    ): this;
+    on(event: "timeout" | "close" | "finish" | "abort" | "continue", listener: () => void): this;
+    on(event: "error", listener: (err: Error) => void): this;
+    /* addListener IS on (Node aliases them) — the suite spells both. Each
+     * answers the request, as Node's does. */
+    addListener(event: "response", listener: (res: IncomingMessage) => void): this;
+    addListener(event: "socket", listener: (socket: Socket) => void): this;
     addListener(
       event: "upgrade",
       listener: (res: IncomingMessage, socket: Socket, head: Buffer) => void,
-    ): void;
-    addListener(event: "timeout" | "close" | "finish" | "abort", listener: () => void): void;
-    addListener(event: "error", listener: (err: Error) => void): void;
-    once(event: "response", listener: (res: IncomingMessage) => void): void;
-    once(event: "socket", listener: (socket: Socket) => void): void;
+    ): this;
+    addListener(event: "timeout" | "close" | "finish" | "abort", listener: () => void): this;
+    addListener(event: "error", listener: (err: Error) => void): this;
+    once(event: "response", listener: (res: IncomingMessage) => void): this;
+    once(event: "socket", listener: (socket: Socket) => void): this;
     once(
       event: "upgrade",
       listener: (res: IncomingMessage, socket: Socket, head: Buffer) => void,
-    ): void;
-    once(event: "timeout" | "close" | "finish" | "abort" | "continue", listener: () => void): void;
-    once(event: "error", listener: (err: Error) => void): void;
+    ): this;
+    once(event: "timeout" | "close" | "finish" | "abort" | "continue", listener: () => void): this;
+    once(event: "error", listener: (err: Error) => void): this;
   }
   export function createServer(
     requestListener?: (req: IncomingMessage, res: ServerResponse) => void,
@@ -308,13 +311,18 @@ declare module "http" {
    * `target` is a URL string or URL object (the spelling a from-scratch
    * client reaches for first — dialed directly, with a non-http scheme
    * an ERR_INVALID_PROTOCOL at runtime rather than a type error), or
-   * the options record. */
+   * the options record. A URL target's second argument is the response
+   * callback or the options value the runtime merges under the URL's
+   * fields (`request(url, options[, callback])`); the lowering tells
+   * the two apart by the argument's own type. */
   export function request(
     target: RequestOptions | string | URL,
+    optionsOrCallback?: RequestOptions | ((res: IncomingMessage) => void),
     callback?: (res: IncomingMessage) => void,
   ): ClientRequest;
   export function get(
     target: RequestOptions | string | URL,
+    optionsOrCallback?: RequestOptions | ((res: IncomingMessage) => void),
     callback?: (res: IncomingMessage) => void,
   ): ClientRequest;
   export function validateHeaderName(name: string, label?: string): void;

package/ambient/node-fallback/https.d.ts

@@ -41,15 +41,18 @@ declare module "https" {
     requestListener: (req: IncomingMessage, res: ServerResponse) => void,
   ): Server;
   /* One signature with a union first parameter, for the request-fn
-   * ternary's sake (see the http block). A URL target takes no options,
-   * which means Node's defaults — the certificate is verified against
+   * ternary's sake (see the http block). The URL target takes an
+   * optional options value the runtime merges under its fields; without
+   * one it takes Node's defaults — the certificate is verified against
    * the default trust anchors. */
   export function request(
     target: RequestOptions | string | URL,
+    optionsOrCallback?: RequestOptions | ((res: IncomingMessage) => void),
     callback?: (res: IncomingMessage) => void,
   ): ClientRequest;
   export function get(
     target: RequestOptions | string | URL,
+    optionsOrCallback?: RequestOptions | ((res: IncomingMessage) => void),
     callback?: (res: IncomingMessage) => void,
   ): ClientRequest;
 }

package/ambient/node-fallback/net.d.ts

@@ -178,6 +178,8 @@ declare module "net" {
     getConnections(callback: (error: Error | null, count: number) => void): Server;
     /* Node answers the server itself (`return this` chaining). */
     listen(port: number, callback?: () => void): Server;
+    /* No port: an arbitrary unused one. */
+    listen(callback?: () => void): Server;
     /* The positional bind address (the options form's host in argument
      * spelling). */
     listen(port: number, host: string, callback?: () => void): Server;
@@ -207,6 +209,8 @@ declare module "net" {
     on(event: "drop", listener: (data?: DropArgument) => void): void;
     on(event: "timeout", listener: (socket: Socket) => void): void;
     on(event: "error", listener: (err: Error) => void): void;
+    /* http servers: a request the parser rejects, or a connection error */
+    on(event: "clientError", listener: (err: Error, socket: Socket) => void): void;
     /* The WebSocket handover: fires INSTEAD of 'request' for
      * Connection: upgrade requests, with the raw socket + head bytes;
      * 'connect' is its twin for CONNECT requests (HTTP tunneling). */
@@ -231,6 +235,8 @@ declare module "net" {
     addListener(event: "drop", listener: (data?: DropArgument) => void): void;
     addListener(event: "timeout", listener: (socket: Socket) => void): void;
     addListener(event: "error", listener: (err: Error) => void): void;
+    /* http servers: a request the parser rejects, or a connection error */
+    addListener(event: "clientError", listener: (err: Error, socket: Socket) => void): void;
     addListener(
       event: "upgrade" | "connect",
       listener: (req: import("http").IncomingMessage, socket: Socket, head: Buffer) => void,
@@ -249,6 +255,8 @@ declare module "net" {
     once(event: "drop", listener: (data?: DropArgument) => void): void;
     once(event: "timeout", listener: (socket: Socket) => void): void;
     once(event: "error", listener: (err: Error) => void): void;
+    /* http servers: a request the parser rejects, or a connection error */
+    once(event: "clientError", listener: (err: Error, socket: Socket) => void): void;
     once(
       event: "upgrade" | "connect",
       listener: (req: import("http").IncomingMessage, socket: Socket, head: Buffer) => void,
@@ -257,6 +265,23 @@ declare module "net" {
       event: "request" | "checkContinue" | "checkExpectation",
       listener: (req: import("http").IncomingMessage, res: import("http").ServerResponse) => void,
     ): void;
+    /* off / removeListener: the LAST listener standing for the same
+     * function leaves that event's list (Node's EventEmitter order). The
+     * server registries that keep a removable list: error, close,
+     * listening, connection/secureConnection, timeout, and drop. */
+    off(event: "error", listener: (err: Error) => void): void;
+    off(event: "close" | "listening", listener: () => void): void;
+    off(event: "connection" | "secureConnection", listener: (socket: Socket) => void): void;
+    off(event: "timeout", listener: (socket: Socket) => void): void;
+    off(event: "drop", listener: (data?: DropArgument) => void): void;
+    removeListener(event: "error", listener: (err: Error) => void): void;
+    removeListener(event: "close" | "listening", listener: () => void): void;
+    removeListener(
+      event: "connection" | "secureConnection",
+      listener: (socket: Socket) => void,
+    ): void;
+    removeListener(event: "timeout", listener: (socket: Socket) => void): void;
+    removeListener(event: "drop", listener: (data?: DropArgument) => void): void;
   }
   /* The 'drop' payload: the turned-away connection's addresses. */
   export interface DropArgument {

package/ambient/node-fallback/os.d.ts

@@ -27,7 +27,17 @@ declare module "os" {
     shell: string | null;
     homedir: string;
   }
-  export function userInfo(): UserInfo;
+  /* userInfo({ encoding: 'buffer' }): the same passwd fields with the
+   * three strings as Buffers (Node's own switch on the encoding). */
+  export interface BufferUserInfo {
+    username: Buffer;
+    uid: number;
+    gid: number;
+    shell: Buffer;
+    homedir: Buffer;
+  }
+  export function userInfo(options: { encoding: "buffer" }): BufferUserInfo;
+  export function userInfo(options?: { encoding?: string }): UserInfo;
   /* The TARGET platform's line terminator (a compile-time constant:
    * "\r\n" under a win32 triple, "\n" everywhere else). */
   export const EOL: "\r\n" | "\n";

package/ambient/node-fallback/path-posix.d.ts

@@ -13,8 +13,14 @@ declare module "path/posix" {
   export function matchesGlob(path: string, pattern: string): boolean;
   export function parse(path: string): import("path").ParsedPath;
   export function format(pathObject: import("path").FormatInputPathObject): string;
+  /* Node's deprecated alias of toNamespacedPath (identity on posix). */
+  export function _makeLong(path: string): string;
   export const sep: "/";
   export const delimiter: ":";
+  /* Node's posix object carries the other namespace too (the same object
+   * require("path/posix") answers). */
+  export const posix: typeof import("path/posix");
+  export const win32: typeof import("path/win32");
 }
 
 declare module "node:path/posix" {

package/ambient/node-fallback/path-win32.d.ts

@@ -13,8 +13,13 @@ declare module "path/win32" {
   export function matchesGlob(path: string, pattern: string): boolean;
   export function parse(path: string): import("path").ParsedPath;
   export function format(pathObject: import("path").FormatInputPathObject): string;
+  /* Node's deprecated alias of toNamespacedPath. */
+  export function _makeLong(path: string): string;
   export const sep: "\\";
   export const delimiter: ";";
+  /* Node's win32 object carries the other namespace too. */
+  export const posix: typeof import("path/posix");
+  export const win32: typeof import("path/win32");
 }
 
 declare module "node:path/win32" {

package/ambient/node-fallback/path.d.ts

@@ -16,6 +16,8 @@ declare module "path" {
   export function isAbsolute(path: string): boolean;
   export function relative(from: string, to: string): string;
   export function toNamespacedPath(path: string): string;
+  /* Node's deprecated alias of toNamespacedPath (POSIX identity). */
+  export function _makeLong(path: string): string;
   /* matchesGlob() is Node's glob matcher: brace expansion, extglobs, POSIX
    * classes and the ** and dot rules. */
   export function matchesGlob(path: string, pattern: string): boolean;

package/ambient/node-fallback/querystring.d.ts

@@ -6,9 +6,9 @@
  * stringify serializes string/number/boolean values and arrays of those
  * (Node's rules: arrays expand to repeated keys, null/undefined and
  * anything else serialize as the empty value). The maxKeys option lowers
- * (0 removes the cap, Node's rule); the custom encoder/decoder options
- * typecheck under the options-record stance and fence by name at the
- * call. decode/encode are Node's own aliases of parse/stringify. */
+ * (0 removes the cap, Node's rule), and so do the custom encoder and
+ * decoder options. decode/encode are Node's own aliases of
+ * parse/stringify. */
 declare module "querystring" {
   export interface ParseOptions {
     maxKeys?: number;