@timber-js/app 0.2.0-alpha.12 → 0.2.0-alpha.120

package/dist/_chunks/define-8zQ8Vm7x.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-8zQ8Vm7x.js","names":[],"sources":["../../src/search-params/define.ts"],"sourcesContent":["/**\n * defineSearchParams — factory for SearchParamsDefinition<T>.\n *\n * Creates a typed, composable definition for a route's search parameters.\n * Accepts both SearchParamCodec values and Standard Schema objects (Zod,\n * Valibot, ArkType) with auto-detection. Supports URL key aliasing via\n * withUrlKey(), default-omission serialization, and composition via\n * .extend() / .pick().\n *\n * Design doc: design/23-search-params.md §\"defineSearchParams — The Factory\"\n */\n\nimport { useQueryStates as clientUseQueryStates } from '../client/use-query-states.js';\nimport { fromSchema, isStandardSchema, isCodec } from '../schema-bridge.js';\nimport type { StandardSchemaV1 } from '../schema-bridge.js';\nimport type { Codec } from '../codec.js';\n\n// Server-only reference for .get() — avoids pulling server ALS into client bundles.\n// In client environments, .get() throws before reaching this code path.\n//\n// IMPORTANT: This is set eagerly via _setGetSearchParamsFn() at server startup\n// (called from request-context.ts module initialization). It must NOT use\n// dynamic `await import()` at call time because the async microtask from the\n// dynamic import loses AsyncLocalStorage context in React's RSC Flight renderer,\n// breaking getSearchParams() in parallel slot pages. See TIM-523.\nlet _getSearchParamsFn: (() => URLSearchParams) | undefined;\n\n/**\n * Register the getSearchParams function. Called once at module load time\n * from request-context.ts to avoid dynamic import at call time.\n * @internal\n */\nexport function _setGetSearchParamsFn(fn: () => URLSearchParams): void {\n  _getSearchParamsFn = fn;\n}\n\nfunction getSearchParamsFromAls(): URLSearchParams {\n  if (!_getSearchParamsFn) {\n    throw new Error(\n      '[timber] searchParams.get() is only available on the server. ' +\n        'Use searchParams.useQueryStates() on the client.'\n    );\n  }\n  return _getSearchParamsFn();\n}\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/**\n * A codec that converts between URL string values and typed values.\n *\n * nuqs parsers implement this interface natively — no adapter needed.\n * Standard Schema objects (Zod, Valibot, ArkType) are auto-detected\n * by defineSearchParams and wrapped via fromSchema.\n */\nexport interface SearchParamCodec<T> extends Codec<T> {\n  /** Optional URL key alias, set by withUrlKey(). */\n  urlKey?: string;\n}\n\n/** A codec with a URL key alias attached via withUrlKey(). */\nexport interface SearchParamCodecWithUrlKey<T> extends SearchParamCodec<T> {\n  urlKey: string;\n}\n\n/** Infer the output type of a codec. */\nexport type InferCodec<C> = C extends SearchParamCodec<infer T> ? T : never;\n\n/** Map of property names to codecs. */\nexport type CodecMap<T extends Record<string, unknown>> = {\n  [K in keyof T]: SearchParamCodec<T[K]>;\n};\n\n/** Options for useQueryStates setter. */\nexport interface SetParamsOptions {\n  /** Update URL without server roundtrip (default: false). */\n  shallow?: boolean;\n  /** Scroll to top after update (default: true). */\n  scroll?: boolean;\n  /** 'push' (default) or 'replace' for history state. */\n  history?: 'push' | 'replace';\n}\n\n/** Setter function returned by useQueryStates. */\nexport type SetParams<T> = (values: Partial<T>, options?: SetParamsOptions) => void;\n\n/** Options for useQueryStates hook. */\nexport interface QueryStatesOptions {\n  /** Update URL without server roundtrip (default: false). */\n  shallow?: boolean;\n  /** Scroll to top after update (default: true). */\n  scroll?: boolean;\n  /** 'push' (default) or 'replace' for history state. */\n  history?: 'push' | 'replace';\n}\n\n/**\n * A fully typed, composable search params definition.\n *\n * Returned by defineSearchParams(). Carries a phantom _type property\n * for build-time type extraction.\n */\nexport interface SearchParamsDefinition<T extends Record<string, unknown>> {\n  /** Parse raw URL search params into typed values. */\n  parse(raw: URLSearchParams | Record<string, string | string[] | undefined>): T;\n  /** Parse a Promise of URLSearchParams (e.g., from the ALS `searchParams()` API). */\n  parse(raw: Promise<URLSearchParams | Record<string, string | string[] | undefined>>): Promise<T>;\n\n  /**\n   * Get typed search params from the current request context (ALS-backed).\n   *\n   * Server-only, sync. Reads getSearchParams() from ALS and parses through codecs.\n   * Throws on client.\n   *\n   * ```tsx\n   * // app/products/page.tsx\n   * import { searchParams } from './params'\n   * export default function Page() {\n   *   const { page, category } = searchParams.get()\n   * }\n   * ```\n   */\n  get(): T;\n\n  /** Client hook — reads current URL params and returns typed values + setter. */\n  useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>];\n\n  /** Extend with additional codecs or Standard Schema objects. */\n  extend<U extends Record<string, SearchParamCodec<unknown> | StandardSchemaV1<unknown>>>(\n    codecs: U\n  ): SearchParamsDefinition<T & { [K in keyof U]: InferField<U[K]> }>;\n\n  /** Pick a subset of keys. Preserves codecs and aliases. */\n  pick<K extends keyof T & string>(...keys: K[]): SearchParamsDefinition<Pick<T, K>>;\n\n  /** Serialize values to a query string (no leading '?'), omitting defaults. */\n  serialize(values: Partial<T>): string;\n\n  /** Build a full path with query string, omitting defaults. */\n  href(pathname: string, values: Partial<T>): string;\n\n  /** Build a URLSearchParams instance, omitting defaults. */\n  toSearchParams(values: Partial<T>): URLSearchParams;\n\n  /** Read-only codec map for spreading into .extend(). */\n  codecs: { [K in keyof T]: SearchParamCodec<T[K]> };\n\n  /** Read-only URL key alias map. Maps property names to URL query parameter keys. */\n  readonly urlKeys: Readonly<Record<string, string>>;\n\n  /**\n   * Phantom property for build-time type extraction.\n   * Never set at runtime — exists only in the type system.\n   */\n  readonly _type?: T;\n}\n\n// StandardSchemaV1 is imported from schema-bridge.ts — single source of truth.\n// Re-export for consumers that import it from this module.\nexport type { StandardSchemaV1 } from '../schema-bridge.js';\n\n// ---------------------------------------------------------------------------\n// Type-level helpers\n// ---------------------------------------------------------------------------\n\n/** Infer the output type from either a SearchParamCodec or a StandardSchemaV1. */\nexport type InferField<V> =\n  V extends SearchParamCodec<infer T> ? T : V extends StandardSchemaV1<infer T> ? T : never;\n\n/** Acceptable field value for defineSearchParams: a codec or a Standard Schema. */\nexport type SearchParamField<T = unknown> = SearchParamCodec<T> | StandardSchemaV1<T>;\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Convert URLSearchParams or a plain record to a normalized record\n * where repeated keys produce arrays.\n */\nfunction normalizeRaw(\n  raw: URLSearchParams | Record<string, string | string[] | undefined>\n): Record<string, string | string[] | undefined> {\n  if (raw instanceof URLSearchParams) {\n    const result: Record<string, string | string[] | undefined> = {};\n    for (const key of new Set(raw.keys())) {\n      const values = raw.getAll(key);\n      result[key] = values.length === 1 ? values[0] : values;\n    }\n    return result;\n  }\n  return raw;\n}\n\n/**\n * Compute the serialized default value for a codec. Used for\n * default-omission: when serialize(value) === serialize(parse(undefined)),\n * the field is omitted from the URL.\n */\nfunction getDefaultSerialized<T>(codec: SearchParamCodec<T>): string | null {\n  return codec.serialize(codec.parse(undefined));\n}\n\n// isStandardSchema and isCodec are imported from schema-bridge.ts.\n\n/**\n * Resolve a field value to a SearchParamCodec. Auto-detects Standard Schema\n * objects and wraps them with fromSchema. Reads .urlKey from codecs.\n */\nfunction resolveField(\n  fieldName: string,\n  value: SearchParamField\n): { codec: SearchParamCodec<unknown>; urlKey?: string } {\n  // Check for codec first (codecs may also have '~standard' if they're nuqs parsers)\n  if (isCodec(value)) {\n    return { codec: value, urlKey: value.urlKey };\n  }\n\n  // Auto-detect Standard Schema\n  if (isStandardSchema(value)) {\n    return { codec: fromSchema(value) };\n  }\n\n  throw new Error(\n    `[timber] defineSearchParams: field '${fieldName}' is not a valid codec or Standard Schema. ` +\n      `Expected an object with { parse, serialize } methods, or a Standard Schema object ` +\n      `(Zod, Valibot, ArkType).`\n  );\n}\n\n/**\n * Validate that all codecs handle absent params (parse(undefined) doesn't throw).\n * Catches schemas that throw on missing input. `undefined` and `null` are both\n * valid defaults — `undefined` is correct for optional fields (e.g., `z.string().optional()`).\n */\nfunction validateDefaults(codecMap: Record<string, SearchParamCodec<unknown>>): void {\n  for (const [key, codec] of Object.entries(codecMap)) {\n    try {\n      codec.parse(undefined);\n    } catch {\n      throw new Error(\n        `[timber] defineSearchParams: field '${key}' throws when the param is absent.\\n` +\n          `  Search params are optional — the URL might not contain ?${key}=anything.\\n` +\n          `  Add .default() or .optional() to your schema, or wrap with withDefault().`\n      );\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a SearchParamsDefinition from a map of codecs and/or Standard Schema\n * objects. Accepts both SearchParamCodec values and raw Zod/Valibot/ArkType\n * schemas with auto-detection.\n *\n * ```ts\n * import { defineSearchParams, withDefault, withUrlKey } from '@timber-js/app/search-params'\n * import { parseAsString, parseAsStringEnum } from 'nuqs'\n * import { z } from 'zod/v4'\n *\n * export const searchParams = defineSearchParams({\n *   page: z.coerce.number().int().min(1).default(1),     // Standard Schema — auto-wrapped\n *   q: withUrlKey(parseAsString, 'search'),                // nuqs codec with URL alias\n *   sort: withDefault(parseAsStringEnum(['price', 'name']), 'price'),\n * })\n * ```\n */\n/**\n * Overload: accept a Standard Schema object schema (e.g., z.object({...})).\n *\n * The schema must have a `.shape` property whose values are themselves\n * Standard Schema objects. Each shape property becomes a field codec\n * via fromSchema().\n *\n * ```ts\n * const searchParams = defineSearchParams(\n *   z.object({ page: z.coerce.number().default(1), q: z.string().optional() })\n * )\n * ```\n */\nexport function defineSearchParams<T extends Record<string, unknown>>(\n  schema: StandardSchemaV1<T> & { shape: Record<string, StandardSchemaV1<unknown>> }\n): SearchParamsDefinition<T>;\n\n/**\n * Overload: accept a map of codecs and/or Standard Schema objects.\n */\nexport function defineSearchParams<C extends Record<string, SearchParamField>>(\n  codecs: C\n): SearchParamsDefinition<{ [K in keyof C]: InferField<C[K]> }>;\n\nexport function defineSearchParams(\n  codecsOrSchema:\n    | Record<string, SearchParamField>\n    | (StandardSchemaV1<unknown> & { shape: Record<string, StandardSchemaV1<unknown>> })\n): SearchParamsDefinition<Record<string, unknown>> {\n  // Detect Standard Schema object with .shape (e.g., z.object(...))\n  if (isStandardSchema(codecsOrSchema) && hasShape(codecsOrSchema)) {\n    const fieldCodecs: Record<string, SearchParamField> = {};\n    for (const [key, fieldSchema] of Object.entries(codecsOrSchema.shape)) {\n      if (isStandardSchema(fieldSchema)) {\n        fieldCodecs[key] = fieldSchema;\n      } else {\n        throw new Error(\n          `[timber] defineSearchParams: field '${key}' in schema.shape is not a Standard Schema. ` +\n            `All shape properties must be Standard Schema objects (Zod, Valibot, ArkType).`\n        );\n      }\n    }\n    return defineSearchParamsFromMap(fieldCodecs);\n  }\n\n  return defineSearchParamsFromMap(codecsOrSchema as Record<string, SearchParamField>);\n}\n\n/** Check if a schema has a .shape property with object-type values. */\nfunction hasShape(schema: unknown): schema is { shape: Record<string, unknown> } {\n  return (\n    typeof schema === 'object' &&\n    schema !== null &&\n    'shape' in schema &&\n    typeof (schema as { shape: unknown }).shape === 'object' &&\n    (schema as { shape: unknown }).shape !== null\n  );\n}\n\nfunction defineSearchParamsFromMap(\n  codecs: Record<string, SearchParamField>\n): SearchParamsDefinition<Record<string, unknown>> {\n  const resolvedCodecs: Record<string, SearchParamCodec<unknown>> = {};\n  const urlKeys: Record<string, string> = {};\n\n  for (const [key, value] of Object.entries(codecs)) {\n    const resolved = resolveField(key, value as SearchParamField);\n    resolvedCodecs[key] = resolved.codec;\n    if (resolved.urlKey) {\n      urlKeys[key] = resolved.urlKey;\n    }\n  }\n\n  // Validate that all codecs handle absent params\n  validateDefaults(resolvedCodecs);\n\n  return buildDefinition(resolvedCodecs as unknown as CodecMap<Record<string, unknown>>, urlKeys);\n}\n\n// ---------------------------------------------------------------------------\n// Internal: build the definition object\n// ---------------------------------------------------------------------------\n\n/**\n * Internal: build a SearchParamsDefinition from a typed codec map and url keys.\n */\nfunction buildDefinition<T extends Record<string, unknown>>(\n  codecMap: CodecMap<T>,\n  urlKeys: Record<string, string>\n): SearchParamsDefinition<T> {\n  // Pre-compute default serialized values for omission check\n  const defaultSerialized: Record<string, string | null> = {};\n  for (const key of Object.keys(codecMap)) {\n    defaultSerialized[key] = getDefaultSerialized(codecMap[key as keyof T]);\n  }\n\n  function getUrlKey(prop: string): string {\n    return urlKeys[prop] ?? prop;\n  }\n\n  // ---- parse ----\n  function parseSync(raw: URLSearchParams | Record<string, string | string[] | undefined>): T {\n    const normalized = normalizeRaw(raw);\n    const result: Record<string, unknown> = {};\n\n    for (const prop of Object.keys(codecMap)) {\n      const urlKey = getUrlKey(prop);\n      const rawValue = normalized[urlKey];\n      result[prop] = (codecMap[prop as keyof T] as SearchParamCodec<unknown>).parse(rawValue);\n    }\n\n    return result as T;\n  }\n\n  // Overloaded parse: sync when given raw params, async when given a Promise.\n  // This enables the ergonomic pattern: await def.parse(searchParams())\n  function parse(raw: URLSearchParams | Record<string, string | string[] | undefined>): T;\n  function parse(\n    raw: Promise<URLSearchParams | Record<string, string | string[] | undefined>>\n  ): Promise<T>;\n  function parse(\n    raw:\n      | URLSearchParams\n      | Record<string, string | string[] | undefined>\n      | Promise<URLSearchParams | Record<string, string | string[] | undefined>>\n  ): T | Promise<T> {\n    if (raw instanceof Promise) {\n      return raw.then(parseSync);\n    }\n    return parseSync(raw);\n  }\n\n  // ---- serialize ----\n  function serialize(values: Partial<T>): string {\n    const parts: string[] = [];\n\n    for (const prop of Object.keys(codecMap)) {\n      if (!(prop in values)) continue;\n      const codec = codecMap[prop as keyof T] as SearchParamCodec<unknown>;\n      const serialized = codec.serialize(values[prop as keyof T] as unknown);\n\n      // Omit if serialized value matches the default\n      if (serialized === defaultSerialized[prop]) continue;\n      if (serialized === null) continue;\n\n      parts.push(`${encodeURIComponent(getUrlKey(prop))}=${encodeURIComponent(serialized)}`);\n    }\n\n    return parts.join('&');\n  }\n\n  // ---- href ----\n  function href(pathname: string, values: Partial<T>): string {\n    const qs = serialize(values);\n    return qs ? `${pathname}?${qs}` : pathname;\n  }\n\n  // ---- toSearchParams ----\n  function toSearchParams(values: Partial<T>): URLSearchParams {\n    const usp = new URLSearchParams();\n\n    for (const prop of Object.keys(codecMap)) {\n      if (!(prop in values)) continue;\n      const codec = codecMap[prop as keyof T] as SearchParamCodec<unknown>;\n      const serialized = codec.serialize(values[prop as keyof T] as unknown);\n\n      if (serialized === defaultSerialized[prop]) continue;\n      if (serialized === null) continue;\n\n      usp.set(getUrlKey(prop), serialized);\n    }\n\n    return usp;\n  }\n\n  // ---- extend ----\n  function extend<U extends Record<string, SearchParamCodec<unknown> | StandardSchemaV1<unknown>>>(\n    newCodecs: U\n  ): SearchParamsDefinition<T & { [K in keyof U]: InferField<U[K]> }> {\n    type Combined = T & { [K in keyof U]: InferField<U[K]> };\n\n    // Resolve any Standard Schema objects in the extension\n    const resolvedNewCodecs: Record<string, SearchParamCodec<unknown>> = {};\n    const newUrlKeys: Record<string, string> = {};\n    for (const [key, value] of Object.entries(newCodecs)) {\n      const resolved = resolveField(key, value as SearchParamField);\n      resolvedNewCodecs[key] = resolved.codec;\n      if (resolved.urlKey) {\n        newUrlKeys[key] = resolved.urlKey;\n      }\n    }\n\n    const combinedCodecs = {\n      ...codecMap,\n      ...resolvedNewCodecs,\n    } as unknown as CodecMap<Combined>;\n\n    // Merge URL keys: base keys + new codec urlKeys from withUrlKey\n    const combinedUrlKeys: Record<string, string> = { ...urlKeys, ...newUrlKeys };\n\n    return buildDefinition<Combined>(combinedCodecs, combinedUrlKeys);\n  }\n\n  // ---- pick ----\n  function pick<K extends keyof T & string>(...keys: K[]): SearchParamsDefinition<Pick<T, K>> {\n    const pickedCodecs: Record<string, SearchParamCodec<unknown>> = {};\n    const pickedUrlKeys: Record<string, string> = {};\n\n    for (const key of keys) {\n      pickedCodecs[key] = codecMap[key] as SearchParamCodec<unknown>;\n      if (key in urlKeys) {\n        pickedUrlKeys[key] = urlKeys[key];\n      }\n    }\n\n    return buildDefinition<Pick<T, K>>(\n      pickedCodecs as unknown as CodecMap<Pick<T, K>>,\n      pickedUrlKeys\n    );\n  }\n\n  // ---- useQueryStates ----\n  // Delegates to the 'use client' implementation from use-query-states.ts.\n  //\n  // In the RSC environment: use-query-states.ts is transformed by the RSC\n  //   plugin into a client reference proxy. Calling it throws — correct,\n  //   because hooks can't run during server component rendering.\n  // In SSR: use-query-states.ts is the real nuqs-backed function. Hooks\n  //   work during SSR's renderToReadableStream, so this works correctly.\n  // On the client: same as SSR — the real function is available.\n  function useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>] {\n    return clientUseQueryStates(codecMap, options, Object.freeze({ ...urlKeys })) as [\n      T,\n      SetParams<T>,\n    ];\n  }\n\n  // ---- get ----\n  // ALS-backed: reads getSearchParams() from the current request context\n  // and parses through codecs. Server-only, sync.\n  function get(): T {\n    if (typeof window !== 'undefined') {\n      throw new Error(\n        '[timber] searchParams.get() is server-only. ' +\n          'Use searchParams.useQueryStates() on the client.'\n      );\n    }\n    const raw = getSearchParamsFromAls();\n    return parseSync(raw);\n  }\n\n  const definition: SearchParamsDefinition<T> = {\n    parse,\n    get,\n    useQueryStates,\n    extend,\n    pick,\n    serialize,\n    href,\n    toSearchParams,\n    codecs: codecMap,\n    urlKeys: Object.freeze({ ...urlKeys }),\n  };\n\n  return definition;\n}\n"],"mappings":"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"}

package/dist/_chunks/define-zQX6e1tN.js

@@ -0,0 +1,124 @@
+import { a as validateSync, i as isStandardSchema, r as isCodec } from "./schema-bridge-eL5vQDSA.js";
+//#region src/segment-params/define.ts
+var _getSegmentParamsFn;
+var _useSegmentParamsHook;
+/**
+* Register the client useSegmentParams hook.
+* Called by client entry at module load time to avoid require() at call time.
+* @internal
+*/
+function _registerUseSegmentParams(hook) {
+	_useSegmentParamsHook = hook;
+}
+if (typeof window !== "undefined" && !_useSegmentParamsHook) import("./use-segment-params-CskiK-59.js").then((n) => n.r).then((mod) => {
+	if (!_useSegmentParamsHook) _useSegmentParamsHook = mod.useSegmentParams;
+});
+/**
+* Register the getSegmentParams function. Called once at module load time
+* from request-context.ts to avoid dynamic import at call time.
+* @internal
+*/
+function _setGetSegmentParamsFn(fn) {
+	_getSegmentParamsFn = fn;
+}
+function getSegmentParamsFromAls() {
+	if (!_getSegmentParamsFn) throw new Error("[timber] segmentParams.get() is only available on the server. Use segmentParams.useSegmentParams() on the client.");
+	return _getSegmentParamsFn();
+}
+/**
+* Wrap a Standard Schema into a Codec for route params.
+*
+* Unlike fromSchema for search params:
+* - Parse throws on failure (no fallback to default)
+* - Serialize returns string (not null)
+*/
+function fromParamSchema(fieldName, schema) {
+	return {
+		parse(value) {
+			const result = validateSync(schema, Array.isArray(value) ? value : value);
+			if (!result.issues) return result.value;
+			const messages = result.issues.map((i) => i.message).join(", ");
+			throw new Error(`[timber] Param '${fieldName}' coercion failed: ${messages}`);
+		},
+		serialize(value) {
+			if (value === null || value === void 0) return null;
+			if (Array.isArray(value)) return value.join("/");
+			return String(value);
+		}
+	};
+}
+/**
+* Resolve a field value to a Codec. Auto-detects Standard Schema objects.
+*/
+function resolveField(fieldName, value) {
+	if (isCodec(value)) return value;
+	if (isStandardSchema(value)) return fromParamSchema(fieldName, value);
+	throw new Error(`[timber] defineSegmentParams: field '${fieldName}' is not a valid codec or Standard Schema. Expected an object with { parse, serialize } methods, or a Standard Schema object (Zod, Valibot, ArkType).`);
+}
+/**
+* Validate that no codec's serialize returns null.
+* Route params are structural — they must produce a valid path segment.
+*/
+function validateSerialize(codecMap) {
+	for (const [key, codec] of Object.entries(codecMap)) try {
+		const testValue = codec.parse("test");
+		if (codec.serialize(testValue) === 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) {
+		if (e instanceof Error && e.message.includes("returned null")) throw e;
+	}
+}
+/**
+* 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(),
+* })
+* ```
+*/
+function defineSegmentParams(codecs) {
+	const resolvedCodecs = {};
+	for (const [key, value] of Object.entries(codecs)) resolvedCodecs[key] = resolveField(key, value);
+	validateSerialize(resolvedCodecs);
+	function parse(raw) {
+		const result = {};
+		for (const [key, codec] of Object.entries(resolvedCodecs)) {
+			const rawValue = raw[key];
+			if (rawValue === void 0) continue;
+			result[key] = codec.parse(rawValue);
+		}
+		return result;
+	}
+	function serialize(values) {
+		const result = {};
+		for (const [key, codec] of Object.entries(resolvedCodecs)) {
+			const serialized = codec.serialize(values[key]);
+			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;
+	}
+	function get() {
+		if (typeof window !== "undefined") throw new Error("[timber] segmentParams.get() is server-only. Use segmentParams.useSegmentParams() on the client.");
+		return getSegmentParamsFromAls();
+	}
+	function useSegmentParams() {
+		if (!_useSegmentParamsHook) throw new Error("[timber] segmentParams.useSegmentParams() requires @timber-js/app/client to be loaded. This hook can only be used in client components.");
+		return _useSegmentParamsHook();
+	}
+	return {
+		parse,
+		serialize,
+		get,
+		useSegmentParams,
+		codecs: resolvedCodecs
+	};
+}
+//#endregion
+export { _setGetSegmentParamsFn as n, defineSegmentParams as r, _registerUseSegmentParams as t };
+
+//# sourceMappingURL=define-zQX6e1tN.js.map

package/dist/_chunks/define-zQX6e1tN.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-zQX6e1tN.js","names":[],"sources":["../../src/segment-params/define.ts"],"sourcesContent":["/**\n * defineSegmentParams — factory for typed route param coercion.\n *\n * Creates a ParamsDefinition that coerces raw string params from the\n * URL into typed values. Used by exporting from params.ts (segment-level)\n * convention file.\n *\n * Reuses the shared Codec<T> protocol with Standard Schema auto-detection,\n * same pattern as defineSearchParams. Runtime constraints are stricter:\n * - serialize must return string (not null — path segments can't be omitted)\n * - parse throwing → 404 (invalid param value)\n *\n * Design doc: design/07a-route-params-triage.md\n */\n\nimport type { Codec } from '../codec.js';\nimport {\n  type StandardSchemaV1,\n  validateSync,\n  isStandardSchema,\n  isCodec,\n} from '../schema-bridge.js';\n\n// ---------------------------------------------------------------------------\n// Server-only ALS reference for .get()\n// ---------------------------------------------------------------------------\n\n// Same pattern as search-params: eagerly registered at server startup\n// to avoid dynamic imports that lose ALS context. See TIM-523.\nlet _getSegmentParamsFn: (() => Record<string, string | string[]>) | undefined;\nlet _useSegmentParamsHook: (() => Record<string, string | string[]>) | undefined;\n\n/**\n * Register the client useSegmentParams hook.\n * Called by client entry at module load time to avoid require() at call time.\n * @internal\n */\nexport function _registerUseSegmentParams(hook: () => Record<string, string | string[]>): void {\n  _useSegmentParamsHook = hook;\n}\n\n// Self-register on the client when the barrel hasn't been imported yet.\n// Handles the edge case where a client component imports only from params.ts\n// without importing anything from @timber-js/app/client (which runs the\n// registration). The dynamic import resolves before React hydration in Vite.\nif (typeof window !== 'undefined' && !_useSegmentParamsHook) {\n  import('../client/use-segment-params.js').then((mod) => {\n    if (!_useSegmentParamsHook) {\n      _useSegmentParamsHook = mod.useSegmentParams;\n    }\n  });\n}\n\n/**\n * Register the getSegmentParams function. Called once at module load time\n * from request-context.ts to avoid dynamic import at call time.\n * @internal\n */\nexport function _setGetSegmentParamsFn(fn: () => Record<string, string | string[]>): void {\n  _getSegmentParamsFn = fn;\n}\n\nfunction getSegmentParamsFromAls(): Record<string, string | string[]> {\n  if (!_getSegmentParamsFn) {\n    throw new Error(\n      '[timber] segmentParams.get() is only available on the server. ' +\n        'Use segmentParams.useSegmentParams() on the client.'\n    );\n  }\n  return _getSegmentParamsFn();\n}\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** Infer the output type from a Codec or StandardSchemaV1. */\nexport type InferParamField<V> =\n  V extends Codec<infer T> ? T : V extends StandardSchemaV1<infer T> ? T : never;\n\n/** Acceptable field value for defineParams: a Codec or a Standard Schema. */\nexport type ParamField<T = unknown> = Codec<T> | StandardSchemaV1<T>;\n\nexport type { StandardSchemaV1 };\n\n/**\n * A typed route params definition.\n *\n * Returned by defineParams(). Provides parse (string → typed) and\n * serialize (typed → string) for each declared param.\n */\nexport interface ParamsDefinition<T extends Record<string, unknown>> {\n  /** Parse raw string params into typed values. Throws on invalid values. */\n  parse(raw: Record<string, string | string[]>): T;\n\n  /** Serialize typed values back to strings for URL construction. */\n  serialize(values: T): Record<string, string>;\n\n  /**\n   * Get typed segment params from the current request context (ALS).\n   *\n   * Server-only, sync.\n   *\n   * ```ts\n   * // app/products/[id]/params.ts\n   * export const segmentParams = defineSegmentParams({ id: z.coerce.number() })\n   *\n   * // app/products/[id]/page.tsx\n   * import { segmentParams } from './params'\n   * export default function Page() {\n   *   const { id } = segmentParams.get() // id: number\n   * }\n   * ```\n   */\n  get(): T;\n\n  /**\n   * Client hook for accessing typed segment params reactively.\n   *\n   * ```tsx\n   * 'use client'\n   * import { segmentParams } from './params'\n   * export function ProductHeader() {\n   *   const { id } = segmentParams.useSegmentParams()\n   * }\n   * ```\n   */\n  useSegmentParams(): T;\n\n  /** Read-only codec map. */\n  codecs: { [K in keyof T]: Codec<T[K]> };\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap a Standard Schema into a Codec for route params.\n *\n * Unlike fromSchema for search params:\n * - Parse throws on failure (no fallback to default)\n * - Serialize returns string (not null)\n */\nfunction fromParamSchema<T>(fieldName: string, schema: StandardSchemaV1<T>): Codec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      // Route params are always strings (single segment) or string[] (catch-all)\n      const input = Array.isArray(value) ? value : value;\n\n      const result = validateSync(schema, input);\n      if (!result.issues) {\n        return result.value;\n      }\n\n      // For route params, parse failure means the param is invalid → throw\n      const messages = result.issues.map((i) => i.message).join(', ');\n      throw new Error(`[timber] Param '${fieldName}' coercion failed: ${messages}`);\n    },\n\n    serialize(value: T): string | null {\n      if (value === null || value === undefined) {\n        return null;\n      }\n      // Catch-all segments produce arrays — join with '/' for path reconstruction\n      if (Array.isArray(value)) {\n        return value.join('/');\n      }\n      return String(value);\n    },\n  };\n}\n\n/**\n * Resolve a field value to a Codec. Auto-detects Standard Schema objects.\n */\nfunction resolveField(fieldName: string, value: ParamField): Codec<unknown> {\n  if (isCodec(value)) {\n    return value;\n  }\n\n  if (isStandardSchema(value)) {\n    return fromParamSchema(fieldName, value);\n  }\n\n  throw new Error(\n    `[timber] defineSegmentParams: field '${fieldName}' is not a valid codec or Standard Schema. ` +\n      `Expected an object with { parse, serialize } methods, or a Standard Schema object ` +\n      `(Zod, Valibot, ArkType).`\n  );\n}\n\n/**\n * Validate that no codec's serialize returns null.\n * Route params are structural — they must produce a valid path segment.\n */\nfunction validateSerialize(codecMap: Record<string, Codec<unknown>>): void {\n  for (const [key, codec] of Object.entries(codecMap)) {\n    // Test serialize with a sample parsed value to check for null\n    // We can't exhaustively test, but we can check that serialize(parse(\"test\"))\n    // doesn't return null for a basic input.\n    try {\n      const testValue = codec.parse('test');\n      const serialized = codec.serialize(testValue);\n      if (serialized === null) {\n        throw new Error(\n          `[timber] defineSegmentParams: field '${key}' codec.serialize() returned null.\\n` +\n            `  Route params are path segments — they cannot be omitted.\\n` +\n            `  Ensure serialize() always returns a string.`\n        );\n      }\n    } catch (e) {\n      // parse('test') may throw for strict codecs (e.g., number-only).\n      // That's fine — it means the codec validates. We only care about\n      // serialize returning null, which we can't test without a valid value.\n      if (e instanceof Error && e.message.includes('returned null')) {\n        throw e;\n      }\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a ParamsDefinition from a map of codecs and/or Standard Schema objects.\n *\n * ```ts\n * // app/products/[id]/layout.tsx\n * import { defineSegmentParams } from '@timber-js/app/segment-params'\n * import { z } from 'zod/v4'\n *\n * export const segmentParams = defineSegmentParams({\n *   id: z.coerce.number().int().positive(),\n * })\n * ```\n */\nexport function defineSegmentParams<C extends Record<string, ParamField>>(\n  codecs: C\n): ParamsDefinition<{ [K in keyof C]: InferParamField<C[K]> }> {\n  type T = { [K in keyof C]: InferParamField<C[K]> };\n\n  const resolvedCodecs: Record<string, Codec<unknown>> = {};\n\n  for (const [key, value] of Object.entries(codecs)) {\n    resolvedCodecs[key] = resolveField(key, value as ParamField);\n  }\n\n  // Validate that serialize doesn't return null\n  validateSerialize(resolvedCodecs);\n\n  // ---- parse ----\n  function parse(raw: Record<string, string | string[]>): T {\n    const result: Record<string, unknown> = {};\n\n    for (const [key, codec] of Object.entries(resolvedCodecs)) {\n      const rawValue = raw[key];\n      // Skip params not present in the URL at this route depth.\n      // This supports TIM-834 inheritance: a parent params.ts can declare\n      // codecs for descendant segments. At shallower depths those params\n      // don't exist yet — skip them instead of passing undefined to the codec.\n      if (rawValue === undefined) continue;\n      result[key] = codec.parse(rawValue);\n    }\n\n    return result as T;\n  }\n\n  // ---- serialize ----\n  function serialize(values: T): Record<string, string> {\n    const result: Record<string, string> = {};\n\n    for (const [key, codec] of Object.entries(resolvedCodecs)) {\n      const serialized = codec.serialize(values[key as keyof T] as unknown);\n      if (serialized === null) {\n        throw new Error(\n          `[timber] params.serialize: field '${key}' serialized to null. ` +\n            `Route params must produce a valid path segment.`\n        );\n      }\n      result[key] = serialized;\n    }\n\n    return result;\n  }\n\n  // ---- get ----\n  // ALS-backed: reads segment params from the current request context.\n  // Server-only, sync.\n  //\n  // The pipeline already coerces params via coerceSegmentParams() which\n  // calls parse() and stores typed values in ALS via setSegmentParams().\n  // We return those directly instead of re-parsing, because codecs may\n  // not be idempotent (e.g., a codec that only accepts raw strings would\n  // throw if given an already-parsed value). See TIM-574.\n  function get(): T {\n    if (typeof window !== 'undefined') {\n      throw new Error(\n        '[timber] segmentParams.get() is server-only. ' +\n          'Use segmentParams.useSegmentParams() on the client.'\n      );\n    }\n    const params = getSegmentParamsFromAls();\n    // params are already coerced by the pipeline — return as-is.\n    return params as unknown as T;\n  }\n\n  // ---- useSegmentParams ----\n  // Client hook that reads typed params from the navigation context.\n  // Delegates to the existing useSegmentParams hook from use-segment-params.ts.\n  function useSegmentParams(): T {\n    if (!_useSegmentParamsHook) {\n      throw new Error(\n        '[timber] segmentParams.useSegmentParams() requires @timber-js/app/client to be loaded. ' +\n          'This hook can only be used in client components.'\n      );\n    }\n    const raw = _useSegmentParamsHook();\n    // Params are already coerced by the server pipeline before being sent\n    // to the client — return as-is. Re-parsing would break non-idempotent\n    // codecs (e.g., z.coerce.number() on an already-parsed number). See TIM-574.\n    return raw as unknown as T;\n  }\n\n  const definition: ParamsDefinition<T> = {\n    parse,\n    serialize,\n    get,\n    useSegmentParams,\n    codecs: resolvedCodecs as { [K in keyof T]: Codec<T[K]> },\n  };\n\n  return definition;\n}\n"],"mappings":";;AA6BA,IAAI;AACJ,IAAI;;;;;;AAOJ,SAAgB,0BAA0B,MAAqD;AAC7F,yBAAwB;;AAO1B,IAAI,OAAO,WAAW,eAAe,CAAC,sBACpC,QAAO,oCAAA,MAAA,MAAA,EAAA,EAAA,CAAmC,MAAM,QAAQ;AACtD,KAAI,CAAC,sBACH,yBAAwB,IAAI;EAE9B;;;;;;AAQJ,SAAgB,uBAAuB,IAAmD;AACxF,uBAAsB;;AAGxB,SAAS,0BAA6D;AACpE,KAAI,CAAC,oBACH,OAAM,IAAI,MACR,oHAED;AAEH,QAAO,qBAAqB;;;;;;;;;AA2E9B,SAAS,gBAAmB,WAAmB,QAAuC;AACpF,QAAO;EACL,MAAM,OAAyC;GAI7C,MAAM,SAAS,aAAa,QAFd,MAAM,QAAQ,MAAM,GAAG,QAAQ,MAEH;AAC1C,OAAI,CAAC,OAAO,OACV,QAAO,OAAO;GAIhB,MAAM,WAAW,OAAO,OAAO,KAAK,MAAM,EAAE,QAAQ,CAAC,KAAK,KAAK;AAC/D,SAAM,IAAI,MAAM,mBAAmB,UAAU,qBAAqB,WAAW;;EAG/E,UAAU,OAAyB;AACjC,OAAI,UAAU,QAAQ,UAAU,KAAA,EAC9B,QAAO;AAGT,OAAI,MAAM,QAAQ,MAAM,CACtB,QAAO,MAAM,KAAK,IAAI;AAExB,UAAO,OAAO,MAAM;;EAEvB;;;;;AAMH,SAAS,aAAa,WAAmB,OAAmC;AAC1E,KAAI,QAAQ,MAAM,CAChB,QAAO;AAGT,KAAI,iBAAiB,MAAM,CACzB,QAAO,gBAAgB,WAAW,MAAM;AAG1C,OAAM,IAAI,MACR,wCAAwC,UAAU,uJAGnD;;;;;;AAOH,SAAS,kBAAkB,UAAgD;AACzE,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,SAAS,CAIjD,KAAI;EACF,MAAM,YAAY,MAAM,MAAM,OAAO;AAErC,MADmB,MAAM,UAAU,UAAU,KAC1B,KACjB,OAAM,IAAI,MACR,wCAAwC,IAAI,+IAG7C;UAEI,GAAG;AAIV,MAAI,aAAa,SAAS,EAAE,QAAQ,SAAS,gBAAgB,CAC3D,OAAM;;;;;;;;;;;;;;;;AAuBd,SAAgB,oBACd,QAC6D;CAG7D,MAAM,iBAAiD,EAAE;AAEzD,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,OAAO,CAC/C,gBAAe,OAAO,aAAa,KAAK,MAAoB;AAI9D,mBAAkB,eAAe;CAGjC,SAAS,MAAM,KAA2C;EACxD,MAAM,SAAkC,EAAE;AAE1C,OAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,eAAe,EAAE;GACzD,MAAM,WAAW,IAAI;AAKrB,OAAI,aAAa,KAAA,EAAW;AAC5B,UAAO,OAAO,MAAM,MAAM,SAAS;;AAGrC,SAAO;;CAIT,SAAS,UAAU,QAAmC;EACpD,MAAM,SAAiC,EAAE;AAEzC,OAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,eAAe,EAAE;GACzD,MAAM,aAAa,MAAM,UAAU,OAAO,KAA2B;AACrE,OAAI,eAAe,KACjB,OAAM,IAAI,MACR,qCAAqC,IAAI,uEAE1C;AAEH,UAAO,OAAO;;AAGhB,SAAO;;CAYT,SAAS,MAAS;AAChB,MAAI,OAAO,WAAW,YACpB,OAAM,IAAI,MACR,mGAED;AAIH,SAFe,yBAAyB;;CAQ1C,SAAS,mBAAsB;AAC7B,MAAI,CAAC,sBACH,OAAM,IAAI,MACR,0IAED;AAMH,SAJY,uBAAuB;;AAerC,QARwC;EACtC;EACA;EACA;EACA;EACA,QAAQ;EACT"}

package/dist/_chunks/format-CR6v1pWE.js

@@ -0,0 +1,14 @@
+//#region src/utils/format.ts
+/**
+* Shared formatting utilities.
+*/
+/** Format a byte count as a human-readable string (e.g. "1.50 kB"). */
+function formatSize(bytes) {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} kB`;
+	return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
+//#endregion
+export { formatSize as t };
+
+//# sourceMappingURL=format-CR6v1pWE.js.map

package/dist/_chunks/format-CR6v1pWE.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-CR6v1pWE.js","names":[],"sources":["../../src/utils/format.ts"],"sourcesContent":["/**\n * Shared formatting utilities.\n */\n\n/** Format a byte count as a human-readable string (e.g. \"1.50 kB\"). */\nexport function formatSize(bytes: number): string {\n  if (bytes < 1024) return `${bytes} B`;\n  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} kB`;\n  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;\n}\n"],"mappings":";;;;;AAKA,SAAgB,WAAW,OAAuB;AAChD,KAAI,QAAQ,KAAM,QAAO,GAAG,MAAM;AAClC,KAAI,QAAQ,OAAO,KAAM,QAAO,IAAI,QAAQ,MAAM,QAAQ,EAAE,CAAC;AAC7D,QAAO,IAAI,SAAS,OAAO,OAAO,QAAQ,EAAE,CAAC"}

package/dist/_chunks/handler-store-iqnt2ghN.js

@@ -0,0 +1,54 @@
+//#region src/cache/handler-store.ts
+var handler = null;
+/** Replace the active cache handler. Called by the framework at boot. */
+function setCacheHandler(h) {
+	handler = h;
+}
+/**
+* Get the active cache handler. Creates a default MemoryCacheHandler on
+* first access if none has been set via setCacheHandler().
+*/
+function getCacheHandler() {
+	if (!handler) handler = createDefaultHandler();
+	return handler;
+}
+function createDefaultHandler() {
+	const store = /* @__PURE__ */ new Map();
+	const maxEntries = 1e3;
+	return {
+		async get(key) {
+			const entry = store.get(key);
+			if (!entry) return null;
+			store.delete(key);
+			store.set(key, entry);
+			const stale = Date.now() > entry.expiresAt;
+			return {
+				value: entry.value,
+				stale
+			};
+		},
+		async set(key, value, opts) {
+			if (store.has(key)) store.delete(key);
+			while (store.size >= maxEntries) {
+				const oldest = store.keys().next().value;
+				if (oldest !== void 0) store.delete(oldest);
+				else break;
+			}
+			store.set(key, {
+				value,
+				expiresAt: Date.now() + opts.ttl * 1e3,
+				tags: opts.tags
+			});
+		},
+		async invalidate(opts) {
+			if (opts.key) store.delete(opts.key);
+			if (opts.tag) {
+				for (const [key, entry] of store) if (entry.tags.includes(opts.tag)) store.delete(key);
+			}
+		}
+	};
+}
+//#endregion
+export { setCacheHandler as n, getCacheHandler as t };
+
+//# sourceMappingURL=handler-store-iqnt2ghN.js.map

package/dist/_chunks/handler-store-iqnt2ghN.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-store-iqnt2ghN.js","names":[],"sources":["../../src/cache/handler-store.ts"],"sourcesContent":["/**\n * Module-level cache handler singleton.\n *\n * Lazily initialized to MemoryCacheHandler on first access. The framework\n * replaces this at boot from timber.config.ts via setCacheHandler().\n *\n * This module avoids importing from ./index to prevent circular dependencies.\n */\n\n// Inline the interface to avoid circular import with index.ts\ninterface CacheHandlerLike {\n  get(key: string): Promise<{ value: unknown; stale: boolean } | null>;\n  set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void>;\n  invalidate(opts: { key?: string; tag?: string }): Promise<void>;\n}\n\nlet handler: CacheHandlerLike | null = null;\n\n/** Replace the active cache handler. Called by the framework at boot. */\nexport function setCacheHandler(h: CacheHandlerLike): void {\n  handler = h;\n}\n\n/**\n * Get the active cache handler. Creates a default MemoryCacheHandler on\n * first access if none has been set via setCacheHandler().\n */\nexport function getCacheHandler(): CacheHandlerLike {\n  if (!handler) {\n    // Inline a minimal LRU cache to avoid circular dep with index.ts.\n    // In production, the framework always calls setCacheHandler() at boot.\n    handler = createDefaultHandler();\n  }\n  return handler;\n}\n\nfunction createDefaultHandler(): CacheHandlerLike {\n  const store = new Map<string, { value: unknown; expiresAt: number; tags: string[] }>();\n  const maxEntries = 1000;\n\n  return {\n    async get(key) {\n      const entry = store.get(key);\n      if (!entry) return null;\n      store.delete(key);\n      store.set(key, entry);\n      const stale = Date.now() > entry.expiresAt;\n      return { value: entry.value, stale };\n    },\n    async set(key, value, opts) {\n      if (store.has(key)) store.delete(key);\n      while (store.size >= maxEntries) {\n        const oldest = store.keys().next().value;\n        if (oldest !== undefined) store.delete(oldest);\n        else break;\n      }\n      store.set(key, { value, expiresAt: Date.now() + opts.ttl * 1000, tags: opts.tags });\n    },\n    async invalidate(opts) {\n      if (opts.key) store.delete(opts.key);\n      if (opts.tag) {\n        for (const [key, entry] of store) {\n          if (entry.tags.includes(opts.tag)) store.delete(key);\n        }\n      }\n    },\n  };\n}\n"],"mappings":";AAgBA,IAAI,UAAmC;;AAGvC,SAAgB,gBAAgB,GAA2B;AACzD,WAAU;;;;;;AAOZ,SAAgB,kBAAoC;AAClD,KAAI,CAAC,QAGH,WAAU,sBAAsB;AAElC,QAAO;;AAGT,SAAS,uBAAyC;CAChD,MAAM,wBAAQ,IAAI,KAAoE;CACtF,MAAM,aAAa;AAEnB,QAAO;EACL,MAAM,IAAI,KAAK;GACb,MAAM,QAAQ,MAAM,IAAI,IAAI;AAC5B,OAAI,CAAC,MAAO,QAAO;AACnB,SAAM,OAAO,IAAI;AACjB,SAAM,IAAI,KAAK,MAAM;GACrB,MAAM,QAAQ,KAAK,KAAK,GAAG,MAAM;AACjC,UAAO;IAAE,OAAO,MAAM;IAAO;IAAO;;EAEtC,MAAM,IAAI,KAAK,OAAO,MAAM;AAC1B,OAAI,MAAM,IAAI,IAAI,CAAE,OAAM,OAAO,IAAI;AACrC,UAAO,MAAM,QAAQ,YAAY;IAC/B,MAAM,SAAS,MAAM,MAAM,CAAC,MAAM,CAAC;AACnC,QAAI,WAAW,KAAA,EAAW,OAAM,OAAO,OAAO;QACzC;;AAEP,SAAM,IAAI,KAAK;IAAE;IAAO,WAAW,KAAK,KAAK,GAAG,KAAK,MAAM;IAAM,MAAM,KAAK;IAAM,CAAC;;EAErF,MAAM,WAAW,MAAM;AACrB,OAAI,KAAK,IAAK,OAAM,OAAO,KAAK,IAAI;AACpC,OAAI,KAAK;SACF,MAAM,CAAC,KAAK,UAAU,MACzB,KAAI,MAAM,KAAK,SAAS,KAAK,IAAI,CAAE,OAAM,OAAO,IAAI;;;EAI3D"}

package/dist/_chunks/logger-DDmK5skc.js

@@ -0,0 +1,291 @@
+import { s as getTraceStore, v as isDebug, y as isDevMode } from "./tracing-DvKLzCFa.js";
+//#region src/server/error-formatter.ts
+/**
+* Error Formatter — rewrites SSR/RSC error messages to surface user code.
+*
+* When React or Vite throw errors during SSR, stack traces reference
+* vendored dependency paths (e.g. `.vite/deps_ssr/@vitejs_plugin-rsc_vendor_...`)
+* and mangled export names (`__vite_ssr_export_default__`). This module
+* rewrites error messages and stack traces to point at user code instead.
+*
+* Dev-only — in production, errors go through the structured logger
+* without formatting.
+*/
+/**
+* Patterns that identify internal Vite/RSC vendor paths in stack traces.
+* These are replaced with human-readable labels.
+*/
+var VENDOR_PATH_PATTERNS = [
+	{
+		pattern: /node_modules\/\.vite\/deps_ssr\/@vitejs_plugin-rsc_vendor_react-server-dom[^\s)]+/g,
+		replacement: "<react-server-dom>"
+	},
+	{
+		pattern: /node_modules\/\.vite\/deps_ssr\/@vitejs_plugin-rsc_vendor[^\s)]+/g,
+		replacement: "<rsc-vendor>"
+	},
+	{
+		pattern: /node_modules\/\.vite\/deps_ssr\/[^\s)]+/g,
+		replacement: "<vite-dep>"
+	},
+	{
+		pattern: /node_modules\/\.vite\/deps\/[^\s)]+/g,
+		replacement: "<vite-dep>"
+	}
+];
+/**
+* Patterns that identify Vite-mangled export names in error messages.
+*/
+var MANGLED_NAME_PATTERNS = [{
+	pattern: /__vite_ssr_export_default__/g,
+	replacement: "<default export>"
+}, {
+	pattern: /__vite_ssr_export_(\w+)__/g,
+	replacement: "<export $1>"
+}];
+/**
+* Rewrite an error's message and stack to replace internal Vite paths
+* and mangled names with human-readable labels.
+*/
+function formatSsrError(error) {
+	if (!(error instanceof Error)) return String(error);
+	let message = error.message;
+	let stack = error.stack ?? "";
+	for (const { pattern, replacement } of MANGLED_NAME_PATTERNS) message = message.replace(pattern, replacement);
+	for (const { pattern, replacement } of VENDOR_PATH_PATTERNS) stack = stack.replace(pattern, replacement);
+	for (const { pattern, replacement } of MANGLED_NAME_PATTERNS) stack = stack.replace(pattern, replacement);
+	const hint = extractErrorHint(error.message);
+	const parts = [];
+	parts.push(message);
+	if (hint) parts.push(`  → ${hint}`);
+	const userFrames = extractUserFrames(stack);
+	if (userFrames.length > 0) {
+		parts.push("");
+		parts.push("  User code in stack:");
+		for (const frame of userFrames) parts.push(`    ${frame}`);
+	}
+	return parts.join("\n");
+}
+/**
+* Extract a human-readable hint from common React/RSC error messages.
+*
+* React error messages contain useful information but the surrounding
+* context (vendor paths, mangled names) obscures it. This extracts the
+* actionable part as a one-line hint.
+*/
+function extractErrorHint(message) {
+	if (message.match(/Functions cannot be passed directly to Client Components/)) {
+		const propMatch = message.match(/<[^>]*?\s(\w+)=\{function/);
+		if (propMatch) return `Prop "${propMatch[1]}" is a function — mark it "use server" or call it before passing`;
+		return "A function prop was passed to a Client Component — mark it \"use server\" or call it before passing";
+	}
+	if (message.includes("Objects are not valid as a React child")) return "An object was rendered as JSX children — convert to string or extract the value";
+	const nullRefMatch = message.match(/Cannot read propert(?:y|ies) of (undefined|null) \(reading '(\w+)'\)/);
+	if (nullRefMatch) return `Accessed .${nullRefMatch[2]} on ${nullRefMatch[1]} — check that the value exists`;
+	const notFnMatch = message.match(/(\w+) is not a function/);
+	if (notFnMatch) return `"${notFnMatch[1]}" is not a function — check imports and exports`;
+	if (message.includes("Element type is invalid")) return "A component resolved to undefined/null — check default exports and import paths";
+	if (message.includes("Invalid hook call")) return "A hook was called outside of a React component render. If this is a 'use client' component, ensure the directive is at the very top of the file (before any imports) and that @vitejs/plugin-rsc is loaded correctly. Barrel re-exports from non-'use client' files do not propagate the directive.";
+	return null;
+}
+/**
+* Extract stack frames that reference user code (not node_modules,
+* not framework internals).
+*
+* Returns at most 5 frames to keep output concise.
+*/
+function extractUserFrames(stack) {
+	const lines = stack.split("\n");
+	const userFrames = [];
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (!trimmed.startsWith("at ")) continue;
+		if (trimmed.includes("node_modules") || trimmed.includes("<react-server-dom>") || trimmed.includes("<rsc-vendor>") || trimmed.includes("<vite-dep>") || trimmed.includes("node:internal")) continue;
+		userFrames.push(trimmed);
+		if (userFrames.length >= 5) break;
+	}
+	return userFrames;
+}
+//#endregion
+//#region src/server/default-logger.ts
+/**
+* DefaultLogger — human-readable stderr logging when no custom logger is configured.
+*
+* Ships as the fallback so production deployments always have error visibility,
+* even without an `instrumentation.ts` logger export. Output is one line per
+* event, designed for `fly logs`, `kubectl logs`, Cloudflare dashboard tails, etc.
+*
+* Format:
+*   [timber] ERROR  message  key=value key=value  trace_id=4bf92f35
+*   [timber] WARN   message  key=value key=value  trace_id=4bf92f35
+*   [timber] INFO   message  method=GET path=/dashboard status=200 durationMs=43  trace_id=4bf92f35
+*
+* Behavior:
+* - Suppressed entirely in dev mode (dev logging handles all output)
+* - `debug` suppressed unless TIMBER_DEBUG is set
+* - Replaced entirely when a custom logger is set via `setLogger()`
+*
+* See design/17-logging.md §"DefaultLogger"
+*/
+/**
+* Format data fields as `key=value` pairs for human-readable output.
+* - `error` key is serialized via formatSsrError for stack trace cleanup
+* - `trace_id` is truncated to 8 chars for readability (full ID in OTEL)
+* - Other values are stringified inline
+*/
+function formatDataFields(data) {
+	if (!data) return "";
+	const parts = [];
+	let traceId;
+	for (const [key, value] of Object.entries(data)) {
+		if (key === "trace_id") {
+			traceId = typeof value === "string" ? value : String(value);
+			continue;
+		}
+		if (key === "error") {
+			parts.push(`error=${formatSsrError(value)}`);
+			continue;
+		}
+		if (value === void 0 || value === null) continue;
+		parts.push(`${key}=${value}`);
+	}
+	if (traceId) parts.push(`trace_id=${traceId.slice(0, 8)}`);
+	return parts.length > 0 ? "  " + parts.join("  ") : "";
+}
+/** Pad level string to fixed width for alignment. */
+function padLevel(level) {
+	return level.padEnd(5);
+}
+function createDefaultLogger() {
+	return {
+		error(msg, data) {
+			const fields = formatDataFields(data);
+			process.stderr.write(`[timber] ${padLevel("ERROR")}  ${msg}${fields}\n`);
+		},
+		warn(msg, data) {
+			const fields = formatDataFields(data);
+			process.stderr.write(`[timber] ${padLevel("WARN")}  ${msg}${fields}\n`);
+		},
+		info(msg, data) {
+			if (isDevMode()) return;
+			if (!isDebug()) return;
+			const fields = formatDataFields(data);
+			process.stderr.write(`[timber] ${padLevel("INFO")}  ${msg}${fields}\n`);
+		},
+		debug(msg, data) {
+			if (isDevMode()) return;
+			if (!isDebug()) return;
+			const fields = formatDataFields(data);
+			process.stderr.write(`[timber] ${padLevel("DEBUG")}  ${msg}${fields}\n`);
+		}
+	};
+}
+//#endregion
+//#region src/server/logger.ts
+/**
+* Logger — structured logging with environment-aware formatting.
+*
+* timber.js ships a DefaultLogger that writes human-readable lines to stderr
+* in production. Users can export a custom logger from instrumentation.ts to
+* replace it with pino, winston, or any TimberLogger-compatible object.
+*
+* See design/17-logging.md §"Production Logging"
+*/
+var _logger = createDefaultLogger();
+/**
+* Set the user-provided logger. Called by the instrumentation loader
+* when it finds a `logger` export in instrumentation.ts. Replaces
+* the DefaultLogger entirely.
+*/
+function setLogger(logger) {
+	_logger = logger;
+}
+/**
+* Get the current logger. Always non-null — returns DefaultLogger when
+* no custom logger is configured.
+*/
+function getLogger() {
+	return _logger;
+}
+/**
+* Inject trace_id and span_id into log data for log–trace correlation.
+* Always injects trace_id (never undefined). Injects span_id only when OTEL is active.
+*/
+function withTraceContext(data) {
+	const store = getTraceStore();
+	const enriched = { ...data };
+	if (store) {
+		enriched.trace_id = store.traceId;
+		if (store.spanId) enriched.span_id = store.spanId;
+	}
+	return enriched;
+}
+/** Log a completed request. Level: info. */
+function logRequestCompleted(data) {
+	_logger.info("request completed", withTraceContext(data));
+}
+/** Log request received. Level: debug. */
+function logRequestReceived(data) {
+	_logger.debug("request received", withTraceContext(data));
+}
+/** Log a slow request warning. Level: warn. */
+function logSlowRequest(data) {
+	_logger.warn("slow request exceeded threshold", withTraceContext(data));
+}
+/** Log middleware short-circuit. Level: debug. */
+function logMiddlewareShortCircuit(data) {
+	_logger.debug("middleware short-circuited", withTraceContext(data));
+}
+/** Log unhandled error in middleware phase. Level: error. */
+function logMiddlewareError(data) {
+	_logger.error("unhandled error in middleware phase", withTraceContext(data));
+}
+/** Log unhandled render-phase error. Level: error. */
+function logRenderError(data) {
+	_logger.error("unhandled render-phase error", withTraceContext(data));
+}
+/** Log proxy.ts uncaught error. Level: error. */
+function logProxyError(data) {
+	_logger.error("proxy.ts threw uncaught error", withTraceContext(data));
+}
+/** Log unhandled error in route handler. Level: error. */
+function logRouteError(data) {
+	_logger.error("unhandled route handler error", withTraceContext(data));
+}
+/** Log waitUntil() adapter missing (once at startup). Level: warn. */
+function logWaitUntilUnsupported() {
+	_logger.warn("adapter does not support waitUntil()");
+}
+/** Log waitUntil() promise rejection. Level: warn. */
+function logWaitUntilRejected(data) {
+	_logger.warn("waitUntil() promise rejected", withTraceContext(data));
+}
+/** Log staleWhileRevalidate refetch failure. Level: warn. */
+function logSwrRefetchFailed(data) {
+	_logger.warn("staleWhileRevalidate refetch failed", withTraceContext(data));
+}
+/** Log cache miss. Level: debug. */
+function logCacheMiss(data) {
+	_logger.debug("timber.cache MISS", withTraceContext(data));
+}
+/**
+* Log an intentionally swallowed error. Provides observability into catch
+* blocks that are deliberately empty — the error is consumed, never rethrown.
+*
+* Default level: `warn` in dev (so the overlay surfaces patterns), `debug`
+* in production (low noise unless TIMBER_DEBUG is set). Pass `opts.level`
+* to override.
+*
+* **Infallible** — swallow() itself never throws, even if the logger is
+* broken. A thrown swallow would turn a benign catch into a crash.
+*/
+function swallow(err, reason, opts) {
+	try {
+		const level = opts?.level ?? (isDevMode() ? "warn" : "debug");
+		_logger[level](`swallowed: ${reason}`, withTraceContext({ error: err }));
+	} catch {}
+}
+//#endregion
+export { logProxyError as a, logRequestReceived as c, logSwrRefetchFailed as d, logWaitUntilRejected as f, swallow as h, logMiddlewareShortCircuit as i, logRouteError as l, setLogger as m, logCacheMiss as n, logRenderError as o, logWaitUntilUnsupported as p, logMiddlewareError as r, logRequestCompleted as s, getLogger as t, logSlowRequest as u };
+
+//# sourceMappingURL=logger-DDmK5skc.js.map

package/dist/_chunks/logger-DDmK5skc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger-DDmK5skc.js","names":[],"sources":["../../src/server/error-formatter.ts","../../src/server/default-logger.ts","../../src/server/logger.ts"],"sourcesContent":["/**\n * Error Formatter — rewrites SSR/RSC error messages to surface user code.\n *\n * When React or Vite throw errors during SSR, stack traces reference\n * vendored dependency paths (e.g. `.vite/deps_ssr/@vitejs_plugin-rsc_vendor_...`)\n * and mangled export names (`__vite_ssr_export_default__`). This module\n * rewrites error messages and stack traces to point at user code instead.\n *\n * Dev-only — in production, errors go through the structured logger\n * without formatting.\n */\n\n// ─── Stack Trace Rewriting ──────────────────────────────────────────────────\n\n/**\n * Patterns that identify internal Vite/RSC vendor paths in stack traces.\n * These are replaced with human-readable labels.\n */\nconst VENDOR_PATH_PATTERNS: Array<{ pattern: RegExp; replacement: string }> = [\n  {\n    pattern: /node_modules\\/\\.vite\\/deps_ssr\\/@vitejs_plugin-rsc_vendor_react-server-dom[^\\s)]+/g,\n    replacement: '<react-server-dom>',\n  },\n  {\n    pattern: /node_modules\\/\\.vite\\/deps_ssr\\/@vitejs_plugin-rsc_vendor[^\\s)]+/g,\n    replacement: '<rsc-vendor>',\n  },\n  {\n    pattern: /node_modules\\/\\.vite\\/deps_ssr\\/[^\\s)]+/g,\n    replacement: '<vite-dep>',\n  },\n  {\n    pattern: /node_modules\\/\\.vite\\/deps\\/[^\\s)]+/g,\n    replacement: '<vite-dep>',\n  },\n];\n\n/**\n * Patterns that identify Vite-mangled export names in error messages.\n */\nconst MANGLED_NAME_PATTERNS: Array<{ pattern: RegExp; replacement: string }> = [\n  {\n    pattern: /__vite_ssr_export_default__/g,\n    replacement: '<default export>',\n  },\n  {\n    pattern: /__vite_ssr_export_(\\w+)__/g,\n    replacement: '<export $1>',\n  },\n];\n\n/**\n * Rewrite an error's message and stack to replace internal Vite paths\n * and mangled names with human-readable labels.\n */\nexport function formatSsrError(error: unknown): string {\n  if (!(error instanceof Error)) {\n    return String(error);\n  }\n\n  let message = error.message;\n  let stack = error.stack ?? '';\n\n  // Rewrite mangled names in the message\n  for (const { pattern, replacement } of MANGLED_NAME_PATTERNS) {\n    message = message.replace(pattern, replacement);\n  }\n\n  // Rewrite vendor paths in the stack\n  for (const { pattern, replacement } of VENDOR_PATH_PATTERNS) {\n    stack = stack.replace(pattern, replacement);\n  }\n\n  // Rewrite mangled names in the stack too\n  for (const { pattern, replacement } of MANGLED_NAME_PATTERNS) {\n    stack = stack.replace(pattern, replacement);\n  }\n\n  // Extract hints from React-specific error patterns\n  const hint = extractErrorHint(error.message);\n\n  // Build formatted output: cleaned message, hint (if any), then cleaned stack\n  const parts: string[] = [];\n  parts.push(message);\n  if (hint) {\n    parts.push(`  → ${hint}`);\n  }\n\n  // Include only the user-code frames from the stack (skip the first line\n  // which is the message itself, and filter out vendor-only frames)\n  const userFrames = extractUserFrames(stack);\n  if (userFrames.length > 0) {\n    parts.push('');\n    parts.push('  User code in stack:');\n    for (const frame of userFrames) {\n      parts.push(`    ${frame}`);\n    }\n  }\n\n  return parts.join('\\n');\n}\n\n// ─── Error Hint Extraction ──────────────────────────────────────────────────\n\n/**\n * Extract a human-readable hint from common React/RSC error messages.\n *\n * React error messages contain useful information but the surrounding\n * context (vendor paths, mangled names) obscures it. This extracts the\n * actionable part as a one-line hint.\n */\nfunction extractErrorHint(message: string): string | null {\n  // \"Functions cannot be passed directly to Client Components\"\n  // Extract the component and prop name from the JSX-like syntax in the message\n  const fnPassedMatch = message.match(/Functions cannot be passed directly to Client Components/);\n  if (fnPassedMatch) {\n    // Try to extract the prop name from the message\n    // React formats: <... propName={function ...} ...>\n    const propMatch = message.match(/<[^>]*?\\s(\\w+)=\\{function/);\n    if (propMatch) {\n      return `Prop \"${propMatch[1]}\" is a function — mark it \"use server\" or call it before passing`;\n    }\n    return 'A function prop was passed to a Client Component — mark it \"use server\" or call it before passing';\n  }\n\n  // \"Objects are not valid as a React child\"\n  if (message.includes('Objects are not valid as a React child')) {\n    return 'An object was rendered as JSX children — convert to string or extract the value';\n  }\n\n  // \"Cannot read properties of undefined/null\"\n  const nullRefMatch = message.match(\n    /Cannot read propert(?:y|ies) of (undefined|null) \\(reading '(\\w+)'\\)/\n  );\n  if (nullRefMatch) {\n    return `Accessed .${nullRefMatch[2]} on ${nullRefMatch[1]} — check that the value exists`;\n  }\n\n  // \"X is not a function\"\n  const notFnMatch = message.match(/(\\w+) is not a function/);\n  if (notFnMatch) {\n    return `\"${notFnMatch[1]}\" is not a function — check imports and exports`;\n  }\n\n  // \"Element type is invalid\"\n  if (message.includes('Element type is invalid')) {\n    return 'A component resolved to undefined/null — check default exports and import paths';\n  }\n\n  // \"Invalid hook call\" — hooks called outside React's render context.\n  // In RSC, this typically means a 'use client' component was executed as a\n  // server component instead of being serialized as a client reference.\n  if (message.includes('Invalid hook call')) {\n    return (\n      'A hook was called outside of a React component render. ' +\n      \"If this is a 'use client' component, ensure the directive is at the very top of the file \" +\n      '(before any imports) and that @vitejs/plugin-rsc is loaded correctly. ' +\n      \"Barrel re-exports from non-'use client' files do not propagate the directive.\"\n    );\n  }\n\n  return null;\n}\n\n// ─── Stack Frame Filtering ──────────────────────────────────────────────────\n\n/**\n * Extract stack frames that reference user code (not node_modules,\n * not framework internals).\n *\n * Returns at most 5 frames to keep output concise.\n */\nfunction extractUserFrames(stack: string): string[] {\n  const lines = stack.split('\\n');\n  const userFrames: string[] = [];\n\n  for (const line of lines) {\n    const trimmed = line.trim();\n    // Skip non-frame lines\n    if (!trimmed.startsWith('at ')) continue;\n    // Skip node_modules, vendor, and internal frames\n    if (\n      trimmed.includes('node_modules') ||\n      trimmed.includes('<react-server-dom>') ||\n      trimmed.includes('<rsc-vendor>') ||\n      trimmed.includes('<vite-dep>') ||\n      trimmed.includes('node:internal')\n    ) {\n      continue;\n    }\n    userFrames.push(trimmed);\n    if (userFrames.length >= 5) break;\n  }\n\n  return userFrames;\n}\n","/**\n * DefaultLogger — human-readable stderr logging when no custom logger is configured.\n *\n * Ships as the fallback so production deployments always have error visibility,\n * even without an `instrumentation.ts` logger export. Output is one line per\n * event, designed for `fly logs`, `kubectl logs`, Cloudflare dashboard tails, etc.\n *\n * Format:\n *   [timber] ERROR  message  key=value key=value  trace_id=4bf92f35\n *   [timber] WARN   message  key=value key=value  trace_id=4bf92f35\n *   [timber] INFO   message  method=GET path=/dashboard status=200 durationMs=43  trace_id=4bf92f35\n *\n * Behavior:\n * - Suppressed entirely in dev mode (dev logging handles all output)\n * - `debug` suppressed unless TIMBER_DEBUG is set\n * - Replaced entirely when a custom logger is set via `setLogger()`\n *\n * See design/17-logging.md §\"DefaultLogger\"\n */\n\nimport { isDevMode, isDebug } from './debug.js';\nimport { formatSsrError } from './error-formatter.js';\nimport type { TimberLogger } from './logger.js';\n\n/**\n * Format data fields as `key=value` pairs for human-readable output.\n * - `error` key is serialized via formatSsrError for stack trace cleanup\n * - `trace_id` is truncated to 8 chars for readability (full ID in OTEL)\n * - Other values are stringified inline\n */\nfunction formatDataFields(data?: Record<string, unknown>): string {\n  if (!data) return '';\n\n  const parts: string[] = [];\n  let traceId: string | undefined;\n\n  for (const [key, value] of Object.entries(data)) {\n    if (key === 'trace_id') {\n      // Defer trace_id to the end\n      traceId = typeof value === 'string' ? value : String(value);\n      continue;\n    }\n    if (key === 'error') {\n      // Serialize errors with formatSsrError for clean output\n      parts.push(`error=${formatSsrError(value)}`);\n      continue;\n    }\n    if (value === undefined || value === null) continue;\n    parts.push(`${key}=${value}`);\n  }\n\n  // trace_id always last, truncated to 8 chars for readability\n  if (traceId) {\n    parts.push(`trace_id=${traceId.slice(0, 8)}`);\n  }\n\n  return parts.length > 0 ? '  ' + parts.join('  ') : '';\n}\n\n/** Pad level string to fixed width for alignment. */\nfunction padLevel(level: string): string {\n  return level.padEnd(5);\n}\n\nexport function createDefaultLogger(): TimberLogger {\n  return {\n    error(msg: string, data?: Record<string, unknown>): void {\n      // Errors are ALWAYS logged, including dev mode. Suppressing errors\n      // in dev causes silent 500s with no stack trace, making route.ts\n      // and render errors impossible to debug. See TIM-555.\n      const fields = formatDataFields(data);\n      process.stderr.write(`[timber] ${padLevel('ERROR')}  ${msg}${fields}\\n`);\n    },\n\n    warn(msg: string, data?: Record<string, unknown>): void {\n      // Warnings are always logged — same rationale as errors.\n      const fields = formatDataFields(data);\n      process.stderr.write(`[timber] ${padLevel('WARN')}  ${msg}${fields}\\n`);\n    },\n\n    info(msg: string, data?: Record<string, unknown>): void {\n      // info is suppressed by default — per-request lines are too noisy\n      // without a custom logger. Enable with TIMBER_DEBUG.\n      if (isDevMode()) return;\n      if (!isDebug()) return;\n      const fields = formatDataFields(data);\n      process.stderr.write(`[timber] ${padLevel('INFO')}  ${msg}${fields}\\n`);\n    },\n\n    debug(msg: string, data?: Record<string, unknown>): void {\n      // debug is suppressed in dev (dev logger handles it) and in\n      // production unless TIMBER_DEBUG is explicitly set.\n      if (isDevMode()) return;\n      if (!isDebug()) return;\n      const fields = formatDataFields(data);\n      process.stderr.write(`[timber] ${padLevel('DEBUG')}  ${msg}${fields}\\n`);\n    },\n  };\n}\n","/**\n * Logger — structured logging with environment-aware formatting.\n *\n * timber.js ships a DefaultLogger that writes human-readable lines to stderr\n * in production. Users can export a custom logger from instrumentation.ts to\n * replace it with pino, winston, or any TimberLogger-compatible object.\n *\n * See design/17-logging.md §\"Production Logging\"\n */\n\nimport { getTraceStore } from './tracing.js';\nimport { createDefaultLogger } from './default-logger.js';\nimport { isDevMode } from './debug.js';\n\n// ─── Logger Interface ─────────────────────────────────────────────────────\n\n/** Any object with standard log methods satisfies this — pino, winston, consola, console. */\nexport interface TimberLogger {\n  info(msg: string, data?: Record<string, unknown>): void;\n  warn(msg: string, data?: Record<string, unknown>): void;\n  error(msg: string, data?: Record<string, unknown>): void;\n  debug(msg: string, data?: Record<string, unknown>): void;\n}\n\n// ─── Logger Registry ──────────────────────────────────────────────────────\n\n// Initialize with DefaultLogger so production errors are never silent.\n// Replaced when setLogger() is called from instrumentation.ts.\nlet _logger: TimberLogger = createDefaultLogger();\n\n/**\n * Set the user-provided logger. Called by the instrumentation loader\n * when it finds a `logger` export in instrumentation.ts. Replaces\n * the DefaultLogger entirely.\n */\nexport function setLogger(logger: TimberLogger): void {\n  _logger = logger;\n}\n\n/**\n * Get the current logger. Always non-null — returns DefaultLogger when\n * no custom logger is configured.\n */\nexport function getLogger(): TimberLogger {\n  return _logger;\n}\n\n// ─── Framework Log Helpers ────────────────────────────────────────────────\n\n/**\n * Inject trace_id and span_id into log data for log–trace correlation.\n * Always injects trace_id (never undefined). Injects span_id only when OTEL is active.\n */\nfunction withTraceContext(data?: Record<string, unknown>): Record<string, unknown> {\n  const store = getTraceStore();\n  const enriched: Record<string, unknown> = { ...data };\n  if (store) {\n    enriched.trace_id = store.traceId;\n    if (store.spanId) {\n      enriched.span_id = store.spanId;\n    }\n  }\n  return enriched;\n}\n\n// ─── Framework Event Emitters ─────────────────────────────────────────────\n\n/** Log a completed request. Level: info. */\nexport function logRequestCompleted(data: {\n  method: string;\n  path: string;\n  status: number;\n  durationMs: number;\n  /** Number of concurrent in-flight requests (including this one) at completion time. */\n  concurrency?: number;\n}): void {\n  _logger.info('request completed', withTraceContext(data));\n}\n\n/** Log request received. Level: debug. */\nexport function logRequestReceived(data: { method: string; path: string }): void {\n  _logger.debug('request received', withTraceContext(data));\n}\n\n/** Log a slow request warning. Level: warn. */\nexport function logSlowRequest(data: {\n  method: string;\n  path: string;\n  durationMs: number;\n  threshold: number;\n  /** Number of concurrent in-flight requests at the time the slow request completed. */\n  concurrency?: number;\n}): void {\n  _logger.warn('slow request exceeded threshold', withTraceContext(data));\n}\n\n/** Log middleware short-circuit. Level: debug. */\nexport function logMiddlewareShortCircuit(data: {\n  method: string;\n  path: string;\n  status: number;\n}): void {\n  _logger.debug('middleware short-circuited', withTraceContext(data));\n}\n\n/** Log unhandled error in middleware phase. Level: error. */\nexport function logMiddlewareError(data: { method: string; path: string; error: unknown }): void {\n  _logger.error('unhandled error in middleware phase', withTraceContext(data));\n}\n\n/** Log unhandled render-phase error. Level: error. */\nexport function logRenderError(data: {\n  method: string;\n  path: string;\n  error: unknown;\n  errorId?: string;\n}): void {\n  _logger.error('unhandled render-phase error', withTraceContext(data));\n}\n\n/** Log proxy.ts uncaught error. Level: error. */\nexport function logProxyError(data: { error: unknown }): void {\n  _logger.error('proxy.ts threw uncaught error', withTraceContext(data));\n}\n\n/** Log unhandled error in server action. Level: error. */\nexport function logActionError(data: { method: string; path: string; error: unknown }): void {\n  _logger.error('unhandled server action error', withTraceContext(data));\n}\n\n/** Log unhandled error in route handler. Level: error. */\nexport function logRouteError(data: { method: string; path: string; error: unknown }): void {\n  _logger.error('unhandled route handler error', withTraceContext(data));\n}\n\n/** Log SSR streaming error (post-shell). Level: error. */\nexport function logStreamingError(data: { error: unknown }): void {\n  _logger.error('SSR streaming error (post-shell)', withTraceContext(data));\n}\n\n/** Log waitUntil() adapter missing (once at startup). Level: warn. */\nexport function logWaitUntilUnsupported(): void {\n  _logger.warn('adapter does not support waitUntil()');\n}\n\n/** Log waitUntil() promise rejection. Level: warn. */\nexport function logWaitUntilRejected(data: { error: unknown }): void {\n  _logger.warn('waitUntil() promise rejected', withTraceContext(data));\n}\n\n/** Log staleWhileRevalidate refetch failure. Level: warn. */\nexport function logSwrRefetchFailed(data: { cacheKey: string; error: unknown }): void {\n  _logger.warn('staleWhileRevalidate refetch failed', withTraceContext(data));\n}\n\n/** Log cache miss. Level: debug. */\nexport function logCacheMiss(data: { cacheKey: string }): void {\n  _logger.debug('timber.cache MISS', withTraceContext(data));\n}\n\n// ─── Swallow Helper ───────────────────────────────────────────────────────\n\n/**\n * Log an intentionally swallowed error. Provides observability into catch\n * blocks that are deliberately empty — the error is consumed, never rethrown.\n *\n * Default level: `warn` in dev (so the overlay surfaces patterns), `debug`\n * in production (low noise unless TIMBER_DEBUG is set). Pass `opts.level`\n * to override.\n *\n * **Infallible** — swallow() itself never throws, even if the logger is\n * broken. A thrown swallow would turn a benign catch into a crash.\n */\nexport function swallow(err: unknown, reason: string, opts?: { level?: 'debug' | 'warn' }): void {\n  try {\n    const level = opts?.level ?? (isDevMode() ? 'warn' : 'debug');\n    _logger[level](`swallowed: ${reason}`, withTraceContext({ error: err }));\n  } catch {\n    // swallow() must never throw.\n  }\n}\n"],"mappings":"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"}