@twin.org/core 0.9.2-next.8 → 0.9.2

package/dist/es/utils/lruCache.js

@@ -0,0 +1,271 @@
+import { Guards } from "./guards.js";
+import { Is } from "./is.js";
+import { Mutex } from "./mutex.js";
+import { Validation } from "./validation.js";
+import { RandomHelper } from "../helpers/randomHelper.js";
+/**
+ * A fixed-capacity LRU cache with time-to-idle eviction.
+ *
+ * Entries are removed in two ways:
+ * - Capacity eviction: when the cache is full the least-recently-used entry is removed first.
+ * - TTI eviction: a background timer sweeps idle entries every ttiMs milliseconds.
+ * The timer only runs while there are entries; it stops automatically when the cache empties.
+ *
+ * `get` and `set` both update an entry's LRU position and reset its idle timer.
+ * `has` is a pure peek it evicts idle entries but does not refresh a live entry's TTI.
+ * Call `destroy` when the cache is no longer needed to stop the background timer.
+ */
+export class LruCache {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "LruCache";
+    /**
+     * Default capacity.
+     */
+    static DEFAULT_CAPACITY = 1000;
+    /**
+     * Default time-to-idle in milliseconds.
+     */
+    static DEFAULT_TTI_MS = 10000;
+    /**
+     * The maximum number of entries the cache will hold.
+     * @internal
+     */
+    _capacity;
+    /**
+     * The idle duration in milliseconds after which an untouched entry is evicted.
+     * @internal
+     */
+    _ttiMs;
+    /**
+     * Optional timeout in milliseconds for mutex acquisition.
+     * @internal
+     */
+    _mutexTimeoutMs;
+    /**
+     * Per-instance namespace prefix for mutex keys.
+     * @internal
+     */
+    _mutexScope;
+    /**
+     * Underlying storage; Map iteration order tracks LRU position (first = oldest).
+     * @internal
+     */
+    _cache;
+    /**
+     * Handle for the pending idle-sweep timeout, or undefined if no timer is scheduled.
+     * @internal
+     */
+    _sweepTimer;
+    /**
+     * Create a new instance of LruCache.
+     * @param options The cache options.
+     * @param options.capacity Maximum number of entries. Defaults to 1000. Must be a positive integer.
+     * @param options.ttiMs Time-to-idle in milliseconds. Defaults to 10000. Must be a positive integer.
+     * @param options.mutexTimeoutMs Maximum time in milliseconds to wait for getOrSet mutex acquisition.
+     * @throws ValidationError if capacity or ttiMs is not a positive integer.
+     */
+    constructor(options) {
+        const capacity = options?.capacity ?? LruCache.DEFAULT_CAPACITY;
+        const ttiMs = options?.ttiMs ?? LruCache.DEFAULT_TTI_MS;
+        const mutexTimeoutMs = options?.mutexTimeoutMs;
+        Guards.integer(LruCache.CLASS_NAME, "capacity", capacity);
+        Guards.integer(LruCache.CLASS_NAME, "ttiMs", ttiMs);
+        if (Is.notEmpty(mutexTimeoutMs)) {
+            Guards.integer(LruCache.CLASS_NAME, "mutexTimeoutMs", mutexTimeoutMs);
+        }
+        const failures = [];
+        Validation.integer("capacity", capacity, failures, undefined, { minValue: 1 });
+        Validation.integer("ttiMs", ttiMs, failures, undefined, { minValue: 1 });
+        if (Is.notEmpty(mutexTimeoutMs)) {
+            Validation.integer("mutexTimeoutMs", mutexTimeoutMs, failures, undefined, {
+                minValue: 0
+            });
+        }
+        Validation.asValidationError(LruCache.CLASS_NAME, "LruCache", failures);
+        this._capacity = capacity;
+        this._ttiMs = ttiMs;
+        this._mutexTimeoutMs = mutexTimeoutMs;
+        this._mutexScope = `${LruCache.CLASS_NAME}:${RandomHelper.generateUuidV7()}`;
+        this._cache = new Map();
+        this._sweepTimer = undefined;
+    }
+    /**
+     * The number of entries currently held in the cache.
+     * @returns The number of entries in the cache.
+     */
+    count() {
+        return this._cache.size;
+    }
+    /**
+     * Get a value from the cache.
+     * Returns undefined if the key is absent or the entry has idled out.
+     * A successful hit resets the entry's idle timer and moves it to most-recently-used.
+     * @param key The key to retrieve.
+     * @returns The cached value, or undefined on a miss or idle eviction.
+     */
+    get(key) {
+        const entry = this._cache.get(key);
+        if (entry === undefined) {
+            return undefined;
+        }
+        const now = Date.now();
+        if (now - entry.lastAccessed >= this._ttiMs) {
+            this._cache.delete(key);
+            return undefined;
+        }
+        // Move to end of Map (most-recently-used) via delete + re-insert
+        this._cache.delete(key);
+        entry.lastAccessed = now;
+        this._cache.set(key, entry);
+        return entry.value;
+    }
+    /**
+     * Store a value in the cache.
+     * If the key already exists its value and idle timer are refreshed.
+     * When the cache is at capacity, idle entries are swept first; if it is still full the
+     * least-recently-used entry is evicted.
+     * @param key The key to store.
+     * @param value The value to cache.
+     */
+    set(key, value) {
+        const now = Date.now();
+        // Remove any existing entry so the refreshed version is inserted at the end
+        this._cache.delete(key);
+        if (this._cache.size >= this._capacity) {
+            this.sweepIdle();
+        }
+        if (this._cache.size >= this._capacity) {
+            const lruKey = this._cache.keys().next().value;
+            if (lruKey !== undefined) {
+                this._cache.delete(lruKey);
+            }
+        }
+        this._cache.set(key, { value, lastAccessed: now });
+        this.startTimer();
+    }
+    /**
+     * Atomically get an existing value or create and store it once using an async factory.
+     * Concurrent calls for the same key are serialized via a mutex.
+     * @param key The key to get or create.
+     * @param valueFactory Async callback used to build a value when the key is absent.
+     * @returns The existing or newly created value.
+     */
+    async getOrSet(key, valueFactory) {
+        Guards.stringValue(LruCache.CLASS_NAME, "key", key);
+        Guards.function(LruCache.CLASS_NAME, "valueFactory", valueFactory);
+        const mutexKey = `${this._mutexScope}:${key}`;
+        await Mutex.lock(mutexKey, {
+            timeoutMs: this._mutexTimeoutMs,
+            throwOnTimeout: true
+        });
+        try {
+            if (this.has(key)) {
+                return this.get(key);
+            }
+            const value = await valueFactory();
+            this.set(key, value);
+            return value;
+        }
+        finally {
+            Mutex.unlock(mutexKey);
+        }
+    }
+    /**
+     * Check whether a key exists in the cache and has not idled out.
+     * Idle entries are evicted on peek, but a live entry's TTI is not reset.
+     * @param key The key to test.
+     * @returns True if the key is present and not idle.
+     */
+    has(key) {
+        const entry = this._cache.get(key);
+        if (entry === undefined) {
+            return false;
+        }
+        if (Date.now() - entry.lastAccessed >= this._ttiMs) {
+            this._cache.delete(key);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Return all keys for entries that have not idled out.
+     * Idle entries encountered during iteration are evicted.
+     * @returns An array of live keys in least-recently-used to most-recently-used order.
+     */
+    keys() {
+        const now = Date.now();
+        const result = [];
+        for (const [k, entry] of this._cache) {
+            if (now - entry.lastAccessed >= this._ttiMs) {
+                this._cache.delete(k);
+            }
+            else {
+                result.push(k);
+            }
+        }
+        return result;
+    }
+    /**
+     * Remove an entry from the cache.
+     * Cancels the background timer if the cache becomes empty.
+     * @param key The key to remove.
+     */
+    delete(key) {
+        this._cache.delete(key);
+        if (this._cache.size === 0) {
+            this.cancelTimer();
+        }
+    }
+    /**
+     * Remove all entries from the cache and cancel the background timer.
+     */
+    clear() {
+        this.cancelTimer();
+        this._cache.clear();
+    }
+    /**
+     * Stop the background idle-sweep timer and release all entries.
+     * The cache must not be used after this call.
+     */
+    destroy() {
+        this.cancelTimer();
+        this._cache.clear();
+    }
+    /**
+     * Delete all entries whose idle time has been exceeded, then restart the timer
+     * if any entries remain.
+     * @internal
+     */
+    sweepIdle() {
+        this.cancelTimer();
+        const now = Date.now();
+        for (const [k, entry] of this._cache) {
+            if (now - entry.lastAccessed >= this._ttiMs) {
+                this._cache.delete(k);
+            }
+        }
+        if (this._cache.size > 0) {
+            this.startTimer();
+        }
+    }
+    /**
+     * Schedule the next idle sweep if no timer is already pending.
+     * @internal
+     */
+    startTimer() {
+        this._sweepTimer ??= setTimeout(() => this.sweepIdle(), this._ttiMs);
+    }
+    /**
+     * Cancel the pending idle-sweep timer.
+     * @internal
+     */
+    cancelTimer() {
+        if (Is.notEmpty(this._sweepTimer)) {
+            clearTimeout(this._sweepTimer);
+            this._sweepTimer = undefined;
+        }
+    }
+}
+//# sourceMappingURL=lruCache.js.map

package/dist/es/utils/lruCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lruCache.js","sourceRoot":"","sources":["../../../src/utils/lruCache.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAG1D;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,QAAQ;IACpB;;OAEG;IACI,MAAM,CAAU,UAAU,cAA8B;IAE/D;;OAEG;IACI,MAAM,CAAU,gBAAgB,GAAG,IAAI,CAAC;IAE/C;;OAEG;IACI,MAAM,CAAU,cAAc,GAAG,KAAK,CAAC;IAE9C;;;OAGG;IACc,SAAS,CAAS;IAEnC;;;OAGG;IACc,MAAM,CAAS;IAEhC;;;OAGG;IACc,eAAe,CAAqB;IAErD;;;OAGG;IACc,WAAW,CAAS;IAErC;;;OAGG;IACc,MAAM,CAAkD;IAEzE;;;OAGG;IACK,WAAW,CAA4C;IAE/D;;;;;;;OAOG;IACH,YAAY,OAAwE;QACnF,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,QAAQ,CAAC,gBAAgB,CAAC;QAChE,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,QAAQ,CAAC,cAAc,CAAC;QACxD,MAAM,cAAc,GAAG,OAAO,EAAE,cAAc,CAAC;QAE/C,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,cAAoB,QAAQ,CAAC,CAAC;QAChE,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,WAAiB,KAAK,CAAC,CAAC;QAC1D,IAAI,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;YACjC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,oBAA0B,cAAc,CAAC,CAAC;QAC7E,CAAC;QAED,MAAM,QAAQ,GAAyB,EAAE,CAAC;QAC1C,UAAU,CAAC,OAAO,aAAmB,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;QACrF,UAAU,CAAC,OAAO,UAAgB,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;QAC/E,IAAI,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;YACjC,UAAU,CAAC,OAAO,mBAAyB,cAAc,EAAE,QAAQ,EAAE,SAAS,EAAE;gBAC/E,QAAQ,EAAE,CAAC;aACX,CAAC,CAAC;QACJ,CAAC;QACD,UAAU,CAAC,iBAAiB,CAAC,QAAQ,CAAC,UAAU,cAAsB,QAAQ,CAAC,CAAC;QAEhF,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,eAAe,GAAG,cAAc,CAAC;QACtC,IAAI,CAAC,WAAW,GAAG,GAAG,QAAQ,CAAC,UAAU,IAAI,YAAY,CAAC,cAAc,EAAE,EAAE,CAAC;QAC7E,IAAI,CAAC,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;QACxB,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;IAC9B,CAAC;IAED;;;OAGG;IACI,KAAK;QACX,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IACzB,CAAC;IAED;;;;;;OAMG;IACI,GAAG,CAAC,GAAW;QACrB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,SAAS,CAAC;QAClB,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,GAAG,GAAG,KAAK,CAAC,YAAY,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAC7C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACxB,OAAO,SAAS,CAAC;QAClB,CAAC;QACD,iEAAiE;QACjE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,KAAK,CAAC,YAAY,GAAG,GAAG,CAAC;QACzB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC5B,OAAO,KAAK,CAAC,KAAK,CAAC;IACpB,CAAC;IAED;;;;;;;OAOG;IACI,GAAG,CAAC,GAAW,EAAE,KAAQ;QAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,4EAA4E;QAC5E,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACxC,IAAI,CAAC,SAAS,EAAE,CAAC;QAClB,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACxC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YAC/C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC1B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC5B,CAAC;QACF,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC;QACnD,IAAI,CAAC,UAAU,EAAE,CAAC;IACnB,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,QAAQ,CAAC,GAAW,EAAE,YAA8B;QAChE,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,UAAU,SAAe,GAAG,CAAC,CAAC;QAC1D,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,UAAU,kBAAwB,YAAY,CAAC,CAAC;QAEzE,MAAM,QAAQ,GAAG,GAAG,IAAI,CAAC,WAAW,IAAI,GAAG,EAAE,CAAC;QAC9C,MAAM,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE;YAC1B,SAAS,EAAE,IAAI,CAAC,eAAe;YAC/B,cAAc,EAAE,IAAI;SACpB,CAAC,CAAC;QAEH,IAAI,CAAC;YACJ,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBACnB,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAM,CAAC;YAC3B,CAAC;YAED,MAAM,KAAK,GAAG,MAAM,YAAY,EAAE,CAAC;YACnC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACrB,OAAO,KAAK,CAAC;QACd,CAAC;gBAAS,CAAC;YACV,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACxB,CAAC;IACF,CAAC;IAED;;;;;OAKG;IACI,GAAG,CAAC,GAAW;QACrB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,KAAK,CAAC;QACd,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,YAAY,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACpD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACxB,OAAO,KAAK,CAAC;QACd,CAAC;QACD,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;;;OAIG;IACI,IAAI;QACV,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,KAAK,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACtC,IAAI,GAAG,GAAG,KAAK,CAAC,YAAY,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAC7C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACvB,CAAC;iBAAM,CAAC;gBACP,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAChB,CAAC;QACF,CAAC;QACD,OAAO,MAAM,CAAC;IACf,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,GAAW;QACxB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YAC5B,IAAI,CAAC,WAAW,EAAE,CAAC;QACpB,CAAC;IACF,CAAC;IAED;;OAEG;IACI,KAAK;QACX,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED;;;OAGG;IACI,OAAO;QACb,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED;;;;OAIG;IACK,SAAS;QAChB,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACtC,IAAI,GAAG,GAAG,KAAK,CAAC,YAAY,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAC7C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACvB,CAAC;QACF,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC,UAAU,EAAE,CAAC;QACnB,CAAC;IACF,CAAC;IAED;;;OAGG;IACK,UAAU;QACjB,IAAI,CAAC,WAAW,KAAK,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACtE,CAAC;IAED;;;OAGG;IACK,WAAW;QAClB,IAAI,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;YACnC,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YAC/B,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;QAC9B,CAAC;IACF,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { nameof } from \"@twin.org/nameof\";\nimport { Guards } from \"./guards.js\";\nimport { Is } from \"./is.js\";\nimport { Mutex } from \"./mutex.js\";\nimport { Validation } from \"./validation.js\";\nimport { RandomHelper } from \"../helpers/randomHelper.js\";\nimport type { IValidationFailure } from \"../models/IValidationFailure.js\";\n\n/**\n * A fixed-capacity LRU cache with time-to-idle eviction.\n *\n * Entries are removed in two ways:\n * - Capacity eviction: when the cache is full the least-recently-used entry is removed first.\n * - TTI eviction: a background timer sweeps idle entries every ttiMs milliseconds.\n * The timer only runs while there are entries; it stops automatically when the cache empties.\n *\n * `get` and `set` both update an entry's LRU position and reset its idle timer.\n * `has` is a pure peek it evicts idle entries but does not refresh a live entry's TTI.\n * Call `destroy` when the cache is no longer needed to stop the background timer.\n */\nexport class LruCache<T = unknown> {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<LruCache>();\n\n\t/**\n\t * Default capacity.\n\t */\n\tpublic static readonly DEFAULT_CAPACITY = 1000;\n\n\t/**\n\t * Default time-to-idle in milliseconds.\n\t */\n\tpublic static readonly DEFAULT_TTI_MS = 10000;\n\n\t/**\n\t * The maximum number of entries the cache will hold.\n\t * @internal\n\t */\n\tprivate readonly _capacity: number;\n\n\t/**\n\t * The idle duration in milliseconds after which an untouched entry is evicted.\n\t * @internal\n\t */\n\tprivate readonly _ttiMs: number;\n\n\t/**\n\t * Optional timeout in milliseconds for mutex acquisition.\n\t * @internal\n\t */\n\tprivate readonly _mutexTimeoutMs: number | undefined;\n\n\t/**\n\t * Per-instance namespace prefix for mutex keys.\n\t * @internal\n\t */\n\tprivate readonly _mutexScope: string;\n\n\t/**\n\t * Underlying storage; Map iteration order tracks LRU position (first = oldest).\n\t * @internal\n\t */\n\tprivate readonly _cache: Map<string, { value: T; lastAccessed: number }>;\n\n\t/**\n\t * Handle for the pending idle-sweep timeout, or undefined if no timer is scheduled.\n\t * @internal\n\t */\n\tprivate _sweepTimer: ReturnType<typeof setTimeout> | undefined;\n\n\t/**\n\t * Create a new instance of LruCache.\n\t * @param options The cache options.\n\t * @param options.capacity Maximum number of entries. Defaults to 1000. Must be a positive integer.\n\t * @param options.ttiMs Time-to-idle in milliseconds. Defaults to 10000. Must be a positive integer.\n\t * @param options.mutexTimeoutMs Maximum time in milliseconds to wait for getOrSet mutex acquisition.\n\t * @throws ValidationError if capacity or ttiMs is not a positive integer.\n\t */\n\tconstructor(options?: { capacity?: number; ttiMs?: number; mutexTimeoutMs?: number }) {\n\t\tconst capacity = options?.capacity ?? LruCache.DEFAULT_CAPACITY;\n\t\tconst ttiMs = options?.ttiMs ?? LruCache.DEFAULT_TTI_MS;\n\t\tconst mutexTimeoutMs = options?.mutexTimeoutMs;\n\n\t\tGuards.integer(LruCache.CLASS_NAME, nameof(capacity), capacity);\n\t\tGuards.integer(LruCache.CLASS_NAME, nameof(ttiMs), ttiMs);\n\t\tif (Is.notEmpty(mutexTimeoutMs)) {\n\t\t\tGuards.integer(LruCache.CLASS_NAME, nameof(mutexTimeoutMs), mutexTimeoutMs);\n\t\t}\n\n\t\tconst failures: IValidationFailure[] = [];\n\t\tValidation.integer(nameof(capacity), capacity, failures, undefined, { minValue: 1 });\n\t\tValidation.integer(nameof(ttiMs), ttiMs, failures, undefined, { minValue: 1 });\n\t\tif (Is.notEmpty(mutexTimeoutMs)) {\n\t\t\tValidation.integer(nameof(mutexTimeoutMs), mutexTimeoutMs, failures, undefined, {\n\t\t\t\tminValue: 0\n\t\t\t});\n\t\t}\n\t\tValidation.asValidationError(LruCache.CLASS_NAME, nameof<LruCache>(), failures);\n\n\t\tthis._capacity = capacity;\n\t\tthis._ttiMs = ttiMs;\n\t\tthis._mutexTimeoutMs = mutexTimeoutMs;\n\t\tthis._mutexScope = `${LruCache.CLASS_NAME}:${RandomHelper.generateUuidV7()}`;\n\t\tthis._cache = new Map();\n\t\tthis._sweepTimer = undefined;\n\t}\n\n\t/**\n\t * The number of entries currently held in the cache.\n\t * @returns The number of entries in the cache.\n\t */\n\tpublic count(): number {\n\t\treturn this._cache.size;\n\t}\n\n\t/**\n\t * Get a value from the cache.\n\t * Returns undefined if the key is absent or the entry has idled out.\n\t * A successful hit resets the entry's idle timer and moves it to most-recently-used.\n\t * @param key The key to retrieve.\n\t * @returns The cached value, or undefined on a miss or idle eviction.\n\t */\n\tpublic get(key: string): T | undefined {\n\t\tconst entry = this._cache.get(key);\n\t\tif (entry === undefined) {\n\t\t\treturn undefined;\n\t\t}\n\t\tconst now = Date.now();\n\t\tif (now - entry.lastAccessed >= this._ttiMs) {\n\t\t\tthis._cache.delete(key);\n\t\t\treturn undefined;\n\t\t}\n\t\t// Move to end of Map (most-recently-used) via delete + re-insert\n\t\tthis._cache.delete(key);\n\t\tentry.lastAccessed = now;\n\t\tthis._cache.set(key, entry);\n\t\treturn entry.value;\n\t}\n\n\t/**\n\t * Store a value in the cache.\n\t * If the key already exists its value and idle timer are refreshed.\n\t * When the cache is at capacity, idle entries are swept first; if it is still full the\n\t * least-recently-used entry is evicted.\n\t * @param key The key to store.\n\t * @param value The value to cache.\n\t */\n\tpublic set(key: string, value: T): void {\n\t\tconst now = Date.now();\n\t\t// Remove any existing entry so the refreshed version is inserted at the end\n\t\tthis._cache.delete(key);\n\t\tif (this._cache.size >= this._capacity) {\n\t\t\tthis.sweepIdle();\n\t\t}\n\t\tif (this._cache.size >= this._capacity) {\n\t\t\tconst lruKey = this._cache.keys().next().value;\n\t\t\tif (lruKey !== undefined) {\n\t\t\t\tthis._cache.delete(lruKey);\n\t\t\t}\n\t\t}\n\t\tthis._cache.set(key, { value, lastAccessed: now });\n\t\tthis.startTimer();\n\t}\n\n\t/**\n\t * Atomically get an existing value or create and store it once using an async factory.\n\t * Concurrent calls for the same key are serialized via a mutex.\n\t * @param key The key to get or create.\n\t * @param valueFactory Async callback used to build a value when the key is absent.\n\t * @returns The existing or newly created value.\n\t */\n\tpublic async getOrSet(key: string, valueFactory: () => Promise<T>): Promise<T> {\n\t\tGuards.stringValue(LruCache.CLASS_NAME, nameof(key), key);\n\t\tGuards.function(LruCache.CLASS_NAME, nameof(valueFactory), valueFactory);\n\n\t\tconst mutexKey = `${this._mutexScope}:${key}`;\n\t\tawait Mutex.lock(mutexKey, {\n\t\t\ttimeoutMs: this._mutexTimeoutMs,\n\t\t\tthrowOnTimeout: true\n\t\t});\n\n\t\ttry {\n\t\t\tif (this.has(key)) {\n\t\t\t\treturn this.get(key) as T;\n\t\t\t}\n\n\t\t\tconst value = await valueFactory();\n\t\t\tthis.set(key, value);\n\t\t\treturn value;\n\t\t} finally {\n\t\t\tMutex.unlock(mutexKey);\n\t\t}\n\t}\n\n\t/**\n\t * Check whether a key exists in the cache and has not idled out.\n\t * Idle entries are evicted on peek, but a live entry's TTI is not reset.\n\t * @param key The key to test.\n\t * @returns True if the key is present and not idle.\n\t */\n\tpublic has(key: string): boolean {\n\t\tconst entry = this._cache.get(key);\n\t\tif (entry === undefined) {\n\t\t\treturn false;\n\t\t}\n\t\tif (Date.now() - entry.lastAccessed >= this._ttiMs) {\n\t\t\tthis._cache.delete(key);\n\t\t\treturn false;\n\t\t}\n\t\treturn true;\n\t}\n\n\t/**\n\t * Return all keys for entries that have not idled out.\n\t * Idle entries encountered during iteration are evicted.\n\t * @returns An array of live keys in least-recently-used to most-recently-used order.\n\t */\n\tpublic keys(): string[] {\n\t\tconst now = Date.now();\n\t\tconst result: string[] = [];\n\t\tfor (const [k, entry] of this._cache) {\n\t\t\tif (now - entry.lastAccessed >= this._ttiMs) {\n\t\t\t\tthis._cache.delete(k);\n\t\t\t} else {\n\t\t\t\tresult.push(k);\n\t\t\t}\n\t\t}\n\t\treturn result;\n\t}\n\n\t/**\n\t * Remove an entry from the cache.\n\t * Cancels the background timer if the cache becomes empty.\n\t * @param key The key to remove.\n\t */\n\tpublic delete(key: string): void {\n\t\tthis._cache.delete(key);\n\t\tif (this._cache.size === 0) {\n\t\t\tthis.cancelTimer();\n\t\t}\n\t}\n\n\t/**\n\t * Remove all entries from the cache and cancel the background timer.\n\t */\n\tpublic clear(): void {\n\t\tthis.cancelTimer();\n\t\tthis._cache.clear();\n\t}\n\n\t/**\n\t * Stop the background idle-sweep timer and release all entries.\n\t * The cache must not be used after this call.\n\t */\n\tpublic destroy(): void {\n\t\tthis.cancelTimer();\n\t\tthis._cache.clear();\n\t}\n\n\t/**\n\t * Delete all entries whose idle time has been exceeded, then restart the timer\n\t * if any entries remain.\n\t * @internal\n\t */\n\tprivate sweepIdle(): void {\n\t\tthis.cancelTimer();\n\t\tconst now = Date.now();\n\t\tfor (const [k, entry] of this._cache) {\n\t\t\tif (now - entry.lastAccessed >= this._ttiMs) {\n\t\t\t\tthis._cache.delete(k);\n\t\t\t}\n\t\t}\n\t\tif (this._cache.size > 0) {\n\t\t\tthis.startTimer();\n\t\t}\n\t}\n\n\t/**\n\t * Schedule the next idle sweep if no timer is already pending.\n\t * @internal\n\t */\n\tprivate startTimer(): void {\n\t\tthis._sweepTimer ??= setTimeout(() => this.sweepIdle(), this._ttiMs);\n\t}\n\n\t/**\n\t * Cancel the pending idle-sweep timer.\n\t * @internal\n\t */\n\tprivate cancelTimer(): void {\n\t\tif (Is.notEmpty(this._sweepTimer)) {\n\t\t\tclearTimeout(this._sweepTimer);\n\t\t\tthis._sweepTimer = undefined;\n\t\t}\n\t}\n}\n"]}

package/dist/types/index.d.ts

@@ -54,6 +54,8 @@ export * from "./types/singleOccurrenceArrayDepthHelper.js";
 export * from "./types/url.js";
 export * from "./types/urn.js";
 export * from "./utils/asyncCache.js";
+export * from "./utils/lfuCache.js";
+export * from "./utils/lruCache.js";
 export * from "./utils/coerce.js";
 export * from "./utils/compression.js";
 export * from "./utils/converter.js";

package/dist/types/models/coerceType.d.ts

@@ -46,6 +46,10 @@ export declare const CoerceType: {
      * Duration in seconds.
      */
     readonly Duration: "duration";
+    /**
+     * Array.
+     */
+    readonly Array: "array";
 };
 /**
  * The types the extracted data can be coerced to.

package/dist/types/utils/coerce.d.ts

@@ -60,6 +60,12 @@ export declare class Coerce {
      * @returns The duration object, or undefined if the value cannot be coerced.
      */
     static duration(value: unknown): IDuration | undefined;
+    /**
+     * Coerce the value to an array.
+     * @param value The value to coerce.
+     * @returns The coerced array, or undefined if the value cannot be coerced.
+     */
+    static array<T = unknown>(value: unknown): T[] | undefined;
     /**
      * Coerce the value to an object.
      * @param value The value to coerce.

package/dist/types/utils/lfuCache.d.ts

@@ -0,0 +1,100 @@
+/**
+ * A fixed-capacity LFU cache with time-to-idle eviction.
+ *
+ * Entries are removed in two ways:
+ * - Capacity eviction: when the cache is full the least-frequently-used entry is removed first.
+ * Ties in frequency are broken by recency the least-recently-used entry among those with the
+ * minimum frequency is evicted.
+ * - TTI eviction: a background timer sweeps idle entries every ttiMs milliseconds.
+ * The timer only runs while there are entries; it stops automatically when the cache empties.
+ *
+ * `get` and `set` increment an entry's access frequency and reset its idle timer.
+ * `has` and `keys` are pure peeks they evict idle entries but do not affect frequency or TTI.
+ * Call `destroy` when the cache is no longer needed to stop the background timer.
+ */
+export declare class LfuCache<T> {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Default capacity.
+     */
+    static readonly DEFAULT_CAPACITY = 1000;
+    /**
+     * Default time-to-idle in milliseconds.
+     */
+    static readonly DEFAULT_TTI_MS = 10000;
+    /**
+     * Create a new instance of LfuCache.
+     * @param options The cache options.
+     * @param options.capacity Maximum number of entries. Defaults to 1000. Must be a positive integer.
+     * @param options.ttiMs Time-to-idle in milliseconds. Defaults to 10000. Must be a positive integer.
+     * @param options.mutexTimeoutMs Maximum time in milliseconds to wait for getOrSet mutex acquisition.
+     * @throws ValidationError if capacity or ttiMs is not a positive integer.
+     */
+    constructor(options?: {
+        capacity?: number;
+        ttiMs?: number;
+        mutexTimeoutMs?: number;
+    });
+    /**
+     * The number of entries currently held in the cache.
+     * @returns The number of entries in the cache.
+     */
+    count(): number;
+    /**
+     * Get a value from the cache.
+     * Returns undefined if the key is absent or the entry has idled out.
+     * A successful hit increments the entry's frequency and resets its idle timer.
+     * @param key The key to retrieve.
+     * @returns The cached value, or undefined on a miss or idle eviction.
+     */
+    get(key: string): T | undefined;
+    /**
+     * Store a value in the cache.
+     * If the key already exists its value and frequency are updated.
+     * When the cache is at capacity, idle entries are swept first; if it is still full the
+     * least-frequently-used entry is evicted (LRU among ties).
+     * @param key The key to store.
+     * @param value The value to cache.
+     */
+    set(key: string, value: T): void;
+    /**
+     * Atomically get an existing value or create and store it once using an async factory.
+     * Concurrent calls for the same key are serialized via a mutex.
+     * @param key The key to get or create.
+     * @param valueFactory Async callback used to build a value when the key is absent.
+     * @returns The existing or newly created value.
+     */
+    getOrSet(key: string, valueFactory: () => Promise<T>): Promise<T>;
+    /**
+     * Check whether a key exists in the cache and has not idled out.
+     * Idle entries are evicted on peek, but a live entry's frequency and TTI are not updated.
+     * @param key The key to test.
+     * @returns True if the key is present and not idle.
+     */
+    has(key: string): boolean;
+    /**
+     * Return all keys for entries that have not idled out.
+     * Idle entries encountered during iteration are evicted.
+     * Keys are returned in ascending frequency order; within the same frequency, LRU first.
+     * @returns An array of live keys ordered from least-frequently-used to most-frequently-used.
+     */
+    keys(): string[];
+    /**
+     * Remove an entry from the cache.
+     * Cancels the background timer if the cache becomes empty.
+     * @param key The key to remove.
+     */
+    delete(key: string): void;
+    /**
+     * Remove all entries from the cache and cancel the background timer.
+     */
+    clear(): void;
+    /**
+     * Stop the background idle-sweep timer and release all entries.
+     * The cache must not be used after this call.
+     */
+    destroy(): void;
+}

package/dist/types/utils/lruCache.d.ts

@@ -0,0 +1,97 @@
+/**
+ * A fixed-capacity LRU cache with time-to-idle eviction.
+ *
+ * Entries are removed in two ways:
+ * - Capacity eviction: when the cache is full the least-recently-used entry is removed first.
+ * - TTI eviction: a background timer sweeps idle entries every ttiMs milliseconds.
+ * The timer only runs while there are entries; it stops automatically when the cache empties.
+ *
+ * `get` and `set` both update an entry's LRU position and reset its idle timer.
+ * `has` is a pure peek it evicts idle entries but does not refresh a live entry's TTI.
+ * Call `destroy` when the cache is no longer needed to stop the background timer.
+ */
+export declare class LruCache<T = unknown> {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Default capacity.
+     */
+    static readonly DEFAULT_CAPACITY = 1000;
+    /**
+     * Default time-to-idle in milliseconds.
+     */
+    static readonly DEFAULT_TTI_MS = 10000;
+    /**
+     * Create a new instance of LruCache.
+     * @param options The cache options.
+     * @param options.capacity Maximum number of entries. Defaults to 1000. Must be a positive integer.
+     * @param options.ttiMs Time-to-idle in milliseconds. Defaults to 10000. Must be a positive integer.
+     * @param options.mutexTimeoutMs Maximum time in milliseconds to wait for getOrSet mutex acquisition.
+     * @throws ValidationError if capacity or ttiMs is not a positive integer.
+     */
+    constructor(options?: {
+        capacity?: number;
+        ttiMs?: number;
+        mutexTimeoutMs?: number;
+    });
+    /**
+     * The number of entries currently held in the cache.
+     * @returns The number of entries in the cache.
+     */
+    count(): number;
+    /**
+     * Get a value from the cache.
+     * Returns undefined if the key is absent or the entry has idled out.
+     * A successful hit resets the entry's idle timer and moves it to most-recently-used.
+     * @param key The key to retrieve.
+     * @returns The cached value, or undefined on a miss or idle eviction.
+     */
+    get(key: string): T | undefined;
+    /**
+     * Store a value in the cache.
+     * If the key already exists its value and idle timer are refreshed.
+     * When the cache is at capacity, idle entries are swept first; if it is still full the
+     * least-recently-used entry is evicted.
+     * @param key The key to store.
+     * @param value The value to cache.
+     */
+    set(key: string, value: T): void;
+    /**
+     * Atomically get an existing value or create and store it once using an async factory.
+     * Concurrent calls for the same key are serialized via a mutex.
+     * @param key The key to get or create.
+     * @param valueFactory Async callback used to build a value when the key is absent.
+     * @returns The existing or newly created value.
+     */
+    getOrSet(key: string, valueFactory: () => Promise<T>): Promise<T>;
+    /**
+     * Check whether a key exists in the cache and has not idled out.
+     * Idle entries are evicted on peek, but a live entry's TTI is not reset.
+     * @param key The key to test.
+     * @returns True if the key is present and not idle.
+     */
+    has(key: string): boolean;
+    /**
+     * Return all keys for entries that have not idled out.
+     * Idle entries encountered during iteration are evicted.
+     * @returns An array of live keys in least-recently-used to most-recently-used order.
+     */
+    keys(): string[];
+    /**
+     * Remove an entry from the cache.
+     * Cancels the background timer if the cache becomes empty.
+     * @param key The key to remove.
+     */
+    delete(key: string): void;
+    /**
+     * Remove all entries from the cache and cancel the background timer.
+     */
+    clear(): void;
+    /**
+     * Stop the background idle-sweep timer and release all entries.
+     * The cache must not be used after this call.
+     */
+    destroy(): void;
+}

package/docs/changelog.md

@@ -1,5 +1,79 @@
 # Changelog
 
+## [0.9.2](https://github.com/iotaledger/twin-framework/compare/core-v0.9.2...core-v0.9.2) (2026-08-24)
+
+
+### Features
+
+* release to production ([b24cba1](https://github.com/iotaledger/twin-framework/commit/b24cba1b6a969278d638e632590602ec881e49fb))
+* release to production ([787287d](https://github.com/iotaledger/twin-framework/commit/787287d06ea8319657401589d61fff369310c422))
+* release to production ([53f4843](https://github.com/iotaledger/twin-framework/commit/53f484326b2851d7a506d2620db24c4a65cee7b3))
+* release to production ([56cda4d](https://github.com/iotaledger/twin-framework/commit/56cda4da93e978c5be19ec7cfd421ae2a7fe4147))
+* release to production ([f7c6586](https://github.com/iotaledger/twin-framework/commit/f7c6586f6976b903b647b4c5ac5ad9421e0c9051))
+* release to production ([829d53d](https://github.com/iotaledger/twin-framework/commit/829d53d3953b1e1b40b0243c04cfdfd3842aac7b))
+* release to production ([5cf3a76](https://github.com/iotaledger/twin-framework/commit/5cf3a76a09eff2e6414d0cba846c7c37400a11d6))
+* release to production ([#330](https://github.com/iotaledger/twin-framework/issues/330)) ([d73f565](https://github.com/iotaledger/twin-framework/commit/d73f565588d156d23ef49b2a5718973756f7a696))
+* release to production ([#382](https://github.com/iotaledger/twin-framework/issues/382)) ([bbed01a](https://github.com/iotaledger/twin-framework/commit/bbed01a605ee9724bda77a0f7feab249118c2d90))
+* release to production ([#417](https://github.com/iotaledger/twin-framework/issues/417)) ([59727e7](https://github.com/iotaledger/twin-framework/commit/59727e73903a137310ca48fe469189cf29879cb9))
+* release to production ([#459](https://github.com/iotaledger/twin-framework/issues/459)) ([e26e2d9](https://github.com/iotaledger/twin-framework/commit/e26e2d9a88767364c32494c45232033447b26e22))
+
+
+### Miscellaneous Chores
+
+* release to production ([63cae24](https://github.com/iotaledger/twin-framework/commit/63cae2401f6c11f93b2a01260b665064e8bd28e0))
+
+## [0.9.2-next.11](https://github.com/iotaledger/twin-framework/compare/core-v0.9.2-next.10...core-v0.9.2-next.11) (2026-08-20)
+
+
+### Features
+
+* coerce array ([#452](https://github.com/iotaledger/twin-framework/issues/452)) ([2019567](https://github.com/iotaledger/twin-framework/commit/20195673a65fe7179272ac84f37dc927218c128a))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/nameof bumped from 0.9.2-next.10 to 0.9.2-next.11
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.9.2-next.10 to 0.9.2-next.11
+    * @twin.org/nameof-vitest-plugin bumped from 0.9.2-next.10 to 0.9.2-next.11
+
+## [0.9.2-next.10](https://github.com/iotaledger/twin-framework/compare/core-v0.9.2-next.9...core-v0.9.2-next.10) (2026-08-11)
+
+
+### Features
+
+* add lru and lft cache ([#449](https://github.com/iotaledger/twin-framework/issues/449)) ([67d741e](https://github.com/iotaledger/twin-framework/commit/67d741eab3b89556e3c55053b5a473a4c1592fed))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/nameof bumped from 0.9.2-next.9 to 0.9.2-next.10
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.9.2-next.9 to 0.9.2-next.10
+    * @twin.org/nameof-vitest-plugin bumped from 0.9.2-next.9 to 0.9.2-next.10
+
+## [0.9.2-next.9](https://github.com/iotaledger/twin-framework/compare/core-v0.9.2-next.8...core-v0.9.2-next.9) (2026-08-10)
+
+
+### Bug Fixes
+
+* number coercion wrongly accepts alpha ([c04c1af](https://github.com/iotaledger/twin-framework/commit/c04c1af24697b6c92a180a71c0722c5673313360))
+* number coercion wrongly accepts alpha ([dd5b193](https://github.com/iotaledger/twin-framework/commit/dd5b193c2501f6d30ca94aa0fc30a6edfe405e6f))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/nameof bumped from 0.9.2-next.8 to 0.9.2-next.9
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.9.2-next.8 to 0.9.2-next.9
+    * @twin.org/nameof-vitest-plugin bumped from 0.9.2-next.8 to 0.9.2-next.9
+
 ## [0.9.2-next.8](https://github.com/iotaledger/twin-framework/compare/core-v0.9.2-next.7...core-v0.9.2-next.8) (2026-08-10)
 
 

package/docs/reference/classes/Coerce.md

@@ -214,6 +214,34 @@ The duration object, or undefined if the value cannot be coerced.
 
 ***
 
+### array() {#array}
+
+> `static` **array**\<`T`\>(`value`): `T`[] \| `undefined`
+
+Coerce the value to an array.
+
+#### Type Parameters
+
+##### T
+
+`T` = `unknown`
+
+#### Parameters
+
+##### value
+
+`unknown`
+
+The value to coerce.
+
+#### Returns
+
+`T`[] \| `undefined`
+
+The coerced array, or undefined if the value cannot be coerced.
+
+***
+
 ### object() {#object}
 
 > `static` **object**\<`T`\>(`value`): `T` \| `undefined`