@timber-js/app 0.2.0-alpha.10 → 0.2.0-alpha.100

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

package/src/server/dev-span-processor.ts

@@ -1,78 +0,0 @@
-/**
- * DevSpanProcessor — Custom OTEL SpanProcessor that drives dev log output.
- *
- * Collects completed spans per-request (correlated by trace ID). When the
- * root span (http.server.request) ends, all child spans are already collected
- * (child spans end before parent in OTEL). The processor formats the span
- * tree and writes it to stderr.
- *
- * This replaces the old DevLogEmitter/DevLogEvents system. OTEL spans are
- * now the single source of truth for dev logging — no more parallel event
- * systems that can drift.
- *
- * Design doc: 17-logging.md §"Dev Logging", 21-dev-server.md §"Dev Logging"
- */
-
-import type { SpanProcessor, ReadableSpan } from '@opentelemetry/sdk-trace-base';
-import type { Span, Context } from '@opentelemetry/api';
-import {
-  formatSpanTree,
-  formatSpanSummary,
-  formatJson,
-  type DevLogMode,
-  type DevLoggerConfig,
-} from './dev-logger.js';
-
-export class DevSpanProcessor implements SpanProcessor {
-  private spansByTrace = new Map<string, ReadableSpan[]>();
-  private mode: DevLogMode;
-  private config: DevLoggerConfig;
-
-  constructor(config: DevLoggerConfig) {
-    this.config = config;
-    this.mode = config.mode ?? 'tree';
-  }
-
-  onStart(_span: Span, _context: Context): void {
-    // No action needed on span start — we collect on end.
-  }
-
-  onEnd(span: ReadableSpan): void {
-    const traceId = span.spanContext().traceId;
-
-    let spans = this.spansByTrace.get(traceId);
-    if (!spans) {
-      spans = [];
-      this.spansByTrace.set(traceId, spans);
-    }
-    spans.push(span);
-
-    // Root span signals request completion — all child spans are already
-    // collected because OTEL ends child spans before parent spans.
-    if (span.name === 'http.server.request') {
-      const output = this.format(spans);
-      if (output) {
-        process.stderr.write(output);
-      }
-      this.spansByTrace.delete(traceId);
-    }
-  }
-
-  private format(spans: ReadableSpan[]): string {
-    if (this.mode === 'quiet') return '';
-    if (this.mode === 'json') return formatJson(spans);
-    if (this.mode === 'summary') return formatSpanSummary(spans, this.config);
-    // Both 'tree' and 'verbose' use the tree formatter.
-    // verbose will show additional detail (every component render) once
-    // component-level spans are wired.
-    return formatSpanTree(spans, this.config);
-  }
-
-  async shutdown(): Promise<void> {
-    this.spansByTrace.clear();
-  }
-
-  async forceFlush(): Promise<void> {
-    // Nothing to flush — output happens synchronously in onEnd.
-  }
-}