@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.190

package/src/search-params/index.ts

@@ -1,34 +1,28 @@
 // @timber-js/app/search-params — Typed search params
 
+// Codec is the canonical home for the Codec type — import from
+// @timber-js/app/codec. Re-export removed per TIM-721.
+
 // Core types and factory
 export type {
   SearchParamCodec,
+  SearchParamCodecWithUrlKey,
+  TotalSearchParamCodec,
   InferCodec,
+  InferField,
+  CodecMap,
   SearchParamsDefinition,
   SetParams,
   SetParamsOptions,
   QueryStatesOptions,
-  SearchParamsOptions,
-} from './create.js';
-export { createSearchParams } from './create.js';
+  StandardSchemaV1,
+} from './define.js';
+export { defineSearchParams } from './define.js';
 
-// Codec bridges
-export { fromSchema, fromArraySchema } from './codecs.js';
+// Codec bridges moved to @timber-js/app/codec
+// Import fromSchema / fromArraySchema from '@timber-js/app/codec' instead.
 
-// Built-in codecs
-export {
-  parseAsString,
-  parseAsInteger,
-  parseAsFloat,
-  parseAsBoolean,
-  parseAsStringEnum,
-  parseAsStringLiteral,
-  withDefault,
-} from './builtin-codecs.js';
+// Codec wrappers
+export { withDefault, withUrlKey } from './wrappers.js';
 
 // Runtime registry (route-scoped useQueryStates)
-export { registerSearchParams, getSearchParams } from './registry.js';
-
-// Static analysis (build-time only)
-export type { AnalyzeResult, AnalyzeError } from './analyze.js';
-export { analyzeSearchParams, formatAnalyzeError } from './analyze.js';

package/src/search-params/parse-total.ts

@@ -0,0 +1,91 @@
+/**
+ * parseTotal — invoke a codec over the FULL raw domain.
+ *
+ * `SearchParamCodec.parse` is documented to be total over
+ * `string | string[] | undefined`, because that is exactly what a URL
+ * hands it: a param can be absent (`undefined`) or repeated (`string[]`).
+ * Timber's own codecs and the Standard Schema bridges honour that.
+ *
+ * nuqs parsers do not. Their `parse` expects a **present scalar string** —
+ * nuqs checks presence itself before ever calling it — so `parseAsBoolean`
+ * and `parseAsIsoDate` threw a render-phase 500 on an absent param and
+ * `parseAsString` returned an array on a repeated one (TIM-1350).
+ *
+ * nuqs ships the missing adapter: every parser builder exposes
+ * `parseServerSide(value: string | string[] | undefined)`, which maps
+ * absent → `null` (or the parser's `withDefault` value), takes the FIRST
+ * entry of a repeated param (matching `URLSearchParams.get()`), and wraps
+ * the inner `parse` so a throw becomes `null`. That is precisely timber's
+ * domain, so we call it in preference to `parse` rather than hand-rolling
+ * a second normalization that could disagree with the client hook.
+ *
+ * Feature detection, not an instanceof check: any codec MAY publish
+ * `parseServerSide` to declare "this is my total entry point" — it is an
+ * optional member of `SearchParamCodec` — and a codec that does not is
+ * assumed already total and called through `parse`. Timber codecs and
+ * schema bridges take the second branch untouched; several of them rely on
+ * `parse(undefined)` to produce their default.
+ *
+ * **Search params only.** Segment params (`server/param-coercion.ts`) call
+ * `codec.parse` directly and must keep doing so: their domain is a value
+ * the router matched, never absent, and a codec that REJECTS one is how a
+ * route produces a 404. Routing a rejection through nuqs's `safeParse`
+ * would turn that 404 into a silent `null` param. The two domains differ
+ * in what "no value" means, not just in plumbing. Cookies are a third
+ * domain (`cookies/define-cookie.ts`) and are likewise untouched.
+ *
+ * `parseServerSide` carries a `@deprecated` tag in nuqs (it steers users to
+ * loaders, which timber does not use). It remains public, typed and
+ * exercised; `tests/nuqs-codec-boundary.test.ts` asserts totality for every
+ * parser through timber's own API, so a nuqs release that drops it fails
+ * loudly rather than silently reinstating the 500s.
+ *
+ * Design doc: design/23-search-params.md §"nuqs parsers, made total"
+ */
+
+/**
+ * Minimal interface for anything `parseTotal` can dispatch. Only `parse` is
+ * required; `parseServerSide` is the optional total entry point. `serialize`
+ * is deliberately absent — `parseTotal` never calls it, and requiring it
+ * would prevent `SearchParamCodec<T>` (whose serialize returns `string |
+ * string[] | null`) from being passed where `Codec<T>` (whose serialize
+ * returns `string | null`) is expected.
+ */
+export interface ParseableCodec<T> {
+  parse(value: string | string[] | undefined): T;
+  parseServerSide?(value: string | string[] | undefined): T;
+}
+
+/**
+ * A codec that publishes a total entry point over the raw URL domain.
+ *
+ * The return is `T`, not `T | null`. This is the entry point timber calls,
+ * so whatever it answers IS the field's type. A `null` for an absent param
+ * belongs in `T` — a bare nuqs parser is a codec of `string | null`, and
+ * `parseAsInteger.withDefault(1)` is a codec of `number`, because nuqs
+ * narrows its own `parseServerSide` return to `NonNullable<T>`. Declaring
+ * `T | null` here would let a codec annotated `SearchParamCodec<string>`
+ * hand back `null` under a non-nullable type (TIM-1350 review).
+ */
+export interface TotalCodec<T> {
+  parseServerSide(value: string | string[] | undefined): T;
+}
+
+function hasParseServerSide<T>(
+  codec: ParseableCodec<T>
+): codec is ParseableCodec<T> & TotalCodec<T> {
+  return typeof (codec as Partial<TotalCodec<T>>).parseServerSide === 'function';
+}
+
+/**
+ * Parse a raw URL value through a codec, using the codec's total entry
+ * point when it publishes one.
+ *
+ * Returns `T`, from both branches. A `null` for an absent param is part of
+ * the codec's own `T` — see TotalCodec above — so this signature does not
+ * widen it, and a caller that must handle "no value" (`withDefault`) sees
+ * it because `T` carries it.
+ */
+export function parseTotal<T>(codec: ParseableCodec<T>, raw: string | string[] | undefined): T {
+  return hasParseServerSide(codec) ? codec.parseServerSide(raw) : codec.parse(raw);
+}

package/src/search-params/serialize-equal.ts

@@ -0,0 +1,14 @@
+/**
+ * Compare two serialize results for equality. Needed because `string[]`
+ * from repeated-key codecs does not compare by reference.
+ *
+ * Shared between define.ts (buildSearchParams default-omission) and
+ * use-query-states.ts (bridgeCodec eq). One source of truth.
+ */
+export function serializedEqual(a: string | string[] | null, b: string | string[] | null): boolean {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((v, i) => v === b[i]);
+  }
+  return false;
+}

package/src/search-params/wrappers.ts

@@ -0,0 +1,150 @@
+/**
+ * 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 {
+  InferField,
+  SearchParamCodec,
+  SearchParamCodecWithUrlKey,
+  SearchParamField,
+} from './define.js';
+import { isCodec, isStandardSchema, fromSchema } from '../schema-bridge.js';
+import { parseTotal } from './parse-total.js';
+
+// ---------------------------------------------------------------------------
+// withDefault
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap a nullable codec with a default value. The output type becomes
+ * non-nullable, and the wrapper is TOTAL over `string | string[] |
+ * undefined` even when the inner codec is not.
+ *
+ * The default is substituted for `null` — the documented "no value"
+ * answer — and for `undefined`, which is what an implicitly-optional
+ * Standard Schema field and a bare `parseAsString` produce for an absent
+ * param. Substituting only for `null` left a field typed non-nullable
+ * `string` holding `undefined` (TIM-1350).
+ *
+ * The inner codec is invoked through `parseTotal`, so a nuqs parser gets
+ * its own normalization (absent → null, repeated → first value, inner
+ * throw → null) before either check applies. That is what makes
+ * `withDefault(parseAsBoolean, false)` total; the wrapper itself does NOT
+ * catch. A throw from a codec is a deliberate signal — `fromSchema` throws
+ * on an async schema, and an app codec may `redirect()` or `notFound()` on
+ * a value it refuses — and swallowing it would convert a loud failure into
+ * a permanently-default field. design/09 §"The SearchParamCodec Protocol":
+ * a codec that throws bubbles as a render-phase error, by design.
+ *
+ * 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
+ * ```
+ *
+ * The signature strips BOTH nullish constituents from the result, not just
+ * `null`, because the runtime substitutes for both. An implicitly-optional
+ * schema field is a `SearchParamCodec<string | undefined>`, and wrapping it
+ * used to yield `SearchParamCodec<string | undefined>` — a field the
+ * wrapper guarantees is always present, still typed as maybe-absent.
+ */
+export function withDefault<T>(
+  codec: SearchParamCodec<T | null | undefined>,
+  defaultValue: NonNullable<T>
+): SearchParamCodec<NonNullable<T>> {
+  // A wrapper that rebuilds a codec from two methods drops everything else
+  // the codec carries. `withUrlKey` lost `parseServerSide` that way; this
+  // one lost `urlKey`, so `withDefault(withUrlKey(parseAsInteger, 'p'), 1)`
+  // silently read `?page=` instead of `?p=`. Carry it explicitly rather
+  // than spreading: this wrapper's own `parse` IS the total entry point,
+  // and re-publishing the inner `parseServerSide` would let `parseTotal`
+  // reach past it and skip the default entirely.
+  const wrapped: SearchParamCodec<NonNullable<T>> = {
+    parse(value: string | string[] | undefined): NonNullable<T> {
+      const result = parseTotal(codec, value);
+      return result === null || result === undefined ? defaultValue : result;
+    },
+    serialize(value: NonNullable<T>): string | string[] | null {
+      return codec.serialize(value);
+    },
+  };
+  if (codec.urlKey !== undefined) wrapped.urlKey = codec.urlKey;
+  return wrapped;
+}
+
+// ---------------------------------------------------------------------------
+// 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<F extends SearchParamField>(
+  codecOrSchema: F,
+  urlKey: string
+): SearchParamCodecWithUrlKey<InferField<F>> {
+  type T = InferField<F>;
+  // Auto-detect Standard Schema (Zod, Valibot, ArkType) and wrap. Schemas
+  // that reject undefined input are implicitly optional — fromSchema returns
+  // undefined for absent params, and InferField widens the type to include
+  // undefined. design/23-search-params.md §"Implicit Optionality"
+  const codec: SearchParamCodec<T> = isCodec(codecOrSchema)
+    ? (codecOrSchema as SearchParamCodec<T>)
+    : isStandardSchema(codecOrSchema)
+      ? (fromSchema(codecOrSchema) as SearchParamCodec<T>)
+      : (codecOrSchema as SearchParamCodec<T>);
+  // Carry the total entry point, bound like the other two methods. A
+  // codec's totality lives in a THIRD property, `parseServerSide` (see
+  // parse-total.ts); picking only `parse`/`serialize` silently produced a
+  // non-total alias, so `withUrlKey(parseAsBoolean, 'b')` threw on an
+  // absent param while the bare parser did not (TIM-1350).
+  //
+  // Bound explicitly rather than spread: a spread copies own enumerable
+  // properties only, so a class-based codec — whose `parse` and
+  // `serialize` this wrapper already reaches through the prototype —
+  // would have kept its methods and lost exactly the one that makes it
+  // total. Three properties, one rule, no dependence on how the inner
+  // codec was constructed.
+  const wrapped: SearchParamCodecWithUrlKey<T> = {
+    parse: codec.parse.bind(codec),
+    serialize: codec.serialize.bind(codec),
+    urlKey,
+  };
+  if (typeof codec.parseServerSide === 'function') {
+    wrapped.parseServerSide = codec.parseServerSide.bind(codec);
+  }
+  return wrapped;
+}

package/src/server/access-gate.tsx

@@ -14,75 +14,115 @@
  */
 
 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 { handleCaughtDeny, setFirstDeniedSegmentIndex } from './deny-boundary.js';
+import type { ReactNode } from 'react';
 
 // ─── AccessGate ─────────────────────────────────────────────────────────────
 
 /**
  * Framework-injected access gate for segments.
  *
- * When a pre-computed `verdict` prop is provided (from the pre-render pass
- * in route-element-builder.ts), AccessGate replays it synchronously — no
- * async, no re-execution of access.ts, immune to Suspense timing. The OTEL
- * span was already emitted during the pre-render pass.
- *
- * When no verdict is provided (backward compat with tree-builder.ts),
- * AccessGate calls accessFn directly with OTEL instrumentation.
+ * Calls accessFn during render — inside `renderToReadableStream`, sharing
+ * the same `React.cache` scope as layouts and pages. A `requireUser()`
+ * call in access.ts populates the cache; the same call in any layout is
+ * a free hit. Access executes exactly once per request. See TIM-1363.
  *
  * 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).
+ *
+ * On denial the gate renders the matching deny page only when this segment
+ * owns it. Because the gate is wrapped OUTSIDE its own layout, that render
+ * omits the denying segment's layout — deliberate, and the one place the
+ * in-tree path diverges from `renderDenyPage`'s inclusive slice: a layout
+ * whose access.ts denied must never run and serialize protected data into
+ * the Flight stream (TIM-1074). An ancestor-owned page is hoisted instead,
+ * because the gate also sits inside every layout above it and rendering
+ * here would wrap the deny page in all of them (TIM-1356).
+ *
+ * For skipped segments (skippedSegment=true), deny pages are NOT rendered
+ * in-tree — the client's cached layout chrome would wrap them incorrectly.
+ * Instead, the deny is recorded in ALS and rethrown so the response path
+ * can return rscErrorEnvelope for a client hard-navigate.
  */
-export function AccessGate(props: AccessGateProps): ReactElement | Promise<ReactElement> {
-  const { accessFn, params, searchParams, segmentName, verdict, children } = props;
+export function AccessGate(props: AccessGateProps): Promise<ReactNode> {
+  const {
+    accessFn,
+    segmentName,
+    segmentKey,
+    segmentIndex,
+    denyPages,
+    skippedSegment,
+    onSettled,
+    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.
-    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);
+  return accessGateFallback(
+    accessFn,
+    segmentName,
+    segmentKey,
+    segmentIndex,
+    skippedSegment ? undefined : denyPages,
+    skippedSegment,
+    onSettled,
+    children
+  );
 }
 
 /**
- * Async fallback for AccessGate when no pre-computed verdict is available.
- * Calls accessFn with OTEL instrumentation.
+ * Calls accessFn during render with OTEL instrumentation.
+ * Records the first denied segment index in ALS for post-render consumers.
  */
 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);
+  segmentKey: AccessGateProps['segmentKey'],
+  segmentIndex: AccessGateProps['segmentIndex'],
+  denyPages: DenyPageEntry[] | undefined,
+  skippedSegment: boolean | undefined,
+  onSettled: (() => void) | 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) {
+    if (error instanceof DenySignal) {
+      if (segmentIndex !== undefined) {
+        setFirstDeniedSegmentIndex(segmentIndex);
+      }
+
+      if (skippedSegment) {
+        error._hardNavigate = true;
+        throw error;
+      }
+
+      if (denyPages) {
+        return handleCaughtDeny(denyPages, error, segmentKey);
       }
-      throw error;
     }
-  });
+    throw error;
+  } finally {
+    onSettled?.();
+  }
 
   return children;
 }
@@ -96,18 +136,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 +172,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 +194,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,
+  });
+}