@nage-api/cache 1.0.0-beta.2

package/dist/two-tier.store.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TwoTierCacheStore = void 0;
+const DEFAULT_L1_TTL_MS = 5_000;
+class TwoTierCacheStore {
+    #l1;
+    #l2;
+    #l1TtlMs;
+    #clock;
+    #onRemoteError;
+    #promotions = 0;
+    constructor(options) {
+        this.#l1 = options.l1;
+        this.#l2 = options.l2;
+        this.#l1TtlMs = options.l1TtlMs ?? DEFAULT_L1_TTL_MS;
+        this.#clock = options.clock ?? { now: () => Date.now() };
+        this.#onRemoteError = options.onRemoteError;
+    }
+    async get(key) {
+        const local = await this.#l1.get(key);
+        if (local !== undefined)
+            return local;
+        const remote = await this.#tryRemote('get', () => this.#l2.get(key));
+        if (remote === undefined)
+            return undefined;
+        await this.#l1.set(key, this.#clampForL1(remote));
+        this.#promotions += 1;
+        return remote;
+    }
+    async set(key, entry) {
+        // L2 first: if the shared write fails, an L1 copy nobody else can see would
+        // be the worst of both worlds.
+        await this.#tryRemote('set', async () => {
+            await this.#l2.set(key, entry);
+            return undefined;
+        });
+        await this.#l1.set(key, this.#clampForL1(entry));
+    }
+    async delete(key) {
+        await this.#l1.delete(key);
+        await this.#tryRemote('delete', async () => {
+            await this.#l2.delete(key);
+            return undefined;
+        });
+    }
+    async deletePrefix(prefix) {
+        await this.#l1.deletePrefix(prefix);
+        return (await this.#tryRemote('deletePrefix', () => this.#l2.deletePrefix(prefix))) ?? 0;
+    }
+    async deleteTag(tag) {
+        await this.#l1.deleteTag(tag);
+        return (await this.#tryRemote('deleteTag', () => this.#l2.deleteTag(tag))) ?? 0;
+    }
+    async clear() {
+        await this.#l1.clear();
+        await this.#tryRemote('clear', async () => {
+            await this.#l2.clear();
+            return undefined;
+        });
+    }
+    /** How many reads were served by L2 and copied into L1. */
+    get promotions() {
+        return this.#promotions;
+    }
+    #clampForL1(entry) {
+        const ceiling = this.#clock.now() + this.#l1TtlMs;
+        const expiresAt = entry.expiresAt === undefined ? ceiling : Math.min(entry.expiresAt, ceiling);
+        return { ...entry, expiresAt };
+    }
+    /**
+     * Run an L2 operation, degrading to `undefined` on failure.
+     *
+     * A cache is an optimisation. If Redis is down, the application should be
+     * slower, not broken — so a remote failure is reported and swallowed rather
+     * than propagated to a request that could have been served from the source.
+     */
+    async #tryRemote(operation, run) {
+        try {
+            return await run();
+        }
+        catch (error) {
+            this.#onRemoteError?.(operation, error);
+            return undefined;
+        }
+    }
+}
+exports.TwoTierCacheStore = TwoTierCacheStore;
+//# sourceMappingURL=two-tier.store.js.map

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@nage-api/cache",
+  "version": "1.0.0-beta.2",
+  "description": "Typed two-tier cache for @nage-api — memory L1, pluggable remote L2, namespaced invalidation",
+  "license": "Apache-2.0",
+  "type": "commonjs",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "!dist/**/*.map",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nage-api/contracts": "1.0.0-beta.2",
+    "@nage-api/core": "1.0.0-beta.2"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "reflect-metadata": "^0.2.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "11.1.29",
+    "@nestjs/core": "11.1.29",
+    "@nestjs/testing": "11.1.29",
+    "@swc/core": "1.15.47",
+    "@types/node": "22.20.1",
+    "@vitest/coverage-v8": "4.1.10",
+    "reflect-metadata": "0.2.2",
+    "rimraf": "6.1.3",
+    "rxjs": "7.8.2",
+    "typescript": "5.9.3",
+    "unplugin-swc": "1.5.11",
+    "vitest": "4.1.10"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "clean": "rimraf dist .turbo",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}