homebridge-plugin-utils 1.35.0 → 2.0.0

package/dist/util.js

@@ -2,138 +2,843 @@
  *
  * util.ts: Useful utility functions when writing TypeScript.
  */
-/**
- * TypeScript Utilities.
- *
- * @module
- */
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { setTimeout as delay } from "node:timers/promises";
 // Validates a name against HomeKit's naming conventions. Compiled once at module scope since this sits on the fast path of sanitizeName().
 const VALID_HOMEKIT_NAME = /^(?!.*\p{Extended_Pictographic})(?!.* {2})(?=^[\p{L}\p{N}].*[\p{L}\p{N}.]$)[\p{L}\p{N}\-"'.,#& ]+$/u;
+// A sentinel AbortSignal that never aborts. Helpers that accept an optional caller signal fall back to this so internal code can always address a non-nullable signal,
+// without branching for the "no signal supplied" case on every operation. Shared module-scope constant rather than per-call allocation - the underlying platform
+// AbortController that produced it is unreferenced after module init, leaving the signal in a permanent unaborted state for the module's lifetime.
+const NEVER_ABORTED_SIGNAL = new AbortController().signal;
+// Shared no-op reaction used by {@link markHandled} to mark promises as observed. Module-scope constant keeps the identity stable across call sites so attaching the
+// reaction is a single function-reference pass rather than a fresh closure allocation per call.
+const MARK_HANDLED_NOOP = () => { };
+// Shared no-op `Disposable` returned by {@link onAbort} on the pre-aborted branch (where no listener was registered and there is nothing to remove). Hoisted to
+// module scope so every pre-aborted call reuses one instance instead of allocating a fresh object + arrow pair - matching the established pattern for other shared
+// module-scope constants in this file (`NEVER_ABORTED_SIGNAL`, `MARK_HANDLED_NOOP`). Safe to share because the disposer is stateless, idempotent, and side-effect
+// free: `[Symbol.dispose]()` can be invoked any number of times from any call site without interference.
+const NO_OP_DISPOSABLE = { [Symbol.dispose]: () => { } };
 /**
- * A utility method that formats a bitrate value into a human-readable form as kbps or Mbps.
+ * The canonical abort error used across `homebridge-plugin-utils`.
  *
- * @param value           - The bitrate value to convert.
+ * `HbpuAbortError` is a lightweight subclass of `Error` whose `name` field is one of the values in {@link HbpuAbortReason}. It is the value passed to
+ * `AbortController.abort(reason)` by every HBPU-owned resource class and is surfaced back to callers as a signal's `reason` or as the rejection of any HBPU-awaited
+ * promise that ends because of an abort.
+ *
+ * @remarks The base class is intentionally minimal. Domain-specific context (FFmpeg exit code, MQTT packet id, etc.) travels on `cause` as a structured object rather
+ * than as additional fields on this class, so that every consumer that catches an `HbpuAbortError` reads the same shape. Specialized subclasses (e.g.,
+ * `FfmpegAbortError` carrying typed exit context) may be introduced later when there is a concrete need - not preemptively.
  *
- * @returns Returns the value as a human-readable string.
  * @example
  *
  * ```ts
- * formatBps(500);        // "500 bps".
- * formatBps(2000);       // "2.0 kbps".
- * formatBps(15000);      // "15.0 kbps".
- * formatBps(1000000);    // "1.0 Mbps".
- * formatBps(2560000);    // "2.6 Mbps".
+ * import { HbpuAbortError, isHbpuAbortReason } from "homebridge-plugin-utils";
+ *
+ * try {
+ *
+ *   await recording.segments().next();
+ * } catch(error: unknown) {
+ *
+ *   if(isHbpuAbortReason(error, "replaced")) {
+ *
+ *     // Stream was superseded; this is expected during a livestream discontinuity.
+ *     return;
+ *   }
+ *
+ *   throw error;
+ * }
  * ```
+ *
+ * @category Utilities
  */
-export function formatBps(value) {
-    // Return the bitrate as-is.
-    if (value < 1000) {
-        return value.toString() + " bps";
+export class HbpuAbortError extends Error {
+    /**
+     * The discriminator. Matches one of {@link HbpuAbortReason}.
+     */
+    name;
+    /**
+     * Construct a new `HbpuAbortError`.
+     *
+     * @param reason    - The abort reason (also assigned to `.name`).
+     * @param options   - Optional `cause` for structured diagnostic context, and an optional human-readable `message`.
+     */
+    constructor(reason, options = {}) {
+        super(options.message ?? reason, { cause: options.cause });
+        this.name = reason;
     }
-    // Return the bitrate in kilobits.
-    if (value < 1000000) {
-        const kbps = value / 1000;
-        return ((kbps % 1) === 0 ? kbps.toFixed(0) : kbps.toFixed(1)) + " kbps";
+}
+/**
+ * Type guard: returns `true` if `error` is an {@link HbpuAbortError}.
+ *
+ * Use this to discriminate HBPU's canonical abort errors from arbitrary thrown values, without nesting `instanceof` checks.
+ *
+ * @param error - The value to test.
+ *
+ * @returns `true` if `error` is an `HbpuAbortError` instance.
+ *
+ * @category Utilities
+ */
+export function isHbpuAbortError(error) {
+    return error instanceof HbpuAbortError;
+}
+/**
+ * Convenience type predicate: returns `true` if `error` is an {@link HbpuAbortError} whose `.name` matches `reason`, and narrows the type so callers can read
+ * `error.cause` and related fields without further casts.
+ *
+ * Collapses the common "is this an HBPU abort, and was it this specific reason?" question into a single call, avoiding the `instanceof` + `.name` nesting that appears
+ * throughout consuming code. The generic parameter `R` preserves the specific reason string in the narrowed type so callers that discriminate further by name get the
+ * literal narrowed form automatically.
+ *
+ * @typeParam R - The specific reason being matched. Defaulted by inference from `reason`.
+ * @param error   - The value to test.
+ * @param reason  - The abort reason to match.
+ *
+ * @returns `true` if `error` is an `HbpuAbortError` with the given reason.
+ *
+ * @category Utilities
+ */
+export function isHbpuAbortReason(error, reason) {
+    return isHbpuAbortError(error) && (error.name === reason);
+}
+/**
+ * Test whether an abort reason indicates a timeout. Matches both the canonical {@link HbpuAbortError} with `"timeout"` name - produced by project watchdogs
+ * ({@link Watchdog}, the inactivity monitors on `FfmpegProcess` / `RtpDemuxer` / `Mp4SegmentAssembler`) - and the platform {@link DOMException}/`Error` whose
+ * `.name === "TimeoutError"` - produced by `AbortSignal.timeout()`. Consumers discriminate on a single predicate regardless of which code path originated the timeout.
+ *
+ * Exists because every long-lived resource class exposes an `isTimedOut` getter with identical branching logic; routing all of them through this single predicate
+ * enforces one taxonomy and eliminates drift if the project ever needs to add, say, a third timeout shape (e.g., an upstream-framework cancellation).
+ *
+ * @param reason - Any value found on `AbortSignal.reason`. Plain objects, non-errors, and `undefined` all return `false`.
+ *
+ * @returns `true` when the reason is a timeout in either supported shape.
+ *
+ * @category Utilities
+ */
+export function isTimeoutReason(reason) {
+    if (isHbpuAbortReason(reason, "timeout")) {
+        return true;
     }
-    // Return the bitrate in megabits.
-    const mbps = value / 1000000;
-    return ((mbps % 1) === 0 ? mbps.toFixed(0) : mbps.toFixed(1)) + " Mbps";
+    // Platform `TimeoutError` from `AbortSignal.timeout()` - a `DOMException` (extends `Error` in Node) whose `.name === "TimeoutError"`. The `instanceof Error` guard
+    // excludes bare objects that happen to carry a coincidental `.name` field.
+    return (reason instanceof Error) && (reason.name === "TimeoutError");
 }
 /**
- * A utility method that retries an operation at a specific interval for up to an absolute total number of retries.
+ * Register a one-shot abort handler on `signal` and return a {@link Disposable} whose `[Symbol.dispose]` removes the listener. If `signal` is already aborted at
+ * call time, `handler` runs inline and the returned handle is a no-op disposer.
+ *
+ * Closes the well-known pitfall in `AbortSignal.addEventListener("abort", ...)`: listeners attached to an already-aborted signal **do not fire**, so constructors
+ * that take a parent signal and attach teardown logic via `addEventListener` silently skip that teardown when the parent is pre-aborted. This helper unifies the
+ * register-or-dispatch-immediately shape so every caller handles both cases without re-implementing the check.
  *
- * @param operation       - The operation callback to try until successful.
- * @param retryInterval   - Interval to retry, in milliseconds.
- * @param totalRetries    - Optionally, specify the total number of retries.
+ * Returning a `Disposable` serves two patterns through one primitive:
  *
- * @returns Returns `true` when the operation is successful, `false` otherwise or if the total number of retries has been exceeded.
+ * - **Long-lived resource-class registrations** (the common case): every HBPU resource class registers its `#teardown` handler in its constructor, intending the
+ *   listener to live until the composed signal aborts. These callers discard the return value; the `{ once: true }` listener auto-unregisters on fire.
+ * - **Scope-bound transient registrations**: observers that only need the listener for a bounded scope (e.g., {@link waitWithSignal}) capture the handle with
+ *   `using` so the listener is deterministically removed on scope exit even when the promise resolves before the signal aborts. This prevents listener accumulation
+ *   on long-lived signals that see many short waits.
  *
- * @remarks `operation` must be an asynchronous function that returns `true` when successful, and `false` otherwise.
+ * The handler runs at most once: on normal abort, via the `{ once: true }` option on `addEventListener`; on pre-aborted signals, via a direct call here. The caller
+ * still decides what to do with the rest of its setup - a constructor that wants to short-circuit further initialization after a pre-aborted signal typically pairs
+ * this call with a subsequent `if(signal.aborted) return;` check.
+ *
+ * @param signal  - The abort signal to observe.
+ * @param handler - The teardown or cleanup action to run once on abort. Invoked synchronously when `signal.aborted` is already `true` at call time; otherwise
+ *                  attached as a one-shot `"abort"` listener.
+ *
+ * @returns A {@link Disposable} handle. `[Symbol.dispose]` removes the abort listener (no-op on the pre-aborted path and after the listener has already fired).
  *
  * @example
+ *
  * ```ts
- * // Example: Retry an async operation up to 5 times, waiting 1 second between each try.
- * let attempt = 0;
- * const result = await retry(async () => {
+ * // Long-lived resource-class registration: discard the returned disposer. The listener lives until the composed signal aborts and `{ once: true }` cleans it up.
+ * constructor(init: { signal?: AbortSignal }) {
+ *
+ *   this.signal = composeSignals(init.signal, this.#controller.signal);
  *
- *   attempt++;
+ *   onAbort(this.signal, () => this.#teardown());
  *
- *   // Simulate a 50% chance of success
- *   return Math.random() > 0.5 || attempt === 5;
- * }, 1000, 5);
+ *   if(this.signal.aborted) {
  *
- * console.log(result); // true if operation succeeded within 5 tries, otherwise false.
+ *     return;
+ *   }
+ *
+ *   // ...proceed with setup that only makes sense on a live signal.
+ * }
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * // Scope-bound transient registration: capture the handle with `using` so the listener auto-removes when the scope exits, even if the signal never aborts.
+ * async function abortableWait<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+ *
+ *   using _registration = onAbort(signal, () => {
+ *     // Abort-driven action goes here.
+ *   });
+ *
+ *   // `return await promise` (not a bare `return promise`) is load-bearing inside an async function. `using` disposes when the enclosing function body finishes
+ *   // executing, and without an `await` the body finishes synchronously at the `return` statement - even though the returned promise is still pending. The
+ *   // listener would therefore be removed the instant the function returned, well before the promise settles. Adding `await` creates a suspension point that
+ *   // keeps the `using` scope alive until the promise actually settles, which is what the "scope-bound registration" pattern relies on.
+ *   return await promise;
+ * }
  * ```
  *
  * @category Utilities
  */
-export async function retry(operation, retryInterval, totalRetries) {
-    let remainingRetries = totalRetries;
-    for (;;) {
-        // If we've exhausted our retries, we're done.
-        if ((remainingRetries !== undefined) && (remainingRetries <= 0)) {
-            return false;
-        }
-        // Try the operation that was requested.
-        // eslint-disable-next-line no-await-in-loop
-        if (await operation()) {
-            return true;
+export function onAbort(signal, handler) {
+    if (signal.aborted) {
+        handler();
+        // Pre-aborted path never registered a listener, so there is nothing to remove. Return the module-scope {@link NO_OP_DISPOSABLE} singleton so the caller's `using`
+        // declaration compiles cleanly and explicit `[Symbol.dispose]()` invocations remain a safe no-op, without allocating a fresh object + arrow pair per call.
+        return NO_OP_DISPOSABLE;
+    }
+    signal.addEventListener("abort", handler, { once: true });
+    // The returned handle lets scope-bound observers remove themselves deterministically when the scope exits, preventing listener accumulation on long-lived signals
+    // that serve many short-lived waits. `removeEventListener` is idempotent - calling it after the listener has already fired (and been auto-removed by `{ once: true }`)
+    // is a safe no-op.
+    return { [Symbol.dispose]: () => signal.removeEventListener("abort", handler) };
+}
+/**
+ * Attach a shared no-op rejection handler to `promise` so that if it rejects and no other observer is attached, Node does not emit an `UnhandledPromiseRejection`
+ * warning. Returns the original promise so callers can mark-and-assign in one expression.
+ *
+ * Use this on internal promise handles (`ready`, `exited`, init segments) that a class exposes for callers who may or may not choose to observe them. Callers who
+ * `await` the promise or attach their own `.catch` still see the rejection through their own chain - this helper only marks the promise as observed for Node's
+ * unhandled-rejection tracker.
+ *
+ * @typeParam T  - The resolved value type.
+ * @param promise - The promise to mark handled.
+ *
+ * @returns The same promise, for chained assignment.
+ *
+ * @example
+ *
+ * ```ts
+ * this.ready = markHandled(readyResolvers.promise);
+ * ```
+ *
+ * @category Utilities
+ */
+// Identity-preserving helper: returns the caller's promise unchanged so mark-and-assign flows (`this.ready = markHandled(...)`) keep reference equality with the
+// underlying resolver. Marking this `async` would wrap the return in a fresh promise chain and break that contract.
+export function markHandled(promise) {
+    promise.catch(MARK_HANDLED_NOOP);
+    return promise;
+}
+/**
+ * A shippable no-op {@link HomebridgePluginLogging}: every method accepts the logging signature and discards its arguments. A module-scope singleton - the methods are
+ * stateless and side-effect-free, so one shared instance is safe to reuse everywhere - which keeps the omitted-logger path allocation-free. This is the SSOT no-op
+ * logger: callers that need a CONCRETE logger but want no output default to it (e.g. a subsystem whose lower layer requires a non-optional logger), and the test-only
+ * `silentLog` helper derives from it rather than re-declaring the empty sink.
+ *
+ * @category Utilities
+ */
+export const noOpLog = {
+    debug: () => { },
+    error: () => { },
+    info: () => { },
+    warn: () => { }
+};
+// Re-export the magnitude-and-percentage formatters from the browser-safe `formatters.ts` module. `featureOptions.ts` imports them directly from there (so it can
+// ship into `dist/ui/` without dragging in any of util.ts's Node-only imports); util.ts surfaces them here so server-side consumers see the same public API they
+// always did. The single SSOT is `formatters.ts`; this file is just a forwarding seam.
+export { formatBps, formatBytes, formatMs, formatPercent, formatSeconds } from "./formatters.js";
+/**
+ * Render an arbitrary thrown value as a clean log-suffix string. Real `Error` instances surface their `.message`; everything else is coerced through `String(...)`.
+ * A trailing period is stripped in either case so the embedding log line (which itself ends in a period) does not produce ".." at the end of the rendered output.
+ *
+ * @param error - The thrown value, typically caught from a `try` block or rejected Promise.
+ *
+ * @returns The cleaned message ready to interpolate into a log format string.
+ *
+ * @example
+ *
+ * ```ts
+ * try {
+ *
+ *   await someOperation();
+ * } catch(error) {
+ *
+ *   log.error("Operation failed: %s.", formatErrorMessage(error));
+ * }
+ * ```
+ *
+ * @category Utilities
+ */
+export function formatErrorMessage(error) {
+    return ((error instanceof Error) ? error.message : String(error)).replace(/\.$/, "");
+}
+/**
+ * The default backoff policy used by {@link retry}: exponential with a 30-second ceiling, starting at 1 second for the second attempt (`attempt = 2`).
+ *
+ * @param attempt - The attempt number about to be run (1-indexed; never called with `attempt === 1`, since the first attempt runs immediately).
+ *
+ * @returns The delay, in milliseconds, to wait before executing `attempt`.
+ *
+ * @category Utilities
+ */
+export function defaultRetryBackoff(attempt) {
+    return Math.min(30_000, 1_000 * (2 ** (attempt - 2)));
+}
+/**
+ * Retry an async operation with configurable attempts and backoff, with first-class abort signal support.
+ *
+ * The operation receives the caller's {@link AbortSignal} directly (or a permanent never-aborted sentinel when no caller signal was provided). Well-behaved operations
+ * forward this signal to any cancellation-aware API they call (`fetch`, `events.once`, etc.) so the in-flight attempt actually cancels. Between-attempt waits use
+ * `node:timers/promises` `setTimeout` with the signal, so abort also interrupts the backoff.
+ *
+ * @typeParam T           - The successful resolution type of `operation`.
+ * @param operation       - The async work to perform. Receives the composed abort signal; must resolve with a value on success, or throw/reject on failure.
+ * @param options         - Retry options. See {@link RetryOptions}.
+ *
+ * @returns Resolves with the first successful operation result. Rejects with the operation's error once the attempt budget is exhausted or a `shouldRetry` predicate
+ * vetoes a further attempt, or with the signal's reason if aborted mid-attempt or mid-backoff.
+ *
+ * @example
+ *
+ * ```ts
+ * import { retry } from "homebridge-plugin-utils";
+ *
+ * const controller = new AbortController();
+ *
+ * const device = await retry(async (signal) => fetchDevice(id, { signal }), {
+ *
+ *   attempts: 5,
+ *   backoff: (attempt) => 1_000 * attempt,
+ *   signal: controller.signal
+ * });
+ * ```
+ *
+ * @category Utilities
+ */
+export async function retry(operation, options = {}) {
+    const { attempts = 3, backoff = defaultRetryBackoff, shouldRetry, signal } = options;
+    // Reject nonsensical attempt counts at the library boundary so the "attempts >= 1" invariant the loop relies on is enforced rather than latent.
+    if (attempts < 1) {
+        throw new Error("retry: `attempts` must be >= 1.");
+    }
+    // Honor a pre-aborted caller signal immediately - avoids spawning the first attempt just to tear it down.
+    signal?.throwIfAborted();
+    // When the caller provides no signal, fall back to the module-scope never-aborted sentinel so `operation` always receives a non-nullable `AbortSignal`. Avoids
+    // branching inside the hot path each attempt and a per-call controller allocation.
+    const operationSignal = signal ?? NEVER_ABORTED_SIGNAL;
+    // Run each attempt, yielding to the backoff policy between failures. The caller's signal is the single source of truth for cancellation: the outer catch below is the
+    // single normalizer that translates any rejection that coincides with an aborted signal back into `signal.reason`. Each abortable await inside the loop - today the
+    // operation and the backoff wait, tomorrow anything we add - inherits that normalization without owing its own check.
+    try {
+        for (let attempt = 1; attempt <= attempts; attempt++) {
+            try {
+                // eslint-disable-next-line no-await-in-loop
+                return await operation(operationSignal);
+            }
+            catch (error) {
+                // Stop and surface the operation's last error when the attempt budget is exhausted, or when `shouldRetry` vetoes another attempt for this error. The budget
+                // check comes first so an exhausted budget always rethrows and the predicate is consulted only while attempts remain; a `false` verdict rethrows immediately
+                // with no backoff wait. When `shouldRetry` is omitted the optional call yields `undefined` (not `false`), so every error retries until the budget runs out -
+                // the existing behavior. If the caller also aborted here, the outer catch normalizes to the signal's reason.
+                if ((attempt === attempts) || (shouldRetry?.(error, attempt) === false)) {
+                    throw error;
+                }
+                // Wait the policy-dictated delay before the next attempt. If the caller aborts mid-wait, `node:timers/promises` `setTimeout` rejects with a platform
+                // `AbortError` that does NOT carry `signal.reason`; the outer catch consults the signal itself and restores the caller's reason for us.
+                // eslint-disable-next-line no-await-in-loop
+                await delay(backoff(attempt + 1), undefined, { signal });
+            }
         }
-        // If the operation wasn't successful, sleep for the requested interval and try again.
-        if (remainingRetries !== undefined) {
-            remainingRetries--;
+        // Unreachable when `attempts >= 1`: the loop either returns the operation result or rethrows the last attempt's error. TypeScript needs a terminal statement.
+        throw new Error("retry: unreachable after attempt loop");
+    }
+    catch (error) {
+        // Single source of truth for cancellation. Whatever rejection bubbled out of the loop - operation error, backoff-wait `AbortError`, or anything we add later - if
+        // the caller's signal is aborted, the signal's reason is the canonical answer. `throwIfAborted()` is a no-op when the signal is not aborted, so genuine errors
+        // propagate unchanged.
+        signal?.throwIfAborted();
+        throw error;
+    }
+}
+/**
+ * Wait for `promise` to settle, bailing out early if `signal` aborts before it does.
+ *
+ * The canonical primitive for "observe this promise but let a caller cancel the wait." Useful inside async flows that reference an external promise (e.g., a resource
+ * class's internal state) and need to honor a per-call abort signal without modifying the underlying promise. Whichever settles first wins: `promise` resolves/rejects
+ * normally, or the signal aborts and `waitWithSignal` rejects with `signal.reason` - including when the signal was already aborted at call time.
+ *
+ * The abort listener is attached with `{ once: true }` and explicitly removed when the helper settles, so there is no listener leak regardless of which side wins the
+ * race. `promise` is ALWAYS observed via `.then(resolve, reject)` - including on the pre-aborted-signal path - which means attaching `waitWithSignal` to a promise
+ * marks it as handled for Node's unhandled-rejection tracker. Callers do not need to wrap `promise` in {@link markHandled} separately.
+ *
+ * @typeParam T   - The resolved value type of `promise`.
+ * @param promise - The promise to wait on.
+ * @param signal  - The abort signal whose firing interrupts the wait.
+ *
+ * @returns The promise's resolved value.
+ *
+ * @throws `signal.reason` if the signal aborts before `promise` settles, or the original rejection if `promise` rejects first.
+ *
+ * @example
+ *
+ * ```ts
+ * import { waitWithSignal } from "homebridge-plugin-utils";
+ *
+ * try {
+ *
+ *   const initSegment = await waitWithSignal(assembler.initSegment, callerSignal);
+ * } catch {
+ *
+ *   // Caller aborted, or the assembler rejected init. Either way, unwind cleanly.
+ *   return;
+ * }
+ * ```
+ *
+ * @category Utilities
+ */
+export async function waitWithSignal(promise, signal) {
+    const env_1 = { stack: [], error: void 0, hasError: false };
+    try {
+        const { promise: result, resolve, reject } = Promise.withResolvers();
+        // `onAbort` is the single source of truth for "register an abort-driven action, handle the pre-aborted-signal pitfall, and release the listener when done." The
+        // pre-aborted path runs our handler inline (rejecting `result` immediately); the live path attaches the listener with `{ once: true }` and returns a disposer that
+        // we hand off to `using` so the listener is deterministically removed when this function's scope exits. That matters for long-lived signals (e.g., a plugin's
+        // lifetime controller) that see many short waits - without explicit removal, each call would leak a listener until the signal finally aborts.
+        const _abortRegistration = __addDisposableResource(env_1, onAbort(signal, () => reject(signal.reason)), false);
+        // `promise` is ALWAYS observed via `.then(resolve, reject)` - including on the pre-aborted path - so `waitWithSignal` marks it handled for Node's unhandled-rejection
+        // tracker regardless of which side wins the race. The derived `.then` microtask becomes a no-op if it loses the race (reject was already called via the abort path,
+        // or resolve is already settled). The derived promise itself always fulfills (our handlers return void), so discarding it with `void` is safe.
+        void promise.then(resolve, reject);
+        return await result;
+    }
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
+    }
+    finally {
+        __disposeResources(env_1);
+    }
+}
+/**
+ * Drain an async iterable and retain only its last `n` values, returned in original (oldest-to-newest) order.
+ *
+ * The implementation is a true fixed-capacity ring buffer: it allocates a single backing array of length `n` once and overwrites slots modulo `n` as values arrive, so
+ * memory stays bounded at `n` entries no matter how long the source runs. It deliberately does NOT accumulate every value and slice the tail at the end - that naive
+ * shape would grow without bound on a long-running source (the canonical use here is "the last ~500 lines of a multi-MB log seed"), defeating the entire point of a
+ * bounded retainer. When the source yields `n` or fewer values the result is simply those values in order; when it yields more, only the most recent `n` survive.
+ *
+ * Consumption is eager and complete: the source is iterated to exhaustion before returning, so callers must only pass iterables that terminate (a finite seed window,
+ * not an unbounded live stream). A non-positive `n` retains nothing and returns an empty array without iterating the source at all.
+ *
+ * @typeParam T  - The element type of the source.
+ * @param source - The async iterable to drain. Must terminate.
+ * @param n      - The maximum number of trailing values to retain. Values `<= 0` retain nothing.
+ *
+ * @returns The last `n` values produced by `source`, in original order.
+ *
+ * @example
+ *
+ * ```ts
+ * import { takeLast } from "homebridge-plugin-utils";
+ *
+ * // Retain only the most recent 500 seed lines from a bounded history window, regardless of how many the source emits.
+ * const recent = await takeLast(seedLines, 500);
+ * ```
+ *
+ * @category Utilities
+ */
+export async function takeLast(source, n) {
+    // A non-positive capacity retains nothing. Returning before touching the source avoids both an empty-ring allocation and any iteration side effects the caller did not
+    // ask to pay for.
+    if (n <= 0) {
+        return [];
+    }
+    // The single fixed-capacity backing store. We overwrite slots modulo `n` so the ring never grows beyond `n` entries even on an arbitrarily long source - the explicit
+    // contrast to an accumulate-then-slice approach that would retain every value transiently.
+    const ring = new Array(n);
+    // `count` is the total number of values seen; `write` is the next slot to overwrite. Tracking the raw count (rather than a saturating flag) lets us reconstruct the
+    // correct oldest-to-newest order at the end whether the source under- or over-filled the ring.
+    let count = 0;
+    let write = 0;
+    for await (const value of source) {
+        ring[write] = value;
+        write = (write + 1) % n;
+        count++;
+    }
+    // Under-filled: fewer values than capacity arrived, so the ring's first `count` slots already hold them in order. Slice rather than return the oversized backing array.
+    if (count < n) {
+        return ring.slice(0, count);
+    }
+    // Filled or over-filled: the oldest retained value sits at `write` (the slot we were about to overwrite next), so we read forward from there, wrapping once, to
+    // recover oldest-to-newest order. This single rotation is the only reordering cost, paid once at the end rather than per value.
+    const result = new Array(n);
+    for (let index = 0; index < n; index++) {
+        // The cast is sound here: when `count >= n` every ring slot has been written at least once, so no slot is the initial `undefined` hole `noUncheckedIndexedAccess`
+        // guards against. We narrow the `T | undefined` index read back to `T` with one cast rather than re-checking a value we have already proven present.
+        result[index] = ring[(write + index) % n];
+    }
+    return result;
+}
+/**
+ * Compose one or more optional {@link AbortSignal} sources into a single signal that aborts when any input aborts.
+ *
+ * Collapses the recurring `parent ? AbortSignal.any([ parent, internal ]) : internal` pattern into a single call, used by every resource class in this library to
+ * compose its lifetime signal. Filters out `undefined` inputs, returns the sole defined signal unchanged (no unnecessary `any()` wrapper), and composes two or more
+ * defined signals with `AbortSignal.any()`.
+ * Throws a {@link TypeError} when every input is `undefined`, because a class whose lifetime is defined by a signal must always have at least one concrete signal to
+ * compose against.
+ *
+ * @param signals - Ordered list of signal sources. `undefined` entries are filtered out; order is preserved among defined entries.
+ *
+ * @returns The single defined signal when only one was supplied; otherwise a new signal that aborts as soon as any input aborts, carrying the first aborting input's
+ *          reason as its own `reason`.
+ *
+ * @throws `TypeError` if every input is `undefined` - the caller passed no concrete signal to compose.
+ *
+ * @example
+ *
+ * ```ts
+ * // Class constructor composing an optional parent signal with the internal controller's signal.
+ * this.signal = composeSignals(init.signal, this.#controller.signal);
+ *
+ * // Per-call composition of the class signal with a caller-supplied per-call signal.
+ * const composed = composeSignals(this.signal, init.signal);
+ *
+ * // Compose an optional caller signal with a derived watchdog timeout.
+ * const composed = composeSignals(init.signal, AbortSignal.timeout(PROBE_DEFAULT_TIMEOUT_MS));
+ * ```
+ *
+ * @category Utilities
+ */
+export function composeSignals(...signals) {
+    const defined = signals.filter((signal) => signal !== undefined);
+    const [first, ...rest] = defined;
+    // At least one concrete signal is required. A class whose lifetime is expressed by a signal cannot exist without one; surfacing the misuse at the boundary catches
+    // the mistake loudly rather than silently producing a signal that can never abort.
+    if (first === undefined) {
+        throw new TypeError("composeSignals: at least one signal must be provided.");
+    }
+    // Short-circuit when only one signal was defined. Wrapping a single signal in `AbortSignal.any([ ... ])` would allocate a derived signal with no behavioral benefit,
+    // so we return the input unchanged. Preserves reference equality for callers who compare against the input.
+    if (rest.length === 0) {
+        return first;
+    }
+    return AbortSignal.any(defined);
+}
+/**
+ * Supervise a detached, signal-bound async loop: run the loop, resolve quietly when it ends or its signal aborts, and route any genuine fault to a caller-supplied
+ * handler exactly once.
+ *
+ * Resilient background loops - membership observers, reachability probes, telemetry firehoses - all share one subtle, correctness-critical invariant: a throw is a
+ * *fault* only when we did not cause it. When the bound signal is aborted, a throw is the orderly unwinding of a loop the caller already tore down, so it is swallowed
+ * silently. Any other throw is a genuine fault and is handed to `onError` exactly once. Hand-copying that swallow-on-abort-versus-surface-once discrimination across
+ * call sites that share no ancestor is how it drifts apart; owning it in one generic primitive is how it stays consistent.
+ *
+ * The home is here, beside {@link composeSignals}, because the envelope is fully generic - it carries no logging policy, no message wording, and makes no detachment
+ * decision of its own. When the loops to supervise live on objects with no common base class (so the shared logic cannot be a method), this free function is the only
+ * shared home. The returned promise NEVER rejects as a consequence of the loop: it resolves when the loop returns (a finite source ending), when the signal aborts
+ * (orderly teardown, swallowed), or once a genuine fault has been delivered to `onError`. The caller owns the rest - `void` the result to fire-and-forget a detached
+ * loop, or `await` it for orderly shutdown and in tests.
+ *
+ * @param options          - Supervision inputs.
+ * @param options.loop     - The loop to run, once. It receives the bound {@link AbortSignal} so it can wire cancellation into `observe()` / `fetch()` / stream reads.
+ * @param options.onError  - Invoked at most once, with the thrown value unchanged, when the loop faults while the signal is NOT aborted. It carries the caller's entire
+ *                           fault policy (logging, wording, recovery), which is why the primitive itself stays logging-free. A throw from `onError` is a defect in the
+ *                           handler and propagates - the never-rejects guarantee covers the loop, not the handler.
+ * @param options.signal   - The signal the loop is bound to. Its aborted state is the single source of truth for "did we cause this throw?": aborted means swallow,
+ *                           not aborted means surface.
+ *
+ * @returns A promise that resolves when the loop ends, the signal aborts, or a fault has been delivered to `onError`. It does not reject for any of those outcomes.
+ *
+ * @example
+ *
+ * ```ts
+ * import { superviseLoop } from "homebridge-plugin-utils";
+ *
+ * // Fire-and-forget a detached observer that survives transient faults until its controller is torn down. Aborting `this.signal` unwinds the loop silently; any other
+ * // failure is surfaced once through the caller's own wording.
+ * void superviseLoop({
+ *
+ *   loop: async (signal) => {
+ *
+ *     for await (const event of client.observe(selector, { signal })) {
+ *
+ *       this.handle(event);
+ *     }
+ *   },
+ *   onError: (error) => this.log.error("The membership observer stopped unexpectedly and will not restart until the next reload: %s", formatErrorMessage(error)),
+ *   signal: this.signal
+ * });
+ * ```
+ *
+ * @category Utilities
+ */
+export async function superviseLoop(options) {
+    const { loop, onError, signal } = options;
+    // Run the loop bound to its signal. The loop forwards `signal` into whatever cancellable work it drives, so tearing the signal down unwinds the loop from the inside.
+    try {
+        await loop(signal);
+    }
+    catch (error) {
+        // The one invariant this primitive centralizes: discriminate orderly teardown from a genuine fault. An aborted signal means this throw is the loop unwinding in
+        // response to a teardown we initiated, so it is expected and is swallowed silently. Otherwise the loop faulted on its own, and we surface it through `onError`
+        // exactly once. Either branch resolves the returned promise rather than rejecting it, so a detached caller never produces an unhandled rejection.
+        if (signal.aborted) {
+            return;
         }
-        // eslint-disable-next-line no-await-in-loop
-        await sleep(retryInterval);
+        onError(error);
     }
 }
 /**
- * Run a promise with a guaranteed timeout to complete.
+ * Build the standard {@link superviseLoop} `onError` handler: a reporter that logs a faulted supervised loop with one canonical message, rendering the thrown value
+ * through {@link formatErrorMessage}.
+ *
+ * `superviseLoop` is deliberately logging-free - it owns the swallow-on-abort-versus-surface-once control flow and nothing else, so the wording of what to say when a
+ * loop dies lives here, in an explicitly logging companion, never in the primitive itself. Plugins that supervise the same shape of loop - a client observe-loop bound
+ * to a terminal shutdown signal with no auto-respawn - all owe the operator the same report: the fault is terminal until the next restart, so the message says exactly
+ * that and hands over the one actionable hint. Single-sourcing the template and the formatting here keeps that report from being hand-copied (and quietly drifting)
+ * across plugins that share no ancestor - the same "no shared home, so a free function is the home" situation {@link superviseLoop} itself answers.
+ *
+ * The wording is specific to that bound-to-shutdown, no-respawn lifecycle. A consumer whose loops recover on their own - reconnecting, re-arming, respawning - has
+ * different news to deliver and should pass its own `onError` to {@link superviseLoop} rather than this reporter.
+ *
+ * @param log   - The plugin logger the report is written to; its `error` method receives the canonical format string and arguments.
+ * @param label - The loop's name, interpolated as the `%s` in `"HomeKit updates for %s ..."` so anyone reading the log can tell which supervised loop died.
+ *
+ * @returns The `(error) => void` handler to hand to {@link superviseLoop}'s `onError`. It logs exactly once per fault and returns nothing.
+ *
+ * @example
+ *
+ * ```ts
+ * import { loopFaultReporter, superviseLoop } from "homebridge-plugin-utils";
+ *
+ * // The standard supervised observer: swallow on shutdown, and on a genuine fault log the canonical "<label> loop died, restart to recover" report exactly once.
+ * void superviseLoop({
+ *
+ *   loop: (signal) => this.observeMembership(signal),
+ *   onError: loopFaultReporter(this.log, "membership"),
+ *   signal: this.signal
+ * });
+ * ```
+ *
+ * @category Utilities
+ */
+export function loopFaultReporter(log, label) {
+    // Return the closure that *is* the `onError`: it logs the one canonical "supervised loop died" line, deferring error rendering to `formatErrorMessage` so the trailing
+    // period is normalized to one and the wording matches every other error log in the package rather than being re-derived at this call site.
+    return (error) => log.error("HomeKit updates for %s stopped unexpectedly and will not resume until the Homebridge plugin restarts: %s.", label, formatErrorMessage(error));
+}
+/**
+ * Run an abortable operation with signal-based cancellation.
+ *
+ * The caller provides a factory function that receives an {@link AbortSignal}. The signal fires when the timeout expires, when the caller's own signal aborts, or
+ * whichever comes first when both are provided. The factory must forward this signal to any API that accepts one (`events.once`, `fetch`, Node stream methods, etc.) so
+ * the underlying work is actually cancelled. When the signal fires and the factory rejects, the rejection is caught and `null` is returned. Genuine (non-abort) errors
+ * from the factory propagate normally.
  *
- * @typeParam T           - The type of value the promise resolves with.
- * @param promise         - The promise you want to run.
- * @param timeout         - The amount of time, in milliseconds, to wait for the promise to resolve.
+ * @typeParam T           - The type of value the factory's promise resolves with.
+ * @param fn              - A factory that receives the composed abort signal and returns the promise to await.
+ * @param options         - Abort options. Provide `timeout` (milliseconds), an external `signal`, or both.
  *
- * @returns Returns the result of resolving the promise it's been passed if it completes before timeout, or null if the timeout expires. The internal timer is cleaned
- * up regardless of which outcome wins the race. Note that the underlying promise is not cancelled...it continues to run, but its result is ignored.
+ * @returns Resolves with the factory's result if it completes before abort, or `null` if the signal fires first.
  *
  * @example
  * ```ts
- * // Resolves in 100ms, timeout is 500ms, so it resolves to 42.
- * const result = await runWithTimeout(Promise.resolve(42), 500);
- * console.log(result); // 42
+ * // Timeout only - cancel after 500ms.
+ * const result = await runWithAbort((signal) => fetch(url, { signal }), { timeout: 500 });
  *
- * // Resolves in 1000ms, timeout is 500ms, so it resolves to null.
- * const slowPromise = new Promise<number>(resolve => setTimeout(() => resolve(42), 1000));
- * const result2 = await runWithTimeout(slowPromise, 500);
- * console.log(result2); // null
+ * // External signal only - cancel on demand.
+ * const controller = new AbortController();
+ * const result2 = await runWithAbort((signal) => once(emitter, "data", { signal }), { signal: controller.signal });
+ * controller.abort();
+ *
+ * // Both - cancel on demand or after 5 seconds, whichever comes first.
+ * const result3 = await runWithAbort((signal) => once(emitter, "data", { signal }), { signal: controller.signal, timeout: 5000 });
  * ```
  *
  * @category Utilities
  */
-export async function runWithTimeout(promise, timeout) {
-    let timer;
-    const timeoutPromise = new Promise((resolve) => { timer = setTimeout(() => { resolve(null); }, timeout); });
-    return Promise.race([promise, timeoutPromise]).finally(() => { clearTimeout(timer); });
+export async function runWithAbort(fn, options) {
+    // Route through `composeSignals` so this helper uses the same signal-composition primitive every other HBPU resource class uses. The discriminated union
+    // guarantees at least one of `signal` / `timeout` is defined, which means `composeSignals` always receives at least one concrete signal and never throws its
+    // empty-input guard. When only a timeout is supplied, `composeSignals` returns that single timeout signal unwrapped (no needless `AbortSignal.any` allocation).
+    const callerSignal = ("signal" in options) ? options.signal : undefined;
+    const timeoutSignal = (options.timeout !== undefined) ? AbortSignal.timeout(options.timeout) : undefined;
+    const signal = composeSignals(callerSignal, timeoutSignal);
+    // If the signal is already aborted, return immediately without starting any work.
+    if (signal.aborted) {
+        return null;
+    }
+    // Run the factory and let the signal handle cancellation. We check `signal.aborted` rather than inspecting the error type because the signal is the source of truth
+    // for cancellation state...the exception type varies by API and abort reason (AbortError from manual abort, TimeoutError from AbortSignal.timeout(), or any custom
+    // reason). Genuine errors that occur before the signal fires propagate normally.
+    try {
+        return await fn(signal);
+    }
+    catch (error) {
+        // The signal's aborted state changes asynchronously while the factory is running...the early-out check above doesn't constrain this.
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (signal.aborted) {
+            return null;
+        }
+        throw error;
+    }
 }
 /**
- * Emulate a sleep function.
+ * Re-armable inactivity watchdog.
+ *
+ * Every long-lived resource class in this library that cares about liveness - an FFmpeg stream's return-port UDP socket, the fMP4 segment assembler's inter-segment
+ * pacing, the RTP demuxer's inbound-packet cadence - composes a single `Watchdog` instance to implement the shared "abort if no activity within window" pattern.
+ *
+ * The semantics are minimal on purpose:
  *
- * @param sleepTimer      - The amount of time to sleep, in milliseconds.
+ *   - `arm()` starts the window. If a previous arm is still pending, it is replaced; if the observed signal has already aborted or the watchdog has been disposed, the
+ *     call is a no-op.
+ *   - If nothing calls `arm()` again within `timeoutMs`, `onFire` runs - but only if the signal is still unaborted at that instant, so a last-moment concurrent abort
+ *     wins the race and the callback is skipped.
+ *   - When the observed signal aborts for any reason, the watchdog self-cleans its pending timer; the consumer never needs to unwire it at teardown.
+ *   - `clear()` cancels any pending fire without aborting anything and leaves the watchdog re-armable.
+ *   - `[Symbol.dispose]` clears the pending fire and marks the watchdog permanently dead: subsequent `arm()` calls are no-ops. This matches the scope-bound semantics
+ *     callers expect from `using` - the resource is dead when the block exits, not merely quiescent.
  *
- * @returns Returns a promise that resolves after the specified time elapses.
+ * This is a `Disposable` (synchronous) rather than `AsyncDisposable` because cancelling a timer is synchronous; there is no background work to await.
  *
  * @example
- * To sleep for 3 seconds before continuing execute:
  *
  * ```ts
- * await sleep(3000)
+ * using watchdog = new Watchdog({
+ *
+ *   onFire: () => this.#controller.abort(new HbpuAbortError("timeout")),
+ *   signal: this.signal,
+ *   timeoutMs: this.#inactivityWindowMs
+ * });
+ *
+ * // Each time a packet / segment / message arrives, re-arm so the fire never fires.
+ * this.#source.on("data", () => watchdog.arm());
+ * watchdog.arm();
  * ```
  *
  * @category Utilities
  */
-export async function sleep(sleepTimer) {
-    return new Promise(resolve => setTimeout(resolve, sleepTimer));
+export class Watchdog {
+    #onFire;
+    #signal;
+    #timeoutMs;
+    #timer;
+    // Set to `true` exactly once when `[Symbol.dispose]` runs. Tracks "caller is done with this watchdog" as a distinct concept from "the observed signal aborted" - the
+    // latter can happen without disposal (normal lifetime end), and disposal can happen without signal abort (scope-bound `using` inside a longer-lived context). Both
+    // paths converge on the same observable behavior: `arm()` becomes a no-op.
+    #disposed = false;
+    /**
+     * Construct a new watchdog. The watchdog is dormant until the first `arm()` call, so construction itself schedules no timers.
+     *
+     * A cleanup handler is registered on `init.signal` through {@link onAbort} so the watchdog auto-cleans when the lifetime signal aborts - consumers do not need to
+     * wire teardown manually. On a pre-aborted signal `onAbort` runs the cleanup inline; `clear()` is a no-op on a freshly-constructed watchdog (no timer has been
+     * armed yet), so the pre-aborted path unwinds harmlessly. A later `arm()` short-circuits on the same aborted check, so no timer is ever scheduled either way.
+     *
+     * @param init - Required init options. See {@link WatchdogInit}.
+     */
+    constructor(init) {
+        this.#onFire = init.onFire;
+        this.#signal = init.signal;
+        this.#timeoutMs = init.timeoutMs;
+        // Self-cleaning via the unified `onAbort` primitive: a pending timer after signal abort would only fire, see the aborted guard, and no-op. Clearing proactively
+        // keeps active-timer counts accurate across short-lived watchdogs and lets the event loop exit promptly in tests that hold no other references. This is a long-
+        // lived registration - the returned disposer is discarded because the listener is intended to live until the signal fires, and `onAbort`'s `{ once: true }` auto-
+        // removes it on fire.
+        onAbort(this.#signal, () => this.clear());
+    }
+    /**
+     * Start or restart the inactivity window. The pending timer (if any) is cancelled and a fresh one is scheduled for `timeoutMs` in the future. A no-op when the
+     * observed signal has already aborted or the watchdog has been disposed - in either state there is nothing live to protect, and scheduling a timer would violate the
+     * `using` contract callers rely on.
+     */
+    arm() {
+        if (this.#disposed || this.#signal.aborted) {
+            return;
+        }
+        if (this.#timer !== undefined) {
+            clearTimeout(this.#timer);
+        }
+        this.#timer = setTimeout(() => {
+            // Null the handle first so a re-entrant `clear()` inside `onFire` is a cheap no-op and so observers inspecting `#timer` post-fire see the correct state.
+            this.#timer = undefined;
+            // Lose a tight race against a concurrent abort cleanly: if the signal fired between timer scheduling and the callback running, the aborted state already
+            // expresses the outcome and `onFire` is redundant at best, double-teardown at worst. Disposal sets the same invariant through a different gate.
+            if (this.#disposed || this.#signal.aborted) {
+                return;
+            }
+            this.#onFire();
+        }, this.#timeoutMs);
+    }
+    /**
+     * Cancel any pending fire without aborting anything and without marking the watchdog as permanently dead. Subsequent `arm()` calls continue to work. Safe to call
+     * when no arm is pending - the method is idempotent.
+     */
+    clear() {
+        if (this.#timer !== undefined) {
+            clearTimeout(this.#timer);
+            this.#timer = undefined;
+        }
+    }
+    /**
+     * `Disposable` implementation. Clears any pending fire AND permanently disables the watchdog: after this runs, `arm()` is a no-op and no further `onFire` calls can
+     * occur. This is the contract `using watchdog = new Watchdog(...)` relies on - the resource is dead when the block exits, not merely quiescent. Idempotent; repeated
+     * disposal is a no-op. Because the class does not own an abort controller, disposal does not signal anything to the rest of the system.
+     */
+    [Symbol.dispose]() {
+        this.#disposed = true;
+        this.clear();
+    }
 }
 /**
  * Start case a string, capitalizing the first letter of each word unconditionally.