@timber-js/app 0.2.0-alpha.60 → 0.2.0-alpha.62

package/dist/_chunks/{use-query-states-wEXY2JQB.js.map → use-query-states-DAhgj8Gx.js.map}

@@ -1 +1 @@
-{"version":3,"file":"use-query-states-wEXY2JQB.js","names":[],"sources":["../../src/search-params/registry.ts","../../src/client/use-query-states.ts"],"sourcesContent":["/**\n * Runtime registry for route-scoped search params definitions.\n *\n * When a route's modules load, the framework registers its search-params\n * definition here. useQueryStates('/route') resolves codecs from this map.\n *\n * Design doc: design/23-search-params.md §\"Runtime: Registration at Route Load\"\n */\n\nimport type { SearchParamsDefinition } from './define.js';\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nconst registry = new Map<string, SearchParamsDefinition<any>>();\n\n/**\n * Register a route's search params definition.\n * Called by the generated route manifest loader when a route's modules load.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function registerSearchParams(route: string, definition: SearchParamsDefinition<any>): void {\n  registry.set(route, definition);\n}\n\n/**\n * Look up a route's search params definition.\n * Returns undefined if the route hasn't been loaded yet.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function getSearchParams(route: string): SearchParamsDefinition<any> | undefined {\n  return registry.get(route);\n}\n","/**\n * useQueryStates — client-side hook for URL-synced search params.\n *\n * Delegates to nuqs for URL synchronization, batching, React 19 transitions,\n * and throttled URL writes. Bridges timber's SearchParamCodec protocol to\n * nuqs-compatible parsers.\n *\n * Design doc: design/23-search-params.md §\"Codec Bridge\"\n */\n\n'use client';\n\nimport { useQueryStates as nuqsUseQueryStates } from 'nuqs';\nimport type { SingleParser } from 'nuqs';\nimport type {\n  SearchParamCodec,\n  SearchParamsDefinition,\n  SetParams,\n  QueryStatesOptions,\n} from '../search-params/define.js';\nimport { getSearchParams } from '../search-params/registry.js';\n\n// ─── Codec Bridge ─────────────────────────────────────────────────\n\n/**\n * Bridge a timber SearchParamCodec to a nuqs-compatible SingleParser.\n *\n * nuqs parsers: { parse(string) → T|null, serialize?(T) → string, eq?, defaultValue? }\n * timber codecs: { parse(string|string[]|undefined) → T, serialize(T) → string|null }\n */\nfunction bridgeCodec<T>(codec: SearchParamCodec<T>): SingleParser<T> & { defaultValue: T } {\n  return {\n    parse: (v: string) => codec.parse(v),\n    serialize: (v: T) => codec.serialize(v) ?? '',\n    defaultValue: codec.parse(undefined) as T,\n    eq: (a: T, b: T) => codec.serialize(a) === codec.serialize(b),\n  };\n}\n\n/**\n * Bridge an entire codec map to nuqs-compatible parsers.\n */\nfunction bridgeCodecs<T extends Record<string, unknown>>(codecs: {\n  [K in keyof T]: SearchParamCodec<T[K]>;\n}) {\n  const result: Record<string, SingleParser<unknown> & { defaultValue: unknown }> = {};\n  for (const key of Object.keys(codecs)) {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    result[key] = bridgeCodec(codecs[key as keyof T]) as any;\n  }\n  return result as { [K in keyof T]: SingleParser<T[K]> & { defaultValue: T[K] } };\n}\n\n// ─── Hook ─────────────────────────────────────────────────────────\n\n/**\n * Read and write typed search params from/to the URL.\n *\n * Delegates to nuqs internally. The timber nuqs adapter (auto-injected in\n * browser-entry.ts) handles RSC navigation on non-shallow updates.\n *\n * Usage:\n * ```ts\n * // Via a SearchParamsDefinition\n * const [params, setParams] = definition.useQueryStates()\n *\n * // Standalone with inline codecs\n * const [params, setParams] = useQueryStates({\n *   page: fromSchema(z.coerce.number().int().min(1).default(1)),\n * })\n * ```\n */\nexport function useQueryStates<T extends Record<string, unknown>>(\n  codecsOrRoute: { [K in keyof T]: SearchParamCodec<T[K]> } | string,\n  _options?: QueryStatesOptions,\n  urlKeys?: Readonly<Record<string, string>>\n): [T, SetParams<T>] {\n  // Route-string overload: resolve codecs from the registry\n  let codecs: { [K in keyof T]: SearchParamCodec<T[K]> };\n  let resolvedUrlKeys = urlKeys;\n  if (typeof codecsOrRoute === 'string') {\n    const definition = getSearchParams(codecsOrRoute);\n    if (!definition) {\n      throw new Error(\n        `useQueryStates('${codecsOrRoute}'): no search params registered for this route. ` +\n          `Either the route has no search-params.ts file, or it hasn't been loaded yet. ` +\n          `For cross-route usage, import the definition explicitly.`\n      );\n    }\n    codecs = definition.codecs as { [K in keyof T]: SearchParamCodec<T[K]> };\n    resolvedUrlKeys = definition.urlKeys;\n  } else {\n    codecs = codecsOrRoute;\n  }\n\n  const bridged = bridgeCodecs(codecs);\n\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const nuqsOptions: any = {};\n  if (resolvedUrlKeys && Object.keys(resolvedUrlKeys).length > 0) {\n    nuqsOptions.urlKeys = resolvedUrlKeys;\n  }\n\n  let values: Record<string, unknown>;\n  let setValues: Function;\n  try {\n    [values, setValues] = nuqsUseQueryStates(bridged, nuqsOptions);\n  } catch (err) {\n    if (\n      err instanceof Error &&\n      /Invalid hook call|cannot be called|Cannot read properties of null/i.test(err.message)\n    ) {\n      throw new Error(\n        'useQueryStates is a client component hook and cannot be called outside a React component. ' +\n          'Use definition.parse(searchParams) in server components instead.'\n      );\n    }\n    throw err;\n  }\n\n  // Wrap the nuqs setter to match timber's SetParams<T> signature.\n  // nuqs's setter accepts Partial<Nullable<Values>> | UpdaterFn | null.\n  // timber's setter accepts Partial<T> with optional SetParamsOptions.\n  const setParams: SetParams<T> = (partial, setOptions?) => {\n    const nuqsSetOptions: Record<string, unknown> = {};\n    if (setOptions?.shallow !== undefined) nuqsSetOptions.shallow = setOptions.shallow;\n    if (setOptions?.scroll !== undefined) nuqsSetOptions.scroll = setOptions.scroll;\n    if (setOptions?.history !== undefined) nuqsSetOptions.history = setOptions.history;\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    void setValues(partial as any, nuqsSetOptions);\n  };\n\n  return [values as T, setParams];\n}\n\n// ─── Definition binding ───────────────────────────────────────────\n\n/**\n * Create a useQueryStates binding for a SearchParamsDefinition.\n * This is used internally by SearchParamsDefinition.useQueryStates().\n */\nexport function bindUseQueryStates<T extends Record<string, unknown>>(\n  definition: SearchParamsDefinition<T>\n): (options?: QueryStatesOptions) => [T, SetParams<T>] {\n  return (options?: QueryStatesOptions) => {\n    return useQueryStates<T>(definition.codecs, options, definition.urlKeys);\n  };\n}\n"],"mappings":";;AAYA,IAAM,2BAAW,IAAI,KAA0C;;;;;AAO/D,SAAgB,qBAAqB,OAAe,YAA+C;AACjG,UAAS,IAAI,OAAO,WAAW;;;;;;AAQjC,SAAgB,gBAAgB,OAAwD;AACtF,QAAO,SAAS,IAAI,MAAM;;;;;;;;;;;;;;;;;;;ACC5B,SAAS,YAAe,OAAmE;AACzF,QAAO;EACL,QAAQ,MAAc,MAAM,MAAM,EAAE;EACpC,YAAY,MAAS,MAAM,UAAU,EAAE,IAAI;EAC3C,cAAc,MAAM,MAAM,KAAA,EAAU;EACpC,KAAK,GAAM,MAAS,MAAM,UAAU,EAAE,KAAK,MAAM,UAAU,EAAE;EAC9D;;;;;AAMH,SAAS,aAAgD,QAEtD;CACD,MAAM,SAA4E,EAAE;AACpF,MAAK,MAAM,OAAO,OAAO,KAAK,OAAO,CAEnC,QAAO,OAAO,YAAY,OAAO,KAAgB;AAEnD,QAAO;;;;;;;;;;;;;;;;;;;AAsBT,SAAgB,iBACd,eACA,UACA,SACmB;CAEnB,IAAI;CACJ,IAAI,kBAAkB;AACtB,KAAI,OAAO,kBAAkB,UAAU;EACrC,MAAM,aAAa,gBAAgB,cAAc;AACjD,MAAI,CAAC,WACH,OAAM,IAAI,MACR,mBAAmB,cAAc,uLAGlC;AAEH,WAAS,WAAW;AACpB,oBAAkB,WAAW;OAE7B,UAAS;CAGX,MAAM,UAAU,aAAa,OAAO;CAGpC,MAAM,cAAmB,EAAE;AAC3B,KAAI,mBAAmB,OAAO,KAAK,gBAAgB,CAAC,SAAS,EAC3D,aAAY,UAAU;CAGxB,IAAI;CACJ,IAAI;AACJ,KAAI;AACF,GAAC,QAAQ,aAAa,eAAmB,SAAS,YAAY;UACvD,KAAK;AACZ,MACE,eAAe,SACf,qEAAqE,KAAK,IAAI,QAAQ,CAEtF,OAAM,IAAI,MACR,6JAED;AAEH,QAAM;;CAMR,MAAM,aAA2B,SAAS,eAAgB;EACxD,MAAM,iBAA0C,EAAE;AAClD,MAAI,YAAY,YAAY,KAAA,EAAW,gBAAe,UAAU,WAAW;AAC3E,MAAI,YAAY,WAAW,KAAA,EAAW,gBAAe,SAAS,WAAW;AACzE,MAAI,YAAY,YAAY,KAAA,EAAW,gBAAe,UAAU,WAAW;AAEtE,YAAU,SAAgB,eAAe;;AAGhD,QAAO,CAAC,QAAa,UAAU;;;;;;AASjC,SAAgB,mBACd,YACqD;AACrD,SAAQ,YAAiC;AACvC,SAAO,iBAAkB,WAAW,QAAQ,SAAS,WAAW,QAAQ"}
+{"version":3,"file":"use-query-states-DAhgj8Gx.js","names":[],"sources":["../../src/search-params/registry.ts","../../src/client/use-query-states.ts"],"sourcesContent":["/**\n * Runtime registry for route-scoped search params definitions.\n *\n * When a route's modules load, the framework registers its search-params\n * definition here. useQueryStates('/route') resolves codecs from this map.\n *\n * Design doc: design/23-search-params.md §\"Runtime: Registration at Route Load\"\n */\n\nimport type { SearchParamsDefinition } from './define.js';\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nconst registry = new Map<string, SearchParamsDefinition<any>>();\n\n/**\n * Register a route's search params definition.\n * Called by the generated route manifest loader when a route's modules load.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function registerSearchParams(route: string, definition: SearchParamsDefinition<any>): void {\n  registry.set(route, definition);\n}\n\n/**\n * Look up a route's search params definition.\n * Returns undefined if the route hasn't been loaded yet.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function getSearchParams(route: string): SearchParamsDefinition<any> | undefined {\n  return registry.get(route);\n}\n","/**\n * useQueryStates — client-side hook for URL-synced search params.\n *\n * Delegates to nuqs for URL synchronization, batching, React 19 transitions,\n * and throttled URL writes. Bridges timber's SearchParamCodec protocol to\n * nuqs-compatible parsers.\n *\n * Design doc: design/23-search-params.md §\"Codec Bridge\"\n */\n\n'use client';\n\nimport { useQueryStates as nuqsUseQueryStates } from 'nuqs';\nimport type { SingleParser } from 'nuqs';\nimport type {\n  SearchParamCodec,\n  SearchParamsDefinition,\n  SetParams,\n  QueryStatesOptions,\n} from '../search-params/define.js';\nimport { getSearchParams } from '../search-params/registry.js';\n\n// ─── Codec Bridge ─────────────────────────────────────────────────\n\n/**\n * Bridge a timber SearchParamCodec to a nuqs-compatible SingleParser.\n *\n * nuqs parsers: { parse(string) → T|null, serialize?(T) → string, eq?, defaultValue? }\n * timber codecs: { parse(string|string[]|undefined) → T, serialize(T) → string|null }\n */\nfunction bridgeCodec<T>(codec: SearchParamCodec<T>): SingleParser<T> & { defaultValue: T } {\n  return {\n    parse: (v: string) => codec.parse(v),\n    serialize: (v: T) => codec.serialize(v) ?? '',\n    defaultValue: codec.parse(undefined) as T,\n    eq: (a: T, b: T) => codec.serialize(a) === codec.serialize(b),\n  };\n}\n\n/**\n * Bridge an entire codec map to nuqs-compatible parsers.\n */\nfunction bridgeCodecs<T extends Record<string, unknown>>(codecs: {\n  [K in keyof T]: SearchParamCodec<T[K]>;\n}) {\n  const result: Record<string, SingleParser<unknown> & { defaultValue: unknown }> = {};\n  for (const key of Object.keys(codecs)) {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    result[key] = bridgeCodec(codecs[key as keyof T]) as any;\n  }\n  return result as { [K in keyof T]: SingleParser<T[K]> & { defaultValue: T[K] } };\n}\n\n// ─── Hook ─────────────────────────────────────────────────────────\n\n/**\n * Read and write typed search params from/to the URL.\n *\n * Delegates to nuqs internally. The timber nuqs adapter (auto-injected in\n * browser-entry.ts) handles RSC navigation on non-shallow updates.\n *\n * Usage:\n * ```ts\n * // Via a SearchParamsDefinition\n * const [params, setParams] = definition.useQueryStates()\n *\n * // Standalone with inline codecs\n * const [params, setParams] = useQueryStates({\n *   page: fromSchema(z.coerce.number().int().min(1).default(1)),\n * })\n * ```\n */\nexport function useQueryStates<T extends Record<string, unknown>>(\n  codecsOrRoute: { [K in keyof T]: SearchParamCodec<T[K]> } | string,\n  _options?: QueryStatesOptions,\n  urlKeys?: Readonly<Record<string, string>>\n): [T, SetParams<T>] {\n  // Route-string overload: resolve codecs from the registry\n  let codecs: { [K in keyof T]: SearchParamCodec<T[K]> };\n  let resolvedUrlKeys = urlKeys;\n  if (typeof codecsOrRoute === 'string') {\n    const definition = getSearchParams(codecsOrRoute);\n    if (!definition) {\n      throw new Error(\n        `useQueryStates('${codecsOrRoute}'): no search params registered for this route. ` +\n          `Either the route has no search-params.ts file, or it hasn't been loaded yet. ` +\n          `For cross-route usage, import the definition explicitly.`\n      );\n    }\n    codecs = definition.codecs as { [K in keyof T]: SearchParamCodec<T[K]> };\n    resolvedUrlKeys = definition.urlKeys;\n  } else {\n    codecs = codecsOrRoute;\n  }\n\n  const bridged = bridgeCodecs(codecs);\n\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const nuqsOptions: any = {};\n  if (resolvedUrlKeys && Object.keys(resolvedUrlKeys).length > 0) {\n    nuqsOptions.urlKeys = resolvedUrlKeys;\n  }\n\n  let values: Record<string, unknown>;\n  let setValues: Function;\n  try {\n    [values, setValues] = nuqsUseQueryStates(bridged, nuqsOptions);\n  } catch (err) {\n    if (\n      err instanceof Error &&\n      /Invalid hook call|cannot be called|Cannot read properties of null/i.test(err.message)\n    ) {\n      throw new Error(\n        'useQueryStates is a client component hook and cannot be called outside a React component. ' +\n          'Use definition.parse(searchParams) in server components instead.'\n      );\n    }\n    throw err;\n  }\n\n  // Wrap the nuqs setter to match timber's SetParams<T> signature.\n  // nuqs's setter accepts Partial<Nullable<Values>> | UpdaterFn | null.\n  // timber's setter accepts Partial<T> with optional SetParamsOptions.\n  const setParams: SetParams<T> = (partial, setOptions?) => {\n    const nuqsSetOptions: Record<string, unknown> = {};\n    if (setOptions?.shallow !== undefined) nuqsSetOptions.shallow = setOptions.shallow;\n    if (setOptions?.scroll !== undefined) nuqsSetOptions.scroll = setOptions.scroll;\n    if (setOptions?.history !== undefined) nuqsSetOptions.history = setOptions.history;\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    void setValues(partial as any, nuqsSetOptions);\n  };\n\n  return [values as T, setParams];\n}\n\n// ─── Definition binding ───────────────────────────────────────────\n\n/**\n * Create a useQueryStates binding for a SearchParamsDefinition.\n * This is used internally by SearchParamsDefinition.useQueryStates().\n */\nexport function bindUseQueryStates<T extends Record<string, unknown>>(\n  definition: SearchParamsDefinition<T>\n): (options?: QueryStatesOptions) => [T, SetParams<T>] {\n  return (options?: QueryStatesOptions) => {\n    return useQueryStates<T>(definition.codecs, options, definition.urlKeys);\n  };\n}\n"],"mappings":";;AAYA,IAAM,2BAAW,IAAI,KAA0C;;;;;AAO/D,SAAgB,qBAAqB,OAAe,YAA+C;AACjG,UAAS,IAAI,OAAO,WAAW;;;;;;AAQjC,SAAgB,gBAAgB,OAAwD;AACtF,QAAO,SAAS,IAAI,MAAM;;;;;;;;;;;;;;;;;;;ACC5B,SAAS,YAAe,OAAmE;AACzF,QAAO;EACL,QAAQ,MAAc,MAAM,MAAM,EAAE;EACpC,YAAY,MAAS,MAAM,UAAU,EAAE,IAAI;EAC3C,cAAc,MAAM,MAAM,KAAA,EAAU;EACpC,KAAK,GAAM,MAAS,MAAM,UAAU,EAAE,KAAK,MAAM,UAAU,EAAE;EAC9D;;;;;AAMH,SAAS,aAAgD,QAEtD;CACD,MAAM,SAA4E,EAAE;AACpF,MAAK,MAAM,OAAO,OAAO,KAAK,OAAO,CAEnC,QAAO,OAAO,YAAY,OAAO,KAAgB;AAEnD,QAAO;;;;;;;;;;;;;;;;;;;AAsBT,SAAgB,iBACd,eACA,UACA,SACmB;CAEnB,IAAI;CACJ,IAAI,kBAAkB;AACtB,KAAI,OAAO,kBAAkB,UAAU;EACrC,MAAM,aAAa,gBAAgB,cAAc;AACjD,MAAI,CAAC,WACH,OAAM,IAAI,MACR,mBAAmB,cAAc,uLAGlC;AAEH,WAAS,WAAW;AACpB,oBAAkB,WAAW;OAE7B,UAAS;CAGX,MAAM,UAAU,aAAa,OAAO;CAGpC,MAAM,cAAmB,EAAE;AAC3B,KAAI,mBAAmB,OAAO,KAAK,gBAAgB,CAAC,SAAS,EAC3D,aAAY,UAAU;CAGxB,IAAI;CACJ,IAAI;AACJ,KAAI;AACF,GAAC,QAAQ,aAAa,eAAmB,SAAS,YAAY;UACvD,KAAK;AACZ,MACE,eAAe,SACf,qEAAqE,KAAK,IAAI,QAAQ,CAEtF,OAAM,IAAI,MACR,6JAED;AAEH,QAAM;;CAMR,MAAM,aAA2B,SAAS,eAAgB;EACxD,MAAM,iBAA0C,EAAE;AAClD,MAAI,YAAY,YAAY,KAAA,EAAW,gBAAe,UAAU,WAAW;AAC3E,MAAI,YAAY,WAAW,KAAA,EAAW,gBAAe,SAAS,WAAW;AACzE,MAAI,YAAY,YAAY,KAAA,EAAW,gBAAe,UAAU,WAAW;AAEtE,YAAU,SAAgB,eAAe;;AAGhD,QAAO,CAAC,QAAa,UAAU;;;;;;AASjC,SAAgB,mBACd,YACqD;AACrD,SAAQ,YAAiC;AACvC,SAAO,iBAAkB,WAAW,QAAQ,SAAS,WAAW,QAAQ"}

package/dist/_chunks/{wrappers-BaG1bnM3.js → wrappers-CJQ3KwVr.js}

@@ -60,4 +60,4 @@ function withUrlKey(codec, urlKey) {
 //#endregion
 export { withUrlKey as n, withDefault as t };
 
-//# sourceMappingURL=wrappers-BaG1bnM3.js.map
+//# sourceMappingURL=wrappers-CJQ3KwVr.js.map

package/dist/_chunks/{wrappers-BaG1bnM3.js.map → wrappers-CJQ3KwVr.js.map}

@@ -1 +1 @@
-{"version":3,"file":"wrappers-BaG1bnM3.js","names":[],"sources":["../../src/search-params/wrappers.ts"],"sourcesContent":["/**\n * Codec wrappers — withDefault and withUrlKey.\n *\n * These are timber-specific utilities that work with any SearchParamCodec.\n * For actual codecs (string, integer, boolean, etc.), use nuqs parsers\n * or Standard Schema objects (Zod, Valibot, ArkType) with auto-detection.\n *\n * Design doc: design/23-search-params.md\n */\n\nimport type { SearchParamCodec, SearchParamCodecWithUrlKey } from './define.js';\n\n// ---------------------------------------------------------------------------\n// withDefault\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap a nullable codec with a default value. When the inner codec returns\n * null, the default is used instead. The output type becomes non-nullable.\n *\n * Works with any codec — nuqs parsers, custom codecs, fromSchema results.\n *\n * ```ts\n * import { parseAsInteger } from 'nuqs'\n * import { withDefault } from '@timber-js/app/search-params'\n *\n * const page = withDefault(parseAsInteger, 1)\n * // page.parse(undefined) → 1 (not null)\n * // page.parse('5') → 5\n * ```\n */\nexport function withDefault<T>(\n  codec: SearchParamCodec<T | null>,\n  defaultValue: T\n): SearchParamCodec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      const result = codec.parse(value);\n      return result === null ? defaultValue : result;\n    },\n    serialize(value: T): string | null {\n      return codec.serialize(value);\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// withUrlKey\n// ---------------------------------------------------------------------------\n\n/**\n * Attach a URL key alias to a codec. The alias determines what query\n * parameter key is used in the URL, while the TypeScript property name\n * stays descriptive.\n *\n * Aliases travel with codecs through object spread composition — when\n * you spread a bundle containing aliased codecs into defineSearchParams,\n * the aliases come along automatically.\n *\n * ```ts\n * import { parseAsString } from 'nuqs'\n * import { withUrlKey } from '@timber-js/app/search-params'\n *\n * export const searchable = {\n *   q: withUrlKey(parseAsString, 'search'),\n *   // ?search=shoes → { q: 'shoes' }\n * }\n * ```\n *\n * Composes with withDefault:\n * ```ts\n * import { parseAsInteger } from 'nuqs'\n * withUrlKey(withDefault(parseAsInteger, 1), 'p')\n * ```\n */\nexport function withUrlKey<T>(\n  codec: SearchParamCodec<T>,\n  urlKey: string\n): SearchParamCodecWithUrlKey<T> {\n  return {\n    parse: codec.parse.bind(codec),\n    serialize: codec.serialize.bind(codec),\n    urlKey,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA+BA,SAAgB,YACd,OACA,cACqB;AACrB,QAAO;EACL,MAAM,OAAyC;GAC7C,MAAM,SAAS,MAAM,MAAM,MAAM;AACjC,UAAO,WAAW,OAAO,eAAe;;EAE1C,UAAU,OAAyB;AACjC,UAAO,MAAM,UAAU,MAAM;;EAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCH,SAAgB,WACd,OACA,QAC+B;AAC/B,QAAO;EACL,OAAO,MAAM,MAAM,KAAK,MAAM;EAC9B,WAAW,MAAM,UAAU,KAAK,MAAM;EACtC;EACD"}
+{"version":3,"file":"wrappers-CJQ3KwVr.js","names":[],"sources":["../../src/search-params/wrappers.ts"],"sourcesContent":["/**\n * Codec wrappers — withDefault and withUrlKey.\n *\n * These are timber-specific utilities that work with any SearchParamCodec.\n * For actual codecs (string, integer, boolean, etc.), use nuqs parsers\n * or Standard Schema objects (Zod, Valibot, ArkType) with auto-detection.\n *\n * Design doc: design/23-search-params.md\n */\n\nimport type { SearchParamCodec, SearchParamCodecWithUrlKey } from './define.js';\n\n// ---------------------------------------------------------------------------\n// withDefault\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap a nullable codec with a default value. When the inner codec returns\n * null, the default is used instead. The output type becomes non-nullable.\n *\n * Works with any codec — nuqs parsers, custom codecs, fromSchema results.\n *\n * ```ts\n * import { parseAsInteger } from 'nuqs'\n * import { withDefault } from '@timber-js/app/search-params'\n *\n * const page = withDefault(parseAsInteger, 1)\n * // page.parse(undefined) → 1 (not null)\n * // page.parse('5') → 5\n * ```\n */\nexport function withDefault<T>(\n  codec: SearchParamCodec<T | null>,\n  defaultValue: T\n): SearchParamCodec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      const result = codec.parse(value);\n      return result === null ? defaultValue : result;\n    },\n    serialize(value: T): string | null {\n      return codec.serialize(value);\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// withUrlKey\n// ---------------------------------------------------------------------------\n\n/**\n * Attach a URL key alias to a codec. The alias determines what query\n * parameter key is used in the URL, while the TypeScript property name\n * stays descriptive.\n *\n * Aliases travel with codecs through object spread composition — when\n * you spread a bundle containing aliased codecs into defineSearchParams,\n * the aliases come along automatically.\n *\n * ```ts\n * import { parseAsString } from 'nuqs'\n * import { withUrlKey } from '@timber-js/app/search-params'\n *\n * export const searchable = {\n *   q: withUrlKey(parseAsString, 'search'),\n *   // ?search=shoes → { q: 'shoes' }\n * }\n * ```\n *\n * Composes with withDefault:\n * ```ts\n * import { parseAsInteger } from 'nuqs'\n * withUrlKey(withDefault(parseAsInteger, 1), 'p')\n * ```\n */\nexport function withUrlKey<T>(\n  codec: SearchParamCodec<T>,\n  urlKey: string\n): SearchParamCodecWithUrlKey<T> {\n  return {\n    parse: codec.parse.bind(codec),\n    serialize: codec.serialize.bind(codec),\n    urlKey,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA+BA,SAAgB,YACd,OACA,cACqB;AACrB,QAAO;EACL,MAAM,OAAyC;GAC7C,MAAM,SAAS,MAAM,MAAM,MAAM;AACjC,UAAO,WAAW,OAAO,eAAe;;EAE1C,UAAU,OAAyB;AACjC,UAAO,MAAM,UAAU,MAAM;;EAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCH,SAAgB,WACd,OACA,QAC+B;AAC/B,QAAO;EACL,OAAO,MAAM,MAAM,KAAK,MAAM;EAC9B,WAAW,MAAM,UAAU,KAAK,MAAM;EACtC;EACD"}

package/dist/cache/cache-api.d.ts

@@ -0,0 +1,24 @@
+import type { CacheOptions } from './index';
+/**
+ * Public caching API: `cache(fn, opts)`.
+ *
+ * Wraps an async function with cross-request caching. Uses the configured
+ * cache handler (defaults to MemoryCacheHandler, overridable via timber.config.ts).
+ *
+ * ```ts
+ * import { cache } from '@timber-js/app/cache';
+ *
+ * const getUser = cache(
+ *   async (id: string) => db.users.findUnique({ where: { id } }),
+ *   { ttl: 60, tags: (id) => [`user:${id}`] }
+ * );
+ * ```
+ */
+export declare function cache<Fn extends (...args: any[]) => Promise<any>>(fn: Fn, opts: CacheOptions<Fn>): Fn;
+export declare namespace cache {
+    var invalidate: (opts: {
+        key?: string;
+        tag?: string;
+    }) => Promise<void>;
+}
+//# sourceMappingURL=cache-api.d.ts.map

package/dist/cache/cache-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-api.d.ts","sourceRoot":"","sources":["../../src/cache/cache-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAI5C;;;;;;;;;;;;;;GAcG;AAEH,wBAAgB,KAAK,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EAC/D,EAAE,EAAE,EAAE,EACN,IAAI,EAAE,YAAY,CAAC,EAAE,CAAC,GACrB,EAAE,CAEJ;yBALe,KAAK;2BAe8B;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,KAAG,OAAO,CAAC,IAAI,CAAC"}

package/dist/cache/handler-store.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Module-level cache handler singleton.
+ *
+ * Lazily initialized to MemoryCacheHandler on first access. The framework
+ * replaces this at boot from timber.config.ts via setCacheHandler().
+ *
+ * This module avoids importing from ./index to prevent circular dependencies.
+ */
+interface CacheHandlerLike {
+    get(key: string): Promise<{
+        value: unknown;
+        stale: boolean;
+    } | null>;
+    set(key: string, value: unknown, opts: {
+        ttl: number;
+        tags: string[];
+    }): Promise<void>;
+    invalidate(opts: {
+        key?: string;
+        tag?: string;
+    }): Promise<void>;
+}
+/** Replace the active cache handler. Called by the framework at boot. */
+export declare function setCacheHandler(h: CacheHandlerLike): void;
+/**
+ * Get the active cache handler. Creates a default MemoryCacheHandler on
+ * first access if none has been set via setCacheHandler().
+ */
+export declare function getCacheHandler(): CacheHandlerLike;
+export {};
+//# sourceMappingURL=handler-store.d.ts.map

package/dist/cache/handler-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-store.d.ts","sourceRoot":"","sources":["../../src/cache/handler-store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,UAAU,gBAAgB;IACxB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IACrE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvF,UAAU,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AAID,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAEzD;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,gBAAgB,CAOlD"}

package/dist/cache/index.d.ts

@@ -46,7 +46,8 @@ export declare class MemoryCacheHandler implements CacheHandler {
 }
 export { RedisCacheHandler } from './redis-handler';
 export type { RedisClient } from './redis-handler';
-export { createCache } from './timber-cache';
+export { cache } from './cache-api';
+export { setCacheHandler, getCacheHandler } from './handler-store';
 export { registerCachedFunction } from './register-cached-function';
 export type { RegisterCachedFunctionOptions } from './register-cached-function';
 export { stableStringify } from './stable-stringify';

package/dist/cache/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IACrE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvF,UAAU,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AAGD,MAAM,WAAW,YAAY,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC;IAC1C,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC;IAC1D;uFACmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,kBAAmB,YAAW,YAAY;IACrD,OAAO,CAAC,KAAK,CAA4E;IACzF,OAAO,CAAC,OAAO,CAAS;gBAEZ,IAAI,CAAC,EAAE,yBAAyB;IAItC,GAAG,CAAC,GAAG,EAAE,MAAM;;;;IAYf,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE;IAuBtE,UAAU,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE;IAarD,gDAAgD;IAChD,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,YAAY,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC9E,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IACrE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvF,UAAU,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AAGD,MAAM,WAAW,YAAY,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC;IAC1C,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC;IAC1D;uFACmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,kBAAmB,YAAW,YAAY;IACrD,OAAO,CAAC,KAAK,CAA4E;IACzF,OAAO,CAAC,OAAO,CAAS;gBAEZ,IAAI,CAAC,EAAE,yBAAyB;IAItC,GAAG,CAAC,GAAG,EAAE,MAAM;;;;IAYf,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE;IAuBtE,UAAU,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE;IAarD,gDAAgD;IAChD,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,YAAY,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC9E,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/cache/index.js

@@ -1,4 +1,4 @@
-import { n as addSpanEventSync } from "../_chunks/tracing-VYETCQsg.js";
+import { i as addSpanEventSync, n as setCacheHandler, t as getCacheHandler } from "../_chunks/handler-store-CaE0ZgVG.js";
 //#region src/cache/redis-handler.ts
 var KEY_PREFIX = "timber:cache:";
 var TAG_PREFIX = "timber:tag:";
@@ -243,6 +243,37 @@ createCache.invalidate = async function invalidate(handler, opts) {
 	await handler.invalidate(opts);
 };
 //#endregion
+//#region src/cache/cache-api.ts
+/**
+* Public caching API: `cache(fn, opts)`.
+*
+* Wraps an async function with cross-request caching. Uses the configured
+* cache handler (defaults to MemoryCacheHandler, overridable via timber.config.ts).
+*
+* ```ts
+* import { cache } from '@timber-js/app/cache';
+*
+* const getUser = cache(
+*   async (id: string) => db.users.findUnique({ where: { id } }),
+*   { ttl: 60, tags: (id) => [`user:${id}`] }
+* );
+* ```
+*/
+function cache(fn, opts) {
+	return createCache(fn, opts, getCacheHandler());
+}
+/**
+* Invalidate cache entries by tag or key.
+*
+* ```ts
+* cache.invalidate({ tag: 'products' });
+* cache.invalidate({ key: 'user:abc' });
+* ```
+*/
+cache.invalidate = async function invalidate(opts) {
+	await getCacheHandler().invalidate(opts);
+};
+//#endregion
 //#region src/cache/register-cached-function.ts
 var singleflight = createSingleflight();
 var REQUEST_SPECIFIC_PROPS = new Set([
@@ -349,6 +380,6 @@ var MemoryCacheHandler = class {
 	}
 };
 //#endregion
-export { MemoryCacheHandler, RedisCacheHandler, SingleflightTimeoutError, createCache, createSingleflight, registerCachedFunction, stableStringify };
+export { MemoryCacheHandler, RedisCacheHandler, SingleflightTimeoutError, cache, createSingleflight, getCacheHandler, registerCachedFunction, setCacheHandler, stableStringify };
 
 //# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/cache/redis-handler.ts","../../src/cache/stable-stringify.ts","../../src/cache/singleflight.ts","../../src/cache/fast-hash.ts","../../src/cache/timber-cache.ts","../../src/cache/register-cached-function.ts","../../src/cache/index.ts"],"sourcesContent":["import type { CacheHandler } from './index';\n\n/**\n * Minimal Redis client interface — compatible with ioredis, node-redis, and\n * Cloudflare Workers Redis bindings. We depend on the interface, not the\n * implementation, so users bring their own Redis client.\n */\nexport interface RedisClient {\n  get(key: string): Promise<string | null>;\n  set(key: string, value: string, ...args: unknown[]): Promise<unknown>;\n  del(key: string | string[]): Promise<number>;\n  sadd(key: string, ...members: string[]): Promise<number>;\n  smembers(key: string): Promise<string[]>;\n}\n\nconst KEY_PREFIX = 'timber:cache:';\nconst TAG_PREFIX = 'timber:tag:';\n\n/**\n * Redis-backed CacheHandler for distributed caching.\n *\n * All instances sharing the same Redis see each other's cache entries and\n * invalidations. Tag-based invalidation uses Redis Sets to track which keys\n * belong to which tags.\n *\n * Bring your own Redis client — any client implementing the RedisClient\n * interface works (ioredis, node-redis, @upstash/redis, etc.).\n */\nexport class RedisCacheHandler implements CacheHandler {\n  private client: RedisClient;\n  private prefix: string;\n\n  constructor(client: RedisClient, opts?: { prefix?: string }) {\n    this.client = client;\n    this.prefix = opts?.prefix ?? '';\n  }\n\n  private cacheKey(key: string): string {\n    return `${this.prefix}${KEY_PREFIX}${key}`;\n  }\n\n  private tagKey(tag: string): string {\n    return `${this.prefix}${TAG_PREFIX}${tag}`;\n  }\n\n  async get(key: string): Promise<{ value: unknown; stale: boolean } | null> {\n    const raw = await this.client.get(this.cacheKey(key));\n    if (raw === null) return null;\n\n    const entry = JSON.parse(raw) as { value: unknown; expiresAt: number };\n    const stale = Date.now() > entry.expiresAt;\n    return { value: entry.value, stale };\n  }\n\n  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void> {\n    const ck = this.cacheKey(key);\n    const expiresAt = Date.now() + opts.ttl * 1000;\n    const payload = JSON.stringify({ value, expiresAt });\n\n    // Redis TTL with generous margin beyond the logical TTL to allow SWR reads\n    // on stale entries. The logical staleness is determined by expiresAt.\n    // We use 2x TTL + 60s as the Redis expiry so stale entries remain\n    // available for SWR background refetches.\n    const redisTtlSeconds = Math.max(opts.ttl * 2 + 60, 120);\n    await this.client.set(ck, payload, 'EX', redisTtlSeconds);\n\n    // Track key membership in each tag set\n    for (const tag of opts.tags) {\n      await this.client.sadd(this.tagKey(tag), key);\n    }\n  }\n\n  async invalidate(opts: { key?: string; tag?: string }): Promise<void> {\n    if (opts.key) {\n      await this.client.del(this.cacheKey(opts.key));\n    }\n\n    if (opts.tag) {\n      const tk = this.tagKey(opts.tag);\n      const keys = await this.client.smembers(tk);\n\n      if (keys.length > 0) {\n        const cacheKeys = keys.map((k) => this.cacheKey(k));\n        await this.client.del(cacheKeys);\n      }\n\n      // Clean up the tag set itself\n      await this.client.del(tk);\n    }\n  }\n}\n","/**\n * Deterministic JSON serialization with sorted object keys.\n * Used for cache key generation — ensures { a: 1, b: 2 } and { b: 2, a: 1 }\n * produce the same string.\n */\nexport function stableStringify(value: unknown): string {\n  if (value === null || value === undefined) return JSON.stringify(value);\n  if (typeof value !== 'object') return JSON.stringify(value);\n  if (Array.isArray(value)) {\n    return '[' + value.map((item) => stableStringify(item)).join(',') + ']';\n  }\n\n  const obj = value as Record<string, unknown>;\n  const keys = Object.keys(obj).sort();\n  const pairs: string[] = [];\n  for (const key of keys) {\n    if (obj[key] === undefined) continue;\n    pairs.push(JSON.stringify(key) + ':' + stableStringify(obj[key]));\n  }\n  return '{' + pairs.join(',') + '}';\n}\n","/**\n * Singleflight coalesces concurrent calls with the same key into a single\n * execution. All callers receive the same result (or error).\n *\n * Per-process, in-memory. Each process coalesces independently.\n *\n * An optional `timeoutMs` prevents hung `fn()` calls from permanently\n * blocking all future callers for that key. When set, `fn()` is raced\n * against a timeout — if the timeout fires first, the promise rejects\n * with `SingleflightTimeoutError`, `finally` cleans up the key, and\n * subsequent callers can retry. See TIM-518.\n */\n\nexport interface SingleflightOptions {\n  /** Maximum time (ms) a coalesced call may run before being rejected. */\n  timeoutMs?: number;\n}\n\nexport interface Singleflight {\n  do<T>(key: string, fn: () => Promise<T>): Promise<T>;\n}\n\n/**\n * Error thrown when a singleflight call exceeds `timeoutMs`.\n * Exported so callers can distinguish timeout from other errors.\n */\nexport class SingleflightTimeoutError extends Error {\n  constructor(key: string, timeoutMs: number) {\n    super(`Singleflight timeout: key \"${key}\" exceeded ${timeoutMs}ms`);\n    this.name = 'SingleflightTimeoutError';\n  }\n}\n\nexport function createSingleflight(opts?: SingleflightOptions): Singleflight {\n  const inflight = new Map<string, Promise<unknown>>();\n  const timeoutMs = opts?.timeoutMs;\n\n  return {\n    do<T>(key: string, fn: () => Promise<T>): Promise<T> {\n      const existing = inflight.get(key);\n      if (existing) return existing as Promise<T>;\n\n      let promise: Promise<T>;\n\n      if (timeoutMs != null && timeoutMs > 0) {\n        // Race fn() against a timeout to prevent hung calls from\n        // permanently blocking the key. See TIM-518.\n        promise = new Promise<T>((resolve, reject) => {\n          const timer = setTimeout(\n            () => reject(new SingleflightTimeoutError(key, timeoutMs)),\n            timeoutMs\n          );\n          // Wrap in try/catch so a synchronous throw from fn()\n          // (e.g. argument validation) still clears the timer.\n          // Without this, the timer leaks until expiry.\n          try {\n            fn().then(\n              (value) => {\n                clearTimeout(timer);\n                resolve(value);\n              },\n              (err) => {\n                clearTimeout(timer);\n                reject(err);\n              }\n            );\n          } catch (err) {\n            clearTimeout(timer);\n            reject(err);\n          }\n        });\n      } else {\n        promise = fn();\n      }\n\n      const tracked = promise.finally(() => {\n        inflight.delete(key);\n      });\n\n      inflight.set(key, tracked);\n      return tracked as Promise<T>;\n    },\n  };\n}\n","/**\n * Fast non-cryptographic hash for cache keys.\n *\n * FNV-1a 64-bit produces a well-distributed hash with a collision\n * probability of ~1 in 5 billion at 77k keys (birthday paradox).\n * Not suitable for security, but ideal for cache key generation\n * where we need speed over crypto strength.\n *\n * Uses BigInt for 64-bit arithmetic — supported in all modern runtimes\n * including Cloudflare Workers. No node:crypto dependency.\n *\n * See TIM-370.\n */\n\n// FNV-1a constants for 64-bit hash\nconst FNV_OFFSET_BASIS = 0xcbf29ce484222325n;\nconst FNV_PRIME = 0x100000001b3n;\nconst MASK_64 = 0xffffffffffffffffn;\n\n/**\n * Compute a 64-bit FNV-1a hash of a string, returned as a 16-char hex string.\n *\n * 64 bits gives ~5 billion keys before a 50% collision probability\n * (birthday paradox), making accidental collisions effectively impossible\n * for cache key use cases.\n */\nexport function fnv1aHash(input: string): string {\n  let hash = FNV_OFFSET_BASIS;\n  for (let i = 0; i < input.length; i++) {\n    hash ^= BigInt(input.charCodeAt(i));\n    hash = (hash * FNV_PRIME) & MASK_64;\n  }\n  return hash.toString(16).padStart(16, '0');\n}\n","import type { CacheHandler, CacheOptions } from './index';\nimport { stableStringify } from './stable-stringify';\nimport { createSingleflight } from './singleflight';\nimport { addSpanEventSync } from '../server/tracing.js';\nimport { fnv1aHash } from './fast-hash.js';\n\nconst defaultSingleflight = createSingleflight();\n\n/**\n * Generate a cache key from function identity and serialized args.\n *\n * Uses FNV-1a (fast non-crypto hash) instead of SHA-256. Cache keys don't\n * need collision resistance — they need speed. The fnId prefix provides\n * namespace isolation; the hash covers the args.\n *\n * See TIM-370 for perf motivation.\n */\nfunction defaultKeyGenerator(fnId: string, args: unknown[]): string {\n  const raw = fnId + ':' + stableStringify(args);\n  return fnId + ':' + fnv1aHash(raw);\n}\n\n/**\n * Resolve tags from the options — supports static array or function form.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nfunction resolveTags<Fn extends (...args: any[]) => any>(\n  opts: CacheOptions<Fn>,\n  args: Parameters<Fn>\n): string[] {\n  if (!opts.tags) return [];\n  if (Array.isArray(opts.tags)) return opts.tags;\n  return opts.tags(...args);\n}\n\n// Counter for generating unique function IDs when no explicit key is provided.\nlet fnIdCounter = 0;\n\n/**\n * Creates a cached wrapper around an async function.\n *\n * - SHA-256 default keys with normalized JSON args\n * - Singleflight: concurrent misses → single execution\n * - SWR: serve stale immediately, background refetch\n * - Tags as string[] or function of args\n * - No ALS dependency\n *\n * Cache hits/misses are recorded as OTEL span events on the enclosing\n * span (not child spans). The DevSpanProcessor reads these for dev log output.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function createCache<Fn extends (...args: any[]) => Promise<any>>(\n  fn: Fn,\n  opts: CacheOptions<Fn>,\n  handler: CacheHandler\n): Fn {\n  const fnId = `timber-cache:${fnIdCounter++}`;\n  const sf = opts.timeoutMs\n    ? createSingleflight({ timeoutMs: opts.timeoutMs })\n    : defaultSingleflight;\n\n  // Cast to Fn to preserve the original function's generic call signature.\n  // Without this, generic type parameters (e.g. <T> in apiFetch<T>) are\n  // erased and callers lose type safety on the return type.\n  return (async (...args: Parameters<Fn>): Promise<Awaited<ReturnType<Fn>>> => {\n    const key = opts.key ? opts.key(...args) : defaultKeyGenerator(fnId, args);\n\n    const cacheStart = performance.now();\n    const cached = await handler.get(key);\n\n    if (cached && !cached.stale) {\n      // Record as OTEL span event on enclosing span (not a child span).\n      // Fire-and-forget — no microtask overhead on the cache hot path.\n      addSpanEventSync('timber.cache.hit', {\n        key,\n        duration_ms: Math.round(performance.now() - cacheStart),\n      });\n      return cached.value as Awaited<ReturnType<Fn>>;\n    }\n\n    if (cached && cached.stale && opts.staleWhileRevalidate) {\n      // Record stale cache hit as OTEL span event (fire-and-forget).\n      addSpanEventSync('timber.cache.hit', {\n        key,\n        duration_ms: Math.round(performance.now() - cacheStart),\n        stale: true,\n      });\n      // Serve stale immediately, trigger background refetch\n      sf.do(`swr:${key}`, async () => {\n        try {\n          const fresh = await fn(...args);\n          const tags = resolveTags(opts, args);\n          await handler.set(key, fresh, { ttl: opts.ttl, tags });\n        } catch {\n          // Failed refetch — stale entry continues to be served.\n          // Error is swallowed per design doc: \"Error is logged.\"\n        }\n      }).catch(() => {\n        // Singleflight promise rejection handled — stale continues.\n      });\n      return cached.value as Awaited<ReturnType<Fn>>;\n    }\n\n    // Cache miss (or stale without SWR) — execute with singleflight\n    const result = await sf.do(key, () => fn(...args));\n    const tags = resolveTags(opts, args);\n    await handler.set(key, result, { ttl: opts.ttl, tags });\n\n    // Record cache miss as OTEL span event (fire-and-forget).\n    addSpanEventSync('timber.cache.miss', {\n      key,\n      duration_ms: Math.round(performance.now() - cacheStart),\n    });\n\n    return result as Awaited<ReturnType<Fn>>;\n  }) as unknown as Fn;\n}\n\n/**\n * Invalidate cache entries by tag or key.\n */\ncreateCache.invalidate = async function invalidate(\n  handler: CacheHandler,\n  opts: { key?: string; tag?: string }\n): Promise<void> {\n  await handler.invalidate(opts);\n};\n","import type { CacheHandler } from './index';\nimport { stableStringify } from './stable-stringify';\nimport { createSingleflight } from './singleflight';\nimport { fnv1aHash } from './fast-hash.js';\n\nconst singleflight = createSingleflight();\n\n// Prop names that suggest request-specific data — triggers dev warning for \"use cache\" components.\nconst REQUEST_SPECIFIC_PROPS = new Set([\n  'cookies',\n  'cookie',\n  'session',\n  'sessionId',\n  'token',\n  'authorization',\n  'auth',\n  'headers',\n]);\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface RegisterCachedFunctionOptions<Fn extends (...args: any[]) => any> {\n  ttl: number;\n  id: string;\n  tags?: string[] | ((...args: Parameters<Fn>) => string[]);\n  /** True when the cached function is a React component (PascalCase name). */\n  isComponent?: boolean;\n}\n\n/**\n * Generate a cache key from a stable function ID and serialized args.\n *\n * Uses FNV-1a (fast non-crypto hash) instead of SHA-256. The id prefix\n * provides namespace isolation; the hash covers the args.\n * See TIM-370.\n */\nfunction generateKey(id: string, args: unknown[]): string {\n  const raw = id + ':' + stableStringify(args);\n  return id + ':' + fnv1aHash(raw);\n}\n\n/**\n * Resolve tags from options — supports static array or function form.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nfunction resolveTags<Fn extends (...args: any[]) => any>(\n  opts: RegisterCachedFunctionOptions<Fn>,\n  args: Parameters<Fn>\n): string[] {\n  if (!opts.tags) return [];\n  if (Array.isArray(opts.tags)) return opts.tags;\n  return opts.tags(...args);\n}\n\n/**\n * Checks if component props contain request-specific keys and emits a dev warning.\n * Only runs when process.env.NODE_ENV !== 'production'.\n */\nfunction warnRequestSpecificProps(id: string, props: unknown): void {\n  if (typeof props !== 'object' || props === null) return;\n  const keys = Object.keys(props);\n  const suspicious = keys.filter((k) => REQUEST_SPECIFIC_PROPS.has(k.toLowerCase()));\n  if (suspicious.length > 0) {\n    console.warn(\n      `[timber] \"use cache\" component ${id} received request-specific props: ${suspicious.join(', ')}. ` +\n        `This may serve one user's cached render to another user. ` +\n        `Remove request-specific data from props or remove \"use cache\".`\n    );\n  }\n}\n\n/**\n * Runtime for the \"use cache\" directive transform. Wraps an async function\n * with caching using the same cache handler as timber.cache.\n *\n * The stable `id` (file path + function name) ensures cache keys are consistent\n * across builds. Args/props are hashed with SHA-256 for the per-call key.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function registerCachedFunction<Fn extends (...args: any[]) => Promise<any>>(\n  fn: Fn,\n  opts: RegisterCachedFunctionOptions<Fn>,\n  handler: CacheHandler\n): (...args: Parameters<Fn>) => Promise<Awaited<ReturnType<Fn>>> {\n  return async (...args: Parameters<Fn>): Promise<Awaited<ReturnType<Fn>>> => {\n    // Dev-mode warning for components with request-specific props\n    if (opts.isComponent && process.env.NODE_ENV !== 'production' && args.length > 0) {\n      warnRequestSpecificProps(opts.id, args[0]);\n    }\n\n    const key = generateKey(opts.id, args);\n    const cached = await handler.get(key);\n\n    if (cached && !cached.stale) {\n      return cached.value as Awaited<ReturnType<Fn>>;\n    }\n\n    // Cache miss or stale — execute with singleflight\n    const result = await singleflight.do(key, () => fn(...args));\n    const tags = resolveTags(opts, args);\n    await handler.set(key, result, { ttl: opts.ttl, tags });\n    return result as Awaited<ReturnType<Fn>>;\n  };\n}\n","// @timber-js/app/cache — Caching primitives\n\nexport interface CacheHandler {\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\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface CacheOptions<Fn extends (...args: any[]) => any> {\n  ttl: number;\n  key?: (...args: Parameters<Fn>) => string;\n  staleWhileRevalidate?: boolean;\n  tags?: string[] | ((...args: Parameters<Fn>) => string[]);\n  /** Timeout (ms) for singleflight-coalesced calls. Prevents hung fn() from\n   *  permanently blocking all future callers for the same cache key. See TIM-518. */\n  timeoutMs?: number;\n}\n\nexport interface MemoryCacheHandlerOptions {\n  /** Maximum number of entries. Oldest accessed entries are evicted first. Default: 1000. */\n  maxSize?: number;\n}\n\nexport class MemoryCacheHandler implements CacheHandler {\n  private store = new Map<string, { value: unknown; expiresAt: number; tags: string[] }>();\n  private maxSize: number;\n\n  constructor(opts?: MemoryCacheHandlerOptions) {\n    this.maxSize = opts?.maxSize ?? 1000;\n  }\n\n  async get(key: string) {\n    const entry = this.store.get(key);\n    if (!entry) return null;\n\n    // Move to end of Map (most recently used) for LRU ordering\n    this.store.delete(key);\n    this.store.set(key, entry);\n\n    const stale = Date.now() > entry.expiresAt;\n    return { value: entry.value, stale };\n  }\n\n  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }) {\n    // If key already exists, delete first to refresh insertion order\n    if (this.store.has(key)) {\n      this.store.delete(key);\n    }\n\n    // Evict oldest entries (front of Map) if at capacity\n    while (this.store.size >= this.maxSize) {\n      const oldest = this.store.keys().next().value;\n      if (oldest !== undefined) {\n        this.store.delete(oldest);\n      } else {\n        break;\n      }\n    }\n\n    this.store.set(key, {\n      value,\n      expiresAt: Date.now() + opts.ttl * 1000,\n      tags: opts.tags,\n    });\n  }\n\n  async invalidate(opts: { key?: string; tag?: string }) {\n    if (opts.key) {\n      this.store.delete(opts.key);\n    }\n    if (opts.tag) {\n      for (const [key, entry] of this.store) {\n        if (entry.tags.includes(opts.tag)) {\n          this.store.delete(key);\n        }\n      }\n    }\n  }\n\n  /** Number of entries currently in the cache. */\n  get size(): number {\n    return this.store.size;\n  }\n}\n\nexport { RedisCacheHandler } from './redis-handler';\nexport type { RedisClient } from './redis-handler';\nexport { createCache } from './timber-cache';\nexport { registerCachedFunction } from './register-cached-function';\nexport type { RegisterCachedFunctionOptions } from './register-cached-function';\nexport { stableStringify } from './stable-stringify';\nexport { createSingleflight, SingleflightTimeoutError } from './singleflight';\nexport type { Singleflight, SingleflightOptions } from './singleflight';\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/cache/redis-handler.ts","../../src/cache/stable-stringify.ts","../../src/cache/singleflight.ts","../../src/cache/fast-hash.ts","../../src/cache/timber-cache.ts","../../src/cache/cache-api.ts","../../src/cache/register-cached-function.ts","../../src/cache/index.ts"],"sourcesContent":["import type { CacheHandler } from './index';\n\n/**\n * Minimal Redis client interface — compatible with ioredis, node-redis, and\n * Cloudflare Workers Redis bindings. We depend on the interface, not the\n * implementation, so users bring their own Redis client.\n */\nexport interface RedisClient {\n  get(key: string): Promise<string | null>;\n  set(key: string, value: string, ...args: unknown[]): Promise<unknown>;\n  del(key: string | string[]): Promise<number>;\n  sadd(key: string, ...members: string[]): Promise<number>;\n  smembers(key: string): Promise<string[]>;\n}\n\nconst KEY_PREFIX = 'timber:cache:';\nconst TAG_PREFIX = 'timber:tag:';\n\n/**\n * Redis-backed CacheHandler for distributed caching.\n *\n * All instances sharing the same Redis see each other's cache entries and\n * invalidations. Tag-based invalidation uses Redis Sets to track which keys\n * belong to which tags.\n *\n * Bring your own Redis client — any client implementing the RedisClient\n * interface works (ioredis, node-redis, @upstash/redis, etc.).\n */\nexport class RedisCacheHandler implements CacheHandler {\n  private client: RedisClient;\n  private prefix: string;\n\n  constructor(client: RedisClient, opts?: { prefix?: string }) {\n    this.client = client;\n    this.prefix = opts?.prefix ?? '';\n  }\n\n  private cacheKey(key: string): string {\n    return `${this.prefix}${KEY_PREFIX}${key}`;\n  }\n\n  private tagKey(tag: string): string {\n    return `${this.prefix}${TAG_PREFIX}${tag}`;\n  }\n\n  async get(key: string): Promise<{ value: unknown; stale: boolean } | null> {\n    const raw = await this.client.get(this.cacheKey(key));\n    if (raw === null) return null;\n\n    const entry = JSON.parse(raw) as { value: unknown; expiresAt: number };\n    const stale = Date.now() > entry.expiresAt;\n    return { value: entry.value, stale };\n  }\n\n  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void> {\n    const ck = this.cacheKey(key);\n    const expiresAt = Date.now() + opts.ttl * 1000;\n    const payload = JSON.stringify({ value, expiresAt });\n\n    // Redis TTL with generous margin beyond the logical TTL to allow SWR reads\n    // on stale entries. The logical staleness is determined by expiresAt.\n    // We use 2x TTL + 60s as the Redis expiry so stale entries remain\n    // available for SWR background refetches.\n    const redisTtlSeconds = Math.max(opts.ttl * 2 + 60, 120);\n    await this.client.set(ck, payload, 'EX', redisTtlSeconds);\n\n    // Track key membership in each tag set\n    for (const tag of opts.tags) {\n      await this.client.sadd(this.tagKey(tag), key);\n    }\n  }\n\n  async invalidate(opts: { key?: string; tag?: string }): Promise<void> {\n    if (opts.key) {\n      await this.client.del(this.cacheKey(opts.key));\n    }\n\n    if (opts.tag) {\n      const tk = this.tagKey(opts.tag);\n      const keys = await this.client.smembers(tk);\n\n      if (keys.length > 0) {\n        const cacheKeys = keys.map((k) => this.cacheKey(k));\n        await this.client.del(cacheKeys);\n      }\n\n      // Clean up the tag set itself\n      await this.client.del(tk);\n    }\n  }\n}\n","/**\n * Deterministic JSON serialization with sorted object keys.\n * Used for cache key generation — ensures { a: 1, b: 2 } and { b: 2, a: 1 }\n * produce the same string.\n */\nexport function stableStringify(value: unknown): string {\n  if (value === null || value === undefined) return JSON.stringify(value);\n  if (typeof value !== 'object') return JSON.stringify(value);\n  if (Array.isArray(value)) {\n    return '[' + value.map((item) => stableStringify(item)).join(',') + ']';\n  }\n\n  const obj = value as Record<string, unknown>;\n  const keys = Object.keys(obj).sort();\n  const pairs: string[] = [];\n  for (const key of keys) {\n    if (obj[key] === undefined) continue;\n    pairs.push(JSON.stringify(key) + ':' + stableStringify(obj[key]));\n  }\n  return '{' + pairs.join(',') + '}';\n}\n","/**\n * Singleflight coalesces concurrent calls with the same key into a single\n * execution. All callers receive the same result (or error).\n *\n * Per-process, in-memory. Each process coalesces independently.\n *\n * An optional `timeoutMs` prevents hung `fn()` calls from permanently\n * blocking all future callers for that key. When set, `fn()` is raced\n * against a timeout — if the timeout fires first, the promise rejects\n * with `SingleflightTimeoutError`, `finally` cleans up the key, and\n * subsequent callers can retry. See TIM-518.\n */\n\nexport interface SingleflightOptions {\n  /** Maximum time (ms) a coalesced call may run before being rejected. */\n  timeoutMs?: number;\n}\n\nexport interface Singleflight {\n  do<T>(key: string, fn: () => Promise<T>): Promise<T>;\n}\n\n/**\n * Error thrown when a singleflight call exceeds `timeoutMs`.\n * Exported so callers can distinguish timeout from other errors.\n */\nexport class SingleflightTimeoutError extends Error {\n  constructor(key: string, timeoutMs: number) {\n    super(`Singleflight timeout: key \"${key}\" exceeded ${timeoutMs}ms`);\n    this.name = 'SingleflightTimeoutError';\n  }\n}\n\nexport function createSingleflight(opts?: SingleflightOptions): Singleflight {\n  const inflight = new Map<string, Promise<unknown>>();\n  const timeoutMs = opts?.timeoutMs;\n\n  return {\n    do<T>(key: string, fn: () => Promise<T>): Promise<T> {\n      const existing = inflight.get(key);\n      if (existing) return existing as Promise<T>;\n\n      let promise: Promise<T>;\n\n      if (timeoutMs != null && timeoutMs > 0) {\n        // Race fn() against a timeout to prevent hung calls from\n        // permanently blocking the key. See TIM-518.\n        promise = new Promise<T>((resolve, reject) => {\n          const timer = setTimeout(\n            () => reject(new SingleflightTimeoutError(key, timeoutMs)),\n            timeoutMs\n          );\n          // Wrap in try/catch so a synchronous throw from fn()\n          // (e.g. argument validation) still clears the timer.\n          // Without this, the timer leaks until expiry.\n          try {\n            fn().then(\n              (value) => {\n                clearTimeout(timer);\n                resolve(value);\n              },\n              (err) => {\n                clearTimeout(timer);\n                reject(err);\n              }\n            );\n          } catch (err) {\n            clearTimeout(timer);\n            reject(err);\n          }\n        });\n      } else {\n        promise = fn();\n      }\n\n      const tracked = promise.finally(() => {\n        inflight.delete(key);\n      });\n\n      inflight.set(key, tracked);\n      return tracked as Promise<T>;\n    },\n  };\n}\n","/**\n * Fast non-cryptographic hash for cache keys.\n *\n * FNV-1a 64-bit produces a well-distributed hash with a collision\n * probability of ~1 in 5 billion at 77k keys (birthday paradox).\n * Not suitable for security, but ideal for cache key generation\n * where we need speed over crypto strength.\n *\n * Uses BigInt for 64-bit arithmetic — supported in all modern runtimes\n * including Cloudflare Workers. No node:crypto dependency.\n *\n * See TIM-370.\n */\n\n// FNV-1a constants for 64-bit hash\nconst FNV_OFFSET_BASIS = 0xcbf29ce484222325n;\nconst FNV_PRIME = 0x100000001b3n;\nconst MASK_64 = 0xffffffffffffffffn;\n\n/**\n * Compute a 64-bit FNV-1a hash of a string, returned as a 16-char hex string.\n *\n * 64 bits gives ~5 billion keys before a 50% collision probability\n * (birthday paradox), making accidental collisions effectively impossible\n * for cache key use cases.\n */\nexport function fnv1aHash(input: string): string {\n  let hash = FNV_OFFSET_BASIS;\n  for (let i = 0; i < input.length; i++) {\n    hash ^= BigInt(input.charCodeAt(i));\n    hash = (hash * FNV_PRIME) & MASK_64;\n  }\n  return hash.toString(16).padStart(16, '0');\n}\n","import type { CacheHandler, CacheOptions } from './index';\nimport { stableStringify } from './stable-stringify';\nimport { createSingleflight } from './singleflight';\nimport { addSpanEventSync } from '../server/tracing.js';\nimport { fnv1aHash } from './fast-hash.js';\n\nconst defaultSingleflight = createSingleflight();\n\n/**\n * Generate a cache key from function identity and serialized args.\n *\n * Uses FNV-1a (fast non-crypto hash) instead of SHA-256. Cache keys don't\n * need collision resistance — they need speed. The fnId prefix provides\n * namespace isolation; the hash covers the args.\n *\n * See TIM-370 for perf motivation.\n */\nfunction defaultKeyGenerator(fnId: string, args: unknown[]): string {\n  const raw = fnId + ':' + stableStringify(args);\n  return fnId + ':' + fnv1aHash(raw);\n}\n\n/**\n * Resolve tags from the options — supports static array or function form.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nfunction resolveTags<Fn extends (...args: any[]) => any>(\n  opts: CacheOptions<Fn>,\n  args: Parameters<Fn>\n): string[] {\n  if (!opts.tags) return [];\n  if (Array.isArray(opts.tags)) return opts.tags;\n  return opts.tags(...args);\n}\n\n// Counter for generating unique function IDs when no explicit key is provided.\nlet fnIdCounter = 0;\n\n/**\n * Creates a cached wrapper around an async function.\n *\n * - SHA-256 default keys with normalized JSON args\n * - Singleflight: concurrent misses → single execution\n * - SWR: serve stale immediately, background refetch\n * - Tags as string[] or function of args\n * - No ALS dependency\n *\n * Cache hits/misses are recorded as OTEL span events on the enclosing\n * span (not child spans). The DevSpanProcessor reads these for dev log output.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function createCache<Fn extends (...args: any[]) => Promise<any>>(\n  fn: Fn,\n  opts: CacheOptions<Fn>,\n  handler: CacheHandler\n): Fn {\n  const fnId = `timber-cache:${fnIdCounter++}`;\n  const sf = opts.timeoutMs\n    ? createSingleflight({ timeoutMs: opts.timeoutMs })\n    : defaultSingleflight;\n\n  // Cast to Fn to preserve the original function's generic call signature.\n  // Without this, generic type parameters (e.g. <T> in apiFetch<T>) are\n  // erased and callers lose type safety on the return type.\n  return (async (...args: Parameters<Fn>): Promise<Awaited<ReturnType<Fn>>> => {\n    const key = opts.key ? opts.key(...args) : defaultKeyGenerator(fnId, args);\n\n    const cacheStart = performance.now();\n    const cached = await handler.get(key);\n\n    if (cached && !cached.stale) {\n      // Record as OTEL span event on enclosing span (not a child span).\n      // Fire-and-forget — no microtask overhead on the cache hot path.\n      addSpanEventSync('timber.cache.hit', {\n        key,\n        duration_ms: Math.round(performance.now() - cacheStart),\n      });\n      return cached.value as Awaited<ReturnType<Fn>>;\n    }\n\n    if (cached && cached.stale && opts.staleWhileRevalidate) {\n      // Record stale cache hit as OTEL span event (fire-and-forget).\n      addSpanEventSync('timber.cache.hit', {\n        key,\n        duration_ms: Math.round(performance.now() - cacheStart),\n        stale: true,\n      });\n      // Serve stale immediately, trigger background refetch\n      sf.do(`swr:${key}`, async () => {\n        try {\n          const fresh = await fn(...args);\n          const tags = resolveTags(opts, args);\n          await handler.set(key, fresh, { ttl: opts.ttl, tags });\n        } catch {\n          // Failed refetch — stale entry continues to be served.\n          // Error is swallowed per design doc: \"Error is logged.\"\n        }\n      }).catch(() => {\n        // Singleflight promise rejection handled — stale continues.\n      });\n      return cached.value as Awaited<ReturnType<Fn>>;\n    }\n\n    // Cache miss (or stale without SWR) — execute with singleflight\n    const result = await sf.do(key, () => fn(...args));\n    const tags = resolveTags(opts, args);\n    await handler.set(key, result, { ttl: opts.ttl, tags });\n\n    // Record cache miss as OTEL span event (fire-and-forget).\n    addSpanEventSync('timber.cache.miss', {\n      key,\n      duration_ms: Math.round(performance.now() - cacheStart),\n    });\n\n    return result as Awaited<ReturnType<Fn>>;\n  }) as unknown as Fn;\n}\n\n/**\n * Invalidate cache entries by tag or key.\n */\ncreateCache.invalidate = async function invalidate(\n  handler: CacheHandler,\n  opts: { key?: string; tag?: string }\n): Promise<void> {\n  await handler.invalidate(opts);\n};\n","import type { CacheOptions } from './index';\nimport { createCache } from './timber-cache';\nimport { getCacheHandler } from './handler-store';\n\n/**\n * Public caching API: `cache(fn, opts)`.\n *\n * Wraps an async function with cross-request caching. Uses the configured\n * cache handler (defaults to MemoryCacheHandler, overridable via timber.config.ts).\n *\n * ```ts\n * import { cache } from '@timber-js/app/cache';\n *\n * const getUser = cache(\n *   async (id: string) => db.users.findUnique({ where: { id } }),\n *   { ttl: 60, tags: (id) => [`user:${id}`] }\n * );\n * ```\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function cache<Fn extends (...args: any[]) => Promise<any>>(\n  fn: Fn,\n  opts: CacheOptions<Fn>\n): Fn {\n  return createCache(fn, opts, getCacheHandler());\n}\n\n/**\n * Invalidate cache entries by tag or key.\n *\n * ```ts\n * cache.invalidate({ tag: 'products' });\n * cache.invalidate({ key: 'user:abc' });\n * ```\n */\ncache.invalidate = async function invalidate(opts: { key?: string; tag?: string }): Promise<void> {\n  await getCacheHandler().invalidate(opts);\n};\n","import type { CacheHandler } from './index';\nimport { stableStringify } from './stable-stringify';\nimport { createSingleflight } from './singleflight';\nimport { fnv1aHash } from './fast-hash.js';\n\nconst singleflight = createSingleflight();\n\n// Prop names that suggest request-specific data — triggers dev warning for \"use cache\" components.\nconst REQUEST_SPECIFIC_PROPS = new Set([\n  'cookies',\n  'cookie',\n  'session',\n  'sessionId',\n  'token',\n  'authorization',\n  'auth',\n  'headers',\n]);\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface RegisterCachedFunctionOptions<Fn extends (...args: any[]) => any> {\n  ttl: number;\n  id: string;\n  tags?: string[] | ((...args: Parameters<Fn>) => string[]);\n  /** True when the cached function is a React component (PascalCase name). */\n  isComponent?: boolean;\n}\n\n/**\n * Generate a cache key from a stable function ID and serialized args.\n *\n * Uses FNV-1a (fast non-crypto hash) instead of SHA-256. The id prefix\n * provides namespace isolation; the hash covers the args.\n * See TIM-370.\n */\nfunction generateKey(id: string, args: unknown[]): string {\n  const raw = id + ':' + stableStringify(args);\n  return id + ':' + fnv1aHash(raw);\n}\n\n/**\n * Resolve tags from options — supports static array or function form.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nfunction resolveTags<Fn extends (...args: any[]) => any>(\n  opts: RegisterCachedFunctionOptions<Fn>,\n  args: Parameters<Fn>\n): string[] {\n  if (!opts.tags) return [];\n  if (Array.isArray(opts.tags)) return opts.tags;\n  return opts.tags(...args);\n}\n\n/**\n * Checks if component props contain request-specific keys and emits a dev warning.\n * Only runs when process.env.NODE_ENV !== 'production'.\n */\nfunction warnRequestSpecificProps(id: string, props: unknown): void {\n  if (typeof props !== 'object' || props === null) return;\n  const keys = Object.keys(props);\n  const suspicious = keys.filter((k) => REQUEST_SPECIFIC_PROPS.has(k.toLowerCase()));\n  if (suspicious.length > 0) {\n    console.warn(\n      `[timber] \"use cache\" component ${id} received request-specific props: ${suspicious.join(', ')}. ` +\n        `This may serve one user's cached render to another user. ` +\n        `Remove request-specific data from props or remove \"use cache\".`\n    );\n  }\n}\n\n/**\n * Runtime for the \"use cache\" directive transform. Wraps an async function\n * with caching using the same cache handler as timber.cache.\n *\n * The stable `id` (file path + function name) ensures cache keys are consistent\n * across builds. Args/props are hashed with SHA-256 for the per-call key.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function registerCachedFunction<Fn extends (...args: any[]) => Promise<any>>(\n  fn: Fn,\n  opts: RegisterCachedFunctionOptions<Fn>,\n  handler: CacheHandler\n): (...args: Parameters<Fn>) => Promise<Awaited<ReturnType<Fn>>> {\n  return async (...args: Parameters<Fn>): Promise<Awaited<ReturnType<Fn>>> => {\n    // Dev-mode warning for components with request-specific props\n    if (opts.isComponent && process.env.NODE_ENV !== 'production' && args.length > 0) {\n      warnRequestSpecificProps(opts.id, args[0]);\n    }\n\n    const key = generateKey(opts.id, args);\n    const cached = await handler.get(key);\n\n    if (cached && !cached.stale) {\n      return cached.value as Awaited<ReturnType<Fn>>;\n    }\n\n    // Cache miss or stale — execute with singleflight\n    const result = await singleflight.do(key, () => fn(...args));\n    const tags = resolveTags(opts, args);\n    await handler.set(key, result, { ttl: opts.ttl, tags });\n    return result as Awaited<ReturnType<Fn>>;\n  };\n}\n","// @timber-js/app/cache — Caching primitives\n\nexport interface CacheHandler {\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\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface CacheOptions<Fn extends (...args: any[]) => any> {\n  ttl: number;\n  key?: (...args: Parameters<Fn>) => string;\n  staleWhileRevalidate?: boolean;\n  tags?: string[] | ((...args: Parameters<Fn>) => string[]);\n  /** Timeout (ms) for singleflight-coalesced calls. Prevents hung fn() from\n   *  permanently blocking all future callers for the same cache key. See TIM-518. */\n  timeoutMs?: number;\n}\n\nexport interface MemoryCacheHandlerOptions {\n  /** Maximum number of entries. Oldest accessed entries are evicted first. Default: 1000. */\n  maxSize?: number;\n}\n\nexport class MemoryCacheHandler implements CacheHandler {\n  private store = new Map<string, { value: unknown; expiresAt: number; tags: string[] }>();\n  private maxSize: number;\n\n  constructor(opts?: MemoryCacheHandlerOptions) {\n    this.maxSize = opts?.maxSize ?? 1000;\n  }\n\n  async get(key: string) {\n    const entry = this.store.get(key);\n    if (!entry) return null;\n\n    // Move to end of Map (most recently used) for LRU ordering\n    this.store.delete(key);\n    this.store.set(key, entry);\n\n    const stale = Date.now() > entry.expiresAt;\n    return { value: entry.value, stale };\n  }\n\n  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }) {\n    // If key already exists, delete first to refresh insertion order\n    if (this.store.has(key)) {\n      this.store.delete(key);\n    }\n\n    // Evict oldest entries (front of Map) if at capacity\n    while (this.store.size >= this.maxSize) {\n      const oldest = this.store.keys().next().value;\n      if (oldest !== undefined) {\n        this.store.delete(oldest);\n      } else {\n        break;\n      }\n    }\n\n    this.store.set(key, {\n      value,\n      expiresAt: Date.now() + opts.ttl * 1000,\n      tags: opts.tags,\n    });\n  }\n\n  async invalidate(opts: { key?: string; tag?: string }) {\n    if (opts.key) {\n      this.store.delete(opts.key);\n    }\n    if (opts.tag) {\n      for (const [key, entry] of this.store) {\n        if (entry.tags.includes(opts.tag)) {\n          this.store.delete(key);\n        }\n      }\n    }\n  }\n\n  /** Number of entries currently in the cache. */\n  get size(): number {\n    return this.store.size;\n  }\n}\n\nexport { RedisCacheHandler } from './redis-handler';\nexport type { RedisClient } from './redis-handler';\nexport { cache } from './cache-api';\nexport { setCacheHandler, getCacheHandler } from './handler-store';\nexport { registerCachedFunction } from './register-cached-function';\nexport type { RegisterCachedFunctionOptions } from './register-cached-function';\nexport { stableStringify } from './stable-stringify';\nexport { createSingleflight, SingleflightTimeoutError } from './singleflight';\nexport type { Singleflight, SingleflightOptions } from './singleflight';\n"],"mappings":"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"}

package/dist/client/error-boundary.js

@@ -1,4 +1,4 @@
 "use client";
 "use client";
-import { t as TimberErrorBoundary } from "../_chunks/error-boundary-DpZJBCqh.js";
+import { t as TimberErrorBoundary } from "../_chunks/error-boundary-A_sgyyUP.js";
 export { TimberErrorBoundary };

package/dist/client/index.d.ts

@@ -8,7 +8,7 @@ export type { RouterInstance, NavigationOptions, RouterDeps, RouterPhase, RscDec
 export { useNavigationPending } from './use-navigation-pending';
 export { useLinkStatus, LinkStatusContext } from './use-link-status';
 export type { LinkStatus } from './use-link-status';
-export { getRouter, setGlobalRouter } from './router-ref';
+export { getRouter, getRouterOrNull, setGlobalRouter } from './router-ref';
 export { useRouter } from './use-router';
 export type { AppRouterInstance } from './use-router';
 export { usePathname } from './use-pathname';

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAGnE,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,WAAW,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAChG,OAAO,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AAC9E,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAChF,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,UAAU,EACV,WAAW,EACX,UAAU,EACV,YAAY,GACb,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACrE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAGpG,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACvE,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAG7D,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC9D,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG9D,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAG9C,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACtE,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAGvF,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGlE,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAClG,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAG5D,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAGxE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAUtE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAClE,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG1C,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAGnE,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,WAAW,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAChG,OAAO,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AAC9E,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAChF,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,UAAU,EACV,WAAW,EACX,UAAU,EACV,YAAY,GACb,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACrE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAGpG,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACvE,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAG7D,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC9D,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG9D,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAG9C,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACtE,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAGvF,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGlE,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAClG,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAG5D,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAGxE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAUtE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAClE,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG1C,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/client/index.js

@@ -1,9 +1,10 @@
 "use client";
 import { n as __exportAll } from "../_chunks/chunk-DYhsFzuS.js";
-import { n as useQueryStates, t as bindUseQueryStates } from "../_chunks/use-query-states-wEXY2JQB.js";
-import { n as useSegmentContext, r as mergePreservedSearchParams, t as SegmentProvider } from "../_chunks/segment-context-CyaM1mrD.js";
-import { a as _setCachedSearch, c as cachedSearch, d as globalRouter, i as setSsrData, l as cachedSearchParams, n as clearSsrData, o as _setCurrentParams, r as getSsrData, s as _setGlobalRouter, t as TimberErrorBoundary, u as currentParams } from "../_chunks/error-boundary-DpZJBCqh.js";
-import { t as _registerUseCookieModule } from "../_chunks/define-cookie-DtAavax4.js";
+import { t as classifyUrlSegment } from "../_chunks/segment-classify-BDNn6EzD.js";
+import { n as useQueryStates, t as bindUseQueryStates } from "../_chunks/use-query-states-DAhgj8Gx.js";
+import { n as useSegmentContext, r as mergePreservedSearchParams, t as SegmentProvider } from "../_chunks/segment-context-CVRHlkkQ.js";
+import { a as _setCachedSearch, c as cachedSearch, d as globalRouter, i as setSsrData, l as cachedSearchParams, n as clearSsrData, o as _setCurrentParams, r as getSsrData, s as _setGlobalRouter, t as TimberErrorBoundary, u as currentParams } from "../_chunks/error-boundary-A_sgyyUP.js";
+import { t as _registerUseCookieModule } from "../_chunks/define-cookie-B2djY9w0.js";
 import React, { cloneElement, createContext, createElement, isValidElement, useActionState as useActionState$1, useContext, useEffect, useRef, useState, useSyncExternalStore, useTransition } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/client/use-link-status.ts
@@ -143,25 +144,53 @@ function isInternalHref(href) {
 * - [...param]       → catch-all (joined with /)
 * - [[...param]]     → optional catch-all (omitted if undefined/empty)
 */
-function interpolateParams(pattern, params) {
-	return pattern.replace(/\[\[\.\.\.(\w+)\]\]|\[\.\.\.(\w+)\]|\[(\w+)\]/g, (_match, optionalCatchAll, catchAll, single) => {
-		if (optionalCatchAll) {
-			const value = params[optionalCatchAll];
-			if (value === void 0 || Array.isArray(value) && value.length === 0) return "";
+/**
+* Parse a route pattern's path portion into classified segments.
+* Exported for testing. Uses the shared character-based classifier.
+*/
+function parseSegments(pattern) {
+	return pattern.split("/").filter(Boolean).map(classifyUrlSegment);
+}
+/**
+* Resolve a single classified segment into its string representation.
+* Returns null for optional catch-all with no value (filtered out before join).
+*/
+function resolveSegment(seg, params, pattern) {
+	switch (seg.kind) {
+		case "static": return seg.value;
+		case "optional-catch-all": {
+			const value = params[seg.name];
+			if (value === void 0 || Array.isArray(value) && value.length === 0) return null;
 			return (Array.isArray(value) ? value : [value]).map(encodeURIComponent).join("/");
 		}
-		if (catchAll) {
-			const value = params[catchAll];
-			if (value === void 0) throw new Error(`<Link> missing required catch-all param "${catchAll}" for pattern "${pattern}".`);
+		case "catch-all": {
+			const value = params[seg.name];
+			if (value === void 0) throw new Error(`<Link> missing required catch-all param "${seg.name}" for pattern "${pattern}".`);
 			const segments = Array.isArray(value) ? value : [value];
-			if (segments.length === 0) throw new Error(`<Link> catch-all param "${catchAll}" must have at least one segment for pattern "${pattern}".`);
+			if (segments.length === 0) throw new Error(`<Link> catch-all param "${seg.name}" must have at least one segment for pattern "${pattern}".`);
 			return segments.map(encodeURIComponent).join("/");
 		}
-		const value = params[single];
-		if (value === void 0) throw new Error(`<Link> missing required param "${single}" for pattern "${pattern}".`);
-		if (Array.isArray(value)) throw new Error(`<Link> param "${single}" expected a string but received an array for pattern "${pattern}".`);
-		return encodeURIComponent(String(value));
-	}).replace(/\/+$/, "") || "/";
+		case "dynamic": {
+			const value = params[seg.name];
+			if (value === void 0) throw new Error(`<Link> missing required param "${seg.name}" for pattern "${pattern}".`);
+			if (Array.isArray(value)) throw new Error(`<Link> param "${seg.name}" expected a string but received an array for pattern "${pattern}".`);
+			return encodeURIComponent(String(value));
+		}
+	}
+}
+/**
+* Split a URL pattern into the path portion and any trailing ?query/#hash suffix.
+* Uses URL parsing for correctness rather than manual index arithmetic.
+*/
+function splitPatternSuffix(pattern) {
+	if (!pattern.includes("?") && !pattern.includes("#")) return [pattern, ""];
+	const url = new URL(pattern, "http://x");
+	const suffix = url.search + url.hash;
+	return [pattern.slice(0, pattern.length - suffix.length), suffix];
+}
+function interpolateParams(pattern, params) {
+	const [pathPart, suffix] = splitPatternSuffix(pattern);
+	return ("/" + parseSegments(pathPart).map((seg) => resolveSegment(seg, params, pattern)).filter((s) => s !== null).join("/") || "/") + suffix;
 }
 /**
 * Resolve the final href string from Link props.
@@ -965,7 +994,7 @@ async function fetchRscPayload(url, deps, stateTree, currentUrl) {
 			if (checkReloadSignal(response)) throw new VersionSkewError();
 			const redirectLocation = response.headers.get("X-Timber-Redirect") || (response.status >= 300 && response.status < 400 ? response.headers.get("Location") : null);
 			if (redirectLocation) throw new RedirectError(redirectLocation);
-			if (response.headers.get("X-Timber-Error") === "1") throw new ServerErrorResponse(response.status, url);
+			if (response.headers.get("X-Timber-Error") === "1" && response.status >= 500) throw new ServerErrorResponse(response.status, url);
 			headElements = extractHeadElements(response);
 			segmentInfo = extractSegmentInfo(response);
 			params = extractParams(response);
@@ -1162,7 +1191,7 @@ function createRouter(deps) {
 			restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
 		} catch (error) {
 			if (error instanceof VersionSkewError) {
-				const { triggerStaleReload } = await import("../_chunks/stale-reload-DKN3aXxR.js");
+				const { triggerStaleReload } = await import("../_chunks/stale-reload-BeyHXZ5B.js");
 				triggerStaleReload();
 				return new Promise(() => {});
 			}
@@ -1770,6 +1799,6 @@ function useCookie(name, defaultOptions) {
 //#region src/client/index.ts
 _registerUseCookieModule(use_cookie_exports);
 //#endregion
-export { HistoryStack, Link, LinkStatusContext, NavigationProvider, PrefetchCache, SegmentCache, SegmentProvider, TimberErrorBoundary, bindUseQueryStates, buildLinkProps, clearSsrData, createRouter, getNavigationState, getRouter, getSsrData, interpolateParams, mergePreservedSearchParams, resolveHref, setCurrentParams, setGlobalRouter, setNavigationState, setSsrData, useActionState, useCookie, useFormAction, useFormErrors, useLinkStatus, useNavigationPending, usePathname, useQueryStates, useRouter, useSearchParams, useSegmentContext, useSegmentParams, useSelectedLayoutSegment, useSelectedLayoutSegments, validateLinkHref };
+export { HistoryStack, Link, LinkStatusContext, NavigationProvider, PrefetchCache, SegmentCache, SegmentProvider, TimberErrorBoundary, bindUseQueryStates, buildLinkProps, clearSsrData, createRouter, getNavigationState, getRouter, getRouterOrNull, getSsrData, interpolateParams, mergePreservedSearchParams, resolveHref, setCurrentParams, setGlobalRouter, setNavigationState, setSsrData, useActionState, useCookie, useFormAction, useFormErrors, useLinkStatus, useNavigationPending, usePathname, useQueryStates, useRouter, useSearchParams, useSegmentContext, useSegmentParams, useSelectedLayoutSegment, useSelectedLayoutSegments, validateLinkHref };
 
 //# sourceMappingURL=index.js.map