@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.190

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

@@ -0,0 +1,65 @@
+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[];
+        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,gBAAgB,CAAC;AAInD;;;;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,CA6CpE;CACF"}

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

@@ -0,0 +1,124 @@
+import { t as warnLossyJsonValue } from "../_chunks/json-lossy-check-ClNvBM_3.js";
+import { l as getCloudflareBindings } from "../_chunks/cloudflare-CGP6BZKO.js";
+//#region src/adapters/cloudflare-kv-cache.ts
+var LEGACY_GRACE_MS = 30 * 86400 * 1e3;
+/**
+* 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) {
+	if (!Array.isArray(raw)) return [];
+	const legacyDeadline = Date.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" })).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 entries = parseTagIndex(await kv.get(this.tagKey(tag), { type: "json" }));
+				const now = Date.now();
+				const filtered = entries.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" }));
+			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';\nimport { getCloudflareBindings } from './cloudflare';\nimport { warnLossyJsonValue } from '../cache/json-lossy-check.js';\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): TagIndexEntry[] {\n  if (!Array.isArray(raw)) return [];\n  const legacyDeadline = Date.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' }));\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 entries = parseTagIndex(await kv.get(this.tagKey(tag), { type: 'json' }));\n            const now = Date.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(await kv.get(this.tagKey(opts.tag), { type: 'json' }));\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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"}

package/dist/adapters/cloudflare.d.ts

@@ -20,14 +20,86 @@ 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.
+ * @internal Used by cloudflareDevBindings() to wrap dev-server requests.
  */
 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 {
+    /**
+     * Worker name used in the generated wrangler.jsonc.
+     * @default 'timber-app'
+     */
+    name?: string;
     /**
      * Cloudflare compatibility date.
      * @default Current date in YYYY-MM-DD format at build time.
@@ -38,11 +110,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.
@@ -58,20 +159,101 @@ export interface CloudflareAdapterOptions {
  * ```
  */
 export declare function cloudflare(options?: CloudflareAdapterOptions): TimberPlatformAdapter;
+/** @internal Exported for testing. */
+export declare function generateWorkerEntry(buildDir: string, outDir: string, hasManifestInit?: boolean, hasWorkerHandlers?: boolean): string;
+/** Build-time prebuilt data read from `.timber/dist/prebuilt/`. */
+export interface PrebuiltModuleData {
+    /** Raw manifest.json content. */
+    manifestJson: string;
+    /** Payload file paths and their raw bytes. */
+    payloads: Array<{
+        file: string;
+        bytes: Buffer;
+    }>;
+}
 /**
- * Wrap a timber request handler to bind the Cloudflare execution context
- * for `waitUntil()` support and env bindings passthrough.
- * Called from the generated worker entry.
+ * Discover and read prebuilt flight payload files from the build directory.
+ * Returns null when no prebuilt artifacts exist (no cache.component usage).
  *
- * This function:
- * 1. Binds `adapter.waitUntil()` to `ctx.waitUntil()` per-request
- * 2. Makes `env` accessible via `getCloudflareBindings()` per-request via ALS
+ * @internal Exported for testing.
  */
-export declare function wrapWithExecutionContext(adapter: TimberPlatformAdapter, handler: (req: Request) => Promise<Response>): ExportedHandler<Record<string, unknown>>;
-/** @internal Exported for testing. */
-export declare function generateWorkerEntry(buildDir: string, outDir: string, hasManifestInit?: boolean): string;
+export declare function readPrebuiltData(buildDir: string): Promise<PrebuiltModuleData | null>;
+/**
+ * Generate the prebuilt payload source module for Cloudflare Workers.
+ *
+ * Inlines manifest JSON and flight payload bytes directly into the module
+ * so they're part of the worker's JS bundle — no external Text/Data module
+ * imports needed. This avoids depending on wrangler's find_additional_modules
+ * to discover non-JS files, which doesn't reliably resolve Text/Data imports.
+ *
+ * @internal Exported for testing.
+ */
+export declare function generatePrebuiltSourceModule(data: PrebuiltModuleData | null): string;
+/**
+ * Generate the runtime init module that sets TIMBER_RUNTIME before the
+ * RSC entry evaluates. Imported as a side-effect module in _worker.js.
+ *
+ * @internal Exported for testing.
+ */
+export declare function generateRuntimeInitModule(): 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;
+/**
+ * Read the user's wrangler config from the project root, if one exists.
+ * Checks wrangler.jsonc first, then wrangler.json.
+ * @internal Exported for testing.
+ */
+export declare function readUserWranglerConfig(root: string): Promise<Record<string, unknown> | null>;
 /** @internal Exported for testing. */
-export declare function generateWranglerConfig(config: TimberConfig, options: CloudflareAdapterOptions): Record<string, unknown>;
+export declare function generateWranglerConfig(config: TimberConfig, options: CloudflareAdapterOptions, userConfig?: Record<string, unknown> | null): Record<string, unknown>;
+/**
+ * Build a Cloudflare Pages-compatible static output directory.
+ *
+ * No Workers entry — just pre-rendered HTML, RSC flight files, and client
+ * assets in a flat directory. Uses the shared buildStaticDirectoryOutput
+ * then adds a `_headers` file for cache control.
+ *
+ * @internal Exported for testing.
+ */
+export declare function buildStaticOutput(config: TimberConfig, buildDir: string, outDir: string, _options: CloudflareAdapterOptions): Promise<void>;
 /** Command descriptor for preview — testable without spawning a process. */
 export interface PreviewCommand {
     command: string;
@@ -80,13 +262,9 @@ 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;
 }
 //# 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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"}