@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/src/search-params/builtin-codecs.ts

@@ -1,228 +0,0 @@
-/**
- * Built-in search param codecs for common types.
- *
- * These provide zero-dependency alternatives to nuqs parsers for the most
- * common cases: strings, integers, floats, booleans, and string enums.
- *
- * All codecs implement SearchParamCodec<T | null> — returning null when the
- * param is absent or unparseable. Use withDefault() to replace null with a
- * concrete fallback value.
- *
- * Design doc: design/23-search-params.md §"Identified Gaps" #1
- * Task: TIM-362
- */
-
-import type { SearchParamCodec } from './create.js';
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Normalize array inputs to a single string (last value wins, matching
- * URLSearchParams.get() semantics). Returns undefined if absent or empty.
- */
-function normalizeInput(value: string | string[] | undefined): string | undefined {
-  if (Array.isArray(value)) {
-    return value.length > 0 ? value[value.length - 1] : undefined;
-  }
-  return value;
-}
-
-// ---------------------------------------------------------------------------
-// parseAsString
-// ---------------------------------------------------------------------------
-
-/**
- * String codec. Returns the raw string value, or null if absent.
- *
- * ```ts
- * import { parseAsString } from '@timber-js/app/search-params'
- *
- * const def = createSearchParams({ q: parseAsString })
- * // ?q=shoes → { q: 'shoes' }
- * // (absent) → { q: null }
- * ```
- */
-export const parseAsString: SearchParamCodec<string | null> = {
-  parse(value: string | string[] | undefined): string | null {
-    const v = normalizeInput(value);
-    return v !== undefined ? v : null;
-  },
-  serialize(value: string | null): string | null {
-    return value;
-  },
-};
-
-// ---------------------------------------------------------------------------
-// parseAsInteger
-// ---------------------------------------------------------------------------
-
-/**
- * Integer codec. Parses a base-10 integer, or returns null if absent or
- * not a valid integer. Rejects floats, NaN, Infinity, and non-numeric strings.
- *
- * ```ts
- * import { parseAsInteger, withDefault } from '@timber-js/app/search-params'
- *
- * const def = createSearchParams({ page: withDefault(parseAsInteger, 1) })
- * // ?page=2 → { page: 2 }
- * // ?page=abc → { page: 1 }
- * // (absent) → { page: 1 }
- * ```
- */
-export const parseAsInteger: SearchParamCodec<number | null> = {
-  parse(value: string | string[] | undefined): number | null {
-    const v = normalizeInput(value);
-    if (v === undefined || v === '') return null;
-    const n = Number(v);
-    if (!Number.isFinite(n) || !Number.isInteger(n)) return null;
-    return n;
-  },
-  serialize(value: number | null): string | null {
-    return value === null ? null : String(value);
-  },
-};
-
-// ---------------------------------------------------------------------------
-// parseAsFloat
-// ---------------------------------------------------------------------------
-
-/**
- * Float codec. Parses a finite number, or returns null if absent or invalid.
- * Rejects NaN and Infinity.
- *
- * ```ts
- * import { parseAsFloat, withDefault } from '@timber-js/app/search-params'
- *
- * const def = createSearchParams({ price: withDefault(parseAsFloat, 0) })
- * ```
- */
-export const parseAsFloat: SearchParamCodec<number | null> = {
-  parse(value: string | string[] | undefined): number | null {
-    const v = normalizeInput(value);
-    if (v === undefined || v === '') return null;
-    const n = Number(v);
-    if (!Number.isFinite(n)) return null;
-    return n;
-  },
-  serialize(value: number | null): string | null {
-    return value === null ? null : String(value);
-  },
-};
-
-// ---------------------------------------------------------------------------
-// parseAsBoolean
-// ---------------------------------------------------------------------------
-
-/**
- * Boolean codec. Accepts "true"/"1" as true, "false"/"0" as false.
- * Returns null for absent or unrecognized values.
- *
- * ```ts
- * import { parseAsBoolean, withDefault } from '@timber-js/app/search-params'
- *
- * const def = createSearchParams({ debug: withDefault(parseAsBoolean, false) })
- * // ?debug=true → { debug: true }
- * // ?debug=0 → { debug: false }
- * ```
- */
-export const parseAsBoolean: SearchParamCodec<boolean | null> = {
-  parse(value: string | string[] | undefined): boolean | null {
-    const v = normalizeInput(value);
-    if (v === undefined) return null;
-    if (v === 'true' || v === '1') return true;
-    if (v === 'false' || v === '0') return false;
-    return null;
-  },
-  serialize(value: boolean | null): string | null {
-    return value === null ? null : String(value);
-  },
-};
-
-// ---------------------------------------------------------------------------
-// parseAsStringEnum
-// ---------------------------------------------------------------------------
-
-/**
- * String enum codec. Accepts only values in the provided list.
- * Returns null for absent or invalid values.
- *
- * ```ts
- * import { parseAsStringEnum, withDefault } from '@timber-js/app/search-params'
- *
- * const sortCodec = withDefault(
- *   parseAsStringEnum(['price', 'name', 'date']),
- *   'date'
- * )
- * ```
- */
-export function parseAsStringEnum<T extends string>(
-  values: readonly T[]
-): SearchParamCodec<T | null> {
-  const allowed = new Set<string>(values);
-  return {
-    parse(value: string | string[] | undefined): T | null {
-      const v = normalizeInput(value);
-      if (v === undefined) return null;
-      return allowed.has(v) ? (v as T) : null;
-    },
-    serialize(value: T | null): string | null {
-      return value;
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// parseAsStringLiteral
-// ---------------------------------------------------------------------------
-
-/**
- * String literal codec. Functionally identical to parseAsStringEnum but
- * accepts `as const` tuples for narrower type inference.
- *
- * ```ts
- * import { parseAsStringLiteral } from '@timber-js/app/search-params'
- *
- * const sizes = ['sm', 'md', 'lg', 'xl'] as const
- * const codec = parseAsStringLiteral(sizes)
- * // Type: SearchParamCodec<'sm' | 'md' | 'lg' | 'xl' | null>
- * ```
- */
-export function parseAsStringLiteral<const T extends readonly string[]>(
-  values: T
-): SearchParamCodec<T[number] | null> {
-  // Delegates to parseAsStringEnum — same runtime behavior, different type
-  return parseAsStringEnum<T[number]>(values);
-}
-
-// ---------------------------------------------------------------------------
-// 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.
- *
- * ```ts
- * import { parseAsInteger, 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);
-    },
-  };
-}

package/src/search-params/codecs.ts

@@ -1,153 +0,0 @@
-/**
- * Built-in codecs and the fromSchema bridge for Standard Schema-compatible
- * validation libraries (Zod, Valibot, ArkType).
- *
- * Design doc: design/09-typescript.md §"The SearchParamCodec Protocol"
- */
-
-import type { SearchParamCodec } from './create.js';
-
-// ---------------------------------------------------------------------------
-// Standard Schema interface (subset)
-//
-// Standard Schema (https://github.com/standard-schema/standard-schema) defines
-// a minimal interface that Zod ≥3.24, Valibot ≥1.0, and ArkType all implement.
-// We depend only on `~standard.validate` to avoid coupling to any specific lib.
-// ---------------------------------------------------------------------------
-
-interface StandardSchemaV1<Output = unknown> {
-  '~standard': {
-    validate(value: unknown): StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
-  };
-}
-
-type StandardSchemaResult<Output> =
-  | { value: Output; issues?: undefined }
-  | { value?: undefined; issues: ReadonlyArray<{ message: string }> };
-
-// ---------------------------------------------------------------------------
-// Sync validate helper
-// ---------------------------------------------------------------------------
-
-/**
- * Zod v4's ~standard.validate() signature includes Promise in the return union
- * to satisfy the Standard Schema spec, but in practice Zod always validates
- * synchronously for the schema types we use. We assert the result is sync and
- * throw if it isn't — search params parsing must be synchronous.
- */
-function validateSync<Output>(
-  schema: StandardSchemaV1<Output>,
-  value: unknown
-): StandardSchemaResult<Output> {
-  const result = schema['~standard'].validate(value);
-  if (result instanceof Promise) {
-    throw new Error(
-      '[timber] fromSchema: schema returned a Promise — only sync schemas are supported for search params.'
-    );
-  }
-  return result;
-}
-
-// ---------------------------------------------------------------------------
-// fromSchema — bridge from Standard Schema to SearchParamCodec
-// ---------------------------------------------------------------------------
-
-/**
- * Bridge a Standard Schema-compatible schema (Zod, Valibot, ArkType) to a
- * SearchParamCodec.
- *
- * Parse: coerces the raw URL 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`.
- *
- * Serialize: uses `String()` for primitives, `null` for null/undefined.
- *
- * ```ts
- * import { fromSchema } from '@timber-js/app/search-params'
- * import { z } from 'zod/v4'
- *
- * const pageCodec = fromSchema(z.coerce.number().int().min(1).default(1))
- * ```
- */
-export function fromSchema<T>(schema: StandardSchemaV1<T>): SearchParamCodec<T> {
-  return {
-    parse(value: string | string[] | undefined): T {
-      // For array inputs, take the last value (consistent with URLSearchParams.get())
-      const input = Array.isArray(value) ? value[value.length - 1] : 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
-      const defaultResult = validateSync(schema, undefined);
-      if (!defaultResult.issues) {
-        return defaultResult.value;
-      }
-
-      // No default available — return undefined (codec design choice)
-      return undefined as T;
-    },
-
-    serialize(value: T): string | null {
-      if (value === null || value === undefined) {
-        return null;
-      }
-      return String(value);
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// fromArraySchema — bridge for array-valued search params
-// ---------------------------------------------------------------------------
-
-/**
- * Bridge a Standard Schema for array values. Handles both single strings
- * and repeated query keys (`?tag=a&tag=b`).
- *
- * ```ts
- * import { fromArraySchema } from '@timber-js/app/search-params'
- * import { z } from 'zod/v4'
- *
- * const tagsCodec = fromArraySchema(z.array(z.string()).default([]))
- * ```
- */
-export function fromArraySchema<T>(schema: StandardSchemaV1<T>): SearchParamCodec<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;
-    },
-
-    serialize(value: T): string | null {
-      if (value === null || value === undefined) {
-        return null;
-      }
-      if (Array.isArray(value)) {
-        return value.length === 0 ? null : value.join(',');
-      }
-      return String(value);
-    },
-  };
-}

package/src/search-params/create.ts

@@ -1,321 +0,0 @@
-/**
- * createSearchParams — factory for SearchParamsDefinition<T>.
- *
- * Creates a typed, composable definition for a route's search parameters.
- * Supports codec protocol, URL key aliasing, default-omission serialization,
- * and composition via .extend() / .pick().
- *
- * Design doc: design/09-typescript.md §"Typed searchParams — search-params.ts"
- */
-
-import { useQueryStates as clientUseQueryStates } from '#/client/use-query-states.js';
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/**
- * A codec that converts between URL string values and typed values.
- *
- * nuqs parsers (parseAsInteger, parseAsString, etc.) implement this
- * interface natively — no adapter needed.
- */
-export interface SearchParamCodec<T> {
-  /** URL string → typed value. Receives undefined when the param is absent. */
-  parse(value: string | string[] | undefined): T;
-  /** Typed value → URL string. Return null to omit from URL. */
-  serialize(value: T): string | null;
-}
-
-/** 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';
-}
-
-/** Options for createSearchParams and .extend(). */
-export interface SearchParamsOptions<Keys extends string = string> {
-  /** Map property names to different URL query parameter keys. */
-  urlKeys?: Partial<Record<Keys, string>>;
-}
-
-/**
- * A fully typed, composable search params definition.
- *
- * Returned by createSearchParams(). 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;
-
-  /** Client hook — reads current URL params and returns typed values + setter. */
-  useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>];
-
-  /** Extend with additional codecs. Key collisions are a type error. */
-  extend<U extends Record<string, SearchParamCodec<unknown>>>(
-    codecs: U,
-    options?: SearchParamsOptions<string>
-  ): SearchParamsDefinition<T & { [K in keyof U]: InferCodec<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(). Aliases NOT carried. */
-  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;
-}
-
-// ---------------------------------------------------------------------------
-// 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));
-}
-
-// ---------------------------------------------------------------------------
-// Factory
-// ---------------------------------------------------------------------------
-
-/**
- * Create a SearchParamsDefinition from a codec map and optional URL key aliases.
- *
- * ```ts
- * import { createSearchParams, fromSchema } from '@timber-js/app/search-params'
- * import { z } from 'zod/v4'
- *
- * export default createSearchParams({
- *   page: fromSchema(z.coerce.number().int().min(1).default(1)),
- *   q: { parse: (v) => v ?? null, serialize: (v) => v },
- * }, {
- *   urlKeys: { q: 'search' },
- * })
- * ```
- */
-export function createSearchParams<C extends Record<string, SearchParamCodec<unknown>>>(
-  codecs: C,
-  options?: SearchParamsOptions<Extract<keyof C, string>>
-): SearchParamsDefinition<{ [K in keyof C]: InferCodec<C[K]> }> {
-  type T = { [K in keyof C]: InferCodec<C[K]> };
-  const urlKeys: Record<string, string> = {};
-  if (options?.urlKeys) {
-    for (const [k, v] of Object.entries(options.urlKeys)) {
-      if (v !== undefined) urlKeys[k] = v;
-    }
-  }
-
-  return buildDefinition<T>(codecs as unknown as CodecMap<T>, urlKeys);
-}
-
-/**
- * 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 parse(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;
-  }
-
-  // ---- 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>>>(
-    newCodecs: U,
-    extendOptions?: SearchParamsOptions<string>
-  ): SearchParamsDefinition<T & { [K in keyof U]: InferCodec<U[K]> }> {
-    type Combined = T & { [K in keyof U]: InferCodec<U[K]> };
-
-    const combinedCodecs = {
-      ...codecMap,
-      ...newCodecs,
-    } as unknown as CodecMap<Combined>;
-
-    // Merge URL keys: extend options override, but do NOT inherit from base
-    // (aliases are route-level, not carried through .codecs)
-    const combinedUrlKeys: Record<string, string> = { ...urlKeys };
-    if (extendOptions?.urlKeys) {
-      for (const [k, v] of Object.entries(extendOptions.urlKeys)) {
-        if (v !== undefined) combinedUrlKeys[k] = v;
-      }
-    }
-
-    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>,
-    ];
-  }
-
-  const definition: SearchParamsDefinition<T> = {
-    parse,
-    useQueryStates,
-    extend,
-    pick,
-    serialize,
-    href,
-    toSearchParams,
-    codecs: codecMap,
-    urlKeys: Object.freeze({ ...urlKeys }),
-  };
-
-  return definition;
-}