@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.187

package/src/segment-params/define.ts

@@ -1,249 +0,0 @@
-/**
- * defineSegmentParams — factory for typed route param coercion.
- *
- * Creates a ParamsDefinition that coerces raw string params from the
- * URL into typed values. Used by exporting from params.ts (segment-level)
- * convention file.
- *
- * Reuses the shared Codec<T> protocol with Standard Schema auto-detection,
- * same pattern as defineSearchParams. Runtime constraints are stricter:
- * - serialize must return string (not null — path segments can't be omitted)
- * - parse throwing → 404 (invalid param value)
- *
- * Design doc: design/07a-route-params-triage.md
- */
-
-import type { Codec } from '../codec.js';
-import { type StandardSchemaV1, resolveCodecOrSchema } from '../schema-bridge.js';
-import { useSegmentParams as clientUseSegmentParams } from '../client/use-segment-params.js';
-
-// ---------------------------------------------------------------------------
-// Server-only ALS reference for .get()
-// ---------------------------------------------------------------------------
-
-// Same pattern as search-params: eagerly registered at server startup
-// to avoid dynamic imports that lose ALS context. See TIM-523.
-let _getSegmentParamsFn: (() => Record<string, string | string[]>) | undefined;
-
-/**
- * Register the getSegmentParams function. Called once at module load time
- * from request-context.ts to avoid dynamic import at call time.
- * @internal
- */
-export function _setGetSegmentParamsFn(fn: () => Record<string, string | string[]>): void {
-  _getSegmentParamsFn = fn;
-}
-
-function getSegmentParamsFromAls(): Record<string, string | string[]> {
-  if (!_getSegmentParamsFn) {
-    throw new Error(
-      '[timber] segmentParams.get() is only available on the server. ' +
-        'Use segmentParams.useSegmentParams() on the client.'
-    );
-  }
-  return _getSegmentParamsFn();
-}
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/** Infer the output type from a Codec or StandardSchemaV1. */
-export type InferParamField<V> =
-  V extends Codec<infer T> ? T : V extends StandardSchemaV1<infer T> ? T : never;
-
-/** Acceptable field value for defineParams: a Codec or a Standard Schema. */
-export type ParamField<T = unknown> = Codec<T> | StandardSchemaV1<T>;
-
-export type { StandardSchemaV1 };
-
-/**
- * A typed route params definition.
- *
- * Returned by defineParams(). Provides parse (string → typed) and
- * serialize (typed → string) for each declared param.
- */
-export interface ParamsDefinition<T extends Record<string, unknown>> {
-  /** Parse raw string params into typed values. Throws on invalid values. */
-  parse(raw: Record<string, string | string[]>): T;
-
-  /** Serialize typed values back to strings for URL construction. */
-  serialize(values: T): Record<string, string>;
-
-  /**
-   * Get typed segment params from the current request context (ALS).
-   *
-   * Server-only, sync.
-   *
-   * ```ts
-   * // app/products/[id]/params.ts
-   * export const segmentParams = defineSegmentParams({ id: z.coerce.number() })
-   *
-   * // app/products/[id]/page.tsx
-   * import { segmentParams } from './params'
-   * export default function Page() {
-   *   const { id } = segmentParams.get() // id: number
-   * }
-   * ```
-   */
-  get(): T;
-
-  /**
-   * Client hook for accessing typed segment params reactively.
-   *
-   * ```tsx
-   * 'use client'
-   * import { segmentParams } from './params'
-   * export function ProductHeader() {
-   *   const { id } = segmentParams.useSegmentParams()
-   * }
-   * ```
-   */
-  useSegmentParams(): T;
-
-  /** Read-only codec map. */
-  codecs: { [K in keyof T]: Codec<T[K]> };
-}
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Validate that no codec's serialize returns null.
- * Route params are structural — they must produce a valid path segment.
- */
-function validateSerialize(codecMap: Record<string, Codec<unknown>>): void {
-  for (const [key, codec] of Object.entries(codecMap)) {
-    // Test serialize with a sample parsed value to check for null
-    // We can't exhaustively test, but we can check that serialize(parse("test"))
-    // doesn't return null for a basic input.
-    try {
-      const testValue = codec.parse('test');
-      const serialized = codec.serialize(testValue);
-      if (serialized === null) {
-        throw new Error(
-          `[timber] defineSegmentParams: field '${key}' codec.serialize() returned null.\n` +
-            `  Route params are path segments — they cannot be omitted.\n` +
-            `  Ensure serialize() always returns a string.`
-        );
-      }
-    } catch (e) {
-      // parse('test') may throw for strict codecs (e.g., number-only).
-      // That's fine — it means the codec validates. We only care about
-      // serialize returning null, which we can't test without a valid value.
-      if (e instanceof Error && e.message.includes('returned null')) {
-        throw e;
-      }
-    }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Factory
-// ---------------------------------------------------------------------------
-
-/**
- * Create a ParamsDefinition from a map of codecs and/or Standard Schema objects.
- *
- * ```ts
- * // app/products/[id]/layout.tsx
- * import { defineSegmentParams } from '@timber-js/app/segment-params'
- * import { z } from 'zod/v4'
- *
- * export const segmentParams = defineSegmentParams({
- *   id: z.coerce.number().int().positive(),
- * })
- * ```
- */
-export function defineSegmentParams<C extends Record<string, ParamField>>(
-  codecs: C
-): ParamsDefinition<{ [K in keyof C]: InferParamField<C[K]> }> {
-  type T = { [K in keyof C]: InferParamField<C[K]> };
-
-  const resolvedCodecs: Record<string, Codec<unknown>> = {};
-
-  for (const [key, value] of Object.entries(codecs)) {
-    resolvedCodecs[key] = resolveCodecOrSchema(key, value, 'param');
-  }
-
-  // Validate that serialize doesn't return null
-  validateSerialize(resolvedCodecs);
-
-  // ---- parse ----
-  function parse(raw: Record<string, string | string[]>): T {
-    const result: Record<string, unknown> = {};
-
-    for (const [key, codec] of Object.entries(resolvedCodecs)) {
-      const rawValue = raw[key];
-      // Skip params not present in the URL at this route depth.
-      // This supports TIM-834 inheritance: a parent params.ts can declare
-      // codecs for descendant segments. At shallower depths those params
-      // don't exist yet — skip them instead of passing undefined to the codec.
-      if (rawValue === undefined) continue;
-      result[key] = codec.parse(rawValue);
-    }
-
-    return result as T;
-  }
-
-  // ---- serialize ----
-  function serialize(values: T): Record<string, string> {
-    const result: Record<string, string> = {};
-
-    for (const [key, codec] of Object.entries(resolvedCodecs)) {
-      const serialized = codec.serialize(values[key as keyof T] as unknown);
-      if (serialized === null) {
-        throw new Error(
-          `[timber] params.serialize: field '${key}' serialized to null. ` +
-            `Route params must produce a valid path segment.`
-        );
-      }
-      result[key] = serialized;
-    }
-
-    return result;
-  }
-
-  // ---- get ----
-  // ALS-backed: reads segment params from the current request context.
-  // Server-only, sync.
-  //
-  // The pipeline already coerces params via coerceSegmentParams() which
-  // calls parse() and stores typed values in ALS via setSegmentParams().
-  // We return those directly instead of re-parsing, because codecs may
-  // not be idempotent (e.g., a codec that only accepts raw strings would
-  // throw if given an already-parsed value). See TIM-574.
-  function get(): T {
-    if (typeof window !== 'undefined') {
-      throw new Error(
-        '[timber] segmentParams.get() is server-only. ' +
-          'Use segmentParams.useSegmentParams() on the client.'
-      );
-    }
-    const params = getSegmentParamsFromAls();
-    // params are already coerced by the pipeline — return as-is.
-    return params as unknown as T;
-  }
-
-  // ---- useSegmentParams ----
-  // Client hook that reads typed params from the navigation context.
-  // Delegates to the existing useSegmentParams hook from use-segment-params.ts.
-  function useSegmentParams(): T {
-    const raw = clientUseSegmentParams();
-    // Params are already coerced by the server pipeline before being sent
-    // to the client — return as-is. Re-parsing would break non-idempotent
-    // codecs (e.g., z.coerce.number() on an already-parsed number). See TIM-574.
-    return raw as unknown as T;
-  }
-
-  const definition: ParamsDefinition<T> = {
-    parse,
-    serialize,
-    get,
-    useSegmentParams,
-    codecs: resolvedCodecs as { [K in keyof T]: Codec<T[K]> },
-  };
-
-  return definition;
-}

package/src/segment-params/index.ts

@@ -1,9 +0,0 @@
-// @timber-js/app/segment-params — Typed route param coercion
-//
-// This is the import path for defineSegmentParams and related types.
-// For search params, import from @timber-js/app/search-params instead.
-//
-// See design/07-routing.md §"params.ts Convention File"
-
-export type { ParamsDefinition, InferParamField, ParamField } from './define.js';
-export { defineSegmentParams } from './define.js';