@timber-js/app 0.1.21 → 0.1.22

package/src/search-params/builtin-codecs.ts

@@ -0,0 +1,228 @@
+/**
+ * Built-in search param codecs for common types.
+ *
+ * These provide zero-dependency alternatives to nuqs parsers for the most
+ * common cases: strings, integers, floats, booleans, and string enums.
+ *
+ * All codecs implement SearchParamCodec<T | null> — returning null when the
+ * param is absent or unparseable. Use withDefault() to replace null with a
+ * concrete fallback value.
+ *
+ * Design doc: design/23-search-params.md §"Identified Gaps" #1
+ * Task: TIM-362
+ */
+
+import type { SearchParamCodec } from './create.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize array inputs to a single string (last value wins, matching
+ * URLSearchParams.get() semantics). Returns undefined if absent or empty.
+ */
+function normalizeInput(value: string | string[] | undefined): string | undefined {
+  if (Array.isArray(value)) {
+    return value.length > 0 ? value[value.length - 1] : undefined;
+  }
+  return value;
+}
+
+// ---------------------------------------------------------------------------
+// parseAsString
+// ---------------------------------------------------------------------------
+
+/**
+ * String codec. Returns the raw string value, or null if absent.
+ *
+ * ```ts
+ * import { parseAsString } from '@timber-js/app/search-params'
+ *
+ * const def = createSearchParams({ q: parseAsString })
+ * // ?q=shoes → { q: 'shoes' }
+ * // (absent) → { q: null }
+ * ```
+ */
+export const parseAsString: SearchParamCodec<string | null> = {
+  parse(value: string | string[] | undefined): string | null {
+    const v = normalizeInput(value);
+    return v !== undefined ? v : null;
+  },
+  serialize(value: string | null): string | null {
+    return value;
+  },
+};
+
+// ---------------------------------------------------------------------------
+// parseAsInteger
+// ---------------------------------------------------------------------------
+
+/**
+ * Integer codec. Parses a base-10 integer, or returns null if absent or
+ * not a valid integer. Rejects floats, NaN, Infinity, and non-numeric strings.
+ *
+ * ```ts
+ * import { parseAsInteger, withDefault } from '@timber-js/app/search-params'
+ *
+ * const def = createSearchParams({ page: withDefault(parseAsInteger, 1) })
+ * // ?page=2 → { page: 2 }
+ * // ?page=abc → { page: 1 }
+ * // (absent) → { page: 1 }
+ * ```
+ */
+export const parseAsInteger: SearchParamCodec<number | null> = {
+  parse(value: string | string[] | undefined): number | null {
+    const v = normalizeInput(value);
+    if (v === undefined || v === '') return null;
+    const n = Number(v);
+    if (!Number.isFinite(n) || !Number.isInteger(n)) return null;
+    return n;
+  },
+  serialize(value: number | null): string | null {
+    return value === null ? null : String(value);
+  },
+};
+
+// ---------------------------------------------------------------------------
+// parseAsFloat
+// ---------------------------------------------------------------------------
+
+/**
+ * Float codec. Parses a finite number, or returns null if absent or invalid.
+ * Rejects NaN and Infinity.
+ *
+ * ```ts
+ * import { parseAsFloat, withDefault } from '@timber-js/app/search-params'
+ *
+ * const def = createSearchParams({ price: withDefault(parseAsFloat, 0) })
+ * ```
+ */
+export const parseAsFloat: SearchParamCodec<number | null> = {
+  parse(value: string | string[] | undefined): number | null {
+    const v = normalizeInput(value);
+    if (v === undefined || v === '') return null;
+    const n = Number(v);
+    if (!Number.isFinite(n)) return null;
+    return n;
+  },
+  serialize(value: number | null): string | null {
+    return value === null ? null : String(value);
+  },
+};
+
+// ---------------------------------------------------------------------------
+// parseAsBoolean
+// ---------------------------------------------------------------------------
+
+/**
+ * Boolean codec. Accepts "true"/"1" as true, "false"/"0" as false.
+ * Returns null for absent or unrecognized values.
+ *
+ * ```ts
+ * import { parseAsBoolean, withDefault } from '@timber-js/app/search-params'
+ *
+ * const def = createSearchParams({ debug: withDefault(parseAsBoolean, false) })
+ * // ?debug=true → { debug: true }
+ * // ?debug=0 → { debug: false }
+ * ```
+ */
+export const parseAsBoolean: SearchParamCodec<boolean | null> = {
+  parse(value: string | string[] | undefined): boolean | null {
+    const v = normalizeInput(value);
+    if (v === undefined) return null;
+    if (v === 'true' || v === '1') return true;
+    if (v === 'false' || v === '0') return false;
+    return null;
+  },
+  serialize(value: boolean | null): string | null {
+    return value === null ? null : String(value);
+  },
+};
+
+// ---------------------------------------------------------------------------
+// parseAsStringEnum
+// ---------------------------------------------------------------------------
+
+/**
+ * String enum codec. Accepts only values in the provided list.
+ * Returns null for absent or invalid values.
+ *
+ * ```ts
+ * import { parseAsStringEnum, withDefault } from '@timber-js/app/search-params'
+ *
+ * const sortCodec = withDefault(
+ *   parseAsStringEnum(['price', 'name', 'date']),
+ *   'date'
+ * )
+ * ```
+ */
+export function parseAsStringEnum<T extends string>(
+  values: readonly T[]
+): SearchParamCodec<T | null> {
+  const allowed = new Set<string>(values);
+  return {
+    parse(value: string | string[] | undefined): T | null {
+      const v = normalizeInput(value);
+      if (v === undefined) return null;
+      return allowed.has(v) ? (v as T) : null;
+    },
+    serialize(value: T | null): string | null {
+      return value;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// parseAsStringLiteral
+// ---------------------------------------------------------------------------
+
+/**
+ * String literal codec. Functionally identical to parseAsStringEnum but
+ * accepts `as const` tuples for narrower type inference.
+ *
+ * ```ts
+ * import { parseAsStringLiteral } from '@timber-js/app/search-params'
+ *
+ * const sizes = ['sm', 'md', 'lg', 'xl'] as const
+ * const codec = parseAsStringLiteral(sizes)
+ * // Type: SearchParamCodec<'sm' | 'md' | 'lg' | 'xl' | null>
+ * ```
+ */
+export function parseAsStringLiteral<const T extends readonly string[]>(
+  values: T
+): SearchParamCodec<T[number] | null> {
+  // Delegates to parseAsStringEnum — same runtime behavior, different type
+  return parseAsStringEnum<T[number]>(values);
+}
+
+// ---------------------------------------------------------------------------
+// withDefault
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap a nullable codec with a default value. When the inner codec returns
+ * null, the default is used instead. The output type becomes non-nullable.
+ *
+ * ```ts
+ * import { parseAsInteger, withDefault } from '@timber-js/app/search-params'
+ *
+ * const page = withDefault(parseAsInteger, 1)
+ * // page.parse(undefined) → 1 (not null)
+ * // page.parse('5') → 5
+ * ```
+ */
+export function withDefault<T>(
+  codec: SearchParamCodec<T | null>,
+  defaultValue: T
+): SearchParamCodec<T> {
+  return {
+    parse(value: string | string[] | undefined): T {
+      const result = codec.parse(value);
+      return result === null ? defaultValue : result;
+    },
+    serialize(value: T): string | null {
+      return codec.serialize(value);
+    },
+  };
+}

package/src/search-params/index.ts

@@ -15,6 +15,17 @@ export { createSearchParams } from './create.js';
 // Codec bridges
 export { fromSchema, fromArraySchema } from './codecs.js';
 
+// Built-in codecs
+export {
+  parseAsString,
+  parseAsInteger,
+  parseAsFloat,
+  parseAsBoolean,
+  parseAsStringEnum,
+  parseAsStringLiteral,
+  withDefault,
+} from './builtin-codecs.js';
+
 // Runtime registry (route-scoped useQueryStates)
 export { registerSearchParams, getSearchParams } from './registry.js';
 

package/src/server/action-handler.ts

@@ -18,7 +18,7 @@ import {
   decodeReply,
   decodeAction,
   renderToReadableStream,
-} from '@vitejs/plugin-rsc/rsc';
+} from '#/rsc-runtime/rsc.js';
 
 import { validateCsrf, type CsrfConfig } from './csrf.js';
 import { executeAction, type RevalidateRenderer } from './actions.js';

package/src/server/actions.ts

@@ -14,10 +14,10 @@
  * See design/08-forms-and-actions.md
  */
 
-import { AsyncLocalStorage } from 'node:async_hooks';
 import type { CacheHandler } from '#/cache/index';
 import { RedirectSignal } from './primitives';
 import { withSpan } from './tracing';
+import { revalidationAls, type RevalidationState } from './als-registry.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -32,13 +32,8 @@ export interface RevalidationResult {
 /** Renderer function that builds a React element tree for a given path. */
 export type RevalidateRenderer = (path: string) => Promise<RevalidationResult>;
 
-/** Per-request revalidation state — tracks revalidatePath/Tag calls within an action. */
-export interface RevalidationState {
-  /** Paths to re-render (populated by revalidatePath calls). */
-  paths: string[];
-  /** Tags to invalidate (populated by revalidateTag calls). */
-  tags: string[];
-}
+// Re-export the type from the registry for public API consumers.
+export type { RevalidationState } from './als-registry.js';
 
 /** Options for creating the action handler. */
 export interface ActionHandlerConfig {
@@ -62,10 +57,9 @@ export interface ActionHandlerResult {
 
 // ─── Revalidation State ──────────────────────────────────────────────────
 
-// Per-request revalidation state stored in AsyncLocalStorage.
+// Per-request revalidation state stored in AsyncLocalStorage (from als-registry.ts).
 // This ensures concurrent requests never share or overwrite each other's state
 // (the previous module-level global was vulnerable to cross-request pollution).
-const revalidationAls = new AsyncLocalStorage<RevalidationState>();
 
 /**
  * Set the revalidation state for the current action execution.

package/src/server/als-registry.ts

@@ -0,0 +1,116 @@
+/**
+ * Centralized AsyncLocalStorage registry for server-side per-request state.
+ *
+ * ALL ALS instances used by the server framework live here. Individual
+ * modules (request-context.ts, tracing.ts, actions.ts, etc.) import from
+ * this registry and re-export public accessor functions.
+ *
+ * Why: ALS instances require singleton semantics — if two copies of the
+ * same ALS exist (one from a relative import, one from a barrel import),
+ * one module writes to its copy and another reads from an empty copy.
+ * Centralizing ALS creation in a single module eliminates this class of bug.
+ *
+ * The `timber-shims` plugin ensures `@timber-js/app/server` resolves to
+ * src/ in RSC and SSR environments, so all import paths converge here.
+ *
+ * DO NOT create ALS instances outside this file. If you need a new ALS,
+ * add it here and import from `./als-registry.js` in the consuming module.
+ *
+ * See design/18-build-system.md §"Module Singleton Strategy" and
+ * §"Singleton State Registry".
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+// ─── Request Context ──────────────────────────────────────────────────────
+// Used by: request-context.ts (headers(), cookies(), searchParams())
+// Design doc: design/04-authorization.md
+
+/** @internal — import via request-context.ts public API */
+export const requestContextAls = new AsyncLocalStorage<RequestContextStore>();
+
+export interface RequestContextStore {
+  /** Incoming request headers (read-only view). */
+  headers: Headers;
+  /** Raw cookie header string, parsed lazily into a Map on first access. */
+  cookieHeader: string;
+  /** Lazily-parsed cookie map (mutable — reflects write-overlay from set()). */
+  parsedCookies?: Map<string, string>;
+  /** Original (pre-overlay) frozen headers, kept for overlay merging. */
+  originalHeaders: Headers;
+  /**
+   * Promise resolving to the route's typed search params (when search-params.ts
+   * exists) or to the raw URLSearchParams. Stored as a Promise so the framework
+   * can later support partial pre-rendering where param resolution is deferred.
+   */
+  searchParamsPromise: Promise<URLSearchParams | Record<string, unknown>>;
+  /** Outgoing Set-Cookie entries (name → serialized value + options). Last write wins. */
+  cookieJar: Map<string, CookieEntry>;
+  /** Whether the response has flushed (headers committed). */
+  flushed: boolean;
+  /** Whether the current context allows cookie mutation. */
+  mutableContext: boolean;
+}
+
+/** A single outgoing cookie entry in the cookie jar. */
+export interface CookieEntry {
+  name: string;
+  value: string;
+  options: import('./request-context.js').CookieOptions;
+}
+
+// ─── Tracing ──────────────────────────────────────────────────────────────
+// Used by: tracing.ts (traceId(), spanId())
+// Design doc: design/17-logging.md
+
+export interface TraceStore {
+  /** 32-char lowercase hex trace ID (OTEL or UUID fallback). */
+  traceId: string;
+  /** OTEL span ID if available, undefined otherwise. */
+  spanId?: string;
+}
+
+/** @internal — import via tracing.ts public API */
+export const traceAls = new AsyncLocalStorage<TraceStore>();
+
+// ─── Server-Timing ────────────────────────────────────────────────────────
+// Used by: server-timing.ts (recordTiming(), withTiming())
+// Design doc: (dev-only performance instrumentation)
+
+export interface TimingStore {
+  entries: import('./server-timing.js').TimingEntry[];
+}
+
+/** @internal — import via server-timing.ts public API */
+export const timingAls = new AsyncLocalStorage<TimingStore>();
+
+// ─── Revalidation ─────────────────────────────────────────────────────────
+// Used by: actions.ts (revalidatePath(), revalidateTag())
+// Design doc: design/08-forms-and-actions.md
+
+export interface RevalidationState {
+  /** Paths to re-render (populated by revalidatePath calls). */
+  paths: string[];
+  /** Tags to invalidate (populated by revalidateTag calls). */
+  tags: string[];
+}
+
+/** @internal — import via actions.ts public API */
+export const revalidationAls = new AsyncLocalStorage<RevalidationState>();
+
+// ─── Form Flash ───────────────────────────────────────────────────────────
+// Used by: form-flash.ts (getFormFlash())
+// Design doc: design/08-forms-and-actions.md §"No-JS Error Round-Trip"
+
+/** @internal — import via form-flash.ts public API */
+export const formFlashAls = new AsyncLocalStorage<import('./form-flash.js').FormFlashData>();
+
+// ─── Early Hints Sender ──────────────────────────────────────────────────
+// Used by: early-hints-sender.ts (sendEarlyHints103())
+// Design doc: design/02-rendering-pipeline.md §"Early Hints (103)"
+
+/** Function that sends Link header values as a 103 Early Hints response. */
+export type EarlyHintsSenderFn = (links: string[]) => void;
+
+/** @internal — import via early-hints-sender.ts public API */
+export const earlyHintsSenderAls = new AsyncLocalStorage<EarlyHintsSenderFn>();

package/src/server/deny-renderer.ts

@@ -16,7 +16,7 @@
  */
 
 import { createElement } from 'react';
-import { renderToReadableStream } from '@vitejs/plugin-rsc/rsc';
+import { renderToReadableStream } from '#/rsc-runtime/rsc.js';
 
 import { DenySignal } from './primitives.js';
 import { logRenderError } from './logger.js';

package/src/server/early-hints-sender.ts

@@ -18,13 +18,11 @@
  * Design doc: 02-rendering-pipeline.md §"Early Hints (103)"
  */
 
-import { AsyncLocalStorage } from 'node:async_hooks';
+import { earlyHintsSenderAls } from './als-registry.js';
 
 /** Function that sends Link header values as a 103 Early Hints response. */
 export type EarlyHintsSenderFn = (links: string[]) => void;
 
-const earlyHintsSenderAls = new AsyncLocalStorage<EarlyHintsSenderFn>();
-
 /**
  * Run a function with a per-request early hints sender installed.
  *

package/src/server/form-flash.ts

@@ -14,8 +14,8 @@
  * See design/08-forms-and-actions.md §"No-JS Error Round-Trip"
  */
 
-import { AsyncLocalStorage } from 'node:async_hooks';
 import type { ValidationErrors } from './action-client.js';
+import { formFlashAls } from './als-registry.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -43,10 +43,6 @@ export interface FormFlashData {
   serverError?: { code: string; data?: Record<string, unknown> };
 }
 
-// ─── ALS Store ───────────────────────────────────────────────────────────
-
-const formFlashAls = new AsyncLocalStorage<FormFlashData>();
-
 // ─── Public API ──────────────────────────────────────────────────────────
 
 /**

package/src/server/index.ts

@@ -36,6 +36,7 @@ export {
   RedirectSignal,
 } from './primitives';
 export type { RenderErrorDigest, WaitUntilAdapter } from './primitives';
+export type { JsonSerializable } from './types';
 
 // Pipeline
 export { createPipeline } from './pipeline';

package/src/server/metadata-routes.ts

@@ -121,6 +121,67 @@ export const METADATA_ROUTE_CONVENTIONS: Record<
   },
 };
 
+// ─── MIME Type Resolution ─────────────────────────────────────────────────────
+
+/**
+ * Map of file extensions to MIME types for static metadata route files.
+ * Used to resolve the generic `image/*` content type for static image files.
+ */
+const EXTENSION_MIME_TYPES: Record<string, string> = {
+  xml: 'application/xml',
+  txt: 'text/plain',
+  json: 'application/json',
+  ico: 'image/x-icon',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  svg: 'image/svg+xml',
+  webp: 'image/webp',
+};
+
+/**
+ * Resolve the concrete MIME type for a static metadata route file.
+ *
+ * For generic content types like `image/*`, this resolves to the actual
+ * MIME type based on the file extension (e.g. `image/png` for `.png`).
+ *
+ * @param conventionContentType - The content type from the convention table (may be generic like `image/*`)
+ * @param extension - The file extension without leading dot (e.g. "png", "xml")
+ * @returns The resolved MIME type
+ */
+export function resolveStaticContentType(conventionContentType: string, extension: string): string {
+  if (conventionContentType.includes('*')) {
+    return EXTENSION_MIME_TYPES[extension] ?? 'application/octet-stream';
+  }
+  return conventionContentType;
+}
+
+/**
+ * Check if a file extension represents a static (non-code) metadata route file.
+ *
+ * @param baseName - The base file name without extension (e.g. "sitemap", "icon")
+ * @param extension - The file extension without leading dot (e.g. "xml", "png", "ts")
+ * @returns true if this is a static file, false if dynamic or unrecognized
+ */
+export function isStaticMetadataExtension(baseName: string, extension: string): boolean {
+  const convention = METADATA_ROUTE_CONVENTIONS[baseName];
+  if (!convention) return false;
+  return convention.staticExtensions.includes(extension);
+}
+
+/**
+ * Check if a file extension represents a dynamic (code) metadata route file.
+ *
+ * @param baseName - The base file name without extension (e.g. "sitemap", "icon")
+ * @param extension - The file extension without leading dot (e.g. "ts", "tsx")
+ * @returns true if this is a dynamic file, false if static or unrecognized
+ */
+export function isDynamicMetadataExtension(baseName: string, extension: string): boolean {
+  const convention = METADATA_ROUTE_CONVENTIONS[baseName];
+  if (!convention) return false;
+  return convention.dynamicExtensions.includes(extension);
+}
+
 // ─── Classification ──────────────────────────────────────────────────────────
 
 /**