@timber-js/app 0.2.0-alpha.186 → 0.2.0-alpha.188

package/src/schema-bridge.ts

@@ -5,8 +5,17 @@
  * This module is the single source of truth for:
  * - StandardSchemaV1 interface (subset of the Standard Schema spec)
  * - validateSync() helper
- * - fromSchema() — bridge from Standard Schema to Codec<T>
- * - fromArraySchema() — bridge for array-valued codecs
+ * - fromSchema() — search-param bridge; scalar shape first, array second
+ * - fromArraySchema() — same loop, array shape first
+ * - fromCookieSchema() — scalar shape only; a cookie has no array shape
+ * - fromParamSchema() — route params; throws on failure (invalid param → 404)
+ *
+ * One parse loop, four candidate orders. Which shapes a bridge offers, and
+ * in what order, is the ONLY thing that differs — see §"Shape tolerance"
+ * below and in design/23-search-params.md. `serialize` is deliberately NOT
+ * shared: `null` means "omit the key" for a search param and "delete the
+ * cookie" for a cookie, so unifying it silently changed what
+ * `cookie.set([])` did (TIM-1352).
  *
  * These are re-exported from @timber-js/app/search-params, @timber-js/app/segment-params,
  * and @timber-js/app/cookies for convenience. The canonical import is
@@ -122,18 +131,21 @@ export function fromParamSchema<T>(fieldName: string, schema: StandardSchemaV1<T
  * @param fieldName - used in error messages
  * @param value - the codec or schema to resolve
  * @param mode - 'param' uses fromParamSchema (throws on parse failure),
- *               'search' uses fromSchema (falls back to default on failure)
+ *               'search' uses fromSchema (falls back to default on failure,
+ *               tolerant of the repeated-key array shape),
+ *               'cookie' uses fromCookieSchema (same, minus the array shape,
+ *               which a cookie value cannot have)
  */
 export function resolveCodecOrSchema(
   fieldName: string,
   value: unknown,
-  mode: 'param' | 'search' = 'search'
+  mode: 'param' | 'search' | 'cookie' = 'search'
 ): Codec<unknown> {
   if (isCodec(value)) return value;
   if (isStandardSchema(value)) {
-    return mode === 'param'
-      ? fromParamSchema(fieldName, value)
-      : (fromSchema(value) as Codec<unknown>);
+    if (mode === 'param') return fromParamSchema(fieldName, value);
+    if (mode === 'cookie') return fromCookieSchema(value) as Codec<unknown>;
+    return fromSchema(value) as Codec<unknown>;
   }
   throw new Error(
     `[timber] Field '${fieldName}' is not a valid codec or Standard Schema. ` +
@@ -146,51 +158,169 @@ export function resolveCodecOrSchema(
 // fromSchema — bridge from Standard Schema to Codec<T>
 // ---------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------
+// Shape tolerance — the shared parse loop for both bridges
+//
+// A URL value is `string | string[] | undefined`, but a schema is written
+// against ONE of those: `z.string()` wants `'a'`, `z.array(z.string())`
+// wants `['a']`. Nothing in Standard Schema says which — `~standard.types`
+// exists at the type level only, and probing at runtime is not reliable
+// (design/23-search-params.md §"Shape tolerance"). So a bridge tries BOTH
+// shapes rather than committing to one and discarding the value when it
+// guessed wrong.
+//
+// Each bridge only chooses WHICH candidates, and in what order. The first
+// candidate is always the shape that bridge already passed, so nothing that
+// parses today changes meaning; a later one is reached only where the old
+// code fell through to the default. `fromCookieSchema` offers ONE candidate,
+// because a cookie has no array shape at all.
+// ---------------------------------------------------------------------------
+
+/**
+ * The scalar shape, and only it. A value that cannot be repeated — a cookie —
+ * has no array shape to tolerate, so its bridge stays exactly where it was.
+ */
+function scalarOnly(value: string | string[] | undefined): unknown[] {
+  return [Array.isArray(value) ? value[0] : value];
+}
+
+/** Candidate inputs for the scalar bridge: scalar first, array second. */
+function scalarFirst(value: string | string[] | undefined): unknown[] {
+  if (value === undefined) return [undefined];
+  if (typeof value === 'string') return [value, [value]];
+  // Repeated keys: `value[0]` matches URLSearchParams.get().
+  //
+  // A raw `[]` carries no value at all. `value[0]` is `undefined`, which is
+  // the shape the scalar bridge has always passed for it, so `undefined`
+  // stays FIRST — an empty array must keep meaning "absent" and land on the
+  // schema's default. Only `defineSearchParams().parse({ tags: [] })`, the
+  // record form, can produce one: URLSearchParams never yields an empty list.
+  return value.length > 0 ? [value[0], value] : [undefined, value];
+}
+
+/** Candidate inputs for the array bridge: array first, scalar second. */
+function arrayFirst(value: string | string[] | undefined): unknown[] {
+  if (value === undefined) return [undefined];
+  if (typeof value === 'string') return [[value], value];
+  // `[]` first here for the same reason, inverted: the array bridge has
+  // always passed the empty array straight through.
+  return value.length > 0 ? [value, value[0]] : [value, undefined];
+}
+
+/**
+ * Validate `value` against `schema` in each candidate shape, then fall back
+ * to the schema's default. Shared by every bridge — they differ only in
+ * which candidates they offer, and in what order.
+ */
+function parseThroughSchema<T>(
+  schema: StandardSchemaV1<T>,
+  candidates: (value: string | string[] | undefined) => unknown[],
+  value: string | string[] | undefined
+): T {
+  const inputs = candidates(value);
+  for (let i = 0; i < inputs.length; i++) {
+    // A throw from the FIRST candidate propagates, unchanged: that is the
+    // shape the schema was written against, and a throw from it is the
+    // deliberate signal design/23 protects — an app schema may `redirect()`
+    // or `notFound()` on a value it refuses, and `validateSync` throws on
+    // an async schema.
+    //
+    // A throw from a LATER candidate is ours, not the app's. We invented
+    // that shape; the schema never agreed to receive it. A scalar-only
+    // hand-written validator doing `value.toUpperCase()`, or a schema that
+    // is async for the array shape only, would turn a field that used to
+    // fall back to its default into a render-phase 500. Treat it as "this
+    // shape does not fit" and keep going.
+    let result: StandardSchemaResult<T>;
+    try {
+      result = validateSync(schema, inputs[i]);
+    } catch (error) {
+      if (i === 0) throw error;
+      continue;
+    }
+    if (!result.issues) {
+      return result.value;
+    }
+  }
+
+  // No shape validated — try parsing undefined to get the default.
+  // Re-validate each time so factory defaults (e.g. .default(() => []))
+  // produce fresh values.
+  const defaultResult = validateSync(schema, undefined);
+  if (!defaultResult.issues) {
+    return defaultResult.value;
+  }
+
+  // No default available — the field is implicitly optional. Return
+  // undefined; defineSearchParams widens the field's inferred type to
+  // T | undefined via InferField so this doesn't lie.
+  // design/23-search-params.md §"Implicit Optionality"
+  return undefined as T;
+}
+
 /**
  * Bridge a Standard Schema-compatible schema (Zod, Valibot, ArkType) to a
  * Codec<T>.
  *
- * Parse: coerces the raw string through the schema. On validation failure,
- * parses `undefined` to get the schema's default value (the schema should have
- * a `.default()` call). If that also fails, returns `undefined`.
+ * Parse: coerces the raw URL value through the schema, trying the scalar
+ * shape and then the array shape (see `scalarFirst`), so an array schema
+ * works bare: `z.array(z.string()).default([])` yields `[]` when absent,
+ * `['a']` for `?tags=a`, and `['a','b']` for `?tags=a&tags=b`. When no
+ * shape validates, parses `undefined` to get the schema's default (the
+ * schema should have a `.default()` call). If that also fails, returns
+ * `undefined`.
  *
- * Serialize: uses `String()` for primitives, `null` for null/undefined.
+ * Serialize: `String()` for primitives, `null` for null/undefined. Note
+ * that `String(['a','b'])` is `'a,b'` — the same string `fromArraySchema`
+ * writes — so a bare array schema round-trips exactly as design/09
+ * §"Array params" describes.
+ *
+ * This is the SEARCH-PARAM bridge. Cookies use `fromCookieSchema`; a
+ * cookie has no array shape (see below).
  *
  * ```ts
- * import { fromSchema } from '@timber-js/app/codec'
  * import { z } from 'zod/v4'
  *
  * const pageCodec = fromSchema(z.coerce.number().int().min(1).default(1))
+ * const tagsCodec = fromSchema(z.array(z.string()).default([]))
  * ```
  */
 export function fromSchema<T>(schema: StandardSchemaV1<T>): Codec<T> {
   return {
-    parse(value: string | string[] | undefined): T {
-      // For array inputs (duplicate query keys), use the first value.
-      // Browsers and URLSearchParams.get() return the first occurrence.
-      const input = Array.isArray(value) ? value[0] : value;
-
-      // Try parsing the raw value
-      const result = validateSync(schema, input);
-      if (!result.issues) {
-        return result.value;
-      }
-
-      // On failure, try parsing undefined to get the default.
-      // Re-validate each time so factory defaults (e.g. .default(() => []))
-      // produce fresh values.
-      const defaultResult = validateSync(schema, undefined);
-      if (!defaultResult.issues) {
-        return defaultResult.value;
+    parse: (value: string | string[] | undefined): T =>
+      parseThroughSchema(schema, scalarFirst, value),
+    serialize(value: T): string | null {
+      if (value === null || value === undefined) {
+        return null;
       }
-
-      // No default available — the field is implicitly optional. Return
-      // undefined; defineSearchParams widens the field's inferred type to
-      // T | undefined via InferField so this doesn't lie.
-      // design/23-search-params.md §"Implicit Optionality"
-      return undefined as T;
+      return String(value);
     },
+  };
+}
 
+// ---------------------------------------------------------------------------
+// fromCookieSchema — bridge for cookie values
+// ---------------------------------------------------------------------------
+
+/**
+ * Bridge a Standard Schema for a COOKIE value.
+ *
+ * Identical to `fromSchema` minus the array shape, because a cookie cannot
+ * carry one: `Cookie:` headers and `document.cookie` yield a single string
+ * per name, and there is no repeated-key concept to be tolerant of. Sharing
+ * the search-param bridge here meant a cookie written by this very codec —
+ * `serialize(['a','b'])` → `a,b` — read back as the one-element array
+ * `['a,b']` instead of failing to its default: no repeated key in sight,
+ * just a delimiter reinterpreted as data.
+ *
+ * The `serialize` contract also differs by domain and must not be unified:
+ * for a search param `null` means "omit the key", for a cookie it means
+ * **delete the cookie** (design/29-cookies.md).
+ */
+export function fromCookieSchema<T>(schema: StandardSchemaV1<T>): Codec<T> {
+  return {
+    parse: (value: string | string[] | undefined): T =>
+      parseThroughSchema(schema, scalarOnly, value),
     serialize(value: T): string | null {
       if (value === null || value === undefined) {
         return null;
@@ -214,32 +344,24 @@ export function fromSchema<T>(schema: StandardSchemaV1<T>): Codec<T> {
  *
  * const tagsCodec = fromArraySchema(z.array(z.string()).default([]))
  * ```
+ *
+ * Since TIM-1352 a bare array schema works through `fromSchema` too, so
+ * this is no longer required to make an array field parse. Two cases still
+ * want it, both listed in design/23 §"Shape tolerance":
+ *
+ * 1. A **permissive** schema meant as an array — one that accepts a string
+ *    as readily as an array (`z.any()`, a hand-written coercing validator)
+ *    — where scalar-first ordering would settle on the scalar shape.
+ * 2. An array schema wrapped in `.catch([])`, which swallows the failure
+ *    that would otherwise trigger the array attempt.
+ *
+ * It also serializes an empty array to `null` (omitting the key) where
+ * `fromSchema` writes `''`.
  */
 export function fromArraySchema<T>(schema: StandardSchemaV1<T>): Codec<T> {
   return {
-    parse(value: string | string[] | undefined): T {
-      // Coerce single string to array for array schemas
-      let input: unknown = value;
-      if (typeof value === 'string') {
-        input = [value];
-      } else if (value === undefined) {
-        input = undefined;
-      }
-
-      const result = validateSync(schema, input);
-      if (!result.issues) {
-        return result.value;
-      }
-
-      // On failure, try undefined for default
-      const defaultResult = validateSync(schema, undefined);
-      if (!defaultResult.issues) {
-        return defaultResult.value;
-      }
-
-      return undefined as T;
-    },
-
+    parse: (value: string | string[] | undefined): T =>
+      parseThroughSchema(schema, arrayFirst, value),
     serialize(value: T): string | null {
       if (value === null || value === undefined) {
         return null;

package/src/search-params/define.ts

@@ -20,6 +20,7 @@ import type { Codec } from '../codec.js';
 // can register the getter without importing this file, which would drag
 // `nuqs` into every server entry (TIM-1298). See shared/als-slots.ts.
 import { getSearchParamsFromAls } from '../shared/als-slots.js';
+import { parseTotal } from './parse-total.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -28,13 +29,43 @@ import { getSearchParamsFromAls } from '../shared/als-slots.js';
 /**
  * A codec that converts between URL string values and typed values.
  *
- * nuqs parsers implement this interface natively — no adapter needed.
+ * `parse` receives the RAW url value: `string | string[] | undefined`.
+ * A codec must be TOTAL over that domain — return a default rather than
+ * throwing on an absent or repeated param.
+ *
+ * A codec whose own `parse` covers only a PRESENT, SINGLE-VALUED param
+ * may publish `parseServerSide` instead, and timber calls that. nuqs
+ * parsers do exactly this, which is how they become total here: absent →
+ * `null` (or their `withDefault` value), repeated → the first value, and
+ * a throw from the inner parse → `null`. See
+ * design/23-search-params.md §'nuqs parsers, made total',
+ * `parse-total.ts`, and tests/nuqs-codec-boundary.test.ts (TIM-1350).
+ *
  * Standard Schema objects (Zod, Valibot, ArkType) are auto-detected
- * by defineSearchParams and wrapped via fromSchema.
+ * by defineSearchParams and wrapped via fromSchema; those ARE total
+ * through `parse` and are called that way.
  */
 export interface SearchParamCodec<T> extends Codec<T> {
   /** Optional URL key alias, set by withUrlKey(). */
   urlKey?: string;
+  /**
+   * Optional TOTAL entry point over `string | string[] | undefined`,
+   * preferred over `parse` wherever timber invokes a codec. Declared here
+   * so the protocol is typed rather than duck-checked at each wrapper:
+   * anything that reconstructs a codec has to carry it, and a wrapper
+   * cannot carry a property the interface does not admit.
+   *
+   * It returns `T`, not `T | null`. This is the entry point timber calls,
+   * so whatever it returns IS the field's type — admitting a `null` the
+   * field type did not carry would let `SearchParamCodec<string>` produce
+   * `null` for an absent param under a non-nullable annotation. A codec
+   * whose absent-case answer is `null` declares that in `T`, exactly as a
+   * bare nuqs parser does: `parseAsString` is a `SearchParamCodec<string |
+   * null>` here, never a `SearchParamCodec<string>`.
+   *
+   * nuqs parser builders satisfy this. See parse-total.ts.
+   */
+  parseServerSide?(value: string | string[] | undefined): T;
 }
 
 /** A codec with a URL key alias attached via withUrlKey(). */
@@ -93,7 +124,7 @@ export interface SearchParamsDefinition<T extends Record<string, unknown>> {
    *
    * ```tsx
    * // app/products/page.tsx
-   * import { searchParams } from './params'
+   * import { searchParams } from './search-params'
    * export default function Page() {
    *   const { page, category } = searchParams.get()
    * }
@@ -112,15 +143,21 @@ export interface SearchParamsDefinition<T extends Record<string, unknown>> {
   /** Pick a subset of keys. Preserves codecs and aliases. */
   pick<K extends keyof T & string>(...keys: K[]): SearchParamsDefinition<Pick<T, K>>;
 
-  /** Serialize values to a query string (no leading '?'), omitting defaults. */
-  serialize(values: Partial<T>): string;
+  /**
+   * Serialize values to a query string (no leading '?'), omitting defaults
+   * and applying `withUrlKey` aliases. This is the value to pass to
+   * `<Link searchParams={...}>`.
+   *
+   * Returns a **string**, not a `URLSearchParams`. A `<Link>` prop crosses
+   * the RSC Flight boundary, and `URLSearchParams` is iterable — React
+   * serializes it as an entries array, which arrives as `[['pg','2'], …]`
+   * and renders as `?0=pg&0=2`. A string survives intact.
+   */
+  buildSearchParams(values: Partial<T>): string;
 
   /** Build a full path with query string, omitting defaults. */
   href(pathname: string, values: Partial<T>): string;
 
-  /** Build a URLSearchParams instance, omitting defaults. */
-  toSearchParams(values: Partial<T>): URLSearchParams;
-
   /** Read-only codec map for spreading into .extend(). */
   codecs: { [K in keyof T]: SearchParamCodec<T[K]> };
 
@@ -159,6 +196,21 @@ type InferSchemaInput<V> = V extends { '~standard': { types?: infer TS } }
 /**
  * Infer the output type from either a SearchParamCodec or a StandardSchemaV1.
  *
+ * A codec publishing `parseServerSide` is read through THAT signature, not
+ * through `parse` — it is the entry point timber actually calls, and it is
+ * the one that tells the truth about absent input. A bare `parseAsString`
+ * declares `parse(value: string): string` but answers `null` for a missing
+ * param, so the field is `string | null`; `parseAsInteger.withDefault(1)`
+ * narrows its own `parseServerSide` to `NonNullable<number>` and the field
+ * stays `number`. Reading `parse` instead produced a non-nullable type for
+ * a nullable field (TIM-1350).
+ *
+ * The match is structural, not nuqs-specific: any codec declaring that
+ * signature opts into being read through it, which is exactly the contract
+ * `parseTotal` applies at runtime. The two must stay in step — a type
+ * inferred from `parse` while the runtime calls `parseServerSide` is the
+ * lie this branch exists to remove.
+ *
  * Schemas whose input type rejects `undefined` (e.g. bare `z.string()`, whose
  * input is `string`) are implicitly optional: the URL might not contain the
  * param, and fromSchema returns `undefined` when the schema rejects absent
@@ -171,8 +223,11 @@ type InferSchemaInput<V> = V extends { '~standard': { types?: infer TS } }
  * keeps its narrow output type even though absent input yields `undefined`
  * at runtime. Add `.default()` to coerce schemas for accurate types.
  */
-export type InferField<V> =
-  V extends SearchParamCodec<infer T>
+export type InferField<V> = V extends {
+  parseServerSide(value: string | string[] | undefined): infer R;
+}
+  ? R
+  : V extends SearchParamCodec<infer T>
     ? T
     : V extends StandardSchemaV1<infer T>
       ? undefined extends InferSchemaInput<V>
@@ -210,13 +265,36 @@ function normalizeRaw(
  * default-omission: when serialize(value) === serialize(parse(undefined)),
  * the field is omitted from the URL.
  *
+ * Goes through `parseTotal` for the same reason request-time parsing does:
+ * a nuqs parser's own `parse` throws on absent input, and this is the
+ * absent case by construction.
+ *
+ * **A codec with no value for an absent param has no default to omit**,
+ * and `null` is returned rather than `serialize(null)`. Serializing it
+ * makes the "no value" case collide with a real one: `parseAsInteger`
+ * serializes `null` as the string `'null'`, so `buildSearchParams({ q:
+ * 'null' })` would silently drop a legitimate value (before TIM-1350 the
+ * absent parse was `undefined` and the swallowed input was the string
+ * `'undefined'` — same defect, a less likely input). Nothing is lost:
+ * `buildSearchParams` already skips a field whose `serialize` returns
+ * `null`, so a codec that encodes "no value" as an omission behaves
+ * identically, and one that encodes it as a real query value now writes
+ * it instead of dropping it.
+ *
  * Codecs are documented to return a default rather than throw, but a
  * hand-written codec that throws on absent input must not turn definition
- * into a crash — treat its default as null (nothing to omit).
+ * into a crash — treat its default as null (nothing to omit). `serialize`
+ * is inside the try for the same reason.
+ *
+ * Typed `SearchParamCodec<unknown>` rather than generic on purpose: the
+ * absent-input value is whatever the codec's total entry point returns,
+ * which for a nuqs parser is `T | null` while its `serialize` declares
+ * `T`. Widening to `unknown` states that honestly instead of casting.
  */
-function getDefaultSerialized<T>(codec: SearchParamCodec<T>): string | null {
+function getDefaultSerialized(codec: SearchParamCodec<unknown>): string | null {
   try {
-    return codec.serialize(codec.parse(undefined));
+    const absent = parseTotal(codec, undefined);
+    return absent === null || absent === undefined ? null : codec.serialize(absent);
   } catch {
     return null;
   }
@@ -382,7 +460,7 @@ function buildDefinition<T extends Record<string, unknown>>(
     for (const prop of Object.keys(codecMap)) {
       const urlKey = getUrlKey(prop);
       const rawValue = normalized[urlKey];
-      result[prop] = (codecMap[prop as keyof T] as SearchParamCodec<unknown>).parse(rawValue);
+      result[prop] = parseTotal(codecMap[prop as keyof T] as SearchParamCodec<unknown>, rawValue);
     }
 
     return result as T;
@@ -406,8 +484,14 @@ function buildDefinition<T extends Record<string, unknown>>(
     return parseSync(raw);
   }
 
-  // ---- serialize ----
-  function serialize(values: Partial<T>): string {
+  // ---- buildSearchParams ----
+  //
+  // Returns a query string. It used to have a URLSearchParams-returning
+  // sibling (`toSearchParams`) that `<Link>` consumed; that shape cannot
+  // cross the RSC Flight boundary (see the interface docstring), and having
+  // two methods produce the same query two ways was a drift waiting to
+  // happen. One method now.
+  function buildSearchParams(values: Partial<T>): string {
     const parts: string[] = [];
 
     for (const prop of Object.keys(codecMap)) {
@@ -427,28 +511,10 @@ function buildDefinition<T extends Record<string, unknown>>(
 
   // ---- href ----
   function href(pathname: string, values: Partial<T>): string {
-    const qs = serialize(values);
+    const qs = buildSearchParams(values);
     return qs ? `${pathname}?${qs}` : pathname;
   }
 
-  // ---- toSearchParams ----
-  function toSearchParams(values: Partial<T>): URLSearchParams {
-    const usp = new URLSearchParams();
-
-    for (const prop of Object.keys(codecMap)) {
-      if (!(prop in values)) continue;
-      const codec = codecMap[prop as keyof T] as SearchParamCodec<unknown>;
-      const serialized = codec.serialize(values[prop as keyof T] as unknown);
-
-      if (serialized === defaultSerialized[prop]) continue;
-      if (serialized === null) continue;
-
-      usp.set(getUrlKey(prop), serialized);
-    }
-
-    return usp;
-  }
-
   // ---- extend ----
   function extend<U extends Record<string, SearchParamCodec<unknown> | StandardSchemaV1<unknown>>>(
     newCodecs: U
@@ -542,9 +608,8 @@ function buildDefinition<T extends Record<string, unknown>>(
     useQueryStates,
     extend,
     pick,
-    serialize,
     href,
-    toSearchParams,
+    buildSearchParams,
     codecs: codecMap,
     urlKeys: Object.freeze({ ...urlKeys }),
   };

package/src/search-params/index.ts

@@ -25,4 +25,3 @@ export { defineSearchParams } from './define.js';
 export { withDefault, withUrlKey } from './wrappers.js';
 
 // Runtime registry (route-scoped useQueryStates)
-export { registerSearchParams, getSearchParamsDefinition } from './registry.js';

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

@@ -0,0 +1,78 @@
+/**
+ * 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"
+ */
+
+import type { Codec } from '../codec.js';
+
+/**
+ * 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: Codec<T>): codec is Codec<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: Codec<T>, raw: string | string[] | undefined): T {
+  return hasParseServerSide(codec) ? codec.parseServerSide(raw) : codec.parse(raw);
+}