tiny-essentials 1.29.1 → 1.29.2

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

@@ -0,0 +1,354 @@
+/**
+ * @fileoverview Shared memory cache for media blobs and object URLs.
+ * Instances are tracked statically so a blob survives until the last cache
+ * releases it, which prevents revoking an object URL that another part of the
+ * application is still rendering.
+ */
+export type MediaCacheStrategy = 'auto' | 'manual' | 'ttl';
+export type MediaCacheOptions = {
+    /**
+     * - Maximum number of entries (Infinity by default).
+     */
+    maxItems?: number;
+    /**
+     * - Maximum cache size in bytes (Infinity by default).
+     */
+    maxBytes?: number;
+    /**
+     * - Entry lifetime in milliseconds (0 = never expires).
+     */
+    ttl?: number;
+    /**
+     * - Cleanup strategy at zero references.
+     */
+    strategy?: MediaCacheStrategy;
+    /**
+     * - Whether the query string is ignored when building keys.
+     */
+    ignoreSearch?: boolean;
+    /**
+     * - Interval in milliseconds for active TTL sweeping (0 = disabled).
+     */
+    sweepInterval?: number;
+};
+export type MediaCacheEntry = {
+    /**
+     * - The normalized cache key.
+     */
+    key: string;
+    /**
+     * - The original URL.
+     */
+    url: string;
+    /**
+     * - The cached blob.
+     */
+    blob: Blob;
+    /**
+     * - The shared object URL.
+     */
+    objectUrl: string;
+    /**
+     * - The blob size in bytes.
+     */
+    size: number;
+    /**
+     * - The blob MIME type.
+     */
+    type: string;
+    /**
+     * - The number of active consumers.
+     */
+    refs: number;
+    /**
+     * - The epoch timestamp when the entry was created.
+     */
+    createdAt: number;
+    /**
+     * - The epoch timestamp of the last access.
+     */
+    lastAccess: number;
+    /**
+     * - The epoch timestamp when the entry expires (0 = never).
+     */
+    expiresAt: number;
+    /**
+     * - Whether the entry is protected from eviction.
+     */
+    pinned: boolean;
+    /**
+     * - The key of the entry that owns this one, or null.
+     */
+    parent: string | null;
+    /**
+     * - The probe metadata captured with the blob.
+     */
+    metadata: Record<string, any>;
+};
+export type MediaCacheStats = {
+    /**
+     * - The number of entries in this cache.
+     */
+    size: number;
+    /**
+     * - The total size in bytes held by this cache.
+     */
+    bytes: number;
+    /**
+     * - The total number of active references.
+     */
+    refs: number;
+    /**
+     * - The number of successful lookups.
+     */
+    hits: number;
+    /**
+     * - The number of failed lookups.
+     */
+    misses: number;
+    /**
+     * - The number of evicted entries.
+     */
+    evictions: number;
+    /**
+     * - The number of entries that currently own at least one child.
+     */
+    links: number;
+    /**
+     * - The number of live cache instances.
+     */
+    instances: number;
+    /**
+     * - The number of blobs in the shared registry.
+     */
+    blobs: number;
+};
+export type MediaCacheRecord = {
+    /**
+     * - The shared object URL.
+     */
+    objectUrl: string;
+    /**
+     * - The number of cache instances holding the key.
+     */
+    refs: number;
+    /**
+     * - The blob size in bytes.
+     */
+    size: number;
+};
+/**
+ * Memory cache shared by every media loader.
+ */
+declare class TinyMediaCache {
+    #private;
+    /**
+     * Cleanup strategies applied when an entry reaches zero references.
+     */
+    static Strategy: Readonly<{
+        AUTO: "auto";
+        MANUAL: "manual";
+        TTL: "ttl";
+    }>;
+    /**
+     * The number of failed lookups recorded by this cache.
+     * @returns {number} The current miss count.
+     */
+    get misses(): number;
+    /**
+     * Whether the query string is ignored when building cache keys.
+     * @returns {boolean} True when the query string is ignored.
+     */
+    get ignoreSearch(): boolean;
+    /**
+     * The cleanup strategy applied when an entry reaches zero references.
+     * @returns {MediaCacheStrategy} The active cleanup strategy used by the cache.
+     */
+    get strategy(): MediaCacheStrategy;
+    /**
+     * The entry lifetime in milliseconds.
+     * @returns {number} The entry lifetime in milliseconds (0 = never expires).
+     */
+    get ttl(): number;
+    /**
+     * The maximum number of entries allowed in this cache.
+     * @returns {number} The maximum number of entries.
+     */
+    get maxItems(): number;
+    /**
+     * The maximum size in bytes allowed in this cache.
+     * @returns {number} The maximum size in bytes.
+     */
+    get maxBytes(): number;
+    /**
+     * The number of entries evicted by the limit enforcement.
+     * @returns {number} The current eviction count.
+     */
+    get evictions(): number;
+    /**
+     * @param {MediaCacheOptions} [options] - The cache configuration.
+     * @throws {TypeError} If `options` is not a plain object.
+     * @throws {RangeError} If `maxItems` is not a positive number.
+     * @throws {RangeError} If `maxBytes` is not a positive number.
+     * @throws {RangeError} If `ttl` is not a positive number.
+     * @throws {TypeError} If `strategy` is not a known strategy.
+     * @throws {TypeError} If `ignoreSearch` is not a boolean.
+     * @throws {RangeError} If `sweepInterval` is not a positive number.
+     */
+    constructor(options?: MediaCacheOptions);
+    /**
+     * A read-only snapshot of the shared blob registry.
+     * @returns {Array<{ key: string, objectUrl: string, refs: number, size: number }>} One record per cached blob.
+     */
+    static get registry(): Array<{
+        key: string;
+        objectUrl: string;
+        refs: number;
+        size: number;
+    }>;
+    /**
+     * Every live cache instance.
+     * @returns {TinyMediaCache[]}
+     */
+    static get instances(): TinyMediaCache[];
+    /**
+     * The number of blobs held by the shared registry.
+     * @returns {number}
+     */
+    static get size(): number;
+    /**
+     * The total number of bytes held by the shared registry.
+     * @returns {number}
+     */
+    static get bytes(): number;
+    /**
+     * Checks the shared registry without touching any instance.
+     * @param {string} url - The media URL.
+     * @param {boolean} [ignoreSearch] - Whether the query string is ignored.
+     * @returns {boolean}
+     */
+    static has(url: string, ignoreSearch?: boolean): boolean;
+    /**
+     * Revokes every object URL in the shared registry.
+     * @returns {void}
+     */
+    static clear(): void;
+    /**
+     * Destroys every live cache instance.
+     * @returns {void}
+     */
+    static destroyAll(): void;
+    /**
+     * The number of entries currently stored in this cache instance.
+     * @returns {number} The number of entries in this cache.
+     */
+    get size(): number;
+    /**
+     * The number of children's currently stored in this cache instance.
+     * @returns {number} The number of children's in this cache.
+     */
+    get links(): number;
+    /**
+     * @returns {number} The total size in bytes held by this cache.
+     */
+    get bytes(): number;
+    /**
+     * Indicates whether the cache instance has been destroyed.
+     * @returns {boolean} True if the cache was destroyed, false otherwise.
+     */
+    get destroyed(): boolean;
+    /**
+     * Returns a snapshot of the cache's internal performance counters.
+     * @returns {MediaCacheStats} A snapshot of the cache counters.
+     */
+    get stats(): MediaCacheStats;
+    /**
+     * A read-only snapshot of every entry held by this cache.
+     * @returns {MediaCacheEntry[]} A shallow copy of the entries.
+     */
+    entries(): MediaCacheEntry[];
+    /**
+     * Stores a blob and returns its entry.
+     * @param {string} url - The media URL.
+     * @param {Blob} blob - The blob to cache.
+     * @param {boolean} [pinned] - Whether the entry is protected from eviction.
+     * @param {Record<string, any>} [metadata] - The probe metadata captured with the blob.
+     * @param {string|null} [parent] - The key of the entry that owns this one.
+     * @returns {MediaCacheEntry} The stored entry.
+     * @throws {TypeError} If `blob` is not a Blob.
+     * @throws {TypeError} If `parent` is neither a string nor null.
+     * @throws {Error} If the cache was destroyed.
+     */
+    set(url: string, blob: Blob, pinned?: boolean, metadata?: Record<string, any>, parent?: string | null): MediaCacheEntry;
+    /**
+     * Reads an entry without changing its reference count.
+     * @param {string} url - The media URL.
+     * @returns {MediaCacheEntry|null}
+     */
+    get(url: string): MediaCacheEntry | null;
+    /**
+     * Checks whether a live entry exists for the given URL.
+     * @param {string} url - The media URL.
+     * @returns {boolean} True when a non-expired entry exists.
+     */
+    has(url: string): boolean;
+    /**
+     * Increments the reference count of an entry.
+     * @param {string} url - The media URL.
+     * @returns {MediaCacheEntry|null} The acquired entry, or null when missing.
+     */
+    acquire(url: string): MediaCacheEntry | null;
+    /**
+     * Decrements the reference count and applies the cleanup strategy.
+     * @param {string} url - The media URL.
+     * @returns {boolean} True when the entry was released.
+     */
+    release(url: string): boolean;
+    /**
+     * Removes an entry and releases its share of the shared registry. When the
+     * entry is the last child of a parent, the parent is removed as well.
+     * @param {string} url - The media URL.
+     * @returns {boolean} True when an entry was removed.
+     */
+    delete(url: string): boolean;
+    /**
+     * The keys of the entries owned by the given key.
+     * @param {string} url - The media URL of the owner.
+     * @returns {string[]} The normalized keys of the children, in insertion order.
+     */
+    children(url: string): string[];
+    /**
+     * Reads an entry without changing its reference count and without touching
+     * the hit/miss counters. Expired entries are reported as missing but are not
+     * removed, so a read-only probe never mutates the cache.
+     * @param {string} url - The media URL.
+     * @returns {MediaCacheEntry|null} The live entry, or null when absent or expired.
+     * @throws {TypeError} If `url` is not a string.
+     * @throws {Error} If the cache was destroyed.
+     */
+    peek(url: string): MediaCacheEntry | null;
+    /**
+     * Pins an entry so the limit enforcement skips it.
+     * @param {string} url - The media URL.
+     * @param {boolean} [value] - The new pinned state.
+     * @returns {boolean} True when the entry exists.
+     */
+    pin(url: string, value?: boolean): boolean;
+    /**
+     * Removes every expired entry.
+     * @returns {number} The number of removed entries.
+     */
+    prune(): number;
+    /**
+     * Removes every entry, regardless of its reference count.
+     * @returns {void}
+     */
+    clear(): void;
+    /**
+     * Detaches this instance from the shared registry.
+     * @returns {void}
+     */
+    destroy(): void;
+}
+export default TinyMediaCache;
+//# sourceMappingURL=TinyMediaCache.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TinyMediaCache.d.mts","sourceRoot":"","sources":["../../../../../../src/v1/libs/html/loader/utils/TinyMediaCache.mjs"],"names":[],"mappings":"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"}