@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.210

package/dist/_chunks/walkers-Czu2jXFq.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walkers-Czu2jXFq.js","names":[],"sources":["../../src/routing/schema-validation.ts","../../src/routing/walkers.ts"],"sourcesContent":["/**\n * Schema key/value validation against the filesystem route tree.\n *\n * Runs at codegen time (build + dev) to catch mismatches between\n * app/schema.ts keys and the actual dynamic segments on disk.\n *\n * Design doc: design/41-global-params.md\n */\n\nimport { readFileCached } from './file-cache.ts';\nimport type { RouteTree, SegmentNode } from './types.ts';\nimport { findSchemaFile, parseExistingSchemaKeys } from '../cli-schema-sync.ts';\nimport { classifyUrlSegment } from './segment-classify.ts';\n\nexport interface SchemaWarning {\n  type: 'stale-key' | 'missing-key' | 'bracket-mismatch';\n  key: string;\n  message: string;\n  filesystemKey?: string;\n}\n\n/**\n * Collect all unique bracket-keyed dynamic segment names from a route tree.\n * Returns entries like '[artistSlug]', '[...slug]', '[[...topic]]'.\n */\nexport function collectDynamicSegmentsFromTree(tree: RouteTree): Set<string> {\n  const segments = new Set<string>();\n  walkTree(tree.root, segments);\n  return segments;\n}\n\nfunction walkTree(node: SegmentNode, segments: Set<string>): void {\n  if (node.paramName && node.segmentName) {\n    const classified = classifyUrlSegment(node.segmentName);\n    if (classified.kind !== 'static') {\n      // Use bare bracket form for schema keys — affixed segments like\n      // `img-[id].png` register as `[id]`, matching runtime codec lookup.\n      if (classified.kind === 'dynamic' && (classified.prefix || classified.suffix)) {\n        segments.add(`[${classified.name}]`);\n      } else {\n        segments.add(node.segmentName);\n      }\n    }\n  }\n  for (const child of node.children) {\n    walkTree(child, segments);\n  }\n  for (const slot of Object.values(node.slots)) {\n    walkTree(slot, segments);\n  }\n}\n\n/**\n * Extract the param name from a bracket key.\n * '[id]' → 'id', '[...slug]' → 'slug', '[[...topic]]' → 'topic'\n */\nfunction extractParamName(bracketKey: string): string | null {\n  const seg = classifyUrlSegment(bracketKey);\n  if (seg.kind === 'static') return null;\n  return seg.name;\n}\n\n/**\n * Validate schema keys against the filesystem route tree.\n *\n * Returns warnings for:\n * - Stale keys: schema keys that don't match any filesystem segment\n * - Bracket form mismatches: same param name, different bracket form\n * - Missing keys: filesystem segments not registered in schema (informational)\n */\nexport function validateSchemaAgainstRoutes(tree: RouteTree, appDir: string): SchemaWarning[] {\n  const schemaPath = findSchemaFile(appDir);\n  if (!schemaPath) return [];\n\n  const content = readFileCached(schemaPath);\n  const schemaKeys = parseExistingSchemaKeys(content);\n\n  if (schemaKeys.length === 0) return [];\n\n  const filesystemSegments = collectDynamicSegmentsFromTree(tree);\n\n  return validateKeys(schemaKeys, filesystemSegments);\n}\n\n/**\n * Core validation: compare schema keys against filesystem segments.\n * Exported separately for testing without filesystem dependencies.\n */\nexport function validateKeys(\n  schemaKeys: string[],\n  filesystemSegments: Set<string>\n): SchemaWarning[] {\n  const warnings: SchemaWarning[] = [];\n\n  // Build a map of param name → bracket form for filesystem segments\n  const fsParamToKey = new Map<string, string>();\n  for (const fsKey of filesystemSegments) {\n    const name = extractParamName(fsKey);\n    if (name) {\n      fsParamToKey.set(name, fsKey);\n    }\n  }\n\n  // Build a set of schema param names for the missing-key check\n  const schemaParamNames = new Set<string>();\n\n  for (const schemaKey of schemaKeys) {\n    const schemaParamName = extractParamName(schemaKey);\n    if (!schemaParamName) continue;\n\n    schemaParamNames.add(schemaParamName);\n\n    if (filesystemSegments.has(schemaKey)) {\n      // Exact match — no issue\n      continue;\n    }\n\n    // Check if the param name exists but with a different bracket form\n    const fsKey = fsParamToKey.get(schemaParamName);\n    if (fsKey) {\n      warnings.push({\n        type: 'bracket-mismatch',\n        key: schemaKey,\n        filesystemKey: fsKey,\n        message:\n          `Schema key '${schemaKey}' does not match filesystem bracket form '${fsKey}'. ` +\n          `Update the schema key to '${fsKey}'.`,\n      });\n    } else {\n      warnings.push({\n        type: 'stale-key',\n        key: schemaKey,\n        message:\n          `Schema key '${schemaKey}' does not match any dynamic segment in the filesystem. ` +\n          `Remove it from app/schema.ts or create the corresponding route segment.`,\n      });\n    }\n  }\n\n  // Check for filesystem segments not in schema (informational)\n  for (const fsKey of filesystemSegments) {\n    const name = extractParamName(fsKey);\n    if (name && !schemaParamNames.has(name)) {\n      warnings.push({\n        type: 'missing-key',\n        key: fsKey,\n        message:\n          `Dynamic segment '${fsKey}' has no codec in app/schema.ts (defaults to string). ` +\n          `Run: timber schema sync`,\n      });\n    }\n  }\n\n  return warnings;\n}\n","/**\n * Shared route-tree walkers (TIM-848).\n *\n * Tiny helpers that walk a `SegmentNode<TFile>` tree generically. Both the\n * build-time tree (`SegmentNode<RouteFile>`) and the runtime manifest\n * tree (`SegmentNode<ManifestFile>`) flow through these helpers because\n * the walker only reads the structural fields shared by both shapes\n * (`children`, `slots`, `page`, `route`, `urlPath`).\n *\n * Before this module, three near-identical `collectRoutes` functions\n * lived in `plugins/dev-404-page.ts`, `plugins/build-report.ts`, and\n * `routing/codegen.ts`. The codegen one is special-purpose (it\n * accumulates `ParamEntry[]` and resolves codec chains) and stays\n * local; the other two now share `collectLeafRoutes` from this file.\n */\n\nimport type { SegmentNode } from './types.ts';\n\n/** A leaf route discovered while walking the segment tree. */\nexport interface LeafRoute<TFile> {\n  /** URL path of the leaf (root is \"/\"). */\n  urlPath: string;\n  /** Segment chain from root to this leaf, inclusive. */\n  segments: SegmentNode<TFile>[];\n  /** The page file at this leaf, if any. */\n  page?: TFile;\n  /** The route handler file at this leaf, if any. */\n  route?: TFile;\n}\n\n/** Options for `collectLeafRoutes`. */\nexport interface CollectLeafRoutesOptions {\n  /**\n   * If true, recurse into parallel slots and emit slot leaves alongside\n   * the main route tree. Defaults to `false` because slots render\n   * alongside their parent at the same URL and are not separately\n   * URL-addressable. The build report excludes slots; route-listing\n   * UIs that want to show \"all leaves with a page handler\" can opt in.\n   */\n  includeSlots?: boolean;\n}\n\n/**\n * Walk a segment tree and collect every leaf with a `page` or `route`\n * handler. Generic over `TFile` so it works on both the build-time\n * scanner output and the runtime manifest tree.\n *\n * - Pages and route handlers at the same URL produce two distinct\n *   entries (the build report deduplicates by URL afterward).\n * - Parallel slots are skipped unless `includeSlots: true` (slots\n *   share their parent's URL and are not addressable on their own).\n * - Intercepting subtrees are skipped unconditionally. They render only\n *   on soft navigation and add no URL depth, so their computed `urlPath`s\n *   are not addresses — listing them would advertise routes (`/[year]`)\n *   that no request can reach. This matches every other consumer of the\n *   tree that produces URLs: the sitemap generator, the static generator,\n *   prerendering and the prebuilt-payload builder all skip them too.\n * - Result is sorted by `urlPath` for deterministic output.\n */\nexport function collectLeafRoutes<TFile>(\n  root: SegmentNode<TFile>,\n  options: CollectLeafRoutesOptions = {}\n): LeafRoute<TFile>[] {\n  const { includeSlots = false } = options;\n  const result: LeafRoute<TFile>[] = [];\n  walk(root, [], result, includeSlots);\n  result.sort((a, b) => a.urlPath.localeCompare(b.urlPath));\n  return result;\n}\n\nfunction walk<TFile>(\n  node: SegmentNode<TFile>,\n  chain: SegmentNode<TFile>[],\n  result: LeafRoute<TFile>[],\n  includeSlots: boolean\n): void {\n  if (node.segmentType === 'intercepting') return;\n\n  const currentChain = [...chain, node];\n  const path = node.urlPath || '/';\n\n  if (node.page) {\n    result.push({ urlPath: path, segments: currentChain, page: node.page });\n  }\n  if (node.route) {\n    result.push({ urlPath: path, segments: currentChain, route: node.route });\n  }\n\n  for (const child of node.children) {\n    walk(child, currentChain, result, includeSlots);\n  }\n\n  if (includeSlots) {\n    for (const slotNode of Object.values(node.slots)) {\n      walk(slotNode, currentChain, result, includeSlots);\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/_chunks/write-file-atomic-D1qWqHb4.js

@@ -0,0 +1,32 @@
+import { randomUUID } from "node:crypto";
+import { rename, rm, writeFile } from "node:fs/promises";
+//#region src/utils/write-file-atomic.ts
+/**
+* Replace a file's contents in one step: write a uniquely named temp sibling,
+* then `rename()` it over the target.
+*
+* `writeFile()` opens its target with `O_TRUNC`, so for the length of the write
+* a concurrent reader sees an empty or half-written file under the real name.
+* `rename()` within one directory swaps the name atomically, so a reader sees
+* either the old file or the new one — never a torn one — and a crashed
+* writer leaves no partial artifact under the final name.
+*
+* The temp name is unique per call, not a fixed `${path}.tmp`: two writers of
+* the same path (a dev server and a `vite build` rewriting the same route
+* types, parallel CLI invocations sharing a cache) would otherwise write into
+* one temp file and rename each other's half-written bytes into place.
+*/
+async function writeFileAtomic(path, data) {
+	const tmp = `${path}.${randomUUID()}.tmp`;
+	try {
+		await writeFile(tmp, data);
+		await rename(tmp, path);
+	} catch (err) {
+		await rm(tmp, { force: true }).catch(() => {});
+		throw err;
+	}
+}
+//#endregion
+export { writeFileAtomic as t };
+
+//# sourceMappingURL=write-file-atomic-D1qWqHb4.js.map

package/dist/_chunks/write-file-atomic-D1qWqHb4.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-file-atomic-D1qWqHb4.js","names":[],"sources":["../../src/utils/write-file-atomic.ts"],"sourcesContent":["/**\n * Replace a file's contents in one step: write a uniquely named temp sibling,\n * then `rename()` it over the target.\n *\n * `writeFile()` opens its target with `O_TRUNC`, so for the length of the write\n * a concurrent reader sees an empty or half-written file under the real name.\n * `rename()` within one directory swaps the name atomically, so a reader sees\n * either the old file or the new one — never a torn one — and a crashed\n * writer leaves no partial artifact under the final name.\n *\n * The temp name is unique per call, not a fixed `${path}.tmp`: two writers of\n * the same path (a dev server and a `vite build` rewriting the same route\n * types, parallel CLI invocations sharing a cache) would otherwise write into\n * one temp file and rename each other's half-written bytes into place.\n */\n\nimport { randomUUID } from 'node:crypto';\nimport { rename, rm, writeFile } from 'node:fs/promises';\n\nexport async function writeFileAtomic(path: string, data: Uint8Array | string): Promise<void> {\n  const tmp = `${path}.${randomUUID()}.tmp`;\n  try {\n    await writeFile(tmp, data);\n    await rename(tmp, path);\n  } catch (err) {\n    // Best-effort cleanup. If the directory refuses the write it may refuse\n    // the rm too, and that error — naming a random temp path — must not\n    // replace the one that says what actually failed.\n    await rm(tmp, { force: true }).catch(() => {});\n    throw err;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAmBA,eAAsB,gBAAgB,MAAc,MAA0C;CAC5F,MAAM,MAAM,GAAG,KAAK,GAAG,WAAW,EAAE;CACpC,IAAI;EACF,MAAM,UAAU,KAAK,IAAI;EACzB,MAAM,OAAO,KAAK,IAAI;CACxB,SAAS,KAAK;EAIZ,MAAM,GAAG,KAAK,EAAE,OAAO,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;EAC7C,MAAM;CACR;AACF"}

package/dist/adapters/build-output-helper.d.ts

@@ -0,0 +1,72 @@
+import type { BuildArtifacts, ServerBuildArtifacts, StaticBuildArtifacts, TimberConfig } from './types.ts';
+/** Options for the shared build output steps. */
+export interface BuildOutputBaseOptions {
+    /** Resolved timber config. */
+    config: TimberConfig;
+    /** What the build produced. */
+    artifacts: ServerBuildArtifacts;
+    /** Adapter-specific output directory (e.g. `.timber/dist/nitro`). */
+    outDir: string;
+    /**
+     * Name of the public/static directory within outDir.
+     * Nitro uses 'public', Cloudflare uses 'static'.
+     */
+    publicDirName: string;
+}
+/**
+ * Run the platform-agnostic build output steps shared by all adapters:
+ *
+ * 1. Create the output directory
+ * 2. Copy client assets to the public/static directory
+ * 3. Write the `_headers` file for static asset cache control
+ * 4. Copy RSC and SSR server bundles into the output directory
+ * 5. Write the manifest-init module if present
+ *
+ * Returns the resolved public directory path for further adapter-specific use.
+ */
+export declare function runSharedBuildSteps(opts: BuildOutputBaseOptions): Promise<string>;
+export declare function findUnhashedStaticFiles(publicDir: string, immutableDirs: readonly string[]): Promise<string[]>;
+/**
+ * Build a static-only output directory (no server entry). Copies client
+ * assets and pre-rendered HTML/RSC/API files into `outDir/publicDirName`.
+ * Used by both Cloudflare and Nitro adapters in `output: 'static'` mode.
+ */
+export declare function buildStaticDirectoryOutput(config: TimberConfig, artifacts: StaticBuildArtifacts, outDir: string, publicDirName: string): Promise<void>;
+/**
+ * Write the `_headers` file, folding in the user's `public/_headers`.
+ *
+ * Every adapter used to `writeFile` a generated `_headers` over whatever
+ * Vite had copied out of `public/`, so an app shipping its own CSP, CORS, or
+ * cache rules deployed without them and without a word (TIM-1326). The
+ * generated rules and the user's are not competitors — they address different
+ * paths — so this merges rather than refusing, the way `_redirects` has since
+ * TIM-1249.
+ *
+ * **Read from the project, not the output.** The generated file lands under
+ * the same name in the output directory, and `runSharedBuildSteps` does not
+ * clean `outDir`; a reader aimed there would fold the previous build's
+ * generated rules back in and compound them on every rebuild — the defect
+ * this pass fixed for `_redirects`.
+ *
+ * User rules go last. On Cloudflare and Netlify a `_headers` file applies
+ * every matching rule, so appending means the user's rules take effect; where
+ * a platform resolves a conflict in favour of the earlier rule instead, the
+ * framework keeps the paths it owns and the user keeps the rest. Under either
+ * reading this is no worse than the previous behaviour, which was to drop the
+ * user's rules entirely.
+ *
+ * @internal Exported for testing.
+ */
+export declare function writeHeadersFile(dir: string, config: TimberConfig, artifacts: BuildArtifacts): Promise<void>;
+/**
+ * Throw if copying `srcDir` over `destDir` would overwrite an existing file.
+ *
+ * Compared against the destination **as it stands**, not against the other
+ * source tree: the first copy is filtered (client JS is dropped when client
+ * JavaScript is disabled), so the files that are actually there are the only
+ * ones a second copy can clobber.
+ *
+ * @internal Exported for testing.
+ */
+export declare function assertNoTreeCollision(srcDir: string, destDir: string): Promise<void>;
+//# sourceMappingURL=build-output-helper.d.ts.map

package/dist/adapters/build-output-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-output-helper.d.ts","sourceRoot":"","sources":["../../src/adapters/build-output-helper.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,oBAAoB,EACpB,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,iDAAiD;AACjD,MAAM,WAAW,sBAAsB;IACrC,8BAA8B;IAC9B,MAAM,EAAE,YAAY,CAAC;IACrB,+BAA+B;IAC/B,SAAS,EAAE,oBAAoB,CAAC;IAChC,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsDvF;AA8BD,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,SAAS,MAAM,EAAE,GAC/B,OAAO,CAAC,MAAM,EAAE,CAAC,CA2BnB;AA2BD;;;;GAIG;AACH,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,oBAAoB,EAC/B,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CA2Bf;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,cAAc,GACxB,OAAO,CAAC,IAAI,CAAC,CAcf;AAoBD;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2B1F"}

package/dist/adapters/canonicalize-module.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Compile server/canonicalize.ts into a standalone ESM module exporting
+ * `canonicalize`.
+ *
+ * @internal Exported for testing.
+ */
+export declare function generateCanonicalizeModule(): Promise<string>;
+//# sourceMappingURL=canonicalize-module.d.ts.map

package/dist/adapters/canonicalize-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalize-module.d.ts","sourceRoot":"","sources":["../../src/adapters/canonicalize-module.ts"],"names":[],"mappings":"AAcA;;;;;GAKG;AACH,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,MAAM,CAAC,CAQlE"}

package/dist/adapters/cloudflare-dev.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Cloudflare dev-mode bindings via wrangler's getPlatformProxy().
+ *
+ * This Vite plugin starts a local workerd process (via Miniflare) that
+ * emulates Cloudflare bindings (KV, D1, R2, Queues, Durable Objects, etc.)
+ * during development. The proxy env is injected into the request ALS so
+ * `getCloudflareBindings()` works identically in dev and production.
+ *
+ * Design doc: design/35-cloudflare-primitives.md §"Dev Experience"
+ *
+ * Usage:
+ * ```ts
+ * // vite.config.ts
+ * import { timber } from '@timber-js/app'
+ * import { cloudflare } from '@timber-js/app/adapters/cloudflare'
+ * import { cloudflareDevBindings } from '@timber-js/app/adapters/cloudflare/dev'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     timber({ adapter: cloudflare() }),
+ *     cloudflareDevBindings(),
+ *   ],
+ * })
+ * ```
+ *
+ * Requires `wrangler` as a dev dependency. Install it:
+ * ```bash
+ * pnpm add -D wrangler
+ * ```
+ */
+import type { Plugin } from 'vite';
+/**
+ * Dynamically import wrangler. Extracted as a named export so tests
+ * can mock it without needing wrangler installed.
+ * @internal
+ */
+export declare function loadWrangler(): Promise<{
+    getPlatformProxy: (opts: any) => Promise<any>;
+}>;
+/**
+ * Symbol key used to store the dev request wrapper on ViteDevServer.
+ *
+ * @internal Exported for testing. The dev-server plugin uses
+ * `Symbol.for('timber:dev-request-wrapper')` directly to avoid
+ * importing from this module.
+ */
+export declare const DEV_REQUEST_WRAPPER_KEY: unique symbol;
+/** Options for the Cloudflare dev bindings plugin. */
+export interface CloudflareDevBindingsOptions {
+    /**
+     * Path to the wrangler configuration file.
+     * @default Auto-detected by wrangler (wrangler.jsonc, wrangler.json, wrangler.toml)
+     */
+    configPath?: string;
+    /**
+     * Whether to persist binding data (KV, D1, R2) between dev server restarts.
+     *
+     * - `true` — persist in wrangler's default location (`.wrangler/state/`)
+     * - `{ path: string }` — persist in a custom directory
+     * - `false` — start fresh on every restart
+     *
+     * @default true
+     */
+    persist?: boolean | {
+        path: string;
+    };
+    /**
+     * Wrangler environment to use (for multi-environment configs).
+     * Maps to `[env.<name>]` sections in wrangler.toml / wrangler.jsonc.
+     */
+    environment?: string;
+    /**
+     * @internal Override the wrangler loader for testing.
+     * Not part of the public API — may change without notice.
+     */
+    _loadWrangler?: () => Promise<{
+        getPlatformProxy: (opts: any) => Promise<any>;
+    }>;
+}
+/**
+ * Vite plugin that provides Cloudflare bindings in dev mode via
+ * wrangler's `getPlatformProxy()`.
+ *
+ * Starts a local workerd process on dev server startup and injects
+ * the proxy env into the per-request ALS. This makes
+ * `getCloudflareBindings()` return real (emulated) bindings during
+ * development — KV, D1, R2, Queues, Durable Objects, and all other
+ * bindings declared in wrangler.jsonc.
+ *
+ * The proxy is automatically disposed when the dev server closes.
+ *
+ * **Requirements:**
+ * - `wrangler` installed as a dev dependency
+ * - A `wrangler.jsonc` (or `wrangler.toml`) with binding declarations
+ *
+ * @example
+ * ```ts
+ * import { cloudflareDevBindings } from '@timber-js/app/adapters/cloudflare/dev'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     timber({ adapter: cloudflare() }),
+ *     cloudflareDevBindings(),
+ *   ],
+ * })
+ * ```
+ */
+export declare function cloudflareDevBindings(options?: CloudflareDevBindingsOptions): Plugin;
+//# sourceMappingURL=cloudflare-dev.d.ts.map

package/dist/adapters/cloudflare-dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-dev.d.ts","sourceRoot":"","sources":["../../src/adapters/cloudflare-dev.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAC;AAGlD;;;;GAIG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC;IAAE,gBAAgB,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;CAAE,CAAC,CAU/F;AAaD;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,eAA2C,CAAC;AAEhF,sDAAsD;AACtD,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAErC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC;QAAE,gBAAgB,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;KAAE,CAAC,CAAC;CAClF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,4BAAiC,GAAG,MAAM,CAmDxF"}

package/dist/adapters/cloudflare-dev.js

@@ -0,0 +1,74 @@
+import { f as runWithBindings } from "../_chunks/cloudflare-Byxl8FWP.js";
+//#region src/adapters/cloudflare-dev.ts
+/**
+* Dynamically import wrangler. Extracted as a named export so tests
+* can mock it without needing wrangler installed.
+* @internal
+*/
+async function loadWrangler() {
+	try {
+		return await import("wrangler");
+	} catch {
+		throw new Error("[timber] Could not import wrangler. cloudflareDevBindings() requires wrangler as a dev dependency.\nInstall it: pnpm add -D wrangler");
+	}
+}
+/**
+* Symbol key used to store the dev request wrapper on ViteDevServer.
+*
+* @internal Exported for testing. The dev-server plugin uses
+* `Symbol.for('timber:dev-request-wrapper')` directly to avoid
+* importing from this module.
+*/
+var DEV_REQUEST_WRAPPER_KEY = Symbol.for("timber:dev-request-wrapper");
+/**
+* Vite plugin that provides Cloudflare bindings in dev mode via
+* wrangler's `getPlatformProxy()`.
+*
+* Starts a local workerd process on dev server startup and injects
+* the proxy env into the per-request ALS. This makes
+* `getCloudflareBindings()` return real (emulated) bindings during
+* development — KV, D1, R2, Queues, Durable Objects, and all other
+* bindings declared in wrangler.jsonc.
+*
+* The proxy is automatically disposed when the dev server closes.
+*
+* **Requirements:**
+* - `wrangler` installed as a dev dependency
+* - A `wrangler.jsonc` (or `wrangler.toml`) with binding declarations
+*
+* @example
+* ```ts
+* import { cloudflareDevBindings } from '@timber-js/app/adapters/cloudflare/dev'
+*
+* export default defineConfig({
+*   plugins: [
+*     timber({ adapter: cloudflare() }),
+*     cloudflareDevBindings(),
+*   ],
+* })
+* ```
+*/
+function cloudflareDevBindings(options = {}) {
+	return {
+		name: "timber-cloudflare-dev-bindings",
+		apply: "serve",
+		async configureServer(server) {
+			if (process.env.TIMBER_ANALYZE === "1") return;
+			const { getPlatformProxy } = await (options._loadWrangler ?? loadWrangler)();
+			const proxyOptions = { persist: options.persist ?? true };
+			if (options.configPath) proxyOptions.configPath = options.configPath;
+			if (options.environment) proxyOptions.environment = options.environment;
+			const proxy = await getPlatformProxy(proxyOptions);
+			server[DEV_REQUEST_WRAPPER_KEY] = (fn) => {
+				return runWithBindings(proxy.env, fn);
+			};
+			server.httpServer?.on("close", () => {
+				proxy.dispose().catch(() => {});
+			});
+		}
+	};
+}
+//#endregion
+export { DEV_REQUEST_WRAPPER_KEY, cloudflareDevBindings, loadWrangler };
+
+//# sourceMappingURL=cloudflare-dev.js.map

package/dist/adapters/cloudflare-dev.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-dev.js","names":[],"sources":["../../src/adapters/cloudflare-dev.ts"],"sourcesContent":["/**\n * Cloudflare dev-mode bindings via wrangler's getPlatformProxy().\n *\n * This Vite plugin starts a local workerd process (via Miniflare) that\n * emulates Cloudflare bindings (KV, D1, R2, Queues, Durable Objects, etc.)\n * during development. The proxy env is injected into the request ALS so\n * `getCloudflareBindings()` works identically in dev and production.\n *\n * Design doc: design/35-cloudflare-primitives.md §\"Dev Experience\"\n *\n * Usage:\n * ```ts\n * // vite.config.ts\n * import { timber } from '@timber-js/app'\n * import { cloudflare } from '@timber-js/app/adapters/cloudflare'\n * import { cloudflareDevBindings } from '@timber-js/app/adapters/cloudflare/dev'\n *\n * export default defineConfig({\n *   plugins: [\n *     timber({ adapter: cloudflare() }),\n *     cloudflareDevBindings(),\n *   ],\n * })\n * ```\n *\n * Requires `wrangler` as a dev dependency. Install it:\n * ```bash\n * pnpm add -D wrangler\n * ```\n */\n\nimport type { Plugin, ViteDevServer } from 'vite';\nimport { runWithBindings } from './cloudflare.ts';\n\n/**\n * Dynamically import wrangler. Extracted as a named export so tests\n * can mock it without needing wrangler installed.\n * @internal\n */\nexport async function loadWrangler(): Promise<{ getPlatformProxy: (opts: any) => Promise<any> }> {\n  try {\n    return await import('wrangler');\n  } catch {\n    throw new Error(\n      '[timber] Could not import wrangler. ' +\n        'cloudflareDevBindings() requires wrangler as a dev dependency.\\n' +\n        'Install it: pnpm add -D wrangler'\n    );\n  }\n}\n\n// ─── Contract ─────────────────────────────────────────────────────────────\n//\n// The dev request wrapper is stored on the ViteDevServer instance using a\n// well-known Symbol. This allows cross-plugin communication without import\n// dependencies — the dev-server plugin checks for this Symbol per-request\n// and wraps the handler call when present.\n//\n// The wrapper type is: <T>(fn: () => T) => T\n// It runs `fn` inside the Cloudflare bindings ALS so getCloudflareBindings()\n// works throughout the request lifecycle.\n\n/**\n * Symbol key used to store the dev request wrapper on ViteDevServer.\n *\n * @internal Exported for testing. The dev-server plugin uses\n * `Symbol.for('timber:dev-request-wrapper')` directly to avoid\n * importing from this module.\n */\nexport const DEV_REQUEST_WRAPPER_KEY = Symbol.for('timber:dev-request-wrapper');\n\n/** Options for the Cloudflare dev bindings plugin. */\nexport interface CloudflareDevBindingsOptions {\n  /**\n   * Path to the wrangler configuration file.\n   * @default Auto-detected by wrangler (wrangler.jsonc, wrangler.json, wrangler.toml)\n   */\n  configPath?: string;\n\n  /**\n   * Whether to persist binding data (KV, D1, R2) between dev server restarts.\n   *\n   * - `true` — persist in wrangler's default location (`.wrangler/state/`)\n   * - `{ path: string }` — persist in a custom directory\n   * - `false` — start fresh on every restart\n   *\n   * @default true\n   */\n  persist?: boolean | { path: string };\n\n  /**\n   * Wrangler environment to use (for multi-environment configs).\n   * Maps to `[env.<name>]` sections in wrangler.toml / wrangler.jsonc.\n   */\n  environment?: string;\n\n  /**\n   * @internal Override the wrangler loader for testing.\n   * Not part of the public API — may change without notice.\n   */\n  _loadWrangler?: () => Promise<{ getPlatformProxy: (opts: any) => Promise<any> }>;\n}\n\n/**\n * Vite plugin that provides Cloudflare bindings in dev mode via\n * wrangler's `getPlatformProxy()`.\n *\n * Starts a local workerd process on dev server startup and injects\n * the proxy env into the per-request ALS. This makes\n * `getCloudflareBindings()` return real (emulated) bindings during\n * development — KV, D1, R2, Queues, Durable Objects, and all other\n * bindings declared in wrangler.jsonc.\n *\n * The proxy is automatically disposed when the dev server closes.\n *\n * **Requirements:**\n * - `wrangler` installed as a dev dependency\n * - A `wrangler.jsonc` (or `wrangler.toml`) with binding declarations\n *\n * @example\n * ```ts\n * import { cloudflareDevBindings } from '@timber-js/app/adapters/cloudflare/dev'\n *\n * export default defineConfig({\n *   plugins: [\n *     timber({ adapter: cloudflare() }),\n *     cloudflareDevBindings(),\n *   ],\n * })\n * ```\n */\nexport function cloudflareDevBindings(options: CloudflareDevBindingsOptions = {}): Plugin {\n  return {\n    name: 'timber-cloudflare-dev-bindings',\n\n    // Dev mode only — never active during production builds.\n    // See design/35-cloudflare-primitives.md §\"Security Considerations\":\n    // \"Dev bindings are dev-only. apply: 'serve' ensures it never runs\n    //  in production builds.\"\n    apply: 'serve',\n\n    async configureServer(server: ViteDevServer) {\n      // The analyze crawl (design/47 §6) boots a middleware-mode server\n      // only to walk import edges — it never renders a request, so the\n      // workerd boot and the wrangler remote-bindings handshake (~6.8 s\n      // measured) are pure waste there. Skip the proxy entirely.\n      if (process.env.TIMBER_ANALYZE === '1') return;\n\n      // Dynamic import — wrangler is an optional peer dependency.\n      // Users must install it themselves: `pnpm add -D wrangler`\n      const { getPlatformProxy } = await (options._loadWrangler ?? loadWrangler)();\n\n      // Build getPlatformProxy options from our public API.\n      const proxyOptions: Record<string, unknown> = {\n        persist: options.persist ?? true,\n      };\n      if (options.configPath) {\n        proxyOptions.configPath = options.configPath;\n      }\n      if (options.environment) {\n        proxyOptions.environment = options.environment;\n      }\n\n      const proxy = await getPlatformProxy(proxyOptions);\n\n      // Store a request wrapper on the server instance. The dev-server\n      // plugin checks for this Symbol per-request and wraps the RSC\n      // handler call so getCloudflareBindings() works throughout the\n      // request lifecycle (server components, middleware, server actions).\n      (server as any)[DEV_REQUEST_WRAPPER_KEY] = <T>(fn: () => T): T => {\n        return runWithBindings(proxy.env as Record<string, unknown>, fn);\n      };\n\n      // Dispose the proxy when the dev server closes. This shuts down\n      // the local workerd process started by getPlatformProxy().\n      server.httpServer?.on('close', () => {\n        proxy.dispose().catch(() => {\n          // Disposal errors are non-fatal — the process is shutting down.\n        });\n      });\n    },\n  };\n}\n"],"mappings":";;;;;;;AAuCA,eAAsB,eAA2E;CAC/F,IAAI;EACF,OAAO,MAAM,OAAO;CACtB,QAAQ;EACN,MAAM,IAAI,MACR,sIAGF;CACF;AACF;;;;;;;;AAoBA,IAAa,0BAA0B,OAAO,IAAI,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8D9E,SAAgB,sBAAsB,UAAwC,CAAC,GAAW;CACxF,OAAO;EACL,MAAM;EAMN,OAAO;EAEP,MAAM,gBAAgB,QAAuB;GAK3C,IAAI,QAAQ,IAAI,mBAAmB,KAAK;GAIxC,MAAM,EAAE,qBAAqB,OAAO,QAAQ,iBAAiB,aAAA,CAAc;GAG3E,MAAM,eAAwC,EAC5C,SAAS,QAAQ,WAAW,KAC9B;GACA,IAAI,QAAQ,YACV,aAAa,aAAa,QAAQ;GAEpC,IAAI,QAAQ,aACV,aAAa,cAAc,QAAQ;GAGrC,MAAM,QAAQ,MAAM,iBAAiB,YAAY;GAMjD,OAAgB,4BAA+B,OAAmB;IAChE,OAAO,gBAAgB,MAAM,KAAgC,EAAE;GACjE;GAIA,OAAO,YAAY,GAAG,eAAe;IACnC,MAAM,QAAQ,CAAC,CAAC,YAAY,CAE5B,CAAC;GACH,CAAC;EACH;CACF;AACF"}

package/dist/adapters/cloudflare-kv-cache.d.ts

@@ -0,0 +1,65 @@
+import type { CacheHandler } from '../cache/index.ts';
+/**
+ * Cloudflare Workers KV interface — the subset of KVNamespace we depend on.
+ * Users don't need to import this; the handler resolves the binding internally
+ * via `getCloudflareBindings()`.
+ */
+export interface CloudflareKVNamespace {
+    get(key: string, options: {
+        type: 'json';
+    }): Promise<unknown>;
+    get(key: string, options?: {
+        type?: string;
+    }): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * Cloudflare Workers KV–backed CacheHandler.
+ *
+ * Uses tag index keys for tag-based invalidation (KV has no secondary indexes).
+ * Stores entries with 2× TTL so stale entries survive for `staleWhileRevalidate`
+ * reads. The logical staleness is determined by the `expiresAt` timestamp inside
+ * the entry payload.
+ *
+ * **Consistency:** KV is eventually consistent (~60s propagation). TTL is the
+ * primary expiry mechanism. Tag invalidation is best-effort — do not rely on it
+ * for security-critical cache purging (use short TTLs instead).
+ *
+ * ```ts
+ * // timber.config.ts
+ * import { CloudflareKVCacheHandler } from '@timber-js/app/adapters/cloudflare/cache';
+ *
+ * export default {
+ *   cacheHandler: new CloudflareKVCacheHandler({ bindingName: 'TIMBER_CACHE' }),
+ * };
+ * ```
+ */
+export declare class CloudflareKVCacheHandler implements CacheHandler {
+    private bindingName;
+    private prefix;
+    constructor(options: {
+        bindingName: string;
+        prefix?: string;
+    });
+    /** Resolve the KV binding from the current request's Cloudflare env. */
+    private getKV;
+    private dataKey;
+    private tagKey;
+    get(key: string): Promise<{
+        value: unknown;
+        stale: boolean;
+    } | null>;
+    set(key: string, value: unknown, opts: {
+        ttl: number;
+        tags: string[];
+        generation?: number;
+    }): Promise<void>;
+    invalidate(opts: {
+        key?: string;
+        tag?: string;
+    }): Promise<void>;
+}
+//# sourceMappingURL=cloudflare-kv-cache.d.ts.map

package/dist/adapters/cloudflare-kv-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-kv-cache.d.ts","sourceRoot":"","sources":["../../src/adapters/cloudflare-kv-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAItD;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACtE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAwCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,wBAAyB,YAAW,YAAY;IAC3D,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,MAAM,CAAS;IAEvB,YAAY,OAAO,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,EAG5D;IAED,wEAAwE;IACxE,OAAO,CAAC,KAAK;IAYb,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,MAAM;IAIR,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC,CAQzE;IAEK,GAAG,CACP,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GACzD,OAAO,CAAC,IAAI,CAAC,CAoCf;IAEK,UAAU,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAgDpE;CACF"}

package/dist/adapters/cloudflare-kv-cache.js

@@ -0,0 +1,123 @@
+import { t as warnLossyJsonValue } from "../_chunks/json-lossy-check-CVuRs2hG.js";
+import { l as getCloudflareBindings } from "../_chunks/cloudflare-Byxl8FWP.js";
+//#region src/adapters/cloudflare-kv-cache.ts
+var LEGACY_GRACE_MS = 2592e6;
+/**
+* Parse a tag index value, handling both the old format (string[]) and the
+* new format (TagIndexEntry[]). Old-format entries get a 30-day grace period
+* so they survive until explicitly invalidated or cycled through a new set().
+*/
+function parseTagIndex(raw, now) {
+	if (!Array.isArray(raw)) return [];
+	const legacyDeadline = now + LEGACY_GRACE_MS;
+	return raw.map((item) => {
+		if (typeof item === "string") return {
+			key: item,
+			expiresAt: legacyDeadline
+		};
+		return item;
+	});
+}
+function computeIndexTtl(entries, now) {
+	const maxExpiresAt = Math.max(...entries.map((e) => e.expiresAt));
+	return Math.max(Math.ceil((maxExpiresAt - now) / 1e3), 60);
+}
+/**
+* Cloudflare Workers KV–backed CacheHandler.
+*
+* Uses tag index keys for tag-based invalidation (KV has no secondary indexes).
+* Stores entries with 2× TTL so stale entries survive for `staleWhileRevalidate`
+* reads. The logical staleness is determined by the `expiresAt` timestamp inside
+* the entry payload.
+*
+* **Consistency:** KV is eventually consistent (~60s propagation). TTL is the
+* primary expiry mechanism. Tag invalidation is best-effort — do not rely on it
+* for security-critical cache purging (use short TTLs instead).
+*
+* ```ts
+* // timber.config.ts
+* import { CloudflareKVCacheHandler } from '@timber-js/app/adapters/cloudflare/cache';
+*
+* export default {
+*   cacheHandler: new CloudflareKVCacheHandler({ bindingName: 'TIMBER_CACHE' }),
+* };
+* ```
+*/
+var CloudflareKVCacheHandler = class {
+	bindingName;
+	prefix;
+	constructor(options) {
+		this.bindingName = options.bindingName;
+		this.prefix = options.prefix ?? "tc:";
+	}
+	/** Resolve the KV binding from the current request's Cloudflare env. */
+	getKV() {
+		const kv = getCloudflareBindings()[this.bindingName];
+		if (!kv) throw new Error(`CloudflareKVCacheHandler: binding "${this.bindingName}" not found. Check your wrangler.jsonc kv_namespaces configuration.`);
+		return kv;
+	}
+	dataKey(key) {
+		return `${this.prefix}d:${key}`;
+	}
+	tagKey(tag) {
+		return `${this.prefix}t:${tag}`;
+	}
+	async get(key) {
+		const raw = await this.getKV().get(this.dataKey(key), { type: "json" });
+		if (!raw) return null;
+		const entry = raw;
+		const stale = Date.now() > entry.expiresAt;
+		return {
+			value: entry.value,
+			stale
+		};
+	}
+	async set(key, value, opts) {
+		warnLossyJsonValue(value, key);
+		const kv = this.getKV();
+		const entry = {
+			value,
+			tags: opts.tags,
+			expiresAt: Date.now() + opts.ttl * 1e3
+		};
+		const kvTtl = Math.max(opts.ttl * 2, 60);
+		const payload = JSON.stringify(entry);
+		const now = Date.now();
+		const kvExpiresAt = now + kvTtl * 1e3;
+		await Promise.all(opts.tags.map(async (tag) => {
+			const fresh = parseTagIndex(await kv.get(this.tagKey(tag), { type: "json" }), now).filter((e) => e.expiresAt > now && e.key !== key);
+			fresh.push({
+				key,
+				expiresAt: kvExpiresAt
+			});
+			await kv.put(this.tagKey(tag), JSON.stringify(fresh), { expirationTtl: computeIndexTtl(fresh, now) });
+		}));
+		await kv.put(this.dataKey(key), payload, { expirationTtl: kvTtl });
+	}
+	async invalidate(opts) {
+		const kv = this.getKV();
+		if (opts.key) {
+			const raw = await kv.get(this.dataKey(opts.key), { type: "json" });
+			if (raw) await Promise.all(raw.tags.map(async (tag) => {
+				const now = Date.now();
+				const filtered = parseTagIndex(await kv.get(this.tagKey(tag), { type: "json" }), now).filter((e) => e.key !== opts.key);
+				if (filtered.length > 0) await kv.put(this.tagKey(tag), JSON.stringify(filtered), { expirationTtl: computeIndexTtl(filtered, now) });
+				else await kv.delete(this.tagKey(tag));
+			}));
+			await kv.delete(this.dataKey(opts.key));
+		}
+		if (opts.tag) {
+			const entries = parseTagIndex(await kv.get(this.tagKey(opts.tag), { type: "json" }), Date.now());
+			if (entries.length > 0) await Promise.all(entries.map(async (e) => {
+				const raw = await kv.get(this.dataKey(e.key), { type: "json" });
+				if (!raw) return;
+				if (raw.tags?.includes(opts.tag)) await kv.delete(this.dataKey(e.key));
+			}));
+			await kv.delete(this.tagKey(opts.tag));
+		}
+	}
+};
+//#endregion
+export { CloudflareKVCacheHandler };
+
+//# sourceMappingURL=cloudflare-kv-cache.js.map

package/dist/adapters/cloudflare-kv-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-kv-cache.js","names":[],"sources":["../../src/adapters/cloudflare-kv-cache.ts"],"sourcesContent":["import type { CacheHandler } from '../cache/index.ts';\nimport { getCloudflareBindings } from './cloudflare.ts';\nimport { warnLossyJsonValue } from '../cache/json-lossy-check.ts';\n\n/**\n * Cloudflare Workers KV interface — the subset of KVNamespace we depend on.\n * Users don't need to import this; the handler resolves the binding internally\n * via `getCloudflareBindings()`.\n */\nexport interface CloudflareKVNamespace {\n  get(key: string, options: { type: 'json' }): Promise<unknown>;\n  get(key: string, options?: { type?: string }): Promise<string | null>;\n  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;\n  delete(key: string): Promise<void>;\n}\n\ninterface KVCacheEntry {\n  value: unknown;\n  tags: string[];\n  expiresAt: number;\n}\n\ninterface TagIndexEntry {\n  key: string;\n  /** Physical KV expiry — the 2× TTL deadline. Members are pruned at this\n   *  timestamp (not the logical expiresAt) so stale entries in the SWR window\n   *  remain in the index for `invalidate({tag})` to find. */\n  expiresAt: number;\n}\n\n// 30 days in ms — used as the grace period for legacy tag index entries whose\n// original expiry is unknown. Must be a concrete number, not Infinity, because\n// JSON.stringify(Infinity) produces null and the entry would be pruned on read.\nconst LEGACY_GRACE_MS = 30 * 86400 * 1000;\n\n/**\n * Parse a tag index value, handling both the old format (string[]) and the\n * new format (TagIndexEntry[]). Old-format entries get a 30-day grace period\n * so they survive until explicitly invalidated or cycled through a new set().\n */\nfunction parseTagIndex(raw: unknown, now: number): TagIndexEntry[] {\n  if (!Array.isArray(raw)) return [];\n  const legacyDeadline = now + LEGACY_GRACE_MS;\n  return raw.map((item: unknown) => {\n    if (typeof item === 'string') return { key: item, expiresAt: legacyDeadline };\n    return item as TagIndexEntry;\n  });\n}\n\nfunction computeIndexTtl(entries: TagIndexEntry[], now: number): number {\n  const maxExpiresAt = Math.max(...entries.map((e) => e.expiresAt));\n  return Math.max(Math.ceil((maxExpiresAt - now) / 1000), 60);\n}\n\n/**\n * Cloudflare Workers KV–backed CacheHandler.\n *\n * Uses tag index keys for tag-based invalidation (KV has no secondary indexes).\n * Stores entries with 2× TTL so stale entries survive for `staleWhileRevalidate`\n * reads. The logical staleness is determined by the `expiresAt` timestamp inside\n * the entry payload.\n *\n * **Consistency:** KV is eventually consistent (~60s propagation). TTL is the\n * primary expiry mechanism. Tag invalidation is best-effort — do not rely on it\n * for security-critical cache purging (use short TTLs instead).\n *\n * ```ts\n * // timber.config.ts\n * import { CloudflareKVCacheHandler } from '@timber-js/app/adapters/cloudflare/cache';\n *\n * export default {\n *   cacheHandler: new CloudflareKVCacheHandler({ bindingName: 'TIMBER_CACHE' }),\n * };\n * ```\n */\nexport class CloudflareKVCacheHandler implements CacheHandler {\n  private bindingName: string;\n  private prefix: string;\n\n  constructor(options: { bindingName: string; prefix?: string }) {\n    this.bindingName = options.bindingName;\n    this.prefix = options.prefix ?? 'tc:';\n  }\n\n  /** Resolve the KV binding from the current request's Cloudflare env. */\n  private getKV(): CloudflareKVNamespace {\n    const env = getCloudflareBindings<Record<string, CloudflareKVNamespace>>();\n    const kv = env[this.bindingName];\n    if (!kv) {\n      throw new Error(\n        `CloudflareKVCacheHandler: binding \"${this.bindingName}\" not found. ` +\n          'Check your wrangler.jsonc kv_namespaces configuration.'\n      );\n    }\n    return kv;\n  }\n\n  private dataKey(key: string): string {\n    return `${this.prefix}d:${key}`;\n  }\n\n  private tagKey(tag: string): string {\n    return `${this.prefix}t:${tag}`;\n  }\n\n  async get(key: string): Promise<{ value: unknown; stale: boolean } | null> {\n    const kv = this.getKV();\n    const raw = await kv.get(this.dataKey(key), { type: 'json' });\n    if (!raw) return null;\n\n    const entry = raw as KVCacheEntry;\n    const stale = Date.now() > entry.expiresAt;\n    return { value: entry.value, stale };\n  }\n\n  async set(\n    key: string,\n    value: unknown,\n    opts: { ttl: number; tags: string[]; generation?: number }\n  ): Promise<void> {\n    warnLossyJsonValue(value, key);\n    const kv = this.getKV();\n    const entry: KVCacheEntry = {\n      value,\n      tags: opts.tags,\n      expiresAt: Date.now() + opts.ttl * 1000,\n    };\n\n    // KV expirationTtl minimum is 60s. Use 2× TTL (min 60s) so stale entries\n    // survive for staleWhileRevalidate background refetches.\n    const kvTtl = Math.max(opts.ttl * 2, 60);\n\n    // Serialize upfront so BigInt/non-serializable errors throw before any\n    // writes — prevents tag indexes pointing at stale data from a prior set().\n    const payload = JSON.stringify(entry);\n\n    // Tag indexes are written BEFORE the data key so that a partial network\n    // failure on the data write never leaves an entry invisible to\n    // invalidate({tag}). A dangling tag-index reference to a non-existent\n    // data key is harmless — invalidate() re-checks stored tags and cleans\n    // up on the next pass.\n    const now = Date.now();\n    const kvExpiresAt = now + kvTtl * 1000;\n    await Promise.all(\n      opts.tags.map(async (tag) => {\n        const existing = parseTagIndex(await kv.get(this.tagKey(tag), { type: 'json' }), now);\n        const fresh = existing.filter((e) => e.expiresAt > now && e.key !== key);\n        fresh.push({ key, expiresAt: kvExpiresAt });\n        await kv.put(this.tagKey(tag), JSON.stringify(fresh), {\n          expirationTtl: computeIndexTtl(fresh, now),\n        });\n      })\n    );\n\n    await kv.put(this.dataKey(key), payload, { expirationTtl: kvTtl });\n  }\n\n  async invalidate(opts: { key?: string; tag?: string }): Promise<void> {\n    const kv = this.getKV();\n\n    if (opts.key) {\n      // Read entry to find its tags, then clean up tag indexes\n      const raw = (await kv.get(this.dataKey(opts.key), { type: 'json' })) as KVCacheEntry | null;\n      if (raw) {\n        await Promise.all(\n          raw.tags.map(async (tag) => {\n            const now = Date.now();\n            const entries = parseTagIndex(await kv.get(this.tagKey(tag), { type: 'json' }), now);\n            const filtered = entries.filter((e) => e.key !== opts.key);\n            if (filtered.length > 0) {\n              await kv.put(this.tagKey(tag), JSON.stringify(filtered), {\n                expirationTtl: computeIndexTtl(filtered, now),\n              });\n            } else {\n              await kv.delete(this.tagKey(tag));\n            }\n          })\n        );\n      }\n      await kv.delete(this.dataKey(opts.key));\n    }\n\n    if (opts.tag) {\n      const entries = parseTagIndex(\n        await kv.get(this.tagKey(opts.tag), { type: 'json' }),\n        Date.now()\n      );\n      if (entries.length > 0) {\n        // Re-check each member's stored tags before deleting — the tag index\n        // can contain stale references from partial writes or entries whose\n        // tags changed since they were indexed. Mirrors Redis handler behavior.\n        await Promise.all(\n          entries.map(async (e) => {\n            const raw = (await kv.get(this.dataKey(e.key), {\n              type: 'json',\n            })) as KVCacheEntry | null;\n            if (!raw) return;\n            if (raw.tags?.includes(opts.tag!)) {\n              await kv.delete(this.dataKey(e.key));\n            }\n          })\n        );\n      }\n      await kv.delete(this.tagKey(opts.tag));\n    }\n  }\n}\n"],"mappings":"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"}