@timber-js/app 0.2.0-alpha.12 → 0.2.0-alpha.120

package/src/search-params/define.ts

@@ -0,0 +1,538 @@
+/**
+ * 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.js';
+import { fromSchema, isStandardSchema, isCodec } from '../schema-bridge.js';
+import type { StandardSchemaV1 } from '../schema-bridge.js';
+import type { Codec } from '../codec.js';
+
+// Server-only reference for .get() — avoids pulling server ALS into client bundles.
+// In client environments, .get() throws before reaching this code path.
+//
+// IMPORTANT: This is set eagerly via _setGetSearchParamsFn() at server startup
+// (called from request-context.ts module initialization). It must NOT use
+// dynamic `await import()` at call time because the async microtask from the
+// dynamic import loses AsyncLocalStorage context in React's RSC Flight renderer,
+// breaking getSearchParams() in parallel slot pages. See TIM-523.
+let _getSearchParamsFn: (() => URLSearchParams) | undefined;
+
+/**
+ * Register the getSearchParams function. Called once at module load time
+ * from request-context.ts to avoid dynamic import at call time.
+ * @internal
+ */
+export function _setGetSearchParamsFn(fn: () => URLSearchParams): void {
+  _getSearchParamsFn = fn;
+}
+
+function getSearchParamsFromAls(): URLSearchParams {
+  if (!_getSearchParamsFn) {
+    throw new Error(
+      '[timber] searchParams.get() is only available on the server. ' +
+        'Use searchParams.useQueryStates() on the client.'
+    );
+  }
+  return _getSearchParamsFn();
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * A codec that converts between URL string values and typed values.
+ *
+ * nuqs parsers implement this interface natively — no adapter needed.
+ * Standard Schema objects (Zod, Valibot, ArkType) are auto-detected
+ * by defineSearchParams and wrapped via fromSchema.
+ */
+export interface SearchParamCodec<T> extends Codec<T> {
+  /** Optional URL key alias, set by withUrlKey(). */
+  urlKey?: string;
+}
+
+/** 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 './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, SearchParamCodec<unknown> | StandardSchemaV1<unknown>>>(
+    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. */
+  serialize(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]> };
+
+  /** 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.js';
+
+// ---------------------------------------------------------------------------
+// Type-level helpers
+// ---------------------------------------------------------------------------
+
+/** Infer the output type from either a SearchParamCodec or a StandardSchemaV1. */
+export type InferField<V> =
+  V extends SearchParamCodec<infer T> ? T : V extends StandardSchemaV1<infer T> ? T : never;
+
+/** Acceptable field value for defineSearchParams: a codec or a Standard Schema. */
+export type SearchParamField<T = unknown> = SearchParamCodec<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> = {};
+    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.
+ */
+function getDefaultSerialized<T>(codec: SearchParamCodec<T>): string | null {
+  return codec.serialize(codec.parse(undefined));
+}
+
+// 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.
+ */
+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)) {
+    return { codec: value, urlKey: value.urlKey };
+  }
+
+  // Auto-detect Standard Schema
+  if (isStandardSchema(value)) {
+    return { codec: fromSchema(value) };
+  }
+
+  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).`
+  );
+}
+
+/**
+ * Validate that all codecs handle absent params (parse(undefined) doesn't throw).
+ * Catches schemas that throw on missing input. `undefined` and `null` are both
+ * valid defaults — `undefined` is correct for optional fields (e.g., `z.string().optional()`).
+ */
+function validateDefaults(codecMap: Record<string, SearchParamCodec<unknown>>): void {
+  for (const [key, codec] of Object.entries(codecMap)) {
+    try {
+      codec.parse(undefined);
+    } catch {
+      throw new Error(
+        `[timber] defineSearchParams: field '${key}' throws when the param is absent.\n` +
+          `  Search params are optional — the URL might not contain ?${key}=anything.\n` +
+          `  Add .default() or .optional() to your schema, or wrap with withDefault().`
+      );
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 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<T extends Record<string, unknown>>(
+  schema: StandardSchemaV1<T> & { shape: Record<string, StandardSchemaV1<unknown>> }
+): SearchParamsDefinition<T>;
+
+/**
+ * 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;
+    }
+  }
+
+  // Validate that all codecs handle absent params
+  validateDefaults(resolvedCodecs);
+
+  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 | 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] = (codecMap[prop as keyof T] as SearchParamCodec<unknown>).parse(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);
+  }
+
+  // ---- serialize ----
+  function serialize(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>;
+      const serialized = codec.serialize(values[prop as keyof T] as unknown);
+
+      // Omit if serialized value matches the default
+      if (serialized === defaultSerialized[prop]) continue;
+      if (serialized === null) continue;
+
+      parts.push(`${encodeURIComponent(getUrlKey(prop))}=${encodeURIComponent(serialized)}`);
+    }
+
+    return parts.join('&');
+  }
+
+  // ---- href ----
+  function href(pathname: string, values: Partial<T>): string {
+    const qs = serialize(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
+  ): 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) {
+      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,
+    serialize,
+    href,
+    toSearchParams,
+    codecs: codecMap,
+    urlKeys: Object.freeze({ ...urlKeys }),
+  };
+
+  return definition;
+}

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,
   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';
+export { registerSearchParams, getSearchParamsDefinition } from './registry.js';

package/src/search-params/registry.ts

@@ -7,7 +7,7 @@
  * Design doc: design/23-search-params.md §"Runtime: Registration at Route Load"
  */
 
-import type { SearchParamsDefinition } from './create.js';
+import type { SearchParamsDefinition } from './define.js';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const registry = new Map<string, SearchParamsDefinition<any>>();
@@ -26,6 +26,6 @@ export function registerSearchParams(route: string, definition: SearchParamsDefi
  * Returns undefined if the route hasn't been loaded yet.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function getSearchParams(route: string): SearchParamsDefinition<any> | undefined {
+export function getSearchParamsDefinition(route: string): SearchParamsDefinition<any> | undefined {
   return registry.get(route);
 }

package/src/search-params/wrappers.ts

@@ -0,0 +1,92 @@
+/**
+ * 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 } from '../schema-bridge.js';
+
+// ---------------------------------------------------------------------------
+// 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
+  const codec: SearchParamCodec<T> = isCodec(codecOrSchema)
+    ? codecOrSchema
+    : isStandardSchema(codecOrSchema)
+      ? fromSchema(codecOrSchema)
+      : (codecOrSchema as SearchParamCodec<T>);
+  return {
+    parse: codec.parse.bind(codec),
+    serialize: codec.serialize.bind(codec),
+    urlKey,
+  };
+}