@timber-js/app 0.1.0 → 0.1.2

package/src/cache/register-cached-function.ts

@@ -0,0 +1,99 @@
+import { createHash } from 'node:crypto';
+import type { CacheHandler } from './index';
+import { stableStringify } from './stable-stringify';
+import { createSingleflight } from './singleflight';
+
+const singleflight = createSingleflight();
+
+// Prop names that suggest request-specific data — triggers dev warning for "use cache" components.
+const REQUEST_SPECIFIC_PROPS = new Set([
+  'cookies',
+  'cookie',
+  'session',
+  'sessionId',
+  'token',
+  'authorization',
+  'auth',
+  'headers',
+]);
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface RegisterCachedFunctionOptions<Fn extends (...args: any[]) => any> {
+  ttl: number;
+  id: string;
+  tags?: string[] | ((...args: Parameters<Fn>) => string[]);
+  /** True when the cached function is a React component (PascalCase name). */
+  isComponent?: boolean;
+}
+
+/**
+ * Generate a SHA-256 cache key from a stable function ID and serialized args.
+ */
+function generateKey(id: string, args: unknown[]): string {
+  const raw = id + ':' + stableStringify(args);
+  return createHash('sha256').update(raw).digest('hex');
+}
+
+/**
+ * Resolve tags from options — supports static array or function form.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function resolveTags<Fn extends (...args: any[]) => any>(
+  opts: RegisterCachedFunctionOptions<Fn>,
+  args: Parameters<Fn>
+): string[] {
+  if (!opts.tags) return [];
+  if (Array.isArray(opts.tags)) return opts.tags;
+  return opts.tags(...args);
+}
+
+/**
+ * Checks if component props contain request-specific keys and emits a dev warning.
+ * Only runs when process.env.NODE_ENV !== 'production'.
+ */
+function warnRequestSpecificProps(id: string, props: unknown): void {
+  if (typeof props !== 'object' || props === null) return;
+  const keys = Object.keys(props);
+  const suspicious = keys.filter((k) => REQUEST_SPECIFIC_PROPS.has(k.toLowerCase()));
+  if (suspicious.length > 0) {
+    console.warn(
+      `[timber] "use cache" component ${id} received request-specific props: ${suspicious.join(', ')}. ` +
+        `This may serve one user's cached render to another user. ` +
+        `Remove request-specific data from props or remove "use cache".`
+    );
+  }
+}
+
+/**
+ * Runtime for the "use cache" directive transform. Wraps an async function
+ * with caching using the same cache handler as timber.cache.
+ *
+ * The stable `id` (file path + function name) ensures cache keys are consistent
+ * across builds. Args/props are hashed with SHA-256 for the per-call key.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerCachedFunction<Fn extends (...args: any[]) => Promise<any>>(
+  fn: Fn,
+  opts: RegisterCachedFunctionOptions<Fn>,
+  handler: CacheHandler
+): (...args: Parameters<Fn>) => Promise<Awaited<ReturnType<Fn>>> {
+  return async (...args: Parameters<Fn>): Promise<Awaited<ReturnType<Fn>>> => {
+    // Dev-mode warning for components with request-specific props
+    if (opts.isComponent && process.env.NODE_ENV !== 'production' && args.length > 0) {
+      warnRequestSpecificProps(opts.id, args[0]);
+    }
+
+    const key = generateKey(opts.id, args);
+    const cached = await handler.get(key);
+
+    if (cached && !cached.stale) {
+      return cached.value as Awaited<ReturnType<Fn>>;
+    }
+
+    // Cache miss or stale — execute with singleflight
+    const result = await singleflight.do(key, () => fn(...args));
+    const tags = resolveTags(opts, args);
+    await handler.set(key, result, { ttl: opts.ttl, tags });
+    return result as Awaited<ReturnType<Fn>>;
+  };
+}

package/src/cache/singleflight.ts

@@ -0,0 +1,26 @@
+/**
+ * Singleflight coalesces concurrent calls with the same key into a single
+ * execution. All callers receive the same result (or error).
+ *
+ * Per-process, in-memory. Each process coalesces independently.
+ */
+export interface Singleflight {
+  do<T>(key: string, fn: () => Promise<T>): Promise<T>;
+}
+
+export function createSingleflight(): Singleflight {
+  const inflight = new Map<string, Promise<unknown>>();
+
+  return {
+    do<T>(key: string, fn: () => Promise<T>): Promise<T> {
+      const existing = inflight.get(key);
+      if (existing) return existing as Promise<T>;
+
+      const promise = fn().finally(() => {
+        inflight.delete(key);
+      });
+      inflight.set(key, promise);
+      return promise;
+    },
+  };
+}

package/src/cache/stable-stringify.ts

@@ -0,0 +1,21 @@
+/**
+ * Deterministic JSON serialization with sorted object keys.
+ * Used for cache key generation — ensures { a: 1, b: 2 } and { b: 2, a: 1 }
+ * produce the same string.
+ */
+export function stableStringify(value: unknown): string {
+  if (value === null || value === undefined) return JSON.stringify(value);
+  if (typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return '[' + value.map((item) => stableStringify(item)).join(',') + ']';
+  }
+
+  const obj = value as Record<string, unknown>;
+  const keys = Object.keys(obj).sort();
+  const pairs: string[] = [];
+  for (const key of keys) {
+    if (obj[key] === undefined) continue;
+    pairs.push(JSON.stringify(key) + ':' + stableStringify(obj[key]));
+  }
+  return '{' + pairs.join(',') + '}';
+}

package/src/cache/timber-cache.ts

@@ -0,0 +1,116 @@
+import { createHash } from 'node:crypto';
+import type { CacheHandler, CacheOptions } from './index';
+import { stableStringify } from './stable-stringify';
+import { createSingleflight } from './singleflight';
+import { addSpanEvent } from '#/server/tracing.js';
+
+const singleflight = createSingleflight();
+
+/**
+ * Generate a SHA-256 cache key from function identity and serialized args.
+ */
+function defaultKeyGenerator(fnId: string, args: unknown[]): string {
+  const raw = fnId + ':' + stableStringify(args);
+  return createHash('sha256').update(raw).digest('hex');
+}
+
+/**
+ * Resolve tags from the options — supports static array or function form.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function resolveTags<Fn extends (...args: any[]) => any>(
+  opts: CacheOptions<Fn>,
+  args: Parameters<Fn>
+): string[] {
+  if (!opts.tags) return [];
+  if (Array.isArray(opts.tags)) return opts.tags;
+  return opts.tags(...args);
+}
+
+// Counter for generating unique function IDs when no explicit key is provided.
+let fnIdCounter = 0;
+
+/**
+ * Creates a cached wrapper around an async function.
+ *
+ * - SHA-256 default keys with normalized JSON args
+ * - Singleflight: concurrent misses → single execution
+ * - SWR: serve stale immediately, background refetch
+ * - Tags as string[] or function of args
+ * - No ALS dependency
+ *
+ * Cache hits/misses are recorded as OTEL span events on the enclosing
+ * span (not child spans). The DevSpanProcessor reads these for dev log output.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function createCache<Fn extends (...args: any[]) => Promise<any>>(
+  fn: Fn,
+  opts: CacheOptions<Fn>,
+  handler: CacheHandler
+): (...args: Parameters<Fn>) => Promise<Awaited<ReturnType<Fn>>> {
+  const fnId = `timber-cache:${fnIdCounter++}`;
+
+  return async (...args: Parameters<Fn>): Promise<Awaited<ReturnType<Fn>>> => {
+    const key = opts.key ? opts.key(...args) : defaultKeyGenerator(fnId, args);
+
+    const cacheStart = performance.now();
+    const cached = await handler.get(key);
+
+    if (cached && !cached.stale) {
+      // Record as OTEL span event on enclosing span (not a child span)
+      await addSpanEvent('timber.cache.hit', {
+        key,
+        duration_ms: Math.round(performance.now() - cacheStart),
+      });
+      return cached.value as Awaited<ReturnType<Fn>>;
+    }
+
+    if (cached && cached.stale && opts.staleWhileRevalidate) {
+      // Record stale cache hit as OTEL span event
+      await addSpanEvent('timber.cache.hit', {
+        key,
+        duration_ms: Math.round(performance.now() - cacheStart),
+        stale: true,
+      });
+      // Serve stale immediately, trigger background refetch
+      singleflight
+        .do(`swr:${key}`, async () => {
+          try {
+            const fresh = await fn(...args);
+            const tags = resolveTags(opts, args);
+            await handler.set(key, fresh, { ttl: opts.ttl, tags });
+          } catch {
+            // Failed refetch — stale entry continues to be served.
+            // Error is swallowed per design doc: "Error is logged."
+          }
+        })
+        .catch(() => {
+          // Singleflight promise rejection handled — stale continues.
+        });
+      return cached.value as Awaited<ReturnType<Fn>>;
+    }
+
+    // Cache miss (or stale without SWR) — execute with singleflight
+    const result = await singleflight.do(key, () => fn(...args));
+    const tags = resolveTags(opts, args);
+    await handler.set(key, result, { ttl: opts.ttl, tags });
+
+    // Record cache miss as OTEL span event
+    await addSpanEvent('timber.cache.miss', {
+      key,
+      duration_ms: Math.round(performance.now() - cacheStart),
+    });
+
+    return result as Awaited<ReturnType<Fn>>;
+  };
+}
+
+/**
+ * Invalidate cache entries by tag or key.
+ */
+createCache.invalidate = async function invalidate(
+  handler: CacheHandler,
+  opts: { key?: string; tag?: string }
+): Promise<void> {
+  await handler.invalidate(opts);
+};

package/src/cli.ts

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+
+// timber.js CLI
+//
+// Wraps Vite commands with timber-specific behavior.
+// See design/18-build-system.md §"CLI".
+//
+// Commands:
+//   timber dev      — Start Vite dev server with HMR
+//   timber build    — Run multi-environment build via createBuilder/buildApp
+//   timber preview  — Serve the production build
+//   timber check    — Validate types + routes without building
+
+const COMMANDS = ['dev', 'build', 'preview', 'check'] as const;
+type Command = (typeof COMMANDS)[number];
+
+export interface ParsedArgs {
+  command: Command;
+  config: string | undefined;
+}
+
+export interface CommandOptions {
+  config?: string;
+}
+
+/**
+ * Parse CLI arguments into a structured command + options.
+ * Accepts: timber <command> [--config|-c <path>]
+ */
+export function parseArgs(args: string[]): ParsedArgs {
+  if (args.length === 0) {
+    throw new Error(
+      'No command provided. Usage: timber <dev|build|preview|check> [--config <path>]'
+    );
+  }
+
+  const command = args[0];
+  if (!COMMANDS.includes(command as Command)) {
+    throw new Error(`Unknown command: ${command}. Available commands: ${COMMANDS.join(', ')}`);
+  }
+
+  let config: string | undefined;
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--config' || args[i] === '-c') {
+      config = args[++i];
+      if (!config) {
+        throw new Error('--config requires a path argument');
+      }
+    }
+  }
+
+  return { command: command as Command, config };
+}
+
+// ─── Command Implementations ─────────────────────────────────────────────────
+
+/**
+ * Start the Vite dev server.
+ * Middleware re-runs on file change via HMR wiring in timber-routing.
+ */
+export async function runDev(options: CommandOptions): Promise<void> {
+  const { createServer } = await import('vite');
+  const server = await createServer({
+    configFile: options.config,
+  });
+  await server.listen();
+  server.printUrls();
+}
+
+/**
+ * Run the production build using createBuilder + buildApp.
+ * Direct build() calls do NOT trigger the RSC plugin's multi-environment
+ * pipeline — createBuilder/buildApp is required.
+ */
+export async function runBuild(options: CommandOptions): Promise<void> {
+  const { createBuilder } = await import('vite');
+  const builder = await createBuilder({
+    configFile: options.config,
+  });
+  await builder.buildApp();
+}
+
+/**
+ * Determine whether to use the adapter's preview or Vite's built-in preview.
+ * Exported for testing — the actual runPreview function uses this internally.
+ */
+export function resolvePreviewStrategy(
+  adapter: import('./adapters/types').TimberPlatformAdapter | undefined
+): 'adapter' | 'vite' {
+  if (adapter && typeof adapter.preview === 'function') {
+    return 'adapter';
+  }
+  return 'vite';
+}
+
+/**
+ * Load timber.config.ts from the project root.
+ * Returns the config object with adapter, output, etc.
+ * Returns null if no config file is found.
+ */
+async function loadTimberConfig(
+  root: string
+): Promise<{ adapter?: import('./adapters/types').TimberPlatformAdapter; output?: string } | null> {
+  const { existsSync } = await import('node:fs');
+  const { join } = await import('node:path');
+  const { pathToFileURL } = await import('node:url');
+
+  const configNames = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];
+
+  for (const name of configNames) {
+    const configPath = join(root, name);
+    if (existsSync(configPath)) {
+      // Use Vite's built-in config loading to handle TypeScript
+      const mod = await import(pathToFileURL(configPath).href);
+      return mod.default ?? mod;
+    }
+  }
+  return null;
+}
+
+/**
+ * Serve the production build for local testing.
+ * If the adapter provides a preview() method, it takes priority.
+ * Otherwise falls back to Vite's built-in preview server.
+ */
+export async function runPreview(options: CommandOptions): Promise<void> {
+  const { join } = await import('node:path');
+
+  // Try to load timber config for adapter-specific preview
+  const root = process.cwd();
+  const config = await loadTimberConfig(root).catch(() => null);
+  const adapter = config?.adapter as import('./adapters/types').TimberPlatformAdapter | undefined;
+
+  if (resolvePreviewStrategy(adapter) === 'adapter') {
+    const buildDir = join(root, '.timber', 'build');
+    const timberConfig = { output: (config?.output ?? 'server') as 'server' | 'static' };
+    await adapter!.preview!(timberConfig, buildDir);
+    return;
+  }
+
+  // Fallback: Vite's built-in preview server
+  const { preview } = await import('vite');
+  const server = await preview({
+    configFile: options.config,
+  });
+  server.printUrls();
+}
+
+/**
+ * Validate types and routes without producing build output.
+ * Runs tsgo --noEmit for type checking.
+ */
+export async function runCheck(options: CommandOptions): Promise<void> {
+  const { execFile } = await import('node:child_process');
+
+  await new Promise<void>((resolve, reject) => {
+    const configArgs = options.config ? ['--project', options.config] : [];
+    execFile('tsgo', ['--noEmit', ...configArgs], (err, stdout, stderr) => {
+      if (stdout) process.stdout.write(stdout);
+      if (stderr) process.stderr.write(stderr);
+      if (err) {
+        reject(new Error(`Type check failed with exit code ${err.code}`));
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+
+// ─── Main Entry Point ────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  const parsed = parseArgs(process.argv.slice(2));
+  const options: CommandOptions = { config: parsed.config };
+
+  switch (parsed.command) {
+    case 'dev':
+      await runDev(options);
+      break;
+    case 'build':
+      await runBuild(options);
+      break;
+    case 'preview':
+      await runPreview(options);
+      break;
+    case 'check':
+      await runCheck(options);
+      break;
+  }
+}
+
+// Only run main when executed directly (not imported in tests)
+const isDirectExecution =
+  typeof process !== 'undefined' && process.argv[1] && import.meta.url.endsWith(process.argv[1]);
+
+if (isDirectExecution) {
+  main().catch((err) => {
+    console.error(err.message);
+    process.exit(1);
+  });
+}