homebridge-plugin-utils 1.35.0 → 2.1.0

package/dist/clock-double.d.ts

@@ -0,0 +1,93 @@
+/**
+ * A reusable, controllable {@link Clock} test double.
+ *
+ * The {@link Clock} seam in `clock.ts` exists so a consuming plugin's time-dependent code can be driven without real wall-clock waits. This module ships the fake that
+ * cashes that in: a {@link TestClock} over a virtual timeline a test advances explicitly. `now()` returns the virtual time; `delay()` registers a pending wait that
+ * resolves only when {@link TestClock.advance} crosses its deadline, or rejects when its signal aborts - matching `node:timers/promises` `setTimeout`'s `AbortError`
+ * shape. No real timers and no wall-clock are used, so a consumer's pacing/timeout/duration path runs deterministically and instantly under test.
+ *
+ * The double builds on the library's own primitives rather than hand-rolling them: {@link onAbort} wires the abort listener and yields the `Disposable` that detaches
+ * it, and `Promise.withResolvers` captures each pending wait's deferred. The abort listener is detached on EITHER resolution path (deadline-crossed or aborted), so no
+ * listener leaks onto a long-lived signal across many short waits.
+ *
+ * @module
+ */
+import type { Clock } from "./clock.ts";
+/**
+ * A controllable {@link Clock} double over virtual time. `now()` returns the current virtual time; `delay()` registers a pending wait that resolves only when
+ * {@link TestClock.advance} crosses its deadline (in ascending-deadline order), or rejects with an `AbortError` (matching `node:timers/promises` `setTimeout` - `name`
+ * `"AbortError"`, `code` `"ABORT_ERR"`, NOT the signal's reason) when its signal aborts. No real timers or wall-clock are used.
+ *
+ * The virtual time is a RELATIVE timeline seeded at `start` (default `0`), NOT real epoch milliseconds. A consumer that compares `now()` against an absolute real-epoch
+ * constant would diverge; consumers must only compare `now()` values to each other (deriving elapsed intervals from differences), which is the only use a
+ * `Date.now()`-style read serves in the consuming pacing path - all its time reads come from the one injected clock.
+ *
+ * @example
+ *
+ * ```ts
+ * import { TestClock } from "homebridge-plugin-utils";
+ *
+ * const clock = new TestClock();
+ *
+ * const waited = clock.delay(100);
+ *
+ * // Nothing resolves until virtual time crosses the deadline.
+ * clock.advance(100);
+ *
+ * await waited;
+ * ```
+ *
+ * @see Clock
+ *
+ * @category Testing
+ */
+export declare class TestClock implements Clock {
+    #private;
+    /**
+     * Construct a clock seeded at `start` (default `0`). The seed is the initial value `now()` returns; `advance` moves it forward (or back, for a negative delta).
+     *
+     * @param start - The initial virtual time, in the consumer's relative timeline. Defaults to `0`.
+     */
+    constructor(start?: number);
+    /**
+     * Advance virtual time by `ms` and resolve every delay whose deadline the new time has reached. The delta is applied regardless of sign, so a negative `ms` moves time
+     * backward; `advance(0)` moves time nowhere but STILL flushes any already-due entry (a `delay(0)` or a `delay` with a non-positive `ms`), so a zero or negative delay
+     * is never a lost wakeup.
+     *
+     * Due entries resolve in ASCENDING deadline order; entries that share a deadline keep their FIFO registration order, because the snapshot is taken before any removal
+     * and the numeric sort is stable - matching how `setTimeout` fires equal-deadline timers in scheduling order. Each due entry is removed by identity and has its abort
+     * listener detached before it resolves, so the resolve path leaks no listener and the iteration is immune to the index shifts a forward in-place splice would cause.
+     *
+     * @param ms - The amount of virtual time to advance, in milliseconds. May be zero or negative.
+     */
+    advance(ms: number): void;
+    /**
+     * Register a delay that resolves when virtual time reaches `this.now() + ms`, or rejects with an `AbortError` (matching `node:timers/promises`) if `init.signal` aborts
+     * first. A non-positive `ms` yields a deadline at or before the current time, which the very next {@link TestClock.advance} (including `advance(0)`) flushes.
+     *
+     * A pre-aborted signal rejects on the executor's microtask exactly as `systemClock` does (NOT a synchronous throw): {@link onAbort} fires the handler inline, which
+     * removes the just-registered entry and rejects, so the entry never lingers in `pending`.
+     *
+     * @param ms   - The delay, in milliseconds. May be zero or negative (flushed by the next `advance`).
+     * @param init - Optional init options. A supplied `signal` rejects the wait with an `AbortError` when it aborts.
+     *
+     * @returns A promise that resolves when the deadline is crossed, or rejects with an `AbortError` if the signal aborts first.
+     */
+    delay(ms: number, init?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Return the current virtual time. Compare these values to each other to derive elapsed intervals - they are a relative timeline, not real epoch milliseconds.
+     *
+     * @returns The current virtual time.
+     */
+    now(): number;
+    /**
+     * The number of registered delays that have neither resolved nor rejected. A test reads this to assert a consumer registered its waits and later cleared them (no
+     * leak).
+     *
+     * @returns The count of unsettled delays.
+     */
+    get pending(): number;
+}
+//# sourceMappingURL=clock-double.d.ts.map

package/dist/clock-double.js

@@ -0,0 +1,141 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * clock-double.ts: A reusable, controllable Clock test double - virtual time a test advances explicitly - for the injectable Clock seam in clock.ts.
+ */
+import { onAbort } from "./util.js";
+/**
+ * Construct the rejection a {@link TestClock} `delay` produces when its signal aborts, matching `node:timers/promises` `setTimeout` exactly: a plain `Error` whose `name`
+ * is `"AbortError"` and whose `code` is the STRING `"ABORT_ERR"`. The real primitive's rejection is a dedicated internal class (not a `DOMException`, whose `code` is the
+ * numeric `20`, and there is no constructable `AbortError` global), so the double cannot match the constructor or prototype identity - it matches the observable `name`
+ * and `code` a consumer branches on, which is the contract that matters.
+ *
+ * @returns The `AbortError`-shaped rejection.
+ */
+function abortError() {
+    const error = new Error("The operation was aborted");
+    error.name = "AbortError";
+    // `code` is not a standard `Error` field, so assign it through an indexed widening rather than declaring a one-off subclass. The STRING value is what the real
+    // `node:timers/promises` rejection carries and what a consumer's `error.code === "ABORT_ERR"` check reads.
+    error.code = "ABORT_ERR";
+    return error;
+}
+/**
+ * A controllable {@link Clock} double over virtual time. `now()` returns the current virtual time; `delay()` registers a pending wait that resolves only when
+ * {@link TestClock.advance} crosses its deadline (in ascending-deadline order), or rejects with an `AbortError` (matching `node:timers/promises` `setTimeout` - `name`
+ * `"AbortError"`, `code` `"ABORT_ERR"`, NOT the signal's reason) when its signal aborts. No real timers or wall-clock are used.
+ *
+ * The virtual time is a RELATIVE timeline seeded at `start` (default `0`), NOT real epoch milliseconds. A consumer that compares `now()` against an absolute real-epoch
+ * constant would diverge; consumers must only compare `now()` values to each other (deriving elapsed intervals from differences), which is the only use a
+ * `Date.now()`-style read serves in the consuming pacing path - all its time reads come from the one injected clock.
+ *
+ * @example
+ *
+ * ```ts
+ * import { TestClock } from "homebridge-plugin-utils";
+ *
+ * const clock = new TestClock();
+ *
+ * const waited = clock.delay(100);
+ *
+ * // Nothing resolves until virtual time crosses the deadline.
+ * clock.advance(100);
+ *
+ * await waited;
+ * ```
+ *
+ * @see Clock
+ *
+ * @category Testing
+ */
+export class TestClock {
+    // The current virtual time. Seeded by the constructor and moved only by `advance`.
+    #now;
+    // The registered, not-yet-settled delays. An entry leaves this list exactly once - either when `advance` crosses its deadline or when its signal aborts - via
+    // `#remove`, which splices by identity so a mixed resolve-and-abort sequence never strands or mis-removes an entry.
+    #pending = [];
+    /**
+     * Construct a clock seeded at `start` (default `0`). The seed is the initial value `now()` returns; `advance` moves it forward (or back, for a negative delta).
+     *
+     * @param start - The initial virtual time, in the consumer's relative timeline. Defaults to `0`.
+     */
+    constructor(start = 0) {
+        this.#now = start;
+    }
+    /**
+     * Advance virtual time by `ms` and resolve every delay whose deadline the new time has reached. The delta is applied regardless of sign, so a negative `ms` moves time
+     * backward; `advance(0)` moves time nowhere but STILL flushes any already-due entry (a `delay(0)` or a `delay` with a non-positive `ms`), so a zero or negative delay
+     * is never a lost wakeup.
+     *
+     * Due entries resolve in ASCENDING deadline order; entries that share a deadline keep their FIFO registration order, because the snapshot is taken before any removal
+     * and the numeric sort is stable - matching how `setTimeout` fires equal-deadline timers in scheduling order. Each due entry is removed by identity and has its abort
+     * listener detached before it resolves, so the resolve path leaks no listener and the iteration is immune to the index shifts a forward in-place splice would cause.
+     *
+     * @param ms - The amount of virtual time to advance, in milliseconds. May be zero or negative.
+     */
+    advance(ms) {
+        this.#now += ms;
+        // Snapshot the due entries BEFORE mutating `#pending`, then sort them into deadline order. Filtering off a live array while removing from it would shift indices and
+        // strand entries; the snapshot first decouples the iteration from the removal. The sort is a stable numeric comparator, so equal deadlines preserve FIFO order.
+        const due = this.#pending.filter((entry) => entry.deadline <= this.#now).sort((a, b) => a.deadline - b.deadline);
+        for (const entry of due) {
+            // Remove by identity first so a re-entrant observer sees the correct `pending` count, then detach the abort listener (present only when this delay had a signal) so
+            // the resolve path leaves no listener on a long-lived signal, then settle the caller's promise.
+            this.#remove(entry);
+            entry.dispose?.[Symbol.dispose]();
+            entry.resolve();
+        }
+    }
+    /**
+     * Register a delay that resolves when virtual time reaches `this.now() + ms`, or rejects with an `AbortError` (matching `node:timers/promises`) if `init.signal` aborts
+     * first. A non-positive `ms` yields a deadline at or before the current time, which the very next {@link TestClock.advance} (including `advance(0)`) flushes.
+     *
+     * A pre-aborted signal rejects on the executor's microtask exactly as `systemClock` does (NOT a synchronous throw): {@link onAbort} fires the handler inline, which
+     * removes the just-registered entry and rejects, so the entry never lingers in `pending`.
+     *
+     * @param ms   - The delay, in milliseconds. May be zero or negative (flushed by the next `advance`).
+     * @param init - Optional init options. A supplied `signal` rejects the wait with an `AbortError` when it aborts.
+     *
+     * @returns A promise that resolves when the deadline is crossed, or rejects with an `AbortError` if the signal aborts first.
+     */
+    delay(ms, init) {
+        const { promise, reject, resolve } = Promise.withResolvers();
+        const entry = { deadline: this.#now + ms, resolve };
+        // Register the entry FIRST so a pre-aborted signal's inline `onAbort` handler (below) can find and remove it. `onAbort` runs the handler synchronously when the
+        // signal is already aborted, so for a pre-aborted signal the entry is pushed and then immediately removed-and-rejected within this call - settling on the executor's
+        // microtask, identical to `systemClock`. When no signal is supplied, `dispose` stays undefined and the entry only ever leaves via `advance`.
+        this.#pending.push(entry);
+        if (init?.signal !== undefined) {
+            entry.dispose = onAbort(init.signal, () => {
+                this.#remove(entry);
+                reject(abortError());
+            });
+        }
+        return promise;
+    }
+    /**
+     * Return the current virtual time. Compare these values to each other to derive elapsed intervals - they are a relative timeline, not real epoch milliseconds.
+     *
+     * @returns The current virtual time.
+     */
+    now() {
+        return this.#now;
+    }
+    /**
+     * The number of registered delays that have neither resolved nor rejected. A test reads this to assert a consumer registered its waits and later cleared them (no
+     * leak).
+     *
+     * @returns The count of unsettled delays.
+     */
+    get pending() {
+        return this.#pending.length;
+    }
+    // Remove `entry` from `#pending` by identity. A guarded `indexOf` + `splice` makes a second removal (e.g. an abort that races a resolve) a safe no-op and
+    // never removes the wrong entry, so `#pending` stays consistent across any resolve-and-abort interleaving.
+    #remove(entry) {
+        const index = this.#pending.indexOf(entry);
+        if (index !== -1) {
+            this.#pending.splice(index, 1);
+        }
+    }
+}
+//# sourceMappingURL=clock-double.js.map

package/dist/clock-double.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock-double.js","sourceRoot":"","sources":["../src/clock-double.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAiBH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAcpC;;;;;;;GAOG;AACH,SAAS,UAAU;IAEjB,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAErD,KAAK,CAAC,IAAI,GAAG,YAAY,CAAC;IAE1B,+JAA+J;IAC/J,2GAA2G;IAC1G,KAAkC,CAAC,IAAI,GAAG,WAAW,CAAC;IAEvD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,OAAO,SAAS;IAEpB,mFAAmF;IACnF,IAAI,CAAS;IAEb,8JAA8J;IAC9J,oHAAoH;IAC3G,QAAQ,GAAiB,EAAE,CAAC;IAErC;;;;OAIG;IACH,YAAmB,KAAK,GAAG,CAAC;QAE1B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC;IACpB,CAAC;IAED;;;;;;;;;;OAUG;IACI,OAAO,CAAC,EAAU;QAEvB,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;QAEhB,qKAAqK;QACrK,gKAAgK;QAChK,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;QAEjH,KAAI,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;YAEvB,oKAAoK;YACpK,gGAAgG;YAChG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YACpB,KAAK,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;YAClC,KAAK,CAAC,OAAO,EAAE,CAAC;QAClB,CAAC;IACH,CAAC;IAED;;;;;;;;;;;OAWG;IACI,KAAK,CAAC,EAAU,EAAE,IAA+B;QAEtD,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,GAA+B,OAAO,CAAC,aAAa,EAAE,CAAC;QACzF,MAAM,KAAK,GAAe,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,GAAG,EAAE,EAAE,OAAO,EAAE,CAAC;QAEhE,gKAAgK;QAChK,qKAAqK;QACrK,6IAA6I;QAC7I,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAE1B,IAAG,IAAI,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;YAE9B,KAAK,CAAC,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE;gBAExC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;gBACpB,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;YACvB,CAAC,CAAC,CAAC;QACL,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACI,GAAG;QAER,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED;;;;;OAKG;IACH,IAAW,OAAO;QAEhB,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;IAC9B,CAAC;IAED,0JAA0J;IAC1J,2GAA2G;IAC3G,OAAO,CAAC,KAAiB;QAEvB,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAE3C,IAAG,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC;YAEhB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;CACF"}

package/dist/clock.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The injectable wall-clock contract: the platform time primitives time-dependent code reads. A consumer holds a `Clock` rather than calling `Date.now()` /
+ * `node:timers/promises` `setTimeout` directly, so a test can substitute a controllable double (`TestClock`) and drive time deterministically while production behavior
+ * stays unchanged through {@link systemClock}.
+ *
+ * @see systemClock
+ *
+ * @category Utilities
+ */
+export interface Clock {
+    /**
+     * Resolve after `ms` milliseconds, or reject if `init.signal` aborts first. The production {@link systemClock} implements this as `node:timers/promises` `setTimeout`,
+     * so an abort rejects with that primitive's `AbortError` (`name` `"AbortError"`, `code` `"ABORT_ERR"`) rather than the signal's reason.
+     *
+     * @param ms   - The delay, in milliseconds.
+     * @param init - Optional init options. `signal` cancels the delay - resolving the wait early with a rejection - when it aborts.
+     *
+     * @returns A promise that resolves after the delay, or rejects with an `AbortError` if the signal aborts first.
+     */
+    delay(ms: number, init?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Return the current time as epoch milliseconds. The production {@link systemClock} implements this as `Date.now()`.
+     *
+     * @returns The current time in epoch milliseconds.
+     */
+    now(): number;
+}
+/**
+ * The behavior-neutral production {@link Clock}: `now()` IS `Date.now()` and `delay()` IS `node:timers/promises` `setTimeout`. A consumer that routes its time reads
+ * through this clock instead of calling those primitives directly cannot observe any behavior change - it is the same two calls, one indirection removed at test time.
+ *
+ * @see Clock
+ *
+ * @category Utilities
+ */
+export declare const systemClock: Clock;
+//# sourceMappingURL=clock.d.ts.map

package/dist/clock.js

@@ -0,0 +1,34 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * clock.ts: An injectable wall-clock seam - the current time and an abortable delay - so time-dependent code can be driven deterministically under test.
+ */
+/**
+ * An injectable wall-clock time seam.
+ *
+ * Time-dependent code reads the platform time primitives it needs: the current epoch time (`Date.now()`) and a delay that can be cancelled (`node:timers/promises`
+ * `setTimeout`). Calling those directly bakes real wall-clock time into the code, so a test cannot exercise a pacing or timeout path without multi-second real waits, and
+ * `node:test`'s mock timers do not patch the `node:timers/promises` primitives. Holding a {@link Clock} instead - the abstraction over those primitives - inverts the
+ * dependency: production wires {@link systemClock}, whose `now()` IS `Date.now()` and whose `delay()` IS `node:timers/promises` `setTimeout`, so routing through the seam
+ * is behavior-neutral; a test wires a `TestClock` (see `clock-double.ts`) that advances virtual time explicitly, so the consumer's time-dependent path runs
+ * deterministically and instantly.
+ *
+ * This module imports `node:timers/promises` and is therefore Node-only (not browser-safe), like `util.ts`. A browser-targeted consumer cannot resolve that import.
+ *
+ * @module
+ */
+import { setTimeout as delay } from "node:timers/promises";
+/**
+ * The behavior-neutral production {@link Clock}: `now()` IS `Date.now()` and `delay()` IS `node:timers/promises` `setTimeout`. A consumer that routes its time reads
+ * through this clock instead of calling those primitives directly cannot observe any behavior change - it is the same two calls, one indirection removed at test time.
+ *
+ * @see Clock
+ *
+ * @category Utilities
+ */
+export const systemClock = {
+    // `setTimeout(ms, value, options)` from `node:timers/promises`: pass `undefined` for the resolution value and forward `init` as the options so the caller's signal
+    // cancels the wait. `setTimeout(ms, undefined, opts)` resolves to `Promise<undefined>`, which is assignable to the `Promise<void>` the contract declares.
+    delay: (ms, init) => delay(ms, undefined, init),
+    now: () => Date.now()
+};
+//# sourceMappingURL=clock.js.map

package/dist/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAgC3D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAU;IAEhC,mKAAmK;IACnK,0JAA0J;IAC1J,KAAK,EAAE,CAAC,EAAU,EAAE,IAA+B,EAAiB,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC;IACjG,GAAG,EAAE,GAAW,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;CAC9B,CAAC"}

package/dist/disposable-stack.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A container that aggregates disposable resources and disposes them, in reverse (last-in-first-out) order, when the stack itself is disposed.
+ *
+ * The class satisfies the platform `DisposableStack` interface by construction - the `implements` clause below binds it to `globalThis.DisposableStack`, so the
+ * compiler enforces that the name's promise (the platform contract) is kept at the definition site.
+ *
+ * @category Utilities
+ */
+export declare class DisposableStack implements InstanceType<typeof globalThis.DisposableStack> {
+    #private;
+    readonly [Symbol.toStringTag] = "DisposableStack";
+    /**
+     * Whether this stack has been disposed.
+     */
+    get disposed(): boolean;
+    /**
+     * Register a {@link Disposable} whose `[Symbol.dispose]()` runs when this stack is disposed, returning the value unchanged.
+     *
+     * `null` and `undefined` pass through without being registered. The dispose method is captured at registration time and invoked with the value as its receiver, so
+     * a later mutation of `value[Symbol.dispose]` cannot change what runs.
+     *
+     * @param value - The resource to register, or `null`/`undefined` to skip registration.
+     * @returns The provided `value`.
+     */
+    use<T extends Disposable | null | undefined>(value: T): T;
+    /**
+     * Register a value together with an explicit disposal callback, returning the value unchanged. The callback is invoked with the value as its first argument when
+     * this stack is disposed.
+     *
+     * @param value - The value to associate with the callback.
+     * @param onDispose - The disposal callback, invoked with `value`.
+     * @returns The provided `value`.
+     */
+    adopt<T>(value: T, onDispose: (value: T) => void): T;
+    /**
+     * Register a callback to run when this stack is disposed.
+     *
+     * @param onDispose - The callback to run on disposal.
+     */
+    defer(onDispose: () => void): void;
+    /**
+     * Move every pending disposer out of this stack into a fresh {@link DisposableStack}, preserving registration order, and mark this stack disposed without running
+     * anything. This is the "commit" primitive: after a successful acquire sequence, moving the disposers away disarms this stack's scope-bound cleanup while handing
+     * responsibility for those resources to the returned stack.
+     *
+     * @returns A new stack owning the transferred disposers.
+     */
+    move(): DisposableStack;
+    /**
+     * Dispose every registered resource in reverse (last-in-first-out) order. A second call is a no-op. Every disposer runs even when an earlier one throws: a single
+     * failure is rethrown after the sweep completes, and multiple failures chain through `SuppressedError` (the newest failure wrapping the accumulated one).
+     */
+    dispose(): void;
+    /**
+     * Dispose this stack. Enables `using` semantics by delegating to {@link dispose}.
+     */
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=disposable-stack.d.ts.map

package/dist/disposable-stack.js

@@ -0,0 +1,155 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * disposable-stack.ts: An in-package stand-in for the platform `DisposableStack` global that the library's own port allocator relies on.
+ */
+// Build a `SuppressedError` that links a newer disposal failure to the error it supersedes, matching the spec's multi-failure aggregation shape. We read the platform
+// `SuppressedError` global fresh on every call rather than caching a reference, because that constructor is itself part of the Node 24 explicit-resource-management
+// surface and can be absent on the engines floor this module exists to serve. When it is missing we synthesize a structurally-identical stand-in - an `Error` whose
+// name is "SuppressedError" carrying `error` and `suppressed` - so multi-failure aggregation is observably identical whether or not the global is present. The typed
+// optional read tells the truth the platform lib cannot: on this engines floor the global may not exist.
+function createSuppressedError(error, suppressed) {
+    const suppressedErrorConstructor = globalThis.SuppressedError;
+    if (suppressedErrorConstructor !== undefined) {
+        return new suppressedErrorConstructor(error, suppressed);
+    }
+    const synthesized = new Error();
+    synthesized.error = error;
+    synthesized.name = "SuppressedError";
+    synthesized.suppressed = suppressed;
+    return synthesized;
+}
+/**
+ * A container that aggregates disposable resources and disposes them, in reverse (last-in-first-out) order, when the stack itself is disposed.
+ *
+ * The class satisfies the platform `DisposableStack` interface by construction - the `implements` clause below binds it to `globalThis.DisposableStack`, so the
+ * compiler enforces that the name's promise (the platform contract) is kept at the definition site.
+ *
+ * @category Utilities
+ */
+export class DisposableStack {
+    // The pending disposers in registration order. A `null` array is the disposed state: pairing "disposed" with "no pending disposers" in a single field makes the
+    // disposed-with-pending-work state unrepresentable, so every member checks this one field to decide whether it may still register or run work.
+    #disposers = [];
+    // The platform tag reported by `Object.prototype.toString`, matching the native class.
+    [Symbol.toStringTag] = "DisposableStack";
+    /**
+     * Whether this stack has been disposed.
+     */
+    get disposed() {
+        return this.#disposers === null;
+    }
+    /**
+     * Register a {@link Disposable} whose `[Symbol.dispose]()` runs when this stack is disposed, returning the value unchanged.
+     *
+     * `null` and `undefined` pass through without being registered. The dispose method is captured at registration time and invoked with the value as its receiver, so
+     * a later mutation of `value[Symbol.dispose]` cannot change what runs.
+     *
+     * @param value - The resource to register, or `null`/`undefined` to skip registration.
+     * @returns The provided `value`.
+     */
+    use(value) {
+        if (this.#disposers === null) {
+            throw new ReferenceError("Cannot use a resource on a disposed DisposableStack.");
+        }
+        // Skip registration for null and undefined, returning them unchanged. We test undefined with `typeof` so the generic parameter narrows cleanly to a Disposable for
+        // the member access below.
+        if ((value === null) || (typeof value === "undefined")) {
+            return value;
+        }
+        // Capture the dispose method now, at registration time, matching the spec's registration-time capture... a later mutation of `value[Symbol.dispose]` must not change
+        // what runs. We read it through `unknown` because use() is a trust boundary: a value can satisfy the Disposable type nominally yet present a non-callable member at
+        // runtime, which the spec requires we reject with a TypeError.
+        const disposeMethod = value[Symbol.dispose];
+        if (typeof disposeMethod !== "function") {
+            throw new TypeError("The value passed to DisposableStack.use() is not disposable.");
+        }
+        const boundDispose = disposeMethod;
+        this.#disposers.push(() => {
+            boundDispose.call(value);
+        });
+        return value;
+    }
+    /**
+     * Register a value together with an explicit disposal callback, returning the value unchanged. The callback is invoked with the value as its first argument when
+     * this stack is disposed.
+     *
+     * @param value - The value to associate with the callback.
+     * @param onDispose - The disposal callback, invoked with `value`.
+     * @returns The provided `value`.
+     */
+    adopt(value, onDispose) {
+        if (this.#disposers === null) {
+            throw new ReferenceError("Cannot adopt a resource on a disposed DisposableStack.");
+        }
+        if (typeof onDispose !== "function") {
+            throw new TypeError("The onDispose callback passed to DisposableStack.adopt() is not a function.");
+        }
+        this.#disposers.push(() => onDispose(value));
+        return value;
+    }
+    /**
+     * Register a callback to run when this stack is disposed.
+     *
+     * @param onDispose - The callback to run on disposal.
+     */
+    defer(onDispose) {
+        if (this.#disposers === null) {
+            throw new ReferenceError("Cannot defer a callback on a disposed DisposableStack.");
+        }
+        if (typeof onDispose !== "function") {
+            throw new TypeError("The onDispose callback passed to DisposableStack.defer() is not a function.");
+        }
+        this.#disposers.push(onDispose);
+    }
+    /**
+     * Move every pending disposer out of this stack into a fresh {@link DisposableStack}, preserving registration order, and mark this stack disposed without running
+     * anything. This is the "commit" primitive: after a successful acquire sequence, moving the disposers away disarms this stack's scope-bound cleanup while handing
+     * responsibility for those resources to the returned stack.
+     *
+     * @returns A new stack owning the transferred disposers.
+     */
+    move() {
+        if (this.#disposers === null) {
+            throw new ReferenceError("Cannot move a disposed DisposableStack.");
+        }
+        const moved = new DisposableStack();
+        // Transfer the array by reference so order is preserved, then mark this stack disposed without running any disposer.
+        moved.#disposers = this.#disposers;
+        this.#disposers = null;
+        return moved;
+    }
+    /**
+     * Dispose every registered resource in reverse (last-in-first-out) order. A second call is a no-op. Every disposer runs even when an earlier one throws: a single
+     * failure is rethrown after the sweep completes, and multiple failures chain through `SuppressedError` (the newest failure wrapping the accumulated one).
+     */
+    dispose() {
+        if (this.#disposers === null) {
+            return;
+        }
+        // Detach the array and mark disposed before running anything, so a disposer that re-enters this stack observes the disposed state and cannot double-run work.
+        const disposers = this.#disposers;
+        this.#disposers = null;
+        let hasError = false;
+        let heldError;
+        // Reverse the detached array in place - we hold the only reference to it, so mutating it is safe - and run the disposers last-in-first-out.
+        for (const disposer of disposers.reverse()) {
+            try {
+                disposer();
+            }
+            catch (error) {
+                heldError = hasError ? createSuppressedError(error, heldError) : error;
+                hasError = true;
+            }
+        }
+        if (hasError) {
+            throw heldError;
+        }
+    }
+    /**
+     * Dispose this stack. Enables `using` semantics by delegating to {@link dispose}.
+     */
+    [Symbol.dispose]() {
+        this.dispose();
+    }
+}
+//# sourceMappingURL=disposable-stack.js.map

package/dist/disposable-stack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"disposable-stack.js","sourceRoot":"","sources":["../src/disposable-stack.ts"],"names":[],"mappings":"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"}