homebridge-plugin-utils 1.35.0 → 2.1.0

package/dist/ffmpeg/stream.js

@@ -1,187 +1,158 @@
 /* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
  *
- * ffmpeg/stream.ts: Provide FFmpeg process control to support HomeKit livestreaming.
+ * ffmpeg/stream.ts: FFmpeg process control for HomeKit livestreaming with signal-driven stream-health monitoring.
  */
-import { FFMPEG_INPUT_TIMEOUT } from "./settings.js";
+/**
+ * HomeKit livestreaming FFmpeg process with a signal-driven internal stream-health monitor.
+ *
+ * This module defines `FfmpegStreamingProcess`, the specialization of {@link FfmpegProcess} for HomeKit live video sessions. The subclass extends the base directly and
+ * composes an internal UDP socket that watches the return port for inbound packets - the HomeKit client's RTCP receiver reports, which flow only once the client is
+ * receiving FFmpeg's output. The watchdog arms on the first such packet; if that return traffic then stops for longer than the configured window the socket aborts the
+ * process with `HbpuAbortError("timeout")` and the base class teardown handles the rest. There is no separate "delegate" surface, no error callbacks,
+ * and no reach-through to the raw ChildProcess - every external interaction is through the inherited `signal`, `ready`, `exited`, `stdin`, `stderr`, `stderrLog`,
+ * `abort()`, and `[Symbol.asyncDispose]`.
+ *
+ * `stdout` stays externally readable on this subclass because HBUP's two-way-audio talkback path forwards stdout bytes to the WebSocket that carries audio from the
+ * camera back to the HomeKit client. Unlike the fMP4 subclasses, there is no internal consumer of the stdout stream that would race with an external reader.
+ *
+ * The stream-health socket is intentionally simpler than {@link ffmpeg/rtp!RtpDemuxer | RtpDemuxer}: its sole job is to detect liveness on a known return port. It
+ * does not classify RTP vs. RTCP or forward packets. Two-way-audio demuxing is `RtpDemuxer`'s responsibility and lives in its own class.
+ *
+ * @module
+ */
+import { HbpuAbortError, Watchdog, onAbort } from "../util.js";
+import { createDgramSocket, loopbackAddress } from "./dgram-util.js";
 import { FfmpegProcess } from "./process.js";
-import { createSocket } from "node:dgram";
+import { STREAM_HEALTH_TIMEOUT } from "./settings.js";
 /**
- * Provides FFmpeg process management and socket handling to support HomeKit livestreaming sessions.
+ * FFmpeg process specialization for HomeKit livestreaming. Extends {@link FfmpegProcess} directly and composes an internal stream-health UDP socket when a return port
+ * is configured.
  *
- * This class extends `FfmpegProcess` to create, monitor, and terminate HomeKit-compatible video streams. Additionally, it invokes delegate hooks for error processing and
- * stream lifecycle management.
+ * Lifecycle is entirely signal-driven: construction spawns the child and (optionally) binds the health socket; the socket watches for inbound packets and aborts the
+ * process with `"timeout"` if the window lapses; the inherited teardown path closes the socket and clears the watchdog timer as part of its signal-abort listener
+ * fan-out. The subclass adds no new public verbs beyond what {@link FfmpegProcess} provides.
  *
  * @example
  *
  * ```ts
- * const streamingDelegate: HomebridgeStreamingDelegate = {
+ * await using proc = new FfmpegStreamingProcess(ffmpegOptions, {
  *
- *   controller,
- *   stopStream: (sessionId) => { ... } // End-of-session cleanup code.
- * };
+ *   args: commandLineArgs,
+ *   returnPort: { ipFamily: "ipv4", port: 50000 },
+ *   signal: session.controller.signal
+ * });
  *
- * const process = new FfmpegStreamingProcess(
+ * await proc.ready;
  *
- *   streamingDelegate,
- *   sessionId,
- *   ffmpegOptions,
- *   commandLineArgs,
- *   { addressVersion: "ipv4", port: 5000 }
- * );
+ * // Observe the process from the session's own control flow. When the health socket detects a stall, proc.signal fires
+ * // with reason "timeout" and proc.exited resolves with the kill-driven exit context. Surface crashes via the owning
+ * // session's error path.
+ * proc.exited.catch((error) => session.onStreamingError(error));
  * ```
  *
- * @see HomebridgeStreamingDelegate
  * @see FfmpegProcess
  *
  * @category FFmpeg
  */
 export class FfmpegStreamingProcess extends FfmpegProcess {
-    /*
-     * The streaming delegate instance responsible for handling stream events and errors.
-     */
-    delegate;
+    // The return-port descriptor requested at construction (verbatim from `init.returnPort`). Undefined when no return port was configured. Read through the
+    // {@link FfmpegStreamingProcess.returnPort} getter, which projects the kernel-assigned port over this descriptor once the bind settles.
+    #requestedReturnPort;
+    // The port the kernel actually bound the health socket to, captured from `socket.address().port` once the `"listening"` event fires. Undefined until then. For
+    // specific-port binds this duplicates {@link #requestedReturnPort}'s port field but the assignment keeps the post-bind read path uniform across both construction
+    // modes (specific port and `port: 0` ephemeral).
+    #assignedReturnPort;
     /**
-     * The unique session identifier for this streaming process.
-     */
-    sessionId;
-    /**
-     * The timeout reference used to monitor UDP stream health.
-     */
-    streamTimeout;
-    /**
-     * Constructs a new FFmpeg streaming process for a HomeKit session.
-     *
-     * Sets up required delegate hooks, creates UDP return sockets if needed, and starts the FFmpeg process. Automatically handles FFmpeg process errors and cleans up on
-     * failures.
-     *
-     * @param delegate         - The Homebridge streaming delegate for this session.
-     * @param sessionId        - The HomeKit session identifier for this stream.
-     * @param ffmpegOptions    - The FFmpeg configuration options.
-     * @param commandLineArgs  - FFmpeg command-line arguments.
-     * @param returnPort       - Optional. UDP port info for talkback support (used for two-way audio in HomeKit for cameras that support it).
-     * @param callback         - Optional. Callback invoked when the stream is ready or errors occur.
+     * Construct and spawn a new streaming FFmpeg process.
      *
-     * @example
+     * Spawning happens synchronously as part of construction. When `init.returnPort` is supplied, the subclass binds a UDP socket and enforces the liveness watchdog; the
+     * socket closes and the watchdog clears as part of the inherited teardown when the signal aborts for any reason.
      *
-     * ```ts
-     * const process = new FfmpegStreamingProcess(delegate, sessionId, ffmpegOptions, commandLineArgs, { addressVersion: "ipv6", port: 6000 });
-     * ```
+     * @param options - Shared {@link FfmpegOptions} configuration (codec support, logger, debug flag, name).
+     * @param init    - Optional init options. See {@link FfmpegStreamingInit}.
      */
-    constructor(delegate, sessionId, ffmpegOptions, commandLineArgs, returnPort, callback) {
-        // Initialize our parent.
-        super(ffmpegOptions);
-        this.delegate = delegate;
-        this.delegate.adjustProbeSize ??= () => { };
-        this.delegate.ffmpegErrorCheck ??= () => undefined;
-        this.delegate.stopStream ??= () => { };
-        this.sessionId = sessionId;
-        // Create the return port for FFmpeg, if requested to do so. The only time we don't do this is when we're standing up
-        // a two-way audio stream - in that case, the audio work is done through RtpSplitter and not here.
-        if (returnPort) {
-            this.createSocket(returnPort);
+    constructor(options, init = {}) {
+        super(options, init);
+        this.#requestedReturnPort = init.returnPort;
+        if (init.returnPort) {
+            this.#startHealthMonitor(init.returnPort, init.healthTimeout ?? STREAM_HEALTH_TIMEOUT);
         }
-        // Start it up, with appropriate error handling.
-        this.start(commandLineArgs, callback, (errorMessage) => {
-            // Stop the stream.
-            this.delegate.stopStream?.(this.sessionId);
-            // Let homebridge know what happened and stop the stream if we've already started.
-            if (!this.isStarted && this.callback) {
-                this.callback(new Error(errorMessage));
-                this.callback = null;
-                return;
-            }
-            // Tell Homebridge to forcibly stop the streaming session.
-            this.delegate.controller.forceStopStreamingSession(this.sessionId);
-            this.delegate.stopStream?.(this.sessionId);
-        });
     }
     /**
-     * Creates and binds a UDP socket for monitoring the health of the outgoing video stream.
+     * The UDP return-port descriptor the health socket is bound to, or `undefined` when no return port was configured. For a specific-port construction
+     * (`init.returnPort.port` non-zero), this descriptor equals `init.returnPort` from the moment the constructor returns; for an ephemeral construction
+     * (`init.returnPort.port === 0`), the `port` field is `0` until the kernel completes the bind, then the kernel-assigned port. Consumers that need the assigned
+     * ephemeral port `await proc.ready` before reading it; in practice the health-socket bind completes well before the FFmpeg child reaches the `ready` signal, so a
+     * post-`ready` read always observes the kernel's pick.
      *
-     * Listens for UDP "message" events, sets and clears timeouts, and handles error/cleanup scenarios. If no messages are received within 5 seconds, forcibly stops the
-     * stream and informs the delegate.
+     * Returns a fresh descriptor on every read; callers must treat the result as read-only. The `ipFamily` field is the verbatim value passed at construction; the
+     * `port` field reads from the live socket-address projection once captured (specific and ephemeral binds converge on a single read path).
      *
-     * @param portInfo - Object containing the address version ("ipv4" or "ipv6") and port number.
+     * @returns The bound return-port descriptor, or `undefined` when no return port was configured.
      */
-    createSocket(portInfo) {
-        let errorListener;
-        let messageListener;
-        const isIPv6 = portInfo.addressVersion === "ipv6";
-        const socket = createSocket(isIPv6 ? "udp6" : "udp4");
-        // Cleanup after ourselves when the socket closes.
-        socket.once("close", () => {
-            if (this.streamTimeout) {
-                clearTimeout(this.streamTimeout);
-            }
-            socket.off("error", errorListener);
-            socket.off("message", messageListener);
+    get returnPort() {
+        if (this.#requestedReturnPort === undefined) {
+            return undefined;
+        }
+        return {
+            ipFamily: this.#requestedReturnPort.ipFamily,
+            port: this.#assignedReturnPort ?? this.#requestedReturnPort.port
+        };
+    }
+    // Bind a UDP socket to the return port and enforce a re-armed inactivity watchdog. Called from the constructor when a return-port descriptor is provided. The
+    // pre-aborted-signal guard is required: if the caller passed an already-aborted parent signal, the base class's teardown runs synchronously during `super()` and
+    // `this.signal` is aborted by the time we get here. Registering an `"abort"` listener on an already-aborted signal does NOT re-dispatch, so the socket and watchdog
+    // timer would leak if we proceeded. Short-circuiting leaves no resources allocated.
+    #startHealthMonitor(returnPort, timeoutMs) {
+        if (this.aborted) {
+            return;
+        }
+        const socket = createDgramSocket(returnPort.ipFamily);
+        // Capture the kernel-assigned port as soon as the bind succeeds. For specific-port binds this duplicates `returnPort.port`; for ephemeral binds (port: 0) this
+        // is where the kernel's pick becomes observable via {@link returnPort}. Wired as `once("listening", ...)` so it fires exactly when the bind transitions to the
+        // listening state - the same moment after which message events can arrive. The handler captures `socket` by closure to avoid `this.#socket`-style reads from
+        // an async event handler.
+        socket.once("listening", () => {
+            this.#assignedReturnPort = socket.address().port;
         });
-        // Handle potential network errors.
-        socket.on("error", errorListener = (error) => {
-            this.log.error("Socket error: %s.", error.name);
-            this.delegate.stopStream?.(this.sessionId);
+        // Inactivity watchdog: if no packets arrive within `timeoutMs`, abort the process with `"timeout"`. Self-cleans when `this.signal` aborts for any other reason,
+        // so the teardown listener below only has to close the socket.
+        const watchdog = new Watchdog({
+            onFire: () => {
+                this.log.debug("Streaming process inactivity watchdog fired after %d ms with no inbound packets.", timeoutMs);
+                this.abort(new HbpuAbortError("timeout"));
+            },
+            signal: this.signal,
+            timeoutMs
         });
-        // Manage our video streams in case we haven't received a stop request, but we're in fact dead zombies.
-        socket.on("message", messageListener = () => {
-            // Clear our last canary.
-            if (this.streamTimeout) {
-                clearTimeout(this.streamTimeout);
+        // Inbound-packet handler and the SOLE arm site for the watchdog. The first inbound packet performs the initial arm; every subsequent packet re-arms it. We do
+        // not inspect the payload - liveness is the only signal this socket cares about.
+        socket.on("message", () => { watchdog.arm(); });
+        // Socket errors on the health port are treated as fatal - if the kernel cannot deliver us packets, we cannot tell the stream is alive. Abort with `"failed"` and
+        // surface the underlying error via `cause` so downstream diagnostics carry the root cause.
+        socket.on("error", (error) => {
+            this.log.error("Streaming process return-port socket error: %s.", error.message);
+            if (!this.aborted) {
+                this.abort(new HbpuAbortError("failed", { cause: error }));
             }
-            // Set our new canary.
-            this.streamTimeout = setTimeout(() => {
-                this.log.debug("Video stream appears to be inactive for 5 seconds. Stopping stream.");
-                this.delegate.controller.forceStopStreamingSession(this.sessionId);
-                this.delegate.stopStream?.(this.sessionId);
-            }, FFMPEG_INPUT_TIMEOUT);
         });
-        // Bind to the port we're opening.
-        socket.bind(portInfo.port, isIPv6 ? "::1" : "127.0.0.1");
-    }
-    /**
-     * Returns the underlying FFmpeg child process, or null if the process is not running.
-     *
-     * @returns The current FFmpeg process, or `null` if not running.
-     *
-     * @example
-     *
-     * ```ts
-     * const ffmpeg = process.ffmpegProcess;
-     *
-     * if(ffmpeg) {
-     *
-     *   // Interact directly with the child process if necessary.
-     * }
-     * ```
-     */
-    get ffmpegProcess() {
-        return this.process;
-    }
-    /**
-     * Handle and logs FFmpeg process errors.
-     *
-     * If a known error condition is detected by the delegate, logs the custom message and returns. For "not enough frames to estimate rate; consider increasing probesize"
-     * errors, invokes the delegate's `adjustProbeSize` hook for automatic tuning. Otherwise, falls back to the parent class's logging.
-     *
-     * @param exitCode - The exit code from FFmpeg.
-     * @param signal   - The signal, if any, used to terminate the process.
-     */
-    logFfmpegError(exitCode, signal) {
-        // We want to process known streaming-related errors due to the performance and latency tweaks we've made to the FFmpeg command line. In some cases we may inform the
-        // user and take no action, in others, we tune our own internal parameters.
-        // Process any specific errors our caller is interested in.
-        const errTest = this.delegate.ffmpegErrorCheck?.(this.stderrLog);
-        if (errTest) {
-            this.log.error(errTest);
-            return;
-        }
-        // Test for probesize errors.
-        if (this.stderrLog.some(logEntry => logEntry.includes("not enough frames to estimate rate; consider increasing probesize"))) {
-            // Let the streaming delegate know to adjust its parameters for the next run and inform the user.
-            this.delegate.adjustProbeSize?.();
-            return;
-        }
-        // Otherwise, revert to our default logging in our parent.
-        super.logFfmpegError(exitCode, signal);
+        // Teardown convergence point: when `this.signal` aborts for any reason, close the socket. The watchdog's timer is handled by its own self-clean listener on the
+        // same signal, so nothing else is owed here. `onAbort` is preferred over bare `addEventListener` even though the early `aborted` short-circuit above already
+        // guards the pre-aborted case for this allocation path - resource-class teardown handlers throughout HBPU go through `onAbort` so no constructor site has to
+        // re-implement the AbortSignal pre-aborted-listener workaround.
+        onAbort(this.signal, () => socket.close());
+        // Bind. Binding may fail asynchronously with an `"error"` event, which the listener above catches.
+        socket.bind(returnPort.port, loopbackAddress(returnPort.ipFamily));
+        // This is an inactivity watchdog, and "inactivity" presupposes prior activity: it watches one thing - a *flowing* return stream that dried up - so it arms only
+        // on the first inbound packet (the message handler above), then re-arms on every subsequent one. There is deliberately NO arm at construction or on `ready`,
+        // because the watchdog must not police startup or establishment. Those are separate concerns owned elsewhere: "did the child process start" is the base-class
+        // optional `startupTimeout` (documented in process.ts), and "did the return stream ever go live" is the consumer's - the HomeKit session lifecycle and the
+        // consumer's establishment gate - which is the only thing that bounds a stream that never delivers a first packet. We do not fold that bound in here, and on the
+        // one-way live-view path that bound stays external to this class, owned by the consumer rather than this watchdog. Arming on `ready` was wrong precisely because a
+        // ready-armed clock starts before any media has round-tripped: on a cold start the first return packet cannot arrive within the window (prime, transcode, SRTP
+        // egress, client decode, client RTCP back all have to complete first), so the clock counts down through that legitimate first-packet latency and false-positives
+        // on a perfectly healthy stream. Arming on the packet itself is immune by construction. Note the message handler arms regardless of `ready`: any datagram that
+        // arrives before stderr does still starts the inactivity clock, so a stream that is already alive never waits on the spawn signal to be protected.
     }
 }
 //# sourceMappingURL=stream.js.map

package/dist/ffmpeg/stream.js.map

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

package/dist/formatters.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Format a bitrate value into a human-readable form as bps, kbps, or Mbps.
+ *
+ * @param value           - The bitrate value to convert, in bits per second.
+ *
+ * @returns Returns the value as a human-readable string.
+ *
+ * @example
+ *
+ * ```ts
+ * formatBps(500);        // "500 bps".
+ * formatBps(2000);       // "2 kbps".
+ * formatBps(15000);      // "15 kbps".
+ * formatBps(2560);       // "2.6 kbps".
+ * formatBps(1000000);    // "1 Mbps".
+ * formatBps(2560000);    // "2.6 Mbps".
+ * ```
+ *
+ * @category Utilities
+ */
+export declare function formatBps(value: number): string;
+/**
+ * Format a byte count into a human-readable form as bytes, KB, MB, GB, or TB. Uses 1024-based thresholds matching the convention every operating system uses for
+ * displaying file and buffer sizes.
+ *
+ * @param value           - The byte count to convert.
+ *
+ * @returns Returns the value as a human-readable string.
+ *
+ * @example
+ *
+ * ```ts
+ * formatBytes(512);                  // "512 bytes".
+ * formatBytes(2048);                 // "2 KB".
+ * formatBytes(1536);                 // "1.5 KB".
+ * formatBytes(1_048_576);            // "1 MB".
+ * formatBytes(2_621_440);            // "2.5 MB".
+ * formatBytes(1_073_741_824);        // "1 GB".
+ * formatBytes(1_099_511_627_776);    // "1 TB".
+ * ```
+ *
+ * @category Utilities
+ */
+export declare function formatBytes(value: number): string;
+/**
+ * Format a millisecond duration into a human-readable form as ms, s, min, or hr. Tiered thresholds match how operators naturally read elapsed time: sub-second
+ * values stay in milliseconds for precision, longer durations promote to seconds, minutes, and hours.
+ *
+ * @param value           - The duration to convert, in milliseconds.
+ *
+ * @returns Returns the value as a human-readable string.
+ *
+ * @example
+ *
+ * ```ts
+ * formatMs(250);          // "250 ms".
+ * formatMs(1500);         // "1.5 s".
+ * formatMs(15000);        // "15 s".
+ * formatMs(90000);        // "1.5 min".
+ * formatMs(5_400_000);    // "1.5 hr".
+ * ```
+ *
+ * @category Utilities
+ */
+export declare function formatMs(value: number): string;
+/**
+ * Format a numeric percentage value into a human-readable form with a trailing percent sign. Applies the same precision policy as the magnitude-based formatters
+ * via the shared internal helper: whole numbers render without a trailing decimal, fractional numbers render to one decimal place.
+ *
+ * @param value           - The percentage value to convert. Treated as already-scaled into percent units (50 means 50%, not 0.5).
+ *
+ * @returns Returns the value as a human-readable string ending in `%`.
+ *
+ * @example
+ *
+ * ```ts
+ * formatPercent(0);        // "0%".
+ * formatPercent(50);       // "50%".
+ * formatPercent(100);      // "100%".
+ * formatPercent(33.333);   // "33.3%".
+ * ```
+ *
+ * @category Utilities
+ */
+export declare function formatPercent(value: number): string;
+/**
+ * Format a second-resolution duration into a human-readable form as s, min, or hr. Same tier semantics as {@link formatMs}, scaled for inputs that arrive already
+ * in seconds rather than milliseconds.
+ *
+ * @param value           - The duration to convert, in seconds.
+ *
+ * @returns Returns the value as a human-readable string.
+ *
+ * @example
+ *
+ * ```ts
+ * formatSeconds(45);          // "45 s".
+ * formatSeconds(90);          // "1.5 min".
+ * formatSeconds(1800);        // "30 min".
+ * formatSeconds(5400);        // "1.5 hr".
+ * ```
+ *
+ * @category Utilities
+ */
+export declare function formatSeconds(value: number): string;
+//# sourceMappingURL=formatters.d.ts.map

package/dist/formatters.js

@@ -0,0 +1,174 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * formatters.ts: Browser-safe magnitude and percentage formatters shared between the server-side `util.ts` surface and the browser-shipped `featureOptions.ts`
+ * model.
+ */
+/**
+ * **Why this file exists.** `featureOptions.ts` ships into `dist/ui/` for the browser to load (via the `copyFeatureOptions` build step). The catalog's built-in
+ * formatter registry needs `formatBps`, `formatBytes`, `formatMs`, `formatPercent`, and `formatSeconds` at runtime - and pulling them from `util.ts` would drag in
+ * `util.ts`'s `node:timers/promises` import, which the browser cannot resolve. This module is the SSOT for the magnitude-rendering policy. It has zero runtime
+ * imports of any kind, so shipping it alongside `featureOptions.js` is safe in any runtime that can execute ES2024+ JavaScript.
+ *
+ * **Precision policy.** Whole numbers render without a trailing decimal place ("5" not "5.0"); fractional numbers render to one decimal place. Centralizing the
+ * precision policy in `formatMagnitude` means tightening it later - more precision, a thousands separator, locale-aware formatting - is a single-line change
+ * rather than a sweep across every format helper.
+ *
+ * **Consumers.** `util.ts` re-exports these for the server-side surface; `featureOptions.ts` imports directly from here to keep its browser-runnable dependency
+ * graph free of `util.ts`. Both consumers share one implementation - the file is the join point.
+ *
+ * @module
+ */
+// Shared magnitude-rendering helper used by every magnitude-based formatter, applying the module's precision policy (see the module doc): whole numbers render with
+// no trailing decimal place, fractional numbers to one decimal place.
+function formatMagnitude(value) {
+    return ((value % 1) === 0 ? value.toFixed(0) : value.toFixed(1));
+}
+/**
+ * Format a bitrate value into a human-readable form as bps, kbps, or Mbps.
+ *
+ * @param value           - The bitrate value to convert, in bits per second.
+ *
+ * @returns Returns the value as a human-readable string.
+ *
+ * @example
+ *
+ * ```ts
+ * formatBps(500);        // "500 bps".
+ * formatBps(2000);       // "2 kbps".
+ * formatBps(15000);      // "15 kbps".
+ * formatBps(2560);       // "2.6 kbps".
+ * formatBps(1000000);    // "1 Mbps".
+ * formatBps(2560000);    // "2.6 Mbps".
+ * ```
+ *
+ * @category Utilities
+ */
+export function formatBps(value) {
+    if (value < 1_000) {
+        return value.toString() + " bps";
+    }
+    if (value < 1_000_000) {
+        return formatMagnitude(value / 1_000) + " kbps";
+    }
+    return formatMagnitude(value / 1_000_000) + " Mbps";
+}
+/**
+ * Format a byte count into a human-readable form as bytes, KB, MB, GB, or TB. Uses 1024-based thresholds matching the convention every operating system uses for
+ * displaying file and buffer sizes.
+ *
+ * @param value           - The byte count to convert.
+ *
+ * @returns Returns the value as a human-readable string.
+ *
+ * @example
+ *
+ * ```ts
+ * formatBytes(512);                  // "512 bytes".
+ * formatBytes(2048);                 // "2 KB".
+ * formatBytes(1536);                 // "1.5 KB".
+ * formatBytes(1_048_576);            // "1 MB".
+ * formatBytes(2_621_440);            // "2.5 MB".
+ * formatBytes(1_073_741_824);        // "1 GB".
+ * formatBytes(1_099_511_627_776);    // "1 TB".
+ * ```
+ *
+ * @category Utilities
+ */
+export function formatBytes(value) {
+    if (value < 1_024) {
+        return value.toString() + " bytes";
+    }
+    if (value < 1_048_576) {
+        return formatMagnitude(value / 1_024) + " KB";
+    }
+    if (value < 1_073_741_824) {
+        return formatMagnitude(value / 1_048_576) + " MB";
+    }
+    if (value < 1_099_511_627_776) {
+        return formatMagnitude(value / 1_073_741_824) + " GB";
+    }
+    return formatMagnitude(value / 1_099_511_627_776) + " TB";
+}
+/**
+ * Format a millisecond duration into a human-readable form as ms, s, min, or hr. Tiered thresholds match how operators naturally read elapsed time: sub-second
+ * values stay in milliseconds for precision, longer durations promote to seconds, minutes, and hours.
+ *
+ * @param value           - The duration to convert, in milliseconds.
+ *
+ * @returns Returns the value as a human-readable string.
+ *
+ * @example
+ *
+ * ```ts
+ * formatMs(250);          // "250 ms".
+ * formatMs(1500);         // "1.5 s".
+ * formatMs(15000);        // "15 s".
+ * formatMs(90000);        // "1.5 min".
+ * formatMs(5_400_000);    // "1.5 hr".
+ * ```
+ *
+ * @category Utilities
+ */
+export function formatMs(value) {
+    if (value < 1_000) {
+        return value.toString() + " ms";
+    }
+    if (value < 60_000) {
+        return formatMagnitude(value / 1_000) + " s";
+    }
+    if (value < 3_600_000) {
+        return formatMagnitude(value / 60_000) + " min";
+    }
+    return formatMagnitude(value / 3_600_000) + " hr";
+}
+/**
+ * Format a numeric percentage value into a human-readable form with a trailing percent sign. Applies the same precision policy as the magnitude-based formatters
+ * via the shared internal helper: whole numbers render without a trailing decimal, fractional numbers render to one decimal place.
+ *
+ * @param value           - The percentage value to convert. Treated as already-scaled into percent units (50 means 50%, not 0.5).
+ *
+ * @returns Returns the value as a human-readable string ending in `%`.
+ *
+ * @example
+ *
+ * ```ts
+ * formatPercent(0);        // "0%".
+ * formatPercent(50);       // "50%".
+ * formatPercent(100);      // "100%".
+ * formatPercent(33.333);   // "33.3%".
+ * ```
+ *
+ * @category Utilities
+ */
+export function formatPercent(value) {
+    return formatMagnitude(value) + "%";
+}
+/**
+ * Format a second-resolution duration into a human-readable form as s, min, or hr. Same tier semantics as {@link formatMs}, scaled for inputs that arrive already
+ * in seconds rather than milliseconds.
+ *
+ * @param value           - The duration to convert, in seconds.
+ *
+ * @returns Returns the value as a human-readable string.
+ *
+ * @example
+ *
+ * ```ts
+ * formatSeconds(45);          // "45 s".
+ * formatSeconds(90);          // "1.5 min".
+ * formatSeconds(1800);        // "30 min".
+ * formatSeconds(5400);        // "1.5 hr".
+ * ```
+ *
+ * @category Utilities
+ */
+export function formatSeconds(value) {
+    if (value < 60) {
+        return value.toString() + " s";
+    }
+    if (value < 3_600) {
+        return formatMagnitude(value / 60) + " min";
+    }
+    return formatMagnitude(value / 3_600) + " hr";
+}
+//# sourceMappingURL=formatters.js.map

package/dist/formatters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatters.js","sourceRoot":"","sources":["../src/formatters.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;GAcG;AAEH,oKAAoK;AACpK,sEAAsE;AACtE,SAAS,eAAe,CAAC,KAAa;IAEpC,OAAO,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa;IAErC,IAAG,KAAK,GAAG,KAAK,EAAE,CAAC;QAEjB,OAAO,KAAK,CAAC,QAAQ,EAAE,GAAG,MAAM,CAAC;IACnC,CAAC;IAED,IAAG,KAAK,GAAG,SAAS,EAAE,CAAC;QAErB,OAAO,eAAe,CAAC,KAAK,GAAG,KAAK,CAAC,GAAG,OAAO,CAAC;IAClD,CAAC;IAED,OAAO,eAAe,CAAC,KAAK,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC;AACtD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IAEvC,IAAG,KAAK,GAAG,KAAK,EAAE,CAAC;QAEjB,OAAO,KAAK,CAAC,QAAQ,EAAE,GAAG,QAAQ,CAAC;IACrC,CAAC;IAED,IAAG,KAAK,GAAG,SAAS,EAAE,CAAC;QAErB,OAAO,eAAe,CAAC,KAAK,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC;IAChD,CAAC;IAED,IAAG,KAAK,GAAG,aAAa,EAAE,CAAC;QAEzB,OAAO,eAAe,CAAC,KAAK,GAAG,SAAS,CAAC,GAAG,KAAK,CAAC;IACpD,CAAC;IAED,IAAG,KAAK,GAAG,iBAAiB,EAAE,CAAC;QAE7B,OAAO,eAAe,CAAC,KAAK,GAAG,aAAa,CAAC,GAAG,KAAK,CAAC;IACxD,CAAC;IAED,OAAO,eAAe,CAAC,KAAK,GAAG,iBAAiB,CAAC,GAAG,KAAK,CAAC;AAC5D,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAa;IAEpC,IAAG,KAAK,GAAG,KAAK,EAAE,CAAC;QAEjB,OAAO,KAAK,CAAC,QAAQ,EAAE,GAAG,KAAK,CAAC;IAClC,CAAC;IAED,IAAG,KAAK,GAAG,MAAM,EAAE,CAAC;QAElB,OAAO,eAAe,CAAC,KAAK,GAAG,KAAK,CAAC,GAAG,IAAI,CAAC;IAC/C,CAAC;IAED,IAAG,KAAK,GAAG,SAAS,EAAE,CAAC;QAErB,OAAO,eAAe,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,MAAM,CAAC;IAClD,CAAC;IAED,OAAO,eAAe,CAAC,KAAK,GAAG,SAAS,CAAC,GAAG,KAAK,CAAC;AACpD,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IAEzC,OAAO,eAAe,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IAEzC,IAAG,KAAK,GAAG,EAAE,EAAE,CAAC;QAEd,OAAO,KAAK,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC;IACjC,CAAC;IAED,IAAG,KAAK,GAAG,KAAK,EAAE,CAAC;QAEjB,OAAO,eAAe,CAAC,KAAK,GAAG,EAAE,CAAC,GAAG,MAAM,CAAC;IAC9C,CAAC;IAED,OAAO,eAAe,CAAC,KAAK,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC;AAChD,CAAC"}