@c9up/echo 0.1.5 → 0.1.6

package/dist/CacheManager.d.ts

@@ -1,48 +1,83 @@
 /**
- * CacheManager — unified cache API with driver abstraction.
+ * CacheManager — a single cache store with a unified, bentocache/@adonisjs/cache
+ * parity API over a pluggable {@link CacheDriver}.
+ *
+ * Every read/write method accepts EITHER the Adonis/bento object form
+ * (`get({ key })`, `set({ key, value, ttl, tags })`, `getOrSet({ key, factory,
+ * … })`) OR echo's original positional form (`get(key)`, `set(key, value,
+ * ttlSeconds)`, `getOrSet(key, ttlSeconds, factory)`). The object form is the
+ * canonical one; the positional form is kept for back-compat.
  */
-export interface CacheDriver {
-    get<T = unknown>(key: string): Promise<T | null>;
-    set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
-    delete(key: string): Promise<boolean>;
-    flush(): Promise<void>;
-    has(key: string): Promise<boolean>;
-}
+import { type Duration } from "./duration.js";
+import type { CacheEmitter, DeleteByTagOptions, DeleteManyOptions, DeleteOptions, ExpireOptions, Factory, GetOptions, GetOrSetForeverOptions, GetOrSetOptions, HasOptions, SetOptions } from "./types.js";
+export type { CacheDriver } from "./types.js";
+import type { CacheDriver } from "./types.js";
 export interface CacheConfig {
     driver?: string;
     prefix?: string;
+    /** Default TTL in **seconds** (echo-native unit; see `duration.ts`). */
     ttl?: number;
+    /** Default grace period (stale-while-revalidate) as a {@link Duration}. */
+    grace?: Duration;
+    /** Default soft timeout for `getOrSet` (return stale if the factory is slower). */
+    timeout?: Duration;
+    /** Default hard timeout for `getOrSet`. */
+    hardTimeout?: Duration;
+    /** Default single-flight lock wait before falling back to stale. */
+    lockTimeout?: Duration;
+    /** Store name reported in events (default `"default"`). */
+    name?: string;
+    /** Optional event emitter (`cache:hit` / `miss` / `written` / `deleted` / `cleared`). */
+    emitter?: CacheEmitter;
+}
+/** Shared single-flight state — one map per store, threaded through namespaces. */
+interface SharedState {
+    inflight: Map<string, {
+        promise: Promise<unknown>;
+    }>;
 }
 export declare class CacheManager {
-    private driver;
-    private prefix;
-    private defaultTtl;
-    constructor(driver: CacheDriver, config?: CacheConfig);
-    private prefixKey;
+    #private;
+    constructor(driver: CacheDriver, config?: CacheConfig, shared?: SharedState);
     get<T = unknown>(key: string): Promise<T | null>;
+    get<T = unknown>(options: GetOptions<T>): Promise<T | null>;
     set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    set(options: SetOptions): Promise<void>;
+    /** Set a value that never expires (bento `setForever`). */
+    setForever(options: Omit<SetOptions, "ttl">): Promise<void>;
     delete(key: string): Promise<boolean>;
-    /** Clear the whole cache (AdonisJS `cache.clear()`). */
-    clear(): Promise<void>;
+    delete(options: DeleteOptions): Promise<boolean>;
+    /** Delete multiple keys (bento `deleteMany`). */
+    deleteMany(keysOrOptions: string[] | DeleteManyOptions): Promise<boolean>;
     has(key: string): Promise<boolean>;
+    has(options: HasOptions): Promise<boolean>;
+    /** Inverse of {@link has} (bento `missing`). */
+    missing(keyOrOptions: string | HasOptions): Promise<boolean>;
+    /** Read a key and delete it in one step (bento `pull`). Returns `null` on miss. */
+    pull<T = unknown>(key: string): Promise<T | null>;
     /**
-     * A cache view scoped under an extra key prefix (AdonisJS `cache.namespace()`).
-     * `cache.namespace('users').get('42')` reads/writes `users:42` (composed with
-     * any existing prefix). Shares the same driver + default TTL.
+     * Expire a key: mark it stale immediately while retaining it for the grace
+     * window (bento `expire`). Without grace this is equivalent to a delete.
      */
-    namespace(ns: string): CacheManager;
-    /** Set a value with tags for grouped invalidation. */
+    expire(keyOrOptions: string | ExpireOptions): Promise<boolean>;
+    /** Clear the whole store (bento/Adonis `clear`). */
+    clear(): Promise<void>;
+    /** Set a value with tags for grouped invalidation (bento parity). */
     setWithTags(key: string, value: unknown, tags: string[], ttlSeconds?: number): Promise<void>;
-    /** Flush only entries with matching tags. */
+    /** Invalidate all entries carrying any of the given tags (bento `deleteByTag`). */
+    deleteByTag(tags: string[]): Promise<void>;
+    deleteByTag(options: DeleteByTagOptions): Promise<void>;
+    /** @deprecated alias of {@link deleteByTag}. */
     flushTags(tags: string[]): Promise<void>;
-    /** In-flight promises for stampede prevention. Each factory is typed per-call; the map is keyed by prefixed cache key. */
-    private inflight;
     /**
-     * Fetch from cache, or compute via `factory` and store (AdonisJS
-     * `cache.getOrSet`). Single-flight: concurrent misses share one factory call.
-     * (Positional `(key, ttl, factory)` is a deliberate simplification over
-     * Adonis's object form — echo keeps a leaner cache surface.)
+     * A cache view scoped under an extra key prefix (Adonis `cache.namespace()`).
+     * Shares the SAME driver, defaults, emitter AND single-flight state, so a
+     * `getOrSet` stampede is collapsed across namespace views of the same key.
      */
-    getOrSet<T>(key: string, ttl: number, factory: () => Promise<T>): Promise<T>;
+    namespace(ns: string): CacheManager;
+    getOrSet<T>(key: string, ttlSeconds: number, factory: Factory<T>): Promise<T>;
+    getOrSet<T>(options: GetOrSetOptions<T>): Promise<T>;
+    /** Like {@link getOrSet} but the stored value never expires (bento `getOrSetForever`). */
+    getOrSetForever<T>(options: GetOrSetForeverOptions<T>): Promise<T>;
 }
 //# sourceMappingURL=CacheManager.d.ts.map

package/dist/CacheManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CacheManager.d.ts","sourceRoot":"","sources":["../src/CacheManager.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,WAAW;IAC3B,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACjD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnC;AAoBD,MAAM,WAAW,WAAW;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED,qBAAa,YAAY;IACxB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAS;gBAEf,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,WAAW;IAMrD,OAAO,CAAC,SAAS;IAIX,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAIhD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAapE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI3C,wDAAwD;IAClD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIxC;;;;OAIG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY;IAOnC,sDAAsD;IAChD,WAAW,CAChB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EAAE,EACd,UAAU,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC;IAmBhB,6CAA6C;IACvC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9C,0HAA0H;IAC1H,OAAO,CAAC,QAAQ,CAA4C;IAE5D;;;;;OAKG;IACG,QAAQ,CAAC,CAAC,EACf,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC;CA0Bb"}
+{"version":3,"file":"CacheManager.d.ts","sourceRoot":"","sources":["../src/CacheManager.ts"],"names":[],"mappings":"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"}

package/dist/CacheManager.js

@@ -1,101 +1,379 @@
 /**
- * CacheManager — unified cache API with driver abstraction.
+ * CacheManager — a single cache store with a unified, bentocache/@adonisjs/cache
+ * parity API over a pluggable {@link CacheDriver}.
+ *
+ * Every read/write method accepts EITHER the Adonis/bento object form
+ * (`get({ key })`, `set({ key, value, ttl, tags })`, `getOrSet({ key, factory,
+ * … })`) OR echo's original positional form (`get(key)`, `set(key, value,
+ * ttlSeconds)`, `getOrSet(key, ttlSeconds, factory)`). The object form is the
+ * canonical one; the positional form is kept for back-compat.
  */
+import { parseDuration, resolveTtlSeconds } from "./duration.js";
+import { FactoryError, TimeoutError } from "./errors.js";
 function isTaggableDriver(driver) {
     const candidate = driver;
-    return (typeof candidate.flushTags === "function" &&
-        typeof candidate.setWithTags === "function");
+    return (typeof candidate.setWithTags === "function" &&
+        (typeof candidate.deleteByTag === "function" ||
+            typeof candidate.flushTags === "function"));
+}
+/** Resolve an optional {@link Duration} to milliseconds; `undefined` when unset. */
+function resolveMs(duration) {
+    if (duration === undefined || duration === null)
+        return undefined;
+    const seconds = typeof duration === "number" ? duration : parseDuration(duration);
+    return Math.max(0, seconds) * 1000;
+}
+const TIMEOUT = Symbol("echo.timeout");
+function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => resolve(TIMEOUT), ms);
+        if (typeof timer === "object" && "unref" in timer) {
+            timer.unref();
+        }
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
 }
 export class CacheManager {
-    driver;
-    prefix;
-    defaultTtl;
-    constructor(driver, config) {
-        this.driver = driver;
-        this.prefix = config?.prefix ?? "";
-        this.defaultTtl = config?.ttl ?? 3600;
+    #driver;
+    #prefix;
+    #defaultTtl;
+    #defaultGrace;
+    #defaultTimeout;
+    #defaultHardTimeout;
+    #defaultLockTimeout;
+    #name;
+    #emitter;
+    #shared;
+    constructor(driver, config, shared) {
+        this.#driver = driver;
+        this.#prefix = config?.prefix ?? "";
+        this.#defaultTtl = config?.ttl ?? 3600;
+        this.#defaultGrace = config?.grace;
+        this.#defaultTimeout = config?.timeout;
+        this.#defaultHardTimeout = config?.hardTimeout;
+        this.#defaultLockTimeout = config?.lockTimeout;
+        this.#name = config?.name ?? "default";
+        this.#emitter = config?.emitter;
+        this.#shared = shared ?? { inflight: new Map() };
+    }
+    #prefixKey(key) {
+        return this.#prefix ? `${this.#prefix}:${key}` : key;
     }
-    prefixKey(key) {
-        return this.prefix ? `${this.prefix}:${key}` : key;
+    #emit(event, payload) {
+        this.#emitter?.emit(event, payload);
     }
-    async get(key) {
-        return this.driver.get(this.prefixKey(key));
+    async #readEntry(prefixed) {
+        if (this.#driver.getEntry)
+            return this.#driver.getEntry(prefixed);
+        const value = await this.#driver.get(prefixed);
+        return value === null ? null : { value, stale: false };
     }
-    async set(key, value, ttlSeconds) {
+    async #writeValue(prefixed, value, ttlSeconds, graceSeconds, tags) {
         if (value === null || value === undefined) {
+            // Named divergence (fail-loud): unlike bento (which no-ops), echo throws
+            // on caching null/undefined — a null cache write is almost always a bug.
             throw new TypeError("Echo: caching null/undefined values is not supported");
         }
-        return this.driver.set(this.prefixKey(key), value, ttlSeconds ?? this.defaultTtl);
+        if (this.#driver.setEntry) {
+            await this.#driver.setEntry(prefixed, value, {
+                ttlSeconds,
+                graceSeconds,
+                tags,
+            });
+            return;
+        }
+        if (tags.length > 0) {
+            if (!isTaggableDriver(this.#driver)) {
+                throw new Error("Echo: the configured driver does not support tag-based invalidation");
+            }
+            await this.#driver.setWithTags(prefixed, value, tags, ttlSeconds);
+            return;
+        }
+        await this.#driver.set(prefixed, value, ttlSeconds);
     }
-    async delete(key) {
-        return this.driver.delete(this.prefixKey(key));
+    async get(keyOrOptions) {
+        const key = typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
+        const graceSeconds = typeof keyOrOptions === "string"
+            ? resolveTtlSeconds(this.#defaultGrace, 0)
+            : resolveTtlSeconds(keyOrOptions.grace ?? this.#defaultGrace, 0);
+        const defaultValue = typeof keyOrOptions === "string" ? undefined : keyOrOptions.defaultValue;
+        const entry = await this.#readEntry(this.#prefixKey(key));
+        if (entry && !entry.stale) {
+            this.#emit("cache:hit", {
+                key,
+                value: entry.value,
+                store: this.#name,
+                graced: false,
+            });
+            return entry.value;
+        }
+        if (entry && entry.stale && graceSeconds > 0) {
+            this.#emit("cache:hit", {
+                key,
+                value: entry.value,
+                store: this.#name,
+                graced: true,
+            });
+            return entry.value;
+        }
+        this.#emit("cache:miss", { key, store: this.#name });
+        if (defaultValue !== undefined) {
+            return defaultValue instanceof Function ? defaultValue() : defaultValue;
+        }
+        return null;
     }
-    /** Clear the whole cache (AdonisJS `cache.clear()`). */
-    async clear() {
-        return this.driver.flush();
+    async set(keyOrOptions, value, ttlSeconds) {
+        let key;
+        let val;
+        let ttl;
+        let graceSeconds;
+        let tags;
+        if (typeof keyOrOptions === "string") {
+            key = keyOrOptions;
+            val = value;
+            ttl = ttlSeconds ?? this.#defaultTtl;
+            graceSeconds = 0;
+            tags = [];
+        }
+        else {
+            key = keyOrOptions.key;
+            val = keyOrOptions.value;
+            ttl = resolveTtlSeconds(keyOrOptions.ttl, this.#defaultTtl);
+            graceSeconds = resolveTtlSeconds(keyOrOptions.grace ?? this.#defaultGrace, 0);
+            tags = keyOrOptions.tags ?? [];
+        }
+        await this.#writeValue(this.#prefixKey(key), val, ttl, graceSeconds, tags);
+        this.#emit("cache:written", { key, value: val, store: this.#name });
+    }
+    /** Set a value that never expires (bento `setForever`). */
+    setForever(options) {
+        return this.set({ ...options, ttl: null });
+    }
+    async delete(keyOrOptions) {
+        const key = typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
+        const deleted = await this.#driver.delete(this.#prefixKey(key));
+        this.#emit("cache:deleted", { key, store: this.#name });
+        return deleted;
+    }
+    /** Delete multiple keys (bento `deleteMany`). */
+    async deleteMany(keysOrOptions) {
+        const keys = Array.isArray(keysOrOptions)
+            ? keysOrOptions
+            : keysOrOptions.keys;
+        let all = true;
+        for (const key of keys) {
+            const ok = await this.#driver.delete(this.#prefixKey(key));
+            this.#emit("cache:deleted", { key, store: this.#name });
+            if (!ok)
+                all = false;
+        }
+        return all;
+    }
+    async has(keyOrOptions) {
+        const key = typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
+        return this.#driver.has(this.#prefixKey(key));
+    }
+    /** Inverse of {@link has} (bento `missing`). */
+    async missing(keyOrOptions) {
+        const key = typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
+        return !(await this.has(key));
     }
-    async has(key) {
-        return this.driver.has(this.prefixKey(key));
+    /** Read a key and delete it in one step (bento `pull`). Returns `null` on miss. */
+    async pull(key) {
+        const value = await this.get(key);
+        if (value !== null)
+            await this.delete(key);
+        return value;
     }
     /**
-     * A cache view scoped under an extra key prefix (AdonisJS `cache.namespace()`).
-     * `cache.namespace('users').get('42')` reads/writes `users:42` (composed with
-     * any existing prefix). Shares the same driver + default TTL.
+     * Expire a key: mark it stale immediately while retaining it for the grace
+     * window (bento `expire`). Without grace this is equivalent to a delete.
      */
-    namespace(ns) {
-        return new CacheManager(this.driver, {
-            prefix: this.prefix ? `${this.prefix}:${ns}` : ns,
-            ttl: this.defaultTtl,
-        });
+    async expire(keyOrOptions) {
+        const key = typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
+        const prefixed = this.#prefixKey(key);
+        const graceSeconds = resolveTtlSeconds(this.#defaultGrace, 0);
+        const entry = await this.#readEntry(prefixed);
+        if (entry === null)
+            return false;
+        if (graceSeconds > 0 && this.#driver.setEntry) {
+            // Mark the entry stale RIGHT NOW (logical expiry one ms in the past) while
+            // keeping it physically for the grace window. A positive `ttlSeconds`
+            // would leave a brief fresh window during which the value is still served
+            // and the factory never runs.
+            await this.#driver.setEntry(prefixed, entry.value, {
+                expiresAt: Date.now() - 1,
+                graceSeconds,
+            });
+            return true;
+        }
+        return this.#driver.delete(prefixed);
+    }
+    /** Clear the whole store (bento/Adonis `clear`). */
+    async clear() {
+        await this.#driver.flush();
+        this.#emit("cache:cleared", { store: this.#name });
     }
-    /** Set a value with tags for grouped invalidation. */
+    // ---- tags ------------------------------------------------------------
+    /** Set a value with tags for grouped invalidation (bento parity). */
     async setWithTags(key, value, tags, ttlSeconds) {
-        if (value === null || value === undefined) {
-            throw new TypeError("Echo: caching null/undefined values is not supported");
-        }
-        if (!isTaggableDriver(this.driver)) {
+        await this.#writeValue(this.#prefixKey(key), value, ttlSeconds ?? this.#defaultTtl, 0, tags);
+        this.#emit("cache:written", { key, value, store: this.#name });
+    }
+    async deleteByTag(tagsOrOptions) {
+        const tags = Array.isArray(tagsOrOptions)
+            ? tagsOrOptions
+            : tagsOrOptions.tags;
+        if (!isTaggableDriver(this.#driver)) {
             throw new Error("Echo: the configured driver does not support tag-based invalidation");
         }
-        return this.driver.setWithTags(this.prefixKey(key), value, tags, ttlSeconds ?? this.defaultTtl);
+        if (typeof this.#driver.deleteByTag === "function") {
+            return this.#driver.deleteByTag(tags);
+        }
+        return this.#driver.flushTags(tags);
     }
-    /** Flush only entries with matching tags. */
+    /** @deprecated alias of {@link deleteByTag}. */
     async flushTags(tags) {
-        if (isTaggableDriver(this.driver)) {
-            return this.driver.flushTags(tags);
+        return this.deleteByTag(tags);
+    }
+    // ---- namespace -------------------------------------------------------
+    /**
+     * A cache view scoped under an extra key prefix (Adonis `cache.namespace()`).
+     * Shares the SAME driver, defaults, emitter AND single-flight state, so a
+     * `getOrSet` stampede is collapsed across namespace views of the same key.
+     */
+    namespace(ns) {
+        return new CacheManager(this.#driver, {
+            prefix: this.#prefix ? `${this.#prefix}:${ns}` : ns,
+            ttl: this.#defaultTtl,
+            grace: this.#defaultGrace,
+            timeout: this.#defaultTimeout,
+            hardTimeout: this.#defaultHardTimeout,
+            lockTimeout: this.#defaultLockTimeout,
+            name: this.#name,
+            emitter: this.#emitter,
+        }, this.#shared);
+    }
+    // ---- getOrSet --------------------------------------------------------
+    #normalizeGetOrSet(a, b, c) {
+        if (typeof a === "string") {
+            if (typeof c !== "function") {
+                throw new TypeError("Echo: getOrSet(key, ttl, factory) requires a factory function");
+            }
+            return {
+                key: a,
+                factory: c,
+                ttlSeconds: resolveTtlSeconds(b, this.#defaultTtl),
+                graceSeconds: resolveTtlSeconds(this.#defaultGrace, 0),
+                timeoutMs: resolveMs(this.#defaultTimeout),
+                hardTimeoutMs: resolveMs(this.#defaultHardTimeout),
+                lockTimeoutMs: resolveMs(this.#defaultLockTimeout),
+                tags: [],
+            };
         }
-        throw new Error("Echo: the configured driver does not support tag-based invalidation");
+        return {
+            key: a.key,
+            factory: a.factory,
+            ttlSeconds: resolveTtlSeconds(a.ttl, this.#defaultTtl),
+            graceSeconds: resolveTtlSeconds(a.grace ?? this.#defaultGrace, 0),
+            timeoutMs: resolveMs(a.timeout ?? this.#defaultTimeout),
+            hardTimeoutMs: resolveMs(a.hardTimeout ?? this.#defaultHardTimeout),
+            lockTimeoutMs: resolveMs(a.lockTimeout ?? this.#defaultLockTimeout),
+            tags: a.tags ?? [],
+            onFactoryError: a.onFactoryError,
+        };
     }
-    /** In-flight promises for stampede prevention. Each factory is typed per-call; the map is keyed by prefixed cache key. */
-    inflight = new Map();
     /**
-     * Fetch from cache, or compute via `factory` and store (AdonisJS
-     * `cache.getOrSet`). Single-flight: concurrent misses share one factory call.
-     * (Positional `(key, ttl, factory)` is a deliberate simplification over
-     * Adonis's object form — echo keeps a leaner cache surface.)
+     * Run (or join) the single-flight factory for `prefixed`. Resolves to the
+     * fresh value on success; on failure it calls `onFactoryError` and either
+     * resolves to `staleValue` (when a stale fallback exists) or rejects.
      */
-    async getOrSet(key, ttl, factory) {
-        const prefixed = this.prefixKey(key);
-        const existing = this.inflight.get(prefixed);
-        if (existing)
-            return existing.then((v) => v);
-        const cached = await this.get(key);
-        if (cached !== null)
-            return cached;
-        const existingAfterAwait = this.inflight.get(prefixed);
-        if (existingAfterAwait)
-            return existingAfterAwait.then((v) => v);
-        const promise = factory()
-            .then(async (value) => {
-            await this.set(key, value, ttl);
-            this.inflight.delete(prefixed);
-            return value;
-        })
-            .catch((err) => {
-            this.inflight.delete(prefixed);
-            throw err;
-        });
-        this.inflight.set(prefixed, promise);
-        return promise;
+    #invokeFactory(prefixed, o, hasStale, staleValue) {
+        const run = async () => {
+            try {
+                const value = await o.factory();
+                await this.#writeValue(prefixed, value, o.ttlSeconds, o.graceSeconds, o.tags);
+                this.#emit("cache:written", {
+                    key: o.key,
+                    value,
+                    store: this.#name,
+                });
+                return value;
+            }
+            catch (error) {
+                o.onFactoryError?.(new FactoryError(o.key, error, hasStale));
+                if (hasStale && staleValue !== undefined)
+                    return staleValue;
+                throw error;
+            }
+            finally {
+                this.#shared.inflight.delete(prefixed);
+            }
+        };
+        return run();
+    }
+    async getOrSet(a, b, c) {
+        const o = this.#normalizeGetOrSet(a, b, c);
+        const prefixed = this.#prefixKey(o.key);
+        const entry = await this.#readEntry(prefixed);
+        if (entry && !entry.stale) {
+            this.#emit("cache:hit", {
+                key: o.key,
+                value: entry.value,
+                store: this.#name,
+                graced: false,
+            });
+            return entry.value;
+        }
+        const hasStale = entry !== null && entry.stale && o.graceSeconds > 0;
+        const staleValue = hasStale ? entry.value : undefined;
+        let record = this.#shared.inflight.get(prefixed);
+        if (!record) {
+            record = {
+                promise: this.#invokeFactory(prefixed, o, hasStale, staleValue),
+            };
+            this.#shared.inflight.set(prefixed, record);
+        }
+        // Single-flight join point: the shared map is heterogeneous (many T), so
+        // this generic re-assertion is unavoidable (mirrors echo <=0.1.5).
+        const factoryPromise = record.promise;
+        if (hasStale && staleValue !== undefined) {
+            // Stale-while-revalidate: serve stale up to the soft timeout (default 0
+            // = serve immediately), let the factory refresh in the background.
+            const softMs = o.timeoutMs ?? 0;
+            const waitMs = o.lockTimeoutMs !== undefined
+                ? Math.min(softMs, o.lockTimeoutMs)
+                : softMs;
+            const result = await withTimeout(factoryPromise, waitMs);
+            if (result === TIMEOUT) {
+                this.#emit("cache:hit", {
+                    key: o.key,
+                    value: staleValue,
+                    store: this.#name,
+                    graced: true,
+                });
+                return staleValue;
+            }
+            return result;
+        }
+        if (o.hardTimeoutMs !== undefined) {
+            const result = await withTimeout(factoryPromise, o.hardTimeoutMs);
+            if (result === TIMEOUT) {
+                throw new TimeoutError(o.key, o.hardTimeoutMs);
+            }
+            return result;
+        }
+        return factoryPromise;
+    }
+    /** Like {@link getOrSet} but the stored value never expires (bento `getOrSetForever`). */
+    getOrSetForever(options) {
+        return this.getOrSet({ ...options, ttl: null });
     }
 }
 //# sourceMappingURL=CacheManager.js.map

package/dist/CacheManager.js.map

@@ -1 +1 @@
-{"version":3,"file":"CacheManager.js","sourceRoot":"","sources":["../src/CacheManager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"CacheManager.js","sourceRoot":"","sources":["../src/CacheManager.ts"],"names":[],"mappings":"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"}