@catbee/utils 0.0.8-next.0 → 0.0.8-rc.1

package/build/esm/utils/cache.utils.js

@@ -0,0 +1,499 @@
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+import { config } from '../config';
+/**
+ * An in-memory cache with time-to-live (TTL) support for each entry.
+ *
+ * @typeParam K - Type of the key.
+ * @typeParam V - Type of the value.
+ *
+ * @example
+ * const cache = new TTLCache<string, number>({ ttlMs: 1000 });
+ * cache.set("x", 123);
+ * const value = cache.get("x"); // 123
+ */
+var TTLCache = /** @class */ (function () {
+    /**
+     * @param options - Configuration options for the cache
+     */
+    function TTLCache(options) {
+        if (options === void 0) { options = {}; }
+        var _this = this;
+        var _a;
+        this.cache = new Map();
+        this.ttlMs = (_a = options.ttlMs) !== null && _a !== void 0 ? _a : config.cache.defaultTtl;
+        this.maxSize = options.maxSize;
+        // Setup auto-cleanup if enabled
+        var autoCleanupMs = options.autoCleanupMs;
+        if (autoCleanupMs && autoCleanupMs > 0) {
+            this.cleanupInterval = setInterval(function () {
+                _this.cleanup();
+            }, autoCleanupMs);
+        }
+    }
+    /**
+     * Sets a key-value pair in the cache with the default TTL.
+     *
+     * @param key - The key to set.
+     * @param value - The value to associate with the key.
+     */
+    TTLCache.prototype.set = function (key, value) {
+        this.setWithTTL(key, value, this.ttlMs);
+    };
+    /**
+     * Sets a key-value pair in the cache with a custom TTL.
+     *
+     * @param key - The key to set.
+     * @param value - The value to associate with the key.
+     * @param ttlMs - Time-to-live in milliseconds.
+     */
+    TTLCache.prototype.setWithTTL = function (key, value, ttlMs) {
+        var now = Date.now();
+        var expiresAt = now + ttlMs;
+        if (this.cache.has(key)) {
+            this.cache.delete(key); // remove old entry to maintain LRU order
+        }
+        this.cache.set(key, { value: value, expiresAt: expiresAt, lastAccessed: now });
+        if (this.maxSize && this.cache.size > this.maxSize) {
+            this.evictLRU();
+        }
+    };
+    /**
+     * Retrieves the value for a given key if it hasn't expired.
+     *
+     * @param key - The key to retrieve.
+     * @returns The cached value, or undefined if not found or expired.
+     */
+    TTLCache.prototype.get = function (key) {
+        var entry = this.cache.get(key);
+        if (!entry)
+            return undefined;
+        var now = Date.now();
+        if (now > entry.expiresAt) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        // Update lastAccessed and move key to the end (most recently used)
+        entry.lastAccessed = now;
+        // Re-insert to end of Map to maintain LRU order
+        this.cache.delete(key);
+        this.cache.set(key, entry);
+        return entry.value;
+    };
+    /**
+     * Retrieves or computes a value if it's not in the cache or has expired.
+     *
+     * @param key - The key to retrieve
+     * @param producer - Function to generate the value if not cached
+     * @param ttlMs - Optional custom TTL for the computed value
+     * @returns The cached or computed value
+     */
+    TTLCache.prototype.getOrCompute = function (key, producer, ttlMs) {
+        return __awaiter(this, void 0, void 0, function () {
+            var value, newValue;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        value = this.get(key);
+                        if (value !== undefined)
+                            return [2 /*return*/, value];
+                        return [4 /*yield*/, producer()];
+                    case 1:
+                        newValue = _a.sent();
+                        this.setWithTTL(key, newValue, ttlMs !== null && ttlMs !== void 0 ? ttlMs : this.ttlMs);
+                        return [2 /*return*/, newValue];
+                }
+            });
+        });
+    };
+    /**
+     * Checks if the key exists and hasn't expired.
+     *
+     * @param key - The key to check.
+     * @returns `true` if key exists and is valid, otherwise `false`.
+     */
+    TTLCache.prototype.has = function (key) {
+        return this.get(key) !== undefined;
+    };
+    /**
+     * Deletes a key from the cache.
+     *
+     * @param key - The key to delete.
+     * @returns `true` if the key existed and was removed, `false` otherwise.
+     */
+    TTLCache.prototype.delete = function (key) {
+        return this.cache.delete(key);
+    };
+    /**
+     * Clears all entries from the cache.
+     */
+    TTLCache.prototype.clear = function () {
+        this.cache.clear();
+    };
+    /**
+     * Returns the number of entries currently in the cache (includes expired entries until next access/cleanup).
+     *
+     * @returns Number of items in the cache (may include expired keys).
+     */
+    TTLCache.prototype.size = function () {
+        return this.cache.size;
+    };
+    /**
+     * Set multiple key-value pairs at once with the default TTL.
+     *
+     * @param entries - Array of [key, value] tuples to set
+     */
+    TTLCache.prototype.setMany = function (entries) {
+        var e_1, _a;
+        try {
+            for (var entries_1 = __values(entries), entries_1_1 = entries_1.next(); !entries_1_1.done; entries_1_1 = entries_1.next()) {
+                var _b = __read(entries_1_1.value, 2), key = _b[0], value = _b[1];
+                this.set(key, value);
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (entries_1_1 && !entries_1_1.done && (_a = entries_1.return)) _a.call(entries_1);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+    };
+    /**
+     * Get multiple values at once.
+     *
+     * @param keys - Array of keys to retrieve
+     * @returns Array of values (undefined for keys that don't exist or expired)
+     */
+    TTLCache.prototype.getMany = function (keys) {
+        var _this = this;
+        return keys.map(function (key) { return _this.get(key); });
+    };
+    /**
+     * Removes all expired entries from the cache.
+     *
+     * @returns Number of entries removed.
+     */
+    TTLCache.prototype.cleanup = function () {
+        var e_2, _a;
+        var removed = 0;
+        var now = Date.now();
+        try {
+            for (var _b = __values(this.cache.entries()), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var _d = __read(_c.value, 2), key = _d[0], entry = _d[1];
+                if (now > entry.expiresAt) {
+                    this.cache.delete(key);
+                    removed++;
+                }
+            }
+        }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        finally {
+            try {
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+            }
+            finally { if (e_2) throw e_2.error; }
+        }
+        return removed;
+    };
+    /**
+     * Returns an iterator of all current valid [key, value] pairs.
+     *
+     * @returns IterableIterator<[K, V]>
+     */
+    TTLCache.prototype.entries = function () {
+        var _a, _b, _c, key, entry, e_3_1;
+        var e_3, _d;
+        return __generator(this, function (_e) {
+            switch (_e.label) {
+                case 0:
+                    _e.trys.push([0, 5, 6, 7]);
+                    _a = __values(this.cache.entries()), _b = _a.next();
+                    _e.label = 1;
+                case 1:
+                    if (!!_b.done) return [3 /*break*/, 4];
+                    _c = __read(_b.value, 2), key = _c[0], entry = _c[1];
+                    if (!(Date.now() <= entry.expiresAt)) return [3 /*break*/, 3];
+                    return [4 /*yield*/, [key, entry.value]];
+                case 2:
+                    _e.sent();
+                    _e.label = 3;
+                case 3:
+                    _b = _a.next();
+                    return [3 /*break*/, 1];
+                case 4: return [3 /*break*/, 7];
+                case 5:
+                    e_3_1 = _e.sent();
+                    e_3 = { error: e_3_1 };
+                    return [3 /*break*/, 7];
+                case 6:
+                    try {
+                        if (_b && !_b.done && (_d = _a.return)) _d.call(_a);
+                    }
+                    finally { if (e_3) throw e_3.error; }
+                    return [7 /*endfinally*/];
+                case 7: return [2 /*return*/];
+            }
+        });
+    };
+    /**
+     * Returns an iterator of all current valid keys.
+     *
+     * @returns IterableIterator<K>
+     */
+    TTLCache.prototype.keys = function () {
+        var _a, _b, _c, key, entry, e_4_1;
+        var e_4, _d;
+        return __generator(this, function (_e) {
+            switch (_e.label) {
+                case 0:
+                    _e.trys.push([0, 5, 6, 7]);
+                    _a = __values(this.cache.entries()), _b = _a.next();
+                    _e.label = 1;
+                case 1:
+                    if (!!_b.done) return [3 /*break*/, 4];
+                    _c = __read(_b.value, 2), key = _c[0], entry = _c[1];
+                    if (!(Date.now() <= entry.expiresAt)) return [3 /*break*/, 3];
+                    return [4 /*yield*/, key];
+                case 2:
+                    _e.sent();
+                    _e.label = 3;
+                case 3:
+                    _b = _a.next();
+                    return [3 /*break*/, 1];
+                case 4: return [3 /*break*/, 7];
+                case 5:
+                    e_4_1 = _e.sent();
+                    e_4 = { error: e_4_1 };
+                    return [3 /*break*/, 7];
+                case 6:
+                    try {
+                        if (_b && !_b.done && (_d = _a.return)) _d.call(_a);
+                    }
+                    finally { if (e_4) throw e_4.error; }
+                    return [7 /*endfinally*/];
+                case 7: return [2 /*return*/];
+            }
+        });
+    };
+    /**
+     * Returns an iterator of all current valid values.
+     *
+     * @returns IterableIterator<V>
+     */
+    TTLCache.prototype.values = function () {
+        var _a, _b, entry, e_5_1;
+        var e_5, _c;
+        return __generator(this, function (_d) {
+            switch (_d.label) {
+                case 0:
+                    _d.trys.push([0, 5, 6, 7]);
+                    _a = __values(this.cache.values()), _b = _a.next();
+                    _d.label = 1;
+                case 1:
+                    if (!!_b.done) return [3 /*break*/, 4];
+                    entry = _b.value;
+                    if (!(Date.now() <= entry.expiresAt)) return [3 /*break*/, 3];
+                    return [4 /*yield*/, entry.value];
+                case 2:
+                    _d.sent();
+                    _d.label = 3;
+                case 3:
+                    _b = _a.next();
+                    return [3 /*break*/, 1];
+                case 4: return [3 /*break*/, 7];
+                case 5:
+                    e_5_1 = _d.sent();
+                    e_5 = { error: e_5_1 };
+                    return [3 /*break*/, 7];
+                case 6:
+                    try {
+                        if (_b && !_b.done && (_c = _a.return)) _c.call(_a);
+                    }
+                    finally { if (e_5) throw e_5.error; }
+                    return [7 /*endfinally*/];
+                case 7: return [2 /*return*/];
+            }
+        });
+    };
+    /**
+     * Extends the expiration of a key by the specified time or default TTL.
+     *
+     * @param key - The key to refresh
+     * @param ttlMs - Optional new TTL in milliseconds (uses default if not specified)
+     * @returns true if the key was found and refreshed, false otherwise
+     */
+    TTLCache.prototype.refresh = function (key, ttlMs) {
+        var entry = this.cache.get(key);
+        if (!entry)
+            return false;
+        var now = Date.now();
+        if (now > entry.expiresAt) {
+            this.cache.delete(key);
+            return false;
+        }
+        entry.expiresAt = now + (ttlMs !== null && ttlMs !== void 0 ? ttlMs : this.ttlMs);
+        entry.lastAccessed = now;
+        return true;
+    };
+    /**
+     * Returns a snapshot of cache stats.
+     *
+     * @returns Object containing cache statistics
+     */
+    TTLCache.prototype.stats = function () {
+        var e_6, _a;
+        var now = Date.now();
+        var expired = 0;
+        var valid = 0;
+        try {
+            for (var _b = __values(this.cache.values()), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var entry = _c.value;
+                if (now > entry.expiresAt) {
+                    expired++;
+                }
+                else {
+                    valid++;
+                }
+            }
+        }
+        catch (e_6_1) { e_6 = { error: e_6_1 }; }
+        finally {
+            try {
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+            }
+            finally { if (e_6) throw e_6.error; }
+        }
+        return {
+            size: this.cache.size,
+            validEntries: valid,
+            expiredEntries: expired,
+            maxSize: this.maxSize
+        };
+    };
+    /**
+     * Stop the auto-cleanup interval if it's running.
+     */
+    TTLCache.prototype.destroy = function () {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = undefined;
+        }
+    };
+    /**
+     * Evict the least recently used entry from the cache.
+     * @private
+     */
+    TTLCache.prototype.evictLRU = function () {
+        var e_7, _a;
+        var now = Date.now();
+        try {
+            // Remove all expired items first
+            for (var _b = __values(Array.from(this.cache.entries())), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var _d = __read(_c.value, 2), key = _d[0], entry = _d[1];
+                if (now > entry.expiresAt) {
+                    this.cache.delete(key);
+                }
+            }
+        }
+        catch (e_7_1) { e_7 = { error: e_7_1 }; }
+        finally {
+            try {
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+            }
+            finally { if (e_7) throw e_7.error; }
+        }
+        // Evict oldest entries until within max size
+        while (this.maxSize && this.cache.size > this.maxSize) {
+            var oldestKey = this.cache.keys().next().value;
+            this.cache.delete(oldestKey);
+        }
+    };
+    return TTLCache;
+}());
+export { TTLCache };
+//# sourceMappingURL=cache.utils.js.map

package/build/esm/utils/cache.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.utils.js","sourceRoot":"","sources":["../../../src/utils/cache.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { config } from '../config';\n\n/**\n * Represents a cached entry with a value and an expiration timestamp.\n */\ntype CacheEntry<T> = {\n  value: T;\n  expiresAt: number;\n  lastAccessed?: number; // Track last access time for LRU functionality\n};\n\n/**\n * Options for configuring a TTLCache instance.\n */\nexport interface TTLCacheOptions {\n  /** Default time-to-live in milliseconds for cache entries */\n  ttlMs?: number;\n  /** Maximum number of entries to keep in cache (uses LRU eviction policy) */\n  maxSize?: number;\n  /** Auto-cleanup interval in milliseconds (disabled if 0 or negative) */\n  autoCleanupMs?: number;\n}\n\n/**\n * An in-memory cache with time-to-live (TTL) support for each entry.\n *\n * @typeParam K - Type of the key.\n * @typeParam V - Type of the value.\n *\n * @example\n * const cache = new TTLCache<string, number>({ ttlMs: 1000 });\n * cache.set(\"x\", 123);\n * const value = cache.get(\"x\"); // 123\n */\nexport class TTLCache<K, V> {\n  private cache = new Map<K, CacheEntry<V>>();\n  private ttlMs: number;\n  private maxSize?: number;\n  private cleanupInterval?: NodeJS.Timeout;\n\n  /**\n   * @param options - Configuration options for the cache\n   */\n  constructor(options: TTLCacheOptions = {}) {\n    this.ttlMs = options.ttlMs ?? config.cache.defaultTtl;\n    this.maxSize = options.maxSize;\n\n    // Setup auto-cleanup if enabled\n    const autoCleanupMs = options.autoCleanupMs;\n    if (autoCleanupMs && autoCleanupMs > 0) {\n      this.cleanupInterval = setInterval(() => {\n        this.cleanup();\n      }, autoCleanupMs);\n    }\n  }\n\n  /**\n   * Sets a key-value pair in the cache with the default TTL.\n   *\n   * @param key - The key to set.\n   * @param value - The value to associate with the key.\n   */\n  set(key: K, value: V): void {\n    this.setWithTTL(key, value, this.ttlMs);\n  }\n\n  /**\n   * Sets a key-value pair in the cache with a custom TTL.\n   *\n   * @param key - The key to set.\n   * @param value - The value to associate with the key.\n   * @param ttlMs - Time-to-live in milliseconds.\n   */\n  setWithTTL(key: K, value: V, ttlMs: number): void {\n    const now = Date.now();\n    const expiresAt = now + ttlMs;\n\n    if (this.cache.has(key)) {\n      this.cache.delete(key); // remove old entry to maintain LRU order\n    }\n\n    this.cache.set(key, { value, expiresAt, lastAccessed: now });\n\n    if (this.maxSize && this.cache.size > this.maxSize) {\n      this.evictLRU();\n    }\n  }\n\n  /**\n   * Retrieves the value for a given key if it hasn't expired.\n   *\n   * @param key - The key to retrieve.\n   * @returns The cached value, or undefined if not found or expired.\n   */\n  get(key: K): V | undefined {\n    const entry = this.cache.get(key);\n    if (!entry) return undefined;\n\n    const now = Date.now();\n    if (now > entry.expiresAt) {\n      this.cache.delete(key);\n      return undefined;\n    }\n\n    // Update lastAccessed and move key to the end (most recently used)\n    entry.lastAccessed = now;\n    // Re-insert to end of Map to maintain LRU order\n    this.cache.delete(key);\n    this.cache.set(key, entry);\n\n    return entry.value;\n  }\n\n  /**\n   * Retrieves or computes a value if it's not in the cache or has expired.\n   *\n   * @param key - The key to retrieve\n   * @param producer - Function to generate the value if not cached\n   * @param ttlMs - Optional custom TTL for the computed value\n   * @returns The cached or computed value\n   */\n  async getOrCompute(key: K, producer: () => Promise<V>, ttlMs?: number): Promise<V> {\n    const value = this.get(key);\n    if (value !== undefined) return value;\n\n    const newValue = await producer();\n    this.setWithTTL(key, newValue, ttlMs ?? this.ttlMs);\n    return newValue;\n  }\n\n  /**\n   * Checks if the key exists and hasn't expired.\n   *\n   * @param key - The key to check.\n   * @returns `true` if key exists and is valid, otherwise `false`.\n   */\n  has(key: K): boolean {\n    return this.get(key) !== undefined;\n  }\n\n  /**\n   * Deletes a key from the cache.\n   *\n   * @param key - The key to delete.\n   * @returns `true` if the key existed and was removed, `false` otherwise.\n   */\n  delete(key: K): boolean {\n    return this.cache.delete(key);\n  }\n\n  /**\n   * Clears all entries from the cache.\n   */\n  clear(): void {\n    this.cache.clear();\n  }\n\n  /**\n   * Returns the number of entries currently in the cache (includes expired entries until next access/cleanup).\n   *\n   * @returns Number of items in the cache (may include expired keys).\n   */\n  size(): number {\n    return this.cache.size;\n  }\n\n  /**\n   * Set multiple key-value pairs at once with the default TTL.\n   *\n   * @param entries - Array of [key, value] tuples to set\n   */\n  setMany(entries: [K, V][]): void {\n    for (const [key, value] of entries) {\n      this.set(key, value);\n    }\n  }\n\n  /**\n   * Get multiple values at once.\n   *\n   * @param keys - Array of keys to retrieve\n   * @returns Array of values (undefined for keys that don't exist or expired)\n   */\n  getMany(keys: K[]): (V | undefined)[] {\n    return keys.map(key => this.get(key));\n  }\n\n  /**\n   * Removes all expired entries from the cache.\n   *\n   * @returns Number of entries removed.\n   */\n  cleanup(): number {\n    let removed = 0;\n    const now = Date.now();\n    for (const [key, entry] of this.cache.entries()) {\n      if (now > entry.expiresAt) {\n        this.cache.delete(key);\n        removed++;\n      }\n    }\n    return removed;\n  }\n\n  /**\n   * Returns an iterator of all current valid [key, value] pairs.\n   *\n   * @returns IterableIterator<[K, V]>\n   */\n  *entries(): IterableIterator<[K, V]> {\n    for (const [key, entry] of this.cache.entries()) {\n      if (Date.now() <= entry.expiresAt) {\n        yield [key, entry.value];\n      }\n    }\n  }\n\n  /**\n   * Returns an iterator of all current valid keys.\n   *\n   * @returns IterableIterator<K>\n   */\n  *keys(): IterableIterator<K> {\n    for (const [key, entry] of this.cache.entries()) {\n      if (Date.now() <= entry.expiresAt) {\n        yield key;\n      }\n    }\n  }\n\n  /**\n   * Returns an iterator of all current valid values.\n   *\n   * @returns IterableIterator<V>\n   */\n  *values(): IterableIterator<V> {\n    for (const entry of this.cache.values()) {\n      if (Date.now() <= entry.expiresAt) {\n        yield entry.value;\n      }\n    }\n  }\n\n  /**\n   * Extends the expiration of a key by the specified time or default TTL.\n   *\n   * @param key - The key to refresh\n   * @param ttlMs - Optional new TTL in milliseconds (uses default if not specified)\n   * @returns true if the key was found and refreshed, false otherwise\n   */\n  refresh(key: K, ttlMs?: number): boolean {\n    const entry = this.cache.get(key);\n    if (!entry) return false;\n\n    const now = Date.now();\n    if (now > entry.expiresAt) {\n      this.cache.delete(key);\n      return false;\n    }\n\n    entry.expiresAt = now + (ttlMs ?? this.ttlMs);\n    entry.lastAccessed = now;\n    return true;\n  }\n\n  /**\n   * Returns a snapshot of cache stats.\n   *\n   * @returns Object containing cache statistics\n   */\n  stats() {\n    const now = Date.now();\n    let expired = 0;\n    let valid = 0;\n\n    for (const entry of this.cache.values()) {\n      if (now > entry.expiresAt) {\n        expired++;\n      } else {\n        valid++;\n      }\n    }\n\n    return {\n      size: this.cache.size,\n      validEntries: valid,\n      expiredEntries: expired,\n      maxSize: this.maxSize\n    };\n  }\n\n  /**\n   * Stop the auto-cleanup interval if it's running.\n   */\n  destroy() {\n    if (this.cleanupInterval) {\n      clearInterval(this.cleanupInterval);\n      this.cleanupInterval = undefined;\n    }\n  }\n\n  /**\n   * Evict the least recently used entry from the cache.\n   * @private\n   */\n  private evictLRU(): void {\n    const now = Date.now();\n\n    // Remove all expired items first\n    for (const [key, entry] of Array.from(this.cache.entries())) {\n      if (now > entry.expiresAt) {\n        this.cache.delete(key);\n      }\n    }\n\n    // Evict oldest entries until within max size\n    while (this.maxSize && this.cache.size > this.maxSize) {\n      const oldestKey = this.cache.keys().next().value;\n      this.cache.delete(oldestKey as K);\n    }\n  }\n}\n"]}