@timber-js/app 0.2.0-alpha.9 → 0.2.0-alpha.90

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.js';\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      // 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;AAC/F,KAAI;AACF,SAAO,MAAM,OAAO;SACd;AACN,QAAM,IAAI,MACR,uIAGD;;;;;;;;;;AAsBL,IAAa,0BAA0B,OAAO,IAAI,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8D/E,SAAgB,sBAAsB,UAAwC,EAAE,EAAU;AACxF,QAAO;EACL,MAAM;EAMN,OAAO;EAEP,MAAM,gBAAgB,QAAuB;GAG3C,MAAM,EAAE,qBAAqB,OAAO,QAAQ,iBAAiB,eAAe;GAG5E,MAAM,eAAwC,EAC5C,SAAS,QAAQ,WAAW,MAC7B;AACD,OAAI,QAAQ,WACV,cAAa,aAAa,QAAQ;AAEpC,OAAI,QAAQ,YACV,cAAa,cAAc,QAAQ;GAGrC,MAAM,QAAQ,MAAM,iBAAiB,aAAa;AAMjD,UAAe,4BAA+B,OAAmB;AAChE,WAAO,gBAAgB,MAAM,KAAgC,GAAG;;AAKlE,UAAO,YAAY,GAAG,eAAe;AACnC,UAAM,SAAS,CAAC,YAAY,GAE1B;KACF;;EAEL"}

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

@@ -0,0 +1,64 @@
+import type { CacheHandler } from '../cache/index';
+/**
+ * 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[];
+    }): 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,gBAAgB,CAAC;AAGnD;;;;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;AAQD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,wBAAyB,YAAW,YAAY;IAC3D,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IAK7D,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;IAUpE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BtF,UAAU,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAgCtE"}

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

@@ -0,0 +1,95 @@
+import { getCloudflareBindings } from "./cloudflare.js";
+//#region src/adapters/cloudflare-kv-cache.ts
+/**
+* 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) {
+		const kv = this.getKV();
+		const entry = {
+			value,
+			tags: opts.tags,
+			expiresAt: Date.now() + opts.ttl * 1e3
+		};
+		const kvTtl = Math.max(opts.ttl * 2, 60);
+		await kv.put(this.dataKey(key), JSON.stringify(entry), { expirationTtl: kvTtl });
+		await Promise.all(opts.tags.map(async (tag) => {
+			const existing = await kv.get(this.tagKey(tag), { type: "json" });
+			const keys = Array.isArray(existing) ? existing : [];
+			if (!keys.includes(key)) {
+				keys.push(key);
+				await kv.put(this.tagKey(tag), JSON.stringify(keys));
+			}
+		}));
+	}
+	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 existing = await kv.get(this.tagKey(tag), { type: "json" });
+				if (Array.isArray(existing)) {
+					const filtered = existing.filter((k) => k !== opts.key);
+					if (filtered.length > 0) await kv.put(this.tagKey(tag), JSON.stringify(filtered));
+					else await kv.delete(this.tagKey(tag));
+				}
+			}));
+			await kv.delete(this.dataKey(opts.key));
+		}
+		if (opts.tag) {
+			const existing = await kv.get(this.tagKey(opts.tag), { type: "json" });
+			if (Array.isArray(existing)) await Promise.all(existing.map((key) => kv.delete(this.dataKey(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';\nimport { getCloudflareBindings } from './cloudflare';\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\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(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void> {\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    await kv.put(this.dataKey(key), JSON.stringify(entry), { expirationTtl: kvTtl });\n\n    // Update tag indexes (best-effort, eventually consistent).\n    // Tag indexes have no TTL — cleaned up on invalidation.\n    await Promise.all(\n      opts.tags.map(async (tag) => {\n        const existing = (await kv.get(this.tagKey(tag), { type: 'json' })) as string[] | null;\n        const keys: string[] = Array.isArray(existing) ? existing : [];\n        if (!keys.includes(key)) {\n          keys.push(key);\n          await kv.put(this.tagKey(tag), JSON.stringify(keys));\n        }\n      })\n    );\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 existing = (await kv.get(this.tagKey(tag), { type: 'json' })) as string[] | null;\n            if (Array.isArray(existing)) {\n              const filtered = existing.filter((k: string) => k !== opts.key);\n              if (filtered.length > 0) {\n                await kv.put(this.tagKey(tag), JSON.stringify(filtered));\n              } else {\n                await kv.delete(this.tagKey(tag));\n              }\n            }\n          })\n        );\n      }\n      await kv.delete(this.dataKey(opts.key));\n    }\n\n    if (opts.tag) {\n      const existing = (await kv.get(this.tagKey(opts.tag), { type: 'json' })) as string[] | null;\n      if (Array.isArray(existing)) {\n        await Promise.all(existing.map((key: string) => kv.delete(this.dataKey(key))));\n      }\n      await kv.delete(this.tagKey(opts.tag));\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AA0CA,IAAa,2BAAb,MAA8D;CAC5D;CACA;CAEA,YAAY,SAAmD;AAC7D,OAAK,cAAc,QAAQ;AAC3B,OAAK,SAAS,QAAQ,UAAU;;;CAIlC,QAAuC;EAErC,MAAM,KADM,uBAA8D,CAC3D,KAAK;AACpB,MAAI,CAAC,GACH,OAAM,IAAI,MACR,sCAAsC,KAAK,YAAY,qEAExD;AAEH,SAAO;;CAGT,QAAgB,KAAqB;AACnC,SAAO,GAAG,KAAK,OAAO,IAAI;;CAG5B,OAAe,KAAqB;AAClC,SAAO,GAAG,KAAK,OAAO,IAAI;;CAG5B,MAAM,IAAI,KAAiE;EAEzE,MAAM,MAAM,MADD,KAAK,OAAO,CACF,IAAI,KAAK,QAAQ,IAAI,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC7D,MAAI,CAAC,IAAK,QAAO;EAEjB,MAAM,QAAQ;EACd,MAAM,QAAQ,KAAK,KAAK,GAAG,MAAM;AACjC,SAAO;GAAE,OAAO,MAAM;GAAO;GAAO;;CAGtC,MAAM,IAAI,KAAa,OAAgB,MAAsD;EAC3F,MAAM,KAAK,KAAK,OAAO;EACvB,MAAM,QAAsB;GAC1B;GACA,MAAM,KAAK;GACX,WAAW,KAAK,KAAK,GAAG,KAAK,MAAM;GACpC;EAID,MAAM,QAAQ,KAAK,IAAI,KAAK,MAAM,GAAG,GAAG;AACxC,QAAM,GAAG,IAAI,KAAK,QAAQ,IAAI,EAAE,KAAK,UAAU,MAAM,EAAE,EAAE,eAAe,OAAO,CAAC;AAIhF,QAAM,QAAQ,IACZ,KAAK,KAAK,IAAI,OAAO,QAAQ;GAC3B,MAAM,WAAY,MAAM,GAAG,IAAI,KAAK,OAAO,IAAI,EAAE,EAAE,MAAM,QAAQ,CAAC;GAClE,MAAM,OAAiB,MAAM,QAAQ,SAAS,GAAG,WAAW,EAAE;AAC9D,OAAI,CAAC,KAAK,SAAS,IAAI,EAAE;AACvB,SAAK,KAAK,IAAI;AACd,UAAM,GAAG,IAAI,KAAK,OAAO,IAAI,EAAE,KAAK,UAAU,KAAK,CAAC;;IAEtD,CACH;;CAGH,MAAM,WAAW,MAAqD;EACpE,MAAM,KAAK,KAAK,OAAO;AAEvB,MAAI,KAAK,KAAK;GAEZ,MAAM,MAAO,MAAM,GAAG,IAAI,KAAK,QAAQ,KAAK,IAAI,EAAE,EAAE,MAAM,QAAQ,CAAC;AACnE,OAAI,IACF,OAAM,QAAQ,IACZ,IAAI,KAAK,IAAI,OAAO,QAAQ;IAC1B,MAAM,WAAY,MAAM,GAAG,IAAI,KAAK,OAAO,IAAI,EAAE,EAAE,MAAM,QAAQ,CAAC;AAClE,QAAI,MAAM,QAAQ,SAAS,EAAE;KAC3B,MAAM,WAAW,SAAS,QAAQ,MAAc,MAAM,KAAK,IAAI;AAC/D,SAAI,SAAS,SAAS,EACpB,OAAM,GAAG,IAAI,KAAK,OAAO,IAAI,EAAE,KAAK,UAAU,SAAS,CAAC;SAExD,OAAM,GAAG,OAAO,KAAK,OAAO,IAAI,CAAC;;KAGrC,CACH;AAEH,SAAM,GAAG,OAAO,KAAK,QAAQ,KAAK,IAAI,CAAC;;AAGzC,MAAI,KAAK,KAAK;GACZ,MAAM,WAAY,MAAM,GAAG,IAAI,KAAK,OAAO,KAAK,IAAI,EAAE,EAAE,MAAM,QAAQ,CAAC;AACvE,OAAI,MAAM,QAAQ,SAAS,CACzB,OAAM,QAAQ,IAAI,SAAS,KAAK,QAAgB,GAAG,OAAO,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAC;AAEhF,SAAM,GAAG,OAAO,KAAK,OAAO,KAAK,IAAI,CAAC"}

package/dist/adapters/cloudflare.d.ts

@@ -20,12 +20,79 @@ import type { TimberPlatformAdapter, TimberConfig } from './types';
  * }
  * ```
  */
-export declare function getCloudflareBindings<T extends Record<string, unknown> = Record<string, unknown>>(): T;
+export declare function getCloudflareBindings<T = Record<string, unknown>>(): T;
 /**
  * Run a function with Cloudflare bindings available via getCloudflareBindings().
  * @internal Used by wrapWithExecutionContext.
  */
 export declare function runWithBindings<T>(env: Record<string, unknown>, fn: () => T): T;
+/** KV namespace binding. `id` defaults to `''` (filled in by wrangler or dashboard). */
+export interface CloudflareKVBinding {
+    name: string;
+    id?: string;
+}
+/** D1 database binding. `database_id` is required (from Cloudflare dashboard). */
+export interface CloudflareD1Binding {
+    name: string;
+    database_id: string;
+}
+/** R2 bucket binding. `bucket_name` must match the bucket created in Cloudflare. */
+export interface CloudflareR2Binding {
+    name: string;
+    bucket_name: string;
+}
+/** Queue producer binding. `queue` is the queue name in Cloudflare. */
+export interface CloudflareQueueProducer {
+    name: string;
+    queue: string;
+}
+/** Queue consumer declaration. Attached to the worker, not a binding name. */
+export interface CloudflareQueueConsumer {
+    queue: string;
+    max_batch_size?: number;
+    max_retries?: number;
+    dead_letter_queue?: string;
+}
+/** Durable Object binding. `script_name` is for external DO references. */
+export interface CloudflareDurableObjectBinding {
+    name: string;
+    class_name: string;
+    script_name?: string;
+}
+/**
+ * Declarative Cloudflare bindings configuration.
+ *
+ * These are converted to the appropriate wrangler.jsonc sections
+ * (`kv_namespaces`, `d1_databases`, `r2_buckets`, `queues`, `durable_objects`).
+ * The `wrangler` escape hatch overrides any generated binding sections
+ * if there's a conflict.
+ *
+ * @example
+ * ```ts
+ * cloudflare({
+ *   bindings: {
+ *     kv: [{ name: 'TIMBER_CACHE' }],
+ *     d1: [{ name: 'MY_DB', database_id: 'xxxx' }],
+ *     r2: [{ name: 'MY_BUCKET', bucket_name: 'my-bucket' }],
+ *     queues: {
+ *       producers: [{ name: 'EMAIL_QUEUE', queue: 'email-queue' }],
+ *       consumers: [{ queue: 'email-queue', max_batch_size: 10 }],
+ *     },
+ *     durableObjects: [{ name: 'MY_DO', class_name: 'MyDurableObject' }],
+ *   },
+ * })
+ * ```
+ */
+export interface CloudflareBindings {
+    kv?: CloudflareKVBinding[];
+    d1?: CloudflareD1Binding[];
+    r2?: CloudflareR2Binding[];
+    queues?: {
+        producers?: CloudflareQueueProducer[];
+        consumers?: CloudflareQueueConsumer[];
+    };
+    durableObjects?: CloudflareDurableObjectBinding[];
+}
 /** Options for the Cloudflare Workers adapter. */
 export interface CloudflareAdapterOptions {
     /**
@@ -38,11 +105,40 @@ export interface CloudflareAdapterOptions {
      * @default ['nodejs_compat']
      */
     compatibilityFlags?: string[];
+    /**
+     * Declarative Cloudflare bindings. Generates the appropriate
+     * `kv_namespaces`, `d1_databases`, `r2_buckets`, `queues`, and
+     * `durable_objects` sections in wrangler.jsonc.
+     *
+     * If both `bindings` and `wrangler` specify the same section,
+     * `wrangler` wins (it's the escape hatch).
+     */
+    bindings?: CloudflareBindings;
     /**
      * Custom wrangler.jsonc fields to merge.
-     * Overrides generated values.
+     * Overrides generated values (including bindings-generated sections).
      */
     wrangler?: Record<string, unknown>;
+    /**
+     * Path to a module that exports additional Worker handlers (queue, scheduled, email, etc.).
+     * The module is imported in the generated `_worker.js` and its named exports are
+     * spread into the default export alongside `fetch`.
+     *
+     * The module receives `(batch/event, env, ctx)` — standard Cloudflare handler signatures.
+     * It does NOT have access to timber's request pipeline (no ALS, no getCloudflareBindings).
+     * Use `env` directly for bindings.
+     *
+     * @example
+     * ```ts
+     * // timber.config.ts
+     * adapter: cloudflare({ workerHandlers: './src/worker-handlers.ts' })
+     *
+     * // src/worker-handlers.ts
+     * export async function queue(batch, env) { ... }
+     * export async function scheduled(controller, env, ctx) { ... }
+     * ```
+     */
+    workerHandlers?: string;
 }
 /**
  * Create a Cloudflare Workers adapter.
@@ -67,9 +163,49 @@ export declare function cloudflare(options?: CloudflareAdapterOptions): TimberPl
  * 1. Binds `adapter.waitUntil()` to `ctx.waitUntil()` per-request
  * 2. Makes `env` accessible via `getCloudflareBindings()` per-request via ALS
  */
-export declare function wrapWithExecutionContext(adapter: TimberPlatformAdapter, handler: (req: Request) => Promise<Response>): ExportedHandler<Record<string, unknown>>;
+export declare function wrapWithExecutionContext(adapter: TimberPlatformAdapter, handler: (req: Request) => Promise<Response>): CfExportedHandler<Record<string, unknown>>;
 /** @internal Exported for testing. */
-export declare function generateWorkerEntry(buildDir: string, outDir: string, hasManifestInit?: boolean): string;
+export declare function generateWorkerEntry(buildDir: string, outDir: string, hasManifestInit?: boolean, hasWorkerHandlers?: boolean): string;
+/** Wrangler binding sections generated from `CloudflareBindings`. */
+export interface WranglerBindingsConfig {
+    kv_namespaces?: Array<{
+        binding: string;
+        id: string;
+    }>;
+    d1_databases?: Array<{
+        binding: string;
+        database_id: string;
+    }>;
+    r2_buckets?: Array<{
+        binding: string;
+        bucket_name: string;
+    }>;
+    queues?: {
+        producers?: Array<{
+            binding: string;
+            queue: string;
+        }>;
+        consumers?: Array<Record<string, unknown>>;
+    };
+    durable_objects?: {
+        bindings: Array<Record<string, string>>;
+    };
+}
+/**
+ * Convert declarative `CloudflareBindings` into wrangler.jsonc binding sections.
+ *
+ * Maps:
+ * - `kv`             → `kv_namespaces`
+ * - `d1`             → `d1_databases`
+ * - `r2`             → `r2_buckets`
+ * - `queues`         → `queues` (producers + consumers)
+ * - `durableObjects` → `durable_objects`
+ *
+ * Empty arrays are omitted from the output.
+ *
+ * @internal Exported for testing.
+ */
+export declare function generateBindingsConfig(bindings: CloudflareBindings | undefined): WranglerBindingsConfig;
 /** @internal Exported for testing. */
 export declare function generateWranglerConfig(config: TimberConfig, options: CloudflareAdapterOptions): Record<string, unknown>;
 /** Command descriptor for preview — testable without spawning a process. */
@@ -80,13 +216,13 @@ export interface PreviewCommand {
 }
 /** @internal Exported for testing. */
 export declare function generatePreviewCommand(buildDir: string): PreviewCommand;
-declare global {
-    interface ExecutionContext {
-        waitUntil(promise: Promise<unknown>): void;
-        passThroughOnException(): void;
-    }
-    interface ExportedHandler<Env = Record<string, unknown>> {
-        fetch?(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> | Response;
-    }
+/** @internal Minimal stub — use @cloudflare/workers-types for full types. */
+export interface CfExecutionContext {
+    waitUntil(promise: Promise<unknown>): void;
+    passThroughOnException(): void;
+}
+/** @internal Minimal stub — use @cloudflare/workers-types for full types. */
+export interface CfExportedHandler<Env = Record<string, unknown>> {
+    fetch?(request: Request, env: Env, ctx: CfExecutionContext): Promise<Response> | Response;
 }
 //# sourceMappingURL=cloudflare.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../../src/adapters/cloudflare.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AA2BnE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CACnC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KACxD,CAAC,CAUL;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE/E;AAED,kDAAkD;AAClD,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE9B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,wBAA6B,GAAG,qBAAqB,CA2DxF;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,GAC3C,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAsB1C;AAID,sCAAsC;AACtC,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,eAAe,UAAQ,GACtB,MAAM,CA0BR;AAED,sCAAsC;AACtC,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,wBAAwB,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA0BzB;AAID,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb;AAED,sCAAsC;AACtC,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAOvE;AAqBD,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,gBAAgB;QACxB,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;QAC3C,sBAAsB,IAAI,IAAI,CAAC;KAChC;IAED,UAAU,eAAe,CAAC,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;QACrD,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAAC;KACzF;CACF"}
+{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../../src/adapters/cloudflare.ts"],"names":[],"mappings":"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"}

package/dist/adapters/cloudflare.js

@@ -16,7 +16,15 @@ function generateHeadersFile() {
   Cache-Control: ${STATIC_CACHE}
 `;
 }
-var bindingsAls = new AsyncLocalStorage();
+var BINDINGS_ALS_KEY = Symbol.for("timber:cf-bindings-als");
+function getBindingsAls() {
+	let als = globalThis[BINDINGS_ALS_KEY];
+	if (!als) {
+		als = new AsyncLocalStorage();
+		globalThis[BINDINGS_ALS_KEY] = als;
+	}
+	return als;
+}
 /**
 * Get Cloudflare Worker bindings for the current request.
 *
@@ -39,7 +47,7 @@ var bindingsAls = new AsyncLocalStorage();
 * ```
 */
 function getCloudflareBindings() {
-	const env = bindingsAls.getStore();
+	const env = getBindingsAls().getStore();
 	if (!env) throw new Error("getCloudflareBindings() called outside a Cloudflare Workers request context. It can only be called from server components, middleware, or server actions when running on the Cloudflare adapter.");
 	return env;
 }
@@ -48,7 +56,7 @@ function getCloudflareBindings() {
 * @internal Used by wrapWithExecutionContext.
 */
 function runWithBindings(env, fn) {
-	return bindingsAls.run(env, fn);
+	return getBindingsAls().run(env, fn);
 }
 /**
 * Create a Cloudflare Workers adapter.
@@ -82,7 +90,28 @@ function cloudflare(options = {}) {
 			await cp(rscDir, join(outDir, "rsc"), { recursive: true });
 			await cp(ssrDir, join(outDir, "ssr"), { recursive: true });
 			if (config.manifestInit) await writeFile(join(outDir, "_timber-manifest-init.js"), config.manifestInit);
-			const workerEntry = generateWorkerEntry(outDir, outDir, !!config.manifestInit);
+			let hasWorkerHandlers = false;
+			if (options.workerHandlers) {
+				const handlersEntry = join(process.cwd(), options.workerHandlers);
+				const { build: viteBuild } = await import("vite");
+				await viteBuild({
+					configFile: false,
+					logLevel: "info",
+					build: {
+						lib: {
+							entry: handlersEntry,
+							formats: ["es"],
+							fileName: () => "_worker-handlers.js"
+						},
+						outDir,
+						emptyOutDir: false,
+						minify: false,
+						rollupOptions: { external: [/^node:/] }
+					}
+				});
+				hasWorkerHandlers = true;
+			}
+			const workerEntry = generateWorkerEntry(outDir, outDir, !!config.manifestInit, hasWorkerHandlers);
 			await writeFile(join(outDir, "_worker.js"), workerEntry);
 			const wranglerConfig = generateWranglerConfig(config, options);
 			await writeFile(join(outDir, "wrangler.jsonc"), JSON.stringify(wranglerConfig, null, 2));
@@ -117,22 +146,115 @@ function wrapWithExecutionContext(adapter, handler) {
 	} };
 }
 /** @internal Exported for testing. */
-function generateWorkerEntry(buildDir, outDir, hasManifestInit = false) {
+function generateWorkerEntry(buildDir, outDir, hasManifestInit = false, hasWorkerHandlers = false) {
 	let rscEntryRelative = relative(outDir, join(buildDir, "rsc", "index.js"));
 	if (!rscEntryRelative.startsWith(".")) rscEntryRelative = "./" + rscEntryRelative;
 	return `// Generated by @timber-js/app/adapters/cloudflare
 // Do not edit — this file is regenerated on each build.
 
+import { AsyncLocalStorage } from 'node:async_hooks'
 ${hasManifestInit ? "import './_timber-manifest-init.js'\n" : ""}import handler from '${rscEntryRelative}'
-
+${hasWorkerHandlers ? "import * as workerHandlers from './_worker-handlers.js'\n" : ""}
 // Set TIMBER_RUNTIME for instrumentation.ts conditional SDK initialization.
 // See design/25-production-deployments.md §"TIMBER_RUNTIME".
 globalThis.process ??= { env: {} }
 process.env.TIMBER_RUNTIME = 'cloudflare'
 
-export default { fetch: handler }
+// Bind Cloudflare env to ALS so getCloudflareBindings() works at runtime.
+// Uses the same Symbol.for key as getCloudflareBindings() reads from.
+const ALS_KEY = Symbol.for('timber:cf-bindings-als')
+let bindingsAls = globalThis[ALS_KEY]
+if (!bindingsAls) {
+  bindingsAls = new AsyncLocalStorage()
+  globalThis[ALS_KEY] = bindingsAls
+}
+
+export default {
+${hasWorkerHandlers ? "  ...workerHandlers,\n" : ""}  async fetch(request, env, ctx) {
+    return bindingsAls.run(env, () => handler(request))
+  }
+}
 `;
 }
+/**
+* Convert declarative `CloudflareBindings` into wrangler.jsonc binding sections.
+*
+* Maps:
+* - `kv`             → `kv_namespaces`
+* - `d1`             → `d1_databases`
+* - `r2`             → `r2_buckets`
+* - `queues`         → `queues` (producers + consumers)
+* - `durableObjects` → `durable_objects`
+*
+* Empty arrays are omitted from the output.
+*
+* @internal Exported for testing.
+*/
+function generateBindingsConfig(bindings) {
+	if (!bindings) return {};
+	const result = {};
+	if (bindings.kv && bindings.kv.length > 0) result.kv_namespaces = bindings.kv.map((kv) => ({
+		binding: kv.name,
+		id: kv.id ?? ""
+	}));
+	if (bindings.d1 && bindings.d1.length > 0) result.d1_databases = bindings.d1.map((d1) => ({
+		binding: d1.name,
+		database_id: d1.database_id
+	}));
+	if (bindings.r2 && bindings.r2.length > 0) result.r2_buckets = bindings.r2.map((r2) => ({
+		binding: r2.name,
+		bucket_name: r2.bucket_name
+	}));
+	if (bindings.queues) {
+		const queues = {};
+		if (bindings.queues.producers && bindings.queues.producers.length > 0) queues.producers = bindings.queues.producers.map((p) => ({
+			binding: p.name,
+			queue: p.queue
+		}));
+		if (bindings.queues.consumers && bindings.queues.consumers.length > 0) queues.consumers = bindings.queues.consumers.map((c) => {
+			const consumer = { queue: c.queue };
+			if (c.max_batch_size !== void 0) consumer.max_batch_size = c.max_batch_size;
+			if (c.max_retries !== void 0) consumer.max_retries = c.max_retries;
+			if (c.dead_letter_queue !== void 0) consumer.dead_letter_queue = c.dead_letter_queue;
+			return consumer;
+		});
+		if (Object.keys(queues).length > 0) result.queues = queues;
+	}
+	if (bindings.durableObjects && bindings.durableObjects.length > 0) result.durable_objects = { bindings: bindings.durableObjects.map((dobj) => {
+		const entry = {
+			name: dobj.name,
+			class_name: dobj.class_name
+		};
+		if (dobj.script_name) entry.script_name = dobj.script_name;
+		return entry;
+	}) };
+	return result;
+}
+/**
+* One-level deep merge: for each key in `override`, if both the base and
+* override values are plain objects (not arrays, not null), merge their
+* keys with override winning on conflicts. Everything else (primitives,
+* arrays, null) is replaced outright — matching the intuitive behavior
+* where `kv_namespaces: [...]` replaces fully but
+* `durable_objects: { migrations }` merges with generated `bindings`.
+*/
+function shallowDeepMerge(base, override) {
+	const result = { ...base };
+	for (const key of Object.keys(override)) {
+		const baseVal = result[key];
+		const overVal = override[key];
+		if (isPlainObject(baseVal) && isPlainObject(overVal)) result[key] = {
+			...baseVal,
+			...overVal
+		};
+		else result[key] = overVal;
+	}
+	return result;
+}
+/** True for `{}` literals — false for arrays, null, Date, etc. */
+function isPlainObject(val) {
+	return val !== null && typeof val === "object" && !Array.isArray(val);
+}
 /** @internal Exported for testing. */
 function generateWranglerConfig(config, options) {
 	const base = {
@@ -148,11 +270,13 @@ function generateWranglerConfig(config, options) {
 		}],
 		assets: { directory: "./static" }
 	};
-	if (options.wrangler) return {
+	const bindingsConfig = generateBindingsConfig(options.bindings);
+	const merged = {
 		...base,
-		...options.wrangler
+		...bindingsConfig
 	};
-	return base;
+	if (options.wrangler) return shallowDeepMerge(merged, options.wrangler);
+	return merged;
 }
 /** @internal Exported for testing. */
 function generatePreviewCommand(buildDir) {
@@ -183,6 +307,6 @@ function spawnPreviewProcess(command, args, cwd) {
 	});
 }
 //#endregion
-export { cloudflare, generatePreviewCommand, generateWorkerEntry, generateWranglerConfig, getCloudflareBindings, runWithBindings, wrapWithExecutionContext };
+export { cloudflare, generateBindingsConfig, generatePreviewCommand, generateWorkerEntry, generateWranglerConfig, getCloudflareBindings, runWithBindings, wrapWithExecutionContext };
 
 //# sourceMappingURL=cloudflare.js.map