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

package/dist/_chunks/define-Dn98bPbb.js

@@ -0,0 +1,195 @@
+import { n as useQueryStates } from "./use-query-states-B-cLl8mx.js";
+import { i as isStandardSchema, n as fromSchema, r as isCodec } from "./schema-bridge-C3xl_vfb.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-Dn98bPbb.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define-Dn98bPbb.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/format-CYBGxKtc.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-CYBGxKtc.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"format-CYBGxKtc.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-B_df5Npe.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-B_df5Npe.js.map

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

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

package/dist/_chunks/logger-DDmK5skc.js

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