homebridge-plugin-utils 1.35.0 → 2.1.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

@@ -1,79 +1,128 @@
+import type { Nullable } from "./util.ts";
+import type { Writable } from "node:stream";
 /**
- * Backpressure-aware write queue for Node.js writable streams.
+ * 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.
  *
- * This module provides a utility class for writing data to a writable stream while respecting backpressure signals. It maintains an internal queue and serializes writes,
- * pausing when the stream signals it isn't ready and resuming when it drains. This is particularly useful when feeding data from an event-driven source (e.g., fMP4
- * segments from a livestream) into a process stdin that may not consume data as fast as it arrives.
+ * Separate from the "writer has aborted" and "underlying stream is dead" failure modes so callers can distinguish backpressure-overflow (back off and retry later)
+ * from terminal failures (give up or escalate) by type rather than by inspecting error message text.
  *
- * @module
+ * @category Utilities
  */
-import type { Nullable } from "./util.js";
-import type { Writable } from "node:stream";
+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);
+}
 /**
- * A backpressure-aware write queue that serializes writes to a writable stream, pausing when the stream signals backpressure and resuming on drain.
+ * Construction-time options for {@link BackpressureWriter}.
  *
- * The stream is resolved lazily via a getter function on each write, allowing the writer to be created before the stream exists and to handle stream replacement across
- * process restarts.
+ * @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
- * // Create a writer that feeds segments to an FFmpeg process stdin.
- * const writer = new BackpressureWriter(() => ffmpegProcess.stdin ?? null);
+ * import { BackpressureWriter } from "homebridge-plugin-utils";
  *
- * // Enqueue segments as they arrive from a livestream source.
- * livestream.on("segment", (segment) => writer.write(segment));
+ * await using writer = new BackpressureWriter(() => ffmpegProcess.stdin ?? null, { signal: session.signal });
  *
- * // When the session ends, close the writer to release pending data.
- * writer.close();
+ * // 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 {
-    private drainListener;
-    private drainStream;
-    private readonly getStream;
-    private isClosed;
-    private isWriting;
-    private readonly onWrite;
-    private readonly queue;
+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;
     /**
-     * Creates a new backpressure-aware write queue.
+     * Construct a new backpressure-aware writer.
      *
-     * @param getStream    - A function that returns the current writable stream, or `null` if the stream is unavailable. Evaluated on each write attempt, allowing the
-     *                        writer to be created before the stream exists or to track a stream that changes across process restarts. For a static stream, wrap it in an
-     *                        arrow function: `() => stream`.
-     * @param onWrite      - Optional. A callback invoked after each segment is successfully written to the underlying stream. Useful for tracking write statistics.
+     * @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
-     * // Lazy resolution...the stream is resolved on each write.
-     * const writer = new BackpressureWriter(() => this.ffmpegProcess?.stdin ?? null, () => segmentCount++);
-     *
-     * // Static stream...wrap in an arrow function.
-     * const writer = new BackpressureWriter(() => stream);
+     * await using writer = new BackpressureWriter(() => this.ffmpegProcess?.stdin ?? null, { highWaterMark: 64, signal: session.signal });
      * ```
      */
-    constructor(getStream: () => Nullable<Writable>, onWrite?: () => void);
+    constructor(streamProvider: () => Nullable<Writable>, init?: BackpressureWriterInit);
     /**
-     * Enqueues data to be written to the stream. If the stream is available and not under backpressure, the data is written immediately. Otherwise, it is queued and
-     * written when the stream signals it is ready via the drain event.
+     * 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.
      *
-     * @param data         - The buffer to write to the stream.
+     * @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 Returns `true` if the data was accepted (stream is available), `false` if the stream is unavailable or the writer has been closed.
+     * @returns A promise that resolves once the drain loop has fully exited.
      */
-    write(data: Buffer): boolean;
+    [Symbol.asyncDispose](): Promise<void>;
     /**
-     * Closes the writer, clearing any pending data and removing drain listeners. After closing, all subsequent writes are rejected. This should be called when the
-     * underlying stream is being shut down or the session is ending.
+     * `true` once `this.signal` has aborted. Derived from the signal; no independent state.
      */
-    close(): void;
+    get aborted(): boolean;
     /**
-     * Returns the number of segments currently queued and waiting to be written.
+     * 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;
-    private processQueue;
 }
+//# sourceMappingURL=backpressure.d.ts.map