@dee-wan/cache 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dee-wan-cms
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# @dee-wan/cache
+
+Prisma read cache for Cloudflare Workers and D1. A Durable Object coordinates invalidation, fill locks
+and cached values, so a write through one Worker is seen by every other Worker on its next read.
+
+The contract, including every invalidation rule and limit, is in
+[docs/cache-contract.md](docs/cache-contract.md).
+
+## Generate the config
+
+```prisma
+generator cache {
+  provider = "dee-wan-cache-generator"
+  output   = "../src/generated/cache"
+  exclude  = ["AuditLog"]   // optional
+}
+
+/// @cache.skip
+model Session {
+  id String @id
+}
+```
+
+Run `npx prisma generate` (or an npm script that runs `prisma generate`) to write `cache-config.ts`.
+The provider name resolves through `node_modules/.bin`, so the Prisma binary must run with npm's `PATH`.
+Every model is cacheable unless it carries `/// @cache.skip` or is listed in `exclude`. Reads that
+include an opted-out model are not cached. Regenerate after upgrading this package: the extension
+refuses a config of another format.
+
+## Wire it into a Worker
+
+```ts
+import { PrismaD1 } from "@prisma/adapter-d1";
+import { createCacheExtension } from "@dee-wan/cache";
+import { createDurableObjectStore } from "@dee-wan/cache/cloudflare";
+import { cacheConfig } from "./generated/cache/cache-config";
+import { Prisma, PrismaClient } from "./generated/prisma";
+
+export { CacheCoordinator } from "@dee-wan/cache/cloudflare";
+
+export default {
+  async fetch(request, env, ctx) {
+    const prisma = new PrismaClient({ adapter: new PrismaD1(env.DB) }).$extends(
+      createCacheExtension({
+        config: cacheConfig,
+        decimal: Prisma.Decimal,
+        enabled: env.CACHE_ENABLED !== "false",
+        generation: env.CACHE_GENERATION,
+        scope: "public",
+        store: createDurableObjectStore(env.CACHE_COORDINATOR, { name: "main-db" }),
+        waitUntil: (promise) => ctx.waitUntil(promise),
+      }),
+    );
+    // ...
+  },
+} satisfies ExportedHandler<Env>;
+```
+
+```jsonc
+{
+  "durable_objects": { "bindings": [{ "name": "CACHE_COORDINATOR", "class_name": "CacheCoordinator" }] },
+  "migrations": [{ "tag": "cache-v1", "new_sqlite_classes": ["CacheCoordinator"] }]
+}
+```
+
+Prisma runs query extensions outermost-first in the order they were applied (verified on Prisma 6.19.3).
+Apply per-caller extensions such as prisma-guard before the cache:
+
+```ts
+const client = base.$extends(guardFor(caller)).$extends(createCacheExtension({ ...options, scope }));
+```
+
+They then run on every read, including hits, and the arguments they rewrite (for example a tenant
+filter) are part of the cache key. An extension applied after the cache is skipped on a hit. Use
+`scope` for anything a caller changes about results without changing the arguments.
+
+## Options
+
+Invalid options throw a `TypeError` at construction.
+
+| Option | Default | Meaning |
+|---|---|---|
+| `config` | — | Generated config. |
+| `store` | — | `createDurableObjectStore(namespace, { name, attempts?, locationHint? })`. |
+| `decimal` | none | `Prisma.Decimal`. Required when the schema has Decimal fields. |
+| `enabled` | `true` | `false`: reads and writes skip the coordinator. `$cacheInvalidate` still calls it. |
+| `scope` | `""` | Part of every key. |
+| `generation` | none | 1..256 chars, the same for every Worker bound to the coordinator. Changing it invalidates every entry once. |
+| `excludeModels` | `[]` | Runtime opt-out on top of the generated config. |
+| `shape` | fresh 3600 s, negative 600 s, soft ratio 0.8 | `{ default, byModel }`. TTLs must be at most 28,747,636 s. |
+| `waitUntil` | none | Enables refresh after the soft TTL. |
+| `leaseMs` | 60000 | Write lease, at most 600000. |
+| `lockMs` | 30000 | Fill lock, at most 300000. |
+| `fillPollDelaysMs` | 20, 40, 80, 160, 320, 640 | Waits while another request fills the same key. Readers stop waiting once the holder has held the lock longer than the whole budget. |
+| `maxValueBytes` | 1500000 | Larger results are served but not cached. At most 1900000. |
+| `onError` | none | Receives coordinator, serialization and write errors. |
+
+`createDurableObjectStore(namespace, { name, attempts, locationHint })`:
+
+- `name` (required) identifies the D1 database. Keys do not include the database, so two databases
+  sharing one coordinator name would share cached rows. Use one name per database.
+- `attempts` (default 3, at most 10) is the total number of tries for retryable coordinator errors on
+  begin, end and invalidate.
+- `locationHint` (`wnam`, `enam`, `sam`, `weur`, `eeur`, `apac`, `oc`, `afr`, `me`) places the
+  coordinator on first creation, best effort.
+
+## Raw SQL writes
+
+Raw SQL does not pass through the extension. Wrap it:
+
+```ts
+await prisma.$cacheRawWrite({ models: ["Post"] }, () => env.DB.prepare("UPDATE Post SET ...").run());
+await prisma.$cacheInvalidate({ entities: [{ model: "Post", pk: [42] }] });
+await prisma.$cacheInvalidate({ all: true });
+```
+
+Models that reference the target through a foreign key are invalidated too. Unknown model names throw.
+
+## Behaviour to plan for
+
+- Coordinator unreachable on a read: the read goes to D1 and nothing is cached.
+- Coordinator unreachable or overloaded before a write: `CacheUnavailableError` is thrown and the write
+  does not run. Cache reads and writes share one coordinator, so heavy read load can refuse writes.
+- Writes made while `enabled: false` are not tracked. Change `generation` when turning the cache back
+  on, or call `$cacheInvalidate({ all: true })`. Never run a disabled and an enabled version together.
+- A new schema or package version invalidates every entry on first contact. Workers of different
+  versions bound to one coordinator keep invalidating each other until one version remains.
+- Rolling back to a release with an older coordinator storage schema makes every write fail with
+  `CacheUnavailableError`. Roll forward.
+- Reads inside batch `$transaction([...])` are not cached. Prisma's D1 adapter rejects interactive
+  transactions.
+- Reads through D1 `withSession` replicas are not supported.
+- One coordinator Durable Object has a soft limit of 1,000 requests per second. Measured on
+  2026-09-17 from one client: about 1,030 cached reads per second at 21 ms p50 with no errors, against
+  about 340 per second at 215 ms reading D1 directly. Higher rates are not measured.
+- Each cached hit costs one coordinator call; a miss costs two; a contended miss can cost up to seven;
+  each write costs two, plus retries. On the Workers Free plan, requests that make many Prisma calls
+  can reach the subrequest limit (see the contract, "Cost per Prisma call").
+- Every write to a model invalidates that model's cached lists, counts and relation reads.
+- Cached entries are capped at 1 GiB per coordinator; the entries closest to expiry are evicted first.
+- Every cached read makes a round trip to the one coordinator location. Measured from Asia on
+  2026-09-17: hits took 8–14 ms with the coordinator in `apac` and 171–210 ms with it in `weur`, slower
+  than reading a nearby D1 directly (48–103 ms). Place the coordinator near most traffic with
+  `locationHint`; users far from it can get slower reads than without the cache.
+
+## Runtime requirements
+
+- Cloudflare Workers with a SQLite-backed Durable Object and D1. No `nodejs_compat` needed.
+- Prisma 6.19.3 or newer 6.x with `@prisma/adapter-d1` (tested with 6.19.3).
+- Generator: Node 20 or newer (CI runs it on 20, 22 and 24). Wrangler 4 and Miniflare need Node 22.
+
+## Development
+
+```sh
+npm run build
+npm run lint
+npm run typecheck        # builds, generates the test client, then checks src and tests
+npm run test:unit        # Node 22.5+ (node:sqlite)
+npm run test:workerd
+npm run test:consumer    # packs, installs into a fresh Worker project, runs it on workerd
+```
+
+Deployed smoke (only on a disposable account; the test Worker runs arbitrary SQL for callers holding
+the token):
+
+```sh
+npm run test:prepare
+npx wrangler d1 create <name>                       # put the id into a copy of test/deployed/wrangler.example.jsonc
+npx wrangler d1 execute <name> --remote --file test/workerd/.build/schema.sql
+npx wrangler deploy -c <copy> --var SMOKE_TOKEN:<random>
+CACHE_SMOKE_URL=https://<worker> CACHE_SMOKE_TOKEN=<random> npm run test:deployed
+npx wrangler delete --name <worker> && npx wrangler d1 delete <name>
+```
+
+`test/workerd/.build/schema.sql` is written by `npm run test:workerd`.

package/dist/chunk-OQRNVGQE.js

@@ -0,0 +1,21 @@
+// src/core/fences.ts
+var GLOBAL_FENCE = "g";
+var modelFence = (model) => `m:${model}`;
+var writeFence = (model) => `w:${model}`;
+var entityFence = (model, pk) => `e:${model}:${pk}`;
+
+// src/core/limits.ts
+var MAX_LOCK_MS = 3e5;
+var MAX_LEASE_MS = 6e5;
+var MAX_VALUE_BYTES = 19e5;
+var MAX_GENERATION_LENGTH = 256;
+var MAX_COORDINATOR_GENERATION_LENGTH = 512;
+var MAX_TTL_MS = 366 * 24 * 60 * 60 * 1e3;
+var TTL_JITTER_RATIO = 0.1;
+var MAX_SHAPE_TTL_SECONDS = Math.floor(MAX_TTL_MS / 1e3 / (1 + TTL_JITTER_RATIO));
+var CONFIG_FORMAT = 2;
+var PLANNER_VERSION = 2;
+
+export { CONFIG_FORMAT, GLOBAL_FENCE, MAX_COORDINATOR_GENERATION_LENGTH, MAX_GENERATION_LENGTH, MAX_LEASE_MS, MAX_LOCK_MS, MAX_SHAPE_TTL_SECONDS, MAX_TTL_MS, MAX_VALUE_BYTES, PLANNER_VERSION, TTL_JITTER_RATIO, entityFence, modelFence, writeFence };
+//# sourceMappingURL=chunk-OQRNVGQE.js.map
+//# sourceMappingURL=chunk-OQRNVGQE.js.map

package/dist/chunk-OQRNVGQE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/fences.ts","../src/core/limits.ts"],"names":[],"mappings":";AAAO,IAAM,YAAA,GAAe;AAErB,IAAM,UAAA,GAAa,CAAC,KAAA,KAA0B,CAAA,EAAA,EAAK,KAAK,CAAA;AAExD,IAAM,UAAA,GAAa,CAAC,KAAA,KAA0B,CAAA,EAAA,EAAK,KAAK,CAAA;AAExD,IAAM,cAAc,CAAC,KAAA,EAAe,OAAuB,CAAA,EAAA,EAAK,KAAK,IAAI,EAAE,CAAA;;;ACN3E,IAAM,WAAA,GAAc;AACpB,IAAM,YAAA,GAAe;AACrB,IAAM,eAAA,GAAkB;AACxB,IAAM,qBAAA,GAAwB;AAC9B,IAAM,iCAAA,GAAoC;AAC1C,IAAM,UAAA,GAAa,GAAA,GAAM,EAAA,GAAK,EAAA,GAAK,EAAA,GAAK;AACxC,IAAM,gBAAA,GAAmB;AACzB,IAAM,wBAAwB,IAAA,CAAK,KAAA,CAAM,UAAA,GAAa,GAAA,IAAQ,IAAI,gBAAA,CAAiB;AACnF,IAAM,aAAA,GAAgB;AACtB,IAAM,eAAA,GAAkB","file":"chunk-OQRNVGQE.js","sourcesContent":["export const GLOBAL_FENCE = \"g\";\n\nexport const modelFence = (model: string): string => `m:${model}`;\n\nexport const writeFence = (model: string): string => `w:${model}`;\n\nexport const entityFence = (model: string, pk: string): string => `e:${model}:${pk}`;\n","export const MAX_LOCK_MS = 300_000;\nexport const MAX_LEASE_MS = 600_000;\nexport const MAX_VALUE_BYTES = 1_900_000;\nexport const MAX_GENERATION_LENGTH = 256;\nexport const MAX_COORDINATOR_GENERATION_LENGTH = 512;\nexport const MAX_TTL_MS = 366 * 24 * 60 * 60 * 1000;\nexport const TTL_JITTER_RATIO = 0.1;\nexport const MAX_SHAPE_TTL_SECONDS = Math.floor(MAX_TTL_MS / 1000 / (1 + TTL_JITTER_RATIO));\nexport const CONFIG_FORMAT = 2;\nexport const PLANNER_VERSION = 2;\n"]}

package/dist/cloudflare/index.d.ts

@@ -0,0 +1,26 @@
+import { DurableObject } from 'cloudflare:workers';
+import { R as ReadRequest, a as ReadResponse, W as WriteRequest, b as WriteResult, c as ReleaseRequest, B as BeginWriteRequest, E as EndWriteRequest, C as CacheStore } from '../types-DwtU0KpX.js';
+
+declare class CacheCoordinator<Env = unknown> extends DurableObject<Env> {
+    private readonly core;
+    constructor(ctx: DurableObjectState, env: Env);
+    read(request: ReadRequest): ReadResponse;
+    write(request: WriteRequest): WriteResult;
+    release(request: ReleaseRequest): void;
+    beginWrite(request: BeginWriteRequest): void;
+    endWrite(request: EndWriteRequest): void;
+    invalidate(fences: string[]): void;
+}
+
+declare const LOCATION_HINTS: readonly ["wnam", "enam", "sam", "weur", "eeur", "apac", "oc", "afr", "me"];
+type CoordinatorLocationHint = (typeof LOCATION_HINTS)[number];
+interface DurableObjectStoreOptions {
+    attempts?: number;
+    locationHint?: CoordinatorLocationHint;
+    name: string;
+    sleep?: (ms: number) => Promise<void>;
+}
+
+declare function createDurableObjectStore<Env>(namespace: DurableObjectNamespace<CacheCoordinator<Env>>, options: DurableObjectStoreOptions): CacheStore;
+
+export { CacheCoordinator, type CoordinatorLocationHint, type DurableObjectStoreOptions, createDurableObjectStore };

package/dist/cloudflare/index.js

@@ -0,0 +1,406 @@
+import { MAX_TTL_MS, MAX_VALUE_BYTES, MAX_COORDINATOR_GENERATION_LENGTH, MAX_LEASE_MS, MAX_LOCK_MS, GLOBAL_FENCE } from '../chunk-OQRNVGQE.js';
+import { DurableObject } from 'cloudflare:workers';
+
+// src/cloudflare/coordinator-core.ts
+var FENCE_RETENTION_MS = 2 * MAX_LOCK_MS;
+var SWEEP_LIMIT = 50;
+var FENCE_COLLECT_LIMIT = 100;
+var PURGE_LIMIT = 500;
+var EVICTION_BATCH = 50;
+var MAX_EVICTION_ROUNDS = 20;
+var MAX_STORED_BYTES = 1024 * 1024 * 1024;
+var MAX_KEY_LENGTH = 1024;
+var MAX_TOKEN_LENGTH = 128;
+var MAX_FENCE_LENGTH = 512;
+var MAX_FENCES_PER_REQUEST = 5e3;
+var MAX_BOUND_PARAMETERS = 90;
+var MIGRATIONS = [
+  `
+CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value INTEGER NOT NULL);
+INSERT OR IGNORE INTO meta (key, value) VALUES ('sequence', 0);
+CREATE TABLE IF NOT EXISTS fences (fence TEXT PRIMARY KEY, epoch INTEGER NOT NULL, updated_at INTEGER NOT NULL);
+CREATE INDEX IF NOT EXISTS fences_by_updated ON fences (updated_at);
+CREATE TABLE IF NOT EXISTS leases (token TEXT NOT NULL, fence TEXT NOT NULL, expires_at INTEGER NOT NULL, PRIMARY KEY (token, fence));
+CREATE INDEX IF NOT EXISTS leases_by_fence ON leases (fence, expires_at);
+CREATE INDEX IF NOT EXISTS leases_by_expiry ON leases (expires_at);
+CREATE TABLE IF NOT EXISTS locks (key TEXT PRIMARY KEY, token TEXT NOT NULL, expires_at INTEGER NOT NULL);
+CREATE INDEX IF NOT EXISTS locks_by_expiry ON locks (expires_at);
+CREATE TABLE IF NOT EXISTS entries (key TEXT PRIMARY KEY, value TEXT NOT NULL, snapshot TEXT NOT NULL, soft_expires_at INTEGER NOT NULL, expires_at INTEGER NOT NULL);
+CREATE INDEX IF NOT EXISTS entries_by_expiry ON entries (expires_at);
+CREATE TABLE IF NOT EXISTS entry_fences (fence TEXT NOT NULL, key TEXT NOT NULL, PRIMARY KEY (fence, key));
+CREATE INDEX IF NOT EXISTS entry_fences_by_key ON entry_fences (key);
+`,
+  `
+CREATE TABLE IF NOT EXISTS generation (id INTEGER PRIMARY KEY CHECK (id = 1), value TEXT NOT NULL);
+`,
+  `
+ALTER TABLE locks ADD COLUMN seq INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE locks ADD COLUMN kind TEXT NOT NULL DEFAULT 'fill';
+ALTER TABLE locks ADD COLUMN acquired_at INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE entries ADD COLUMN size INTEGER NOT NULL DEFAULT 0;
+INSERT OR IGNORE INTO meta (key, value) VALUES ('gc_watermark', 0);
+INSERT OR IGNORE INTO meta (key, value) VALUES ('entry_bytes', 0);
+CREATE TABLE IF NOT EXISTS gc_cursor (id INTEGER PRIMARY KEY CHECK (id = 1), updated_at INTEGER NOT NULL, fence TEXT NOT NULL);
+INSERT OR IGNORE INTO gc_cursor (id, updated_at, fence) VALUES (1, -1, '');
+CREATE INDEX IF NOT EXISTS fences_by_updated_fence ON fences (updated_at, fence);
+`
+];
+function chunks(items) {
+  const out = [];
+  for (let i = 0; i < items.length; i += MAX_BOUND_PARAMETERS) out.push(items.slice(i, i + MAX_BOUND_PARAMETERS));
+  return out;
+}
+var placeholders = (count) => Array.from({ length: count }, () => "?").join(",");
+var clamp = (value, max) => Math.min(Math.max(Math.trunc(value), 1), max);
+function assertRequest(condition, message) {
+  if (!condition) throw new TypeError(`cache coordinator: ${message}`);
+}
+var isKey = (value) => typeof value === "string" && value.length > 0 && value.length <= MAX_KEY_LENGTH;
+var isFenceList = (value) => Array.isArray(value) && value.length <= MAX_FENCES_PER_REQUEST && value.every((fence) => typeof fence === "string" && fence.length > 0 && fence.length <= MAX_FENCE_LENGTH);
+var isSnapshot = (value) => !!value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length <= MAX_FENCES_PER_REQUEST && Object.values(value).every((epoch) => Number.isSafeInteger(epoch));
+var isGeneration = (value) => value === void 0 || typeof value === "string" && value.length > 0 && value.length <= MAX_COORDINATOR_GENERATION_LENGTH;
+var isToken = (value) => typeof value === "string" && value.length > 0 && value.length <= MAX_TOKEN_LENGTH;
+var isDuration = (value) => typeof value === "number" && Number.isFinite(value) && value > 0;
+var byteLength = (text) => new TextEncoder().encode(text).byteLength;
+function parseSnapshot(text) {
+  try {
+    const parsed = JSON.parse(text);
+    return isSnapshot(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function migrate(sql, transact) {
+  transact(() => {
+    sql.exec("CREATE TABLE IF NOT EXISTS schema_version (id INTEGER PRIMARY KEY CHECK (id = 1), version INTEGER NOT NULL)");
+    const current = Number(sql.exec("SELECT version FROM schema_version WHERE id = 1").toArray()[0]?.version ?? 0);
+    if (current > MIGRATIONS.length) {
+      throw new Error(`cache coordinator: storage schema ${current} is newer than this code (${MIGRATIONS.length})`);
+    }
+    if (current === MIGRATIONS.length) return;
+    MIGRATIONS.slice(current).forEach((migration) => sql.exec(migration));
+    sql.exec("INSERT OR REPLACE INTO schema_version (id, version) VALUES (1, ?)", MIGRATIONS.length);
+  });
+}
+function createCoordinatorCore(sql, newToken, transact, limits = {}) {
+  const maxStoredBytes = limits.maxStoredBytes ?? MAX_STORED_BYTES;
+  const rows = (query, ...bindings) => sql.exec(query, ...bindings).toArray();
+  const metaValue = (key) => Number(rows("SELECT value FROM meta WHERE key = ?", key)[0]?.value ?? 0);
+  function epochs(fences) {
+    const out = Object.fromEntries(fences.map((fence) => [fence, 0]));
+    for (const chunk of chunks([...new Set(fences)])) {
+      for (const row of rows(`SELECT fence, epoch FROM fences WHERE fence IN (${placeholders(chunk.length)})`, ...chunk)) {
+        out[String(row.fence)] = Number(row.epoch);
+      }
+    }
+    return out;
+  }
+  const matches = (snapshot, current) => {
+    const fences = Object.keys(snapshot);
+    return fences.length > 0 && fences.every((fence) => current[fence] === snapshot[fence]);
+  };
+  const pending = (fences, now) => chunks([...new Set(fences)]).some(
+    (chunk) => rows(`SELECT 1 FROM leases WHERE expires_at > ? AND fence IN (${placeholders(chunk.length)}) LIMIT 1`, now, ...chunk).length > 0
+  );
+  function writeLock(key, lockMs, now, kind) {
+    const token = newToken();
+    sql.exec(
+      "INSERT OR REPLACE INTO locks (key, token, expires_at, seq, kind, acquired_at) VALUES (?, ?, ?, ?, ?, ?)",
+      key,
+      token,
+      now + clamp(lockMs, MAX_LOCK_MS),
+      metaValue("sequence"),
+      kind,
+      now
+    );
+    return token;
+  }
+  function deleteEntries(keys) {
+    for (const chunk of chunks(keys)) {
+      const bytes = Number(rows(`SELECT COALESCE(SUM(size), 0) AS bytes FROM entries WHERE key IN (${placeholders(chunk.length)})`, ...chunk)[0]?.bytes ?? 0);
+      sql.exec(`DELETE FROM entry_fences WHERE key IN (${placeholders(chunk.length)})`, ...chunk);
+      sql.exec(`DELETE FROM entries WHERE key IN (${placeholders(chunk.length)})`, ...chunk);
+      if (bytes > 0) sql.exec("UPDATE meta SET value = MAX(0, value - ?) WHERE key = 'entry_bytes'", bytes);
+    }
+  }
+  function makeRoom(size) {
+    for (let round = 0; round < MAX_EVICTION_ROUNDS; round++) {
+      const overflow = metaValue("entry_bytes") + size - maxStoredBytes;
+      if (overflow <= 0) return true;
+      const candidates = rows("SELECT key, size FROM entries ORDER BY expires_at LIMIT ?", EVICTION_BATCH);
+      if (candidates.length === 0) break;
+      let freed = 0;
+      const victims = candidates.filter((row) => {
+        if (freed >= overflow) return false;
+        freed += Number(row.size);
+        return true;
+      });
+      deleteEntries(victims.map((row) => String(row.key)));
+    }
+    return metaValue("entry_bytes") + size <= maxStoredBytes;
+  }
+  function bump(fences, now) {
+    for (const fence of new Set(fences)) {
+      const next = Number(rows("UPDATE meta SET value = value + 1 WHERE key = 'sequence' RETURNING value")[0]?.value);
+      sql.exec(
+        "INSERT INTO fences (fence, epoch, updated_at) VALUES (?, ?, ?) ON CONFLICT (fence) DO UPDATE SET epoch = excluded.epoch, updated_at = excluded.updated_at",
+        fence,
+        next,
+        now
+      );
+    }
+  }
+  function purge(fences) {
+    let budget = PURGE_LIMIT;
+    for (const chunk of chunks([...new Set(fences)])) {
+      if (budget <= 0) return;
+      const keys = rows(
+        `SELECT DISTINCT key FROM entry_fences WHERE fence IN (${placeholders(chunk.length)}) LIMIT ?`,
+        ...chunk,
+        budget
+      );
+      deleteEntries(keys.map((row) => String(row.key)));
+      budget -= keys.length;
+    }
+  }
+  function collectFences(now) {
+    const cursor = rows("SELECT updated_at, fence FROM gc_cursor WHERE id = 1")[0];
+    const after = Number(cursor?.updated_at ?? -1);
+    const afterFence = String(cursor?.fence ?? "");
+    const batch = rows(
+      `SELECT fence, updated_at, epoch,
+         EXISTS (SELECT 1 FROM entry_fences WHERE entry_fences.fence = fences.fence) AS in_entries,
+         EXISTS (SELECT 1 FROM leases WHERE leases.fence = fences.fence) AS in_leases
+       FROM fences
+       WHERE (updated_at, fence) > (?, ?) AND updated_at <= ? AND fence >= ? AND fence < ?
+       ORDER BY updated_at, fence LIMIT ?`,
+      after,
+      afterFence,
+      now - FENCE_RETENTION_MS,
+      "e:",
+      "e;",
+      FENCE_COLLECT_LIMIT
+    );
+    const deletable = batch.filter((row) => Number(row.in_entries) === 0 && Number(row.in_leases) === 0);
+    for (const chunk of chunks(deletable.map((row) => String(row.fence)))) {
+      sql.exec(`DELETE FROM fences WHERE fence IN (${placeholders(chunk.length)})`, ...chunk);
+    }
+    const highestDeletedEpoch = Math.max(0, ...deletable.map((row) => Number(row.epoch)));
+    if (highestDeletedEpoch > 0) {
+      sql.exec("UPDATE meta SET value = MAX(value, ?) WHERE key = 'gc_watermark'", highestDeletedEpoch);
+    }
+    const last = batch[batch.length - 1];
+    const [nextAt, nextFence] = batch.length < FENCE_COLLECT_LIMIT || !last ? [-1, ""] : [Number(last.updated_at), String(last.fence)];
+    if (nextAt !== after || nextFence !== afterFence) {
+      sql.exec("UPDATE gc_cursor SET updated_at = ?, fence = ? WHERE id = 1", nextAt, nextFence);
+    }
+  }
+  function sweep(now) {
+    const expired = rows("SELECT key FROM entries WHERE expires_at <= ? LIMIT ?", now, SWEEP_LIMIT);
+    deleteEntries(expired.map((row) => String(row.key)));
+    sql.exec("DELETE FROM leases WHERE rowid IN (SELECT rowid FROM leases WHERE expires_at <= ? LIMIT ?)", now, SWEEP_LIMIT);
+    sql.exec("DELETE FROM locks WHERE rowid IN (SELECT rowid FROM locks WHERE expires_at <= ? LIMIT ?)", now, SWEEP_LIMIT);
+    collectFences(now);
+  }
+  function observeGeneration(generation, now) {
+    if (generation === void 0) return;
+    const current = rows("SELECT value FROM generation WHERE id = 1")[0]?.value;
+    if (current === generation) return;
+    bump([GLOBAL_FENCE], now);
+    sql.exec("INSERT OR REPLACE INTO generation (id, value) VALUES (1, ?)", generation);
+  }
+  function snapshotValid(snapshot) {
+    return snapshot !== null && matches(snapshot, epochs(Object.keys(snapshot)));
+  }
+  return {
+    beginWrite(request, now) {
+      assertRequest(
+        isFenceList(request.fences) && isDuration(request.leaseMs) && isGeneration(request.generation) && isToken(request.token),
+        "invalid beginWrite request"
+      );
+      transact(() => {
+        observeGeneration(request.generation, now);
+        bump(request.fences, now);
+        const expiresAt = now + clamp(request.leaseMs, MAX_LEASE_MS);
+        for (const fence of new Set(request.fences)) {
+          sql.exec("INSERT OR REPLACE INTO leases (token, fence, expires_at) VALUES (?, ?, ?)", request.token, fence, expiresAt);
+        }
+      });
+    },
+    endWrite(request, now) {
+      assertRequest(isFenceList(request.fences) && isToken(request.token), "invalid endWrite request");
+      transact(() => {
+        bump(request.fences, now);
+        sql.exec("DELETE FROM leases WHERE token = ?", request.token);
+        purge(request.fences);
+        sweep(now);
+      });
+    },
+    invalidate(fences, now) {
+      assertRequest(isFenceList(fences), "invalid invalidate request");
+      transact(() => {
+        bump(fences, now);
+        purge(fences);
+        sweep(now);
+      });
+    },
+    read(request, now) {
+      assertRequest(
+        isKey(request.key) && isFenceList(request.fences) && isDuration(request.lockMs) && isGeneration(request.generation),
+        "invalid read request"
+      );
+      return transact(() => {
+        observeGeneration(request.generation, now);
+        const entry = rows("SELECT value, snapshot, soft_expires_at, expires_at FROM entries WHERE key = ?", request.key)[0];
+        const lock = rows("SELECT expires_at, kind, acquired_at FROM locks WHERE key = ?", request.key)[0];
+        const lockLive = lock !== void 0 && Number(lock.expires_at) > now;
+        if (entry && Number(entry.expires_at) > now) {
+          const snapshot = parseSnapshot(String(entry.snapshot));
+          const current = epochs([...request.fences, ...Object.keys(snapshot ?? {})]);
+          if (snapshot && matches(snapshot, current)) {
+            const refreshable = request.refresh === true && now >= Number(entry.soft_expires_at) && !lockLive && !pending(request.fences, now);
+            return {
+              epochs: Object.fromEntries(request.fences.map((fence) => [fence, current[fence] ?? 0])),
+              kind: "hit",
+              refreshToken: refreshable ? writeLock(request.key, request.lockMs, now, "refresh") : null,
+              value: String(entry.value)
+            };
+          }
+        }
+        if (entry) deleteEntries([request.key]);
+        const isPending = pending(request.fences, now);
+        const heldByFill = lockLive && lock.kind !== "refresh";
+        const lockToken = isPending || heldByFill ? null : writeLock(request.key, request.lockMs, now, "fill");
+        return {
+          epochs: epochs(request.fences),
+          kind: "miss",
+          lockHeldForMs: heldByFill ? Math.max(0, now - Number(lock.acquired_at)) : null,
+          lockToken,
+          pending: isPending
+        };
+      });
+    },
+    release(request) {
+      assertRequest(isKey(request.key) && isToken(request.lockToken), "invalid release request");
+      transact(() => sql.exec("DELETE FROM locks WHERE key = ? AND token = ?", request.key, request.lockToken));
+    },
+    write(request, now) {
+      assertRequest(
+        typeof request.key === "string" && typeof request.lockToken === "string" && typeof request.value === "string" && isSnapshot(request.snapshot) && isDuration(request.ttlMs) && isDuration(request.softTtlMs),
+        "invalid write request"
+      );
+      return transact(() => {
+        const lock = rows("SELECT token, expires_at, seq FROM locks WHERE key = ?", request.key)[0];
+        if (!lock || lock.token !== request.lockToken || Number(lock.expires_at) <= now) return { ok: false, reason: "lock" };
+        sql.exec("DELETE FROM locks WHERE key = ?", request.key);
+        const snapshotText = JSON.stringify(request.snapshot);
+        const size = byteLength(request.value) + snapshotText.length + request.key.length;
+        const oversize = !isKey(request.key) || request.ttlMs > MAX_TTL_MS || byteLength(request.value) > MAX_VALUE_BYTES;
+        if (oversize) return { ok: false, reason: "invalid" };
+        const capturedMissing = Object.values(request.snapshot).some((epoch) => epoch === 0);
+        if (capturedMissing && Number(lock.seq) < metaValue("gc_watermark")) return { ok: false, reason: "fence" };
+        if (!snapshotValid(request.snapshot)) return { ok: false, reason: "fence" };
+        deleteEntries([request.key]);
+        if (!makeRoom(size)) return { ok: false, reason: "full" };
+        sql.exec(
+          "INSERT INTO entries (key, value, snapshot, soft_expires_at, expires_at, size) VALUES (?, ?, ?, ?, ?, ?)",
+          request.key,
+          request.value,
+          snapshotText,
+          now + Math.min(request.softTtlMs, request.ttlMs),
+          now + request.ttlMs,
+          size
+        );
+        sql.exec("UPDATE meta SET value = value + ? WHERE key = 'entry_bytes'", size);
+        for (const fence of Object.keys(request.snapshot)) {
+          sql.exec("INSERT INTO entry_fences (fence, key) VALUES (?, ?)", fence, request.key);
+        }
+        sweep(now);
+        return { ok: true };
+      });
+    }
+  };
+}
+
+// src/cloudflare/coordinator.ts
+var CacheCoordinator = class extends DurableObject {
+  core;
+  constructor(ctx, env) {
+    super(ctx, env);
+    const transact = (run) => ctx.storage.transactionSync(run);
+    migrate(ctx.storage.sql, transact);
+    this.core = createCoordinatorCore(ctx.storage.sql, () => crypto.randomUUID(), transact);
+  }
+  read(request) {
+    return this.core.read(request, Date.now());
+  }
+  write(request) {
+    return this.core.write(request, Date.now());
+  }
+  release(request) {
+    this.core.release(request);
+  }
+  beginWrite(request) {
+    this.core.beginWrite(request, Date.now());
+  }
+  endWrite(request) {
+    this.core.endWrite(request, Date.now());
+  }
+  invalidate(fences) {
+    this.core.invalidate(fences, Date.now());
+  }
+};
+
+// src/cloudflare/retry.ts
+var BASE_BACKOFF_MS = 50;
+var isRetryable = (error) => !!error && typeof error === "object" && Reflect.get(error, "retryable") === true && Reflect.get(error, "overloaded") !== true;
+async function retryTransient(call, attempts, sleep) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await call();
+    } catch (error) {
+      if (attempt + 1 >= attempts || !isRetryable(error)) throw error;
+      await sleep(BASE_BACKOFF_MS * Math.random() * 2 ** attempt);
+    }
+  }
+}
+
+// src/cloudflare/store-options.ts
+var WRITE_PATH_ATTEMPTS = 3;
+var MAX_COORDINATOR_NAME_LENGTH = 256;
+var LOCATION_HINTS = ["wnam", "enam", "sam", "weur", "eeur", "apac", "oc", "afr", "me"];
+var isLocationHint = (value) => LOCATION_HINTS.some((hint) => hint === value);
+function resolveStoreOptions(options) {
+  const { attempts = WRITE_PATH_ATTEMPTS, locationHint, name } = options;
+  const problems = [
+    !(typeof name === "string" && name.length > 0 && name.length <= MAX_COORDINATOR_NAME_LENGTH) && `name must be 1..${MAX_COORDINATOR_NAME_LENGTH} characters and identify one D1 database`,
+    !(Number.isInteger(attempts) && attempts >= 1 && attempts <= 10) && "attempts must be an integer in 1..10",
+    locationHint !== void 0 && !isLocationHint(locationHint) && `locationHint must be one of ${LOCATION_HINTS.join(", ")}`
+  ].filter((problem) => typeof problem === "string");
+  if (problems.length > 0) throw new TypeError(`cache store: ${problems.join("; ")}`);
+  return {
+    attempts,
+    name,
+    sleep: options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+    ...locationHint ? { locationHint } : {}
+  };
+}
+
+// src/cloudflare/store.ts
+function createDurableObjectStore(namespace, options) {
+  const { attempts, locationHint, name, sleep } = resolveStoreOptions(options);
+  const stub = () => namespace.get(namespace.idFromName(name), locationHint ? { locationHint } : void 0);
+  const withRetry = (call) => retryTransient(() => call(stub()), attempts, sleep);
+  return {
+    beginWrite: (request) => withRetry(async (coordinator) => void await coordinator.beginWrite(request)),
+    endWrite: (request) => withRetry(async (coordinator) => void await coordinator.endWrite(request)),
+    invalidate: (fences) => withRetry(async (coordinator) => void await coordinator.invalidate(fences)),
+    read: async (request) => stub().read(request),
+    release: async (request) => void await stub().release(request),
+    write: async (request) => stub().write(request)
+  };
+}
+
+export { CacheCoordinator, createDurableObjectStore };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map