tiny-essentials 1.29.1 → 1.29.2

package/dist/v1/libs/html/loader/utils/TinyMediaMirror.mjs

@@ -0,0 +1,280 @@
+/**
+ * @fileoverview Registry of in-flight media downloads.
+ *
+ * Two loaders that request the same URL at the same time would normally open
+ * two connections and decode the same picture twice. This registry lets the
+ * second loader attach to the download that is already running, so the bytes
+ * travel through the network exactly once and every consumer receives the very
+ * same {@link Blob} instance.
+ */
+/**
+ * Describes a single in-flight download.
+ * @template {string} Name
+ * @template {unknown[]} Args
+ * @typedef {Object} MediaMirrorEntry
+ * @property {string} key - The normalized registry key.
+ * @property {string} src - The original source URL.
+ * @property {number} startedAt - The epoch timestamp, in milliseconds, when the download started.
+ * @property {number} mirrors - The number of loaders attached to this download.
+ * @property {boolean} settled - Whether the download already produced a payload.
+ * @property {number} sequence - The sequence number assigned to the next published event.
+ * @property {MediaMirrorEvent<Name, Args>[]} events - Every event published so far, in order.
+ * @property {Set<MediaMirrorSubscriber<Name, Args>>} subscribers - The loaders attached to this download.
+ * @property {Promise<Blob>} promise - Resolves with the shared blob.
+ * @property {(blob: Blob) => void} resolve - Resolves the shared promise.
+ * @property {(error: Error) => void} reject - Rejects the shared promise.
+ */
+/**
+ * A read-only snapshot of the registry counters.
+ * @typedef {Object} MediaMirrorStats
+ * @property {number} pending - The number of downloads currently in flight.
+ * @property {number} mirrors - The total number of attached loaders.
+ */
+/**
+ * A read-only snapshot of a single in-flight download.
+ * @typedef {Object} MediaMirrorSnapshot
+ * @property {string} key - The normalized registry key.
+ * @property {string} src - The original source URL.
+ * @property {number} startedAt - The epoch timestamp, in milliseconds, when the download started.
+ * @property {number} mirrors - The number of loaders attached to this download.
+ * @property {boolean} settled - Whether the download already produced a payload.
+ */
+/**
+ * A single event captured from the leading loader.
+ * @template {string} Name
+ * @template {unknown[]} Args
+ * @typedef {Object} MediaMirrorEvent
+ * @property {number} seq - The zero-based position of the event in the stream.
+ * @property {Name} name - The event name.
+ * @property {Args} args - The arguments the event was emitted with.
+ * @property {number} timestamp - The high resolution timestamp of the capture.
+ */
+/**
+ * Handles a broadcast event.
+ * @template {string} Name
+ * @template {unknown[]} Args
+ * @callback MediaMirrorSubscriber
+ * @param {MediaMirrorEvent<Name, Args>} event - The published event.
+ * @returns {void}
+ */
+/**
+ * Deduplicates concurrent downloads that target the same URL.
+ */
+class TinyMediaMirror {
+    /** @type {Map<string, MediaMirrorEntry<string, unknown[]>>} */
+    static #pending = new Map();
+    /**
+     * The number of downloads currently in flight.
+     * @returns {number} The number of registered downloads.
+     */
+    static get size() {
+        return TinyMediaMirror.#pending.size;
+    }
+    /**
+     * The key of every in-flight download.
+     * @returns {string[]} A new array with the registered keys.
+     */
+    static get keys() {
+        return Array.from(TinyMediaMirror.#pending.keys());
+    }
+    /**
+     * A read-only snapshot of the registry counters.
+     * @returns {MediaMirrorStats} The current counters.
+     */
+    static get stats() {
+        let mirrors = 0;
+        for (const entry of TinyMediaMirror.#pending.values()) {
+            mirrors += entry.mirrors;
+        }
+        return { pending: TinyMediaMirror.#pending.size, mirrors };
+    }
+    /**
+     * Checks whether a download is already in flight for the given key.
+     * @param {string} key - The normalized registry key.
+     * @returns {boolean} True when a download is in flight.
+     */
+    static has(key) {
+        return TinyMediaMirror.#pending.has(key);
+    }
+    /**
+     * Reads an in-flight download without attaching to it.
+     * @param {string} key - The normalized registry key.
+     * @returns {MediaMirrorEntry<string, unknown[]>|null} The shared entry, or null when nothing is in flight.
+     */
+    static get(key) {
+        return TinyMediaMirror.#pending.get(key) ?? null;
+    }
+    /**
+     * A read-only snapshot of every in-flight download.
+     * @returns {MediaMirrorSnapshot[]} One record per in-flight download.
+     */
+    static entries() {
+        return Array.from(TinyMediaMirror.#pending.values(), (entry) => ({
+            key: entry.key,
+            src: entry.src,
+            startedAt: entry.startedAt,
+            mirrors: entry.mirrors,
+            settled: entry.settled,
+        }));
+    }
+    /**
+     * Registers a new in-flight download. When the key is already taken the
+     * existing entry is returned, so a live download is never overwritten.
+     * @param {string} key - The normalized registry key.
+     * @param {string} src - The original source URL.
+     * @returns {MediaMirrorEntry<string, unknown[]>} The registered entry.
+     * @throws {TypeError} If `key` is not a string.
+     * @throws {TypeError} If `src` is not a string.
+     */
+    static open(key, src) {
+        if (typeof key !== 'string') {
+            throw new TypeError('The "key" argument must be a string.');
+        }
+        if (typeof src !== 'string') {
+            throw new TypeError('The "src" argument must be a string.');
+        }
+        const existing = TinyMediaMirror.#pending.get(key);
+        if (existing) {
+            return existing;
+        }
+        /** @type {MediaMirrorEntry<string, unknown[]>} */
+        const entry = {
+            key,
+            src,
+            startedAt: Date.now(),
+            mirrors: 0,
+            settled: false,
+            sequence: 0,
+            events: [],
+            subscribers: new Set(),
+            promise: /** @type {Promise<Blob>} */ ( /** @type {unknown} */(null)),
+            resolve: () => { },
+            reject: () => { },
+        };
+        entry.promise = new Promise((resolve, reject) => {
+            entry.resolve = (blob) => {
+                entry.settled = true;
+                resolve(blob);
+            };
+            entry.reject = (error) => {
+                entry.settled = true;
+                reject(error);
+            };
+        });
+        // A download without mirrors must never surface as an unhandled rejection.
+        entry.promise.catch(() => { });
+        TinyMediaMirror.#pending.set(key, entry);
+        return entry;
+    }
+    /**
+     * Attaches a new consumer to an in-flight download.
+     * @param {string} key - The normalized registry key.
+     * @returns {MediaMirrorEntry<string, unknown[]>|null} The shared entry, or null when nothing is in flight.
+     */
+    static attach(key) {
+        const entry = TinyMediaMirror.#pending.get(key);
+        if (!entry) {
+            return null;
+        }
+        entry.mirrors += 1;
+        return entry;
+    }
+    /**
+     * Removes a finished download from the registry. A download that never
+     * produced a payload rejects its waiters instead of hanging them forever.
+     * @param {string} key - The normalized registry key.
+     * @returns {boolean} True when an entry was removed.
+     */
+    static close(key) {
+        const entry = TinyMediaMirror.#pending.get(key);
+        if (!entry) {
+            return false;
+        }
+        if (!entry.settled) {
+            entry.reject(new Error(`The mirrored download for "${entry.src}" ended without a payload.`));
+        }
+        return TinyMediaMirror.#pending.delete(key);
+    }
+    /**
+     * Rejects every in-flight download and empties the registry.
+     * @returns {void}
+     */
+    static clear() {
+        for (const entry of TinyMediaMirror.#pending.values()) {
+            if (!entry.settled) {
+                entry.reject(new Error('The mirror registry was cleared.'));
+            }
+        }
+        TinyMediaMirror.#pending.clear();
+    }
+    /**
+     * Broadcasts an event to every loader attached to an in-flight download. The
+     * event is appended to the history so a loader that attaches later still
+     * receives the complete stream, in its original order.
+     * @param {string} key - The normalized registry key.
+     * @param {string} name - The event name.
+     * @param {unknown[]} args - The arguments the event was emitted with.
+     * @returns {number} The number of subscribers that received the event.
+     * @throws {TypeError} If `key` is not a string.
+     * @throws {TypeError} If `name` is not a string.
+     * @throws {TypeError} If `args` is not an array.
+     */
+    static publish(key, name, args) {
+        if (typeof key !== 'string') {
+            throw new TypeError('The "key" argument must be a string.');
+        }
+        if (typeof name !== 'string') {
+            throw new TypeError('The "name" argument must be a string.');
+        }
+        if (!Array.isArray(args)) {
+            throw new TypeError('The "args" argument must be an array.');
+        }
+        const entry = TinyMediaMirror.#pending.get(key);
+        if (!entry) {
+            return 0;
+        }
+        const event = { seq: entry.sequence, name, args, timestamp: performance.now() };
+        entry.sequence += 1;
+        entry.events.push(event);
+        for (const subscriber of entry.subscribers) {
+            subscriber(event);
+        }
+        return entry.subscribers.size;
+    }
+    /**
+     * Attaches a subscriber to an in-flight download. The entire history is
+     * replayed synchronously, in its original order, before the handler starts
+     * receiving live events. Because JavaScript never preempts a running
+     * function, no live event can slip between the replay and the subscription,
+     * so the handler observes exactly the same sequence the leader produced.
+     * @param {string} key - The normalized registry key.
+     * @param {MediaMirrorSubscriber<string, unknown[]>} handler - The callback invoked for every event.
+     * @returns {(() => void)|null} A function that detaches the subscriber, or null when nothing is in flight.
+     * @throws {TypeError} If `handler` is not a function.
+     */
+    static subscribe(key, handler) {
+        if (typeof handler !== 'function') {
+            throw new TypeError('The "handler" argument must be a function.');
+        }
+        const entry = TinyMediaMirror.#pending.get(key);
+        if (!entry) {
+            return null;
+        }
+        const { events } = entry;
+        for (let index = 0; index < events.length; index += 1) {
+            handler(events[index]);
+        }
+        entry.subscribers.add(handler);
+        return () => entry.subscribers.delete(handler);
+    }
+    /**
+     * The ordered event history of an in-flight download. The array is live and
+     * must be treated as read-only.
+     * @param {string} key - The normalized registry key.
+     * @returns {MediaMirrorEvent<string, unknown[]>[]} The captured events, oldest first.
+     */
+    static history(key) {
+        return TinyMediaMirror.#pending.get(key)?.events ?? [];
+    }
+}
+export default TinyMediaMirror;

package/dist/v1/libs/html/loader/utils/TinyMediaProgress.cjs

@@ -0,0 +1,194 @@
+'use strict';
+
+/**
+ * @fileoverview Tracks byte-level progress for a media download. It is a plain
+ * value object: the loader pushes chunks in and reads snapshots out.
+ */
+
+/**
+ * A point-in-time snapshot of the download progress. It exposes both the raw
+ * byte counters and the derived metrics (rate, ETA and completion percentage)
+ * so that consumers can render progress without recalculating anything.
+ *
+ * @typedef {Object} MediaProgressSnapshot
+ * @property {number} loaded - The number of bytes downloaded so far.
+ * @property {number} total - The total number of bytes (0 when unknown).
+ * @property {number} remaining - The number of bytes left to download.
+ * @property {number} percent - The completion percentage between 0 and 100.
+ * @property {number} rate - The smoothed download rate in bytes per second.
+ * @property {number} elapsed - The elapsed time in milliseconds.
+ * @property {number} eta - The estimated time remaining in milliseconds.
+ * @property {number} chunks - The number of chunks received so far.
+ * @property {number} [width] - The intrinsic width of the media.
+ * @property {number} [height] - The intrinsic height of the media.
+ */
+
+/**
+ * Accumulates download chunks and derives rate, ETA and percentage.
+ */
+class TinyMediaProgress {
+  /** @type {number} */
+  #total;
+  /** @type {number} */
+  #loaded = 0;
+  /** @type {number} */
+  #chunks = 0;
+  /** @type {number} */
+  #startTime = 0;
+  /** @type {number} */
+  #lastTime = 0;
+  /** @type {number} */
+  #lastLoaded = 0;
+  /** @type {number} */
+  #rate = 0;
+
+  /**
+   * Initializes a new progress tracker.
+   * @param {number} [total] - The total number of bytes (0 when unknown).
+   * @throws {RangeError} If `total` is not a positive number.
+   */
+  constructor(total = 0) {
+    if (typeof total !== 'number' || Number.isNaN(total) || total < 0) {
+      throw new RangeError('The "total" argument must be a positive number.');
+    }
+    this.#total = total;
+  }
+
+  /**
+   * The total number of bytes (0 when unknown).
+   * @returns {number}
+   */
+  get total() {
+    return this.#total;
+  }
+
+  /**
+   * Updates the total size of the media being loaded.
+   * @param {number} value - The new total in bytes.
+   * @throws {RangeError} If `value` is not a positive number.
+   */
+  set total(value) {
+    if (typeof value !== 'number' || Number.isNaN(value) || value < 0) {
+      throw new RangeError('The "total" value must be a positive number.');
+    }
+    this.#total = value;
+  }
+
+  /**
+   * @returns {number} The number of bytes downloaded so far.
+   */
+  get loaded() {
+    return this.#loaded;
+  }
+
+  /**
+   * @returns {number} The number of bytes left to download.
+   */
+  get remaining() {
+    return this.#total > 0 ? Math.max(0, this.#total - this.#loaded) : 0;
+  }
+
+  /**
+   * @returns {number} The completion percentage between 0 and 100.
+   */
+  get percent() {
+    return this.#total > 0 ? Math.min(100, (this.#loaded / this.#total) * 100) : 0;
+  }
+
+  /**
+   * @returns {number} The smoothed download rate in bytes per second.
+   */
+  get rate() {
+    return this.#rate;
+  }
+
+  /**
+   * @returns {number} The number of chunks received so far.
+   */
+  get chunks() {
+    return this.#chunks;
+  }
+
+  /**
+   * @returns {number} The elapsed time in milliseconds.
+   */
+  get elapsed() {
+    return this.#startTime === 0 ? 0 : performance.now() - this.#startTime;
+  }
+
+  /**
+   * @returns {number} The estimated time remaining in milliseconds.
+   */
+  get eta() {
+    if (this.#rate <= 0 || this.#total <= 0) {
+      return 0;
+    }
+    return (this.remaining / this.#rate) * 1000;
+  }
+
+  /**
+   * Marks the start of the download.
+   * @returns {TinyMediaProgress} The current instance for chaining.
+   */
+  start() {
+    this.#startTime = performance.now();
+    this.#lastTime = this.#startTime;
+    return this;
+  }
+
+  /**
+   * Registers a new chunk and updates the smoothed rate.
+   * @param {number} bytes - The size of the chunk in bytes.
+   * @returns {TinyMediaProgress} The current instance for chaining.
+   * @throws {RangeError} If `bytes` is not a positive number.
+   */
+  push(bytes) {
+    if (typeof bytes !== 'number' || Number.isNaN(bytes) || bytes < 0) {
+      throw new RangeError('The "bytes" argument must be a positive number.');
+    }
+    const now = performance.now();
+    this.#loaded += bytes;
+    this.#chunks += 1;
+    const deltaTime = now - this.#lastTime;
+    if (deltaTime > 0) {
+      const instantRate = ((this.#loaded - this.#lastLoaded) / deltaTime) * 1000;
+      this.#rate = this.#rate === 0 ? instantRate : this.#rate * 0.7 + instantRate * 0.3;
+    }
+    this.#lastTime = now;
+    this.#lastLoaded = this.#loaded;
+    return this;
+  }
+
+  /**
+   * Resets every counter so the instance can be reused.
+   * @returns {TinyMediaProgress} The current instance for chaining.
+   */
+  reset() {
+    this.#loaded = 0;
+    this.#chunks = 0;
+    this.#rate = 0;
+    this.#lastLoaded = 0;
+    this.#startTime = 0;
+    this.#lastTime = 0;
+    return this;
+  }
+
+  /**
+   * Returns a read-only snapshot of the current progress and derived metrics.
+   * @returns {MediaProgressSnapshot} An immutable snapshot of the current state.
+   */
+  snapshot() {
+    return {
+      loaded: this.#loaded,
+      total: this.#total,
+      remaining: this.remaining,
+      percent: this.percent,
+      rate: this.#rate,
+      elapsed: this.elapsed,
+      eta: this.eta,
+      chunks: this.#chunks,
+    };
+  }
+}
+
+module.exports = TinyMediaProgress;

package/dist/v1/libs/html/loader/utils/TinyMediaProgress.d.mts

@@ -0,0 +1,138 @@
+/**
+ * @fileoverview Tracks byte-level progress for a media download. It is a plain
+ * value object: the loader pushes chunks in and reads snapshots out.
+ */
+export type MediaProgressSnapshot = {
+    /**
+     * - The number of bytes downloaded so far.
+     */
+    loaded: number;
+    /**
+     * - The total number of bytes (0 when unknown).
+     */
+    total: number;
+    /**
+     * - The number of bytes left to download.
+     */
+    remaining: number;
+    /**
+     * - The completion percentage between 0 and 100.
+     */
+    percent: number;
+    /**
+     * - The smoothed download rate in bytes per second.
+     */
+    rate: number;
+    /**
+     * - The elapsed time in milliseconds.
+     */
+    elapsed: number;
+    /**
+     * - The estimated time remaining in milliseconds.
+     */
+    eta: number;
+    /**
+     * - The number of chunks received so far.
+     */
+    chunks: number;
+    /**
+     * - The intrinsic width of the media.
+     */
+    width?: number;
+    /**
+     * - The intrinsic height of the media.
+     */
+    height?: number;
+};
+/**
+ * A point-in-time snapshot of the download progress. It exposes both the raw
+ * byte counters and the derived metrics (rate, ETA and completion percentage)
+ * so that consumers can render progress without recalculating anything.
+ *
+ * @typedef {Object} MediaProgressSnapshot
+ * @property {number} loaded - The number of bytes downloaded so far.
+ * @property {number} total - The total number of bytes (0 when unknown).
+ * @property {number} remaining - The number of bytes left to download.
+ * @property {number} percent - The completion percentage between 0 and 100.
+ * @property {number} rate - The smoothed download rate in bytes per second.
+ * @property {number} elapsed - The elapsed time in milliseconds.
+ * @property {number} eta - The estimated time remaining in milliseconds.
+ * @property {number} chunks - The number of chunks received so far.
+ * @property {number} [width] - The intrinsic width of the media.
+ * @property {number} [height] - The intrinsic height of the media.
+ */
+/**
+ * Accumulates download chunks and derives rate, ETA and percentage.
+ */
+declare class TinyMediaProgress {
+    #private;
+    /**
+     * Initializes a new progress tracker.
+     * @param {number} [total] - The total number of bytes (0 when unknown).
+     * @throws {RangeError} If `total` is not a positive number.
+     */
+    constructor(total?: number);
+    /**
+     * The total number of bytes (0 when unknown).
+     * @returns {number}
+     */
+    get total(): number;
+    /**
+     * Updates the total size of the media being loaded.
+     * @param {number} value - The new total in bytes.
+     * @throws {RangeError} If `value` is not a positive number.
+     */
+    set total(value: number);
+    /**
+     * @returns {number} The number of bytes downloaded so far.
+     */
+    get loaded(): number;
+    /**
+     * @returns {number} The number of bytes left to download.
+     */
+    get remaining(): number;
+    /**
+     * @returns {number} The completion percentage between 0 and 100.
+     */
+    get percent(): number;
+    /**
+     * @returns {number} The smoothed download rate in bytes per second.
+     */
+    get rate(): number;
+    /**
+     * @returns {number} The number of chunks received so far.
+     */
+    get chunks(): number;
+    /**
+     * @returns {number} The elapsed time in milliseconds.
+     */
+    get elapsed(): number;
+    /**
+     * @returns {number} The estimated time remaining in milliseconds.
+     */
+    get eta(): number;
+    /**
+     * Marks the start of the download.
+     * @returns {TinyMediaProgress} The current instance for chaining.
+     */
+    start(): TinyMediaProgress;
+    /**
+     * Registers a new chunk and updates the smoothed rate.
+     * @param {number} bytes - The size of the chunk in bytes.
+     * @returns {TinyMediaProgress} The current instance for chaining.
+     * @throws {RangeError} If `bytes` is not a positive number.
+     */
+    push(bytes: number): TinyMediaProgress;
+    /**
+     * Resets every counter so the instance can be reused.
+     * @returns {TinyMediaProgress} The current instance for chaining.
+     */
+    reset(): TinyMediaProgress;
+    /**
+     * Returns a read-only snapshot of the current progress and derived metrics.
+     * @returns {MediaProgressSnapshot} An immutable snapshot of the current state.
+     */
+    snapshot(): MediaProgressSnapshot;
+}
+export default TinyMediaProgress;
+//# sourceMappingURL=TinyMediaProgress.d.mts.map

package/dist/v1/libs/html/loader/utils/TinyMediaProgress.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TinyMediaProgress.d.mts","sourceRoot":"","sources":["../../../../../../src/v1/libs/html/loader/utils/TinyMediaProgress.mjs"],"names":[],"mappings":"AAAA;;;GAGG;AAOA,YAAkB,qBAAqB,GACvC;;;;IAAmB,MAAM,EAAd,MAAM,CACjB;;;;IAAmB,KAAK,EAAb,MAAM,CACjB;;;;IAAmB,SAAS,EAAjB,MAAM,CACjB;;;;IAAmB,OAAO,EAAf,MAAM,CACjB;;;;IAAmB,IAAI,EAAZ,MAAM,CACjB;;;;IAAmB,OAAO,EAAf,MAAM,CACjB;;;;IAAmB,GAAG,EAAX,MAAM,CACjB;;;;IAAmB,MAAM,EAAd,MAAM,CACjB;;;;IAAoB,KAAK,AAAzB,CACA,EADW,MAAM,CACjB;;;;IAAoB,MAAM,AAA1B,CACF,EADa,MAAM,CACnB;CAAA,CAAA;AAhBD;;;;;;;;;;;;;;;;GAgBG;AAEH;;GAEG;AACH,cAAM,iBAAiB;;IAgBrB;;;;OAIG;IACH,YAAY,KAAK,AAHd,CACA,EADQ,MAGU,EAKpB;IAED;;;OAGG;IACH,IAAI,KAAK,IAFI,MAAM,CAIlB;IAED;;;;OAIG;IACH,IAAI,KAAK,CAAC,KAAK,EAHJ,MAGI,EAKd;IAED;;OAEG;IACH,IAAI,MAAM,IAFG,MAAM,CAIlB;IAED;;OAEG;IACH,IAAI,SAAS,IAFA,MAAM,CAIlB;IAED;;OAEG;IACH,IAAI,OAAO,IAFE,MAAM,CAIlB;IAED;;OAEG;IACH,IAAI,IAAI,IAFK,MAAM,CAIlB;IAED;;OAEG;IACH,IAAI,MAAM,IAFG,MAAM,CAIlB;IAED;;OAEG;IACH,IAAI,OAAO,IAFE,MAAM,CAIlB;IAED;;OAEG;IACH,IAAI,GAAG,IAFM,MAAM,CAOlB;IAED;;;OAGG;IACH,KAAK,IAFQ,iBAAiB,CAM7B;IAED;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAJC,MAID,GAHG,iBAAiB,CAkB7B;IAED;;;OAGG;IACH,KAAK,IAFQ,iBAAiB,CAU7B;IAED;;;OAGG;IACH,QAAQ,IAFK,qBAAqB,CAajC;CACF;eAEc,iBAAiB"}