@timber-js/app 0.2.0-alpha.4 → 0.2.0-alpha.40

package/dist/search-params/define.d.ts

@@ -0,0 +1,153 @@
+/**
+ * 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"
+ */
+import type { Codec } from '#/codec.js';
+/**
+ * A codec that converts between URL string values and typed values.
+ *
+ * nuqs parsers implement this interface natively — no adapter needed.
+ * Standard Schema objects (Zod, Valibot, ArkType) are auto-detected
+ * by defineSearchParams and wrapped via fromSchema.
+ */
+export interface SearchParamCodec<T> extends Codec<T> {
+    /** Optional URL key alias, set by withUrlKey(). */
+    urlKey?: string;
+}
+/** A codec with a URL key alias attached via withUrlKey(). */
+export interface SearchParamCodecWithUrlKey<T> extends SearchParamCodec<T> {
+    urlKey: string;
+}
+/** Infer the output type of a codec. */
+export type InferCodec<C> = C extends SearchParamCodec<infer T> ? T : never;
+/** Map of property names to codecs. */
+export type CodecMap<T extends Record<string, unknown>> = {
+    [K in keyof T]: SearchParamCodec<T[K]>;
+};
+/** Options for useQueryStates setter. */
+export interface SetParamsOptions {
+    /** Update URL without server roundtrip (default: false). */
+    shallow?: boolean;
+    /** Scroll to top after update (default: true). */
+    scroll?: boolean;
+    /** 'push' (default) or 'replace' for history state. */
+    history?: 'push' | 'replace';
+}
+/** Setter function returned by useQueryStates. */
+export type SetParams<T> = (values: Partial<T>, options?: SetParamsOptions) => void;
+/** Options for useQueryStates hook. */
+export interface QueryStatesOptions {
+    /** Update URL without server roundtrip (default: false). */
+    shallow?: boolean;
+    /** Scroll to top after update (default: true). */
+    scroll?: boolean;
+    /** 'push' (default) or 'replace' for history state. */
+    history?: 'push' | 'replace';
+}
+/**
+ * A fully typed, composable search params definition.
+ *
+ * Returned by defineSearchParams(). Carries a phantom _type property
+ * for build-time type extraction.
+ */
+export interface SearchParamsDefinition<T extends Record<string, unknown>> {
+    /** Parse raw URL search params into typed values. */
+    parse(raw: URLSearchParams | Record<string, string | string[] | undefined>): T;
+    /** Parse a Promise of URLSearchParams (e.g., from the ALS `searchParams()` API). */
+    parse(raw: Promise<URLSearchParams | Record<string, string | string[] | undefined>>): Promise<T>;
+    /**
+     * Load typed search params from the current request context (ALS-backed).
+     *
+     * Server-only — reads rawSearchParams() from ALS and parses through codecs.
+     * Throws on client. Eliminates the naming conflict between the definition
+     * export and the server helper.
+     *
+     * ```tsx
+     * // app/products/page.tsx
+     * import { searchParams } from './params'
+     * export default async function Page() {
+     *   const { page, category } = await searchParams.load()
+     * }
+     * ```
+     */
+    load(): Promise<T>;
+    /** Client hook — reads current URL params and returns typed values + setter. */
+    useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>];
+    /** Extend with additional codecs or Standard Schema objects. */
+    extend<U extends Record<string, SearchParamCodec<unknown> | StandardSchemaV1<unknown>>>(codecs: U): SearchParamsDefinition<T & {
+        [K in keyof U]: InferField<U[K]>;
+    }>;
+    /** Pick a subset of keys. Preserves codecs and aliases. */
+    pick<K extends keyof T & string>(...keys: K[]): SearchParamsDefinition<Pick<T, K>>;
+    /** Serialize values to a query string (no leading '?'), omitting defaults. */
+    serialize(values: Partial<T>): string;
+    /** Build a full path with query string, omitting defaults. */
+    href(pathname: string, values: Partial<T>): string;
+    /** Build a URLSearchParams instance, omitting defaults. */
+    toSearchParams(values: Partial<T>): URLSearchParams;
+    /** Read-only codec map for spreading into .extend(). */
+    codecs: {
+        [K in keyof T]: SearchParamCodec<T[K]>;
+    };
+    /** Read-only URL key alias map. Maps property names to URL query parameter keys. */
+    readonly urlKeys: Readonly<Record<string, string>>;
+    /**
+     * Phantom property for build-time type extraction.
+     * Never set at runtime — exists only in the type system.
+     */
+    readonly _type?: T;
+}
+/** Minimal Standard Schema interface for auto-detection. */
+export interface StandardSchemaV1<Output = unknown> {
+    '~standard': {
+        validate(value: unknown): {
+            value: Output;
+            issues?: undefined;
+        } | {
+            value?: undefined;
+            issues: ReadonlyArray<{
+                message: string;
+            }>;
+        } | Promise<{
+            value: Output;
+            issues?: undefined;
+        } | {
+            value?: undefined;
+            issues: ReadonlyArray<{
+                message: string;
+            }>;
+        }>;
+    };
+}
+/** Infer the output type from either a SearchParamCodec or a StandardSchemaV1. */
+export type InferField<V> = V extends SearchParamCodec<infer T> ? T : V extends StandardSchemaV1<infer T> ? T : never;
+/** Acceptable field value for defineSearchParams: a codec or a Standard Schema. */
+export type SearchParamField<T = unknown> = SearchParamCodec<T> | StandardSchemaV1<T>;
+/**
+ * Create a SearchParamsDefinition from a map of codecs and/or Standard Schema
+ * objects. Accepts both SearchParamCodec values and raw Zod/Valibot/ArkType
+ * schemas with auto-detection.
+ *
+ * ```ts
+ * import { defineSearchParams, withDefault, withUrlKey } from '@timber-js/app/search-params'
+ * import { parseAsString, parseAsStringEnum } from 'nuqs'
+ * import { z } from 'zod/v4'
+ *
+ * export const searchParams = defineSearchParams({
+ *   page: z.coerce.number().int().min(1).default(1),     // Standard Schema — auto-wrapped
+ *   q: withUrlKey(parseAsString, 'search'),                // nuqs codec with URL alias
+ *   sort: withDefault(parseAsStringEnum(['price', 'name']), 'price'),
+ * })
+ * ```
+ */
+export declare function defineSearchParams<C extends Record<string, SearchParamField>>(codecs: C): SearchParamsDefinition<{
+    [K in keyof C]: InferField<C[K]>;
+}>;
+//# sourceMappingURL=define.d.ts.map

package/dist/search-params/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/search-params/define.ts"],"names":[],"mappings":"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"}

package/dist/search-params/index.d.ts

@@ -1,8 +1,7 @@
-export type { SearchParamCodec, InferCodec, SearchParamsDefinition, SetParams, SetParamsOptions, QueryStatesOptions, SearchParamsOptions, } from './create.js';
-export { createSearchParams } from './create.js';
+export type { Codec } from '#/codec.js';
+export type { SearchParamCodec, SearchParamCodecWithUrlKey, InferCodec, InferField, CodecMap, SearchParamsDefinition, SetParams, SetParamsOptions, QueryStatesOptions, StandardSchemaV1, } from './define.js';
+export { defineSearchParams } from './define.js';
 export { fromSchema, fromArraySchema } from './codecs.js';
-export { parseAsString, parseAsInteger, parseAsFloat, parseAsBoolean, parseAsStringEnum, parseAsStringLiteral, withDefault, } from './builtin-codecs.js';
+export { withDefault, withUrlKey } from './wrappers.js';
 export { registerSearchParams, getSearchParams } from './registry.js';
-export type { AnalyzeResult, AnalyzeError } from './analyze.js';
-export { analyzeSearchParams, formatAnalyzeError } from './analyze.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/search-params/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/search-params/index.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,gBAAgB,EAChB,UAAU,EACV,sBAAsB,EACtB,SAAS,EACT,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG1D,OAAO,EACL,aAAa,EACb,cAAc,EACd,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGtE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/search-params/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC,YAAY,EACV,gBAAgB,EAChB,0BAA0B,EAC1B,UAAU,EACV,UAAU,EACV,QAAQ,EACR,sBAAsB,EACtB,SAAS,EACT,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG1D,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGxD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/dist/search-params/index.js

@@ -1,474 +1,3 @@
-import { i as registerSearchParams, n as useQueryStates, r as getSearchParams } from "../_chunks/use-query-states-D5KaffOK.js";
-//#region src/search-params/create.ts
-/**
-* createSearchParams — factory for SearchParamsDefinition<T>.
-*
-* Creates a typed, composable definition for a route's search parameters.
-* Supports codec protocol, URL key aliasing, default-omission serialization,
-* and composition via .extend() / .pick().
-*
-* Design doc: design/09-typescript.md §"Typed searchParams — search-params.ts"
-*/
-/**
-* 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));
-}
-/**
-* Create a SearchParamsDefinition from a codec map and optional URL key aliases.
-*
-* ```ts
-* import { createSearchParams, fromSchema } from '@timber-js/app/search-params'
-* import { z } from 'zod/v4'
-*
-* export default createSearchParams({
-*   page: fromSchema(z.coerce.number().int().min(1).default(1)),
-*   q: { parse: (v) => v ?? null, serialize: (v) => v },
-* }, {
-*   urlKeys: { q: 'search' },
-* })
-* ```
-*/
-function createSearchParams(codecs, options) {
-	const urlKeys = {};
-	if (options?.urlKeys) {
-		for (const [k, v] of Object.entries(options.urlKeys)) if (v !== void 0) urlKeys[k] = v;
-	}
-	return buildDefinition(codecs, 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 parse(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 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, extendOptions) {
-		const combinedCodecs = {
-			...codecMap,
-			...newCodecs
-		};
-		const combinedUrlKeys = { ...urlKeys };
-		if (extendOptions?.urlKeys) {
-			for (const [k, v] of Object.entries(extendOptions.urlKeys)) if (v !== void 0) combinedUrlKeys[k] = v;
-		}
-		return buildDefinition(combinedCodecs, combinedUrlKeys);
-	}
-	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 }));
-	}
-	return {
-		parse,
-		useQueryStates: useQueryStates$1,
-		extend,
-		pick,
-		serialize,
-		href,
-		toSearchParams,
-		codecs: codecMap,
-		urlKeys: Object.freeze({ ...urlKeys })
-	};
-}
-//#endregion
-//#region src/search-params/codecs.ts
-/**
-* Zod v4's ~standard.validate() signature includes Promise in the return union
-* to satisfy the Standard Schema spec, but in practice Zod always validates
-* synchronously for the schema types we use. We assert the result is sync and
-* throw if it isn't — search params parsing must be synchronous.
-*/
-function validateSync(schema, value) {
-	const result = schema["~standard"].validate(value);
-	if (result instanceof Promise) throw new Error("[timber] fromSchema: schema returned a Promise — only sync schemas are supported for search params.");
-	return result;
-}
-/**
-* Bridge a Standard Schema-compatible schema (Zod, Valibot, ArkType) to a
-* SearchParamCodec.
-*
-* Parse: coerces the raw URL string through the schema. On validation failure,
-* parses `undefined` to get the schema's default value (the schema should have
-* a `.default()` call). If that also fails, returns `undefined`.
-*
-* Serialize: uses `String()` for primitives, `null` for null/undefined.
-*
-* ```ts
-* import { fromSchema } from '@timber-js/app/search-params'
-* import { z } from 'zod/v4'
-*
-* const pageCodec = fromSchema(z.coerce.number().int().min(1).default(1))
-* ```
-*/
-function fromSchema(schema) {
-	return {
-		parse(value) {
-			const result = validateSync(schema, Array.isArray(value) ? value[value.length - 1] : value);
-			if (!result.issues) return result.value;
-			const defaultResult = validateSync(schema, void 0);
-			if (!defaultResult.issues) return defaultResult.value;
-		},
-		serialize(value) {
-			if (value === null || value === void 0) return null;
-			return String(value);
-		}
-	};
-}
-/**
-* Bridge a Standard Schema for array values. Handles both single strings
-* and repeated query keys (`?tag=a&tag=b`).
-*
-* ```ts
-* import { fromArraySchema } from '@timber-js/app/search-params'
-* import { z } from 'zod/v4'
-*
-* const tagsCodec = fromArraySchema(z.array(z.string()).default([]))
-* ```
-*/
-function fromArraySchema(schema) {
-	return {
-		parse(value) {
-			let input = value;
-			if (typeof value === "string") input = [value];
-			else if (value === void 0) input = void 0;
-			const result = validateSync(schema, input);
-			if (!result.issues) return result.value;
-			const defaultResult = validateSync(schema, void 0);
-			if (!defaultResult.issues) return defaultResult.value;
-		},
-		serialize(value) {
-			if (value === null || value === void 0) return null;
-			if (Array.isArray(value)) return value.length === 0 ? null : value.join(",");
-			return String(value);
-		}
-	};
-}
-//#endregion
-//#region src/search-params/builtin-codecs.ts
-/**
-* Normalize array inputs to a single string (last value wins, matching
-* URLSearchParams.get() semantics). Returns undefined if absent or empty.
-*/
-function normalizeInput(value) {
-	if (Array.isArray(value)) return value.length > 0 ? value[value.length - 1] : void 0;
-	return value;
-}
-/**
-* String codec. Returns the raw string value, or null if absent.
-*
-* ```ts
-* import { parseAsString } from '@timber-js/app/search-params'
-*
-* const def = createSearchParams({ q: parseAsString })
-* // ?q=shoes → { q: 'shoes' }
-* // (absent) → { q: null }
-* ```
-*/
-var parseAsString = {
-	parse(value) {
-		const v = normalizeInput(value);
-		return v !== void 0 ? v : null;
-	},
-	serialize(value) {
-		return value;
-	}
-};
-/**
-* Integer codec. Parses a base-10 integer, or returns null if absent or
-* not a valid integer. Rejects floats, NaN, Infinity, and non-numeric strings.
-*
-* ```ts
-* import { parseAsInteger, withDefault } from '@timber-js/app/search-params'
-*
-* const def = createSearchParams({ page: withDefault(parseAsInteger, 1) })
-* // ?page=2 → { page: 2 }
-* // ?page=abc → { page: 1 }
-* // (absent) → { page: 1 }
-* ```
-*/
-var parseAsInteger = {
-	parse(value) {
-		const v = normalizeInput(value);
-		if (v === void 0 || v === "") return null;
-		const n = Number(v);
-		if (!Number.isFinite(n) || !Number.isInteger(n)) return null;
-		return n;
-	},
-	serialize(value) {
-		return value === null ? null : String(value);
-	}
-};
-/**
-* Float codec. Parses a finite number, or returns null if absent or invalid.
-* Rejects NaN and Infinity.
-*
-* ```ts
-* import { parseAsFloat, withDefault } from '@timber-js/app/search-params'
-*
-* const def = createSearchParams({ price: withDefault(parseAsFloat, 0) })
-* ```
-*/
-var parseAsFloat = {
-	parse(value) {
-		const v = normalizeInput(value);
-		if (v === void 0 || v === "") return null;
-		const n = Number(v);
-		if (!Number.isFinite(n)) return null;
-		return n;
-	},
-	serialize(value) {
-		return value === null ? null : String(value);
-	}
-};
-/**
-* Boolean codec. Accepts "true"/"1" as true, "false"/"0" as false.
-* Returns null for absent or unrecognized values.
-*
-* ```ts
-* import { parseAsBoolean, withDefault } from '@timber-js/app/search-params'
-*
-* const def = createSearchParams({ debug: withDefault(parseAsBoolean, false) })
-* // ?debug=true → { debug: true }
-* // ?debug=0 → { debug: false }
-* ```
-*/
-var parseAsBoolean = {
-	parse(value) {
-		const v = normalizeInput(value);
-		if (v === void 0) return null;
-		if (v === "true" || v === "1") return true;
-		if (v === "false" || v === "0") return false;
-		return null;
-	},
-	serialize(value) {
-		return value === null ? null : String(value);
-	}
-};
-/**
-* String enum codec. Accepts only values in the provided list.
-* Returns null for absent or invalid values.
-*
-* ```ts
-* import { parseAsStringEnum, withDefault } from '@timber-js/app/search-params'
-*
-* const sortCodec = withDefault(
-*   parseAsStringEnum(['price', 'name', 'date']),
-*   'date'
-* )
-* ```
-*/
-function parseAsStringEnum(values) {
-	const allowed = new Set(values);
-	return {
-		parse(value) {
-			const v = normalizeInput(value);
-			if (v === void 0) return null;
-			return allowed.has(v) ? v : null;
-		},
-		serialize(value) {
-			return value;
-		}
-	};
-}
-/**
-* String literal codec. Functionally identical to parseAsStringEnum but
-* accepts `as const` tuples for narrower type inference.
-*
-* ```ts
-* import { parseAsStringLiteral } from '@timber-js/app/search-params'
-*
-* const sizes = ['sm', 'md', 'lg', 'xl'] as const
-* const codec = parseAsStringLiteral(sizes)
-* // Type: SearchParamCodec<'sm' | 'md' | 'lg' | 'xl' | null>
-* ```
-*/
-function parseAsStringLiteral(values) {
-	return parseAsStringEnum(values);
-}
-/**
-* Wrap a nullable codec with a default value. When the inner codec returns
-* null, the default is used instead. The output type becomes non-nullable.
-*
-* ```ts
-* import { parseAsInteger, withDefault } from '@timber-js/app/search-params'
-*
-* const page = withDefault(parseAsInteger, 1)
-* // page.parse(undefined) → 1 (not null)
-* // page.parse('5') → 5
-* ```
-*/
-function withDefault(codec, defaultValue) {
-	return {
-		parse(value) {
-			const result = codec.parse(value);
-			return result === null ? defaultValue : result;
-		},
-		serialize(value) {
-			return codec.serialize(value);
-		}
-	};
-}
-//#endregion
-//#region src/search-params/analyze.ts
-/**
-* Patterns that indicate a valid default export:
-*
-* 1. `export default createSearchParams(...)`
-* 2. `export default someVar.extend(...)`
-* 3. `export default someVar.pick(...)`
-* 4. `export default someVar.extend(...).extend(...)`  (chained)
-* 5. `export default someVar.extend(...).pick(...)`    (chained)
-* 6. `export default createSearchParams(...).extend(...)`
-*
-* Invalid patterns:
-* - `export default someFunction(...)` (arbitrary factory)
-* - `export default condition ? a : b` (runtime conditional)
-* - `export default variable` (opaque reference without call)
-*/
-/**
-* Analyze a search-params.ts file source for static analyzability.
-*
-* @param source - The file content as a string
-* @param filePath - Absolute path to the file (for diagnostics)
-*/
-function analyzeSearchParams(source, filePath) {
-	const defaultExport = extractDefaultExport(stripComments(source));
-	if (!defaultExport) return {
-		valid: false,
-		error: {
-			filePath,
-			expression: "(no default export found)",
-			suggestion: "search-params.ts must have a default export. Use: export default createSearchParams({ ... })"
-		}
-	};
-	if (isValidExpression(defaultExport.trim())) return { valid: true };
-	return {
-		valid: false,
-		error: {
-			filePath,
-			expression: defaultExport.trim(),
-			suggestion: "The default export must be a createSearchParams() call, or a chain of .extend() / .pick() calls on a SearchParamsDefinition. Arbitrary factory functions and runtime conditionals are not supported."
-		}
-	};
-}
-/** Strip single-line and multi-line comments from source. */
-function stripComments(source) {
-	let result = source.replace(/\/\*[\s\S]*?\*\//g, "");
-	result = result.replace(/\/\/.*$/gm, "");
-	return result;
-}
-/**
-* Extract the expression from `export default <expr>`.
-*
-* Handles both:
-*   export default createSearchParams(...)
-*   export default expr\n (terminated by newline or semicolon before next statement)
-*/
-function extractDefaultExport(source) {
-	const match = source.match(/export\s+default\s+([\s\S]+?)(?:;|\n(?=export|import|const|let|var|function|class|type|interface|declare))/);
-	if (match) return match[1];
-	const fallback = source.match(/export\s+default\s+([\s\S]+)$/);
-	if (fallback) return fallback[1].replace(/;\s*$/, "");
-}
-/**
-* Check if an expression is a valid statically-analyzable pattern.
-*
-* Valid patterns:
-* - Starts with `createSearchParams(`
-* - Contains `.extend(` or `.pick(` chains (possibly starting with createSearchParams or a variable)
-* - A variable identifier followed by chaining
-*/
-function isValidExpression(expr) {
-	const normalized = expr.replace(/\s+/g, " ").trim();
-	if (normalized.startsWith("createSearchParams(")) return true;
-	if (/\.(extend|pick)\s*\(/.test(normalized)) {
-		if (/\?/.test(normalized) && /:/.test(normalized)) return false;
-		if (/^\s*(function|=>|\()/.test(normalized)) return false;
-		return true;
-	}
-	return false;
-}
-/**
-* Format an AnalyzeError into a human-readable build error message.
-*/
-function formatAnalyzeError(error) {
-	return [
-		`[timber] Non-analyzable search-params.ts`,
-		``,
-		`  File: ${error.filePath}`,
-		`  Expression: ${error.expression}`,
-		``,
-		`  ${error.suggestion}`,
-		``,
-		`  The framework must be able to statically extract the type from your`,
-		`  search-params.ts at build time. Dynamic values, conditionals, and`,
-		`  arbitrary factory functions prevent this analysis.`
-	].join("\n");
-}
-//#endregion
-export { analyzeSearchParams, createSearchParams, formatAnalyzeError, fromArraySchema, fromSchema, getSearchParams, parseAsBoolean, parseAsFloat, parseAsInteger, parseAsString, parseAsStringEnum, parseAsStringLiteral, registerSearchParams, withDefault };
-
-//# sourceMappingURL=index.js.map
+import { i as registerSearchParams, r as getSearchParams } from "../_chunks/use-query-states-BvW0TKDn.js";
+import { a as fromSchema, i as fromArraySchema, n as withUrlKey, r as defineSearchParams, t as withDefault } from "../_chunks/wrappers-C6J0nNji.js";
+export { defineSearchParams, fromArraySchema, fromSchema, getSearchParams, registerSearchParams, withDefault, withUrlKey };

package/dist/search-params/registry.d.ts

@@ -6,7 +6,7 @@
  *
  * Design doc: design/23-search-params.md §"Runtime: Registration at Route Load"
  */
-import type { SearchParamsDefinition } from './create.js';
+import type { SearchParamsDefinition } from './define.js';
 /**
  * Register a route's search params definition.
  * Called by the generated route manifest loader when a route's modules load.