@gjsify/utils 0.36.0 → 0.37.0

package/lib/types/callable.d.ts

@@ -1,29 +1,21 @@
 /**
- * Wrap an ES6 class so it supports both the modern `new Cls(...)` pattern and
- * the legacy `Cls.call(thisArg, ...)` / `Cls(...)` (no-`new`) patterns.
+ * Wrap an ES6 class so it supports `new Cls(...)`, `Cls.call(thisArg, ...)` and
+ * `Cls(...)` (no-`new`) alike.
  *
  * The `apply` trap has two modes:
  *
- *  1. **`Cls.call(thisArg, ...)`** — a real consumer instance is provided.
- *     We materialise a temporary instance via `Reflect.construct` (so field
- *     initializers and constructor bodies run normally) and transplant its
- *     own property descriptors onto `thisArg`. This is how Node-era CJS
- *     consumers + `util.inherits(Sub, Cls)` chains expect to subclass our
- *     ES6 classes.
+ *  1. **`Cls.call(thisArg, ...)`** — materialise a temporary instance via
+ *     `Reflect.construct` (so field initializers and constructor bodies run) and
+ *     transplant its own property descriptors onto `thisArg`.
  *
- *  2. **`Cls(...)`** (called as a plain function — `thisArg` is `undefined`
- *     in strict mode or `globalThis` in sloppy mode) — we treat the call as
- *     a constructor call and return a fresh `new Cls(...)`. Node's stream
- *     constructors implement this guard explicitly:
- *       `if (!(this instanceof PassThrough)) return new PassThrough(...)`
- *     so consumers like `merge2` invoke `Stream.PassThrough(opts)` without
- *     `new` and rely on the result being a real instance. Without this
- *     branch the apply trap would crash with "undefined is not a non-null
- *     object" when it tried to `Object.defineProperty(thisArg, …)`.
+ *  2. **`Cls(...)`** — `thisArg` is `undefined` (strict) or `globalThis`
+ *     (sloppy); construct instead. Node's stream constructors guard this
+ *     explicitly (`if (!(this instanceof PassThrough)) return new PassThrough(…)`)
+ *     and consumers like `merge2` rely on it. Without this branch the trap
+ *     crashes on `Object.defineProperty(thisArg, …)`.
  *
- * The default Proxy traps pass `construct`, `get` and `getPrototypeOf`
- * straight through, so `new Wrapped()`, `Wrapped.prototype` (consulted by
- * `util.inherits`) and `instance instanceof Wrapped` all behave identically
- * to the underlying class.
+ * `construct`, `get` and `getPrototypeOf` pass straight through, so
+ * `Wrapped.prototype` (consulted by `util.inherits`) and `instanceof` behave
+ * exactly as on the underlying class.
  */
 export declare function makeCallable<T extends new (...args: unknown[]) => unknown>(Cls: T): T;

package/lib/types/error.d.ts

@@ -1,6 +1,5 @@
 /**
- * Defines the static Error.captureStackTrace method,
- * this is not present in SpiderMonkey because it comes from V8
+ * Installs the V8-only static `Error.captureStackTrace` on engines that lack it.
  * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error#static_methods
  * @see https://nodejs.org/dist/latest-v18.x/docs/api/errors.html#errorcapturestacktracetargetobject-constructoropt
  */

package/lib/types/fs.d.ts

@@ -1,3 +1,3 @@
-/** Check if a file descriptor exists */
+/** Is `fd` open? Probed by wrapping it, as GLib has no file-descriptor test. */
 export declare const existsFD: (fd: number) => boolean;
 export declare function existsSync(path: string): boolean;

package/lib/types/gio-errors.d.ts

@@ -1,4 +1,13 @@
-/** Map from Gio.IOErrorEnum numeric values to Node.js error code strings. */
+/**
+ * Gio.IOErrorEnum numeric value → Node error code.
+ *
+ * The trailing name on each row is the member that number ACTUALLY has, checked
+ * against `Gio.IOErrorEnum` on gjs 1.88.1; GLib's numbering is append-only, so it
+ * does not drift with the GIR version. Several rows pair a member with an errno that
+ * does not follow from it (12 is NO_SPACE yet maps to ELOOP, 24 is TIMED_OUT yet maps
+ * to EROFS, 31 is TOO_MANY_OPEN_FILES yet maps to ENETUNREACH): those are wrong
+ * mappings to repair, not aliases — do not "correct" the name back.
+ */
 export declare const GIO_ERROR_TO_NODE: Record<number, string>;
 export interface NodeErrorDetails {
     path?: string;

package/lib/types/gio.d.ts

@@ -8,16 +8,9 @@ import Gio from '@girs/gio-2.0';
 export declare function gioAsync<T>(obj: any, asyncMethod: string, finishMethod: string, ...args: any[]): Promise<T>;
 /**
  * Promise wrapper around `Gio.InputStream.read_bytes_async` / `read_bytes_finish`.
- * Returns a `Uint8Array` or `null` if the end of the stream is reached.
- *
- * Treats `G_IO_ERROR_PARTIAL_INPUT` as EOF: Soup3's chunked-decoding input
- * stream surfaces this when the upstream closes the connection cleanly at a
- * non-chunk boundary (common on the npm registry CDN). Without this, the
- * fetch `Body.text()` path raises "Invalid response body" mid-read even
- * though the full payload has already arrived. Bubble all other errors.
+ * `null` means end of stream; a clean-stream-end error counts as EOF (see the catch),
+ * everything else is bubbled.
  */
 export declare function readBytesAsync(inputStream: Gio.InputStream, count?: number, ioPriority?: number, cancellable?: Gio.Cancellable | null): Promise<Uint8Array | null>;
-/**
- * Async generator that yields `Uint8Array` chunks from a `Gio.InputStream`.
- */
+/** Yields `Uint8Array` chunks from a `Gio.InputStream` until EOF. */
 export declare function inputStreamAsyncIterator(inputStream: Gio.InputStream, count?: number, ioPriority?: number, cancellable?: Gio.Cancellable | null): AsyncGenerator<Uint8Array>;

package/lib/types/globals.d.ts

@@ -1,5 +1,5 @@
 /**
- * Register a value as a global property if it doesn't already exist.
- * This is a no-op in environments where the global is already defined (e.g. Node.js).
+ * Register `value` as a global only where that name is still free, so a web polyfill
+ * never displaces a host implementation that is already there.
  */
 export declare function registerGlobal(name: string, value: unknown): void;

package/lib/types/host-os.d.ts

@@ -2,26 +2,22 @@ import type { ProcessPlatform } from './platform-names.js';
 /**
  * The three operating systems ADR 0018 declares as the project's target set.
  *
- * Deliberately NARROWER than {@link ProcessPlatform}, which is Node's full
- * vocabulary. `gjsify.os` keys are exactly these three: a package may not
- * declare support for an OS the project does not claim, and `os-axis` fails on
- * a key outside this set. The emulated `linux-{ppc64,s390x,riscv64}` targets
- * are build-verified only and are an ARCH question, not an OS one — they live
- * on the `gjsify.platforms` axis, which stays separate by design.
+ * Deliberately narrower than {@link ProcessPlatform} (Node's full vocabulary):
+ * `gjsify.os` keys are exactly these three and `os-axis` fails on any other key.
+ * The emulated `linux-{ppc64,s390x,riscv64}` targets are an ARCH question and
+ * live on the separate `gjsify.platforms` axis.
  */
 export type TargetOs = 'linux' | 'darwin' | 'win32';
-/** The target set as data, so a check iterates it instead of restating it. */
+/** The target set as data, for checks that iterate it. */
 export declare const TARGET_OSES: readonly TargetOs[];
 /** Is `value` one of the three declared target operating systems? */
 export declare function isTargetOs(value: unknown): value is TargetOs;
 /**
  * The host's `process.platform`, or `undefined` where nothing answers.
  *
- * `undefined` is the honest result on a runtime with no process object (the
- * browser), and callers must treat it as "unknown", never as "not Windows" —
- * which is why this returns an optional rather than defaulting to `'linux'`.
- * The defaulting belongs to `@gjsify/process`'s `detectPlatform()`, which has a
- * uname probe to fall back ON; this module has none and must not pretend.
+ * Callers must treat `undefined` as "unknown", never as "not Windows". Nothing is
+ * defaulted here because this module has no uname probe to fall back on; that
+ * defaulting belongs to `@gjsify/process`'s `detectPlatform()`.
  */
 export declare function hostPlatform(): ProcessPlatform | undefined;
 /**
@@ -32,9 +28,9 @@ export declare function hostOs(): TargetOs | undefined;
 /**
  * Running on Windows?
  *
- * The predicate `it.failing(name, fn, reason, { when: isWin32() })` takes — the
- * sanctioned way to carry a POSIX-only assertion through a win32 run without
- * weakening it, and without an `if (platform)` guard that would hide it forever.
+ * The predicate for `it.failing(name, fn, reason, { when: isWin32() })` — the
+ * sanctioned way to park a POSIX-only assertion on a win32 run, instead of an
+ * `if (platform)` guard that would hide it forever.
  */
 export declare function isWin32(): boolean;
 /** Running on macOS? */

package/lib/types/host-process.d.ts

@@ -1,7 +1,9 @@
 /** Does this host have a readable procfs for the current process? */
 export declare function hasProcfs(): boolean;
 /**
- * This process's own pid, or `undefined` where nothing can answer.
+ * This process's own pid, or `undefined` where nothing can answer. Never `0` —
+ * that is a real pid, and returning it as "unknown" hands the caller a number
+ * that looks answered.
  *
  * Two readers, capability-selected:
  *
@@ -9,12 +11,8 @@ export declare function hasProcfs(): boolean;
  *      subprocess.
  *   2. `sh -c 'echo $PPID'` — the shell's PARENT is us, because
  *      `g_spawn_command_line_sync()` forks this process and execs the shell in
- *      the child. This is the same trick `@gjsify/v8`'s darwin heap reader has
- *      used since it was written, and it is portable to every POSIX host that
- *      has no procfs.
- *
- * Never `0`. `0` is a real pid, so returning it as "unknown" would hand every
- * caller a number that looks answered.
+ *      the child (same trick as `@gjsify/v8`'s darwin heap reader; portable to
+ *      every POSIX host without procfs).
  */
 export declare function hostPid(): number | undefined;
 /**
@@ -30,20 +28,17 @@ export declare function hostPpid(): number | undefined;
  * The absolute path of the INTERPRETER running this process — what Node calls
  * `process.execPath` — or `undefined` where nothing can answer.
  *
- * NOT `imports.system.programInvocationName`. That is the SCRIPT, and reporting
- * it as `execPath` is a defect with teeth: `spawn(process.execPath, […])` is the
- * documented portable way to start a second copy of the current runtime, and
- * against a script path it fails `ENOENT` — or worse, `g_spawn` retries a
- * non-executable text file through `/bin/sh` and the shell begins interpreting
- * a bundle.
+ * NOT `imports.system.programInvocationName`: that is the SCRIPT, and reporting it
+ * as `execPath` breaks `spawn(process.execPath, […])` — the portable way to start
+ * a second copy of the runtime — with `ENOENT`, or worse, `g_spawn` retries the
+ * non-executable text file through `/bin/sh` and the shell interprets a bundle.
  *
  *   1. `/proc/self/exe` — a symlink to the running binary, exact by
  *      construction.
- *   2. `g_find_program_in_path(g_get_prgname())` — the PATH lookup for the name
- *      this process was invoked under (`gjs`). Honest but not exact: a host with
- *      two gjs installations can resolve the other one. That is why it is the
- *      fallback and not the primary, and why nothing here defaults to a
- *      hardcoded `/usr/bin/gjs` — a path that does not exist on macOS at all.
+ *   2. `g_find_program_in_path(g_get_prgname())` — honest but not exact, since a
+ *      host with two gjs installations can resolve the other one; hence the
+ *      fallback position. Nothing defaults to a hardcoded `/usr/bin/gjs`, a path
+ *      that does not exist on macOS at all.
  */
 export declare function hostExecPath(): string | undefined;
 /** The OS's view of a process's memory, in bytes. */
@@ -60,11 +55,9 @@ export interface ProcessMemory {
 /**
  * This process's memory figures, or `null` when no reader applies.
  *
- * DEGRADED CONTRACT off procfs: `ps(1)` reports only `rss` and `vsz`, so `data`
- * and `peak` stay `0` there. That is the same shape the Linux reader already
- * produced for a procfs it could not parse, so no consumer meets a new one —
- * but it is a real difference and `@gjsify/v8` documents it in
- * `getHeapStatistics()`'s own contract.
+ * Degraded off procfs: `ps(1)` reports only `rss` and `vsz`, so `data` and `peak`
+ * stay `0` — the same shape the Linux reader already produced for a procfs it
+ * could not parse.
  *
  * Both `ps` columns are in KiB on Linux and on macOS (POSIX mandates KiB for
  * `rss`; BSD `vsz` follows), so one multiply serves both.

package/lib/types/main-loop.d.ts

@@ -1,4 +1,21 @@
 import type GLib from '@girs/glib-2.0';
+/**
+ * Ensure a GLib MainLoop is running for async I/O dispatch (Soup.Server,
+ * Gio.SocketService, …). No-op on Node.js. Idempotent.
+ *
+ * Called automatically by `http.Server.listen()`, `net.Server.listen()`,
+ * `dgram.Socket.bind()`. GTK apps must NOT call it — they use
+ * `Gtk.Application.runAsync()` instead.
+ *
+ * Teardown hazard: with a main-loop hook set, GJS's `eval_module` drives the
+ * hook's *blocking* `loop.run()`, so terminating from an async continuation with
+ * a bare `imports.system.exit()` DEADLOCKS — it only sets GJS's internal exit
+ * flag, never calls `loop.quit()`, so the parked `loop.run()` never returns.
+ * Microtask draining is unaffected; only the exit hangs
+ * (`docs/poc/tla-microtask-draining.md`). Exit through `process.exit()` (which
+ * idle-schedules `quitMainLoop()` + `system.exit()`) or call {@link quitMainLoop}
+ * yourself first.
+ */
 export declare function ensureMainLoop(): GLib.MainLoop | undefined;
 /**
  * Quit the MainLoop created by `ensureMainLoop()`. Idempotent, no-op on Node.js.

package/lib/types/next-tick.d.ts

@@ -1,8 +1,7 @@
 /** @internal Test helper: reset burst state. */
 export declare function __resetBurstStateForTests(): void;
 /**
- * Schedule a function on the next turn of the event loop.
- * On GJS: uses GLib.timeout_add(PRIORITY_DEFAULT, delay=0).
- * On Node.js: uses process.nextTick → queueMicrotask → Promise.resolve().then().
+ * Schedule a function on the next turn of the event loop: the burst-yield drainer on
+ * GJS, otherwise `process.nextTick` → `queueMicrotask` → `Promise.resolve().then()`.
  */
 export declare const nextTick: (fn: (...args: unknown[]) => void, ...args: unknown[]) => void;

package/lib/types/structured-clone.d.ts

@@ -1,22 +1,15 @@
 /**
  * structuredClone polyfill implementing the HTML structured clone algorithm.
  *
- * Supports: primitives (incl. -0, NaN, Infinity, BigInt), wrapper objects,
- * Date, RegExp, Error types, ArrayBuffer (with transfer), TypedArrays,
- * DataView, Map, Set, Blob, File, circular/shared references, plain objects
- * and arrays.
+ * Throws DataCloneError for functions, symbols, WeakMap, WeakSet, WeakRef and
+ * Promise; everything else the spec covers is cloned, circular and shared
+ * references included.
  *
- * Throws DataCloneError for: functions, symbols, WeakMap, WeakSet, WeakRef, Promise.
- *
- * Transfer semantics: any `ArrayBuffer` listed in `options.transfer` is
- * transferred to the clone via SM140's `ArrayBuffer.prototype.transfer()`
- * (zero-copy, sender becomes detached). Non-`ArrayBuffer` entries are
- * accepted but ignored — the caller (e.g. `MessagePort.postMessage`) is
- * responsible for handling transferable objects that aren't structured-clone
- * primitives (`MessagePort`, `ReadableStream`, …).
- *
- * @param value The value to clone
- * @param options Optional transfer list
+ * An `ArrayBuffer` in `options.transfer` is moved zero-copy via
+ * `ArrayBuffer.prototype.transfer()` and the sender's buffer becomes detached.
+ * Non-`ArrayBuffer` entries are accepted but IGNORED: transferables that are not
+ * structured-clone primitives (`MessagePort`, `ReadableStream`, …) are the caller's
+ * responsibility, e.g. `MessagePort.postMessage`.
  */
 export declare function structuredClone<T>(value: T, options?: {
     transfer?: unknown[];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/utils",
-    "version": "0.36.0",
+    "version": "0.37.0",
     "description": "Utils module for gjsify",
     "module": "lib/esm/index.js",
     "types": "lib/types/index.d.ts",
@@ -40,7 +40,7 @@
         "fs"
     ],
     "devDependencies": {
-        "@gjsify/cli": "^0.36.0",
+        "@gjsify/cli": "^0.37.0",
         "typescript": "^6.0.3"
     },
     "dependencies": {