@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.200

package/src/search-params/define.ts

@@ -0,0 +1,677 @@
+/**
+ * defineSearchParams — factory for SearchParamsDefinition<T>.
+ *
+ * Creates a typed, composable definition for a route's search parameters.
+ * Accepts both SearchParamCodec values and Standard Schema objects (Zod,
+ * Valibot, ArkType) with auto-detection. Supports URL key aliasing via
+ * withUrlKey(), default-omission serialization, and composition via
+ * .extend() / .pick().
+ *
+ * Design doc: design/23-search-params.md §"defineSearchParams — The Factory"
+ */
+
+import { useQueryStates as clientUseQueryStates } from '../client/use-query-states.ts';
+import { fromSchema, isStandardSchema, isCodec } from '../schema-bridge.ts';
+import type { StandardSchemaV1 } from '../schema-bridge.ts';
+import type { Codec } from '../codec.ts';
+// Server-only reference for .get() — avoids pulling server ALS into client
+// bundles. In client environments, .get() throws before reaching this code
+// path. The slot lives in its own leaf module so that `request-context.ts`
+// 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.ts';
+import { parseTotal } from './parse-total.ts';
+import { serializedEqual } from './serialize-equal.ts';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * A codec that converts between URL string values and typed values.
+ *
+ * `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; those ARE total
+ * through `parse` and are called that way.
+ */
+export interface SearchParamCodec<T> extends Omit<Codec<T>, 'serialize'> {
+  /**
+   * Typed value → URL string(s). Return `null` to omit/clear.
+   *
+   * A codec MAY return `string[]` to emit repeated keys (`?tag=a&tag=b`).
+   * `buildSearchParams` appends one `key=value` entry per array element;
+   * the nuqs bridge forwards the array to nuqs, which does the same.
+   * Codecs that always produce a single value return a plain string.
+   *
+   * Wider than `Codec<T>.serialize` (`string | null`) because search params
+   * have a repeated-key concept that cookies and segment params do not.
+   */
+  serialize(value: T): string | string[] | null;
+  /** 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(). */
+export interface SearchParamCodecWithUrlKey<T> extends SearchParamCodec<T> {
+  urlKey: string;
+}
+
+/** Infer the output type of a codec. */
+export type InferCodec<C> = C extends SearchParamCodec<infer T> ? T : never;
+
+/** Map of property names to codecs. */
+export type CodecMap<T extends Record<string, unknown>> = {
+  [K in keyof T]: SearchParamCodec<T[K]>;
+};
+
+/** Options for useQueryStates setter. */
+export interface SetParamsOptions {
+  /** Update URL without server roundtrip (default: false). */
+  shallow?: boolean;
+  /** Scroll to top after update (default: true). */
+  scroll?: boolean;
+  /** 'push' (default) or 'replace' for history state. */
+  history?: 'push' | 'replace';
+}
+
+/** Setter function returned by useQueryStates. */
+export type SetParams<T> = (values: Partial<T>, options?: SetParamsOptions) => void;
+
+/** Options for useQueryStates hook. */
+export interface QueryStatesOptions {
+  /** Update URL without server roundtrip (default: false). */
+  shallow?: boolean;
+  /** Scroll to top after update (default: true). */
+  scroll?: boolean;
+  /** 'push' (default) or 'replace' for history state. */
+  history?: 'push' | 'replace';
+}
+
+/**
+ * A fully typed, composable search params definition.
+ *
+ * Returned by defineSearchParams(). Carries a phantom _type property
+ * for build-time type extraction.
+ */
+export interface SearchParamsDefinition<T extends Record<string, unknown>> {
+  /** Parse raw URL search params into typed values. */
+  parse(raw: URLSearchParams | Record<string, string | string[] | undefined>): T;
+  /** Parse a Promise of URLSearchParams (e.g., from the ALS `searchParams()` API). */
+  parse(raw: Promise<URLSearchParams | Record<string, string | string[] | undefined>>): Promise<T>;
+
+  /**
+   * Get typed search params from the current request context (ALS-backed).
+   *
+   * Server-only, sync. Reads getSearchParams() from ALS and parses through codecs.
+   * Throws on client.
+   *
+   * ```tsx
+   * // app/products/page.tsx
+   * import { searchParams } from './search-params'
+   * export default function Page() {
+   *   const { page, category } = searchParams.get()
+   * }
+   * ```
+   */
+  get(): T;
+
+  /** Client hook — reads current URL params and returns typed values + setter. */
+  useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>];
+
+  /** Extend with additional codecs or Standard Schema objects. */
+  extend<U extends Record<string, SearchParamField>>(
+    codecs: U
+  ): SearchParamsDefinition<T & { [K in keyof U]: InferField<U[K]> }>;
+
+  /** 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
+   * 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;
+
+  /** Read-only codec map for spreading into .extend(). */
+  codecs: { [K in keyof T]: SearchParamCodec<T[K]> };
+
+  /** Read-only URL key alias map. Maps property names to URL query parameter keys. */
+  readonly urlKeys: Readonly<Record<string, string>>;
+
+  /**
+   * Phantom property for build-time type extraction.
+   * Never set at runtime — exists only in the type system.
+   */
+  readonly _type?: T;
+}
+
+// StandardSchemaV1 is imported from schema-bridge.ts — single source of truth.
+// Re-export for consumers that import it from this module.
+export type { StandardSchemaV1 } from '../schema-bridge.ts';
+
+// ---------------------------------------------------------------------------
+// Type-level helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract a Standard Schema's declared *input* type from its optional
+ * `~standard.types` property (part of the Standard Schema spec; Zod, Valibot,
+ * and ArkType all declare it at the type level). Falls back to `never` when
+ * the schema doesn't declare types (e.g. hand-written schemas): with no
+ * metadata we can't know whether the schema handles `undefined`, so InferField
+ * widens conservatively rather than risk a type lie.
+ */
+type InferSchemaInput<V> = V extends { '~standard': { types?: infer TS } }
+  ? [NonNullable<TS>] extends [{ input: infer I }]
+    ? I
+    : never
+  : never;
+
+/**
+ * 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
+ * input and has no default. The output type widens to `T | undefined` so the
+ * type doesn't lie. Schemas that accept `undefined` input (`.optional()`,
+ * `.default()`) keep their declared output type.
+ *
+ * Limitation: `z.coerce.*` schemas declare input `unknown`, which accepts
+ * `undefined` at the type level — so a coerce schema without `.default()`
+ * 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 {
+  parseServerSide(value: string | string[] | undefined): infer R;
+}
+  ? R
+  : V extends SearchParamCodec<infer T>
+    ? T
+    : V extends StandardSchemaV1<infer T>
+      ? undefined extends InferSchemaInput<V>
+        ? T
+        : T | undefined
+      : never;
+
+/**
+ * A codec whose total entry point is `parseServerSide`, even when `parse`
+ * has a narrower signature. nuqs multi parsers (`parseAsNativeArrayOf`) have
+ * `parse(value: readonly string[])` — too narrow for `SearchParamCodec`'s
+ * `parse(string | string[] | undefined)` — but their `parseServerSide`
+ * covers the full domain. Timber never calls `parse` directly on these;
+ * `parseTotal` always reaches `parseServerSide` first (TIM-1355).
+ */
+export interface TotalSearchParamCodec<T> {
+  parseServerSide(value: string | string[] | undefined): T;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  parse(...args: any[]): any;
+  serialize(value: T): string | string[] | null;
+  urlKey?: string;
+}
+
+/** Acceptable field value for defineSearchParams: a codec, a total codec, or a Standard Schema. */
+export type SearchParamField<T = unknown> =
+  | SearchParamCodec<T>
+  | TotalSearchParamCodec<T>
+  | StandardSchemaV1<T>;
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert URLSearchParams or a plain record to a normalized record
+ * where repeated keys produce arrays.
+ */
+function normalizeRaw(
+  raw: URLSearchParams | Record<string, string | string[] | undefined>
+): Record<string, string | string[] | undefined> {
+  if (raw instanceof URLSearchParams) {
+    const result: Record<string, string | string[] | undefined> = Object.create(null);
+    for (const key of new Set(raw.keys())) {
+      const values = raw.getAll(key);
+      result[key] = values.length === 1 ? values[0] : values;
+    }
+    return result;
+  }
+  return raw;
+}
+
+/**
+ * Compute the serialized default value for a codec. Used for
+ * 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). `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(codec: SearchParamCodec<unknown>): string | string[] | null {
+  try {
+    const absent = parseTotal(codec, undefined);
+    return absent === null || absent === undefined ? null : codec.serialize(absent);
+  } catch {
+    return null;
+  }
+}
+
+// isStandardSchema and isCodec are imported from schema-bridge.ts.
+
+/**
+ * Resolve a field value to a SearchParamCodec. Auto-detects Standard Schema
+ * objects and wraps them with fromSchema. Reads .urlKey from codecs.
+ *
+ * The returned codec is typed as `SearchParamCodec<unknown>` because the
+ * codec map uses that type. At runtime, the value may be a `Codec<T>` from
+ * `fromSchema` (whose serialize returns `string | null`) or a nuqs parser
+ * (whose serialize returns `string | string[] | null`). Both are safe
+ * because `buildSearchParams` handles the union.
+ */
+function resolveField(
+  fieldName: string,
+  value: SearchParamField
+): { codec: SearchParamCodec<unknown>; urlKey?: string } {
+  // Check for codec first (codecs may also have '~standard' if they're nuqs parsers)
+  if (isCodec(value)) {
+    const urlKey = (value as SearchParamCodec<unknown>).urlKey;
+    return { codec: value as SearchParamCodec<unknown>, urlKey };
+  }
+
+  // Auto-detect Standard Schema. Schemas that reject undefined input and
+  // have no default are implicitly optional: fromSchema returns undefined
+  // for absent params, and InferField widens the output type to
+  // T | undefined. design/23-search-params.md §"Implicit Optionality"
+  if (isStandardSchema(value)) {
+    return { codec: fromSchema(value) as SearchParamCodec<unknown> };
+  }
+
+  throw new Error(
+    `[timber] defineSearchParams: field '${fieldName}' is not a valid codec or Standard Schema. ` +
+      `Expected an object with { parse, serialize } methods, or a Standard Schema object ` +
+      `(Zod, Valibot, ArkType).`
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a SearchParamsDefinition from a map of codecs and/or Standard Schema
+ * objects. Accepts both SearchParamCodec values and raw Zod/Valibot/ArkType
+ * schemas with auto-detection.
+ *
+ * ```ts
+ * import { defineSearchParams, withDefault, withUrlKey } from '@timber-js/app/search-params'
+ * import { parseAsString, parseAsStringEnum } from 'nuqs'
+ * import { z } from 'zod/v4'
+ *
+ * export const searchParams = defineSearchParams({
+ *   page: z.coerce.number().int().min(1).default(1),     // Standard Schema — auto-wrapped
+ *   q: withUrlKey(parseAsString, 'search'),                // nuqs codec with URL alias
+ *   sort: withDefault(parseAsStringEnum(['price', 'name']), 'price'),
+ * })
+ * ```
+ */
+/**
+ * Overload: accept a Standard Schema object schema (e.g., z.object({...})).
+ *
+ * The schema must have a `.shape` property whose values are themselves
+ * Standard Schema objects. Each shape property becomes a field codec
+ * via fromSchema().
+ *
+ * ```ts
+ * const searchParams = defineSearchParams(
+ *   z.object({ page: z.coerce.number().default(1), q: z.string().optional() })
+ * )
+ * ```
+ */
+export function defineSearchParams<
+  S extends StandardSchemaV1<Record<string, unknown>> & {
+    shape: Record<string, StandardSchemaV1<unknown>>;
+  },
+>(
+  schema: S
+): SearchParamsDefinition<{ [K in keyof S['shape'] & string]: InferField<S['shape'][K]> }>;
+
+/**
+ * Overload: accept a map of codecs and/or Standard Schema objects.
+ */
+export function defineSearchParams<C extends Record<string, SearchParamField>>(
+  codecs: C
+): SearchParamsDefinition<{ [K in keyof C]: InferField<C[K]> }>;
+
+export function defineSearchParams(
+  codecsOrSchema:
+    | Record<string, SearchParamField>
+    | (StandardSchemaV1<unknown> & { shape: Record<string, StandardSchemaV1<unknown>> })
+): SearchParamsDefinition<Record<string, unknown>> {
+  // Detect Standard Schema object with .shape (e.g., z.object(...))
+  if (isStandardSchema(codecsOrSchema) && hasShape(codecsOrSchema)) {
+    const fieldCodecs: Record<string, SearchParamField> = {};
+    for (const [key, fieldSchema] of Object.entries(codecsOrSchema.shape)) {
+      if (isStandardSchema(fieldSchema)) {
+        fieldCodecs[key] = fieldSchema;
+      } else {
+        throw new Error(
+          `[timber] defineSearchParams: field '${key}' in schema.shape is not a Standard Schema. ` +
+            `All shape properties must be Standard Schema objects (Zod, Valibot, ArkType).`
+        );
+      }
+    }
+    return defineSearchParamsFromMap(fieldCodecs);
+  }
+
+  return defineSearchParamsFromMap(codecsOrSchema as Record<string, SearchParamField>);
+}
+
+/** Check if a schema has a .shape property with object-type values. */
+function hasShape(schema: unknown): schema is { shape: Record<string, unknown> } {
+  return (
+    typeof schema === 'object' &&
+    schema !== null &&
+    'shape' in schema &&
+    typeof (schema as { shape: unknown }).shape === 'object' &&
+    (schema as { shape: unknown }).shape !== null
+  );
+}
+
+function defineSearchParamsFromMap(
+  codecs: Record<string, SearchParamField>
+): SearchParamsDefinition<Record<string, unknown>> {
+  const resolvedCodecs: Record<string, SearchParamCodec<unknown>> = {};
+  const urlKeys: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(codecs)) {
+    const resolved = resolveField(key, value as SearchParamField);
+    resolvedCodecs[key] = resolved.codec;
+    if (resolved.urlKey) {
+      urlKeys[key] = resolved.urlKey;
+    }
+  }
+
+  return buildDefinition(resolvedCodecs as unknown as CodecMap<Record<string, unknown>>, urlKeys);
+}
+
+// ---------------------------------------------------------------------------
+// Internal: build the definition object
+// ---------------------------------------------------------------------------
+
+/**
+ * Internal: build a SearchParamsDefinition from a typed codec map and url keys.
+ */
+function buildDefinition<T extends Record<string, unknown>>(
+  codecMap: CodecMap<T>,
+  urlKeys: Record<string, string>
+): SearchParamsDefinition<T> {
+  // Pre-compute default serialized values for omission check
+  const defaultSerialized: Record<string, string | string[] | null> = {};
+  for (const key of Object.keys(codecMap)) {
+    defaultSerialized[key] = getDefaultSerialized(codecMap[key as keyof T]);
+  }
+
+  function getUrlKey(prop: string): string {
+    return urlKeys[prop] ?? prop;
+  }
+
+  // ---- parse ----
+  function parseSync(raw: URLSearchParams | Record<string, string | string[] | undefined>): T {
+    const normalized = normalizeRaw(raw);
+    const result: Record<string, unknown> = {};
+
+    for (const prop of Object.keys(codecMap)) {
+      const urlKey = getUrlKey(prop);
+      const rawValue = normalized[urlKey];
+      result[prop] = parseTotal(codecMap[prop as keyof T] as SearchParamCodec<unknown>, rawValue);
+    }
+
+    return result as T;
+  }
+
+  // Overloaded parse: sync when given raw params, async when given a Promise.
+  // This enables the ergonomic pattern: await def.parse(searchParams())
+  function parse(raw: URLSearchParams | Record<string, string | string[] | undefined>): T;
+  function parse(
+    raw: Promise<URLSearchParams | Record<string, string | string[] | undefined>>
+  ): Promise<T>;
+  function parse(
+    raw:
+      | URLSearchParams
+      | Record<string, string | string[] | undefined>
+      | Promise<URLSearchParams | Record<string, string | string[] | undefined>>
+  ): T | Promise<T> {
+    if (raw instanceof Promise) {
+      return raw.then(parseSync);
+    }
+    return parseSync(raw);
+  }
+
+  // ---- 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)) {
+      if (!(prop in values)) continue;
+      const codec = codecMap[prop as keyof T] as SearchParamCodec<unknown>;
+
+      // TIM-1354: serialize may not be total over null — nuqs parsers like
+      // parseAsIsoDate throw TypeError on null (null.toISOString()). Catch
+      // TypeError and omit, matching what setParams does on the client.
+      // Only TypeError — a deliberate throw (redirect(), notFound()) from a
+      // codec's serialize must propagate, not be silently swallowed.
+      let serialized: string | string[] | null;
+      try {
+        serialized = codec.serialize(values[prop as keyof T] as unknown);
+      } catch (error) {
+        if (error instanceof TypeError) continue;
+        throw error;
+      }
+
+      if (serialized === null) continue;
+      // Omit if serialized value matches the default
+      if (serializedEqual(serialized, defaultSerialized[prop])) continue;
+
+      // TIM-1353: string[] → repeated keys (?tag=a&tag=b)
+      const urlKey = encodeURIComponent(getUrlKey(prop));
+      if (Array.isArray(serialized)) {
+        for (const entry of serialized) {
+          parts.push(`${urlKey}=${encodeURIComponent(entry)}`);
+        }
+      } else {
+        parts.push(`${urlKey}=${encodeURIComponent(serialized)}`);
+      }
+    }
+
+    return parts.join('&');
+  }
+
+  // ---- href ----
+  function href(pathname: string, values: Partial<T>): string {
+    const qs = buildSearchParams(values);
+    return qs ? `${pathname}?${qs}` : pathname;
+  }
+
+  // ---- extend ----
+  function extend<U extends Record<string, SearchParamField>>(
+    newCodecs: U
+  ): SearchParamsDefinition<T & { [K in keyof U]: InferField<U[K]> }> {
+    type Combined = T & { [K in keyof U]: InferField<U[K]> };
+
+    // Resolve any Standard Schema objects in the extension
+    const resolvedNewCodecs: Record<string, SearchParamCodec<unknown>> = {};
+    const newUrlKeys: Record<string, string> = {};
+    for (const [key, value] of Object.entries(newCodecs)) {
+      const resolved = resolveField(key, value as SearchParamField);
+      resolvedNewCodecs[key] = resolved.codec;
+      if (resolved.urlKey) {
+        newUrlKeys[key] = resolved.urlKey;
+      }
+    }
+
+    const combinedCodecs = {
+      ...codecMap,
+      ...resolvedNewCodecs,
+    } as unknown as CodecMap<Combined>;
+
+    // Merge URL keys: base keys + new codec urlKeys from withUrlKey
+    const combinedUrlKeys: Record<string, string> = { ...urlKeys, ...newUrlKeys };
+
+    return buildDefinition<Combined>(combinedCodecs, combinedUrlKeys);
+  }
+
+  // ---- pick ----
+  function pick<K extends keyof T & string>(...keys: K[]): SearchParamsDefinition<Pick<T, K>> {
+    const pickedCodecs: Record<string, SearchParamCodec<unknown>> = {};
+    const pickedUrlKeys: Record<string, string> = {};
+
+    for (const key of keys) {
+      // Explicit guard — TypeScript prevents this, but JS callers and
+      // casts reach here, and "Cannot read properties of undefined
+      // (reading 'serialize')" is no help (TIM-1066).
+      if (!(key in codecMap)) {
+        throw new Error(
+          `[timber] pick('${key}'): unknown key. ` +
+            `Available keys: ${Object.keys(codecMap)
+              .map((k) => `'${k}'`)
+              .join(', ')}.`
+        );
+      }
+      pickedCodecs[key] = codecMap[key] as SearchParamCodec<unknown>;
+      if (key in urlKeys) {
+        pickedUrlKeys[key] = urlKeys[key];
+      }
+    }
+
+    return buildDefinition<Pick<T, K>>(
+      pickedCodecs as unknown as CodecMap<Pick<T, K>>,
+      pickedUrlKeys
+    );
+  }
+
+  // ---- useQueryStates ----
+  // Delegates to the 'use client' implementation from use-query-states.ts.
+  //
+  // In the RSC environment: use-query-states.ts is transformed by the RSC
+  //   plugin into a client reference proxy. Calling it throws — correct,
+  //   because hooks can't run during server component rendering.
+  // In SSR: use-query-states.ts is the real nuqs-backed function. Hooks
+  //   work during SSR's renderToReadableStream, so this works correctly.
+  // On the client: same as SSR — the real function is available.
+  function useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>] {
+    return clientUseQueryStates(codecMap, options, Object.freeze({ ...urlKeys })) as [
+      T,
+      SetParams<T>,
+    ];
+  }
+
+  // ---- get ----
+  // ALS-backed: reads getSearchParams() from the current request context
+  // and parses through codecs. Server-only, sync.
+  function get(): T {
+    if (typeof window !== 'undefined') {
+      throw new Error(
+        '[timber] searchParams.get() is server-only. ' +
+          'Use searchParams.useQueryStates() on the client.'
+      );
+    }
+    const raw = getSearchParamsFromAls();
+    return parseSync(raw);
+  }
+
+  const definition: SearchParamsDefinition<T> = {
+    parse,
+    get,
+    useQueryStates,
+    extend,
+    pick,
+    href,
+    buildSearchParams,
+    codecs: codecMap,
+    urlKeys: Object.freeze({ ...urlKeys }),
+  };
+
+  return definition;
+}