@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.190

package/dist/search-params/index.js

@@ -1,13 +1,17 @@
-import { i as registerSearchParams, n as useQueryStates, r as getSearchParams } from "../_chunks/use-query-states-D5KaffOK.js";
-//#region src/search-params/create.ts
+import { r as getSearchParamsFromAls } from "../_chunks/als-slots-BEEIPKYm.js";
+import { i as isStandardSchema, n as fromSchema, r as isCodec } from "../_chunks/schema-bridge-C83xa9lT.js";
+import { i as parseTotal, n as useQueryStates, r as serializedEqual } from "../_chunks/use-query-states-I3JMng6J.js";
+//#region src/search-params/define.ts
 /**
-* createSearchParams — factory for SearchParamsDefinition<T>.
+* defineSearchParams — 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().
+* 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/09-typescript.md §"Typed searchParams — search-params.ts"
+* Design doc: design/23-search-params.md §"defineSearchParams — The Factory"
 */
 /**
 * Convert URLSearchParams or a plain record to a normalized record
@@ -15,7 +19,7 @@ import { i as registerSearchParams, n as useQueryStates, r as getSearchParams }
 */
 function normalizeRaw(raw) {
 	if (raw instanceof URLSearchParams) {
-		const result = {};
+		const result = Object.create(null);
 		for (const key of new Set(raw.keys())) {
 			const values = raw.getAll(key);
 			result[key] = values.length === 1 ? values[0] : values;
@@ -28,31 +32,81 @@ function normalizeRaw(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.
+*
+* Goes through `parseTotal` for the same reason request-time parsing does:
+* a nuqs parser's own `parse` throws on absent input, and this is the
+* absent case by construction.
+*
+* **A codec with no value for an absent param has no default to omit**,
+* and `null` is returned rather than `serialize(null)`. Serializing it
+* makes the "no value" case collide with a real one: `parseAsInteger`
+* serializes `null` as the string `'null'`, so `buildSearchParams({ q:
+* 'null' })` would silently drop a legitimate value (before TIM-1350 the
+* absent parse was `undefined` and the swallowed input was the string
+* `'undefined'` — same defect, a less likely input). Nothing is lost:
+* `buildSearchParams` already skips a field whose `serialize` returns
+* `null`, so a codec that encodes "no value" as an omission behaves
+* identically, and one that encodes it as a real query value now writes
+* it instead of dropping it.
+*
+* Codecs are documented to return a default rather than throw, but a
+* hand-written codec that throws on absent input must not turn definition
+* into a crash — treat its default as null (nothing to omit). `serialize`
+* is inside the try for the same reason.
+*
+* Typed `SearchParamCodec<unknown>` rather than generic on purpose: the
+* absent-input value is whatever the codec's total entry point returns,
+* which for a nuqs parser is `T | null` while its `serialize` declares
+* `T`. Widening to `unknown` states that honestly instead of casting.
 */
 function getDefaultSerialized(codec) {
-	return codec.serialize(codec.parse(void 0));
+	try {
+		const absent = parseTotal(codec, void 0);
+		return absent === null || absent === void 0 ? null : codec.serialize(absent);
+	} catch {
+		return null;
+	}
 }
 /**
-* 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'
+* Resolve a field value to a SearchParamCodec. Auto-detects Standard Schema
+* objects and wraps them with fromSchema. Reads .urlKey from codecs.
 *
-* export default createSearchParams({
-*   page: fromSchema(z.coerce.number().int().min(1).default(1)),
-*   q: { parse: (v) => v ?? null, serialize: (v) => v },
-* }, {
-*   urlKeys: { q: 'search' },
-* })
-* ```
+* The returned codec is typed as `SearchParamCodec<unknown>` because the
+* codec map uses that type. At runtime, the value may be a `Codec<T>` from
+* `fromSchema` (whose serialize returns `string | null`) or a nuqs parser
+* (whose serialize returns `string | string[] | null`). Both are safe
+* because `buildSearchParams` handles the union.
 */
-function createSearchParams(codecs, options) {
+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).`);
+}
+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 = {};
-	if (options?.urlKeys) {
-		for (const [k, v] of Object.entries(options.urlKeys)) if (v !== void 0) urlKeys[k] = v;
+	for (const [key, value] of Object.entries(codecs)) {
+		const resolved = resolveField(key, value);
+		resolvedCodecs[key] = resolved.codec;
+		if (resolved.urlKey) urlKeys[key] = resolved.urlKey;
 	}
-	return buildDefinition(codecs, urlKeys);
+	return buildDefinition(resolvedCodecs, urlKeys);
 }
 /**
 * Internal: build a SearchParamsDefinition from a typed codec map and url keys.
@@ -63,56 +117,64 @@ function buildDefinition(codecMap, urlKeys) {
 	function getUrlKey(prop) {
 		return urlKeys[prop] ?? prop;
 	}
-	function parse(raw) {
+	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);
+			result[prop] = parseTotal(codecMap[prop], rawValue);
 		}
 		return result;
 	}
-	function serialize(values) {
+	function parse(raw) {
+		if (raw instanceof Promise) return raw.then(parseSync);
+		return parseSync(raw);
+	}
+	function buildSearchParams(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;
+			const codec = codecMap[prop];
+			let serialized;
+			try {
+				serialized = codec.serialize(values[prop]);
+			} catch (error) {
+				if (error instanceof TypeError) continue;
+				throw error;
+			}
 			if (serialized === null) continue;
-			parts.push(`${encodeURIComponent(getUrlKey(prop))}=${encodeURIComponent(serialized)}`);
+			if (serializedEqual(serialized, defaultSerialized[prop])) continue;
+			const urlKey = encodeURIComponent(getUrlKey(prop));
+			if (Array.isArray(serialized)) for (const entry of serialized) parts.push(`${urlKey}=${encodeURIComponent(entry)}`);
+			else parts.push(`${urlKey}=${encodeURIComponent(serialized)}`);
 		}
 		return parts.join("&");
 	}
 	function href(pathname, values) {
-		const qs = serialize(values);
+		const qs = buildSearchParams(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);
+	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 usp;
-	}
-	function extend(newCodecs, extendOptions) {
-		const combinedCodecs = {
+		return buildDefinition({
 			...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);
+			...resolvedNewCodecs
+		}, {
+			...urlKeys,
+			...newUrlKeys
+		});
 	}
 	function pick(...keys) {
 		const pickedCodecs = {};
 		const pickedUrlKeys = {};
 		for (const key of keys) {
+			if (!(key in codecMap)) throw new Error(`[timber] pick('${key}'): unknown key. Available keys: ${Object.keys(codecMap).map((k) => `'${k}'`).join(", ")}.`);
 			pickedCodecs[key] = codecMap[key];
 			if (key in urlKeys) pickedUrlKeys[key] = urlKeys[key];
 		}
@@ -121,354 +183,111 @@ function buildDefinition(codecMap, urlKeys) {
 	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,
+		buildSearchParams,
 		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;
-	}
-};
+//#region src/search-params/wrappers.ts
 /**
-* 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.
+* Wrap a nullable codec with a default value. The output type becomes
+* non-nullable, and the wrapper is TOTAL over `string | string[] |
+* undefined` even when the inner codec is not.
 *
-* ```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.
+* The default is substituted for `null` — the documented "no value"
+* answer — and for `undefined`, which is what an implicitly-optional
+* Standard Schema field and a bare `parseAsString` produce for an absent
+* param. Substituting only for `null` left a field typed non-nullable
+* `string` holding `undefined` (TIM-1350).
 *
-* ```ts
-* import { parseAsStringLiteral } from '@timber-js/app/search-params'
+* The inner codec is invoked through `parseTotal`, so a nuqs parser gets
+* its own normalization (absent → null, repeated → first value, inner
+* throw → null) before either check applies. That is what makes
+* `withDefault(parseAsBoolean, false)` total; the wrapper itself does NOT
+* catch. A throw from a codec is a deliberate signal — `fromSchema` throws
+* on an async schema, and an app codec may `redirect()` or `notFound()` on
+* a value it refuses — and swallowing it would convert a loud failure into
+* a permanently-default field. design/09 §"The SearchParamCodec Protocol":
+* a codec that throws bubbles as a render-phase error, by design.
 *
-* 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.
+* Works with any codec — nuqs parsers, custom codecs, fromSchema results.
 *
 * ```ts
-* import { parseAsInteger, withDefault } from '@timber-js/app/search-params'
+* import { parseAsInteger } from 'nuqs'
+* import { withDefault } from '@timber-js/app/search-params'
 *
 * const page = withDefault(parseAsInteger, 1)
 * // page.parse(undefined) → 1 (not null)
 * // page.parse('5') → 5
 * ```
+*
+* The signature strips BOTH nullish constituents from the result, not just
+* `null`, because the runtime substitutes for both. An implicitly-optional
+* schema field is a `SearchParamCodec<string | undefined>`, and wrapping it
+* used to yield `SearchParamCodec<string | undefined>` — a field the
+* wrapper guarantees is always present, still typed as maybe-absent.
 */
 function withDefault(codec, defaultValue) {
-	return {
+	const wrapped = {
 		parse(value) {
-			const result = codec.parse(value);
-			return result === null ? defaultValue : result;
+			const result = parseTotal(codec, value);
+			return result === null || result === void 0 ? defaultValue : result;
 		},
 		serialize(value) {
 			return codec.serialize(value);
 		}
 	};
+	if (codec.urlKey !== void 0) wrapped.urlKey = codec.urlKey;
+	return wrapped;
 }
-//#endregion
-//#region src/search-params/analyze.ts
 /**
-* Patterns that indicate a valid default export:
+* Attach a URL key alias to a codec. The alias determines what query
+* parameter key is used in the URL, while the TypeScript property name
+* stays descriptive.
 *
-* 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(...)`
+* Aliases travel with codecs through object spread composition — when
+* you spread a bundle containing aliased codecs into defineSearchParams,
+* the aliases come along automatically.
 *
-* 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>`.
+* ```ts
+* import { parseAsString } from 'nuqs'
+* import { withUrlKey } from '@timber-js/app/search-params'
 *
-* 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.
+* export const searchable = {
+*   q: withUrlKey(parseAsString, 'search'),
+*   // ?search=shoes → { q: 'shoes' }
+* }
+* ```
 *
-* 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.
+* Composes with withDefault:
+* ```ts
+* import { parseAsInteger } from 'nuqs'
+* withUrlKey(withDefault(parseAsInteger, 1), 'p')
+* ```
 */
-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");
+function withUrlKey(codecOrSchema, urlKey) {
+	const codec = isCodec(codecOrSchema) ? codecOrSchema : isStandardSchema(codecOrSchema) ? fromSchema(codecOrSchema) : codecOrSchema;
+	const wrapped = {
+		parse: codec.parse.bind(codec),
+		serialize: codec.serialize.bind(codec),
+		urlKey
+	};
+	if (typeof codec.parseServerSide === "function") wrapped.parseServerSide = codec.parseServerSide.bind(codec);
+	return wrapped;
 }
 //#endregion
-export { analyzeSearchParams, createSearchParams, formatAnalyzeError, fromArraySchema, fromSchema, getSearchParams, parseAsBoolean, parseAsFloat, parseAsInteger, parseAsString, parseAsStringEnum, parseAsStringLiteral, registerSearchParams, withDefault };
+export { defineSearchParams, withDefault, withUrlKey };
 
 //# sourceMappingURL=index.js.map