@c9up/echo 0.1.4 → 0.1.6

package/dist/drivers/RedisDriver.js

@@ -1,11 +1,23 @@
 /**
- * Redis cache driver — production-grade cache with TTL and tags.
+ * Redis cache driver — production-grade cache with TTL, grace
+ * (stale-while-revalidate) and tags. Suitable as the L2 tier of
+ * {@link TieredDriver}.
  *
  * Requires a Redis client instance implementing the minimal interface below.
  * Compatible with ioredis and redis (node-redis) clients.
  *
- * @implements MISS-10
+ * STORAGE FORMAT (breaking vs echo <=0.1.5): values are stored as a JSON
+ * envelope `{ "v": <value>, "e": <logicalExpiryEpochMs> }`. The physical Redis
+ * TTL (`EX`) covers `ttl + grace` so a logically-expired value survives for the
+ * grace window; `e` records the logical expiry so reads can flag it stale.
  */
+function isEnvelope(x) {
+    return (typeof x === "object" &&
+        x !== null &&
+        "v" in x &&
+        "e" in x &&
+        typeof Reflect.get(x, "e") === "number");
+}
 export class RedisDriver {
     #client;
     #prefix;
@@ -17,12 +29,9 @@ export class RedisDriver {
         return `${this.#prefix}${k}`;
     }
     /**
-     * Reverse-index for per-key tag membership. Lets `setWithTags()` clean
-     * stale memberships when a key is retagged, and `delete()` drop the key
-     * from every tag-set it belongs to. Without this, a re-tag like
-     * `setWithTags('article:42', v, ['homepage'])` (was `['news']`) leaves
-     * `tag:news` pointing at `article:42`, and a later `flushTags(['news'])`
-     * silently deletes the value.
+     * Reverse-index for per-key tag membership. Lets tag writes clean stale
+     * memberships on retag, and `delete()` drop the key from every tag-set it
+     * belongs to.
      */
     #metaKey(k) {
         return `${this.#prefix}meta:tags:${k}`;
@@ -42,19 +51,79 @@ export class RedisDriver {
         return count > 0;
     }
     async get(key) {
+        const entry = await this.getEntry(key);
+        if (entry === null || entry.stale)
+            return null;
+        return entry.value;
+    }
+    async getEntry(key) {
         const raw = await this.#client.get(this.#key(key));
         if (raw === null)
             return null;
-        return JSON.parse(raw);
+        const parsed = JSON.parse(raw);
+        if (!isEnvelope(parsed))
+            return null;
+        const stale = parsed.e > 0 && parsed.e < Date.now();
+        // Deserialize boundary: the on-the-wire value is genuinely `unknown`; the
+        // caller's generic `T` is the assertion. This is the single unavoidable
+        // cast site (mirrors echo <=0.1.5 `JSON.parse(raw) as T`).
+        const value = parsed.v;
+        return { value, stale, expiresAt: parsed.e };
     }
-    async set(key, value, ttlSeconds) {
-        const serialized = JSON.stringify(value);
-        if (ttlSeconds && ttlSeconds > 0) {
-            await this.#client.set(this.#key(key), serialized, "EX", ttlSeconds);
+    /** Write the value envelope with a physical (grace-inclusive) TTL in seconds. */
+    async #writeEnvelope(fullKey, value, logicalTtlSeconds, physicalTtlSeconds, logicalExpiresAtOverride) {
+        // An absolute override (e.g. `expire()` marking stale-now) wins over the
+        // ttl-derived logical expiry; a past value flags the entry stale on read.
+        const expiresAt = logicalExpiresAtOverride !== undefined
+            ? logicalExpiresAtOverride
+            : logicalTtlSeconds > 0
+                ? Date.now() + logicalTtlSeconds * 1000
+                : 0;
+        const envelope = { v: value, e: expiresAt };
+        const serialized = JSON.stringify(envelope);
+        if (physicalTtlSeconds > 0) {
+            await this.#client.set(fullKey, serialized, "EX", physicalTtlSeconds);
         }
         else {
-            await this.#client.set(this.#key(key), serialized);
+            await this.#client.set(fullKey, serialized);
+        }
+    }
+    /** Drop a key from its previous tag memberships (reconcile before re-tagging). */
+    async #dropTags(fullKey, metaKey) {
+        const prevTags = await this.#client.smembers(metaKey);
+        for (const tag of prevTags) {
+            await this.#client.srem(`${this.#prefix}tag:${tag}`, fullKey);
         }
+        if (prevTags.length > 0)
+            await this.#client.del(metaKey);
+        return prevTags;
+    }
+    async set(key, value, ttlSeconds) {
+        const fullKey = this.#key(key);
+        await this.#dropTags(fullKey, this.#metaKey(key));
+        const ttl = ttlSeconds && ttlSeconds > 0 ? ttlSeconds : 0;
+        await this.#writeEnvelope(fullKey, value, ttl, ttl);
+    }
+    async setEntry(key, value, options) {
+        const fullKey = this.#key(key);
+        const metaKey = this.#metaKey(key);
+        const ttl = options.ttlSeconds && options.ttlSeconds > 0 ? options.ttlSeconds : 0;
+        const grace = options.graceSeconds && options.graceSeconds > 0
+            ? options.graceSeconds
+            : 0;
+        // With an absolute logical expiry (e.g. `expire()` marking stale-now), the
+        // ttl no longer drives physical retention — keep the value for the grace
+        // window measured from now so a stale-but-graced read still finds it.
+        const override = options.expiresAt;
+        const physical = override !== undefined ? grace : ttl > 0 ? ttl + grace : 0;
+        const tags = options.tags ?? [];
+        if (tags.length === 0) {
+            await this.#dropTags(fullKey, metaKey);
+            await this.#writeEnvelope(fullKey, value, ttl, physical, override);
+            return;
+        }
+        await this.#writeEnvelope(fullKey, value, ttl, physical, override);
+        await this.#applyTags(key, tags, physical);
     }
     async flush() {
         const scan = this.#client.scan;
@@ -73,19 +142,13 @@ export class RedisDriver {
         }
     }
     async has(key) {
-        const exists = await this.#client.exists(this.#key(key));
-        return exists > 0;
+        return (await this.get(key)) !== null;
     }
     /**
-     * Set a value with tag memberships for group invalidation.
-     *
-     * Re-tagging an existing key (e.g. `['news']` → `['homepage']`) cleans
-     * the stale memberships via the per-key reverse-index — without this,
-     * a later `flushTags(['news'])` would silently wipe the still-current
-     * value because the abandoned `tag:news` set kept pointing at it.
+     * Reconcile the tag reverse-index for `key` to exactly `tags`, and extend
+     * tag-set / meta TTLs to the physical (grace-inclusive) retention.
      */
-    async setWithTags(key, value, tags, ttlSeconds) {
-        await this.set(key, value, ttlSeconds);
+    async #applyTags(key, tags, physicalTtlSeconds) {
         const fullKey = this.#key(key);
         const metaKey = this.#metaKey(key);
         const oldTags = await this.#client.smembers(metaKey);
@@ -93,54 +156,47 @@ export class RedisDriver {
         const oldTagSet = new Set(oldTags);
         const removedTags = oldTags.filter((t) => !newTagSet.has(t));
         const addedTags = tags.filter((t) => !oldTagSet.has(t));
-        // Drop the key from tag-sets it no longer belongs to.
         for (const tag of removedTags) {
-            const tagKey = `${this.#prefix}tag:${tag}`;
-            await this.#client.srem(tagKey, fullKey);
+            await this.#client.srem(`${this.#prefix}tag:${tag}`, fullKey);
         }
-        // Add to new tag-sets; re-touch TTLs on every declared tag so existing
-        // memberships extend correctly on re-set.
         for (const tag of tags) {
             const tagKey = `${this.#prefix}tag:${tag}`;
             if (addedTags.includes(tag)) {
                 await this.#client.sadd(tagKey, fullKey);
             }
-            if (ttlSeconds && ttlSeconds > 0) {
+            if (physicalTtlSeconds > 0) {
                 const currentTtl = await this.#client.ttl(tagKey);
-                if (currentTtl < 0 || ttlSeconds > currentTtl) {
-                    await this.#client.expire(tagKey, ttlSeconds);
+                if (currentTtl < 0 || physicalTtlSeconds > currentTtl) {
+                    await this.#client.expire(tagKey, physicalTtlSeconds);
                 }
             }
         }
-        // Refresh the reverse-index to match the new tag set. Drop+re-add is
-        // simpler than diff-mutating the set and matches `tags` exactly even
-        // in the empty-array case.
         if (oldTags.length > 0) {
             await this.#client.del(metaKey);
         }
         if (tags.length > 0) {
             await this.#client.sadd(metaKey, ...tags);
-            if (ttlSeconds && ttlSeconds > 0) {
-                await this.#client.expire(metaKey, ttlSeconds);
+            if (physicalTtlSeconds > 0) {
+                await this.#client.expire(metaKey, physicalTtlSeconds);
             }
         }
     }
+    /** Set a value with tag memberships for group invalidation (no grace). */
+    async setWithTags(key, value, tags, ttlSeconds) {
+        const ttl = ttlSeconds && ttlSeconds > 0 ? ttlSeconds : 0;
+        await this.#writeEnvelope(this.#key(key), value, ttl, ttl);
+        await this.#applyTags(key, tags, ttl);
+    }
     /**
-     * Flush all entries tagged with any of the given tags. Cleans up the
-     * per-key reverse-index AND cross-tag memberships so a multi-tag key
-     * (e.g. `['news', 'homepage']`) flushed via `news` is also removed from
-     * the `homepage` tag-set — otherwise the `homepage` set ends up with a
-     * dangling reference to a now-deleted value.
+     * Invalidate all entries tagged with any of the given tags. Cleans the
+     * per-key reverse-index AND cross-tag memberships so a multi-tag key flushed
+     * via one tag is also removed from the others.
      */
-    async flushTags(tags) {
+    async deleteByTag(tags) {
         for (const tag of tags) {
             const tagKey = `${this.#prefix}tag:${tag}`;
             const members = await this.#client.smembers(tagKey);
             for (const fullKey of members) {
-                // Read every OTHER tag this key claims (via the reverse-index)
-                // and SREM the key from each. The reverse-index key derives
-                // from the unprefixed user key — recover it by stripping the
-                // prefix.
                 const userKey = fullKey.startsWith(this.#prefix)
                     ? fullKey.slice(this.#prefix.length)
                     : fullKey;
@@ -162,5 +218,9 @@ export class RedisDriver {
             await this.#client.del(tagKey);
         }
     }
+    /** @deprecated alias of {@link deleteByTag}. */
+    async flushTags(tags) {
+        return this.deleteByTag(tags);
+    }
 }
 //# sourceMappingURL=RedisDriver.js.map

package/dist/drivers/RedisDriver.js.map

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

package/dist/drivers/TieredDriver.d.ts

@@ -0,0 +1,41 @@
+/**
+ * TieredDriver — two-tier cache composing an L1 (in-process, e.g.
+ * {@link MemoryDriver}) and an L2 (distributed, e.g. {@link RedisDriver}).
+ *
+ * Reads go L1 → L2 → miss, promoting an L2 hit back into L1. Writes are
+ * write-through to both tiers. An optional {@link CacheBus} broadcasts
+ * invalidations so peer instances drop their (now stale) L1 copies — the L2 is
+ * shared, so only L1 needs cross-instance invalidation.
+ */
+import type { CacheDriver, CacheEntry, DriverSetOptions, TaggableDriver } from "../types.js";
+/** A cross-instance invalidation message. */
+export interface BusMessage {
+    type: "delete" | "clear";
+    keys: string[];
+}
+/** Duck-typed pub/sub bus for cross-instance L1 invalidation (e.g. Redis pub/sub). */
+export interface CacheBus {
+    publish(message: BusMessage): void | Promise<void>;
+    subscribe(handler: (message: BusMessage) => void): void;
+}
+export interface TieredDriverOptions {
+    l1: CacheDriver;
+    l2: CacheDriver;
+    bus?: CacheBus;
+}
+export declare class TieredDriver implements TaggableDriver {
+    #private;
+    constructor(options: TieredDriverOptions);
+    getEntry<T = unknown>(key: string): Promise<CacheEntry<T> | null>;
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    setEntry(key: string, value: unknown, options: DriverSetOptions): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    flush(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    setWithTags(key: string, value: unknown, tags: string[], ttlSeconds?: number): Promise<void>;
+    deleteByTag(tags: string[]): Promise<void>;
+    /** @deprecated alias of {@link deleteByTag}. */
+    flushTags(tags: string[]): Promise<void>;
+}
+//# sourceMappingURL=TieredDriver.d.ts.map

package/dist/drivers/TieredDriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TieredDriver.d.ts","sourceRoot":"","sources":["../../src/drivers/TieredDriver.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACX,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,cAAc,EACd,MAAM,aAAa,CAAC;AAErB,6CAA6C;AAC7C,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC;IACzB,IAAI,EAAE,MAAM,EAAE,CAAC;CACf;AAED,sFAAsF;AACtF,MAAM,WAAW,QAAQ;IACxB,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,SAAS,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI,CAAC;CACxD;AAED,MAAM,WAAW,mBAAmB;IACnC,EAAE,EAAE,WAAW,CAAC;IAChB,EAAE,EAAE,WAAW,CAAC;IAChB,GAAG,CAAC,EAAE,QAAQ,CAAC;CACf;AAqCD,qBAAa,YAAa,YAAW,cAAc;;gBAKtC,OAAO,EAAE,mBAAmB;IAclC,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IA+BjE,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAMhD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE,QAAQ,CACb,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,gBAAgB,GACvB,OAAO,CAAC,IAAI,CAAC;IAMV,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIlC,WAAW,CAChB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EAAE,EACd,UAAU,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC;IAIV,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAehD,gDAAgD;IAC1C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAG9C"}

package/dist/drivers/TieredDriver.js

@@ -0,0 +1,132 @@
+/**
+ * TieredDriver — two-tier cache composing an L1 (in-process, e.g.
+ * {@link MemoryDriver}) and an L2 (distributed, e.g. {@link RedisDriver}).
+ *
+ * Reads go L1 → L2 → miss, promoting an L2 hit back into L1. Writes are
+ * write-through to both tiers. An optional {@link CacheBus} broadcasts
+ * invalidations so peer instances drop their (now stale) L1 copies — the L2 is
+ * shared, so only L1 needs cross-instance invalidation.
+ */
+function isTaggable(driver) {
+    const candidate = driver;
+    return (typeof candidate.setWithTags === "function" &&
+        (typeof candidate.deleteByTag === "function" ||
+            typeof candidate.flushTags === "function"));
+}
+async function readEntry(driver, key) {
+    if (driver.getEntry)
+        return driver.getEntry(key);
+    const value = await driver.get(key);
+    return value === null ? null : { value, stale: false };
+}
+async function writeEntry(driver, key, value, options) {
+    if (driver.setEntry) {
+        await driver.setEntry(key, value, options);
+        return;
+    }
+    if (options.tags && options.tags.length > 0 && isTaggable(driver)) {
+        await driver.setWithTags(key, value, options.tags, options.ttlSeconds);
+        return;
+    }
+    await driver.set(key, value, options.ttlSeconds);
+}
+export class TieredDriver {
+    #l1;
+    #l2;
+    #bus;
+    constructor(options) {
+        this.#l1 = options.l1;
+        this.#l2 = options.l2;
+        this.#bus = options.bus;
+        this.#bus?.subscribe((message) => {
+            // Peer invalidation: only the local L1 needs clearing (L2 is shared).
+            if (message.type === "clear") {
+                void this.#l1.flush();
+                return;
+            }
+            for (const key of message.keys)
+                void this.#l1.delete(key);
+        });
+    }
+    async getEntry(key) {
+        const l1 = await readEntry(this.#l1, key);
+        if (l1 && !l1.stale)
+            return l1;
+        const l2 = await readEntry(this.#l2, key);
+        if (l2 && !l2.stale) {
+            // Promote a fresh L2 hit into L1 — preserving the remaining logical TTL
+            // so L1 cannot outlive L2 (a promotion with no TTL left an immortal L1
+            // entry that kept serving a value the L2 had already expired).
+            if (l2.expiresAt === undefined) {
+                // Driver doesn't expose expiry — promoting with no TTL risks an
+                // immortal L1 copy; skip promotion rather than cache it forever.
+                return l2;
+            }
+            const opts = {};
+            if (l2.expiresAt > 0) {
+                const remainingSeconds = (l2.expiresAt - Date.now()) / 1000;
+                // Raced past expiry between the stale check and now — don't promote
+                // a value that is already dead.
+                if (remainingSeconds <= 0)
+                    return l2;
+                opts.ttlSeconds = remainingSeconds;
+            }
+            // expiresAt === 0 → the L2 entry genuinely never expires → promote as-is.
+            await writeEntry(this.#l1, key, l2.value, opts);
+            return l2;
+        }
+        if (l2)
+            return l2; // stale L2 (grace)
+        if (l1)
+            return l1; // stale L1 (grace)
+        return null;
+    }
+    async get(key) {
+        const entry = await this.getEntry(key);
+        if (entry === null || entry.stale)
+            return null;
+        return entry.value;
+    }
+    async set(key, value, ttlSeconds) {
+        await this.setEntry(key, value, { ttlSeconds });
+    }
+    async setEntry(key, value, options) {
+        await writeEntry(this.#l1, key, value, options);
+        await writeEntry(this.#l2, key, value, options);
+        await this.#bus?.publish({ type: "delete", keys: [key] });
+    }
+    async delete(key) {
+        const l1 = await this.#l1.delete(key);
+        const l2 = await this.#l2.delete(key);
+        await this.#bus?.publish({ type: "delete", keys: [key] });
+        return l1 || l2;
+    }
+    async flush() {
+        await this.#l1.flush();
+        await this.#l2.flush();
+        await this.#bus?.publish({ type: "clear", keys: [] });
+    }
+    async has(key) {
+        return (await this.get(key)) !== null;
+    }
+    async setWithTags(key, value, tags, ttlSeconds) {
+        await this.setEntry(key, value, { ttlSeconds, tags });
+    }
+    async deleteByTag(tags) {
+        const l1 = this.#l1;
+        const l2 = this.#l2;
+        if (!isTaggable(l1) || !isTaggable(l2)) {
+            throw new Error("Echo: TieredDriver.deleteByTag requires both tiers to be taggable");
+        }
+        await l1.deleteByTag(tags);
+        await l2.deleteByTag(tags);
+        // Peers can't map tags → keys locally; broadcast a clear so their L1 drops
+        // any tagged copies (conservative but correct).
+        await this.#bus?.publish({ type: "clear", keys: [] });
+    }
+    /** @deprecated alias of {@link deleteByTag}. */
+    async flushTags(tags) {
+        return this.deleteByTag(tags);
+    }
+}
+//# sourceMappingURL=TieredDriver.js.map

package/dist/drivers/TieredDriver.js.map

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

package/dist/duration.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Duration parsing — bentocache `Duration` parity, adapted to echo's
+ * seconds-native driver layer.
+ *
+ * DIVERGENCE (named): bentocache treats a bare `number` as **milliseconds**.
+ * Echo's drivers, positional API (`set(key, value, ttlSeconds)`) and the
+ * kitchen-sink app are all **seconds-native**, so a bare `number` here means
+ * **seconds**. Keeping one unit across the positional and object forms avoids
+ * a dual-unit footgun (cf. DNR `helpers_no_magic_layer`). String durations use
+ * the same human syntax as bento (`'5m'`, `'300s'`, `'2h'`, `'500ms'`).
+ */
+/**
+ * A cache duration:
+ * - `number` — seconds (echo-native; see divergence note above)
+ * - `string` — human duration (`'5m'`, `'2h'`, `'1d'`, `'500ms'`, …)
+ * - `null`   — never expires
+ */
+export type Duration = number | string | null;
+/**
+ * Parse a human duration string (`'5m'`, `'300s'`, `'500ms'`) into seconds.
+ * A unit-less numeric string is interpreted as seconds.
+ */
+export declare function parseDuration(value: string): number;
+/**
+ * Resolve a {@link Duration} to a TTL in **seconds**.
+ *
+ * @returns the TTL in seconds; `0` means "never expires" (either an explicit
+ *   `null`, or a non-positive value, matching echo's driver convention where
+ *   `ttlSeconds <= 0` is treated as immortal).
+ */
+export declare function resolveTtlSeconds(ttl: Duration | undefined, defaultSeconds: number): number;
+//# sourceMappingURL=duration.d.ts.map

package/dist/duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.d.ts","sourceRoot":"","sources":["../src/duration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAiC9C;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAanD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAChC,GAAG,EAAE,QAAQ,GAAG,SAAS,EACzB,cAAc,EAAE,MAAM,GACpB,MAAM,CAKR"}

package/dist/duration.js

@@ -0,0 +1,75 @@
+/**
+ * Duration parsing — bentocache `Duration` parity, adapted to echo's
+ * seconds-native driver layer.
+ *
+ * DIVERGENCE (named): bentocache treats a bare `number` as **milliseconds**.
+ * Echo's drivers, positional API (`set(key, value, ttlSeconds)`) and the
+ * kitchen-sink app are all **seconds-native**, so a bare `number` here means
+ * **seconds**. Keeping one unit across the positional and object forms avoids
+ * a dual-unit footgun (cf. DNR `helpers_no_magic_layer`). String durations use
+ * the same human syntax as bento (`'5m'`, `'300s'`, `'2h'`, `'500ms'`).
+ */
+const UNIT_SECONDS = {
+    ms: 1 / 1000,
+    msec: 1 / 1000,
+    msecs: 1 / 1000,
+    millisecond: 1 / 1000,
+    milliseconds: 1 / 1000,
+    s: 1,
+    sec: 1,
+    secs: 1,
+    second: 1,
+    seconds: 1,
+    m: 60,
+    min: 60,
+    mins: 60,
+    minute: 60,
+    minutes: 60,
+    h: 3600,
+    hr: 3600,
+    hrs: 3600,
+    hour: 3600,
+    hours: 3600,
+    d: 86_400,
+    day: 86_400,
+    days: 86_400,
+    w: 604_800,
+    week: 604_800,
+    weeks: 604_800,
+};
+const DURATION_RE = /^\s*(-?\d+(?:\.\d+)?)\s*([a-z]+)?\s*$/i;
+/**
+ * Parse a human duration string (`'5m'`, `'300s'`, `'500ms'`) into seconds.
+ * A unit-less numeric string is interpreted as seconds.
+ */
+export function parseDuration(value) {
+    const match = DURATION_RE.exec(value);
+    if (!match) {
+        throw new TypeError(`Echo: invalid duration string "${value}"`);
+    }
+    const amount = Number(match[1]);
+    const unit = match[2]?.toLowerCase();
+    if (unit === undefined)
+        return amount;
+    const factor = UNIT_SECONDS[unit];
+    if (factor === undefined) {
+        throw new TypeError(`Echo: unknown duration unit "${unit}" in "${value}"`);
+    }
+    return amount * factor;
+}
+/**
+ * Resolve a {@link Duration} to a TTL in **seconds**.
+ *
+ * @returns the TTL in seconds; `0` means "never expires" (either an explicit
+ *   `null`, or a non-positive value, matching echo's driver convention where
+ *   `ttlSeconds <= 0` is treated as immortal).
+ */
+export function resolveTtlSeconds(ttl, defaultSeconds) {
+    if (ttl === null)
+        return 0;
+    if (ttl === undefined)
+        return defaultSeconds;
+    const seconds = typeof ttl === "number" ? ttl : parseDuration(ttl);
+    return seconds > 0 ? seconds : 0;
+}
+//# sourceMappingURL=duration.js.map

package/dist/duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.js","sourceRoot":"","sources":["../src/duration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAUH,MAAM,YAAY,GAA2B;IAC5C,EAAE,EAAE,CAAC,GAAG,IAAI;IACZ,IAAI,EAAE,CAAC,GAAG,IAAI;IACd,KAAK,EAAE,CAAC,GAAG,IAAI;IACf,WAAW,EAAE,CAAC,GAAG,IAAI;IACrB,YAAY,EAAE,CAAC,GAAG,IAAI;IACtB,CAAC,EAAE,CAAC;IACJ,GAAG,EAAE,CAAC;IACN,IAAI,EAAE,CAAC;IACP,MAAM,EAAE,CAAC;IACT,OAAO,EAAE,CAAC;IACV,CAAC,EAAE,EAAE;IACL,GAAG,EAAE,EAAE;IACP,IAAI,EAAE,EAAE;IACR,MAAM,EAAE,EAAE;IACV,OAAO,EAAE,EAAE;IACX,CAAC,EAAE,IAAI;IACP,EAAE,EAAE,IAAI;IACR,GAAG,EAAE,IAAI;IACT,IAAI,EAAE,IAAI;IACV,KAAK,EAAE,IAAI;IACX,CAAC,EAAE,MAAM;IACT,GAAG,EAAE,MAAM;IACX,IAAI,EAAE,MAAM;IACZ,CAAC,EAAE,OAAO;IACV,IAAI,EAAE,OAAO;IACb,KAAK,EAAE,OAAO;CACd,CAAC;AAEF,MAAM,WAAW,GAAG,wCAAwC,CAAC;AAE7D;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IAC1C,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtC,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,MAAM,IAAI,SAAS,CAAC,kCAAkC,KAAK,GAAG,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAChC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;IACrC,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACtC,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,IAAI,SAAS,CAAC,gCAAgC,IAAI,SAAS,KAAK,GAAG,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,MAAM,GAAG,MAAM,CAAC;AACxB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAChC,GAAyB,EACzB,cAAsB;IAEtB,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,CAAC,CAAC;IAC3B,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,cAAc,CAAC;IAC7C,MAAM,OAAO,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IACnE,OAAO,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AAClC,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Echo cache errors — bentocache parity (`errors.ts`).
+ */
+/** Raised when a factory exceeds its configured `hardTimeout`. */
+export declare class TimeoutError extends Error {
+    constructor(key: string, timeoutMs: number);
+}
+/**
+ * Wraps an error thrown by a `getOrSet` factory. Passed to `onFactoryError`
+ * so callers can observe both foreground and background factory failures.
+ */
+export declare class FactoryError extends Error {
+    /** The cache key the factory was computing. */
+    readonly key: string;
+    /** The original error thrown by the factory. */
+    readonly cause: unknown;
+    /** `true` when the factory was running in the background (soft timeout / refresh). */
+    readonly isBackground: boolean;
+    constructor(key: string, cause: unknown, isBackground: boolean);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,kEAAkE;AAClE,qBAAa,YAAa,SAAQ,KAAK;gBAC1B,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAI1C;AAED;;;GAGG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACtC,+CAA+C;IAC/C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,SAAkB,KAAK,EAAE,OAAO,CAAC;IACjC,sFAAsF;IACtF,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;gBAEnB,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO;CAQ9D"}

package/dist/errors.js

@@ -0,0 +1,31 @@
+/**
+ * Echo cache errors — bentocache parity (`errors.ts`).
+ */
+/** Raised when a factory exceeds its configured `hardTimeout`. */
+export class TimeoutError extends Error {
+    constructor(key, timeoutMs) {
+        super(`Echo: factory for "${key}" timed out after ${timeoutMs}ms`);
+        this.name = "TimeoutError";
+    }
+}
+/**
+ * Wraps an error thrown by a `getOrSet` factory. Passed to `onFactoryError`
+ * so callers can observe both foreground and background factory failures.
+ */
+export class FactoryError extends Error {
+    /** The cache key the factory was computing. */
+    key;
+    /** The original error thrown by the factory. */
+    cause;
+    /** `true` when the factory was running in the background (soft timeout / refresh). */
+    isBackground;
+    constructor(key, cause, isBackground) {
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        super(`Echo: factory for "${key}" failed: ${reason}`);
+        this.name = "FactoryError";
+        this.key = key;
+        this.cause = cause;
+        this.isBackground = isBackground;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,kEAAkE;AAClE,MAAM,OAAO,YAAa,SAAQ,KAAK;IACtC,YAAY,GAAW,EAAE,SAAiB;QACzC,KAAK,CAAC,sBAAsB,GAAG,qBAAqB,SAAS,IAAI,CAAC,CAAC;QACnE,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC5B,CAAC;CACD;AAED;;;GAGG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACtC,+CAA+C;IACtC,GAAG,CAAS;IACrB,gDAAgD;IAC9B,KAAK,CAAU;IACjC,sFAAsF;IAC7E,YAAY,CAAU;IAE/B,YAAY,GAAW,EAAE,KAAc,EAAE,YAAqB;QAC7D,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,KAAK,CAAC,sBAAsB,GAAG,aAAa,MAAM,EAAE,CAAC,CAAC;QACtD,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IAClC,CAAC;CACD"}