@timber-js/app 0.1.1 → 0.1.3

package/src/adapters/nitro.ts

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

package/src/adapters/types.ts

@@ -0,0 +1,63 @@
+// Platform adapter interface
+//
+// Adapters transform build output into deployable artifacts and provide
+// runtime hooks for platform-specific capabilities (waitUntil, etc.).
+// See design/11-platform.md §"The Adapter Interface".
+
+/**
+ * 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;
+}

package/src/cache/index.ts

@@ -0,0 +1,91 @@
+// @timber/app/cache — Caching primitives
+
+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>;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+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 class MemoryCacheHandler implements CacheHandler {
+  private store = new Map<string, { value: unknown; expiresAt: number; tags: string[] }>();
+  private maxSize: number;
+
+  constructor(opts?: MemoryCacheHandlerOptions) {
+    this.maxSize = opts?.maxSize ?? 1000;
+  }
+
+  async get(key: string) {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+
+    // Move to end of Map (most recently used) for LRU ordering
+    this.store.delete(key);
+    this.store.set(key, entry);
+
+    const stale = Date.now() > entry.expiresAt;
+    return { value: entry.value, stale };
+  }
+
+  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }) {
+    // If key already exists, delete first to refresh insertion order
+    if (this.store.has(key)) {
+      this.store.delete(key);
+    }
+
+    // Evict oldest entries (front of Map) if at capacity
+    while (this.store.size >= this.maxSize) {
+      const oldest = this.store.keys().next().value;
+      if (oldest !== undefined) {
+        this.store.delete(oldest);
+      } else {
+        break;
+      }
+    }
+
+    this.store.set(key, {
+      value,
+      expiresAt: Date.now() + opts.ttl * 1000,
+      tags: opts.tags,
+    });
+  }
+
+  async invalidate(opts: { key?: string; tag?: string }) {
+    if (opts.key) {
+      this.store.delete(opts.key);
+    }
+    if (opts.tag) {
+      for (const [key, entry] of this.store) {
+        if (entry.tags.includes(opts.tag)) {
+          this.store.delete(key);
+        }
+      }
+    }
+  }
+
+  /** Number of entries currently in the cache. */
+  get size(): number {
+    return this.store.size;
+  }
+}
+
+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';

package/src/cache/redis-handler.ts

@@ -0,0 +1,91 @@
+import type { CacheHandler } from './index';
+
+/**
+ * Minimal Redis client interface — compatible with ioredis, node-redis, and
+ * Cloudflare Workers Redis bindings. We depend on the interface, not the
+ * implementation, so users bring their own Redis client.
+ */
+export interface RedisClient {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
+  del(key: string | string[]): Promise<number>;
+  sadd(key: string, ...members: string[]): Promise<number>;
+  smembers(key: string): Promise<string[]>;
+}
+
+const KEY_PREFIX = 'timber:cache:';
+const TAG_PREFIX = 'timber:tag:';
+
+/**
+ * Redis-backed CacheHandler for distributed caching.
+ *
+ * All instances sharing the same Redis see each other's cache entries and
+ * invalidations. Tag-based invalidation uses Redis Sets to track which keys
+ * belong to which tags.
+ *
+ * Bring your own Redis client — any client implementing the RedisClient
+ * interface works (ioredis, node-redis, @upstash/redis, etc.).
+ */
+export class RedisCacheHandler implements CacheHandler {
+  private client: RedisClient;
+  private prefix: string;
+
+  constructor(client: RedisClient, opts?: { prefix?: string }) {
+    this.client = client;
+    this.prefix = opts?.prefix ?? '';
+  }
+
+  private cacheKey(key: string): string {
+    return `${this.prefix}${KEY_PREFIX}${key}`;
+  }
+
+  private tagKey(tag: string): string {
+    return `${this.prefix}${TAG_PREFIX}${tag}`;
+  }
+
+  async get(key: string): Promise<{ value: unknown; stale: boolean } | null> {
+    const raw = await this.client.get(this.cacheKey(key));
+    if (raw === null) return null;
+
+    const entry = JSON.parse(raw) as { value: unknown; expiresAt: number };
+    const stale = Date.now() > entry.expiresAt;
+    return { value: entry.value, stale };
+  }
+
+  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void> {
+    const ck = this.cacheKey(key);
+    const expiresAt = Date.now() + opts.ttl * 1000;
+    const payload = JSON.stringify({ value, expiresAt });
+
+    // Redis TTL with generous margin beyond the logical TTL to allow SWR reads
+    // on stale entries. The logical staleness is determined by expiresAt.
+    // We use 2x TTL + 60s as the Redis expiry so stale entries remain
+    // available for SWR background refetches.
+    const redisTtlSeconds = Math.max(opts.ttl * 2 + 60, 120);
+    await this.client.set(ck, payload, 'EX', redisTtlSeconds);
+
+    // Track key membership in each tag set
+    for (const tag of opts.tags) {
+      await this.client.sadd(this.tagKey(tag), key);
+    }
+  }
+
+  async invalidate(opts: { key?: string; tag?: string }): Promise<void> {
+    if (opts.key) {
+      await this.client.del(this.cacheKey(opts.key));
+    }
+
+    if (opts.tag) {
+      const tk = this.tagKey(opts.tag);
+      const keys = await this.client.smembers(tk);
+
+      if (keys.length > 0) {
+        const cacheKeys = keys.map((k) => this.cacheKey(k));
+        await this.client.del(cacheKeys);
+      }
+
+      // Clean up the tag set itself
+      await this.client.del(tk);
+    }
+  }
+}