tiny-essentials 1.28.19 → 1.29.1

package/dist/v1/libs/storage/TinyMapCache.d.mts

@@ -0,0 +1,274 @@
+export type ForEachCallback<T> = (data: T, key: string, cache: TinyMapCache<T>) => void;
+export type SetEventPayload<T> = {
+    /**
+     * - The key that was set.
+     */
+    key: string;
+    /**
+     * - The data that was set.
+     */
+    data: T;
+};
+export type GetEventPayload<T> = {
+    /**
+     * - The key that was accessed.
+     */
+    key: string;
+    /**
+     * - True if the key was found and is valid, false otherwise.
+     */
+    hit: boolean;
+};
+export type DeleteEventPayload<T> = {
+    /**
+     * - The key that was removed.
+     */
+    key: string;
+};
+export type ExpireEventPayload<T> = {
+    /**
+     * - The key that expired.
+     */
+    key: string;
+    /**
+     * - The data that was removed due to expiration.
+     */
+    data: T;
+};
+export type PurgeEventPayload = {
+    /**
+     * - The number of items removed during purge.
+     */
+    count: number;
+};
+export type CacheEntry<T> = {
+    /**
+     * - The actual data being stored.
+     */
+    data: T;
+    /**
+     * - The Unix timestamp (ms) when the data was stored.
+     */
+    timestamp: number;
+};
+export type CacheMap<T> = Map<string, CacheEntry<T>>;
+export type CacheObject<T> = Object<string, CacheEntry<T>>;
+export type TinyMapCacheEvents<T> = {
+    /**
+     * - Emitted when an item is stored.
+     */
+    set: (payload: SetEventPayload<T>) => void;
+    /**
+     * - Emitted when an item is removed.
+     */
+    delete: (payload: DeleteEventPayload<T>) => void;
+    /**
+     * - Emitted when an item expires.
+     */
+    expire: (payload: ExpireEventPayload<T>) => void;
+    /**
+     * - Emitted after a purge cycle removes items.
+     */
+    purge: (payload: PurgeEventPayload) => void;
+    /**
+     * - Emitted when the cache is cleared.
+     */
+    clear: () => void;
+};
+export type TinyMapCacheEmitter<T> = import('../../jsdoc/EventEmitter.mjs').ICustomEventEmitter<TinyMapCacheEvents<T>>;
+/**
+ * @template T
+ * @callback ForEachCallback
+ * @param {T} data - The value of the current entry.
+ * @param {string} key - The key of the current entry.
+ * @param {TinyMapCache<T>} cache - The cache instance that is being iterated.
+ * @returns {void}
+ */
+/**
+ * @template T
+ * @typedef {Object} SetEventPayload
+ * @property {string} key - The key that was set.
+ * @property {T} data - The data that was set.
+ */
+/**
+ * @template T
+ * @typedef {Object} GetEventPayload
+ * @property {string} key - The key that was accessed.
+ * @property {boolean} hit - True if the key was found and is valid, false otherwise.
+ */
+/**
+ * @template T
+ * @typedef {Object} DeleteEventPayload
+ * @property {string} key - The key that was removed.
+ */
+/**
+ * @template T
+ * @typedef {Object} ExpireEventPayload
+ * @property {string} key - The key that expired.
+ * @property {T} data - The data that was removed due to expiration.
+ */
+/**
+ * @typedef {Object} PurgeEventPayload
+ * @property {number} count - The number of items removed during purge.
+ */
+/**
+ * @template T
+ * @typedef {Object} CacheEntry
+ * @property {T} data - The actual data being stored.
+ * @property {number} timestamp - The Unix timestamp (ms) when the data was stored.
+ */
+/**
+ * A Map collection where keys are strings and values are CacheEntry objects.
+ * @template T
+ * @typedef {Map<string, CacheEntry<T>>} CacheMap
+ */
+/**
+ * A plain object representation of the cache, where keys are strings and values are CacheEntry objects.
+ * @template T
+ * @typedef {Object.<string, CacheEntry<T>>} CacheObject
+ */
+/**
+ * Event map for {@link TinyMapCache}.
+ * @template T
+ * @typedef {Object} TinyMapCacheEvents
+ * @property {(payload: SetEventPayload<T>) => void} set - Emitted when an item is stored.
+ * @property {(payload: DeleteEventPayload<T>) => void} delete - Emitted when an item is removed.
+ * @property {(payload: ExpireEventPayload<T>) => void} expire - Emitted when an item expires.
+ * @property {(payload: PurgeEventPayload) => void} purge - Emitted after a purge cycle removes items.
+ * @property {() => void} clear - Emitted when the cache is cleared.
+ */
+/**
+ * @template T
+ * @typedef {import('../../jsdoc/EventEmitter.mjs').ICustomEventEmitter<TinyMapCacheEvents<T>>} TinyMapCacheEmitter
+ */
+/** @type {new () => TinyMapCacheEmitter<any>} */
+declare const TypedEventEmitter: new () => TinyMapCacheEmitter<any>;
+/**
+ * @template {any} T
+ * In-memory cache manager to prevent duplicate requests.
+ */
+declare class TinyMapCache<T extends any> extends TypedEventEmitter {
+    #private;
+    /**
+     * A collection of all active `TinyMapCache` instances.
+     * This collection is used to facilitate cascaded operations (like `purgeExpired`) across all existing cache instances.
+     * @type {Array<TinyMapCache<any>>}
+     */
+    static get activeInstances(): Array<TinyMapCache<any>>;
+    /**
+     * Returns the total number of active `TinyMapCache` instances currently being tracked.
+     * @returns {number} The count of active instances.
+     */
+    static get activeInstancesSize(): number;
+    constructor();
+    /**
+     * Gets the current Time-To-Live (TTL) in milliseconds.
+     * @returns {number}
+     */
+    get ttl(): number;
+    /**
+     * Sets the Time-To-Live (TTL) in milliseconds.
+     * @param {number} value - The new TTL value.
+     * @throws {TypeError} If the value is not a number.
+     * @throws {RangeError} If the value is less than 0.
+     */
+    set ttl(value: number);
+    /**
+     * Returns the number of items currently stored in the cache.
+     * @returns {number}
+     */
+    get size(): number;
+    /**
+     * Checks if a specific key exists in the cache.
+     *
+     * Note: This method triggers a full purge of all expired items in the cache.
+     * @param {string} key - The identifier for the data.
+     * @returns {boolean} True if the key exists, false otherwise.
+     * @throws {TypeError} If the key is not a string.
+     */
+    has(key: string): boolean;
+    /**
+     * Removes the item associated with the specified key from the cache.
+     *
+     * Note: This method triggers a full purge of all expired items in the cache.
+     * @param {string} key - The identifier for the data.
+     * @returns {boolean} True if an element in the Map existed and has been removed, false otherwise.
+     * @throws {TypeError} If the key is not a string.
+     */
+    delete(key: string): boolean;
+    /**
+     * Saves an item to the cache.
+     *
+     * Note: This method triggers a full purge of all expired items in the cache.
+     * @param {string} key - The identifier for the data.
+     * @param {T} data - The data to be stored.
+     * @throws {TypeError} If the key is not a string.
+     */
+    set(key: string, data: T): void;
+    /**
+     * Retrieves an item if it is still valid.
+     *
+     * Note: This method triggers a full purge of all expired items in the cache.
+     * @param {string} key - The identifier for the data.
+     * @returns {T | null} The data if valid, or null if expired/not found.
+     * @throws {TypeError} If the key is not a string.
+     */
+    get(key: string): T | null;
+    /**
+     * Returns the string tag used by `Object.prototype.toString`.
+     * @returns {string} The string tag for this class.
+     */
+    get [Symbol.toStringTag](): string;
+    /**
+     * Returns a new iterator that yields the keys of all valid (non-expired) entries.
+     *
+     * Note: This method triggers a full purge of all expired items in the cache.
+     * @returns {IterableIterator<string>} An iterator over the cache keys.
+     */
+    keys(): IterableIterator<string>;
+    /**
+     * Returns a new iterator that yields the values of all valid (non-expired) entries.
+     *
+     * Note: This method triggers a full purge of all expired items in the cache.
+     * @returns {IterableIterator<T>} An iterator over the cache values.
+     */
+    values(): IterableIterator<T>;
+    /**
+     * Returns a new iterator that yields the `[key, value]` pairs of all valid (non-expired) entries.
+     *
+     * Note: This method triggers a full purge of all expired items in the cache.
+     * @returns {IterableIterator<[string, T]>} An iterator over the cache entries.
+     */
+    entries(): IterableIterator<[string, T]>;
+    /**
+     * Returns a new iterator over the `[key, value]` pairs of all valid (non-expired) entries.
+     * Alias for `entries()`, enabling `for...of` and spread syntax.
+     *
+     * Note: This method triggers a full purge of all expired items in the cache.
+     * @returns {IterableIterator<[string, T]>} An iterator over the cache entries.
+     */
+    [Symbol.iterator](): IterableIterator<[string, T]>;
+    /**
+     * Executes a provided function once for each valid (non-expired) entry.
+     *
+     * Note: This method triggers a full purge of all expired items in the cache.
+     * @param {ForEachCallback<T>} callbackFn - The function to execute for each entry.
+     * @param {any} [thisArg] - The value to use as `this` when executing `callbackFn`.
+     * @returns {void}
+     * @throws {TypeError} If the callback is not a function.
+     */
+    forEach(callbackFn: ForEachCallback<T>, thisArg?: any): void;
+    /**
+     * Iterates through the current cache and removes all entries that have exceeded the TTL.
+     * @param {boolean} [clearAll=true] - If true, triggers a purge on all other active cache instances.
+     * @returns {void}
+     */
+    purgeExpired(clearAll?: boolean): void;
+    /**
+     * Removes all items from the cache.
+     * @returns {void}
+     */
+    clear(): void;
+}
+export default TinyMapCache;
+//# sourceMappingURL=TinyMapCache.d.mts.map

package/dist/v1/libs/storage/TinyMapCache.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TinyMapCache.d.mts","sourceRoot":"","sources":["../../../../src/v1/libs/storage/TinyMapCache.mjs"],"names":[],"mappings":"AAIG,YAAU,eAAe,CADf,CAAC,IAEX,CAAW,IAAI,EAAP,CACR,EAAgB,GAAG,EAAX,MACR,EAAyB,KAAK,EAAtB,YAAY,CAAC,CAAC,CACtB,KAAU,IACZ,CAAA;AAIE,YAAkB,eAAe,CADvB,CAAC,IAEX;;;;IAAmB,GAAG,EAAX,MAAM,CACjB;;;;IAAc,IAAI,EAAP,CAAC,CACd;CAAA,CAAA;AAIE,YAAkB,eAAe,CADvB,CAAC,IAEX;;;;IAAmB,GAAG,EAAX,MAAM,CACjB;;;;IAAoB,GAAG,EAAZ,OAAO,CACpB;CAAA,CAAA;AAIE,YAAkB,kBAAkB,CAD1B,CAAC,IAEX;;;;IAAmB,GAAG,EAAX,MAAM,CACnB;CAAA,CAAA;AAIE,YAAkB,kBAAkB,CAD1B,CAAC,IAEX;;;;IAAmB,GAAG,EAAX,MAAM,CACjB;;;;IAAc,IAAI,EAAP,CAAC,CACd;CAAA,CAAA;AAGE,YAAkB,iBAAiB,GACnC;;;;IAAmB,KAAK,EAAb,MAAM,CACnB;CAAA,CAAA;AAIE,YAAkB,UAAU,CADlB,CAAC,IAEX;;;;IAAc,IAAI,EAAP,CAAC,CACZ;;;;IAAmB,SAAS,EAAjB,MAAM,CACnB;CAAA,CAAA;AAKE,YAAsC,QAAQ,CADpC,CAAC,IACD,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAU;AAM9C,YAA0C,WAAW,CAD3C,CAAC,IACD,MAAM,CAAE,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAa;AAMrD,YAAkB,kBAAkB,CAD1B,CAAC,IAEX;;;;IAAkD,GAAG,EAA1C,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,KAAK,IAAI,CAChD;;;;IAAqD,MAAM,EAAhD,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,KAAK,IAAI,CACnD;;;;IAAqD,MAAM,EAAhD,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,KAAK,IAAI,CACnD;;;;IAAiD,KAAK,EAA3C,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAC/C;;;;IAAuB,KAAK,EAAjB,MAAM,IAAI,CACvB;CAAA,CAAA;AAIE,YAA6F,mBAAmB,CADtG,CAAC,IACD,OAAO,8BAA8B,EAAE,mBAAmB,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAqB;AAzEnH;;;;;;;GAOG;AAEH;;;;;GAKG;AAEH;;;;;GAKG;AAEH;;;;GAIG;AAEH;;;;;GAKG;AAEH;;;GAGG;AAEH;;;;;GAKG;AAEH;;;;GAIG;AAEH;;;;GAIG;AAEH;;;;;;;;;GASG;AAEH;;;GAGG;AAEH,iDAAiD;AACjD,QAAA,MAAM,iBAAiB,EADZ,UAAU,mBAAmB,CAAC,GAAG,CACe,CAAC;AAE5D;;;GAGG;AACH,cAAM,YAAY,CAHC,CAAC,SAAN,GAAM,CAGD,SAAQ,iBAAiB;;IAQ1C;;;;OAIG;IACH,MAAM,KAAK,eAAe,IAFhB,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAIjC;IAED;;;OAGG;IACH,MAAM,KAAK,mBAAmB,IAFjB,MAAM,CAIlB;IAED,cAEC;IAUD;;;OAGG;IACH,IAAI,GAAG,IAFM,MAAM,CAIlB;IAED;;;;;OAKG;IACH,IAAI,GAAG,CAAC,KAAK,EAJF,MAIE,EAQZ;IAED;;;OAGG;IACH,IAAI,IAAI,IAFK,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,GAAG,CAAC,GAAG,EAJI,MAIJ,GAHM,OAAO,CASnB;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,GAAG,EAJC,MAID,GAHG,OAAO,CAenB;IAED;;;;;;;OAOG;IACH,GAAG,CAAC,GAAG,EAJI,MAIJ,EAAE,IAAI,EAHF,CAGE,QAeZ;IAED;;;;;;;OAOG;IACH,GAAG,CAAC,GAAG,EAJI,MAIJ,GAHM,CAAC,GAAG,IAAI,CAYpB;IAED;;;OAGG;IACH,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAFX,MAAM,CAIlB;IAED;;;;;OAKG;IACH,IAAI,IAFS,gBAAgB,CAAC,MAAM,CAAC,CAOpC;IAED;;;;;OAKG;IACH,MAAM,IAFO,gBAAgB,CAAC,CAAC,CAAC,CAO/B;IAED;;;;;OAKG;IACH,OAAO,IAFM,gBAAgB,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAKzC;IAED;;;;;;OAMG;IACH,CAAC,MAAM,CAAC,QAAQ,CAAC,IAFJ,gBAAgB,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAIzC;IAED;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU,EALP,eAAe,CAAC,CAAC,CAKV,EAAE,OAAO,AAJxB,CACA,EADQ,GAIgB,GAHd,IAAI,CAWhB;IAgBD;;;;OAIG;IACH,YAAY,CAAC,QAAQ,AAHlB,CACA,EADQ,OAGkB,GAFhB,IAAI,CA6BhB;IAED;;;OAGG;IACH,KAAK,IAFQ,IAAI,CAMhB;CACF;eAEc,YAAY"}

package/dist/v1/libs/storage/TinyMapCache.mjs

@@ -0,0 +1,333 @@
+import { EventEmitter } from 'events';
+/**
+ * @template T
+ * @callback ForEachCallback
+ * @param {T} data - The value of the current entry.
+ * @param {string} key - The key of the current entry.
+ * @param {TinyMapCache<T>} cache - The cache instance that is being iterated.
+ * @returns {void}
+ */
+/**
+ * @template T
+ * @typedef {Object} SetEventPayload
+ * @property {string} key - The key that was set.
+ * @property {T} data - The data that was set.
+ */
+/**
+ * @template T
+ * @typedef {Object} GetEventPayload
+ * @property {string} key - The key that was accessed.
+ * @property {boolean} hit - True if the key was found and is valid, false otherwise.
+ */
+/**
+ * @template T
+ * @typedef {Object} DeleteEventPayload
+ * @property {string} key - The key that was removed.
+ */
+/**
+ * @template T
+ * @typedef {Object} ExpireEventPayload
+ * @property {string} key - The key that expired.
+ * @property {T} data - The data that was removed due to expiration.
+ */
+/**
+ * @typedef {Object} PurgeEventPayload
+ * @property {number} count - The number of items removed during purge.
+ */
+/**
+ * @template T
+ * @typedef {Object} CacheEntry
+ * @property {T} data - The actual data being stored.
+ * @property {number} timestamp - The Unix timestamp (ms) when the data was stored.
+ */
+/**
+ * A Map collection where keys are strings and values are CacheEntry objects.
+ * @template T
+ * @typedef {Map<string, CacheEntry<T>>} CacheMap
+ */
+/**
+ * A plain object representation of the cache, where keys are strings and values are CacheEntry objects.
+ * @template T
+ * @typedef {Object.<string, CacheEntry<T>>} CacheObject
+ */
+/**
+ * Event map for {@link TinyMapCache}.
+ * @template T
+ * @typedef {Object} TinyMapCacheEvents
+ * @property {(payload: SetEventPayload<T>) => void} set - Emitted when an item is stored.
+ * @property {(payload: DeleteEventPayload<T>) => void} delete - Emitted when an item is removed.
+ * @property {(payload: ExpireEventPayload<T>) => void} expire - Emitted when an item expires.
+ * @property {(payload: PurgeEventPayload) => void} purge - Emitted after a purge cycle removes items.
+ * @property {() => void} clear - Emitted when the cache is cleared.
+ */
+/**
+ * @template T
+ * @typedef {import('../../jsdoc/EventEmitter.mjs').ICustomEventEmitter<TinyMapCacheEvents<T>>} TinyMapCacheEmitter
+ */
+/** @type {new () => TinyMapCacheEmitter<any>} */
+const TypedEventEmitter = /** @type {any} */ (EventEmitter);
+/**
+ * @template {any} T
+ * In-memory cache manager to prevent duplicate requests.
+ */
+class TinyMapCache extends TypedEventEmitter {
+    /**
+     * A private collection of all active `TinyMapCache` instances.
+     * This set is used to facilitate cascaded operations (like `purgeExpired`) across all existing cache instances.
+     * @type {Set<TinyMapCache<any>>}
+     */
+    static #instances = new Set();
+    /**
+     * A collection of all active `TinyMapCache` instances.
+     * This collection is used to facilitate cascaded operations (like `purgeExpired`) across all existing cache instances.
+     * @type {Array<TinyMapCache<any>>}
+     */
+    static get activeInstances() {
+        return Array.from(TinyMapCache.#instances);
+    }
+    /**
+     * Returns the total number of active `TinyMapCache` instances currently being tracked.
+     * @returns {number} The count of active instances.
+     */
+    static get activeInstancesSize() {
+        return TinyMapCache.#instances.size;
+    }
+    constructor() {
+        super();
+    }
+    /** @type {CacheMap<T>} */
+    #cache = new Map();
+    /**
+     * Time-to-live: 5 minutes in milliseconds
+     * @type {number}
+     */
+    #ttl = 300000;
+    /**
+     * Gets the current Time-To-Live (TTL) in milliseconds.
+     * @returns {number}
+     */
+    get ttl() {
+        return this.#ttl;
+    }
+    /**
+     * Sets the Time-To-Live (TTL) in milliseconds.
+     * @param {number} value - The new TTL value.
+     * @throws {TypeError} If the value is not a number.
+     * @throws {RangeError} If the value is less than 0.
+     */
+    set ttl(value) {
+        if (typeof value !== 'number') {
+            throw new TypeError('The TTL value must be a number.');
+        }
+        if (value < 0) {
+            throw new RangeError('The TTL value cannot be negative.');
+        }
+        this.#ttl = value;
+    }
+    /**
+     * Returns the number of items currently stored in the cache.
+     * @returns {number}
+     */
+    get size() {
+        return this.#cache.size;
+    }
+    /**
+     * Checks if a specific key exists in the cache.
+     *
+     * Note: This method triggers a full purge of all expired items in the cache.
+     * @param {string} key - The identifier for the data.
+     * @returns {boolean} True if the key exists, false otherwise.
+     * @throws {TypeError} If the key is not a string.
+     */
+    has(key) {
+        if (typeof key !== 'string') {
+            throw new TypeError('The cache key must be a string.');
+        }
+        this.purgeExpired(true);
+        return this.#cache.has(key);
+    }
+    /**
+     * Removes the item associated with the specified key from the cache.
+     *
+     * Note: This method triggers a full purge of all expired items in the cache.
+     * @param {string} key - The identifier for the data.
+     * @returns {boolean} True if an element in the Map existed and has been removed, false otherwise.
+     * @throws {TypeError} If the key is not a string.
+     */
+    delete(key) {
+        if (typeof key !== 'string') {
+            throw new TypeError('The cache key must be a string.');
+        }
+        this.purgeExpired(true);
+        const deleted = this.#cache.delete(key);
+        if (deleted) {
+            /** @type {DeleteEventPayload<T>} */
+            const payload = { key };
+            this.emit('delete', payload);
+        }
+        return deleted;
+    }
+    /**
+     * Saves an item to the cache.
+     *
+     * Note: This method triggers a full purge of all expired items in the cache.
+     * @param {string} key - The identifier for the data.
+     * @param {T} data - The data to be stored.
+     * @throws {TypeError} If the key is not a string.
+     */
+    set(key, data) {
+        if (typeof key !== 'string') {
+            throw new TypeError('The cache key must be a string.');
+        }
+        this.purgeExpired(true);
+        if (!TinyMapCache.#instances.has(this))
+            TinyMapCache.#instances.add(this);
+        this.#cache.set(key, {
+            data,
+            timestamp: Date.now(),
+        });
+        /** @type {SetEventPayload<T>} */
+        const payload = { key, data };
+        this.emit('set', payload);
+    }
+    /**
+     * Retrieves an item if it is still valid.
+     *
+     * Note: This method triggers a full purge of all expired items in the cache.
+     * @param {string} key - The identifier for the data.
+     * @returns {T | null} The data if valid, or null if expired/not found.
+     * @throws {TypeError} If the key is not a string.
+     */
+    get(key) {
+        if (typeof key !== 'string') {
+            throw new TypeError('The cache key must be a string.');
+        }
+        this.purgeExpired(true);
+        const cached = this.#cache.get(key);
+        if (!cached)
+            return null;
+        return cached.data;
+    }
+    /**
+     * Returns the string tag used by `Object.prototype.toString`.
+     * @returns {string} The string tag for this class.
+     */
+    get [Symbol.toStringTag]() {
+        return 'TinyMapCache';
+    }
+    /**
+     * Returns a new iterator that yields the keys of all valid (non-expired) entries.
+     *
+     * Note: This method triggers a full purge of all expired items in the cache.
+     * @returns {IterableIterator<string>} An iterator over the cache keys.
+     */
+    keys() {
+        this.purgeExpired(true);
+        return this.#validEntries()
+            .map(([key]) => key)
+            .values();
+    }
+    /**
+     * Returns a new iterator that yields the values of all valid (non-expired) entries.
+     *
+     * Note: This method triggers a full purge of all expired items in the cache.
+     * @returns {IterableIterator<T>} An iterator over the cache values.
+     */
+    values() {
+        this.purgeExpired(true);
+        return this.#validEntries()
+            .map(([, data]) => data)
+            .values();
+    }
+    /**
+     * Returns a new iterator that yields the `[key, value]` pairs of all valid (non-expired) entries.
+     *
+     * Note: This method triggers a full purge of all expired items in the cache.
+     * @returns {IterableIterator<[string, T]>} An iterator over the cache entries.
+     */
+    entries() {
+        this.purgeExpired(true);
+        return this.#validEntries().values();
+    }
+    /**
+     * Returns a new iterator over the `[key, value]` pairs of all valid (non-expired) entries.
+     * Alias for `entries()`, enabling `for...of` and spread syntax.
+     *
+     * Note: This method triggers a full purge of all expired items in the cache.
+     * @returns {IterableIterator<[string, T]>} An iterator over the cache entries.
+     */
+    [Symbol.iterator]() {
+        return this.entries();
+    }
+    /**
+     * Executes a provided function once for each valid (non-expired) entry.
+     *
+     * Note: This method triggers a full purge of all expired items in the cache.
+     * @param {ForEachCallback<T>} callbackFn - The function to execute for each entry.
+     * @param {any} [thisArg] - The value to use as `this` when executing `callbackFn`.
+     * @returns {void}
+     * @throws {TypeError} If the callback is not a function.
+     */
+    forEach(callbackFn, thisArg) {
+        if (typeof callbackFn !== 'function') {
+            throw new TypeError('The callback must be a function.');
+        }
+        this.purgeExpired(true);
+        for (const [key, data] of this.#validEntries()) {
+            callbackFn.call(thisArg, data, key, this);
+        }
+    }
+    /**
+     * Builds a snapshot of all valid (non-expired) entries as `[key, value]` pairs.
+     * Expired entries are expected to be removed beforehand via `purgeExpired`.
+     * @returns {Array<[string, T]>} The list of valid entries.
+     */
+    #validEntries() {
+        /** @type {Array<[string, T]>} */
+        const entries = [];
+        for (const [key, entry] of this.#cache.entries()) {
+            entries.push([key, entry.data]);
+        }
+        return entries;
+    }
+    /**
+     * Iterates through the current cache and removes all entries that have exceeded the TTL.
+     * @param {boolean} [clearAll=true] - If true, triggers a purge on all other active cache instances.
+     * @returns {void}
+     */
+    purgeExpired(clearAll = false) {
+        const now = Date.now();
+        let purgedCount = 0;
+        for (const [key, entry] of this.#cache.entries()) {
+            if (now - entry.timestamp > this.#ttl) {
+                this.#cache.delete(key);
+                purgedCount++;
+                /** @type {ExpireEventPayload<T>} */
+                const expirePayload = { key, data: entry.data };
+                this.emit('expire', expirePayload);
+            }
+        }
+        if (purgedCount > 0) {
+            /** @type {PurgeEventPayload} */
+            const purgePayload = { count: purgedCount };
+            this.emit('purge', purgePayload);
+        }
+        if (this.#cache.size < 1)
+            TinyMapCache.#instances.delete(this);
+        if (clearAll)
+            TinyMapCache.#instances.forEach((i) => {
+                if (i !== this)
+                    i.purgeExpired(false);
+            });
+    }
+    /**
+     * Removes all items from the cache.
+     * @returns {void}
+     */
+    clear() {
+        TinyMapCache.#instances.delete(this);
+        this.#cache.clear();
+        this.emit('clear');
+    }
+}
+export default TinyMapCache;