@timber-js/app 0.1.0

package/dist/adapters/cloudflare.js

@@ -0,0 +1,188 @@
+import { join, relative } from "node:path";
+import { cp, mkdir, writeFile } from "node:fs/promises";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { execFile } from "node:child_process";
+//#region src/adapters/cloudflare.ts
+var IMMUTABLE_CACHE = "public, max-age=31536000, immutable";
+var STATIC_CACHE = "public, max-age=3600, must-revalidate";
+function generateHeadersFile() {
+	return `# Auto-generated by @timber/app — static asset cache headers.
+# See design/25-production-deployments.md §"CDN / Edge Cache"
+
+/assets/*
+  Cache-Control: ${IMMUTABLE_CACHE}
+
+/*
+  Cache-Control: ${STATIC_CACHE}
+`;
+}
+var bindingsAls = new AsyncLocalStorage();
+/**
+* Get Cloudflare Worker bindings for the current request.
+*
+* Returns the `env` object passed to the Worker's `fetch` handler,
+* giving direct access to KV, D1, Durable Objects, R2, Queues, and
+* any other bindings configured in `wrangler.jsonc`.
+*
+* Must be called within a request context (server component, middleware,
+* server action). Throws outside a request.
+*
+* @example
+* ```ts
+* import { getCloudflareBindings } from '@timber/app/adapters/cloudflare'
+*
+* export default async function Page() {
+*   const { MY_KV, MY_DB } = getCloudflareBindings()
+*   const data = await MY_KV.get('key')
+*   return <div>{data}</div>
+* }
+* ```
+*/
+function getCloudflareBindings() {
+	const env = bindingsAls.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;
+}
+/**
+* Run a function with Cloudflare bindings available via getCloudflareBindings().
+* @internal Used by wrapWithExecutionContext.
+*/
+function runWithBindings(env, fn) {
+	return bindingsAls.run(env, fn);
+}
+/**
+* Create a Cloudflare Workers adapter.
+*
+* @example
+* ```ts
+* import { cloudflare } from '@timber/app/adapters/cloudflare'
+*
+* export default {
+*   output: 'server',
+*   adapter: cloudflare(),
+* }
+* ```
+*/
+function cloudflare(options = {}) {
+	return {
+		name: "cloudflare",
+		async buildOutput(config, buildDir) {
+			const outDir = join(buildDir, "cloudflare");
+			await mkdir(outDir, { recursive: true });
+			const clientDir = join(buildDir, "client");
+			const staticDir = join(outDir, "static");
+			await mkdir(staticDir, { recursive: true });
+			await cp(clientDir, staticDir, {
+				recursive: true,
+				filter: config.clientJavascriptDisabled ? (src) => !src.endsWith(".js") : void 0
+			}).catch(() => {});
+			await writeFile(join(staticDir, "_headers"), generateHeadersFile());
+			const rscDir = join(buildDir, "rsc");
+			const ssrDir = join(buildDir, "ssr");
+			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);
+			await writeFile(join(outDir, "_worker.js"), workerEntry);
+			const wranglerConfig = generateWranglerConfig(config, options);
+			await writeFile(join(outDir, "wrangler.jsonc"), JSON.stringify(wranglerConfig, null, 2));
+		},
+		async preview(_config, buildDir) {
+			const cmd = generatePreviewCommand(buildDir);
+			await spawnPreviewProcess(cmd.command, cmd.args, cmd.cwd);
+		},
+		waitUntil(_promise) {}
+	};
+}
+/**
+* Wrap a timber request handler to bind the Cloudflare execution context
+* for `waitUntil()` support and env bindings passthrough.
+* Called from the generated worker entry.
+*
+* This function:
+* 1. Binds `adapter.waitUntil()` to `ctx.waitUntil()` per-request
+* 2. Makes `env` accessible via `getCloudflareBindings()` per-request via ALS
+*/
+function wrapWithExecutionContext(adapter, handler) {
+	return { async fetch(request, env, ctx) {
+		const originalWaitUntil = adapter.waitUntil;
+		adapter.waitUntil = (promise) => {
+			ctx.waitUntil(promise);
+		};
+		try {
+			return await runWithBindings(env, () => handler(request));
+		} finally {
+			adapter.waitUntil = originalWaitUntil;
+		}
+	} };
+}
+/** @internal Exported for testing. */
+function generateWorkerEntry(buildDir, outDir, hasManifestInit = false) {
+	let rscEntryRelative = relative(outDir, join(buildDir, "rsc", "index.js"));
+	if (!rscEntryRelative.startsWith(".")) rscEntryRelative = "./" + rscEntryRelative;
+	return `// Generated by @timber/app/adapters/cloudflare
+// Do not edit — this file is regenerated on each build.
+
+${hasManifestInit ? "import './_timber-manifest-init.js'\n" : ""}import handler from '${rscEntryRelative}'
+
+// 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 }
+`;
+}
+/** @internal Exported for testing. */
+function generateWranglerConfig(config, options) {
+	const base = {
+		name: "timber-app",
+		main: "_worker.js",
+		compatibility_date: options.compatibilityDate ?? (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
+		compatibility_flags: options.compatibilityFlags ?? ["nodejs_compat"],
+		no_bundle: true,
+		find_additional_modules: true,
+		rules: [{
+			type: "ESModule",
+			globs: ["**/*.js"]
+		}],
+		assets: { directory: "./static" }
+	};
+	if (options.wrangler) return {
+		...base,
+		...options.wrangler
+	};
+	return base;
+}
+/** @internal Exported for testing. */
+function generatePreviewCommand(buildDir) {
+	const cfDir = join(buildDir, "cloudflare");
+	return {
+		command: "wrangler",
+		args: [
+			"dev",
+			"--local",
+			"--config",
+			join(cfDir, "wrangler.jsonc")
+		],
+		cwd: cfDir
+	};
+}
+/**
+* Spawn a long-running preview process and pipe stdio to the parent.
+* Resolves when the process exits.
+*/
+function spawnPreviewProcess(command, args, cwd) {
+	return new Promise((resolve, reject) => {
+		const child = execFile(command, args, { cwd }, (err) => {
+			if (err) reject(err);
+			else resolve();
+		});
+		child.stdout?.pipe(process.stdout);
+		child.stderr?.pipe(process.stderr);
+	});
+}
+//#endregion
+export { cloudflare, generatePreviewCommand, generateWorkerEntry, generateWranglerConfig, getCloudflareBindings, runWithBindings, wrapWithExecutionContext };
+
+//# sourceMappingURL=cloudflare.js.map

package/dist/adapters/cloudflare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare.js","names":[],"sources":["../../src/adapters/cloudflare.ts"],"sourcesContent":["// Cloudflare Workers adapter\n//\n// Primary deployment target. Generates a Workers-compatible entry point\n// and wrangler.jsonc configuration. See design/11-platform.md §\"Cloudflare Workers\".\n\nimport { writeFile, mkdir, cp } from 'node:fs/promises';\nimport { execFile } from 'node:child_process';\nimport { join, relative } from 'node:path';\nimport { AsyncLocalStorage } from 'node:async_hooks';\nimport type { TimberPlatformAdapter, TimberConfig } from './types';\n// Inlined from server/asset-headers.ts — adapters are loaded by Node at\n// Vite startup time, before Vite's module resolver is available, so cross-\n// directory .ts imports don't resolve.\nconst IMMUTABLE_CACHE = 'public, max-age=31536000, immutable';\nconst STATIC_CACHE = 'public, max-age=3600, must-revalidate';\n\nfunction generateHeadersFile(): string {\n  return `# Auto-generated by @timber/app — static asset cache headers.\n# See design/25-production-deployments.md §\"CDN / Edge Cache\"\n\n/assets/*\n  Cache-Control: ${IMMUTABLE_CACHE}\n\n/*\n  Cache-Control: ${STATIC_CACHE}\n`;\n}\n\n// ─── Bindings passthrough ─────────────────────────────────────────────────\n// ALS stores the env object per-request so server components and middleware\n// can access KV, D1, DO, R2, Queues, etc. via getCloudflareBindings().\n// No global fallback — if called outside a request, it throws.\n// See design/11-platform.md §\"Platform Target\" and design/25-production-deployments.md.\n\nconst bindingsAls = new AsyncLocalStorage<Record<string, unknown>>();\n\n/**\n * Get Cloudflare Worker bindings for the current request.\n *\n * Returns the `env` object passed to the Worker's `fetch` handler,\n * giving direct access to KV, D1, Durable Objects, R2, Queues, and\n * any other bindings configured in `wrangler.jsonc`.\n *\n * Must be called within a request context (server component, middleware,\n * server action). Throws outside a request.\n *\n * @example\n * ```ts\n * import { getCloudflareBindings } from '@timber/app/adapters/cloudflare'\n *\n * export default async function Page() {\n *   const { MY_KV, MY_DB } = getCloudflareBindings()\n *   const data = await MY_KV.get('key')\n *   return <div>{data}</div>\n * }\n * ```\n */\nexport function getCloudflareBindings<\n  T extends Record<string, unknown> = Record<string, unknown>,\n>(): T {\n  const env = bindingsAls.getStore();\n  if (!env) {\n    throw new Error(\n      'getCloudflareBindings() called outside a Cloudflare Workers request context. ' +\n        'It can only be called from server components, middleware, or server actions ' +\n        'when running on the Cloudflare adapter.'\n    );\n  }\n  return env as T;\n}\n\n/**\n * Run a function with Cloudflare bindings available via getCloudflareBindings().\n * @internal Used by wrapWithExecutionContext.\n */\nexport function runWithBindings<T>(env: Record<string, unknown>, fn: () => T): T {\n  return bindingsAls.run(env, fn);\n}\n\n/** Options for the Cloudflare Workers adapter. */\nexport interface CloudflareAdapterOptions {\n  /**\n   * Cloudflare compatibility date.\n   * @default Current date in YYYY-MM-DD format at build time.\n   */\n  compatibilityDate?: string;\n\n  /**\n   * Additional compatibility flags.\n   * @default ['nodejs_compat']\n   */\n  compatibilityFlags?: string[];\n\n  /**\n   * Custom wrangler.jsonc fields to merge.\n   * Overrides generated values.\n   */\n  wrangler?: Record<string, unknown>;\n}\n\n/**\n * Create a Cloudflare Workers adapter.\n *\n * @example\n * ```ts\n * import { cloudflare } from '@timber/app/adapters/cloudflare'\n *\n * export default {\n *   output: 'server',\n *   adapter: cloudflare(),\n * }\n * ```\n */\nexport function cloudflare(options: CloudflareAdapterOptions = {}): TimberPlatformAdapter {\n  return {\n    name: 'cloudflare',\n\n    async buildOutput(config: TimberConfig, buildDir: string) {\n      const outDir = join(buildDir, 'cloudflare');\n      await mkdir(outDir, { recursive: true });\n\n      // Copy client assets to static output.\n      // When client JavaScript is disabled, skip .js files — only CSS,\n      // fonts, images, and other static assets are needed.\n      const clientDir = join(buildDir, 'client');\n      const staticDir = join(outDir, 'static');\n      await mkdir(staticDir, { recursive: true });\n      await cp(clientDir, staticDir, {\n        recursive: true,\n        filter: config.clientJavascriptDisabled ? (src: string) => !src.endsWith('.js') : undefined,\n      }).catch(() => {\n        // Client dir may not exist when client JavaScript is disabled\n      });\n\n      // Write _headers file for static asset cache control.\n      // Cloudflare Workers Static Assets reads this to set Cache-Control\n      // headers on responses. Hashed assets get immutable; others get 1h.\n      await writeFile(join(staticDir, '_headers'), generateHeadersFile());\n\n      // Copy server bundles (rsc + ssr) into the output directory.\n      // These are already fully bundled by Vite with resolve.noExternal: true.\n      const rscDir = join(buildDir, 'rsc');\n      const ssrDir = join(buildDir, 'ssr');\n      await cp(rscDir, join(outDir, 'rsc'), { recursive: true });\n      await cp(ssrDir, join(outDir, 'ssr'), { recursive: true });\n\n      // Write the build manifest init module (if manifest data was produced).\n      // This must be imported before the RSC handler so the global is set\n      // when virtual:timber-build-manifest evaluates.\n      if (config.manifestInit) {\n        await writeFile(join(outDir, '_timber-manifest-init.js'), config.manifestInit);\n      }\n\n      // Generate the Workers entry point\n      const hasManifestInit = !!config.manifestInit;\n      const workerEntry = generateWorkerEntry(outDir, outDir, hasManifestInit);\n      await writeFile(join(outDir, '_worker.js'), workerEntry);\n\n      // Generate wrangler.jsonc\n      const wranglerConfig = generateWranglerConfig(config, options);\n      await writeFile(join(outDir, 'wrangler.jsonc'), JSON.stringify(wranglerConfig, null, 2));\n    },\n\n    async preview(_config: TimberConfig, buildDir: string) {\n      const cmd = generatePreviewCommand(buildDir);\n      await spawnPreviewProcess(cmd.command, cmd.args, cmd.cwd);\n    },\n\n    // Default no-op. wrapWithExecutionContext() replaces this per-request\n    // with a function that routes to ctx.waitUntil().\n    waitUntil(_promise: Promise<unknown>) {},\n  };\n}\n\n/**\n * Wrap a timber request handler to bind the Cloudflare execution context\n * for `waitUntil()` support and env bindings passthrough.\n * Called from the generated worker entry.\n *\n * This function:\n * 1. Binds `adapter.waitUntil()` to `ctx.waitUntil()` per-request\n * 2. Makes `env` accessible via `getCloudflareBindings()` per-request via ALS\n */\nexport function wrapWithExecutionContext(\n  adapter: TimberPlatformAdapter,\n  handler: (req: Request) => Promise<Response>\n): ExportedHandler<Record<string, unknown>> {\n  return {\n    async fetch(\n      request: Request,\n      env: Record<string, unknown>,\n      ctx: ExecutionContext\n    ): Promise<Response> {\n      // Bind the adapter's waitUntil to the Workers execution context\n      const originalWaitUntil = adapter.waitUntil;\n      adapter.waitUntil = (promise: Promise<unknown>) => {\n        ctx.waitUntil(promise);\n      };\n\n      try {\n        // Run the handler within ALS so getCloudflareBindings() works\n        return await runWithBindings(env, () => handler(request));\n      } finally {\n        // Restore (in case adapter is reused across isolate resets)\n        adapter.waitUntil = originalWaitUntil;\n      }\n    },\n  };\n}\n\n// ─── Exported helpers (used by tests and build) ─────────────────────────────\n\n/** @internal Exported for testing. */\nexport function generateWorkerEntry(\n  buildDir: string,\n  outDir: string,\n  hasManifestInit = false\n): string {\n  // The RSC entry is the main request handler — it exports the fetch handler as default.\n  // The Vite RSC plugin outputs it to rsc/index.js.\n  let rscEntryRelative = relative(outDir, join(buildDir, 'rsc', 'index.js'));\n  // Ensure the import path starts with ./ for ESM compatibility\n  if (!rscEntryRelative.startsWith('.')) {\n    rscEntryRelative = './' + rscEntryRelative;\n  }\n\n  // Build manifest init must be imported before the RSC handler so that\n  // globalThis.__TIMBER_BUILD_MANIFEST__ is set when the virtual module evaluates.\n  // ESM guarantees imports are evaluated in order.\n  const manifestImport = hasManifestInit ? \"import './_timber-manifest-init.js'\\n\" : '';\n\n  return `// Generated by @timber/app/adapters/cloudflare\n// Do not edit — this file is regenerated on each build.\n\n${manifestImport}import handler from '${rscEntryRelative}'\n\n// Set TIMBER_RUNTIME for instrumentation.ts conditional SDK initialization.\n// See design/25-production-deployments.md §\"TIMBER_RUNTIME\".\nglobalThis.process ??= { env: {} }\nprocess.env.TIMBER_RUNTIME = 'cloudflare'\n\nexport default { fetch: handler }\n`;\n}\n\n/** @internal Exported for testing. */\nexport function generateWranglerConfig(\n  config: TimberConfig,\n  options: CloudflareAdapterOptions\n): Record<string, unknown> {\n  const compatDate = options.compatibilityDate ?? new Date().toISOString().slice(0, 10);\n\n  const flags = options.compatibilityFlags ?? ['nodejs_compat'];\n\n  const base: Record<string, unknown> = {\n    name: 'timber-app',\n    main: '_worker.js',\n    compatibility_date: compatDate,\n    compatibility_flags: flags,\n    // The build output is already fully bundled by Vite — skip wrangler's\n    // esbuild pass to avoid issues with top-level await and module format.\n    no_bundle: true,\n    find_additional_modules: true,\n    rules: [{ type: 'ESModule', globs: ['**/*.js'] }],\n    assets: {\n      directory: './static',\n    },\n  };\n\n  // Merge user overrides\n  if (options.wrangler) {\n    return { ...base, ...options.wrangler };\n  }\n\n  return base;\n}\n\n// ─── Preview ─────────────────────────────────────────────────────────────────\n\n/** Command descriptor for preview — testable without spawning a process. */\nexport interface PreviewCommand {\n  command: string;\n  args: string[];\n  cwd: string;\n}\n\n/** @internal Exported for testing. */\nexport function generatePreviewCommand(buildDir: string): PreviewCommand {\n  const cfDir = join(buildDir, 'cloudflare');\n  return {\n    command: 'wrangler',\n    args: ['dev', '--local', '--config', join(cfDir, 'wrangler.jsonc')],\n    cwd: cfDir,\n  };\n}\n\n/**\n * Spawn a long-running preview process and pipe stdio to the parent.\n * Resolves when the process exits.\n */\nfunction spawnPreviewProcess(command: string, args: string[], cwd: string): Promise<void> {\n  return new Promise<void>((resolve, reject) => {\n    const child = execFile(command, args, { cwd }, (err) => {\n      if (err) reject(err);\n      else resolve();\n    });\n    child.stdout?.pipe(process.stdout);\n    child.stderr?.pipe(process.stderr);\n  });\n}\n\n// ─── Cloudflare Workers type stubs ───────────────────────────────────────────\n// Minimal type declarations so this file compiles without @cloudflare/workers-types.\n// In production builds, users install @cloudflare/workers-types themselves.\n\ndeclare global {\n  interface ExecutionContext {\n    waitUntil(promise: Promise<unknown>): void;\n    passThroughOnException(): void;\n  }\n\n  interface ExportedHandler<Env = Record<string, unknown>> {\n    fetch?(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> | Response;\n  }\n}\n"],"mappings":"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"}

package/dist/adapters/nitro.d.ts

@@ -0,0 +1,72 @@
+import type { TimberPlatformAdapter } from './types';
+/**
+ * Supported Nitro deployment presets.
+ *
+ * Each preset maps to a Nitro deployment target. The adapter generates
+ * the appropriate configuration and entry point for the selected platform.
+ */
+export type NitroPreset = 'vercel' | 'vercel-edge' | 'netlify' | 'netlify-edge' | 'aws-lambda' | 'deno-deploy' | 'azure-functions' | 'node-server' | 'bun';
+/** Preset-specific Nitro configuration. */
+interface PresetConfig {
+    /** Nitro preset name passed to the Nitro build. */
+    nitroPreset: string;
+    /** Output directory name within the build dir. */
+    outputDir: string;
+    /** Whether the runtime supports waitUntil. */
+    supportsWaitUntil: boolean;
+    /** Whether the runtime supports application-level 103 Early Hints. */
+    supportsEarlyHints: boolean;
+    /** Value for TIMBER_RUNTIME env var. See design/25-production-deployments.md. */
+    runtimeName: string;
+    /** Additional nitro.config fields for this preset. */
+    extraConfig?: Record<string, unknown>;
+}
+/** Options for the Nitro adapter. */
+export interface NitroAdapterOptions {
+    /**
+     * Deployment preset. Determines the target platform.
+     * @default 'node-server'
+     */
+    preset?: NitroPreset;
+    /**
+     * Additional Nitro configuration to merge into the generated config.
+     * Overrides default values for the selected preset.
+     */
+    nitroConfig?: Record<string, unknown>;
+}
+/**
+ * Create a Nitro-based adapter for multi-platform deployment.
+ *
+ * Nitro abstracts deployment targets — the same timber.js app can deploy
+ * to Vercel, Netlify, AWS, Deno Deploy, or Azure by changing the preset.
+ *
+ * @example
+ * ```ts
+ * import { nitro } from '@timber/app/adapters/nitro'
+ *
+ * export default {
+ *   output: 'server',
+ *   adapter: nitro({ preset: 'vercel' }),
+ * }
+ * ```
+ */
+export declare function nitro(options?: NitroAdapterOptions): TimberPlatformAdapter;
+/** @internal Exported for testing. */
+export declare function generateNitroEntry(buildDir: string, outDir: string, preset: NitroPreset, hasManifestInit?: boolean): string;
+/** @internal Exported for testing. */
+export declare function generateNitroConfig(preset: NitroPreset, userConfig?: Record<string, unknown>): string;
+/** Command descriptor for Nitro preview — testable without spawning. */
+export interface NitroPreviewCommand {
+    command: string;
+    args: string[];
+    cwd: string;
+}
+/** @internal Exported for testing. */
+export declare function generateNitroPreviewCommand(buildDir: string, preset: NitroPreset): NitroPreviewCommand | null;
+/**
+ * Get the preset configuration for a given preset name.
+ * @internal Exported for testing.
+ */
+export declare function getPresetConfig(preset: NitroPreset): PresetConfig;
+export {};
+//# sourceMappingURL=nitro.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"nitro.d.ts","sourceRoot":"","sources":["../../src/adapters/nitro.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,qBAAqB,EAAgB,MAAM,SAAS,CAAC;AAqBnE;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GACnB,QAAQ,GACR,aAAa,GACb,SAAS,GACT,cAAc,GACd,YAAY,GACZ,aAAa,GACb,iBAAiB,GACjB,aAAa,GACb,KAAK,CAAC;AAEV,2CAA2C;AAC3C,UAAU,YAAY;IACpB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,iBAAiB,EAAE,OAAO,CAAC;IAC3B,sEAAsE;IACtE,kBAAkB,EAAE,OAAO,CAAC;IAC5B,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAuED,qCAAqC;AACrC,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IAErB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,KAAK,CAAC,OAAO,GAAE,mBAAwB,GAAG,qBAAqB,CAgE9E;AAID,sCAAsC;AACtC,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,WAAW,EACnB,eAAe,UAAQ,GACtB,MAAM,CA2CR;AAED,sCAAsC;AACtC,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,EACnB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,MAAM,CAwBR;AAOD,wEAAwE;AACxE,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb;AAED,sCAAsC;AACtC,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,WAAW,GAClB,mBAAmB,GAAG,IAAI,CAY5B;AAgBD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,CAEjE"}

package/dist/adapters/nitro.js

@@ -0,0 +1,217 @@
+import { join, relative } from "node:path";
+import { cp, mkdir, writeFile } from "node:fs/promises";
+import { execFile } from "node:child_process";
+//#region src/adapters/nitro.ts
+var IMMUTABLE_CACHE = "public, max-age=31536000, immutable";
+var STATIC_CACHE = "public, max-age=3600, must-revalidate";
+function generateHeadersFile() {
+	return `# Auto-generated by @timber/app — static asset cache headers.
+# See design/25-production-deployments.md §"CDN / Edge Cache"
+
+/assets/*
+  Cache-Control: ${IMMUTABLE_CACHE}
+
+/*
+  Cache-Control: ${STATIC_CACHE}
+`;
+}
+var PRESET_CONFIGS = {
+	"vercel": {
+		nitroPreset: "vercel",
+		outputDir: ".vercel/output",
+		supportsWaitUntil: true,
+		supportsEarlyHints: false,
+		runtimeName: "vercel",
+		extraConfig: { vercel: { functions: { maxDuration: 30 } } }
+	},
+	"vercel-edge": {
+		nitroPreset: "vercel-edge",
+		outputDir: ".vercel/output",
+		supportsWaitUntil: true,
+		supportsEarlyHints: false,
+		runtimeName: "vercel-edge"
+	},
+	"netlify": {
+		nitroPreset: "netlify",
+		outputDir: ".netlify/functions-internal",
+		supportsWaitUntil: false,
+		supportsEarlyHints: false,
+		runtimeName: "netlify"
+	},
+	"netlify-edge": {
+		nitroPreset: "netlify-edge",
+		outputDir: ".netlify/edge-functions",
+		supportsWaitUntil: true,
+		supportsEarlyHints: false,
+		runtimeName: "netlify-edge"
+	},
+	"aws-lambda": {
+		nitroPreset: "aws-lambda",
+		outputDir: ".output",
+		supportsWaitUntil: false,
+		supportsEarlyHints: false,
+		runtimeName: "aws-lambda"
+	},
+	"deno-deploy": {
+		nitroPreset: "deno-deploy",
+		outputDir: ".output",
+		supportsWaitUntil: true,
+		supportsEarlyHints: false,
+		runtimeName: "deno-deploy"
+	},
+	"azure-functions": {
+		nitroPreset: "azure-functions",
+		outputDir: ".output",
+		supportsWaitUntil: false,
+		supportsEarlyHints: false,
+		runtimeName: "azure-functions"
+	},
+	"node-server": {
+		nitroPreset: "node-server",
+		outputDir: ".output",
+		supportsWaitUntil: true,
+		supportsEarlyHints: true,
+		runtimeName: "node-server"
+	},
+	"bun": {
+		nitroPreset: "bun",
+		outputDir: ".output",
+		supportsWaitUntil: true,
+		supportsEarlyHints: true,
+		runtimeName: "bun"
+	}
+};
+/**
+* Create a Nitro-based adapter for multi-platform deployment.
+*
+* Nitro abstracts deployment targets — the same timber.js app can deploy
+* to Vercel, Netlify, AWS, Deno Deploy, or Azure by changing the preset.
+*
+* @example
+* ```ts
+* import { nitro } from '@timber/app/adapters/nitro'
+*
+* export default {
+*   output: 'server',
+*   adapter: nitro({ preset: 'vercel' }),
+* }
+* ```
+*/
+function nitro(options = {}) {
+	const preset = options.preset ?? "node-server";
+	const presetConfig = PRESET_CONFIGS[preset];
+	const pendingPromises = [];
+	return {
+		name: `nitro-${preset}`,
+		async buildOutput(config, buildDir) {
+			const outDir = join(buildDir, "nitro");
+			await mkdir(outDir, { recursive: true });
+			const clientDir = join(buildDir, "client");
+			const publicDir = join(outDir, "public");
+			await mkdir(publicDir, { recursive: true });
+			await cp(clientDir, publicDir, {
+				recursive: true,
+				filter: config.clientJavascriptDisabled ? (src) => !src.endsWith(".js") : void 0
+			}).catch(() => {});
+			await writeFile(join(publicDir, "_headers"), generateHeadersFile());
+			if (config.manifestInit) await writeFile(join(outDir, "_timber-manifest-init.js"), config.manifestInit);
+			const entry = generateNitroEntry(buildDir, outDir, preset, !!config.manifestInit);
+			await writeFile(join(outDir, "entry.ts"), entry);
+			const nitroConfig = generateNitroConfig(preset, options.nitroConfig);
+			await writeFile(join(outDir, "nitro.config.ts"), nitroConfig);
+		},
+		preview: LOCALLY_PREVIEWABLE.has(preset) ? async (_config, buildDir) => {
+			const cmd = generateNitroPreviewCommand(buildDir, preset);
+			if (!cmd) return;
+			await spawnNitroPreview(cmd.command, cmd.args, cmd.cwd);
+		} : void 0,
+		waitUntil: presetConfig.supportsWaitUntil ? (promise) => {
+			const tracked = promise.catch((err) => {
+				console.error("[timber] waitUntil promise rejected:", err);
+			});
+			pendingPromises.push(tracked);
+		} : void 0
+	};
+}
+/** @internal Exported for testing. */
+function generateNitroEntry(buildDir, outDir, preset, hasManifestInit = false) {
+	const serverEntryRelative = relative(outDir, join(buildDir, "server", "entry.js"));
+	const runtimeName = PRESET_CONFIGS[preset].runtimeName;
+	const earlyHints = PRESET_CONFIGS[preset].supportsEarlyHints;
+	return `// Generated by @timber/app/adapters/nitro
+// Do not edit — this file is regenerated on each build.
+
+${hasManifestInit ? "import './_timber-manifest-init.js'\n" : ""}${earlyHints ? `import { runWithEarlyHintsSender } from '${serverEntryRelative}'\n` : ""}import { defineEventHandler, toWebRequest, sendWebResponse } from 'h3'
+import { handler } from '${serverEntryRelative}'
+
+// Set TIMBER_RUNTIME for instrumentation.ts conditional SDK initialization.
+// See design/25-production-deployments.md §"TIMBER_RUNTIME".
+process.env.TIMBER_RUNTIME = '${runtimeName}'
+
+export default defineEventHandler(async (event) => {
+  const webRequest = toWebRequest(event)
+${earlyHints ? `  const nodeRes = event.node?.res
+  const earlyHintsSender = (typeof nodeRes?.writeEarlyHints === 'function')
+    ? (links) => { try { nodeRes.writeEarlyHints({ link: links }) } catch {} }
+    : undefined
+
+  const webResponse = earlyHintsSender
+    ? await runWithEarlyHintsSender(earlyHintsSender, () => handler(webRequest))
+    : await handler(webRequest)` : `  const webResponse = await handler(webRequest)`}
+  return sendWebResponse(event, webResponse)
+})
+`;
+}
+/** @internal Exported for testing. */
+function generateNitroConfig(preset, userConfig) {
+	const presetConfig = PRESET_CONFIGS[preset];
+	const config = {
+		preset: presetConfig.nitroPreset,
+		output: { dir: presetConfig.outputDir },
+		routeRules: { "/assets/**": { headers: { "Cache-Control": IMMUTABLE_CACHE } } },
+		...presetConfig.extraConfig,
+		...userConfig
+	};
+	return `// Generated by @timber/app/adapters/nitro
+// Do not edit — this file is regenerated on each build.
+
+import { defineNitroConfig } from 'nitropack/config'
+
+export default defineNitroConfig(${JSON.stringify(config, null, 2)})
+`;
+}
+/** Presets that produce a locally-runnable server entry. */
+var LOCALLY_PREVIEWABLE = new Set(["node-server", "bun"]);
+/** @internal Exported for testing. */
+function generateNitroPreviewCommand(buildDir, preset) {
+	if (!LOCALLY_PREVIEWABLE.has(preset)) return null;
+	const nitroDir = join(buildDir, "nitro");
+	const entryPath = join(nitroDir, "entry.ts");
+	return {
+		command: preset === "bun" ? "bun" : "node",
+		args: [entryPath],
+		cwd: nitroDir
+	};
+}
+/** Spawn a Nitro preview process and pipe stdio. */
+function spawnNitroPreview(command, args, cwd) {
+	return new Promise((resolve, reject) => {
+		const child = execFile(command, args, { cwd }, (err) => {
+			if (err) reject(err);
+			else resolve();
+		});
+		child.stdout?.pipe(process.stdout);
+		child.stderr?.pipe(process.stderr);
+	});
+}
+/**
+* Get the preset configuration for a given preset name.
+* @internal Exported for testing.
+*/
+function getPresetConfig(preset) {
+	return PRESET_CONFIGS[preset];
+}
+//#endregion
+export { generateNitroConfig, generateNitroEntry, generateNitroPreviewCommand, getPresetConfig, nitro };
+
+//# sourceMappingURL=nitro.js.map

package/dist/adapters/nitro.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nitro.js","names":[],"sources":["../../src/adapters/nitro.ts"],"sourcesContent":["// Nitro adapter — multi-platform deployment\n//\n// Covers everything except Cloudflare Workers: Node.js, Bun, Vercel,\n// Netlify, AWS Lambda, Deno Deploy, Azure Functions. Nitro handles\n// compression, graceful shutdown, static file serving, and platform quirks.\n// See design/11-platform.md and design/25-production-deployments.md.\n\nimport { writeFile, mkdir, cp } from 'node:fs/promises';\nimport { execFile } from 'node:child_process';\nimport { join, relative } from 'node:path';\nimport type { TimberPlatformAdapter, TimberConfig } from './types';\n// Inlined from server/asset-headers.ts — adapters are loaded by Node at\n// Vite startup time, before Vite's module resolver is available, so cross-\n// directory .ts imports don't resolve.\nconst IMMUTABLE_CACHE = 'public, max-age=31536000, immutable';\nconst STATIC_CACHE = 'public, max-age=3600, must-revalidate';\n\nfunction generateHeadersFile(): string {\n  return `# Auto-generated by @timber/app — static asset cache headers.\n# See design/25-production-deployments.md §\"CDN / Edge Cache\"\n\n/assets/*\n  Cache-Control: ${IMMUTABLE_CACHE}\n\n/*\n  Cache-Control: ${STATIC_CACHE}\n`;\n}\n\n// ─── Presets ─────────────────────────────────────────────────────────────────\n\n/**\n * Supported Nitro deployment presets.\n *\n * Each preset maps to a Nitro deployment target. The adapter generates\n * the appropriate configuration and entry point for the selected platform.\n */\nexport type NitroPreset =\n  | 'vercel'\n  | 'vercel-edge'\n  | 'netlify'\n  | 'netlify-edge'\n  | 'aws-lambda'\n  | 'deno-deploy'\n  | 'azure-functions'\n  | 'node-server'\n  | 'bun';\n\n/** Preset-specific Nitro configuration. */\ninterface PresetConfig {\n  /** Nitro preset name passed to the Nitro build. */\n  nitroPreset: string;\n  /** Output directory name within the build dir. */\n  outputDir: string;\n  /** Whether the runtime supports waitUntil. */\n  supportsWaitUntil: boolean;\n  /** Whether the runtime supports application-level 103 Early Hints. */\n  supportsEarlyHints: boolean;\n  /** Value for TIMBER_RUNTIME env var. See design/25-production-deployments.md. */\n  runtimeName: string;\n  /** Additional nitro.config fields for this preset. */\n  extraConfig?: Record<string, unknown>;\n}\n\nconst PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {\n  'vercel': {\n    nitroPreset: 'vercel',\n    outputDir: '.vercel/output',\n    supportsWaitUntil: true,\n    supportsEarlyHints: false,\n    runtimeName: 'vercel',\n    extraConfig: { vercel: { functions: { maxDuration: 30 } } },\n  },\n  'vercel-edge': {\n    nitroPreset: 'vercel-edge',\n    outputDir: '.vercel/output',\n    supportsWaitUntil: true,\n    supportsEarlyHints: false,\n    runtimeName: 'vercel-edge',\n  },\n  'netlify': {\n    nitroPreset: 'netlify',\n    outputDir: '.netlify/functions-internal',\n    supportsWaitUntil: false,\n    supportsEarlyHints: false,\n    runtimeName: 'netlify',\n  },\n  'netlify-edge': {\n    nitroPreset: 'netlify-edge',\n    outputDir: '.netlify/edge-functions',\n    supportsWaitUntil: true,\n    supportsEarlyHints: false,\n    runtimeName: 'netlify-edge',\n  },\n  'aws-lambda': {\n    nitroPreset: 'aws-lambda',\n    outputDir: '.output',\n    supportsWaitUntil: false,\n    supportsEarlyHints: false,\n    runtimeName: 'aws-lambda',\n  },\n  'deno-deploy': {\n    nitroPreset: 'deno-deploy',\n    outputDir: '.output',\n    supportsWaitUntil: true,\n    supportsEarlyHints: false,\n    runtimeName: 'deno-deploy',\n  },\n  'azure-functions': {\n    nitroPreset: 'azure-functions',\n    outputDir: '.output',\n    supportsWaitUntil: false,\n    supportsEarlyHints: false,\n    runtimeName: 'azure-functions',\n  },\n  'node-server': {\n    nitroPreset: 'node-server',\n    outputDir: '.output',\n    supportsWaitUntil: true,\n    supportsEarlyHints: true,\n    runtimeName: 'node-server',\n  },\n  'bun': {\n    nitroPreset: 'bun',\n    outputDir: '.output',\n    supportsWaitUntil: true,\n    supportsEarlyHints: true,\n    runtimeName: 'bun',\n  },\n};\n\n// ─── Options ─────────────────────────────────────────────────────────────────\n\n/** Options for the Nitro adapter. */\nexport interface NitroAdapterOptions {\n  /**\n   * Deployment preset. Determines the target platform.\n   * @default 'node-server'\n   */\n  preset?: NitroPreset;\n\n  /**\n   * Additional Nitro configuration to merge into the generated config.\n   * Overrides default values for the selected preset.\n   */\n  nitroConfig?: Record<string, unknown>;\n}\n\n// ─── Adapter ─────────────────────────────────────────────────────────────────\n\n/**\n * Create a Nitro-based adapter for multi-platform deployment.\n *\n * Nitro abstracts deployment targets — the same timber.js app can deploy\n * to Vercel, Netlify, AWS, Deno Deploy, or Azure by changing the preset.\n *\n * @example\n * ```ts\n * import { nitro } from '@timber/app/adapters/nitro'\n *\n * export default {\n *   output: 'server',\n *   adapter: nitro({ preset: 'vercel' }),\n * }\n * ```\n */\nexport function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter {\n  const preset = options.preset ?? 'node-server';\n  const presetConfig = PRESET_CONFIGS[preset];\n  const pendingPromises: Promise<unknown>[] = [];\n\n  return {\n    name: `nitro-${preset}`,\n\n    async buildOutput(config: TimberConfig, buildDir: string) {\n      const outDir = join(buildDir, 'nitro');\n      await mkdir(outDir, { recursive: true });\n\n      // Copy client assets to public directory.\n      // When client JavaScript is disabled, skip .js files — only CSS,\n      // fonts, images, and other static assets are needed.\n      const clientDir = join(buildDir, 'client');\n      const publicDir = join(outDir, 'public');\n      await mkdir(publicDir, { recursive: true });\n      await cp(clientDir, publicDir, {\n        recursive: true,\n        filter: config.clientJavascriptDisabled ? (src: string) => !src.endsWith('.js') : undefined,\n      }).catch(() => {\n        // Client dir may not exist when client JavaScript is disabled\n      });\n\n      // Write _headers file for platforms that support it (Netlify, etc.).\n      // See design/25-production-deployments.md §\"CDN / Edge Cache\"\n      await writeFile(join(publicDir, '_headers'), generateHeadersFile());\n\n      // Write the build manifest init module (if manifest data was produced).\n      if (config.manifestInit) {\n        await writeFile(join(outDir, '_timber-manifest-init.js'), config.manifestInit);\n      }\n\n      // Generate the Nitro entry point\n      const hasManifestInit = !!config.manifestInit;\n      const entry = generateNitroEntry(buildDir, outDir, preset, hasManifestInit);\n      await writeFile(join(outDir, 'entry.ts'), entry);\n\n      // Generate the Nitro config with static asset cache rules\n      const nitroConfig = generateNitroConfig(preset, options.nitroConfig);\n      await writeFile(join(outDir, 'nitro.config.ts'), nitroConfig);\n    },\n\n    // Only presets that produce a locally-runnable server get preview().\n    // Serverless presets (vercel, netlify, aws-lambda, etc.) have no\n    // local runtime — Vite's built-in preview is the fallback.\n    preview: LOCALLY_PREVIEWABLE.has(preset)\n      ? async (_config: TimberConfig, buildDir: string) => {\n          const cmd = generateNitroPreviewCommand(buildDir, preset);\n          if (!cmd) return;\n          await spawnNitroPreview(cmd.command, cmd.args, cmd.cwd);\n        }\n      : undefined,\n\n    waitUntil: presetConfig.supportsWaitUntil\n      ? (promise: Promise<unknown>) => {\n          const tracked = promise.catch((err) => {\n            console.error('[timber] waitUntil promise rejected:', err);\n          });\n          pendingPromises.push(tracked);\n        }\n      : undefined,\n  };\n}\n\n// ─── Entry Generation ────────────────────────────────────────────────────────\n\n/** @internal Exported for testing. */\nexport function generateNitroEntry(\n  buildDir: string,\n  outDir: string,\n  preset: NitroPreset,\n  hasManifestInit = false\n): string {\n  const serverEntryRelative = relative(outDir, join(buildDir, 'server', 'entry.js'));\n  const runtimeName = PRESET_CONFIGS[preset].runtimeName;\n  const earlyHints = PRESET_CONFIGS[preset].supportsEarlyHints;\n\n  // Build manifest init must be imported before the handler so that\n  // globalThis.__TIMBER_BUILD_MANIFEST__ is set when the virtual module evaluates.\n  const manifestImport = hasManifestInit ? \"import './_timber-manifest-init.js'\\n\" : '';\n\n  // On node-server and bun, wrap the handler with ALS so the pipeline\n  // can send 103 Early Hints via res.writeEarlyHints(). Other presets\n  // either don't support 103 or handle it at the CDN level.\n  const earlyHintsImport = earlyHints\n    ? `import { runWithEarlyHintsSender } from '${serverEntryRelative}'\\n`\n    : '';\n\n  const handlerCall = earlyHints\n    ? `  const nodeRes = event.node?.res\n  const earlyHintsSender = (typeof nodeRes?.writeEarlyHints === 'function')\n    ? (links) => { try { nodeRes.writeEarlyHints({ link: links }) } catch {} }\n    : undefined\n\n  const webResponse = earlyHintsSender\n    ? await runWithEarlyHintsSender(earlyHintsSender, () => handler(webRequest))\n    : await handler(webRequest)`\n    : `  const webResponse = await handler(webRequest)`;\n\n  return `// Generated by @timber/app/adapters/nitro\n// Do not edit — this file is regenerated on each build.\n\n${manifestImport}${earlyHintsImport}import { defineEventHandler, toWebRequest, sendWebResponse } from 'h3'\nimport { handler } from '${serverEntryRelative}'\n\n// Set TIMBER_RUNTIME for instrumentation.ts conditional SDK initialization.\n// See design/25-production-deployments.md §\"TIMBER_RUNTIME\".\nprocess.env.TIMBER_RUNTIME = '${runtimeName}'\n\nexport default defineEventHandler(async (event) => {\n  const webRequest = toWebRequest(event)\n${handlerCall}\n  return sendWebResponse(event, webResponse)\n})\n`;\n}\n\n/** @internal Exported for testing. */\nexport function generateNitroConfig(\n  preset: NitroPreset,\n  userConfig?: Record<string, unknown>\n): string {\n  const presetConfig = PRESET_CONFIGS[preset];\n\n  const config: Record<string, unknown> = {\n    preset: presetConfig.nitroPreset,\n    output: { dir: presetConfig.outputDir },\n    // Static asset cache headers — hashed assets are immutable, others get 1h.\n    // See design/25-production-deployments.md §\"CDN / Edge Cache\"\n    routeRules: {\n      '/assets/**': { headers: { 'Cache-Control': IMMUTABLE_CACHE } },\n    },\n    ...presetConfig.extraConfig,\n    ...userConfig,\n  };\n\n  const configJson = JSON.stringify(config, null, 2);\n\n  return `// Generated by @timber/app/adapters/nitro\n// Do not edit — this file is regenerated on each build.\n\nimport { defineNitroConfig } from 'nitropack/config'\n\nexport default defineNitroConfig(${configJson})\n`;\n}\n\n// ─── Preview ─────────────────────────────────────────────────────────────────\n\n/** Presets that produce a locally-runnable server entry. */\nconst LOCALLY_PREVIEWABLE = new Set<NitroPreset>(['node-server', 'bun']);\n\n/** Command descriptor for Nitro preview — testable without spawning. */\nexport interface NitroPreviewCommand {\n  command: string;\n  args: string[];\n  cwd: string;\n}\n\n/** @internal Exported for testing. */\nexport function generateNitroPreviewCommand(\n  buildDir: string,\n  preset: NitroPreset\n): NitroPreviewCommand | null {\n  if (!LOCALLY_PREVIEWABLE.has(preset)) return null;\n\n  const nitroDir = join(buildDir, 'nitro');\n  const entryPath = join(nitroDir, 'entry.ts');\n\n  const command = preset === 'bun' ? 'bun' : 'node';\n  return {\n    command,\n    args: [entryPath],\n    cwd: nitroDir,\n  };\n}\n\n/** Spawn a Nitro preview process and pipe stdio. */\nfunction spawnNitroPreview(command: string, args: string[], cwd: string): Promise<void> {\n  return new Promise<void>((resolve, reject) => {\n    const child = execFile(command, args, { cwd }, (err) => {\n      if (err) reject(err);\n      else resolve();\n    });\n    child.stdout?.pipe(process.stdout);\n    child.stderr?.pipe(process.stderr);\n  });\n}\n\n// ─── Helpers ─────────────────────────────────────────────────────────────────\n\n/**\n * Get the preset configuration for a given preset name.\n * @internal Exported for testing.\n */\nexport function getPresetConfig(preset: NitroPreset): PresetConfig {\n  return PRESET_CONFIGS[preset];\n}\n"],"mappings":"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"}

package/dist/adapters/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Configuration passed to adapter lifecycle methods.
+ * A subset of the resolved timber.config.ts relevant to adapters.
+ */
+export interface TimberConfig {
+    output: 'server' | 'static';
+    clientJavascriptDisabled?: boolean;
+    /**
+     * JS module source that sets globalThis.__TIMBER_BUILD_MANIFEST__.
+     * Written by adapters as _timber-manifest-init.js, imported before the RSC handler.
+     * Undefined when no build manifest was produced (e.g., dev mode or no client assets).
+     */
+    manifestInit?: string;
+}
+/**
+ * The formal adapter interface. An adapter transforms the build output
+ * into a deployable artifact for a specific platform.
+ *
+ * Adapters are small: they receive the build output directory and
+ * transform or copy it into whatever shape the platform expects.
+ */
+export interface TimberPlatformAdapter {
+    /** Unique adapter name (e.g. 'cloudflare', 'node', 'bun'). */
+    name: string;
+    /**
+     * Transform the build output for the target platform.
+     * Called at the end of `timber build`.
+     */
+    buildOutput(config: TimberConfig, buildDir: string): Promise<void>;
+    /**
+     * Start a local preview server for the built output.
+     * Falls back to the built-in Node.js preview server if not provided.
+     */
+    preview?(config: TimberConfig, buildDir: string): Promise<void>;
+    /**
+     * Register a promise to be kept alive after the response is sent.
+     * Maps to platform-specific lifecycle extension (e.g. ctx.waitUntil()
+     * on Cloudflare Workers). Undefined if the platform doesn't support it.
+     */
+    waitUntil?(promise: Promise<unknown>): void;
+    /**
+     * Send 103 Early Hints to the client before the final response.
+     *
+     * On Node.js (v18.11+) and Bun, uses `res.writeEarlyHints()` on the
+     * raw HTTP response. On Cloudflare, the CDN converts Link headers into
+     * 103 automatically — this method is not needed.
+     *
+     * Undefined if the platform doesn't support application-level 103,
+     * or if 103 is handled at the CDN level (Cloudflare).
+     */
+    sendEarlyHints?(links: string[]): void;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC5B,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,WAAW,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE;;;OAGG;IACH,OAAO,CAAC,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhE;;;;OAIG;IACH,SAAS,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IAE5C;;;;;;;;;OASG;IACH,cAAc,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CACxC"}

package/dist/cache/index.d.ts

@@ -0,0 +1,52 @@
+export interface CacheHandler {
+    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>;
+}
+export interface CacheOptions<Fn extends (...args: any[]) => any> {
+    ttl: number;
+    key?: (...args: Parameters<Fn>) => string;
+    staleWhileRevalidate?: boolean;
+    tags?: string[] | ((...args: Parameters<Fn>) => string[]);
+}
+export interface MemoryCacheHandlerOptions {
+    /** Maximum number of entries. Oldest accessed entries are evicted first. Default: 1000. */
+    maxSize?: number;
+}
+export declare class MemoryCacheHandler implements CacheHandler {
+    private store;
+    private maxSize;
+    constructor(opts?: MemoryCacheHandlerOptions);
+    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>;
+    /** Number of entries currently in the cache. */
+    get size(): number;
+}
+export { RedisCacheHandler } from './redis-handler';
+export type { RedisClient } from './redis-handler';
+export { createCache } from './timber-cache';
+export { registerCachedFunction } from './register-cached-function';
+export type { RegisterCachedFunctionOptions } from './register-cached-function';
+export { stableStringify } from './stable-stringify';
+export { createSingleflight } from './singleflight';
+export type { Singleflight } from './singleflight';
+//# sourceMappingURL=index.d.ts.map