@native-router/core 1.7.0 → 1.9.0

package/README.md

@@ -108,10 +108,42 @@ const router = create(
 );
 ```
 
-- `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
+- `parseSearchInput(search)` degrades a query string into a plain object — single-valued keys are strings, keys repeated in the query string 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-time flavor and rejects async validators with a clear error
+- Guards: `beforeLoad` receives the level's parsed search as `ctx.search` — the schema output (parsed with `parseSearch`, so async validators work), or the degraded input on schema-less levels; an invalid search fails the resolution through the `errorHandler` channel like a data-phase search 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
 
+## Params validation
+
+Params are always strings (wildcards: string arrays) — the URL has no types. Declare a `params` schema on a route level and the core validates/coerces the merged params of that level before its `beforeLoad` runs, so guards see numbers instead of `Number(id)` everywhere.
+
+```ts
+import {create} from '@native-router/core';
+import {z} from 'zod';
+
+const router = create(
+  {
+    path: '',
+    children: [
+      {
+        path: '/users/:id',
+        params: z.object({id: z.coerce.number().int().positive()}),
+        beforeLoad: ({params}) => {
+          params.id; // number — coerced, or the navigation failed
+        }
+      }
+    ]
+  },
+  createBrowserHistory(),
+  (matched) => renderUser(matched)
+);
+```
+
+- No `params` schema → behavior unchanged: the raw string map flows through
+- The parse runs per level (shallow → deep): a level's schema validates the params merged up to it; a deeper schema sees the (possibly coerced) output of the shallower ones
+- A rejected validation fails the resolution through the `errorHandler` channel with a `ParamsError` (a `NativeRouterError`) carrying the raw `params` and the reported `issues` — the same route a search-schema failure takes
+- `parseParams`/`parseParamsSync` are exported for custom `resolveView` implementations (the async/sync flavors mirror `parseSearch`/`parseSearchSync`)
+
 ## Design principles
 
 **Navigation semantics follow the browser** — native-router aligns with browser-native navigation semantics, not with what other SPA routers happen to do. Every navigation API decision is measured against that yardstick; "a popular router has it" is not, by itself, a reason to follow. These are deliberate choices, not bugs to fix.

package/dist/index.cjs

@@ -39,12 +39,159 @@ class SearchError extends NativeRouterError {
     this.issues = issues;
   }
 }
+
+/**
+ * Thrown when a route {@link BaseRoute.params params schema} rejects the
+ * merged path params. Issues are formatted like {@link SearchError}'s —
+ * `path: message` pairs joined with `; `, e.g.
+ * `Invalid path params "/users/abc": id: expected a number`.
+ */
+class ParamsError extends NativeRouterError {
+  /** The raw params object that failed validation. */
+  params;
+
+  /** The issues reported by the schema. */
+  issues;
+  constructor(params, issues) {
+    super(`Invalid path params "${JSON.stringify(params)}": ${issues.map(({
+      message,
+      path
+    }) => `${formatIssuePath(path)}${message}`).join('; ')}`);
+    this.params = params;
+    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('.')}: `;
 }
 
+/**
+ * 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';
+}
+
+/**
+ * Validate the merged path params of a route level with a
+ * {@link StandardSchemaV1} schema — any zod/valibot/arktype schema
+ * works, no hard dependency. Params arrive as the plain string map the
+ * matcher extracted(see `mergeMatchedParams`), so schemas can coerce
+ * (`'7'` → `7`) and normalize along the way.
+ *
+ * Async schemas(`validate` returning a promise) are awaited.
+ *
+ * @group Methods
+ * @category Route
+ * @param schema the params schema
+ * @param params the merged raw params of the level
+ * @returns the parsed(and possibly coerced) output of the schema
+ * @throws {ParamsError} when the schema reports issues
+ */
+async function parseParams(schema, params) {
+  const result = await schema['~standard'].validate(params);
+  if (result.issues) throw new ParamsError(params, result.issues);
+  // The schema's declared output; the loose `StandardSchemaV1` default
+  // degrades to `unknown`.
+  return result.value;
+}
+
+/**
+ * Synchronous flavor of {@link parseParams}, for render-time reads and
+ * custom `resolveView` implementations.
+ *
+ * @group Methods
+ * @category Route
+ * @param schema the params schema — must validate synchronously
+ * @param params the merged raw params of the level
+ * @returns the parsed(and possibly coerced) output of the schema
+ * @throws {ParamsError} when the schema reports issues
+ * @throws when the schema validates asynchronously; use {@link parseParams}
+ * for async schemas instead
+ */
+function parseParamsSync(schema, params) {
+  const result = schema['~standard'].validate(params);
+  if (isThenable(result)) {
+    throw new Error('The params schema validates asynchronously; parse it during resolve ' + '(parseParams) instead of synchronously');
+  }
+  if (result.issues) throw new ParamsError(params, result.issues);
+  // See parseParams for the cast rationale.
+  return result.value;
+}
+
 const DEFAULT_MAX_STACK_DEPTH = 100;
 
 /** Max redirects followed by {@link resolveEntry} before giving up. */
@@ -327,6 +474,16 @@ function resolveTo(router, to, state) {
  * aborts — their resolution may be shared, so cancelling it on behalf of
  * one consumer is not sound yet.
  *
+ * A guard's context also carries the level's parsed
+ * {@link GuardContext.search search}: the {@link BaseRoute.search schema}
+ * output(its validation failure rejects this resolution with a
+ * `SearchError`), or the degraded input without a schema. Its
+ * {@link GuardContext.params params} are likewise the merged raw string
+ * map unless some level declares a {@link BaseRoute.params params
+ * schema} — the deepest schema seen so far has already upgraded them to
+ * its output(its validation failure rides the same channel with a
+ * `ParamsError`).
+ *
  * @group Methods
  * @category Router
  * @param router router instance
@@ -358,20 +515,67 @@ async function resolveEntry(router, location, opts) {
       };
     }
     let redirected = false;
+    // Raw params merged level-by-level; a level with a `params` schema
+    // upgrades them to the schema output before its guard runs, so
+    // guards of deeper levels see coerced params of the whole prefix.
+    let params = {};
     for (let i = 0; i < matched.length; i++) {
       const {
         route
       } = matched[i];
+      params = {
+        ...params,
+        ...matched[i].params
+      };
+      // The level's params schema runs before its guard, so the guard
+      // sees the coerced output. A validation failure fails the
+      // resolution through the task's errorHandler channel — the same
+      // route a search-schema failure takes — instead of rejecting this
+      // entry, which preload consumers share.
+      if (route.params) {
+        try {
+          // eslint-disable-next-line no-await-in-loop -- guards must run in declaration order, sequentially
+          params = await parseParams(route.params, params);
+        } catch (e) {
+          return {
+            location,
+            task: Promise.reject(e).catch(errorHandler)
+          };
+        }
+      }
       // `redirect` wins over `beforeLoad`; a non-empty string target
       // restarts the resolution at the redirected location.
-      const target = route.redirect ?? (
-      // eslint-disable-next-line no-await-in-loop -- guards must run in declaration order, sequentially
-      await route.beforeLoad?.({
-        router,
-        location,
-        params: mergeMatchedParams(matched, i),
-        signal
-      }));
+      let target = route.redirect;
+      if (!target && route.beforeLoad) {
+        // The level's search schema runs before its guard, so the guard
+        // sees the parsed output(degraded input without a schema). A
+        // validation failure fails the resolution through the task's
+        // errorHandler channel — the same route a data-phase search
+        // error takes — instead of rejecting this entry, which preload
+        // consumers share.
+        let search;
+        if (route.search) {
+          try {
+            // eslint-disable-next-line no-await-in-loop -- guards must run in declaration order, sequentially
+            search = await parseSearch(route.search, location.search);
+          } catch (e) {
+            return {
+              location,
+              task: Promise.reject(e).catch(errorHandler)
+            };
+          }
+        } else {
+          search = parseSearchInput(location.search);
+        }
+        // eslint-disable-next-line no-await-in-loop -- guards must run in declaration order, sequentially
+        target = await route.beforeLoad({
+          router,
+          location,
+          params,
+          signal,
+          search
+        });
+      }
       if (target) {
         location = toLocation(router, target, location.state);
         redirected = true;
@@ -1076,86 +1280,9 @@ 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.ParamsError = ParamsError;
 exports.RedirectLoopError = RedirectLoopError;
 exports.SearchError = SearchError;
 exports.back = back;
@@ -1175,6 +1302,8 @@ exports.listen = listen;
 exports.match = match;
 exports.mergeMatchedParams = mergeMatchedParams;
 exports.navigate = navigate;
+exports.parseParams = parseParams;
+exports.parseParamsSync = parseParamsSync;
 exports.parseSearch = parseSearch;
 exports.parseSearchInput = parseSearchInput;
 exports.parseSearchSync = parseSearchSync;

package/dist/index.mjs

@@ -37,12 +37,159 @@ class SearchError extends NativeRouterError {
     this.issues = issues;
   }
 }
+
+/**
+ * Thrown when a route {@link BaseRoute.params params schema} rejects the
+ * merged path params. Issues are formatted like {@link SearchError}'s —
+ * `path: message` pairs joined with `; `, e.g.
+ * `Invalid path params "/users/abc": id: expected a number`.
+ */
+class ParamsError extends NativeRouterError {
+  /** The raw params object that failed validation. */
+  params;
+
+  /** The issues reported by the schema. */
+  issues;
+  constructor(params, issues) {
+    super(`Invalid path params "${JSON.stringify(params)}": ${issues.map(({
+      message,
+      path
+    }) => `${formatIssuePath(path)}${message}`).join('; ')}`);
+    this.params = params;
+    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('.')}: `;
 }
 
+/**
+ * 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';
+}
+
+/**
+ * Validate the merged path params of a route level with a
+ * {@link StandardSchemaV1} schema — any zod/valibot/arktype schema
+ * works, no hard dependency. Params arrive as the plain string map the
+ * matcher extracted(see `mergeMatchedParams`), so schemas can coerce
+ * (`'7'` → `7`) and normalize along the way.
+ *
+ * Async schemas(`validate` returning a promise) are awaited.
+ *
+ * @group Methods
+ * @category Route
+ * @param schema the params schema
+ * @param params the merged raw params of the level
+ * @returns the parsed(and possibly coerced) output of the schema
+ * @throws {ParamsError} when the schema reports issues
+ */
+async function parseParams(schema, params) {
+  const result = await schema['~standard'].validate(params);
+  if (result.issues) throw new ParamsError(params, result.issues);
+  // The schema's declared output; the loose `StandardSchemaV1` default
+  // degrades to `unknown`.
+  return result.value;
+}
+
+/**
+ * Synchronous flavor of {@link parseParams}, for render-time reads and
+ * custom `resolveView` implementations.
+ *
+ * @group Methods
+ * @category Route
+ * @param schema the params schema — must validate synchronously
+ * @param params the merged raw params of the level
+ * @returns the parsed(and possibly coerced) output of the schema
+ * @throws {ParamsError} when the schema reports issues
+ * @throws when the schema validates asynchronously; use {@link parseParams}
+ * for async schemas instead
+ */
+function parseParamsSync(schema, params) {
+  const result = schema['~standard'].validate(params);
+  if (isThenable(result)) {
+    throw new Error('The params schema validates asynchronously; parse it during resolve ' + '(parseParams) instead of synchronously');
+  }
+  if (result.issues) throw new ParamsError(params, result.issues);
+  // See parseParams for the cast rationale.
+  return result.value;
+}
+
 const DEFAULT_MAX_STACK_DEPTH = 100;
 
 /** Max redirects followed by {@link resolveEntry} before giving up. */
@@ -325,6 +472,16 @@ function resolveTo(router, to, state) {
  * aborts — their resolution may be shared, so cancelling it on behalf of
  * one consumer is not sound yet.
  *
+ * A guard's context also carries the level's parsed
+ * {@link GuardContext.search search}: the {@link BaseRoute.search schema}
+ * output(its validation failure rejects this resolution with a
+ * `SearchError`), or the degraded input without a schema. Its
+ * {@link GuardContext.params params} are likewise the merged raw string
+ * map unless some level declares a {@link BaseRoute.params params
+ * schema} — the deepest schema seen so far has already upgraded them to
+ * its output(its validation failure rides the same channel with a
+ * `ParamsError`).
+ *
  * @group Methods
  * @category Router
  * @param router router instance
@@ -356,20 +513,67 @@ async function resolveEntry(router, location, opts) {
       };
     }
     let redirected = false;
+    // Raw params merged level-by-level; a level with a `params` schema
+    // upgrades them to the schema output before its guard runs, so
+    // guards of deeper levels see coerced params of the whole prefix.
+    let params = {};
     for (let i = 0; i < matched.length; i++) {
       const {
         route
       } = matched[i];
+      params = {
+        ...params,
+        ...matched[i].params
+      };
+      // The level's params schema runs before its guard, so the guard
+      // sees the coerced output. A validation failure fails the
+      // resolution through the task's errorHandler channel — the same
+      // route a search-schema failure takes — instead of rejecting this
+      // entry, which preload consumers share.
+      if (route.params) {
+        try {
+          // eslint-disable-next-line no-await-in-loop -- guards must run in declaration order, sequentially
+          params = await parseParams(route.params, params);
+        } catch (e) {
+          return {
+            location,
+            task: Promise.reject(e).catch(errorHandler)
+          };
+        }
+      }
       // `redirect` wins over `beforeLoad`; a non-empty string target
       // restarts the resolution at the redirected location.
-      const target = route.redirect ?? (
-      // eslint-disable-next-line no-await-in-loop -- guards must run in declaration order, sequentially
-      await route.beforeLoad?.({
-        router,
-        location,
-        params: mergeMatchedParams(matched, i),
-        signal
-      }));
+      let target = route.redirect;
+      if (!target && route.beforeLoad) {
+        // The level's search schema runs before its guard, so the guard
+        // sees the parsed output(degraded input without a schema). A
+        // validation failure fails the resolution through the task's
+        // errorHandler channel — the same route a data-phase search
+        // error takes — instead of rejecting this entry, which preload
+        // consumers share.
+        let search;
+        if (route.search) {
+          try {
+            // eslint-disable-next-line no-await-in-loop -- guards must run in declaration order, sequentially
+            search = await parseSearch(route.search, location.search);
+          } catch (e) {
+            return {
+              location,
+              task: Promise.reject(e).catch(errorHandler)
+            };
+          }
+        } else {
+          search = parseSearchInput(location.search);
+        }
+        // eslint-disable-next-line no-await-in-loop -- guards must run in declaration order, sequentially
+        target = await route.beforeLoad({
+          router,
+          location,
+          params,
+          signal,
+          search
+        });
+      }
       if (target) {
         location = toLocation(router, target, location.state);
         redirected = true;
@@ -1074,82 +1278,4 @@ 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';
-}
-
-export { NativeRouterError, NotFoundError, RedirectLoopError, SearchError, back, cancel, commit, commitReplace, create, createHref, forward, getCurrentView, getLocation, getParams, go, initHistoryStack, invalidate, listen, match, mergeMatchedParams, navigate, parseSearch, parseSearchInput, parseSearchSync, preload, refresh, resolve, resolveEntry, resolveTo, setBlocker, setOptions, toLocation };
+export { NativeRouterError, NotFoundError, ParamsError, RedirectLoopError, SearchError, back, cancel, commit, commitReplace, create, createHref, forward, getCurrentView, getLocation, getParams, go, initHistoryStack, invalidate, listen, match, mergeMatchedParams, navigate, parseParams, parseParamsSync, parseSearch, parseSearchInput, parseSearchSync, preload, refresh, resolve, resolveEntry, resolveTo, setBlocker, setOptions, toLocation };

package/dist/types/errors.d.ts

@@ -20,3 +20,16 @@ export declare class SearchError extends NativeRouterError {
     readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
     constructor(search: string, issues: ReadonlyArray<StandardSchemaV1.Issue>);
 }
+/**
+ * Thrown when a route {@link BaseRoute.params params schema} rejects the
+ * merged path params. Issues are formatted like {@link SearchError}'s —
+ * `path: message` pairs joined with `; `, e.g.
+ * `Invalid path params "/users/abc": id: expected a number`.
+ */
+export declare class ParamsError extends NativeRouterError {
+    /** The raw params object that failed validation. */
+    readonly params: Record<string, string>;
+    /** The issues reported by the schema. */
+    readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
+    constructor(params: Record<string, string>, issues: ReadonlyArray<StandardSchemaV1.Issue>);
+}

package/dist/types/router.d.ts

@@ -100,6 +100,16 @@ export declare function resolveTo<R extends BaseRoute = BaseRoute, V = any>(rout
  * aborts — their resolution may be shared, so cancelling it on behalf of
  * one consumer is not sound yet.
  *
+ * A guard's context also carries the level's parsed
+ * {@link GuardContext.search search}: the {@link BaseRoute.search schema}
+ * output(its validation failure rejects this resolution with a
+ * `SearchError`), or the degraded input without a schema. Its
+ * {@link GuardContext.params params} are likewise the merged raw string
+ * map unless some level declares a {@link BaseRoute.params params
+ * schema} — the deepest schema seen so far has already upgraded them to
+ * its output(its validation failure rides the same channel with a
+ * `ParamsError`).
+ *
  * @group Methods
  * @category Router
  * @param router router instance

package/dist/types/search.d.ts

@@ -43,3 +43,34 @@ export declare function parseSearch<S extends StandardSchemaV1>(schema: S, searc
  * for async schemas instead
  */
 export declare function parseSearchSync<S extends StandardSchemaV1>(schema: S, search: string): SearchOutputOf<S>;
+/**
+ * Validate the merged path params of a route level with a
+ * {@link StandardSchemaV1} schema — any zod/valibot/arktype schema
+ * works, no hard dependency. Params arrive as the plain string map the
+ * matcher extracted(see `mergeMatchedParams`), so schemas can coerce
+ * (`'7'` → `7`) and normalize along the way.
+ *
+ * Async schemas(`validate` returning a promise) are awaited.
+ *
+ * @group Methods
+ * @category Route
+ * @param schema the params schema
+ * @param params the merged raw params of the level
+ * @returns the parsed(and possibly coerced) output of the schema
+ * @throws {ParamsError} when the schema reports issues
+ */
+export declare function parseParams<S extends StandardSchemaV1>(schema: S, params: Record<string, string>): Promise<SearchOutputOf<S>>;
+/**
+ * Synchronous flavor of {@link parseParams}, for render-time reads and
+ * custom `resolveView` implementations.
+ *
+ * @group Methods
+ * @category Route
+ * @param schema the params schema — must validate synchronously
+ * @param params the merged raw params of the level
+ * @returns the parsed(and possibly coerced) output of the schema
+ * @throws {ParamsError} when the schema reports issues
+ * @throws when the schema validates asynchronously; use {@link parseParams}
+ * for async schemas instead
+ */
+export declare function parseParamsSync<S extends StandardSchemaV1>(schema: S, params: Record<string, string>): SearchOutputOf<S>;

package/dist/types/types.d.ts

@@ -143,10 +143,26 @@ export type ExtractPathParams<P extends string> = P extends `${infer Head}/${inf
  * `params` are accumulated from the root level down to the level that
  * owns the guard, so a guard only sees params of itself and its parents.
  */
-export type GuardContext<R extends BaseRoute = BaseRoute> = {
+export type GuardContext<R extends BaseRoute = BaseRoute, S = unknown> = {
     router: RouterInstance<R>;
     location: Location;
+    /**
+     * The merged params of this level and its parents: when any level
+     * declares a {@link BaseRoute.params params schema}, the merged raw
+     * params are parsed through the deepest matching schema before the
+     * guard runs; without schemas the raw string map the matcher
+     * extracted.
+     */
     params: Record<string, string>;
+    /**
+     * The search the guard sees: the route's {@link BaseRoute.search search
+     * schema} output(parsed and validated before the guard runs), or the
+     * degraded {@link SearchInput} when the route declares no schema. The
+     * loose default types it `unknown` — narrow it in the guard, or let a
+     * typed route table(see `createRoutes` of `@native-router/react`)
+     * derive it from the schema.
+     */
+    search: S;
     /**
      * Aborted when this navigation is superseded by a newer one or
      * cancelled(see {@link RouterInstance.cancelAll cancel}); pass it to
@@ -171,9 +187,25 @@ export type BaseRoute<T = any> = {
      * navigation error.
      */
     search?: StandardSchemaV1;
+    /**
+     * Optional Standard Schema validator of the merged path params this
+     * level and its parents contribute(see `mergeMatchedParams`). The core
+     * runs it in {@link resolveEntry} after matching and before the level's
+     * `beforeLoad`, so guards and loaders see coerced params(e.g. `:id`
+     * as a number) instead of raw strings; a validation failure fails the
+     * resolve like any other navigation error(via `ParamsError`).
+     *
+     * Omit it and the params stay the raw `Record<string, string>` the
+     * matcher extracted — behavior is unchanged.
+     */
+    params?: StandardSchemaV1;
     /**
      * Route guard invoked before the view resolves. Return a path string
-     * to redirect, or nothing(`undefined`) to continue.
+     * to redirect, or nothing(`undefined`) to continue. The guard's
+     * {@link GuardContext context} carries the level's parsed
+     * {@link GuardContext.search search}(schema output, or the degraded
+     * input without a schema); an invalid search fails the resolution at
+     * this phase like any other navigation error.
      */
     beforeLoad?(ctx: GuardContext<BaseRoute<T>>): Awaitable<string | void>;
 } & Omit<T, 'path' | 'children'>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@native-router/core",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
@@ -31,7 +31,7 @@
     "build": "rm -rf dist && rollup -c && tsc -p tsconfig.production.json && tsc-alias -p tsconfig.production.json",
     "commit": "lint-staged && git-cz -n",
     "coverage": "vitest run --coverage",
-    "lint": "eslint --fix src test *.js --ext .js,.jsx,.ts,.tsx",
+    "lint": "eslint --fix src test *.js",
     "doc:gen": "typedoc",
     "deploy": "npm run doc:gen && gh-pages -d dist",
     "test": "vitest run"
@@ -58,44 +58,46 @@
     "@babel/core": "^8.0.1",
     "@babel/preset-env": "^8.0.2",
     "@babel/preset-typescript": "^8.0.1",
+    "@eslint/eslintrc": "^3.3.6",
     "@rollup/plugin-babel": "^7.1.0",
     "@rollup/plugin-commonjs": "^29.0.3",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-replace": "^6.0.3",
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.4.0",
     "@types/sinon": "^22.0.0",
-    "@typescript-eslint/eslint-plugin": "^6.2.0",
-    "@typescript-eslint/parser": "^6.2.0",
+    "@typescript-eslint/eslint-plugin": "^8.68.0",
+    "@typescript-eslint/parser": "^8.68.0",
     "@vitest/coverage-v8": "^4.1.11",
     "commitizen": "^4.3.2",
     "core-js": "^3.50.0",
     "cross-env": "^10.1.0",
-    "eslint": "^8.50.0",
+    "eslint": "^10.9.1",
     "eslint-config-airbnb": "^19.0.4",
-    "eslint-config-airbnb-typescript": "^17.1.0",
-    "eslint-config-prettier": "^8.8.0",
-    "eslint-import-resolver-typescript": "^3.5.5",
-    "eslint-plugin-compat": "^4.1.4",
-    "eslint-plugin-import": "^2.27.5",
-    "eslint-plugin-jsx-a11y": "^6.7.1",
-    "eslint-plugin-prettier": "^5.0.0",
-    "eslint-plugin-react": "^7.33.0",
-    "eslint-plugin-react-hooks": "^4.6.0",
+    "eslint-config-airbnb-typescript": "^18.0.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-import-resolver-typescript": "^4.4.5",
+    "eslint-plugin-compat": "^7.0.2",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-jsx-a11y": "^6.10.2",
+    "eslint-plugin-prettier": "^5.5.6",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.1.1",
     "gh-pages": "^6.3.0",
+    "globals": "^17.11.0",
     "husky": "^9.1.7",
     "lint-staged": "^17.3.0",
     "prettier": "^3.9.6",
-    "rollup": "^4.62.5",
+    "rollup": "^4.63.0",
     "semantic-release": "^25.0.9",
     "should": "^13.2.3",
     "should-sinon": "0.0.6",
     "sinon": "^22.1.0",
-    "terser": "^5.50.0",
+    "terser": "^5.51.0",
     "tsc-alias": "^1.9.2",
     "typedoc": "^0.28.20",
     "typedoc-plugin-mark-react-functional-components": "^0.2.2",
     "typedoc-plugin-missing-exports": "^4.1.4",
-    "typescript": "~5.9.3",
+    "typescript": "~6.0.3",
     "vitest": "^4.1.11"
   }
 }