@timber-js/app 0.2.0-alpha.11 → 0.2.0-alpha.111

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

@@ -0,0 +1,195 @@
+import { n as useQueryStates } from "./use-query-states-D9SBlAfp.js";
+import { i as isStandardSchema, n as fromSchema, r as isCodec } from "./schema-bridge-eL5vQDSA.js";
+//#region src/search-params/define.ts
+/**
+* defineSearchParams — factory for SearchParamsDefinition<T>.
+*
+* Creates a typed, composable definition for a route's search parameters.
+* Accepts both SearchParamCodec values and Standard Schema objects (Zod,
+* Valibot, ArkType) with auto-detection. Supports URL key aliasing via
+* withUrlKey(), default-omission serialization, and composition via
+* .extend() / .pick().
+*
+* Design doc: design/23-search-params.md §"defineSearchParams — The Factory"
+*/
+var _getSearchParamsFn;
+/**
+* Register the getSearchParams function. Called once at module load time
+* from request-context.ts to avoid dynamic import at call time.
+* @internal
+*/
+function _setGetSearchParamsFn(fn) {
+	_getSearchParamsFn = fn;
+}
+function getSearchParamsFromAls() {
+	if (!_getSearchParamsFn) throw new Error("[timber] searchParams.get() is only available on the server. Use searchParams.useQueryStates() on the client.");
+	return _getSearchParamsFn();
+}
+/**
+* Convert URLSearchParams or a plain record to a normalized record
+* where repeated keys produce arrays.
+*/
+function normalizeRaw(raw) {
+	if (raw instanceof URLSearchParams) {
+		const result = {};
+		for (const key of new Set(raw.keys())) {
+			const values = raw.getAll(key);
+			result[key] = values.length === 1 ? values[0] : values;
+		}
+		return result;
+	}
+	return raw;
+}
+/**
+* Compute the serialized default value for a codec. Used for
+* default-omission: when serialize(value) === serialize(parse(undefined)),
+* the field is omitted from the URL.
+*/
+function getDefaultSerialized(codec) {
+	return codec.serialize(codec.parse(void 0));
+}
+/**
+* Resolve a field value to a SearchParamCodec. Auto-detects Standard Schema
+* objects and wraps them with fromSchema. Reads .urlKey from codecs.
+*/
+function resolveField(fieldName, value) {
+	if (isCodec(value)) return {
+		codec: value,
+		urlKey: value.urlKey
+	};
+	if (isStandardSchema(value)) return { codec: fromSchema(value) };
+	throw new Error(`[timber] defineSearchParams: 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 all codecs handle absent params (parse(undefined) doesn't throw).
+* Catches schemas that throw on missing input. `undefined` and `null` are both
+* valid defaults — `undefined` is correct for optional fields (e.g., `z.string().optional()`).
+*/
+function validateDefaults(codecMap) {
+	for (const [key, codec] of Object.entries(codecMap)) try {
+		codec.parse(void 0);
+	} catch {
+		throw new Error(`[timber] defineSearchParams: field '${key}' throws when the param is absent.\n  Search params are optional — the URL might not contain ?${key}=anything.\n  Add .default() or .optional() to your schema, or wrap with withDefault().`);
+	}
+}
+function defineSearchParams(codecsOrSchema) {
+	if (isStandardSchema(codecsOrSchema) && hasShape(codecsOrSchema)) {
+		const fieldCodecs = {};
+		for (const [key, fieldSchema] of Object.entries(codecsOrSchema.shape)) if (isStandardSchema(fieldSchema)) fieldCodecs[key] = fieldSchema;
+		else throw new Error(`[timber] defineSearchParams: field '${key}' in schema.shape is not a Standard Schema. All shape properties must be Standard Schema objects (Zod, Valibot, ArkType).`);
+		return defineSearchParamsFromMap(fieldCodecs);
+	}
+	return defineSearchParamsFromMap(codecsOrSchema);
+}
+/** Check if a schema has a .shape property with object-type values. */
+function hasShape(schema) {
+	return typeof schema === "object" && schema !== null && "shape" in schema && typeof schema.shape === "object" && schema.shape !== null;
+}
+function defineSearchParamsFromMap(codecs) {
+	const resolvedCodecs = {};
+	const urlKeys = {};
+	for (const [key, value] of Object.entries(codecs)) {
+		const resolved = resolveField(key, value);
+		resolvedCodecs[key] = resolved.codec;
+		if (resolved.urlKey) urlKeys[key] = resolved.urlKey;
+	}
+	validateDefaults(resolvedCodecs);
+	return buildDefinition(resolvedCodecs, urlKeys);
+}
+/**
+* Internal: build a SearchParamsDefinition from a typed codec map and url keys.
+*/
+function buildDefinition(codecMap, urlKeys) {
+	const defaultSerialized = {};
+	for (const key of Object.keys(codecMap)) defaultSerialized[key] = getDefaultSerialized(codecMap[key]);
+	function getUrlKey(prop) {
+		return urlKeys[prop] ?? prop;
+	}
+	function parseSync(raw) {
+		const normalized = normalizeRaw(raw);
+		const result = {};
+		for (const prop of Object.keys(codecMap)) {
+			const rawValue = normalized[getUrlKey(prop)];
+			result[prop] = codecMap[prop].parse(rawValue);
+		}
+		return result;
+	}
+	function parse(raw) {
+		if (raw instanceof Promise) return raw.then(parseSync);
+		return parseSync(raw);
+	}
+	function serialize(values) {
+		const parts = [];
+		for (const prop of Object.keys(codecMap)) {
+			if (!(prop in values)) continue;
+			const serialized = codecMap[prop].serialize(values[prop]);
+			if (serialized === defaultSerialized[prop]) continue;
+			if (serialized === null) continue;
+			parts.push(`${encodeURIComponent(getUrlKey(prop))}=${encodeURIComponent(serialized)}`);
+		}
+		return parts.join("&");
+	}
+	function href(pathname, values) {
+		const qs = serialize(values);
+		return qs ? `${pathname}?${qs}` : pathname;
+	}
+	function toSearchParams(values) {
+		const usp = new URLSearchParams();
+		for (const prop of Object.keys(codecMap)) {
+			if (!(prop in values)) continue;
+			const serialized = codecMap[prop].serialize(values[prop]);
+			if (serialized === defaultSerialized[prop]) continue;
+			if (serialized === null) continue;
+			usp.set(getUrlKey(prop), serialized);
+		}
+		return usp;
+	}
+	function extend(newCodecs) {
+		const resolvedNewCodecs = {};
+		const newUrlKeys = {};
+		for (const [key, value] of Object.entries(newCodecs)) {
+			const resolved = resolveField(key, value);
+			resolvedNewCodecs[key] = resolved.codec;
+			if (resolved.urlKey) newUrlKeys[key] = resolved.urlKey;
+		}
+		return buildDefinition({
+			...codecMap,
+			...resolvedNewCodecs
+		}, {
+			...urlKeys,
+			...newUrlKeys
+		});
+	}
+	function pick(...keys) {
+		const pickedCodecs = {};
+		const pickedUrlKeys = {};
+		for (const key of keys) {
+			pickedCodecs[key] = codecMap[key];
+			if (key in urlKeys) pickedUrlKeys[key] = urlKeys[key];
+		}
+		return buildDefinition(pickedCodecs, pickedUrlKeys);
+	}
+	function useQueryStates$1(options) {
+		return useQueryStates(codecMap, options, Object.freeze({ ...urlKeys }));
+	}
+	function get() {
+		if (typeof window !== "undefined") throw new Error("[timber] searchParams.get() is server-only. Use searchParams.useQueryStates() on the client.");
+		return parseSync(getSearchParamsFromAls());
+	}
+	return {
+		parse,
+		get,
+		useQueryStates: useQueryStates$1,
+		extend,
+		pick,
+		serialize,
+		href,
+		toSearchParams,
+		codecs: codecMap,
+		urlKeys: Object.freeze({ ...urlKeys })
+	};
+}
+//#endregion
+export { defineSearchParams as n, _setGetSearchParamsFn as t };
+
+//# sourceMappingURL=define-8zQ8Vm7x.js.map

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-a0CCE6Nx.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-BSt_O2cb.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-a0CCE6Nx.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define-a0CCE6Nx.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"}