@nage-api/cache 1.0.0-beta.2

package/dist/cache.service.js

@@ -0,0 +1,147 @@
+"use strict";
+/**
+ * The typed cache application code uses (PLAN.md §8).
+ *
+ * Three things it adds over a bare store:
+ *
+ * **Namespacing.** Every key is prefixed, so `cache.namespace('product')` can
+ * be dropped wholesale without knowing which keys it wrote. The legacy
+ * framework shared one flat keyspace, which meant invalidation was either
+ * surgical-and-wrong or a full flush.
+ *
+ * **Single-flight.** Concurrent `wrap` calls for the same key run the loader
+ * once. Without it, a popular key expiring under load starts one identical
+ * database query per in-flight request — the cache stampede that turns a cache
+ * miss into an outage.
+ *
+ * **Typing.** `wrap<T>` returns `T`, not `any`. A cache that hands back
+ * `unknown` pushes a cast to every call site, and those casts are where a
+ * schema change stops being a type error.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheService = void 0;
+exports.toMilliseconds = toMilliseconds;
+const core_1 = require("@nage-api/core");
+const NAMESPACE_SEPARATOR = ':';
+class CacheService {
+    #store;
+    #namespace;
+    #defaultTtlMs;
+    #clock;
+    #inFlight = new Map();
+    #hits = 0;
+    #misses = 0;
+    #coalesced = 0;
+    constructor(options) {
+        this.#store = options.store;
+        this.#namespace = options.namespace ?? '';
+        this.#defaultTtlMs = options.defaultTtlMs ?? 0;
+        this.#clock = options.clock ?? { now: () => Date.now() };
+    }
+    /** A view scoped to a sub-namespace, sharing the same store and counters. */
+    namespace(name) {
+        const scoped = new CacheService({
+            store: this.#store,
+            namespace: this.#key(name),
+            defaultTtlMs: this.#defaultTtlMs,
+            clock: this.#clock,
+        });
+        return scoped;
+    }
+    async get(key) {
+        const entry = await this.#store.get(this.#key(key));
+        if (entry === undefined) {
+            this.#misses += 1;
+            return undefined;
+        }
+        this.#hits += 1;
+        return entry.value;
+    }
+    async set(key, value, options = {}) {
+        await this.#store.set(this.#key(key), this.#entry(value, options));
+    }
+    async delete(key) {
+        await this.#store.delete(this.#key(key));
+    }
+    /** Drop everything this namespace wrote. */
+    async invalidateNamespace(name) {
+        const prefix = name === undefined ? this.#namespace : this.#key(name);
+        return this.#store.deletePrefix(prefix === '' ? '' : `${prefix}${NAMESPACE_SEPARATOR}`);
+    }
+    /** Drop every entry labelled with a tag, wherever it was written. */
+    async invalidateTag(tag) {
+        return this.#store.deleteTag(tag);
+    }
+    /**
+     * Read through the cache, loading on a miss.
+     *
+     * Concurrent calls for the same key share one loader invocation, so a key
+     * expiring under load costs one query rather than one per request.
+     */
+    async wrap(key, load, options = {}) {
+        const fullKey = this.#key(key);
+        if (options.refresh !== true) {
+            const entry = await this.#store.get(fullKey);
+            if (entry !== undefined) {
+                this.#hits += 1;
+                return entry.value;
+            }
+            this.#misses += 1;
+        }
+        const existing = this.#inFlight.get(fullKey);
+        if (existing !== undefined) {
+            this.#coalesced += 1;
+            return existing;
+        }
+        const pending = this.#load(fullKey, load, options);
+        this.#inFlight.set(fullKey, pending);
+        try {
+            return await pending;
+        }
+        finally {
+            // Cleared in `finally` so a rejected load does not poison the key: the
+            // next caller retries rather than inheriting the failure.
+            this.#inFlight.delete(fullKey);
+        }
+    }
+    get stats() {
+        return { hits: this.#hits, misses: this.#misses, promotions: 0, coalesced: this.#coalesced };
+    }
+    resetStats() {
+        this.#hits = 0;
+        this.#misses = 0;
+        this.#coalesced = 0;
+    }
+    async #load(fullKey, load, options) {
+        const value = await load();
+        // Cast to `unknown` first: `value` is an unconstrained type parameter, and
+        // TypeScript narrows the comparison away without it.
+        const empty = value === undefined || value === null;
+        if (!empty || options.cacheEmpty === true) {
+            await this.#store.set(fullKey, this.#entry(value, options));
+        }
+        return value;
+    }
+    #entry(value, options) {
+        const ttlMs = toMilliseconds(options.ttl) ?? this.#defaultTtlMs;
+        return {
+            value,
+            ...(ttlMs > 0 ? { expiresAt: this.#clock.now() + ttlMs } : {}),
+            ...(options.tags === undefined ? {} : { tags: options.tags }),
+        };
+    }
+    #key(key) {
+        return this.#namespace === '' ? key : `${this.#namespace}${NAMESPACE_SEPARATOR}${key}`;
+    }
+}
+exports.CacheService = CacheService;
+/** Accepts milliseconds or a duration string, so config and code agree. */
+function toMilliseconds(ttl) {
+    if (ttl === undefined)
+        return undefined;
+    if (typeof ttl === 'number')
+        return ttl;
+    const parsed = (0, core_1.parseDurationMs)(ttl);
+    return parsed > 0 ? parsed : undefined;
+}
+//# sourceMappingURL=cache.service.js.map

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `@nage-api/cache` — the typed two-tier cache (PLAN.md §8, §25 P1).
+ *
+ * A cache is an optimisation, so this package is built to fail soft: a broken
+ * remote tier degrades to a slower application rather than a broken one, and a
+ * value it cannot parse is a miss rather than an exception.
+ */
+export type * from '@nage-api/contracts';
+export { NageCacheModule, type NageCacheModuleOptions } from './cache.module.js';
+export { CacheService, toMilliseconds, type CacheServiceOptions, type CacheSetOptions, type CacheWrapOptions, } from './cache.service.js';
+export { MemoryCacheStore, type MemoryCacheStoreOptions } from './memory.store.js';
+export { TwoTierCacheStore, type TwoTierCacheStoreOptions } from './two-tier.store.js';
+export { RedisCacheStore, type RedisCacheStoreOptions, type RedisClientPort, } from './redis.store.js';
+export { NAGE_CACHE, NAGE_CACHE_STORE } from './tokens.js';
+export { systemClock, type CacheEntry, type CacheOutcome, type CacheStats, type CacheStore, type Clock, } from './ports.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * `@nage-api/cache` — the typed two-tier cache (PLAN.md §8, §25 P1).
+ *
+ * A cache is an optimisation, so this package is built to fail soft: a broken
+ * remote tier degrades to a slower application rather than a broken one, and a
+ * value it cannot parse is a miss rather than an exception.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemClock = exports.NAGE_CACHE_STORE = exports.NAGE_CACHE = exports.RedisCacheStore = exports.TwoTierCacheStore = exports.MemoryCacheStore = exports.toMilliseconds = exports.CacheService = exports.NageCacheModule = void 0;
+var cache_module_js_1 = require("./cache.module.js");
+Object.defineProperty(exports, "NageCacheModule", { enumerable: true, get: function () { return cache_module_js_1.NageCacheModule; } });
+var cache_service_js_1 = require("./cache.service.js");
+Object.defineProperty(exports, "CacheService", { enumerable: true, get: function () { return cache_service_js_1.CacheService; } });
+Object.defineProperty(exports, "toMilliseconds", { enumerable: true, get: function () { return cache_service_js_1.toMilliseconds; } });
+var memory_store_js_1 = require("./memory.store.js");
+Object.defineProperty(exports, "MemoryCacheStore", { enumerable: true, get: function () { return memory_store_js_1.MemoryCacheStore; } });
+var two_tier_store_js_1 = require("./two-tier.store.js");
+Object.defineProperty(exports, "TwoTierCacheStore", { enumerable: true, get: function () { return two_tier_store_js_1.TwoTierCacheStore; } });
+var redis_store_js_1 = require("./redis.store.js");
+Object.defineProperty(exports, "RedisCacheStore", { enumerable: true, get: function () { return redis_store_js_1.RedisCacheStore; } });
+var tokens_js_1 = require("./tokens.js");
+Object.defineProperty(exports, "NAGE_CACHE", { enumerable: true, get: function () { return tokens_js_1.NAGE_CACHE; } });
+Object.defineProperty(exports, "NAGE_CACHE_STORE", { enumerable: true, get: function () { return tokens_js_1.NAGE_CACHE_STORE; } });
+var ports_js_1 = require("./ports.js");
+Object.defineProperty(exports, "systemClock", { enumerable: true, get: function () { return ports_js_1.systemClock; } });
+//# sourceMappingURL=index.js.map

package/dist/memory.store.d.ts

@@ -0,0 +1,44 @@
+/**
+ * In-process cache with a bounded size and lazy expiry.
+ *
+ * This is both the L1 of the two-tier arrangement and a complete cache in its
+ * own right for single-instance deployments. Two properties make it safe to
+ * leave running for months:
+ *
+ * **It is bounded.** An unbounded `Map` keyed by anything a request can
+ * influence is a memory leak with a slow fuse. Eviction is least-recently-used,
+ * which is what a cache wants and what a plain `Map` gives almost for free —
+ * `Map` preserves insertion order, so re-inserting on read moves an entry to
+ * the end and the first key is always the coldest.
+ *
+ * **It sweeps.** Expired entries are dropped on read, but a key that is written
+ * once and never read again would otherwise sit there forever, so a periodic
+ * sweep removes them. The timer is `unref`'d: a cache must not be the reason a
+ * process refuses to exit.
+ */
+import type { CacheEntry, CacheStore, Clock } from './ports.js';
+export interface MemoryCacheStoreOptions {
+    /** Entries kept before the least recently used one is evicted. */
+    readonly maxEntries?: number;
+    /** How often expired entries are swept. `0` disables the timer. */
+    readonly sweepIntervalMs?: number;
+    readonly clock?: Clock;
+}
+export declare class MemoryCacheStore implements CacheStore {
+    #private;
+    constructor(options?: MemoryCacheStoreOptions);
+    get<TValue>(key: string): Promise<CacheEntry<TValue> | undefined>;
+    set<TValue>(key: string, entry: CacheEntry<TValue>): Promise<void>;
+    delete(key: string): Promise<void>;
+    deletePrefix(prefix: string): Promise<number>;
+    deleteTag(tag: string): Promise<number>;
+    clear(): Promise<void>;
+    /** Drop expired entries. Called by the timer and directly by tests. */
+    sweep(): number;
+    /** Stop the sweeper. Wired to Nest's shutdown hooks by the module. */
+    stop(): void;
+    get size(): number;
+    /** Keys currently held, oldest first. Test and diagnostics only. */
+    get keys(): readonly string[];
+}
+//# sourceMappingURL=memory.store.d.ts.map

package/dist/memory.store.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * In-process cache with a bounded size and lazy expiry.
+ *
+ * This is both the L1 of the two-tier arrangement and a complete cache in its
+ * own right for single-instance deployments. Two properties make it safe to
+ * leave running for months:
+ *
+ * **It is bounded.** An unbounded `Map` keyed by anything a request can
+ * influence is a memory leak with a slow fuse. Eviction is least-recently-used,
+ * which is what a cache wants and what a plain `Map` gives almost for free —
+ * `Map` preserves insertion order, so re-inserting on read moves an entry to
+ * the end and the first key is always the coldest.
+ *
+ * **It sweeps.** Expired entries are dropped on read, but a key that is written
+ * once and never read again would otherwise sit there forever, so a periodic
+ * sweep removes them. The timer is `unref`'d: a cache must not be the reason a
+ * process refuses to exit.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryCacheStore = void 0;
+const DEFAULT_MAX_ENTRIES = 10_000;
+const DEFAULT_SWEEP_INTERVAL_MS = 60_000;
+class MemoryCacheStore {
+    #entries = new Map();
+    #maxEntries;
+    #clock;
+    #sweeper;
+    constructor(options = {}) {
+        this.#maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        this.#clock = options.clock ?? { now: () => Date.now() };
+        const interval = options.sweepIntervalMs ?? DEFAULT_SWEEP_INTERVAL_MS;
+        if (interval > 0) {
+            this.#sweeper = setInterval(() => this.sweep(), interval);
+            // A cache must never be the reason a process refuses to exit.
+            this.#sweeper.unref();
+        }
+    }
+    async get(key) {
+        await Promise.resolve();
+        const entry = this.#entries.get(key);
+        if (entry === undefined)
+            return undefined;
+        if (this.#expired(entry)) {
+            this.#entries.delete(key);
+            return undefined;
+        }
+        // Re-insert to mark it as most recently used.
+        this.#entries.delete(key);
+        this.#entries.set(key, entry);
+        return entry;
+    }
+    async set(key, entry) {
+        await Promise.resolve();
+        this.#entries.delete(key);
+        this.#entries.set(key, entry);
+        this.#evictIfFull();
+    }
+    async delete(key) {
+        await Promise.resolve();
+        this.#entries.delete(key);
+    }
+    async deletePrefix(prefix) {
+        await Promise.resolve();
+        let deleted = 0;
+        for (const key of [...this.#entries.keys()]) {
+            if (!key.startsWith(prefix))
+                continue;
+            this.#entries.delete(key);
+            deleted += 1;
+        }
+        return deleted;
+    }
+    async deleteTag(tag) {
+        await Promise.resolve();
+        let deleted = 0;
+        for (const [key, entry] of [...this.#entries]) {
+            if (entry.tags?.includes(tag) !== true)
+                continue;
+            this.#entries.delete(key);
+            deleted += 1;
+        }
+        return deleted;
+    }
+    async clear() {
+        await Promise.resolve();
+        this.#entries.clear();
+    }
+    /** Drop expired entries. Called by the timer and directly by tests. */
+    sweep() {
+        let removed = 0;
+        for (const [key, entry] of [...this.#entries]) {
+            if (!this.#expired(entry))
+                continue;
+            this.#entries.delete(key);
+            removed += 1;
+        }
+        return removed;
+    }
+    /** Stop the sweeper. Wired to Nest's shutdown hooks by the module. */
+    stop() {
+        if (this.#sweeper === undefined)
+            return;
+        clearInterval(this.#sweeper);
+        this.#sweeper = undefined;
+    }
+    get size() {
+        return this.#entries.size;
+    }
+    /** Keys currently held, oldest first. Test and diagnostics only. */
+    get keys() {
+        return [...this.#entries.keys()];
+    }
+    #expired(entry) {
+        return entry.expiresAt !== undefined && entry.expiresAt <= this.#clock.now();
+    }
+    #evictIfFull() {
+        while (this.#entries.size > this.#maxEntries) {
+            // Insertion order makes the first key the least recently used.
+            const oldest = this.#entries.keys().next();
+            if (oldest.done)
+                return;
+            this.#entries.delete(oldest.value);
+        }
+    }
+}
+exports.MemoryCacheStore = MemoryCacheStore;
+//# sourceMappingURL=memory.store.js.map

package/dist/ports.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The cache contract (PLAN.md §8, §25 P1).
+ *
+ * One port, two tiers. `CacheStore` is what a backend implements — memory,
+ * Redis, anything with get/set/delete — and `CacheService` is what application
+ * code uses. Keeping them apart is what lets the two-tier arrangement (a small
+ * in-process L1 in front of a shared L2) be a composition rather than a special
+ * case every caller has to know about.
+ */
+/** A stored entry plus the metadata needed to expire and invalidate it. */
+export interface CacheEntry<TValue> {
+    readonly value: TValue;
+    /** Epoch milliseconds; `undefined` means it never expires on its own. */
+    readonly expiresAt?: number;
+    /** Labels this entry can be invalidated by, e.g. `product:17`. */
+    readonly tags?: readonly string[];
+}
+/**
+ * A cache backend.
+ *
+ * Deliberately small: a store that only knows how to read, write and forget
+ * cannot be where a subtle correctness bug lives. Everything else — negative
+ * caching, single-flight, tag bookkeeping — is composed above it.
+ */
+export interface CacheStore {
+    /** The stored entry, or `undefined` when absent or expired. */
+    get<TValue>(key: string): Promise<CacheEntry<TValue> | undefined>;
+    set<TValue>(key: string, entry: CacheEntry<TValue>): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** Remove every key under a prefix; how a namespace is dropped. */
+    deletePrefix(prefix: string): Promise<number>;
+    /** Remove every entry carrying a tag. */
+    deleteTag(tag: string): Promise<number>;
+    clear(): Promise<void>;
+}
+/** What `CacheService.wrap` was asked to do, for metrics and tests. */
+export type CacheOutcome = 'hit' | 'miss' | 'stale' | 'bypass';
+export interface CacheStats {
+    readonly hits: number;
+    readonly misses: number;
+    /** Served from L2 and promoted into L1. */
+    readonly promotions: number;
+    /** Loads that joined an in-flight load rather than starting their own. */
+    readonly coalesced: number;
+}
+/** Injected so TTLs are testable without waiting. */
+export interface Clock {
+    now(): number;
+}
+export declare const systemClock: Clock;
+//# sourceMappingURL=ports.d.ts.map

package/dist/ports.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * The cache contract (PLAN.md §8, §25 P1).
+ *
+ * One port, two tiers. `CacheStore` is what a backend implements — memory,
+ * Redis, anything with get/set/delete — and `CacheService` is what application
+ * code uses. Keeping them apart is what lets the two-tier arrangement (a small
+ * in-process L1 in front of a shared L2) be a composition rather than a special
+ * case every caller has to know about.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemClock = void 0;
+exports.systemClock = { now: () => Date.now() };
+//# sourceMappingURL=ports.js.map

package/dist/redis.store.d.ts

@@ -0,0 +1,48 @@
+/**
+ * A Redis-backed L2, written against a **client port** rather than a client.
+ *
+ * `@nage-api/cache` does not depend on ioredis or node-redis. It states the six
+ * commands it needs, an application passes something that implements them, and
+ * this file contains the part that is actually cache-specific: how an entry is
+ * serialised, how a namespace is dropped without `KEYS *`, and how tags are
+ * tracked.
+ *
+ * That indirection is not ceremony. It keeps a heavyweight optional dependency
+ * out of the install for the many deployments that never use it, and it makes
+ * the store testable without a Redis daemon — which is what the suite does.
+ */
+import type { CacheEntry, CacheStore } from './ports.js';
+/**
+ * The subset of a Redis client this store uses.
+ *
+ * `scan` rather than `keys`: `KEYS` is O(n) over the whole keyspace and blocks
+ * the server, which is exactly the wrong thing to do on the shared instance
+ * every service depends on.
+ */
+export interface RedisClientPort {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, expiryMode?: 'PX', ttl?: number): Promise<unknown>;
+    del(...keys: string[]): Promise<number>;
+    /** Returns `[cursor, keys]`, exactly as Redis does. */
+    scan(cursor: string, match: string, count: number): Promise<[string, string[]]>;
+    sadd(key: string, ...members: string[]): Promise<number>;
+    smembers(key: string): Promise<string[]>;
+}
+export interface RedisCacheStoreOptions {
+    readonly client: RedisClientPort;
+    /** Prefix for every key, so several apps can share one Redis. */
+    readonly keyPrefix?: string;
+    /** Keys scanned per round trip. */
+    readonly scanCount?: number;
+}
+export declare class RedisCacheStore implements CacheStore {
+    #private;
+    constructor(options: RedisCacheStoreOptions);
+    get<TValue>(key: string): Promise<CacheEntry<TValue> | undefined>;
+    set<TValue>(key: string, entry: CacheEntry<TValue>): Promise<void>;
+    delete(key: string): Promise<void>;
+    deletePrefix(prefix: string): Promise<number>;
+    deleteTag(tag: string): Promise<number>;
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=redis.store.d.ts.map

package/dist/redis.store.js

@@ -0,0 +1,101 @@
+"use strict";
+/**
+ * A Redis-backed L2, written against a **client port** rather than a client.
+ *
+ * `@nage-api/cache` does not depend on ioredis or node-redis. It states the six
+ * commands it needs, an application passes something that implements them, and
+ * this file contains the part that is actually cache-specific: how an entry is
+ * serialised, how a namespace is dropped without `KEYS *`, and how tags are
+ * tracked.
+ *
+ * That indirection is not ceremony. It keeps a heavyweight optional dependency
+ * out of the install for the many deployments that never use it, and it makes
+ * the store testable without a Redis daemon — which is what the suite does.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisCacheStore = void 0;
+const DEFAULT_SCAN_COUNT = 200;
+const TAG_INDEX_PREFIX = '__tag__';
+class RedisCacheStore {
+    #client;
+    #prefix;
+    #scanCount;
+    constructor(options) {
+        this.#client = options.client;
+        this.#prefix = options.keyPrefix ?? '';
+        this.#scanCount = options.scanCount ?? DEFAULT_SCAN_COUNT;
+    }
+    async get(key) {
+        const raw = await this.#client.get(this.#full(key));
+        if (raw === null)
+            return undefined;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            // A value written by another version, or by something else entirely. A
+            // cache miss is the right answer; a parse error would take down a request
+            // that could have been served from the source.
+            return undefined;
+        }
+    }
+    async set(key, entry) {
+        const full = this.#full(key);
+        const payload = JSON.stringify(entry);
+        // Redis owns expiry, so a restarted process cannot resurrect stale values.
+        if (entry.expiresAt === undefined) {
+            await this.#client.set(full, payload);
+        }
+        else {
+            const ttl = Math.max(1, entry.expiresAt - Date.now());
+            await this.#client.set(full, payload, 'PX', ttl);
+        }
+        for (const tag of entry.tags ?? []) {
+            await this.#client.sadd(this.#tagKey(tag), full);
+        }
+    }
+    async delete(key) {
+        await this.#client.del(this.#full(key));
+    }
+    async deletePrefix(prefix) {
+        const keys = await this.#scan(`${this.#full(prefix)}*`);
+        if (keys.length === 0)
+            return 0;
+        return this.#client.del(...keys);
+    }
+    async deleteTag(tag) {
+        const tagKey = this.#tagKey(tag);
+        const members = await this.#client.smembers(tagKey);
+        if (members.length === 0)
+            return 0;
+        // The index goes too, so a tag never accumulates keys that no longer exist.
+        const deleted = await this.#client.del(...members);
+        await this.#client.del(tagKey);
+        return deleted;
+    }
+    async clear() {
+        // Scoped to this store's prefix. Flushing the whole database would take out
+        // every other service sharing the instance.
+        const keys = await this.#scan(`${this.#prefix}*`);
+        if (keys.length > 0)
+            await this.#client.del(...keys);
+    }
+    async #scan(match) {
+        const found = [];
+        let cursor = '0';
+        do {
+            const [next, keys] = await this.#client.scan(cursor, match, this.#scanCount);
+            found.push(...keys);
+            cursor = next;
+        } while (cursor !== '0');
+        return found;
+    }
+    #full(key) {
+        return `${this.#prefix}${key}`;
+    }
+    #tagKey(tag) {
+        return `${this.#prefix}${TAG_INDEX_PREFIX}:${tag}`;
+    }
+}
+exports.RedisCacheStore = RedisCacheStore;
+//# sourceMappingURL=redis.store.js.map

package/dist/tokens.d.ts

@@ -0,0 +1,14 @@
+/**
+ * DI tokens for the cache (PLAN.md §7.3).
+ *
+ * Two tokens, not one: application code injects `NAGE_CACHE` (the typed
+ * service), and a driver or a diagnostic tool that needs the raw store injects
+ * `NAGE_CACHE_STORE`. Collapsing them would make every consumer depend on the
+ * backend's surface.
+ */
+import { type Token } from '@nage-api/core';
+import type { CacheService } from './cache.service.js';
+import type { CacheStore } from './ports.js';
+export declare const NAGE_CACHE: Token<CacheService>;
+export declare const NAGE_CACHE_STORE: Token<CacheStore>;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * DI tokens for the cache (PLAN.md §7.3).
+ *
+ * Two tokens, not one: application code injects `NAGE_CACHE` (the typed
+ * service), and a driver or a diagnostic tool that needs the raw store injects
+ * `NAGE_CACHE_STORE`. Collapsing them would make every consumer depend on the
+ * backend's surface.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NAGE_CACHE_STORE = exports.NAGE_CACHE = void 0;
+const core_1 = require("@nage-api/core");
+exports.NAGE_CACHE = (0, core_1.createToken)('NAGE_CACHE');
+exports.NAGE_CACHE_STORE = (0, core_1.createToken)('NAGE_CACHE_STORE');
+//# sourceMappingURL=tokens.js.map

package/dist/two-tier.store.d.ts

@@ -0,0 +1,41 @@
+/**
+ * L1 in front of L2 (PLAN.md §8: "two-tier Keyv (memory+redis), typed").
+ *
+ * The point is latency, not capacity: a shared Redis is one network round trip
+ * away, and a request that reads the same key five times should pay for it
+ * once. L1 is a small in-process cache with a **shorter** TTL than L2, because
+ * an in-process copy is the one nothing can invalidate remotely.
+ *
+ * That shorter TTL is the whole safety argument. Another instance deleting a
+ * key clears L2 immediately and every L1 within its own TTL — so staleness is
+ * bounded by a number you choose, rather than by when a process happens to
+ * restart. Deleting locally also clears the local copy at once, so the instance
+ * that made a change never reads its own stale value.
+ */
+import type { CacheEntry, CacheStore, Clock } from './ports.js';
+export interface TwoTierCacheStoreOptions {
+    readonly l1: CacheStore;
+    readonly l2: CacheStore;
+    /**
+     * Cap on how long L1 may hold a value, in milliseconds. Keep it small: it is
+     * the window in which this instance can serve a value another instance has
+     * already invalidated.
+     */
+    readonly l1TtlMs?: number;
+    readonly clock?: Clock;
+    /** Called when L2 fails, so a broken remote degrades rather than throws. */
+    readonly onRemoteError?: (operation: string, error: unknown) => void;
+}
+export declare class TwoTierCacheStore implements CacheStore {
+    #private;
+    constructor(options: TwoTierCacheStoreOptions);
+    get<TValue>(key: string): Promise<CacheEntry<TValue> | undefined>;
+    set<TValue>(key: string, entry: CacheEntry<TValue>): Promise<void>;
+    delete(key: string): Promise<void>;
+    deletePrefix(prefix: string): Promise<number>;
+    deleteTag(tag: string): Promise<number>;
+    clear(): Promise<void>;
+    /** How many reads were served by L2 and copied into L1. */
+    get promotions(): number;
+}
+//# sourceMappingURL=two-tier.store.d.ts.map