@timber-js/app 0.2.0-alpha.16 → 0.2.0-alpha.161

package/src/search-params/wrappers.ts

@@ -0,0 +1,110 @@
+/**
+ * Codec wrappers — withDefault and withUrlKey.
+ *
+ * These are timber-specific utilities that work with any SearchParamCodec.
+ * For actual codecs (string, integer, boolean, etc.), use nuqs parsers
+ * or Standard Schema objects (Zod, Valibot, ArkType) with auto-detection.
+ *
+ * Design doc: design/23-search-params.md
+ */
+
+import type { SearchParamCodec, SearchParamCodecWithUrlKey, SearchParamField } from './define.js';
+import { isCodec, isStandardSchema, fromSchema, validateSync } from '../schema-bridge.js';
+import type { StandardSchemaV1 } from '../schema-bridge.js';
+
+function validateSchemaAbsentParam<T>(
+  schema: StandardSchemaV1<T>,
+  fieldHint: string
+): SearchParamCodec<T> {
+  const absentCheck = validateSync(schema, undefined);
+  if (absentCheck.issues) {
+    throw new Error(
+      `[timber] withUrlKey: schema for '${fieldHint}' has no default value and rejects undefined input.\n` +
+        `  Search params are optional — the URL might not contain ?${fieldHint}=anything.\n` +
+        `  Add .default() to your schema or use .optional().`
+    );
+  }
+  return fromSchema(schema);
+}
+
+// ---------------------------------------------------------------------------
+// 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.
+ *
+ * Works with any codec — nuqs parsers, custom codecs, fromSchema results.
+ *
+ * ```ts
+ * import { parseAsInteger } from 'nuqs'
+ * import { 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);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// withUrlKey
+// ---------------------------------------------------------------------------
+
+/**
+ * Attach a URL key alias to a codec. The alias determines what query
+ * parameter key is used in the URL, while the TypeScript property name
+ * stays descriptive.
+ *
+ * Aliases travel with codecs through object spread composition — when
+ * you spread a bundle containing aliased codecs into defineSearchParams,
+ * the aliases come along automatically.
+ *
+ * ```ts
+ * import { parseAsString } from 'nuqs'
+ * import { withUrlKey } from '@timber-js/app/search-params'
+ *
+ * export const searchable = {
+ *   q: withUrlKey(parseAsString, 'search'),
+ *   // ?search=shoes → { q: 'shoes' }
+ * }
+ * ```
+ *
+ * Composes with withDefault:
+ * ```ts
+ * import { parseAsInteger } from 'nuqs'
+ * withUrlKey(withDefault(parseAsInteger, 1), 'p')
+ * ```
+ */
+export function withUrlKey<T>(
+  codecOrSchema: SearchParamField<T>,
+  urlKey: string
+): SearchParamCodecWithUrlKey<T> {
+  // Auto-detect Standard Schema (Zod, Valibot, ArkType) and wrap.
+  // Validate absent-param handling here since withUrlKey converts to a codec
+  // before resolveField sees it. design/23-search-params.md §"Default Validation"
+  const codec: SearchParamCodec<T> = isCodec(codecOrSchema)
+    ? codecOrSchema
+    : isStandardSchema(codecOrSchema)
+      ? validateSchemaAbsentParam(codecOrSchema, urlKey)
+      : (codecOrSchema as SearchParamCodec<T>);
+  return {
+    parse: codec.parse.bind(codec),
+    serialize: codec.serialize.bind(codec),
+    urlKey,
+  };
+}

package/src/segment-params/define.ts

@@ -0,0 +1,249 @@
+/**
+ * defineSegmentParams — factory for typed route param coercion.
+ *
+ * Creates a ParamsDefinition that coerces raw string params from the
+ * URL into typed values. Used by exporting from params.ts (segment-level)
+ * convention file.
+ *
+ * Reuses the shared Codec<T> protocol with Standard Schema auto-detection,
+ * same pattern as defineSearchParams. Runtime constraints are stricter:
+ * - serialize must return string (not null — path segments can't be omitted)
+ * - parse throwing → 404 (invalid param value)
+ *
+ * Design doc: design/07a-route-params-triage.md
+ */
+
+import type { Codec } from '../codec.js';
+import { type StandardSchemaV1, resolveCodecOrSchema } from '../schema-bridge.js';
+import { useSegmentParams as clientUseSegmentParams } from '../client/use-segment-params.js';
+
+// ---------------------------------------------------------------------------
+// Server-only ALS reference for .get()
+// ---------------------------------------------------------------------------
+
+// Same pattern as search-params: eagerly registered at server startup
+// to avoid dynamic imports that lose ALS context. See TIM-523.
+let _getSegmentParamsFn: (() => Record<string, string | string[]>) | undefined;
+
+/**
+ * Register the getSegmentParams function. Called once at module load time
+ * from request-context.ts to avoid dynamic import at call time.
+ * @internal
+ */
+export function _setGetSegmentParamsFn(fn: () => Record<string, string | string[]>): void {
+  _getSegmentParamsFn = fn;
+}
+
+function getSegmentParamsFromAls(): Record<string, string | string[]> {
+  if (!_getSegmentParamsFn) {
+    throw new Error(
+      '[timber] segmentParams.get() is only available on the server. ' +
+        'Use segmentParams.useSegmentParams() on the client.'
+    );
+  }
+  return _getSegmentParamsFn();
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Infer the output type from a Codec or StandardSchemaV1. */
+export type InferParamField<V> =
+  V extends Codec<infer T> ? T : V extends StandardSchemaV1<infer T> ? T : never;
+
+/** Acceptable field value for defineParams: a Codec or a Standard Schema. */
+export type ParamField<T = unknown> = Codec<T> | StandardSchemaV1<T>;
+
+export type { StandardSchemaV1 };
+
+/**
+ * A typed route params definition.
+ *
+ * Returned by defineParams(). Provides parse (string → typed) and
+ * serialize (typed → string) for each declared param.
+ */
+export interface ParamsDefinition<T extends Record<string, unknown>> {
+  /** Parse raw string params into typed values. Throws on invalid values. */
+  parse(raw: Record<string, string | string[]>): T;
+
+  /** Serialize typed values back to strings for URL construction. */
+  serialize(values: T): Record<string, string>;
+
+  /**
+   * Get typed segment params from the current request context (ALS).
+   *
+   * Server-only, sync.
+   *
+   * ```ts
+   * // app/products/[id]/params.ts
+   * export const segmentParams = defineSegmentParams({ id: z.coerce.number() })
+   *
+   * // app/products/[id]/page.tsx
+   * import { segmentParams } from './params'
+   * export default function Page() {
+   *   const { id } = segmentParams.get() // id: number
+   * }
+   * ```
+   */
+  get(): T;
+
+  /**
+   * Client hook for accessing typed segment params reactively.
+   *
+   * ```tsx
+   * 'use client'
+   * import { segmentParams } from './params'
+   * export function ProductHeader() {
+   *   const { id } = segmentParams.useSegmentParams()
+   * }
+   * ```
+   */
+  useSegmentParams(): T;
+
+  /** Read-only codec map. */
+  codecs: { [K in keyof T]: Codec<T[K]> };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate that no codec's serialize returns null.
+ * Route params are structural — they must produce a valid path segment.
+ */
+function validateSerialize(codecMap: Record<string, Codec<unknown>>): void {
+  for (const [key, codec] of Object.entries(codecMap)) {
+    // Test serialize with a sample parsed value to check for null
+    // We can't exhaustively test, but we can check that serialize(parse("test"))
+    // doesn't return null for a basic input.
+    try {
+      const testValue = codec.parse('test');
+      const serialized = codec.serialize(testValue);
+      if (serialized === null) {
+        throw new Error(
+          `[timber] defineSegmentParams: field '${key}' codec.serialize() returned null.\n` +
+            `  Route params are path segments — they cannot be omitted.\n` +
+            `  Ensure serialize() always returns a string.`
+        );
+      }
+    } catch (e) {
+      // parse('test') may throw for strict codecs (e.g., number-only).
+      // That's fine — it means the codec validates. We only care about
+      // serialize returning null, which we can't test without a valid value.
+      if (e instanceof Error && e.message.includes('returned null')) {
+        throw e;
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a ParamsDefinition from a map of codecs and/or Standard Schema objects.
+ *
+ * ```ts
+ * // app/products/[id]/layout.tsx
+ * import { defineSegmentParams } from '@timber-js/app/segment-params'
+ * import { z } from 'zod/v4'
+ *
+ * export const segmentParams = defineSegmentParams({
+ *   id: z.coerce.number().int().positive(),
+ * })
+ * ```
+ */
+export function defineSegmentParams<C extends Record<string, ParamField>>(
+  codecs: C
+): ParamsDefinition<{ [K in keyof C]: InferParamField<C[K]> }> {
+  type T = { [K in keyof C]: InferParamField<C[K]> };
+
+  const resolvedCodecs: Record<string, Codec<unknown>> = {};
+
+  for (const [key, value] of Object.entries(codecs)) {
+    resolvedCodecs[key] = resolveCodecOrSchema(key, value, 'param');
+  }
+
+  // Validate that serialize doesn't return null
+  validateSerialize(resolvedCodecs);
+
+  // ---- parse ----
+  function parse(raw: Record<string, string | string[]>): T {
+    const result: Record<string, unknown> = {};
+
+    for (const [key, codec] of Object.entries(resolvedCodecs)) {
+      const rawValue = raw[key];
+      // Skip params not present in the URL at this route depth.
+      // This supports TIM-834 inheritance: a parent params.ts can declare
+      // codecs for descendant segments. At shallower depths those params
+      // don't exist yet — skip them instead of passing undefined to the codec.
+      if (rawValue === undefined) continue;
+      result[key] = codec.parse(rawValue);
+    }
+
+    return result as T;
+  }
+
+  // ---- serialize ----
+  function serialize(values: T): Record<string, string> {
+    const result: Record<string, string> = {};
+
+    for (const [key, codec] of Object.entries(resolvedCodecs)) {
+      const serialized = codec.serialize(values[key as keyof T] as unknown);
+      if (serialized === null) {
+        throw new Error(
+          `[timber] params.serialize: field '${key}' serialized to null. ` +
+            `Route params must produce a valid path segment.`
+        );
+      }
+      result[key] = serialized;
+    }
+
+    return result;
+  }
+
+  // ---- get ----
+  // ALS-backed: reads segment params from the current request context.
+  // Server-only, sync.
+  //
+  // The pipeline already coerces params via coerceSegmentParams() which
+  // calls parse() and stores typed values in ALS via setSegmentParams().
+  // We return those directly instead of re-parsing, because codecs may
+  // not be idempotent (e.g., a codec that only accepts raw strings would
+  // throw if given an already-parsed value). See TIM-574.
+  function get(): T {
+    if (typeof window !== 'undefined') {
+      throw new Error(
+        '[timber] segmentParams.get() is server-only. ' +
+          'Use segmentParams.useSegmentParams() on the client.'
+      );
+    }
+    const params = getSegmentParamsFromAls();
+    // params are already coerced by the pipeline — return as-is.
+    return params as unknown as T;
+  }
+
+  // ---- useSegmentParams ----
+  // Client hook that reads typed params from the navigation context.
+  // Delegates to the existing useSegmentParams hook from use-segment-params.ts.
+  function useSegmentParams(): T {
+    const raw = clientUseSegmentParams();
+    // Params are already coerced by the server pipeline before being sent
+    // to the client — return as-is. Re-parsing would break non-idempotent
+    // codecs (e.g., z.coerce.number() on an already-parsed number). See TIM-574.
+    return raw as unknown as T;
+  }
+
+  const definition: ParamsDefinition<T> = {
+    parse,
+    serialize,
+    get,
+    useSegmentParams,
+    codecs: resolvedCodecs as { [K in keyof T]: Codec<T[K]> },
+  };
+
+  return definition;
+}

package/src/segment-params/index.ts

@@ -0,0 +1,9 @@
+// @timber-js/app/segment-params — Typed route param coercion
+//
+// This is the import path for defineSegmentParams and related types.
+// For search params, import from @timber-js/app/search-params instead.
+//
+// See design/07-routing.md §"params.ts Convention File"
+
+export type { ParamsDefinition, InferParamField, ParamField } from './define.js';
+export { defineSegmentParams } from './define.js';

package/src/server/access-gate.tsx

@@ -14,9 +14,12 @@
  */
 
 import { DenySignal, RedirectSignal } from './primitives.js';
-import type { AccessGateProps, SlotAccessGateProps, ReactElement } from './tree-builder.js';
+import type { AccessGateProps, SlotAccessGateProps } from './tree-builder.js';
 import { withSpan, setSpanAttribute } from './tracing.js';
 import { isDebug } from './debug.js';
+import type { DenyPageEntry } from './deny-boundary.js';
+import { renderMatchingDenyPage, setDenyStatus } from './deny-boundary.js';
+import type { ReactNode } from 'react';
 
 // ─── AccessGate ─────────────────────────────────────────────────────────────
 
@@ -34,25 +37,29 @@ import { isDebug } from './debug.js';
  * access.ts is a pure gate — return values are discarded. The layout below
  * gets the same data by calling the same cached functions (React.cache dedup).
  */
-export function AccessGate(props: AccessGateProps): ReactElement | Promise<ReactElement> {
-  const { accessFn, params, searchParams, segmentName, verdict, children } = props;
+export function AccessGate(props: AccessGateProps): ReactNode | Promise<ReactNode> {
+  const { accessFn, segmentName, verdict, denyPages, children } = props;
 
   // Fast path: replay pre-computed verdict from the pre-render pass.
-  // This is synchronous — Suspense boundaries cannot interfere with the
-  // status code because the signal throws before any async work.
   if (verdict !== undefined) {
     if (verdict === 'pass') {
       return children;
     }
-    // Throw the stored DenySignal or RedirectSignal synchronously.
-    // React catches this as a render-phase throw — the flush controller
-    // produces the correct HTTP status code.
+    // Render deny page in-tree when possible (same as the fallback path).
+    if (verdict instanceof DenySignal && denyPages) {
+      const denyElement = renderMatchingDenyPage(denyPages, verdict.status, verdict.data);
+      if (denyElement) {
+        setDenyStatus(verdict.status);
+        return denyElement;
+      }
+    }
     throw verdict;
   }
 
-  // Fallback: call accessFn directly (used by tree-builder.ts which
-  // doesn't run a pre-render pass, and for backward compat).
-  return accessGateFallback(accessFn, params, searchParams, segmentName, children);
+  // Primary path: call accessFn directly during render.
+  // If denyPages is provided, catch DenySignal and render the deny page
+  // in-tree — no throw reaches React Flight, no second render pass.
+  return accessGateFallback(accessFn, segmentName, denyPages, children);
 }
 
 /**
@@ -61,28 +68,41 @@ export function AccessGate(props: AccessGateProps): ReactElement | Promise<React
  */
 async function accessGateFallback(
   accessFn: AccessGateProps['accessFn'],
-  params: AccessGateProps['params'],
-  searchParams: AccessGateProps['searchParams'],
   segmentName: AccessGateProps['segmentName'],
-  children: ReactElement
-): Promise<ReactElement> {
-  await withSpan('timber.access', { 'timber.segment': segmentName ?? 'unknown' }, async () => {
-    try {
-      await accessFn({ params, searchParams });
-      await setSpanAttribute('timber.result', 'pass');
-    } catch (error: unknown) {
-      if (error instanceof DenySignal) {
-        await setSpanAttribute('timber.result', 'deny');
-        await setSpanAttribute('timber.deny_status', error.status);
-        if (error.sourceFile) {
-          await setSpanAttribute('timber.deny_file', error.sourceFile);
+  denyPages: DenyPageEntry[] | undefined,
+  children: ReactNode
+): Promise<ReactNode> {
+  try {
+    await withSpan('timber.access', { 'timber.segment': segmentName ?? 'unknown' }, async () => {
+      try {
+        await accessFn();
+        await setSpanAttribute('timber.result', 'pass');
+      } catch (error: unknown) {
+        if (error instanceof DenySignal) {
+          await setSpanAttribute('timber.result', 'deny');
+          await setSpanAttribute('timber.deny_status', error.status);
+          if (error.sourceFile) {
+            await setSpanAttribute('timber.deny_file', error.sourceFile);
+          }
+        } else if (error instanceof RedirectSignal) {
+          await setSpanAttribute('timber.result', 'redirect');
         }
-      } else if (error instanceof RedirectSignal) {
-        await setSpanAttribute('timber.result', 'redirect');
+        throw error;
+      }
+    });
+  } catch (error: unknown) {
+    // Catch DenySignal and render the deny page in-tree.
+    // No throw reaches React Flight — clean stream, single render pass.
+    // RedirectSignal and other errors propagate normally.
+    if (error instanceof DenySignal && denyPages) {
+      const denyElement = renderMatchingDenyPage(denyPages, error.status, error.data);
+      if (denyElement) {
+        setDenyStatus(error.status);
+        return denyElement;
       }
-      throw error;
     }
-  });
+    throw error;
+  }
 
   return children;
 }
@@ -96,18 +116,27 @@ async function accessGateFallback(
  * The HTTP status code is unaffected — slot denial is a UI concern, not
  * a protocol concern. The parent layout and sibling slots still render.
  *
+ * DeniedComponent is passed instead of a pre-built element so that
+ * DenySignal.data can be forwarded as the dangerouslyPassData prop
+ * and the slot name can be passed as the slot prop. See TIM-488.
+ *
  * redirect() in slot access.ts is a dev-mode error — redirecting from a
  * slot doesn't make architectural sense.
  */
-export async function SlotAccessGate(props: SlotAccessGateProps): Promise<ReactElement> {
-  const { accessFn, params, searchParams, deniedFallback, defaultFallback, children } = props;
+export async function SlotAccessGate(props: SlotAccessGateProps): Promise<ReactNode> {
+  const { accessFn, DeniedComponent, slotName, createElement, defaultFallback, children } = props;
 
   try {
-    await accessFn({ params, searchParams });
+    await accessFn();
   } catch (error: unknown) {
     // DenySignal → graceful degradation (denied.tsx → default.tsx → null)
+    // Build the denied element dynamically so DenySignal.data is forwarded.
     if (error instanceof DenySignal) {
-      return deniedFallback ?? defaultFallback ?? null;
+      return (
+        buildDeniedFallback(DeniedComponent, slotName, error.data, createElement) ??
+        defaultFallback ??
+        null
+      );
     }
 
     // RedirectSignal in slot access → dev-mode error.
@@ -123,7 +152,11 @@ export async function SlotAccessGate(props: SlotAccessGateProps): Promise<ReactE
         );
       }
       // In production, treat as a deny — render fallback rather than crash.
-      return deniedFallback ?? defaultFallback ?? null;
+      return (
+        buildDeniedFallback(DeniedComponent, slotName, undefined, createElement) ??
+        defaultFallback ??
+        null
+      );
     }
 
     // Unhandled error — re-throw so error boundaries can catch it.
@@ -141,3 +174,20 @@ export async function SlotAccessGate(props: SlotAccessGateProps): Promise<ReactE
   // Access passed — render slot content.
   return children;
 }
+
+/**
+ * Build the denied fallback element dynamically with DenySignal data.
+ * Returns null if no DeniedComponent is available.
+ */
+function buildDeniedFallback(
+  DeniedComponent: SlotAccessGateProps['DeniedComponent'],
+  slotName: string,
+  data: unknown,
+  createElement: SlotAccessGateProps['createElement']
+): ReactNode | null {
+  if (!DeniedComponent) return null;
+  return createElement(DeniedComponent, {
+    slot: slotName,
+    dangerouslyPassData: data,
+  });
+}