homebridge-plugin-utils 1.34.0 → 2.0.0

package/build/fs-ops.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * fs-ops.mjs: Native node:fs/promises filesystem operations for HBPU's build and test scripts (rm, cp, mkdir). Node 22+ provides recursive flags natively, so no
+ * shell-portability shim is needed for the handful of operations we use.
+ *
+ * Subcommands:
+ *
+ *   build-ui               mkdir dist/ui and copy shippable ui/*.mjs (excluding test-only files) into it (invoked by the `build-ui` npm script).
+ *   clean <paths...>       rm -rf each path, silently ignoring missing entries; errors if no paths are supplied (invoked by `clean`).
+ *   clean-docs             remove TypeDoc-generated markdown from docs/ and docs/ffmpeg/ before regeneration (invoked by `build-docs`).
+ *   finalize               ready the emitted dist/ for shipping and local consumption: copy the browser-runtime modules into dist/ui and mark every declared bin
+ *                          entry executable, after tsc emits them (invoked at the tail of `build`).
+ */
+import { basename, join } from "node:path";
+import { chmod, cp, mkdir, readFile, readdir, rm, stat } from "node:fs/promises";
+
+// Hand-authored docs preserved through the clean-docs sweep. Everything else at the root of docs/ (and the entire docs/ffmpeg/ tree) is transient and regenerated by
+// `npm run build-docs` on every run. Add entries to this set when introducing another file that should survive regeneration.
+const PRESERVED_DOCS = new Set([ "Changelog.md", "Overview.md" ]);
+
+// Recursively remove every path in the list. `rm` with `force: true` already silences ENOENT, so missing paths are a no-op and the behavior matches shx's `rm -rf`.
+async function clean(paths) {
+
+  await Promise.all(paths.map((path) => rm(path, { force: true, recursive: true })));
+}
+
+// Ensure dist/ui exists and copy the browser-side UI assets into it. Runs during the clean and build-ui phases, before tsc emits the compiled featureOptions.js,
+// so the directory has to exist up front and the featureOptions copy step runs separately after tsc. We filter to shippable artifacts by excluding the
+// test-only file shapes: `*.test.mjs` (suite files), `*.fixtures.mjs` (shared test data), `*.helpers.mjs` (shared test code), and `test-*.mjs` (test infrastructure,
+// currently the `registerHooks` module-resolution loader). Suffix matches are centralized in `TEST_ONLY_SUFFIXES` so adding a new test-file shape is a one-line edit
+// rather than a chain of `&& !entry.endsWith(...)` clauses. The resulting dist/ui/ contains only the browser runtime files consumers execute.
+//
+// The copy is recursive so the directory structure under `ui/` (the `webUi-featureOptions/`, `webUi-featureOptions/effects/`, `webUi-featureOptions/views/`
+// subdirectories) is preserved as-is in `dist/ui/`. The filter is consulted per-entry: directories always pass through (returning `true` lets `cp` walk into them);
+// files are kept only when they match the shippable shape.
+const TEST_ONLY_SUFFIXES = [ ".fixtures.mjs", ".helpers.mjs", ".test.mjs" ];
+
+async function buildUi() {
+
+  await mkdir("dist/ui", { recursive: true });
+
+  await cp("ui", "dist/ui", {
+
+    filter: async (src) => {
+
+      const s = await stat(src);
+
+      if(s.isDirectory()) {
+
+        return true;
+      }
+
+      const name = basename(src);
+
+      if(!name.endsWith(".mjs") || name.startsWith("test-")) {
+
+        return false;
+      }
+
+      return !TEST_ONLY_SUFFIXES.some((suffix) => name.endsWith(suffix));
+    },
+    recursive: true
+  });
+}
+
+// Copy the compiled browser-runnable modules into dist/ui so the browser-side webUI can resolve them as siblings of the orchestrator. Runs after tsc emits the
+// compiled `dist/*.js` files. The module list is the SSOT for "what `featureOptions.js` needs at runtime in the browser" - currently `featureOptions.js` itself
+// plus `formatters.js` (the magnitude/percentage formatters the catalog's built-in renderer registry imports). Adding a new browser-side runtime dependency
+// means adding its name here AND keeping that artifact's own imports browser-safe.
+//
+// Each module ships paired with its `.js.map` so browser DevTools can map runtime errors back to the original `.ts` source. The `.d.ts` / `.d.ts.map` artifacts
+// are TypeScript-only and stay in `dist/` for type consumers; the browser never loads them, so they have no place in `dist/ui/`.
+async function copyFeatureOptions() {
+
+  const modules = [ "featureOptions", "formatters" ];
+
+  await Promise.all(modules.flatMap((name) => [
+
+    cp(join("dist", name + ".js"), join("dist/ui", name + ".js")),
+    cp(join("dist", name + ".js.map"), join("dist/ui", name + ".js.map"))
+  ]));
+}
+
+// Mark every executable declared in package.json's `bin` field as user-executable (0o755). tsc emits plain 0o644 files with no execute bit. For a registry install
+// npm sets the bit on bin targets itself, but it does NOT chmod the live source file behind a `file:` symlinked dependency - so a plugin consuming HBPU locally
+// gets a non-executable CLI entry and a "Permission denied" the moment it invokes the bin. Reading the path set straight from package.json keeps the `bin`
+// declaration the single source of truth: the build chmods whatever `bin` points at, so introducing or relocating a bin entry needs no parallel edit here.
+async function makeBinExecutable() {
+
+  const manifest = JSON.parse(await readFile("package.json", "utf8"));
+  const bin = manifest.bin;
+
+  // npm permits `bin` as either a string (a single executable named after the package) or an object map of command-name to path. Normalize both shapes to a flat
+  // list of paths so the chmod loop is agnostic to which form the manifest uses.
+  const binPaths = (typeof bin === "string") ? [bin] : Object.values(bin ?? {});
+
+  await Promise.all(binPaths.map((binPath) => chmod(binPath, 0o755)));
+}
+
+// Post-tsc finalization: ready the emitted dist/ for shipping and local consumption. Placing the browser-runtime modules alongside the webUI and marking the
+// CLI bin executable are independent concerns, so they run concurrently. This is the single tail-of-build step the `build` script invokes after tsc.
+async function finalize() {
+
+  await Promise.all([ copyFeatureOptions(), makeBinExecutable() ]);
+}
+
+// Remove the TypeDoc-generated markdown fragments from docs/ before regeneration. Entries listed in PRESERVED_DOCS survive at the root; docs/ffmpeg/ is cleared in
+// full since everything under it is regenerated from source on every build-docs run.
+async function cleanDocs() {
+
+  await Promise.all([
+
+    cleanDir("docs", (entry) => entry.endsWith(".md") && !PRESERVED_DOCS.has(entry)),
+    cleanDir("docs/ffmpeg", (entry) => entry.endsWith(".md"))
+  ]);
+}
+
+// Utility shared by cleanDocs: list a directory and remove every entry that matches the predicate. A missing parent directory resolves as a no-op rather than
+// surfacing ENOENT, since a fresh clone won't have `docs/` at all and the build-docs flow needs to tolerate that.
+async function cleanDir(dir, matches) {
+
+  let entries;
+
+  try {
+
+    entries = await readdir(dir);
+  } catch(error) {
+
+    if((error instanceof Error) && ("code" in error) && (error.code === "ENOENT")) {
+
+      return;
+    }
+
+    throw error;
+  }
+
+  await Promise.all(entries.filter(matches).map((entry) => rm(join(dir, entry), { force: true })));
+}
+
+const [ command, ...args ] = process.argv.slice(2);
+
+switch(command) {
+
+  case "build-ui": {
+
+    await buildUi();
+
+    break;
+  }
+
+  case "clean": {
+
+    if(!args.length) {
+
+      process.stderr.write("Usage: fs-ops.mjs clean <paths...>\n");
+      process.exit(1);
+    }
+
+    await clean(args);
+
+    break;
+  }
+
+  case "clean-docs": {
+
+    await cleanDocs();
+
+    break;
+  }
+
+  case "finalize": {
+
+    await finalize();
+
+    break;
+  }
+
+  default: {
+
+    process.stderr.write("Usage: fs-ops.mjs {build-ui | clean <paths...> | clean-docs | finalize}\n");
+    process.exit(1);
+  }
+}

package/build/tsconfig.json

@@ -5,10 +5,13 @@
 {
   "compilerOptions": {
 
-    "allowSyntheticDefaultImports": true,
+    "allowImportingTsExtensions": true,
     "declaration": true,
+    "declarationMap": true,
+    "erasableSyntaxOnly": true,
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
 
     "lib": [
 
@@ -16,13 +19,25 @@
       "ES2024",
       "ESNext.Array",
       "ESNext.Collection",
-      "ESNext.Iterator"
+      "ESNext.Disposable",
+      "ESNext.Iterator",
+      "ESNext.Promise"
     ],
 
     "module": "nodenext",
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noUncheckedIndexedAccess": true,
+    "noUncheckedSideEffectImports": true,
+    "resolveJsonModule": true,
+    "rewriteRelativeImportExtensions": true,
+    "skipLibCheck": true,
     "sourceMap": true,
     "strict": true,
-    "target": "ES2024"
+    "target": "ES2024",
+    "verbatimModuleSyntax": true
   }
 }
 /* When creating your own tsconfig.json, use the following as a starting point to inherit these defaults:

package/dist/backpressure.d.ts

@@ -0,0 +1,128 @@
+import type { Nullable } from "./util.ts";
+import type { Writable } from "node:stream";
+/**
+ * Thrown synchronously by {@link BackpressureWriter.write} when the pending queue is already at the configured {@link BackpressureWriterInit.highWaterMark} and
+ * accepting the new chunk would push it over.
+ *
+ * Separate from the "writer has aborted" and "underlying stream is dead" failure modes so callers can discriminate backpressure-overflow (back off and retry later)
+ * from terminal failures (give up or escalate) by type rather than by inspecting error message text.
+ *
+ * @category Utilities
+ */
+export declare class BackpressureOverflowError extends Error {
+    readonly name: "BackpressureOverflowError";
+    constructor(message?: string);
+}
+/**
+ * Rejected by an individual {@link BackpressureWriter.write} promise when the provider returned a {@link Writable} whose `writable` flag is `false` (the stream has
+ * ended or been destroyed). The writer itself remains alive - a later stream replacement via the provider may revive the pipeline - so this is a per-write rejection,
+ * not a terminal writer error.
+ *
+ * @category Utilities
+ */
+export declare class BackpressureClosedStreamError extends Error {
+    readonly name: "BackpressureClosedStreamError";
+    constructor(message?: string);
+}
+/**
+ * Construction-time options for {@link BackpressureWriter}.
+ *
+ * @property highWaterMark - Optional ceiling on the total pending-write depth, including the in-flight entry that is currently awaiting `drain`. When specified, a
+ *                           `write()` call that would push the pending queue past this depth rejects synchronously with a {@link BackpressureOverflowError} rather
+ *                           than buffering unboundedly. Omit for unbounded queueing (the caller trusts upstream producers not to outrun the stream by more than
+ *                           available memory).
+ * @property signal        - Optional parent {@link AbortSignal} to compose with the writer's internal controller. When the parent aborts, the writer tears down:
+ *                           pending writes reject with `signal.reason`, any in-flight drain wait unwinds, and every subsequent `write()` call rejects immediately.
+ *
+ * @category Utilities
+ */
+export interface BackpressureWriterInit {
+    highWaterMark?: number;
+    signal?: AbortSignal;
+}
+/**
+ * AsyncDisposable backpressure-aware write queue for Node {@link Writable} streams.
+ *
+ * Each call to {@link BackpressureWriter.write} returns a Promise that resolves once the chunk has been written (and any triggered backpressure has drained) or rejects
+ * if the writer aborts mid-write. Concurrent writes serialize through an internal FIFO queue; ordering matches call order. The stream itself is resolved lazily through
+ * a caller-supplied provider on each drain turn, so the writer may outlive any particular stream instance - the provider is consulted per chunk, and a `null` return is
+ * a signal to drop the chunk (the associated write promise still resolves, treating the drop as a success from the caller's perspective).
+ *
+ * @example
+ *
+ * ```ts
+ * import { BackpressureWriter } from "homebridge-plugin-utils";
+ *
+ * await using writer = new BackpressureWriter(() => ffmpegProcess.stdin ?? null, { signal: session.signal });
+ *
+ * // Each write awaits its own flush; concurrent writes queue behind prior ones.
+ * await writer.write(segmentOne);
+ * await writer.write(segmentTwo);
+ * ```
+ *
+ * @category Utilities
+ */
+export declare class BackpressureWriter implements AsyncDisposable {
+    #private;
+    /**
+     * The composed abort signal representing this writer's lifetime. Aborts exactly once when {@link BackpressureWriter.abort} is called, when the parent signal fires,
+     * or when the underlying stream surfaces an error that invalidates the writer; `signal.reason` names the cause.
+     */
+    readonly signal: AbortSignal;
+    /**
+     * Construct a new backpressure-aware writer.
+     *
+     * @param streamProvider - A function that returns the current writable stream, or `null` to drop incoming chunks. Evaluated lazily on each drain-loop iteration.
+     * @param init           - Optional init options. See {@link BackpressureWriterInit}.
+     *
+     * @example
+     *
+     * ```ts
+     * await using writer = new BackpressureWriter(() => this.ffmpegProcess?.stdin ?? null, { highWaterMark: 64, signal: session.signal });
+     * ```
+     */
+    constructor(streamProvider: () => Nullable<Writable>, init?: BackpressureWriterInit);
+    /**
+     * Enqueue `chunk` for writing. Concurrent calls serialize in FIFO order via the internal queue.
+     *
+     * @param chunk - The buffer to write.
+     *
+     * @returns A promise that resolves when the chunk has been flushed to the underlying stream (including any required drain wait), or immediately if the provider
+     *          returned `null` at dispatch time (drop semantics). The promise rejects in the following cases:
+     *
+     * - `this.signal.reason` - the writer aborted before or during the write.
+     * - {@link BackpressureOverflowError} (thrown synchronously) - `highWaterMark` is configured and the queue depth already equals or exceeds it.
+     * - {@link BackpressureClosedStreamError} - the provider returned a stream whose `writable` flag is `false`. The writer itself stays alive for a potential later
+     *   stream replacement.
+     *
+     * @throws {@link BackpressureOverflowError} when `highWaterMark` is exceeded.
+     */
+    write(chunk: Buffer): Promise<void>;
+    /**
+     * Abort the writer and tear it down. Defaults to `HbpuAbortError("shutdown")` when no reason is supplied; explicit reasons pass through unchanged.
+     *
+     * Safe to call more than once: subsequent calls are no-ops because the underlying signal only aborts once. Every queued write rejects with the signal's reason; any
+     * in-flight drain wait rejects with the signal's reason as well, and that rejection propagates out of the in-flight `write()` promise.
+     *
+     * @param reason - Optional abort reason. Typically an {@link HbpuAbortError}; platform errors (`TimeoutError`, `AbortError`) also interoperate by convention.
+     */
+    abort(reason?: unknown): void;
+    /**
+     * `AsyncDisposable` implementation. Aborts the writer (defaulting to `"shutdown"`) and awaits actual drain-loop completion before returning, so callers using
+     * `await using` are guaranteed every pending write has settled by the time the surrounding scope exits.
+     *
+     * @returns A promise that resolves once the drain loop has fully exited.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * `true` once `this.signal` has aborted. Derived from the signal; no independent state.
+     */
+    get aborted(): boolean;
+    /**
+     * Total number of entries in the pending-write queue, including the in-flight entry (if the drain loop is parked on `events.once(stream, "drain", { signal })`).
+     * Matches the depth that the configured `highWaterMark` is compared against, so adaptive producers watching this value see the same accounting the writer uses
+     * internally.
+     */
+    get pending(): number;
+}
+//# sourceMappingURL=backpressure.d.ts.map

package/dist/backpressure.js

@@ -0,0 +1,273 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * backpressure.ts: Signal-driven, backpressure-aware write queue for Node.js writable streams.
+ */
+/**
+ * AsyncDisposable write queue that serializes Buffer writes onto a Node {@link Writable}, respects backpressure via the stream's `drain` event, and composes into the
+ * library's `AbortSignal`-driven lifecycle so a parent signal can tear the writer down uniformly with every other HBPU resource class.
+ *
+ * Primary use case: feeding fMP4 segments from a livestream event source into an FFmpeg process's stdin, where the downstream may not consume as fast as the upstream
+ * produces.
+ *
+ * @module
+ */
+import { HbpuAbortError, composeSignals, onAbort } from "./util.js";
+import { once } from "node:events";
+/**
+ * Thrown synchronously by {@link BackpressureWriter.write} when the pending queue is already at the configured {@link BackpressureWriterInit.highWaterMark} and
+ * accepting the new chunk would push it over.
+ *
+ * Separate from the "writer has aborted" and "underlying stream is dead" failure modes so callers can discriminate backpressure-overflow (back off and retry later)
+ * from terminal failures (give up or escalate) by type rather than by inspecting error message text.
+ *
+ * @category Utilities
+ */
+export class BackpressureOverflowError extends Error {
+    name = "BackpressureOverflowError";
+    constructor(message = "BackpressureWriter: queue depth exceeds configured highWaterMark.") {
+        super(message);
+    }
+}
+/**
+ * Rejected by an individual {@link BackpressureWriter.write} promise when the provider returned a {@link Writable} whose `writable` flag is `false` (the stream has
+ * ended or been destroyed). The writer itself remains alive - a later stream replacement via the provider may revive the pipeline - so this is a per-write rejection,
+ * not a terminal writer error.
+ *
+ * @category Utilities
+ */
+export class BackpressureClosedStreamError extends Error {
+    name = "BackpressureClosedStreamError";
+    constructor(message = "BackpressureWriter: underlying stream is not writable.") {
+        super(message);
+    }
+}
+/**
+ * AsyncDisposable backpressure-aware write queue for Node {@link Writable} streams.
+ *
+ * Each call to {@link BackpressureWriter.write} returns a Promise that resolves once the chunk has been written (and any triggered backpressure has drained) or rejects
+ * if the writer aborts mid-write. Concurrent writes serialize through an internal FIFO queue; ordering matches call order. The stream itself is resolved lazily through
+ * a caller-supplied provider on each drain turn, so the writer may outlive any particular stream instance - the provider is consulted per chunk, and a `null` return is
+ * a signal to drop the chunk (the associated write promise still resolves, treating the drop as a success from the caller's perspective).
+ *
+ * @example
+ *
+ * ```ts
+ * import { BackpressureWriter } from "homebridge-plugin-utils";
+ *
+ * await using writer = new BackpressureWriter(() => ffmpegProcess.stdin ?? null, { signal: session.signal });
+ *
+ * // Each write awaits its own flush; concurrent writes queue behind prior ones.
+ * await writer.write(segmentOne);
+ * await writer.write(segmentTwo);
+ * ```
+ *
+ * @category Utilities
+ */
+export class BackpressureWriter {
+    /**
+     * The composed abort signal representing this writer's lifetime. Aborts exactly once when {@link BackpressureWriter.abort} is called, when the parent signal fires,
+     * or when the underlying stream surfaces an error that invalidates the writer; `signal.reason` names the cause.
+     */
+    signal;
+    // The private AbortController whose signal is composed into `this.signal`. Owning the controller internally keeps teardown reachable from any handler - drain-wait
+    // cancellation, stream-error escalation, explicit abort - without giving callers a handle to the raw controller.
+    #controller;
+    // Optional queue-depth ceiling. When undefined, the queue is unbounded and the only memory discipline is whatever the caller imposes by awaiting prior writes before
+    // issuing new ones.
+    #highWaterMark;
+    // Caller-provided resolver for the target stream. Evaluated lazily on each drain-loop iteration so the writer can survive stream replacement across FFmpeg process
+    // restarts, and so callers can bind the writer to a stream that does not yet exist at construction time.
+    #streamProvider;
+    // FIFO queue of pending writes. Each entry pairs the buffer with its resolver so the drain loop can settle the caller's promise at the same point it consumes the
+    // chunk. The drain loop peeks `queue[0]` during the write (so queue.length reflects total pending, including the in-flight entry) and shifts the entry off only
+    // after it has fully flushed or failed.
+    #queue = [];
+    // The active drain-loop promise, if any. Held so `[Symbol.asyncDispose]` can await actual completion before returning, so `await using` callers are guaranteed no
+    // stream interaction is still in flight by the time the surrounding scope exits.
+    #drainTask;
+    // True while the drain loop is active (set at entry, cleared in the loop's `finally`). Used by `write()` to decide whether to spawn a new drain - the flag flips
+    // back to false the moment the loop exits, whether synchronously (queue emptied in one pass, no backpressure) or asynchronously (after a drain wait or abort) - so
+    // a subsequent `write()` that arrives right after an empty-queue exit correctly re-spawns the loop rather than being stranded by a stale drain-task reference.
+    #processing = false;
+    /**
+     * Construct a new backpressure-aware writer.
+     *
+     * @param streamProvider - A function that returns the current writable stream, or `null` to drop incoming chunks. Evaluated lazily on each drain-loop iteration.
+     * @param init           - Optional init options. See {@link BackpressureWriterInit}.
+     *
+     * @example
+     *
+     * ```ts
+     * await using writer = new BackpressureWriter(() => this.ffmpegProcess?.stdin ?? null, { highWaterMark: 64, signal: session.signal });
+     * ```
+     */
+    constructor(streamProvider, init = {}) {
+        this.#streamProvider = streamProvider;
+        this.#highWaterMark = init.highWaterMark;
+        this.#controller = new AbortController();
+        this.signal = composeSignals(init.signal, this.#controller.signal);
+        // Single teardown convergence point. `onAbort` registers the one-shot teardown handler AND handles the pre-aborted-signal edge case where `addEventListener`
+        // would otherwise skip the handler. Rejects every pending entry - including the in-flight entry when the drain loop is parked on
+        // `events.once(stream, "drain", { signal })`. The drain loop's catch branch may also reject the in-flight resolver under the same abort; promise resolvers are
+        // idempotent after first settlement, so the second call is a no-op. Rejecting from here unconditionally is load-bearing in the stream-error escalation path,
+        // where the drain loop shifts the in-flight entry before calling `this.#controller.abort(...)` - by the time the listener runs, only the queued entries remain
+        // in the queue, and leaving any of them unrejected would orphan the caller's promise.
+        onAbort(this.signal, () => this.#teardown());
+    }
+    /**
+     * Enqueue `chunk` for writing. Concurrent calls serialize in FIFO order via the internal queue.
+     *
+     * @param chunk - The buffer to write.
+     *
+     * @returns A promise that resolves when the chunk has been flushed to the underlying stream (including any required drain wait), or immediately if the provider
+     *          returned `null` at dispatch time (drop semantics). The promise rejects in the following cases:
+     *
+     * - `this.signal.reason` - the writer aborted before or during the write.
+     * - {@link BackpressureOverflowError} (thrown synchronously) - `highWaterMark` is configured and the queue depth already equals or exceeds it.
+     * - {@link BackpressureClosedStreamError} - the provider returned a stream whose `writable` flag is `false`. The writer itself stays alive for a potential later
+     *   stream replacement.
+     *
+     * @throws {@link BackpressureOverflowError} when `highWaterMark` is exceeded.
+     */
+    async write(chunk) {
+        // Pre-aborted short-circuit: a write issued after teardown has nothing live to attach to. Rejecting with the signal's reason keeps semantics uniform with the
+        // mid-write abort path - callers discriminate on `signal.reason` / `isHbpuAbortReason` in either case.
+        if (this.signal.aborted) {
+            throw this.signal.reason;
+        }
+        // Queue-overflow fail-fast. Rejecting synchronously lets upstream producers apply their own pacing rather than silently accumulating unbounded backlog. A
+        // dedicated {@link BackpressureOverflowError} class (not an `HbpuAbortError`) is thrown here because the writer itself is still healthy - the caller supplied too
+        // much work, not the system asking for teardown - and consumers who care about the distinction can `instanceof`-check rather than match on message text.
+        if ((this.#highWaterMark !== undefined) && (this.#queue.length >= this.#highWaterMark)) {
+            throw new BackpressureOverflowError();
+        }
+        const resolvers = Promise.withResolvers();
+        this.#queue.push({ chunk, resolvers });
+        // Spin up the drain loop when nothing is already processing. We key off the `#processing` flag rather than `#drainTask` because an async function's body runs
+        // synchronously until its first `await`: a no-backpressure drain completes before `write()` returns, leaving `#drainTask` set to a resolved-but-not-yet-cleared
+        // promise that would falsely gate subsequent writes. `#processing` is flipped true at the top of `#drain` and false in its `finally`, so checking it gives us a
+        // truthful "is a drain currently running?" answer with no chained-promise races.
+        if (!this.#processing) {
+            this.#drainTask = this.#drain();
+        }
+        return resolvers.promise;
+    }
+    /**
+     * Abort the writer and tear it down. Defaults to `HbpuAbortError("shutdown")` when no reason is supplied; explicit reasons pass through unchanged.
+     *
+     * Safe to call more than once: subsequent calls are no-ops because the underlying signal only aborts once. Every queued write rejects with the signal's reason; any
+     * in-flight drain wait rejects with the signal's reason as well, and that rejection propagates out of the in-flight `write()` promise.
+     *
+     * @param reason - Optional abort reason. Typically an {@link HbpuAbortError}; platform errors (`TimeoutError`, `AbortError`) also interoperate by convention.
+     */
+    abort(reason) {
+        if (this.aborted) {
+            return;
+        }
+        this.#controller.abort(reason ?? new HbpuAbortError("shutdown"));
+    }
+    /**
+     * `AsyncDisposable` implementation. Aborts the writer (defaulting to `"shutdown"`) and awaits actual drain-loop completion before returning, so callers using
+     * `await using` are guaranteed every pending write has settled by the time the surrounding scope exits.
+     *
+     * @returns A promise that resolves once the drain loop has fully exited.
+     */
+    async [Symbol.asyncDispose]() {
+        this.abort();
+        if (this.#drainTask) {
+            // Drain failures are already observed through the individual write promises; swallow here so `await using` does not surface cleanup-side errors the caller has
+            // no way to react to.
+            await this.#drainTask.catch(() => { });
+        }
+    }
+    /**
+     * `true` once `this.signal` has aborted. Derived from the signal; no independent state.
+     */
+    get aborted() {
+        return this.signal.aborted;
+    }
+    /**
+     * Total number of entries in the pending-write queue, including the in-flight entry (if the drain loop is parked on `events.once(stream, "drain", { signal })`).
+     * Matches the depth that the configured `highWaterMark` is compared against, so adaptive producers watching this value see the same accounting the writer uses
+     * internally.
+     */
+    get pending() {
+        return this.#queue.length;
+    }
+    // Drain loop. Iterates the queue, writing each chunk through the provider's current stream, honoring backpressure via `events.once(stream, "drain", { signal })`.
+    // Runs until the queue is empty or the signal aborts; every in-flight write is settled before exit (resolved on successful write, rejected via drain-abort on
+    // teardown). Note the peek-then-shift pattern: the entry stays at `queue[0]` while the write is in flight, so `queue.length` reflects the true pending count
+    // (including the in-flight entry) and `highWaterMark` checks in `write()` work uniformly whether the drain is idle or mid-wait.
+    async #drain() {
+        this.#processing = true;
+        try {
+            while ((this.#queue.length > 0) && !this.signal.aborted) {
+                const entry = this.#queue[0];
+                // `length`-guarded peek: the loop condition just checked non-empty, so we always have an entry. `noUncheckedIndexedAccess` widens the indexed access to
+                // `PendingWrite | undefined`; the null check below narrows for the compiler without changing runtime semantics.
+                if (!entry) {
+                    break;
+                }
+                // Re-evaluate the stream on every iteration. The provider is free to return a different instance across turns (stream replacement across restarts) or `null`
+                // (no live stream right now - drop the chunk). Both cases are expected in HBUP's pipeline and are handled here without surfacing as errors to the caller.
+                const stream = this.#streamProvider();
+                if (!stream) {
+                    // Drop semantics: the provider explicitly said "no stream." The write promise resolves so the caller can continue without branching on a per-write return;
+                    // the surrounding session is responsible for deciding whether the lack of a stream is itself a fault.
+                    this.#queue.shift();
+                    entry.resolvers.resolve();
+                    continue;
+                }
+                if (!stream.writable) {
+                    // Stream exists but has ended. Reject this specific write with a {@link BackpressureClosedStreamError} and let the caller decide whether to escalate - we
+                    // do not abort the writer here, because a later stream replacement (via the provider) may revive the pipeline.
+                    this.#queue.shift();
+                    entry.resolvers.reject(new BackpressureClosedStreamError());
+                    continue;
+                }
+                try {
+                    // `stream.write()` returns `false` when the high-water mark has been breached; the write is still queued by Node, but we must wait for `drain` before
+                    // pushing more bytes or we risk unbounded growth of Node's internal write buffer in process memory. `events.once` with `{ signal }` ties the wait to the
+                    // writer's lifetime so an abort during drain rejects the wait with the signal's reason rather than hanging.
+                    if (!stream.write(entry.chunk)) {
+                        // eslint-disable-next-line no-await-in-loop
+                        await once(stream, "drain", { signal: this.signal });
+                    }
+                    this.#queue.shift();
+                    entry.resolvers.resolve();
+                }
+                catch (error) {
+                    // Two rejection shapes land here. (a) Our signal aborted mid-drain: `once` rejects with `signal.reason`; we surface that to the caller and exit the loop
+                    // because teardown is already in flight. (b) The stream emitted an error via some path `events.once` exposes: the write that triggered the error cannot
+                    // complete, so we reject this caller and abort the writer with `"failed"` so no subsequent write tries to reuse a broken stream silently.
+                    this.#queue.shift();
+                    if (this.aborted) {
+                        entry.resolvers.reject(this.signal.reason);
+                        return;
+                    }
+                    entry.resolvers.reject(error);
+                    this.#controller.abort(new HbpuAbortError("failed", { cause: error }));
+                    return;
+                }
+            }
+        }
+        finally {
+            this.#processing = false;
+        }
+    }
+    // Teardown convergence point, fired exactly once when `this.signal` aborts. Rejects every pending entry with the signal's reason, regardless of whether the drain
+    // loop is currently processing. Promise resolvers are idempotent after first settlement, so if the drain loop's catch branch also rejects the in-flight resolver
+    // (e.g., when `events.once(..., { signal })` rejects on the same abort), the second call is a no-op. Draining the queue unconditionally here prevents the
+    // stream-error escalation path from orphaning queued resolvers - `#drain`'s catch shifts the in-flight entry and then calls `this.#controller.abort(...)`, which
+    // fires this listener synchronously while the remaining queued entries are still in the queue.
+    #teardown() {
+        // `signal.reason` is typed `any` in the DOM lib. The `: unknown` annotation narrows it to `unknown` for the `@typescript-eslint/no-unsafe-assignment` rule, which
+        // surfaces stray `any` values on assignment. `unknown` flows through `resolvers.reject()` unchanged - reject accepts any value.
+        const reason = this.signal.reason;
+        const pending = this.#queue.splice(0);
+        for (const entry of pending) {
+            entry.resolvers.reject(reason);
+        }
+    }
+}
+//# sourceMappingURL=backpressure.js.map

package/dist/backpressure.js.map

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