@timber-js/app 0.2.0-alpha.7 → 0.2.0-alpha.71

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/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;
-}

package/src/server/prerender.ts

@@ -1,139 +0,0 @@
-/**
- * Pre-rendering types and utilities.
- *
- * A `prerender.ts` file in a route segment signals the framework to
- * pre-render the route's shell at build time. This module defines the
- * types that a user exports from `prerender.ts` and utilities for
- * loading and validating those exports.
- *
- * Design doc: design/15-future-prerendering.md
- */
-
-import { parseCacheLife } from '#/plugins/cache-transform.js';
-
-// ---------------------------------------------------------------------------
-// Types — user-facing exports from prerender.ts
-// ---------------------------------------------------------------------------
-
-/**
- * The shape of a prerender.ts module's exports.
- *
- * ```ts
- * // app/docs/[slug]/prerender.ts
- * export async function generateParams() {
- *   return docs.map(d => ({ slug: d.slug }))
- * }
- * export const ttl = '1h'
- * export const tags = ['docs']
- * ```
- */
-export interface PrerenderConfig {
-  /**
-   * Generate the set of params to pre-render at build time.
-   * Required for dynamic segments (`[param]`).
-   * Optional for static segments (the single URL is pre-rendered automatically).
-   */
-  generateParams?: () => Promise<Record<string, string>[]> | Record<string, string>[];
-
-  /**
-   * How long the pre-rendered shell is considered fresh.
-   * Accepts duration strings ('30s', '5m', '1h', '2d', '1w') or seconds as a number.
-   * Default: Infinity (cache until explicit invalidation).
-   */
-  ttl?: string | number;
-
-  /**
-   * Invalidation tags. Calling `revalidateTag('docs')` purges all
-   * pre-rendered shells with that tag.
-   */
-  tags?: string[];
-
-  /**
-   * Fallback strategy for dynamic routes without `generateParams`.
-   * Only valid in `output: 'static'` mode.
-   * - `'shell'`: emit a single pre-rendered shell that serves as client-side fallback
-   */
-  fallback?: 'shell';
-}
-
-// ---------------------------------------------------------------------------
-// Parsed prerender config — framework-internal, with TTL resolved to seconds
-// ---------------------------------------------------------------------------
-
-export interface ResolvedPrerenderConfig {
-  /** TTL in seconds. Infinity if not set. */
-  ttlSeconds: number;
-  /** Invalidation tags */
-  tags: string[];
-  /** The generateParams function, if provided */
-  generateParams?: () => Promise<Record<string, string>[]> | Record<string, string>[];
-  /** Fallback strategy */
-  fallback?: 'shell';
-}
-
-/**
- * Resolve raw prerender.ts exports into a normalized config.
- *
- * Validates:
- * - `ttl` is a valid duration string or number
- * - `tags` is an array of strings
- * - `fallback` is 'shell' or undefined
- */
-export function resolvePrerenderConfig(raw: PrerenderConfig): ResolvedPrerenderConfig {
-  const ttlSeconds = raw.ttl != null ? parseCacheLife(raw.ttl) : Infinity;
-
-  const tags = raw.tags ?? [];
-  if (!Array.isArray(tags) || tags.some((t) => typeof t !== 'string')) {
-    throw new Error(
-      `prerender.ts: tags must be an array of strings. Got: ${JSON.stringify(raw.tags)}`
-    );
-  }
-
-  if (raw.fallback != null && raw.fallback !== 'shell') {
-    throw new Error(
-      `prerender.ts: fallback must be 'shell' or omitted. Got: ${JSON.stringify(raw.fallback)}`
-    );
-  }
-
-  return {
-    ttlSeconds,
-    tags,
-    generateParams: raw.generateParams,
-    fallback: raw.fallback,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Build diagnostics
-// ---------------------------------------------------------------------------
-
-export interface PrerenderDiagnostic {
-  type: 'DYNAMIC_SEGMENT_NO_PARAMS';
-  segmentPath: string;
-  message: string;
-}
-
-/**
- * Check if a dynamic segment has `generateParams` when prerender.ts is present.
- * If not, emit a diagnostic — the route falls back to SSR.
- */
-export function checkDynamicSegmentParams(
-  segmentPath: string,
-  isDynamic: boolean,
-  hasGenerateParams: boolean,
-  fallback?: 'shell'
-): PrerenderDiagnostic | null {
-  if (!isDynamic) return null;
-  if (hasGenerateParams) return null;
-  if (fallback === 'shell') return null;
-
-  return {
-    type: 'DYNAMIC_SEGMENT_NO_PARAMS',
-    segmentPath,
-    message:
-      `Dynamic segment "${segmentPath}" has prerender.ts but no generateParams(). ` +
-      `The route will fall back to SSR at request time. ` +
-      `Add generateParams() to pre-render specific param values, ` +
-      `or set fallback: 'shell' (static mode only) for a client-side fallback shell.`,
-  };
-}