@native-router/core 1.8.0 → 1.9.0

package/README.md

@@ -113,6 +113,37 @@ const router = create(
 - 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,6 +39,28 @@ 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));
@@ -123,6 +145,53 @@ 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. */
@@ -408,7 +477,12 @@ function resolveTo(router, to, state) {
  * 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.
+ * `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
@@ -441,10 +515,34 @@ 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.
       let target = route.redirect;
@@ -473,7 +571,7 @@ async function resolveEntry(router, location, opts) {
         target = await route.beforeLoad({
           router,
           location,
-          params: mergeMatchedParams(matched, i),
+          params,
           signal,
           search
         });
@@ -1184,6 +1282,7 @@ function getParams(router) {
 
 exports.NativeRouterError = NativeRouterError;
 exports.NotFoundError = NotFoundError;
+exports.ParamsError = ParamsError;
 exports.RedirectLoopError = RedirectLoopError;
 exports.SearchError = SearchError;
 exports.back = back;
@@ -1203,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,6 +37,28 @@ 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));
@@ -121,6 +143,53 @@ 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. */
@@ -406,7 +475,12 @@ function resolveTo(router, to, state) {
  * 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.
+ * `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
@@ -439,10 +513,34 @@ 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.
       let target = route.redirect;
@@ -471,7 +569,7 @@ async function resolveEntry(router, location, opts) {
         target = await route.beforeLoad({
           router,
           location,
-          params: mergeMatchedParams(matched, i),
+          params,
           signal,
           search
         });
@@ -1180,4 +1278,4 @@ function getParams(router) {
   return mergeMatchedParams(match(router, location.pathname) ?? []);
 }
 
-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

@@ -103,7 +103,12 @@ export declare function resolveTo<R extends BaseRoute = BaseRoute, V = any>(rout
  * 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.
+ * `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

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

@@ -146,6 +146,13 @@ export type ExtractPathParams<P extends string> = P extends `${infer Head}/${inf
 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
@@ -180,6 +187,18 @@ 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. The guard's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@native-router/core",
-  "version": "1.8.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"
   }
 }