cacheplank 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cacheplank contributors
+
+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

@@ -1,3 +1,161 @@
-# Temporary Holding Version
+# cacheplank
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**The shared plank your pods walk across: one table of tag stamps, everything else stays local.**
+
+`cacheplank` is a single-file, tag-based distributed cache handler for Next.js 16's
+[`cacheHandlers`](https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheHandlers)
+API, backed by [libSQL](https://github.com/tursodatabase/libsql).
+
+Cache **entries** stay local to each process (a plain in-memory LRU). Only tag
+**invalidation** is shared, through one tiny libSQL table (`tag_stamps`). Any
+number of pods or regions converge because every `get` compares the entry's
+timestamp against the shared invalidation stamps. That makes ISR/data-cache cost
+structurally low for self-hosted deploys: every regeneration is a local memory
+write, and the only durable write is a KB-scale tag-stamp upsert.
+
+## Quickstart
+
+```sh
+npm i cacheplank
+```
+
+```sh
+# One env pair is the entire migration surface.
+CACHEPLANK_URL=libsql://your-db.turso.io
+CACHEPLANK_AUTH_TOKEN=...
+```
+
+```js
+// next.config.js  (CommonJS)
+module.exports = {
+  cacheComponents: true,
+  cacheHandlers: {
+    default: require.resolve('cacheplank'),
+  },
+};
+```
+
+```js
+// next.config.mjs  (ESM) — `require` doesn't exist here, so create it:
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+
+export default {
+  cacheComponents: true,
+  cacheHandlers: {
+    default: require.resolve('cacheplank'),
+  },
+};
+```
+
+That's it. The package's `default` export is a ready-to-use handler configured
+from the environment.
+
+### Storage backends
+
+Any libSQL URL scheme works — the table is created lazily on first use.
+
+```sh
+CACHEPLANK_URL=:memory:                       # tests / single process
+CACHEPLANK_URL=file:./.cache/tag_stamps.db    # one box, several processes
+CACHEPLANK_URL=libsql://db.turso.io           # Turso (add CACHEPLANK_AUTH_TOKEN)
+CACHEPLANK_URL=libsql://db.bunny.net          # Bunny Database (libSQL)
+```
+
+The target deployment injects Bunny's native names, so these are honored as
+fallbacks: `BUNNY_DATABASE_URL` and `BUNNY_DATABASE_AUTH_TOKEN`.
+
+### Configuration
+
+| Env var | Default | Purpose |
+| --- | --- | --- |
+| `CACHEPLANK_URL` | — | libSQL URL (falls back to `BUNNY_DATABASE_URL`) |
+| `CACHEPLANK_AUTH_TOKEN` | — | libSQL token (falls back to `BUNNY_DATABASE_AUTH_TOKEN`) |
+| `CACHEPLANK_PREFIX` | `''` | String prepended to every key (the only build/deploy escape hatch) |
+| `CACHEPLANK_MAX_ENTRIES` | `2000` | Local LRU capacity |
+| `CACHEPLANK_STAMPS_TTL_MS` | `3000` | How long the in-process stamp memo is trusted |
+
+The same options can be passed programmatically:
+
+```js
+import { createCacheHandler } from 'cacheplank';
+
+const handler = createCacheHandler({ url: process.env.CACHEPLANK_URL, prefix: 'prod' });
+```
+
+## What it does *not* do
+
+> **cacheplank does not share cache entries between pods. Entries are local and
+> derived; only invalidation is shared. If you want shared entry storage, this is
+> not your package.**
+
+That is the design, not a shortcut. Two pods will each render and each hold their
+own copy; what they agree on is *what is stale*, not *what is cached*. In
+exchange, the shared state is one KB-scale table, and a cold pod simply
+regenerates locally instead of paying a network round-trip for every read.
+
+The handler is **fail-open**: if the database is unreachable, `get` still serves
+valid local entries, and `updateTags` / `refreshTags` resolve without throwing
+(after logging exactly one warning). cacheplank never throws into Next's request
+path.
+
+## Invariants (the compatibility contract)
+
+These are enforced by the test suite, which runs against the built artifacts —
+the thing npm actually ships:
+
+1. `set` → `get` roundtrip returns identical bytes, tags, and timestamps.
+2. `updateTags` is idempotent and monotone across processes sharing one DB
+   (`MAX` wins, interleaved upserts all land).
+3. A tag mutation after a write makes the entry miss — entry tags and route
+   soft tags alike.
+4. Fail-open: an unreachable store never throws, and local hits still serve.
+5. `get` after `set` works with tags alone (never relies on revalidate times
+   round-tripping through Next).
+6. Expiry mirrors Next's own bounds: an entry is a miss past `revalidate` **or**
+   past `expire` (the wrapper discards on either), `expire < 0` is the tiered-cache
+   eviction sentinel → miss, and `expire === 0` is dynamic and not stored in
+   production.
+
+Plus a cross-process fixture: two real child processes, one on-disk `file:` DB,
+a stamp written by one observed by the other. Run everything with:
+
+```sh
+npm run build && npm test
+```
+
+## Compatibility notes
+
+**Verified against [next@16.3.8](https://www.npmjs.com/package/next/v/16.3.8);
+the handler API is platform-unofficial — pin your Next version and treat the
+tests as the contract.** The following were resolved by reading the installed
+package's source (code is truth, prose isn't):
+
+1. **Types are hand-written.** Next does not export `CacheHandler` / `CacheEntry`
+   from its public surface; the canonical definitions live in
+   `dist/server/lib/cache-handlers/types.d.ts`. cacheplank mirrors them exactly
+   (including the `[seconds]` durations and the ms-epoch `timestamp`), so it
+   compiles without depending on Next's internal paths.
+2. **`revalidatePath` is soft-tag based.** Next derives implicit tags from the
+   route path (`_N_T_/…/layout`, `_N_T_/<path>`, with `/` ↔ `/index` aliases) in
+   `dist/server/lib/implicit-tags.js` and passes them to `get` as `softTags`.
+   `revalidatePath` ultimately calls `updateTags([_N_T_<path>])`, so it flows
+   through the same shared-stamp path as any other tag. cacheplank treats
+   `softTags` identically to entry tags.
+3. **The cache key embeds a build ID.** `use-cache-wrapper.js` seeds the key with
+   `workStore.deploymentId || workStore.buildId`, so a new deploy does not reuse
+   old entries. No extra coupling is needed; `CACHEPLANK_PREFIX` remains as an
+   optional manual namespace.
+4. **`updateTags` `durations` is accepted but not persisted.** Next passes
+   `{ expire }` in seconds when `revalidateTag` uses a cacheLife profile. The
+   one-table model stores a single monotone stamp per tag, so a profile-driven
+   `revalidateTag` invalidates immediately rather than serving stale-while-
+   revalidate. This is safe (never serves stale data); it only forgoes a
+   background-refresh window.
+5. **The default handler is the reference.** Next's in-memory handler is
+   `dist/server/lib/cache-handlers/default.js`; cacheplank's expiry logic and its
+   negative-`expire` / `expire === 0` handling are mirrored from it deliberately.
+
+## License
+
+MIT.

package/dist/index.cjs

@@ -0,0 +1,234 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createCacheHandler: () => createCacheHandler,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var import_client = require("@libsql/client");
+var TAG_CHECK_TTL_MS = (() => {
+  const configured = Number(process.env.CACHEPLANK_STAMPS_TTL_MS);
+  return Number.isFinite(configured) && configured >= 0 ? configured : 3e3;
+})();
+var RETRY_BACKOFF_MS = 3e4;
+var DEFAULT_MAX_ENTRIES = 2e3;
+var now = () => Date.now();
+function createCacheHandler(options = {}) {
+  const url = options.url ?? process.env.CACHEPLANK_URL ?? process.env.BUNNY_DATABASE_URL;
+  const authToken = options.authToken ?? process.env.CACHEPLANK_AUTH_TOKEN ?? process.env.BUNNY_DATABASE_AUTH_TOKEN;
+  const prefix = options.prefix ?? process.env.CACHEPLANK_PREFIX ?? "";
+  const configuredMax = Number(process.env.CACHEPLANK_MAX_ENTRIES);
+  const maxEntries = options.maxEntries ?? (Number.isFinite(configuredMax) && configuredMax > 0 ? configuredMax : DEFAULT_MAX_ENTRIES);
+  const configuredTtl = Number(process.env.CACHEPLANK_STAMPS_TTL_MS);
+  const tagCheckTtlMs = options.stampsTtlMs ?? (Number.isFinite(configuredTtl) && configuredTtl >= 0 ? configuredTtl : TAG_CHECK_TTL_MS);
+  const warn = options.warn ?? ((message) => console.warn(`[cacheplank] ${message}`));
+  const entries = /* @__PURE__ */ new Map();
+  function remember(key, entry) {
+    entries.delete(key);
+    entries.set(key, entry);
+    while (entries.size > maxEntries) {
+      const oldest = entries.keys().next().value;
+      if (oldest === void 0) break;
+      entries.delete(oldest);
+    }
+  }
+  const stamps = /* @__PURE__ */ new Map();
+  let stampsSyncedAt = 0;
+  function observeStamp(tag, at) {
+    if (at > (stamps.get(tag) ?? 0)) stamps.set(tag, at);
+  }
+  let client;
+  let ready;
+  let retryAt = 0;
+  let warned = false;
+  function warnOnce(message) {
+    if (!warned) {
+      warned = true;
+      warn(message);
+    }
+  }
+  function ensureStore() {
+    if (ready) return ready;
+    if (!url) {
+      warnOnce("no CACHEPLANK_URL / BUNNY_DATABASE_URL set; tag stamps are process-local only");
+      return Promise.resolve(false);
+    }
+    if (now() < retryAt) return Promise.resolve(false);
+    ready = (async () => {
+      try {
+        const created = (0, import_client.createClient)({ url, authToken });
+        await created.execute(
+          "CREATE TABLE IF NOT EXISTS tag_stamps (tag TEXT PRIMARY KEY, revalidated_at INTEGER NOT NULL)"
+        );
+        client = created;
+        return true;
+      } catch (error) {
+        retryAt = now() + RETRY_BACKOFF_MS;
+        ready = void 0;
+        warnOnce(`tag-stamp store unavailable; continuing fail-open (${error.message})`);
+        return false;
+      }
+    })();
+    return ready;
+  }
+  async function syncStamps() {
+    if (now() - stampsSyncedAt < tagCheckTtlMs) return;
+    try {
+      if (!await ensureStore() || !client) return;
+      const result = await client.execute("SELECT tag, revalidated_at FROM tag_stamps");
+      for (const row of result.rows) {
+        const at = Number(row.revalidated_at);
+        if (Number.isFinite(at)) observeStamp(String(row.tag), at);
+      }
+    } catch (error) {
+      retryAt = now() + RETRY_BACKOFF_MS;
+      warnOnce(`tag-stamp read failed; serving local state (${error.message})`);
+    } finally {
+      stampsSyncedAt = now();
+    }
+  }
+  const pendingSets = /* @__PURE__ */ new Map();
+  return {
+    async get(cacheKey, softTags) {
+      const key = prefix + cacheKey;
+      const pending = pendingSets.get(key);
+      if (pending) await pending.catch(() => {
+      });
+      const entry = entries.get(key);
+      if (!entry) return void 0;
+      entries.delete(key);
+      entries.set(key, entry);
+      if (entry.expire < 0) {
+        entries.delete(key);
+        return void 0;
+      }
+      const age = now() - entry.timestamp;
+      const maxAgeSeconds = process.env.__NEXT_DEV_SERVER ? Math.max(entry.expire, 300) : entry.revalidate;
+      if (!(age < maxAgeSeconds * 1e3) || entry.expire >= 0 && !(age < entry.expire * 1e3)) {
+        return void 0;
+      }
+      await syncStamps();
+      for (const tag of entry.tags) {
+        if ((stamps.get(tag) ?? 0) >= entry.timestamp) return void 0;
+      }
+      for (const tag of softTags) {
+        if ((stamps.get(tag) ?? 0) >= entry.timestamp) return void 0;
+      }
+      const bytes = entry.bytes;
+      return {
+        value: new ReadableStream({
+          start(controller) {
+            controller.enqueue(bytes);
+            controller.close();
+          }
+        }),
+        tags: entry.tags,
+        stale: entry.stale,
+        timestamp: entry.timestamp,
+        expire: entry.expire,
+        revalidate: entry.revalidate
+      };
+    },
+    async set(cacheKey, pendingEntry) {
+      const key = prefix + cacheKey;
+      let release = () => {
+      };
+      const gate = new Promise((resolve) => {
+        release = resolve;
+      });
+      pendingSets.set(key, gate);
+      try {
+        const entry = await pendingEntry;
+        if (entry.expire === 0 && !process.env.__NEXT_DEV_SERVER) return;
+        const reader = entry.value.getReader();
+        const chunks = [];
+        let size = 0;
+        try {
+          for (; ; ) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            if (value) {
+              chunks.push(value);
+              size += value.byteLength;
+            }
+          }
+        } finally {
+          reader.releaseLock();
+        }
+        const bytes = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) {
+          bytes.set(chunk, offset);
+          offset += chunk.byteLength;
+        }
+        remember(key, {
+          bytes,
+          tags: entry.tags ?? [],
+          timestamp: entry.timestamp,
+          expire: entry.expire,
+          revalidate: entry.revalidate,
+          stale: entry.stale
+        });
+      } catch (error) {
+        warnOnce(`failed to buffer a cache entry (${error.message})`);
+      } finally {
+        release();
+        pendingSets.delete(key);
+      }
+    },
+    async refreshTags() {
+      await syncStamps();
+    },
+    async getExpiration(tags) {
+      await syncStamps();
+      let max = 0;
+      for (const tag of tags) {
+        const at = stamps.get(tag) ?? 0;
+        if (at > max) max = at;
+      }
+      return max;
+    },
+    async updateTags(tags, _durations) {
+      const at = now();
+      for (const tag of tags) observeStamp(tag, at);
+      if (tags.length === 0) return;
+      try {
+        if (!await ensureStore() || !client) return;
+        await client.batch(
+          tags.map((tag) => ({
+            sql: "INSERT INTO tag_stamps(tag, revalidated_at) VALUES (?, ?) ON CONFLICT(tag) DO UPDATE SET revalidated_at = MAX(revalidated_at, excluded.revalidated_at)",
+            args: [tag, at]
+          })),
+          "write"
+        );
+      } catch (error) {
+        warnOnce(`tag-stamp write failed; local state kept (${error.message})`);
+      }
+    }
+  };
+}
+var index_default = createCacheHandler();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createCacheHandler
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": ["/**\n * cacheplank \u2014 \"the shared plank your pods walk across.\"\n *\n * A single-file, tag-based distributed cache handler for Next.js 16's\n * `cacheHandlers` API, backed by libSQL.\n *\n * Cache *entries* stay local to each process (an in-memory LRU). Only tag\n * *invalidation* is shared, through one tiny libSQL table (`tag_stamps`). Any\n * number of pods/regions converge because every `get` compares the entry's\n * timestamp against the shared invalidation stamps.\n *\n * Ground truth for the contract below: the installed `next@16.3.8` package \u2014\n * `dist/server/lib/cache-handlers/{types,default}.js`,\n * `dist/server/lib/incremental-cache/tags-manifest.external.js`, and\n * `dist/server/use-cache/{use-cache-wrapper,handlers}.js`. See README\n * \"Compatibility notes\".\n */\nimport { createClient, type Client } from '@libsql/client';\n\n/* ------------------------------------------------------------------------- *\n * Next 16 cache-handler contract.                                            *\n * Hand-written: Next does not export these types publicly (README note #1).  *\n * ------------------------------------------------------------------------- */\n\n/** A timestamp in milliseconds elapsed since the epoch. */\nexport type Timestamp = number;\n\n/** Mirrors `CacheEntry` in next@16.3.8. Durations are in seconds. */\nexport interface CacheEntry {\n  /** The stored value. May be partially written / error while pending. */\n  value: ReadableStream<Uint8Array>;\n  /** Tags configured for the entry, excluding soft tags. */\n  tags: string[];\n  /** Client hint only; not used to compute expiration. [seconds] */\n  stale: number;\n  /** When the entry was created. [ms epoch] */\n  timestamp: Timestamp;\n  /** How long the entry may be used. [seconds] */\n  expire: number;\n  /** How long until the entry should be revalidated. [seconds] */\n  revalidate: number;\n}\n\n/** Mirrors `CacheHandler` in next@16.3.8. */\nexport interface CacheHandler {\n  get(cacheKey: string, softTags: string[]): Promise<CacheEntry | undefined>;\n  set(cacheKey: string, pendingEntry: Promise<CacheEntry>): Promise<void>;\n  refreshTags(): Promise<void>;\n  getExpiration(tags: string[]): Promise<Timestamp>;\n  updateTags(tags: string[], durations?: { expire?: number }): Promise<void>;\n}\n\nexport interface CacheplankOptions {\n  /** libSQL URL. Defaults to `CACHEPLANK_URL`, then `BUNNY_DATABASE_URL`. */\n  url?: string;\n  /** libSQL auth token. Defaults to `CACHEPLANK_AUTH_TOKEN`, then `BUNNY_DATABASE_AUTH_TOKEN`. */\n  authToken?: string;\n  /** Key namespace. Defaults to `CACHEPLANK_PREFIX` (may be empty). */\n  prefix?: string;\n  /** Max local entries. Defaults to `CACHEPLANK_MAX_ENTRIES`, else 2000. */\n  maxEntries?: number;\n  /**\n   * How long an in-process tag-stamp memo may be reused before the shared table\n   * is re-read. This bounds how stale a pod's view of invalidation can get.\n   * Defaults to `CACHEPLANK_STAMPS_TTL_MS`, else 3000. [ms]\n   */\n  stampsTtlMs?: number;\n  /** Sink for the single fail-open warning. Defaults to `console.warn`. */\n  warn?: (message: string) => void;\n}\n\ninterface StoredEntry {\n  bytes: Uint8Array;\n  tags: string[];\n  timestamp: number;\n  expire: number;\n  revalidate: number;\n  stale: number;\n}\n\n/**\n * Soft TTL for the in-process tag-stamp memo. [ms]. Defaults to 3000; override\n * with `CACHEPLANK_STAMPS_TTL_MS` (e.g. `0` to read the shared table on every\n * `get`, which the cross-process test relies on).\n */\nconst TAG_CHECK_TTL_MS = (() => {\n  const configured = Number(process.env.CACHEPLANK_STAMPS_TTL_MS);\n  return Number.isFinite(configured) && configured >= 0 ? configured : 3000;\n})();\n/** Fail-open backoff after a stamp-store error, so we don't hammer a dead DB. [ms] */\nconst RETRY_BACKOFF_MS = 30_000;\nconst DEFAULT_MAX_ENTRIES = 2000;\n\nconst now = (): number => Date.now();\n\n/**\n * Create a cache handler. The package's `default` export is one of these,\n * configured from the environment.\n */\nexport function createCacheHandler(options: CacheplankOptions = {}): CacheHandler {\n  const url = options.url ?? process.env.CACHEPLANK_URL ?? process.env.BUNNY_DATABASE_URL;\n  const authToken =\n    options.authToken ?? process.env.CACHEPLANK_AUTH_TOKEN ?? process.env.BUNNY_DATABASE_AUTH_TOKEN;\n  const prefix = options.prefix ?? process.env.CACHEPLANK_PREFIX ?? '';\n  const configuredMax = Number(process.env.CACHEPLANK_MAX_ENTRIES);\n  const maxEntries =\n    options.maxEntries ??\n    (Number.isFinite(configuredMax) && configuredMax > 0 ? configuredMax : DEFAULT_MAX_ENTRIES);\n  const configuredTtl = Number(process.env.CACHEPLANK_STAMPS_TTL_MS);\n  const tagCheckTtlMs =\n    options.stampsTtlMs ??\n    (Number.isFinite(configuredTtl) && configuredTtl >= 0 ? configuredTtl : TAG_CHECK_TTL_MS);\n  const warn = options.warn ?? ((message: string) => console.warn(`[cacheplank] ${message}`));\n\n  // ---- local entry store, LRU via Map insertion order ----\n  const entries = new Map<string, StoredEntry>();\n  function remember(key: string, entry: StoredEntry): void {\n    entries.delete(key);\n    entries.set(key, entry);\n    while (entries.size > maxEntries) {\n      const oldest = entries.keys().next().value;\n      if (oldest === undefined) break;\n      entries.delete(oldest);\n    }\n  }\n\n  // ---- shared tag stamps (in-process memo; monotonically increasing) ----\n  const stamps = new Map<string, number>();\n  let stampsSyncedAt = 0;\n  function observeStamp(tag: string, at: number): void {\n    if (at > (stamps.get(tag) ?? 0)) stamps.set(tag, at);\n  }\n\n  // ---- libSQL client: lazy, memoized, and never allowed to throw ----\n  let client: Client | undefined;\n  let ready: Promise<boolean> | undefined;\n  let retryAt = 0;\n  let warned = false;\n  function warnOnce(message: string): void {\n    if (!warned) {\n      warned = true;\n      warn(message);\n    }\n  }\n\n  function ensureStore(): Promise<boolean> {\n    if (ready) return ready;\n    if (!url) {\n      warnOnce('no CACHEPLANK_URL / BUNNY_DATABASE_URL set; tag stamps are process-local only');\n      return Promise.resolve(false);\n    }\n    if (now() < retryAt) return Promise.resolve(false);\n    ready = (async () => {\n      try {\n        const created = createClient({ url, authToken });\n        await created.execute(\n          'CREATE TABLE IF NOT EXISTS tag_stamps (tag TEXT PRIMARY KEY, revalidated_at INTEGER NOT NULL)',\n        );\n        client = created;\n        return true;\n      } catch (error) {\n        retryAt = now() + RETRY_BACKOFF_MS;\n        ready = undefined;\n        warnOnce(`tag-stamp store unavailable; continuing fail-open (${(error as Error).message})`);\n        return false;\n      }\n    })();\n    return ready;\n  }\n\n  async function syncStamps(): Promise<void> {\n    if (now() - stampsSyncedAt < tagCheckTtlMs) return;\n    try {\n      if (!(await ensureStore()) || !client) return;\n      const result = await client.execute('SELECT tag, revalidated_at FROM tag_stamps');\n      for (const row of result.rows) {\n        const at = Number(row.revalidated_at);\n        if (Number.isFinite(at)) observeStamp(String(row.tag), at);\n      }\n    } catch (error) {\n      retryAt = now() + RETRY_BACKOFF_MS;\n      warnOnce(`tag-stamp read failed; serving local state (${(error as Error).message})`);\n    } finally {\n      stampsSyncedAt = now();\n    }\n  }\n\n  // In-flight `set` calls, so a `get` racing a `set` waits instead of missing.\n  const pendingSets = new Map<string, Promise<void>>();\n\n  return {\n    async get(cacheKey, softTags) {\n      const key = prefix + cacheKey;\n      const pending = pendingSets.get(key);\n      if (pending) await pending.catch(() => {});\n\n      const entry = entries.get(key);\n      if (!entry) return undefined;\n\n      // Touch for LRU recency.\n      entries.delete(key);\n      entries.set(key, entry);\n\n      // A negative `expire` is the tiered-cache eviction sentinel Next's tiered\n      // handler uses in dev (the interface has no per-key delete); treat it as\n      // missing, independently of the retention bounds below.\n      if (entry.expire < 0) {\n        entries.delete(key);\n        return undefined;\n      }\n      // Mirror Next's effective expiry. `set` already dropped `expire: 0` in\n      // production. The wrapper discards an entry once\n      // `currentTime > timestamp + expire*1000` (always) or past `revalidate`\n      // during static generation; the default handler additionally drops past\n      // `revalidate` in production (SWR background revalidation then takes\n      // over). Dropping at either bound here matches what Next would reject\n      // anyway and never serves a value the wrapper throws away. In dev the\n      // default handler retains short-`expire` entries for at least\n      // MIN_PRERENDERABLE_EXPIRE (300s) so reloads hit; mirror that. A\n      // `revalidate <= 0` (including the stale-while-revalidate `-1`) drops.\n      const age = now() - entry.timestamp;\n      const maxAgeSeconds = process.env.__NEXT_DEV_SERVER\n        ? Math.max(entry.expire, 300)\n        : entry.revalidate;\n      if (!(age < maxAgeSeconds * 1000) || (entry.expire >= 0 && !(age < entry.expire * 1000))) {\n        return undefined;\n      }\n\n      // Shared invalidation: any tag (own or route soft tag) stamped at or\n      // after this entry was written means another pod revalidated it \u2014 miss,\n      // so Next regenerates. `>=` mirrors Next's wrapper-side discard\n      // (`entry.timestamp <= implicitTagsExpiration`): for an entry created in\n      // the same millisecond as a stamp the ordering is unknowable, so we\n      // conservatively regenerate.\n      await syncStamps();\n      for (const tag of entry.tags) {\n        if ((stamps.get(tag) ?? 0) >= entry.timestamp) return undefined;\n      }\n      for (const tag of softTags) {\n        if ((stamps.get(tag) ?? 0) >= entry.timestamp) return undefined;\n      }\n\n      const bytes = entry.bytes;\n      return {\n        value: new ReadableStream<Uint8Array>({\n          start(controller) {\n            controller.enqueue(bytes);\n            controller.close();\n          },\n        }),\n        tags: entry.tags,\n        stale: entry.stale,\n        timestamp: entry.timestamp,\n        expire: entry.expire,\n        revalidate: entry.revalidate,\n      };\n    },\n\n    async set(cacheKey, pendingEntry) {\n      const key = prefix + cacheKey;\n      let release: () => void = () => {};\n      const gate = new Promise<void>((resolve) => {\n        release = resolve;\n      });\n      pendingSets.set(key, gate);\n      try {\n        const entry = await pendingEntry;\n        // In production an `expire: 0` entry is dynamic and never served back.\n        if (entry.expire === 0 && !process.env.__NEXT_DEV_SERVER) return;\n\n        const reader = entry.value.getReader();\n        const chunks: Uint8Array[] = [];\n        let size = 0;\n        try {\n          for (;;) {\n            const { done, value } = await reader.read();\n            if (done) break;\n            if (value) {\n              chunks.push(value);\n              size += value.byteLength;\n            }\n          }\n        } finally {\n          reader.releaseLock();\n        }\n        const bytes = new Uint8Array(size);\n        let offset = 0;\n        for (const chunk of chunks) {\n          bytes.set(chunk, offset);\n          offset += chunk.byteLength;\n        }\n\n        remember(key, {\n          bytes,\n          tags: entry.tags ?? [],\n          timestamp: entry.timestamp,\n          expire: entry.expire,\n          revalidate: entry.revalidate,\n          stale: entry.stale,\n        });\n      } catch (error) {\n        warnOnce(`failed to buffer a cache entry (${(error as Error).message})`);\n      } finally {\n        release();\n        pendingSets.delete(key);\n      }\n    },\n\n    async refreshTags() {\n      await syncStamps();\n    },\n\n    async getExpiration(tags) {\n      await syncStamps();\n      let max = 0;\n      for (const tag of tags) {\n        const at = stamps.get(tag) ?? 0;\n        if (at > max) max = at;\n      }\n      return max;\n    },\n\n    async updateTags(tags, _durations) {\n      // `durations.expire` is accepted but not persisted: the shared table holds\n      // a single monotone stamp per tag. A profile'd `revalidateTag` therefore\n      // invalidates immediately rather than stale-while-revalidate \u2014 safe, and\n      // faithful to the one-table model. See README compatibility note #4.\n      const at = now();\n      for (const tag of tags) observeStamp(tag, at);\n      if (tags.length === 0) return;\n      try {\n        if (!(await ensureStore()) || !client) return;\n        await client.batch(\n          tags.map((tag) => ({\n            sql:\n              'INSERT INTO tag_stamps(tag, revalidated_at) VALUES (?, ?) ' +\n              'ON CONFLICT(tag) DO UPDATE SET revalidated_at = MAX(revalidated_at, excluded.revalidated_at)',\n            args: [tag, at],\n          })),\n          'write',\n        );\n      } catch (error) {\n        warnOnce(`tag-stamp write failed; local state kept (${(error as Error).message})`);\n      }\n    },\n  };\n}\n\n/**\n * Default singleton. Next loads the module via `interopDefault`, so this\n * `default` export is the handler Next uses.\n */\nexport default createCacheHandler();\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+/** A timestamp in milliseconds elapsed since the epoch. */
+export type Timestamp = number;
+/** Mirrors `CacheEntry` in next@16.3.8. Durations are in seconds. */
+export interface CacheEntry {
+    /** The stored value. May be partially written / error while pending. */
+    value: ReadableStream<Uint8Array>;
+    /** Tags configured for the entry, excluding soft tags. */
+    tags: string[];
+    /** Client hint only; not used to compute expiration. [seconds] */
+    stale: number;
+    /** When the entry was created. [ms epoch] */
+    timestamp: Timestamp;
+    /** How long the entry may be used. [seconds] */
+    expire: number;
+    /** How long until the entry should be revalidated. [seconds] */
+    revalidate: number;
+}
+/** Mirrors `CacheHandler` in next@16.3.8. */
+export interface CacheHandler {
+    get(cacheKey: string, softTags: string[]): Promise<CacheEntry | undefined>;
+    set(cacheKey: string, pendingEntry: Promise<CacheEntry>): Promise<void>;
+    refreshTags(): Promise<void>;
+    getExpiration(tags: string[]): Promise<Timestamp>;
+    updateTags(tags: string[], durations?: {
+        expire?: number;
+    }): Promise<void>;
+}
+export interface CacheplankOptions {
+    /** libSQL URL. Defaults to `CACHEPLANK_URL`, then `BUNNY_DATABASE_URL`. */
+    url?: string;
+    /** libSQL auth token. Defaults to `CACHEPLANK_AUTH_TOKEN`, then `BUNNY_DATABASE_AUTH_TOKEN`. */
+    authToken?: string;
+    /** Key namespace. Defaults to `CACHEPLANK_PREFIX` (may be empty). */
+    prefix?: string;
+    /** Max local entries. Defaults to `CACHEPLANK_MAX_ENTRIES`, else 2000. */
+    maxEntries?: number;
+    /**
+     * How long an in-process tag-stamp memo may be reused before the shared table
+     * is re-read. This bounds how stale a pod's view of invalidation can get.
+     * Defaults to `CACHEPLANK_STAMPS_TTL_MS`, else 3000. [ms]
+     */
+    stampsTtlMs?: number;
+    /** Sink for the single fail-open warning. Defaults to `console.warn`. */
+    warn?: (message: string) => void;
+}
+/**
+ * Create a cache handler. The package's `default` export is one of these,
+ * configured from the environment.
+ */
+export declare function createCacheHandler(options?: CacheplankOptions): CacheHandler;
+/**
+ * Default singleton. Next loads the module via `interopDefault`, so this
+ * `default` export is the handler Next uses.
+ */
+declare const _default: CacheHandler;
+export default _default;

package/dist/index.mjs

@@ -0,0 +1,209 @@
+// src/index.ts
+import { createClient } from "@libsql/client";
+var TAG_CHECK_TTL_MS = (() => {
+  const configured = Number(process.env.CACHEPLANK_STAMPS_TTL_MS);
+  return Number.isFinite(configured) && configured >= 0 ? configured : 3e3;
+})();
+var RETRY_BACKOFF_MS = 3e4;
+var DEFAULT_MAX_ENTRIES = 2e3;
+var now = () => Date.now();
+function createCacheHandler(options = {}) {
+  const url = options.url ?? process.env.CACHEPLANK_URL ?? process.env.BUNNY_DATABASE_URL;
+  const authToken = options.authToken ?? process.env.CACHEPLANK_AUTH_TOKEN ?? process.env.BUNNY_DATABASE_AUTH_TOKEN;
+  const prefix = options.prefix ?? process.env.CACHEPLANK_PREFIX ?? "";
+  const configuredMax = Number(process.env.CACHEPLANK_MAX_ENTRIES);
+  const maxEntries = options.maxEntries ?? (Number.isFinite(configuredMax) && configuredMax > 0 ? configuredMax : DEFAULT_MAX_ENTRIES);
+  const configuredTtl = Number(process.env.CACHEPLANK_STAMPS_TTL_MS);
+  const tagCheckTtlMs = options.stampsTtlMs ?? (Number.isFinite(configuredTtl) && configuredTtl >= 0 ? configuredTtl : TAG_CHECK_TTL_MS);
+  const warn = options.warn ?? ((message) => console.warn(`[cacheplank] ${message}`));
+  const entries = /* @__PURE__ */ new Map();
+  function remember(key, entry) {
+    entries.delete(key);
+    entries.set(key, entry);
+    while (entries.size > maxEntries) {
+      const oldest = entries.keys().next().value;
+      if (oldest === void 0) break;
+      entries.delete(oldest);
+    }
+  }
+  const stamps = /* @__PURE__ */ new Map();
+  let stampsSyncedAt = 0;
+  function observeStamp(tag, at) {
+    if (at > (stamps.get(tag) ?? 0)) stamps.set(tag, at);
+  }
+  let client;
+  let ready;
+  let retryAt = 0;
+  let warned = false;
+  function warnOnce(message) {
+    if (!warned) {
+      warned = true;
+      warn(message);
+    }
+  }
+  function ensureStore() {
+    if (ready) return ready;
+    if (!url) {
+      warnOnce("no CACHEPLANK_URL / BUNNY_DATABASE_URL set; tag stamps are process-local only");
+      return Promise.resolve(false);
+    }
+    if (now() < retryAt) return Promise.resolve(false);
+    ready = (async () => {
+      try {
+        const created = createClient({ url, authToken });
+        await created.execute(
+          "CREATE TABLE IF NOT EXISTS tag_stamps (tag TEXT PRIMARY KEY, revalidated_at INTEGER NOT NULL)"
+        );
+        client = created;
+        return true;
+      } catch (error) {
+        retryAt = now() + RETRY_BACKOFF_MS;
+        ready = void 0;
+        warnOnce(`tag-stamp store unavailable; continuing fail-open (${error.message})`);
+        return false;
+      }
+    })();
+    return ready;
+  }
+  async function syncStamps() {
+    if (now() - stampsSyncedAt < tagCheckTtlMs) return;
+    try {
+      if (!await ensureStore() || !client) return;
+      const result = await client.execute("SELECT tag, revalidated_at FROM tag_stamps");
+      for (const row of result.rows) {
+        const at = Number(row.revalidated_at);
+        if (Number.isFinite(at)) observeStamp(String(row.tag), at);
+      }
+    } catch (error) {
+      retryAt = now() + RETRY_BACKOFF_MS;
+      warnOnce(`tag-stamp read failed; serving local state (${error.message})`);
+    } finally {
+      stampsSyncedAt = now();
+    }
+  }
+  const pendingSets = /* @__PURE__ */ new Map();
+  return {
+    async get(cacheKey, softTags) {
+      const key = prefix + cacheKey;
+      const pending = pendingSets.get(key);
+      if (pending) await pending.catch(() => {
+      });
+      const entry = entries.get(key);
+      if (!entry) return void 0;
+      entries.delete(key);
+      entries.set(key, entry);
+      if (entry.expire < 0) {
+        entries.delete(key);
+        return void 0;
+      }
+      const age = now() - entry.timestamp;
+      const maxAgeSeconds = process.env.__NEXT_DEV_SERVER ? Math.max(entry.expire, 300) : entry.revalidate;
+      if (!(age < maxAgeSeconds * 1e3) || entry.expire >= 0 && !(age < entry.expire * 1e3)) {
+        return void 0;
+      }
+      await syncStamps();
+      for (const tag of entry.tags) {
+        if ((stamps.get(tag) ?? 0) >= entry.timestamp) return void 0;
+      }
+      for (const tag of softTags) {
+        if ((stamps.get(tag) ?? 0) >= entry.timestamp) return void 0;
+      }
+      const bytes = entry.bytes;
+      return {
+        value: new ReadableStream({
+          start(controller) {
+            controller.enqueue(bytes);
+            controller.close();
+          }
+        }),
+        tags: entry.tags,
+        stale: entry.stale,
+        timestamp: entry.timestamp,
+        expire: entry.expire,
+        revalidate: entry.revalidate
+      };
+    },
+    async set(cacheKey, pendingEntry) {
+      const key = prefix + cacheKey;
+      let release = () => {
+      };
+      const gate = new Promise((resolve) => {
+        release = resolve;
+      });
+      pendingSets.set(key, gate);
+      try {
+        const entry = await pendingEntry;
+        if (entry.expire === 0 && !process.env.__NEXT_DEV_SERVER) return;
+        const reader = entry.value.getReader();
+        const chunks = [];
+        let size = 0;
+        try {
+          for (; ; ) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            if (value) {
+              chunks.push(value);
+              size += value.byteLength;
+            }
+          }
+        } finally {
+          reader.releaseLock();
+        }
+        const bytes = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) {
+          bytes.set(chunk, offset);
+          offset += chunk.byteLength;
+        }
+        remember(key, {
+          bytes,
+          tags: entry.tags ?? [],
+          timestamp: entry.timestamp,
+          expire: entry.expire,
+          revalidate: entry.revalidate,
+          stale: entry.stale
+        });
+      } catch (error) {
+        warnOnce(`failed to buffer a cache entry (${error.message})`);
+      } finally {
+        release();
+        pendingSets.delete(key);
+      }
+    },
+    async refreshTags() {
+      await syncStamps();
+    },
+    async getExpiration(tags) {
+      await syncStamps();
+      let max = 0;
+      for (const tag of tags) {
+        const at = stamps.get(tag) ?? 0;
+        if (at > max) max = at;
+      }
+      return max;
+    },
+    async updateTags(tags, _durations) {
+      const at = now();
+      for (const tag of tags) observeStamp(tag, at);
+      if (tags.length === 0) return;
+      try {
+        if (!await ensureStore() || !client) return;
+        await client.batch(
+          tags.map((tag) => ({
+            sql: "INSERT INTO tag_stamps(tag, revalidated_at) VALUES (?, ?) ON CONFLICT(tag) DO UPDATE SET revalidated_at = MAX(revalidated_at, excluded.revalidated_at)",
+            args: [tag, at]
+          })),
+          "write"
+        );
+      } catch (error) {
+        warnOnce(`tag-stamp write failed; local state kept (${error.message})`);
+      }
+    }
+  };
+}
+var index_default = createCacheHandler();
+export {
+  createCacheHandler,
+  index_default as default
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": ["/**\n * cacheplank \u2014 \"the shared plank your pods walk across.\"\n *\n * A single-file, tag-based distributed cache handler for Next.js 16's\n * `cacheHandlers` API, backed by libSQL.\n *\n * Cache *entries* stay local to each process (an in-memory LRU). Only tag\n * *invalidation* is shared, through one tiny libSQL table (`tag_stamps`). Any\n * number of pods/regions converge because every `get` compares the entry's\n * timestamp against the shared invalidation stamps.\n *\n * Ground truth for the contract below: the installed `next@16.3.8` package \u2014\n * `dist/server/lib/cache-handlers/{types,default}.js`,\n * `dist/server/lib/incremental-cache/tags-manifest.external.js`, and\n * `dist/server/use-cache/{use-cache-wrapper,handlers}.js`. See README\n * \"Compatibility notes\".\n */\nimport { createClient, type Client } from '@libsql/client';\n\n/* ------------------------------------------------------------------------- *\n * Next 16 cache-handler contract.                                            *\n * Hand-written: Next does not export these types publicly (README note #1).  *\n * ------------------------------------------------------------------------- */\n\n/** A timestamp in milliseconds elapsed since the epoch. */\nexport type Timestamp = number;\n\n/** Mirrors `CacheEntry` in next@16.3.8. Durations are in seconds. */\nexport interface CacheEntry {\n  /** The stored value. May be partially written / error while pending. */\n  value: ReadableStream<Uint8Array>;\n  /** Tags configured for the entry, excluding soft tags. */\n  tags: string[];\n  /** Client hint only; not used to compute expiration. [seconds] */\n  stale: number;\n  /** When the entry was created. [ms epoch] */\n  timestamp: Timestamp;\n  /** How long the entry may be used. [seconds] */\n  expire: number;\n  /** How long until the entry should be revalidated. [seconds] */\n  revalidate: number;\n}\n\n/** Mirrors `CacheHandler` in next@16.3.8. */\nexport interface CacheHandler {\n  get(cacheKey: string, softTags: string[]): Promise<CacheEntry | undefined>;\n  set(cacheKey: string, pendingEntry: Promise<CacheEntry>): Promise<void>;\n  refreshTags(): Promise<void>;\n  getExpiration(tags: string[]): Promise<Timestamp>;\n  updateTags(tags: string[], durations?: { expire?: number }): Promise<void>;\n}\n\nexport interface CacheplankOptions {\n  /** libSQL URL. Defaults to `CACHEPLANK_URL`, then `BUNNY_DATABASE_URL`. */\n  url?: string;\n  /** libSQL auth token. Defaults to `CACHEPLANK_AUTH_TOKEN`, then `BUNNY_DATABASE_AUTH_TOKEN`. */\n  authToken?: string;\n  /** Key namespace. Defaults to `CACHEPLANK_PREFIX` (may be empty). */\n  prefix?: string;\n  /** Max local entries. Defaults to `CACHEPLANK_MAX_ENTRIES`, else 2000. */\n  maxEntries?: number;\n  /**\n   * How long an in-process tag-stamp memo may be reused before the shared table\n   * is re-read. This bounds how stale a pod's view of invalidation can get.\n   * Defaults to `CACHEPLANK_STAMPS_TTL_MS`, else 3000. [ms]\n   */\n  stampsTtlMs?: number;\n  /** Sink for the single fail-open warning. Defaults to `console.warn`. */\n  warn?: (message: string) => void;\n}\n\ninterface StoredEntry {\n  bytes: Uint8Array;\n  tags: string[];\n  timestamp: number;\n  expire: number;\n  revalidate: number;\n  stale: number;\n}\n\n/**\n * Soft TTL for the in-process tag-stamp memo. [ms]. Defaults to 3000; override\n * with `CACHEPLANK_STAMPS_TTL_MS` (e.g. `0` to read the shared table on every\n * `get`, which the cross-process test relies on).\n */\nconst TAG_CHECK_TTL_MS = (() => {\n  const configured = Number(process.env.CACHEPLANK_STAMPS_TTL_MS);\n  return Number.isFinite(configured) && configured >= 0 ? configured : 3000;\n})();\n/** Fail-open backoff after a stamp-store error, so we don't hammer a dead DB. [ms] */\nconst RETRY_BACKOFF_MS = 30_000;\nconst DEFAULT_MAX_ENTRIES = 2000;\n\nconst now = (): number => Date.now();\n\n/**\n * Create a cache handler. The package's `default` export is one of these,\n * configured from the environment.\n */\nexport function createCacheHandler(options: CacheplankOptions = {}): CacheHandler {\n  const url = options.url ?? process.env.CACHEPLANK_URL ?? process.env.BUNNY_DATABASE_URL;\n  const authToken =\n    options.authToken ?? process.env.CACHEPLANK_AUTH_TOKEN ?? process.env.BUNNY_DATABASE_AUTH_TOKEN;\n  const prefix = options.prefix ?? process.env.CACHEPLANK_PREFIX ?? '';\n  const configuredMax = Number(process.env.CACHEPLANK_MAX_ENTRIES);\n  const maxEntries =\n    options.maxEntries ??\n    (Number.isFinite(configuredMax) && configuredMax > 0 ? configuredMax : DEFAULT_MAX_ENTRIES);\n  const configuredTtl = Number(process.env.CACHEPLANK_STAMPS_TTL_MS);\n  const tagCheckTtlMs =\n    options.stampsTtlMs ??\n    (Number.isFinite(configuredTtl) && configuredTtl >= 0 ? configuredTtl : TAG_CHECK_TTL_MS);\n  const warn = options.warn ?? ((message: string) => console.warn(`[cacheplank] ${message}`));\n\n  // ---- local entry store, LRU via Map insertion order ----\n  const entries = new Map<string, StoredEntry>();\n  function remember(key: string, entry: StoredEntry): void {\n    entries.delete(key);\n    entries.set(key, entry);\n    while (entries.size > maxEntries) {\n      const oldest = entries.keys().next().value;\n      if (oldest === undefined) break;\n      entries.delete(oldest);\n    }\n  }\n\n  // ---- shared tag stamps (in-process memo; monotonically increasing) ----\n  const stamps = new Map<string, number>();\n  let stampsSyncedAt = 0;\n  function observeStamp(tag: string, at: number): void {\n    if (at > (stamps.get(tag) ?? 0)) stamps.set(tag, at);\n  }\n\n  // ---- libSQL client: lazy, memoized, and never allowed to throw ----\n  let client: Client | undefined;\n  let ready: Promise<boolean> | undefined;\n  let retryAt = 0;\n  let warned = false;\n  function warnOnce(message: string): void {\n    if (!warned) {\n      warned = true;\n      warn(message);\n    }\n  }\n\n  function ensureStore(): Promise<boolean> {\n    if (ready) return ready;\n    if (!url) {\n      warnOnce('no CACHEPLANK_URL / BUNNY_DATABASE_URL set; tag stamps are process-local only');\n      return Promise.resolve(false);\n    }\n    if (now() < retryAt) return Promise.resolve(false);\n    ready = (async () => {\n      try {\n        const created = createClient({ url, authToken });\n        await created.execute(\n          'CREATE TABLE IF NOT EXISTS tag_stamps (tag TEXT PRIMARY KEY, revalidated_at INTEGER NOT NULL)',\n        );\n        client = created;\n        return true;\n      } catch (error) {\n        retryAt = now() + RETRY_BACKOFF_MS;\n        ready = undefined;\n        warnOnce(`tag-stamp store unavailable; continuing fail-open (${(error as Error).message})`);\n        return false;\n      }\n    })();\n    return ready;\n  }\n\n  async function syncStamps(): Promise<void> {\n    if (now() - stampsSyncedAt < tagCheckTtlMs) return;\n    try {\n      if (!(await ensureStore()) || !client) return;\n      const result = await client.execute('SELECT tag, revalidated_at FROM tag_stamps');\n      for (const row of result.rows) {\n        const at = Number(row.revalidated_at);\n        if (Number.isFinite(at)) observeStamp(String(row.tag), at);\n      }\n    } catch (error) {\n      retryAt = now() + RETRY_BACKOFF_MS;\n      warnOnce(`tag-stamp read failed; serving local state (${(error as Error).message})`);\n    } finally {\n      stampsSyncedAt = now();\n    }\n  }\n\n  // In-flight `set` calls, so a `get` racing a `set` waits instead of missing.\n  const pendingSets = new Map<string, Promise<void>>();\n\n  return {\n    async get(cacheKey, softTags) {\n      const key = prefix + cacheKey;\n      const pending = pendingSets.get(key);\n      if (pending) await pending.catch(() => {});\n\n      const entry = entries.get(key);\n      if (!entry) return undefined;\n\n      // Touch for LRU recency.\n      entries.delete(key);\n      entries.set(key, entry);\n\n      // A negative `expire` is the tiered-cache eviction sentinel Next's tiered\n      // handler uses in dev (the interface has no per-key delete); treat it as\n      // missing, independently of the retention bounds below.\n      if (entry.expire < 0) {\n        entries.delete(key);\n        return undefined;\n      }\n      // Mirror Next's effective expiry. `set` already dropped `expire: 0` in\n      // production. The wrapper discards an entry once\n      // `currentTime > timestamp + expire*1000` (always) or past `revalidate`\n      // during static generation; the default handler additionally drops past\n      // `revalidate` in production (SWR background revalidation then takes\n      // over). Dropping at either bound here matches what Next would reject\n      // anyway and never serves a value the wrapper throws away. In dev the\n      // default handler retains short-`expire` entries for at least\n      // MIN_PRERENDERABLE_EXPIRE (300s) so reloads hit; mirror that. A\n      // `revalidate <= 0` (including the stale-while-revalidate `-1`) drops.\n      const age = now() - entry.timestamp;\n      const maxAgeSeconds = process.env.__NEXT_DEV_SERVER\n        ? Math.max(entry.expire, 300)\n        : entry.revalidate;\n      if (!(age < maxAgeSeconds * 1000) || (entry.expire >= 0 && !(age < entry.expire * 1000))) {\n        return undefined;\n      }\n\n      // Shared invalidation: any tag (own or route soft tag) stamped at or\n      // after this entry was written means another pod revalidated it \u2014 miss,\n      // so Next regenerates. `>=` mirrors Next's wrapper-side discard\n      // (`entry.timestamp <= implicitTagsExpiration`): for an entry created in\n      // the same millisecond as a stamp the ordering is unknowable, so we\n      // conservatively regenerate.\n      await syncStamps();\n      for (const tag of entry.tags) {\n        if ((stamps.get(tag) ?? 0) >= entry.timestamp) return undefined;\n      }\n      for (const tag of softTags) {\n        if ((stamps.get(tag) ?? 0) >= entry.timestamp) return undefined;\n      }\n\n      const bytes = entry.bytes;\n      return {\n        value: new ReadableStream<Uint8Array>({\n          start(controller) {\n            controller.enqueue(bytes);\n            controller.close();\n          },\n        }),\n        tags: entry.tags,\n        stale: entry.stale,\n        timestamp: entry.timestamp,\n        expire: entry.expire,\n        revalidate: entry.revalidate,\n      };\n    },\n\n    async set(cacheKey, pendingEntry) {\n      const key = prefix + cacheKey;\n      let release: () => void = () => {};\n      const gate = new Promise<void>((resolve) => {\n        release = resolve;\n      });\n      pendingSets.set(key, gate);\n      try {\n        const entry = await pendingEntry;\n        // In production an `expire: 0` entry is dynamic and never served back.\n        if (entry.expire === 0 && !process.env.__NEXT_DEV_SERVER) return;\n\n        const reader = entry.value.getReader();\n        const chunks: Uint8Array[] = [];\n        let size = 0;\n        try {\n          for (;;) {\n            const { done, value } = await reader.read();\n            if (done) break;\n            if (value) {\n              chunks.push(value);\n              size += value.byteLength;\n            }\n          }\n        } finally {\n          reader.releaseLock();\n        }\n        const bytes = new Uint8Array(size);\n        let offset = 0;\n        for (const chunk of chunks) {\n          bytes.set(chunk, offset);\n          offset += chunk.byteLength;\n        }\n\n        remember(key, {\n          bytes,\n          tags: entry.tags ?? [],\n          timestamp: entry.timestamp,\n          expire: entry.expire,\n          revalidate: entry.revalidate,\n          stale: entry.stale,\n        });\n      } catch (error) {\n        warnOnce(`failed to buffer a cache entry (${(error as Error).message})`);\n      } finally {\n        release();\n        pendingSets.delete(key);\n      }\n    },\n\n    async refreshTags() {\n      await syncStamps();\n    },\n\n    async getExpiration(tags) {\n      await syncStamps();\n      let max = 0;\n      for (const tag of tags) {\n        const at = stamps.get(tag) ?? 0;\n        if (at > max) max = at;\n      }\n      return max;\n    },\n\n    async updateTags(tags, _durations) {\n      // `durations.expire` is accepted but not persisted: the shared table holds\n      // a single monotone stamp per tag. A profile'd `revalidateTag` therefore\n      // invalidates immediately rather than stale-while-revalidate \u2014 safe, and\n      // faithful to the one-table model. See README compatibility note #4.\n      const at = now();\n      for (const tag of tags) observeStamp(tag, at);\n      if (tags.length === 0) return;\n      try {\n        if (!(await ensureStore()) || !client) return;\n        await client.batch(\n          tags.map((tag) => ({\n            sql:\n              'INSERT INTO tag_stamps(tag, revalidated_at) VALUES (?, ?) ' +\n              'ON CONFLICT(tag) DO UPDATE SET revalidated_at = MAX(revalidated_at, excluded.revalidated_at)',\n            args: [tag, at],\n          })),\n          'write',\n        );\n      } catch (error) {\n        warnOnce(`tag-stamp write failed; local state kept (${(error as Error).message})`);\n      }\n    },\n  };\n}\n\n/**\n * Default singleton. Next loads the module via `interopDefault`, so this\n * `default` export is the handler Next uses.\n */\nexport default createCacheHandler();\n"],
+  "mappings": ";AAiBA,SAAS,oBAAiC;AAoE1C,IAAM,oBAAoB,MAAM;AAC9B,QAAM,aAAa,OAAO,QAAQ,IAAI,wBAAwB;AAC9D,SAAO,OAAO,SAAS,UAAU,KAAK,cAAc,IAAI,aAAa;AACvE,GAAG;AAEH,IAAM,mBAAmB;AACzB,IAAM,sBAAsB;AAE5B,IAAM,MAAM,MAAc,KAAK,IAAI;AAM5B,SAAS,mBAAmB,UAA6B,CAAC,GAAiB;AAChF,QAAM,MAAM,QAAQ,OAAO,QAAQ,IAAI,kBAAkB,QAAQ,IAAI;AACrE,QAAM,YACJ,QAAQ,aAAa,QAAQ,IAAI,yBAAyB,QAAQ,IAAI;AACxE,QAAM,SAAS,QAAQ,UAAU,QAAQ,IAAI,qBAAqB;AAClE,QAAM,gBAAgB,OAAO,QAAQ,IAAI,sBAAsB;AAC/D,QAAM,aACJ,QAAQ,eACP,OAAO,SAAS,aAAa,KAAK,gBAAgB,IAAI,gBAAgB;AACzE,QAAM,gBAAgB,OAAO,QAAQ,IAAI,wBAAwB;AACjE,QAAM,gBACJ,QAAQ,gBACP,OAAO,SAAS,aAAa,KAAK,iBAAiB,IAAI,gBAAgB;AAC1E,QAAM,OAAO,QAAQ,SAAS,CAAC,YAAoB,QAAQ,KAAK,gBAAgB,OAAO,EAAE;AAGzF,QAAM,UAAU,oBAAI,IAAyB;AAC7C,WAAS,SAAS,KAAa,OAA0B;AACvD,YAAQ,OAAO,GAAG;AAClB,YAAQ,IAAI,KAAK,KAAK;AACtB,WAAO,QAAQ,OAAO,YAAY;AAChC,YAAM,SAAS,QAAQ,KAAK,EAAE,KAAK,EAAE;AACrC,UAAI,WAAW,OAAW;AAC1B,cAAQ,OAAO,MAAM;AAAA,IACvB;AAAA,EACF;AAGA,QAAM,SAAS,oBAAI,IAAoB;AACvC,MAAI,iBAAiB;AACrB,WAAS,aAAa,KAAa,IAAkB;AACnD,QAAI,MAAM,OAAO,IAAI,GAAG,KAAK,GAAI,QAAO,IAAI,KAAK,EAAE;AAAA,EACrD;AAGA,MAAI;AACJ,MAAI;AACJ,MAAI,UAAU;AACd,MAAI,SAAS;AACb,WAAS,SAAS,SAAuB;AACvC,QAAI,CAAC,QAAQ;AACX,eAAS;AACT,WAAK,OAAO;AAAA,IACd;AAAA,EACF;AAEA,WAAS,cAAgC;AACvC,QAAI,MAAO,QAAO;AAClB,QAAI,CAAC,KAAK;AACR,eAAS,+EAA+E;AACxF,aAAO,QAAQ,QAAQ,KAAK;AAAA,IAC9B;AACA,QAAI,IAAI,IAAI,QAAS,QAAO,QAAQ,QAAQ,KAAK;AACjD,aAAS,YAAY;AACnB,UAAI;AACF,cAAM,UAAU,aAAa,EAAE,KAAK,UAAU,CAAC;AAC/C,cAAM,QAAQ;AAAA,UACZ;AAAA,QACF;AACA,iBAAS;AACT,eAAO;AAAA,MACT,SAAS,OAAO;AACd,kBAAU,IAAI,IAAI;AAClB,gBAAQ;AACR,iBAAS,sDAAuD,MAAgB,OAAO,GAAG;AAC1F,eAAO;AAAA,MACT;AAAA,IACF,GAAG;AACH,WAAO;AAAA,EACT;AAEA,iBAAe,aAA4B;AACzC,QAAI,IAAI,IAAI,iBAAiB,cAAe;AAC5C,QAAI;AACF,UAAI,CAAE,MAAM,YAAY,KAAM,CAAC,OAAQ;AACvC,YAAM,SAAS,MAAM,OAAO,QAAQ,4CAA4C;AAChF,iBAAW,OAAO,OAAO,MAAM;AAC7B,cAAM,KAAK,OAAO,IAAI,cAAc;AACpC,YAAI,OAAO,SAAS,EAAE,EAAG,cAAa,OAAO,IAAI,GAAG,GAAG,EAAE;AAAA,MAC3D;AAAA,IACF,SAAS,OAAO;AACd,gBAAU,IAAI,IAAI;AAClB,eAAS,+CAAgD,MAAgB,OAAO,GAAG;AAAA,IACrF,UAAE;AACA,uBAAiB,IAAI;AAAA,IACvB;AAAA,EACF;AAGA,QAAM,cAAc,oBAAI,IAA2B;AAEnD,SAAO;AAAA,IACL,MAAM,IAAI,UAAU,UAAU;AAC5B,YAAM,MAAM,SAAS;AACrB,YAAM,UAAU,YAAY,IAAI,GAAG;AACnC,UAAI,QAAS,OAAM,QAAQ,MAAM,MAAM;AAAA,MAAC,CAAC;AAEzC,YAAM,QAAQ,QAAQ,IAAI,GAAG;AAC7B,UAAI,CAAC,MAAO,QAAO;AAGnB,cAAQ,OAAO,GAAG;AAClB,cAAQ,IAAI,KAAK,KAAK;AAKtB,UAAI,MAAM,SAAS,GAAG;AACpB,gBAAQ,OAAO,GAAG;AAClB,eAAO;AAAA,MACT;AAWA,YAAM,MAAM,IAAI,IAAI,MAAM;AAC1B,YAAM,gBAAgB,QAAQ,IAAI,oBAC9B,KAAK,IAAI,MAAM,QAAQ,GAAG,IAC1B,MAAM;AACV,UAAI,EAAE,MAAM,gBAAgB,QAAU,MAAM,UAAU,KAAK,EAAE,MAAM,MAAM,SAAS,MAAQ;AACxF,eAAO;AAAA,MACT;AAQA,YAAM,WAAW;AACjB,iBAAW,OAAO,MAAM,MAAM;AAC5B,aAAK,OAAO,IAAI,GAAG,KAAK,MAAM,MAAM,UAAW,QAAO;AAAA,MACxD;AACA,iBAAW,OAAO,UAAU;AAC1B,aAAK,OAAO,IAAI,GAAG,KAAK,MAAM,MAAM,UAAW,QAAO;AAAA,MACxD;AAEA,YAAM,QAAQ,MAAM;AACpB,aAAO;AAAA,QACL,OAAO,IAAI,eAA2B;AAAA,UACpC,MAAM,YAAY;AAChB,uBAAW,QAAQ,KAAK;AACxB,uBAAW,MAAM;AAAA,UACnB;AAAA,QACF,CAAC;AAAA,QACD,MAAM,MAAM;AAAA,QACZ,OAAO,MAAM;AAAA,QACb,WAAW,MAAM;AAAA,QACjB,QAAQ,MAAM;AAAA,QACd,YAAY,MAAM;AAAA,MACpB;AAAA,IACF;AAAA,IAEA,MAAM,IAAI,UAAU,cAAc;AAChC,YAAM,MAAM,SAAS;AACrB,UAAI,UAAsB,MAAM;AAAA,MAAC;AACjC,YAAM,OAAO,IAAI,QAAc,CAAC,YAAY;AAC1C,kBAAU;AAAA,MACZ,CAAC;AACD,kBAAY,IAAI,KAAK,IAAI;AACzB,UAAI;AACF,cAAM,QAAQ,MAAM;AAEpB,YAAI,MAAM,WAAW,KAAK,CAAC,QAAQ,IAAI,kBAAmB;AAE1D,cAAM,SAAS,MAAM,MAAM,UAAU;AACrC,cAAM,SAAuB,CAAC;AAC9B,YAAI,OAAO;AACX,YAAI;AACF,qBAAS;AACP,kBAAM,EAAE,MAAM,MAAM,IAAI,MAAM,OAAO,KAAK;AAC1C,gBAAI,KAAM;AACV,gBAAI,OAAO;AACT,qBAAO,KAAK,KAAK;AACjB,sBAAQ,MAAM;AAAA,YAChB;AAAA,UACF;AAAA,QACF,UAAE;AACA,iBAAO,YAAY;AAAA,QACrB;AACA,cAAM,QAAQ,IAAI,WAAW,IAAI;AACjC,YAAI,SAAS;AACb,mBAAW,SAAS,QAAQ;AAC1B,gBAAM,IAAI,OAAO,MAAM;AACvB,oBAAU,MAAM;AAAA,QAClB;AAEA,iBAAS,KAAK;AAAA,UACZ;AAAA,UACA,MAAM,MAAM,QAAQ,CAAC;AAAA,UACrB,WAAW,MAAM;AAAA,UACjB,QAAQ,MAAM;AAAA,UACd,YAAY,MAAM;AAAA,UAClB,OAAO,MAAM;AAAA,QACf,CAAC;AAAA,MACH,SAAS,OAAO;AACd,iBAAS,mCAAoC,MAAgB,OAAO,GAAG;AAAA,MACzE,UAAE;AACA,gBAAQ;AACR,oBAAY,OAAO,GAAG;AAAA,MACxB;AAAA,IACF;AAAA,IAEA,MAAM,cAAc;AAClB,YAAM,WAAW;AAAA,IACnB;AAAA,IAEA,MAAM,cAAc,MAAM;AACxB,YAAM,WAAW;AACjB,UAAI,MAAM;AACV,iBAAW,OAAO,MAAM;AACtB,cAAM,KAAK,OAAO,IAAI,GAAG,KAAK;AAC9B,YAAI,KAAK,IAAK,OAAM;AAAA,MACtB;AACA,aAAO;AAAA,IACT;AAAA,IAEA,MAAM,WAAW,MAAM,YAAY;AAKjC,YAAM,KAAK,IAAI;AACf,iBAAW,OAAO,KAAM,cAAa,KAAK,EAAE;AAC5C,UAAI,KAAK,WAAW,EAAG;AACvB,UAAI;AACF,YAAI,CAAE,MAAM,YAAY,KAAM,CAAC,OAAQ;AACvC,cAAM,OAAO;AAAA,UACX,KAAK,IAAI,CAAC,SAAS;AAAA,YACjB,KACE;AAAA,YAEF,MAAM,CAAC,KAAK,EAAE;AAAA,UAChB,EAAE;AAAA,UACF;AAAA,QACF;AAAA,MACF,SAAS,OAAO;AACd,iBAAS,6CAA8C,MAAgB,OAAO,GAAG;AAAA,MACnF;AAAA,IACF;AAAA,EACF;AACF;AAMA,IAAO,gBAAQ,mBAAmB;",
+  "names": []
+}

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "cacheplank",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "The shared plank your pods walk across: a single-file Next.js 16 cache handler where entries stay local and only tag invalidation is shared, via one libSQL table.",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node build.mjs && tsc -p tsconfig.json",
+    "test": "node --test test/*.test.mjs",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "prepublishOnly": "npm run build && npm test && npm run typecheck"
+  },
+  "dependencies": {
+    "@libsql/client": "^0.18.0"
+  },
+  "peerDependencies": {
+    "next": ">=16.0.0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.25.0",
+    "next": "16.3.8",
+    "typescript": "^5.6.0"
+  },
+  "keywords": [
+    "next",
+    "nextjs",
+    "next.js",
+    "cache-handler",
+    "cacheComponents",
+    "use-cache",
+    "isr",
+    "revalidateTag",
+    "libsql",
+    "turso",
+    "bunny"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dmytri/cacheplank.git"
+  }
+}