@native-router/core 1.3.0 → 1.4.0

package/README.md

@@ -59,9 +59,10 @@ commit(router, entry.task, entry.location); // commit like a click
 - Route guards: static `redirect` and async `beforeLoad` on every route level, run shallow → deep; more than 10 chained redirects reject with `RedirectLoopError`
 - Cancelable async navigation: a new resolve supersedes the in-flight one (`currentGuard`); `cancel()` aborts it; a history POP cancels it too. A superseded or cancelled `navigate()` promise **never settles** — don't `await` a navigation that might be superseded
 - Navigation API: `navigate`, `refresh`, `go`/`forward`/`back`, `commit`/`commitReplace`, `createHref`, `getParams`, `match`, `toLocation`, `resolve`, `resolveTo`
+- Search validation via [Standard Schema](https://standardschema.dev): a `search` schema on any route level (zod/valibot/arktype, no hard dependency), parsed with `parseSearch`/`parseSearchSync`; failures throw `SearchError`
 - `preload(router, to, {ttl})`: resolve a target through the guards ahead of time, sharing one task across concurrent callers (in-flight dedup) with a TTL, default 30s; consumed entries are dropped on commit
 - `errorHandler` hook turns resolve failures into fallback views
-- Errors: `NativeRouterError`, `NotFoundError`, `RedirectLoopError`
+- Errors: `NativeRouterError`, `NotFoundError`, `RedirectLoopError`, `SearchError`
 - Tree-shakable: `sideEffects: false`
 
 ## Matching semantics
@@ -73,6 +74,30 @@ commit(router, entry.task, entry.location); // commit like a click
 - Matching is **case-sensitive**.
 - Params of nested levels are merged **deep over shallow** (`mergeMatchedParams`): for `/:id` + `/posts/:id`, the deeper `id` wins.
 
+## Search validation
+
+Declare a `search` validator on a route level and parse `location.search` with it in your `resolveView`. Any [Standard Schema](https://standardschema.dev) validator works — zod, valibot and arktype all implement the interface — so the core keeps zero extra runtime dependencies.
+
+```ts
+import {create, parseSearch} from '@native-router/core';
+import {z} from 'zod';
+
+const listSearch = z.object({page: z.coerce.number().default(1)});
+
+const router = create(
+  {path: '', children: [{path: '/list', search: listSearch}]},
+  createBrowserHistory(),
+  // Your resolveView consumes route.search itself: parse the location
+  // search, then resolve the view from the parsed output
+  async (matched, {location}) =>
+    renderList(await parseSearch(matched.at(-1)!.route.search!, location.search))
+);
+```
+
+- `parseSearchInput(search)` degrades a query string into a plain object — single-valued keys are strings, keys repeated in the query are arrays — which is also the input every schema validates
+- `parseSearch(schema, search)` resolves the schema output (async validators are awaited); `parseSearchSync` is the render/guard-time flavor and rejects async validators with a clear error
+- A rejected validation throws `SearchError` (a `NativeRouterError`) carrying the raw `search` and the reported `issues` — route it through your `errorHandler` like any other resolve failure
+
 ## Install
 
 ```bash

package/dist/index.cjs

@@ -18,6 +18,32 @@ class RedirectLoopError extends NativeRouterError {
   }
 }
 
+/**
+ * Thrown when a route {@link BaseRoute.search search schema} rejects the
+ * location search. Issues are formatted as `path: message` pairs joined
+ * with `; `, e.g.
+ * `Invalid search params "?page=abc": page: Expected a positive integer`.
+ */
+class SearchError extends NativeRouterError {
+  /** The raw search string that failed validation. */
+
+  /** The issues reported by the schema. */
+
+  constructor(search, issues) {
+    super(`Invalid search params "${search}": ${issues.map(({
+      message,
+      path
+    }) => `${formatIssuePath(path)}${message}`).join('; ')}`);
+    this.search = search;
+    this.issues = issues;
+  }
+}
+function formatIssuePath(path) {
+  if (!path?.length) return '';
+  const keys = path.map(segment => typeof segment === 'object' ? String(segment.key) : String(segment));
+  return `${keys.join('.')}: `;
+}
+
 const DEFAULT_MAX_STACK_DEPTH = 100;
 
 /** Max redirects followed by {@link resolveEntry} before giving up. */
@@ -753,9 +779,88 @@ function getParams(router) {
   return mergeMatchedParams(match(router, location.pathname) ?? []);
 }
 
+/**
+ * Parse a raw search string(e.g. `?page=2&tag=a&tag=b`) into the plain
+ * input object consumed by {@link StandardSchemaV1 search schemas}:
+ * single-valued keys are strings, keys repeated in the query string are
+ * arrays of their values. An empty search is `{}`.
+ *
+ * This is also the degraded shape every search API falls back to when no
+ * schema is given.
+ * @group Methods
+ * @category Route
+ * @param search the raw `location.search` string, with or without `?`
+ * @returns the input object for schema validation
+ */
+function parseSearchInput(search) {
+  const input = {};
+  // eslint-disable-next-line compat/compat -- URLSearchParams support is the app's polyfill concern, not bundled
+  new URLSearchParams(search).forEach((value, key) => {
+    const prev = input[key];
+    if (prev === undefined) {
+      input[key] = value;
+    } else if (Array.isArray(prev)) {
+      prev.push(value);
+    } else {
+      input[key] = [prev, value];
+    }
+  });
+  return input;
+}
+
+/**
+ * Validate a search string with a {@link StandardSchemaV1} schema — any
+ * zod/valibot/arktype schema works, no hard dependency. The string is
+ * first degraded via {@link parseSearchInput}, then parsed by the schema,
+ * so schemas can coerce(`'2'` → `2`) and normalize along the way.
+ *
+ * Async schemas(`validate` returning a promise) are awaited.
+ *
+ * @group Methods
+ * @category Route
+ * @param schema the search schema
+ * @param search the raw `location.search` string
+ * @returns the parsed(and possibly coerced) output of the schema
+ * @throws {SearchError} when the schema reports issues
+ */
+async function parseSearch(schema, search) {
+  const result = await schema['~standard'].validate(parseSearchInput(search));
+  if (result.issues) throw new SearchError(search, result.issues);
+  // The schema's declared output; the loose `StandardSchemaV1` default
+  // degrades to `unknown`.
+  return result.value;
+}
+
+/**
+ * Synchronous flavor of {@link parseSearch}, for render-time reads(see
+ * `useSearch` of `@native-router/react`) and route guards.
+ *
+ * @group Methods
+ * @category Route
+ * @param schema the search schema — must validate synchronously
+ * @param search the raw `location.search` string
+ * @returns the parsed(and possibly coerced) output of the schema
+ * @throws {SearchError} when the schema reports issues
+ * @throws when the schema validates asynchronously; use {@link parseSearch}
+ * for async schemas instead
+ */
+function parseSearchSync(schema, search) {
+  const result = schema['~standard'].validate(parseSearchInput(search));
+  if (isThenable(result)) {
+    throw new Error('The search schema validates asynchronously; parse it during resolve ' + '(parseSearch) instead of synchronously');
+  }
+  if (result.issues) throw new SearchError(search, result.issues);
+  // See parseSearch for the cast rationale.
+  return result.value;
+}
+function isThenable(value) {
+  return typeof value?.then === 'function';
+}
+
 exports.NativeRouterError = NativeRouterError;
 exports.NotFoundError = NotFoundError;
 exports.RedirectLoopError = RedirectLoopError;
+exports.SearchError = SearchError;
 exports.back = back;
 exports.cancel = cancel;
 exports.commit = commit;
@@ -772,6 +877,9 @@ exports.listen = listen;
 exports.match = match;
 exports.mergeMatchedParams = mergeMatchedParams;
 exports.navigate = navigate;
+exports.parseSearch = parseSearch;
+exports.parseSearchInput = parseSearchInput;
+exports.parseSearchSync = parseSearchSync;
 exports.preload = preload;
 exports.refresh = refresh;
 exports.resolve = resolve;

package/dist/index.mjs

@@ -16,6 +16,32 @@ class RedirectLoopError extends NativeRouterError {
   }
 }
 
+/**
+ * Thrown when a route {@link BaseRoute.search search schema} rejects the
+ * location search. Issues are formatted as `path: message` pairs joined
+ * with `; `, e.g.
+ * `Invalid search params "?page=abc": page: Expected a positive integer`.
+ */
+class SearchError extends NativeRouterError {
+  /** The raw search string that failed validation. */
+
+  /** The issues reported by the schema. */
+
+  constructor(search, issues) {
+    super(`Invalid search params "${search}": ${issues.map(({
+      message,
+      path
+    }) => `${formatIssuePath(path)}${message}`).join('; ')}`);
+    this.search = search;
+    this.issues = issues;
+  }
+}
+function formatIssuePath(path) {
+  if (!path?.length) return '';
+  const keys = path.map(segment => typeof segment === 'object' ? String(segment.key) : String(segment));
+  return `${keys.join('.')}: `;
+}
+
 const DEFAULT_MAX_STACK_DEPTH = 100;
 
 /** Max redirects followed by {@link resolveEntry} before giving up. */
@@ -751,4 +777,82 @@ function getParams(router) {
   return mergeMatchedParams(match(router, location.pathname) ?? []);
 }
 
-export { NativeRouterError, NotFoundError, RedirectLoopError, back, cancel, commit, commitReplace, create, createHref, forward, getCurrentView, getLocation, getParams, go, initHistoryStack, listen, match, mergeMatchedParams, navigate, preload, refresh, resolve, resolveEntry, resolveTo, setOptions, toLocation };
+/**
+ * Parse a raw search string(e.g. `?page=2&tag=a&tag=b`) into the plain
+ * input object consumed by {@link StandardSchemaV1 search schemas}:
+ * single-valued keys are strings, keys repeated in the query string are
+ * arrays of their values. An empty search is `{}`.
+ *
+ * This is also the degraded shape every search API falls back to when no
+ * schema is given.
+ * @group Methods
+ * @category Route
+ * @param search the raw `location.search` string, with or without `?`
+ * @returns the input object for schema validation
+ */
+function parseSearchInput(search) {
+  const input = {};
+  // eslint-disable-next-line compat/compat -- URLSearchParams support is the app's polyfill concern, not bundled
+  new URLSearchParams(search).forEach((value, key) => {
+    const prev = input[key];
+    if (prev === undefined) {
+      input[key] = value;
+    } else if (Array.isArray(prev)) {
+      prev.push(value);
+    } else {
+      input[key] = [prev, value];
+    }
+  });
+  return input;
+}
+
+/**
+ * Validate a search string with a {@link StandardSchemaV1} schema — any
+ * zod/valibot/arktype schema works, no hard dependency. The string is
+ * first degraded via {@link parseSearchInput}, then parsed by the schema,
+ * so schemas can coerce(`'2'` → `2`) and normalize along the way.
+ *
+ * Async schemas(`validate` returning a promise) are awaited.
+ *
+ * @group Methods
+ * @category Route
+ * @param schema the search schema
+ * @param search the raw `location.search` string
+ * @returns the parsed(and possibly coerced) output of the schema
+ * @throws {SearchError} when the schema reports issues
+ */
+async function parseSearch(schema, search) {
+  const result = await schema['~standard'].validate(parseSearchInput(search));
+  if (result.issues) throw new SearchError(search, result.issues);
+  // The schema's declared output; the loose `StandardSchemaV1` default
+  // degrades to `unknown`.
+  return result.value;
+}
+
+/**
+ * Synchronous flavor of {@link parseSearch}, for render-time reads(see
+ * `useSearch` of `@native-router/react`) and route guards.
+ *
+ * @group Methods
+ * @category Route
+ * @param schema the search schema — must validate synchronously
+ * @param search the raw `location.search` string
+ * @returns the parsed(and possibly coerced) output of the schema
+ * @throws {SearchError} when the schema reports issues
+ * @throws when the schema validates asynchronously; use {@link parseSearch}
+ * for async schemas instead
+ */
+function parseSearchSync(schema, search) {
+  const result = schema['~standard'].validate(parseSearchInput(search));
+  if (isThenable(result)) {
+    throw new Error('The search schema validates asynchronously; parse it during resolve ' + '(parseSearch) instead of synchronously');
+  }
+  if (result.issues) throw new SearchError(search, result.issues);
+  // See parseSearch for the cast rationale.
+  return result.value;
+}
+function isThenable(value) {
+  return typeof value?.then === 'function';
+}
+
+export { NativeRouterError, NotFoundError, RedirectLoopError, SearchError, back, cancel, commit, commitReplace, create, createHref, forward, getCurrentView, getLocation, getParams, go, initHistoryStack, listen, match, mergeMatchedParams, navigate, parseSearch, parseSearchInput, parseSearchSync, preload, refresh, resolve, resolveEntry, resolveTo, setOptions, toLocation };

package/dist/types/errors.d.ts

@@ -1,3 +1,4 @@
+import type { StandardSchemaV1 } from './types';
 export declare class NativeRouterError extends Error {
 }
 export declare class NotFoundError extends NativeRouterError {
@@ -6,3 +7,16 @@ export declare class NotFoundError extends NativeRouterError {
 export declare class RedirectLoopError extends NativeRouterError {
     constructor(target?: string);
 }
+/**
+ * Thrown when a route {@link BaseRoute.search search schema} rejects the
+ * location search. Issues are formatted as `path: message` pairs joined
+ * with `; `, e.g.
+ * `Invalid search params "?page=abc": page: Expected a positive integer`.
+ */
+export declare class SearchError extends NativeRouterError {
+    /** The raw search string that failed validation. */
+    readonly search: string;
+    /** The issues reported by the schema. */
+    readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
+    constructor(search: string, issues: ReadonlyArray<StandardSchemaV1.Issue>);
+}

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
 export * from './router';
 export * from './errors';
+export * from './search';
 export type * from './types';

package/dist/types/search.d.ts

@@ -0,0 +1,45 @@
+import type { SearchInput, SearchOutputOf, StandardSchemaV1 } from './types';
+/**
+ * Parse a raw search string(e.g. `?page=2&tag=a&tag=b`) into the plain
+ * input object consumed by {@link StandardSchemaV1 search schemas}:
+ * single-valued keys are strings, keys repeated in the query string are
+ * arrays of their values. An empty search is `{}`.
+ *
+ * This is also the degraded shape every search API falls back to when no
+ * schema is given.
+ * @group Methods
+ * @category Route
+ * @param search the raw `location.search` string, with or without `?`
+ * @returns the input object for schema validation
+ */
+export declare function parseSearchInput(search: string): SearchInput;
+/**
+ * Validate a search string with a {@link StandardSchemaV1} schema — any
+ * zod/valibot/arktype schema works, no hard dependency. The string is
+ * first degraded via {@link parseSearchInput}, then parsed by the schema,
+ * so schemas can coerce(`'2'` → `2`) and normalize along the way.
+ *
+ * Async schemas(`validate` returning a promise) are awaited.
+ *
+ * @group Methods
+ * @category Route
+ * @param schema the search schema
+ * @param search the raw `location.search` string
+ * @returns the parsed(and possibly coerced) output of the schema
+ * @throws {SearchError} when the schema reports issues
+ */
+export declare function parseSearch<S extends StandardSchemaV1>(schema: S, search: string): Promise<SearchOutputOf<S>>;
+/**
+ * Synchronous flavor of {@link parseSearch}, for render-time reads(see
+ * `useSearch` of `@native-router/react`) and route guards.
+ *
+ * @group Methods
+ * @category Route
+ * @param schema the search schema — must validate synchronously
+ * @param search the raw `location.search` string
+ * @returns the parsed(and possibly coerced) output of the schema
+ * @throws {SearchError} when the schema reports issues
+ * @throws when the schema validates asynchronously; use {@link parseSearch}
+ * for async schemas instead
+ */
+export declare function parseSearchSync<S extends StandardSchemaV1>(schema: S, search: string): SearchOutputOf<S>;

package/dist/types/types.d.ts

@@ -22,6 +22,63 @@ export type HistoryState = {
 };
 export type WrappedLocation = Location<HistoryState>;
 export type Awaitable<T> = T | Promise<T>;
+/**
+ * The [Standard Schema](https://standardschema.dev) interface, version 1 —
+ * the common validation interface implemented by zod, valibot and arktype.
+ *
+ * Inlined type-only from `@standard-schema/spec` so the core keeps zero
+ * extra runtime dependencies: any schema exposing `~standard` works.
+ * @group Types
+ * @category Route
+ */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+export declare namespace StandardSchemaV1 {
+    interface Props<Input = unknown, Output = Input> {
+        /** The version number of the standard. */
+        readonly version: 1;
+        /** The vendor name of the schema library. */
+        readonly vendor: string;
+        /** Validates unknown input values. */
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+    }
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    interface SuccessResult<Output> {
+        /** The typed output value. */
+        readonly value: Output;
+        /** The issues of the input value. */
+        readonly issues?: undefined;
+    }
+    interface FailureResult {
+        /** The issues of the input value. */
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    interface Issue {
+        /** The issue message. */
+        readonly message: string;
+        /** The issue path. */
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment>;
+    }
+    interface PathSegment {
+        /** The key of the path segment. */
+        readonly key: PropertyKey;
+    }
+}
+/**
+ * The plain input object a search string degrades into before schema
+ * validation: single-valued keys are strings, keys repeated in the query
+ * string are arrays of their values.
+ * @group Types
+ * @category Route
+ */
+export type SearchInput = Record<string, string | string[]>;
+/**
+ * Parsed output type of a {@link StandardSchemaV1 search schema}.
+ * @group Types
+ * @category Route
+ */
+export type SearchOutputOf<S> = S extends StandardSchemaV1<any, infer Output> ? Output : never;
 /**
  * Params contributed by a single path segment: `:name` is required,
  * `:name?` is optional, anything else(static or wildcard) contributes
@@ -70,6 +127,14 @@ export type BaseRoute<T = any> = {
      * redirected to the target path before the view resolves.
      */
     redirect?: string;
+    /**
+     * Optional Standard Schema(zod/valibot/arktype, ...) validator of the
+     * route search. Frameworks parse `location.search` with it at resolve
+     * time(see `parseSearch`) and inject the parsed output into their data
+     * contexts; a validation failure fails the resolve like any other
+     * navigation error.
+     */
+    search?: StandardSchemaV1;
     /**
      * Route guard invoked before the view resolves. Return a path string
      * to redirect, or nothing(`undefined`) to continue.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@native-router/core",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",