@timber-js/app 0.2.0-alpha.13 → 0.2.0-alpha.132

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/dev-fetch-instrumentation.ts

@@ -1,96 +0,0 @@
-/**
- * Dev-mode fetch instrumentation — patches globalThis.fetch to create OTEL
- * spans for every fetch call, giving visibility into async data fetching
- * in the dev request log tree.
- *
- * Only activated in dev mode — zero overhead in production.
- *
- * The spans are automatically children of the active OTEL context (e.g. a
- * timber.page or timber.layout span), so they appear nested under the
- * component that initiated the fetch in the dev log tree.
- *
- * Design ref: 17-logging.md §"Dev Logging", LOCAL-289
- */
-
-import * as api from '@opentelemetry/api';
-
-export type DevFetchCleanup = () => void;
-
-/**
- * Patch globalThis.fetch to wrap every call in an OTEL span.
- *
- * Returns a cleanup function that restores the original fetch.
- * Only call this in dev mode.
- */
-export function instrumentDevFetch(): DevFetchCleanup {
-  const originalFetch = globalThis.fetch;
-  const tracer = api.trace.getTracer('timber.js');
-
-  globalThis.fetch = async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
-    const { method, url } = extractFetchInfo(input, init);
-
-    return tracer.startActiveSpan(
-      'timber.fetch',
-      {
-        attributes: {
-          'http.request.method': method,
-          'http.url': url,
-        },
-      },
-      async (span) => {
-        try {
-          const response = await originalFetch(input, init);
-
-          span.setAttribute('http.response.status_code', response.status);
-
-          // Surface cache status from standard headers
-          const cacheStatus =
-            response.headers.get('X-Cache') ?? response.headers.get('CF-Cache-Status');
-          if (cacheStatus) {
-            span.setAttribute('timber.cache_status', cacheStatus);
-          }
-
-          span.setStatus({ code: api.SpanStatusCode.OK });
-          span.end();
-          return response;
-        } catch (error) {
-          span.setStatus({ code: api.SpanStatusCode.ERROR });
-          if (error instanceof Error) {
-            span.setAttribute('timber.fetch_error', error.message);
-            span.recordException(error);
-          }
-          span.end();
-          throw error;
-        }
-      }
-    );
-  };
-
-  return () => {
-    globalThis.fetch = originalFetch;
-  };
-}
-
-/**
- * Extract method and URL from the various fetch() call signatures.
- */
-function extractFetchInfo(
-  input: RequestInfo | URL,
-  init?: RequestInit
-): { method: string; url: string } {
-  let method = init?.method ?? 'GET';
-  let url: string;
-
-  if (input instanceof Request) {
-    url = input.url;
-    if (!init?.method) {
-      method = input.method;
-    }
-  } else if (input instanceof URL) {
-    url = input.toString();
-  } else {
-    url = input;
-  }
-
-  return { method: method.toUpperCase(), url };
-}