@saacms/plugin-cache-kv 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @saacms/plugin-cache-kv — public surface.
+ *
+ * Opt-in Cloudflare KV-backed L4 cache plugin per ADR 0023 amendment 2026-05-15
+ * (no-platform-dependency principle) and ADR 0024 §"Platform-specific
+ * enhancement layer". The framework's caching story works WITHOUT this plugin
+ * via per-isolate Map + D1 (the correctness layer); installing this plugin
+ * upgrades cache reads to KV (cross-isolate, edge-replicated) for hot paths
+ * — per-user OpenAPI snapshots, ETag projections, session shadows, etc.
+ */
+export { cacheKv, kvCacheAdapter } from "./plugin.ts";
+export type { CacheKvOptions, KvCacheAdapter, KvCacheBinding, KvCacheEntry, KvCachePutOptions, } from "./plugin.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACrD,YAAY,EACV,cAAc,EACd,cAAc,EACd,cAAc,EACd,YAAY,EACZ,iBAAiB,GAClB,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,92 @@
+// src/plugin.ts
+var TAG_RE = /^[a-zA-Z0-9_:./-]{1,128}$/;
+var TAG_INDEX_PREFIX = "tag:";
+var DEFAULT_TTL_SECONDS = 300;
+var DEFAULT_MAX_ENTRY_BYTES = 1e6;
+function assertSafeTag(tag) {
+  if (typeof tag !== "string" || !TAG_RE.test(tag)) {
+    throw new Error(`[saacms/cache-kv] invalid tag: ${JSON.stringify(tag)}`);
+  }
+}
+function tagIndexKey(tag, key) {
+  return `${TAG_INDEX_PREFIX}${tag}:${key}`;
+}
+function kvCacheAdapter(opts) {
+  const binding = opts.binding;
+  const defaultTtl = opts.defaultTtlSeconds ?? DEFAULT_TTL_SECONDS;
+  const maxBytes = opts.maxEntryBytes ?? DEFAULT_MAX_ENTRY_BYTES;
+  return {
+    async get(key) {
+      try {
+        const raw = await binding.get(key, "json");
+        if (raw === null || raw === undefined)
+          return null;
+        return raw;
+      } catch (err) {
+        console.warn(`[saacms/cache-kv] get(${JSON.stringify(key)}) failed:`, err);
+        return null;
+      }
+    },
+    async put(key, value, putOpts) {
+      const tags = putOpts?.tags ?? [];
+      for (const t of tags)
+        assertSafeTag(t);
+      const entry = {
+        value,
+        tags,
+        storedAt: new Date().toISOString()
+      };
+      const json = JSON.stringify(entry);
+      if (json.length > maxBytes) {
+        console.warn(`[saacms/cache-kv] put(${JSON.stringify(key)}) skipped: entry ${json.length}B exceeds maxEntryBytes ${maxBytes}`);
+        return;
+      }
+      const ttl = putOpts?.expirationTtl ?? defaultTtl;
+      const writeOpts = { expirationTtl: ttl };
+      await binding.put(key, json, writeOpts);
+      for (const tag of tags) {
+        await binding.put(tagIndexKey(tag, key), "", writeOpts);
+      }
+    },
+    async delete(key) {
+      await binding.delete(key);
+    },
+    async purgeByTag(tag) {
+      assertSafeTag(tag);
+      const prefix = `${TAG_INDEX_PREFIX}${tag}:`;
+      let cursor;
+      let purged = 0;
+      do {
+        const page = await binding.list({ prefix, cursor });
+        for (const entry of page.keys) {
+          const cacheKey = entry.name.slice(prefix.length);
+          await binding.delete(cacheKey);
+          await binding.delete(entry.name);
+          purged += 1;
+        }
+        if (page.list_complete) {
+          cursor = undefined;
+        } else {
+          cursor = page.cursor;
+          if (!cursor)
+            break;
+        }
+      } while (cursor);
+      return { purgedKeys: purged };
+    }
+  };
+}
+function cacheKv(options) {
+  const adapter = kvCacheAdapter(options);
+  return {
+    name: "@saacms/plugin-cache-kv",
+    version: "0.1.0",
+    services: {
+      cache: adapter
+    }
+  };
+}
+export {
+  kvCacheAdapter,
+  cacheKv
+};

package/dist/plugin.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @saacms/plugin-cache-kv — Cloudflare KV-backed L4 cache.
+ *
+ * Per ADR 0021 (cache hierarchy) + ADR 0023 amendment 2026-05-15
+ * (no-platform-dependency principle): this plugin is the *efficiency* layer.
+ * The framework's caching story works without it via per-isolate Map + D1;
+ * installing it upgrades cache reads to KV (cross-isolate, edge-replicated)
+ * for hot paths — per-user OpenAPI snapshots, ETag projections, etc.
+ *
+ * The plugin contributes a `services.cache` slot containing a `KvCacheAdapter`
+ * bound to a host-supplied KV binding. Runtime cache-wiring (read-through
+ * fallthrough to Map → D1, event-driven invalidation) is a separate dispatch;
+ * this dispatch ships the adapter + factory.
+ */
+import type { PluginDef } from "@saacms/core";
+export interface CacheKvOptions {
+    /** The Workers `KVNamespace` binding; supplied by the host. */
+    readonly binding: KvCacheBinding;
+    /** Documentational: the binding name the host wired (default `SAACMS_CACHE`). */
+    readonly bindingName?: string;
+    /** Default TTL applied to entries that don't specify one. Default: 300s. */
+    readonly defaultTtlSeconds?: number;
+    /** Max bytes per entry; KV's hard cap is 25MB but we default to 1MB. */
+    readonly maxEntryBytes?: number;
+}
+/** Subset of `KVNamespace` used by this plugin. Mirrors @cloudflare/workers-types. */
+export interface KvCacheBinding {
+    get(key: string, type: "json"): Promise<unknown>;
+    get(key: string, type: "text"): Promise<string | null>;
+    put(key: string, value: string | ArrayBuffer | ArrayBufferView, opts?: {
+        readonly expirationTtl?: number;
+        readonly metadata?: unknown;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(opts?: {
+        readonly prefix?: string;
+        readonly cursor?: string;
+    }): Promise<{
+        readonly keys: ReadonlyArray<{
+            readonly name: string;
+            readonly metadata?: unknown;
+        }>;
+        readonly list_complete: boolean;
+        readonly cursor?: string;
+    }>;
+}
+/** What the plugin stores under each cache key. */
+export interface KvCacheEntry<T = unknown> {
+    readonly value: T;
+    readonly tags: ReadonlyArray<string>;
+    readonly storedAt: string;
+}
+export interface KvCachePutOptions {
+    readonly tags?: ReadonlyArray<string>;
+    readonly expirationTtl?: number;
+}
+export interface KvCacheAdapter {
+    get<T = unknown>(key: string): Promise<KvCacheEntry<T> | null>;
+    put<T = unknown>(key: string, value: T, opts?: KvCachePutOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    purgeByTag(tag: string): Promise<{
+        purgedKeys: number;
+    }>;
+}
+export declare function kvCacheAdapter(opts: CacheKvOptions): KvCacheAdapter;
+export declare function cacheKv(options: CacheKvOptions): PluginDef;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAM7C,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;IAChC,iFAAiF;IACjF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;IACnC,wEAAwE;IACxE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAChC;AAED,sFAAsF;AACtF,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAChD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACtD,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,eAAe,EAC7C,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GACtE,OAAO,CAAC,IAAI,CAAC,CAAA;IAChB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAC3E,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;YAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;SAAE,CAAC,CAAA;QACpF,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;QAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KACzB,CAAC,CAAA;CACH;AAED,mDAAmD;AACnD,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACvC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;IACjB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACrC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IAC9D,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAChF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACzD;AAyBD,wBAAgB,cAAc,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,CA+EnE;AAMD,wBAAgB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS,CAS1D"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@saacms/plugin-cache-kv",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc --build",
+    "typecheck": "tsc --build --noEmit",
+    "prepack": "cp package.json package.json.pack-bak && bun run ../../scripts/prepack-pkg.ts",
+    "postpack": "mv package.json.pack-bak package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@saacms/core": "workspace:*",
+    "@cloudflare/workers-types": "^4.20240925.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}