@native-router/core 1.4.0 → 1.5.0

package/README.md

@@ -57,7 +57,7 @@ commit(router, entry.task, entry.location); // commit like a click
 - Framework-agnostic: bring your own `resolveView`, the view type (`V`) is yours — a string, a vdom, anything
 - Route matching via path-to-regexp: declaration order, layout routes without `path`, index/fallback children with `path: ''`, strict trailing slashes, case-sensitive, nested params merged deep over shallow
 - 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
+- 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. Superseding or cancelling also aborts the chain's `AbortSignal`: guards (`beforeLoad` ctx) and view loaders (`ResolveViewContext`) receive it as `ctx.signal`, so their in-flight requests stop instead of only having results dropped; `preload` resolutions are shared and therefore never aborted
 - 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

package/dist/index.cjs

@@ -26,9 +26,10 @@ class RedirectLoopError extends NativeRouterError {
  */
 class SearchError extends NativeRouterError {
   /** The raw search string that failed validation. */
+  search;
 
   /** The issues reported by the schema. */
-
+  issues;
   constructor(search, issues) {
     super(`Invalid search params "${search}": ${issues.map(({
       message,
@@ -74,6 +75,10 @@ const DEFAULT_PRELOAD_TTL = 30_000;
  *   `history index - baseIndex`; entries whose slot falls outside the
  *   memory window re-resolve lazily when landed on.
  * - `preloadCache`: router-level cache of {@link preload} results.
+ * - `resolvingController`: the in-flight chain's AbortController. It is
+ *   aborted(supersede/cancel) only while the chain is in flight; a
+ *   settled chain's controller is left alone so its contexts never
+ *   report `aborted` for a navigation that actually committed.
  */
 
 /**
@@ -210,7 +215,7 @@ function match(router, pathname) {
       const route = routes[i];
       const end = !route.children;
       const matched = route.path ? pathToRegexp.match(route.path, {
-        strict: true,
+        trailing: false,
         sensitive: true,
         decode: typeof decodeURIComponent === 'function' ? decodeURIComponent : undefined,
         end
@@ -273,7 +278,10 @@ function resolve(router, location) {
   } = router;
   return (matched ? resolveView(matched, {
     router,
-    location
+    location,
+    // One-shot resolves(warm-up, direct calls) are never superseded
+    // or cancelled: their loaders get a signal that never aborts.
+    signal: new AbortController().signal
   }) : Promise.reject(new NotFoundError(location.pathname))).catch(errorHandler);
 }
 
@@ -300,22 +308,37 @@ function resolveTo(router, to, state) {
  * levels re-run on every hop(keep side-effectful guards idempotent) —
  * carrying the original user state; at most
  * {@link MAX_REDIRECTS 10} redirects are followed before a
- * {@link RedirectLoopError} is thrown. An unmatched pathname keeps the
+ * An unmatched pathname keeps the
  * {@link resolve resolve} behavior: the task rejects with a
  * {@link NotFoundError} and is routed through `router.errorHandler`.
  *
+ * `opts.signal` is the abort signal of the whole chain: guards see it in
+ * their {@link GuardContext contexts}, the view task's
+ * {@link ResolveViewContext context} carries it on, and it is aborted
+ * once the navigation is superseded or cancelled. Standalone callers
+ * that pass nothing(e.g. {@link preload}) get a signal that never
+ * aborts — their resolution may be shared, so cancelling it on behalf of
+ * one consumer is not sound yet.
+ *
  * @group Methods
  * @category Router
  * @param router router instance
  * @param location the location to resolve; the object itself is never
  * mutated — a redirect rebinds the resolution to a new location
+ * @param opts options; `signal` is the chain's abort signal
  * @returns the terminal location and its resolve task
  */
-async function resolveEntry(router, location) {
+async function resolveEntry(router, location, opts) {
   const {
     resolveView,
     errorHandler
   } = router;
+  // The chain owner(navigate/refresh) passes its controller's signal;
+  // standalone resolutions get one more controller whose signal never
+  // aborts, so downstream consumers always observe a real signal.
+  const {
+    signal = new AbortController().signal
+  } = opts ?? {};
   for (let redirects = 0;; redirects++) {
     if (redirects > MAX_REDIRECTS) {
       throw new RedirectLoopError(location.pathname);
@@ -339,7 +362,8 @@ async function resolveEntry(router, location) {
       await route.beforeLoad?.({
         router,
         location,
-        params: mergeMatchedParams(matched, i)
+        params: mergeMatchedParams(matched, i),
+        signal
       }));
       if (target) {
         location = toLocation(router, target, location.state);
@@ -353,7 +377,8 @@ async function resolveEntry(router, location) {
       location,
       task: resolveView(matched, {
         router,
-        location
+        location,
+        signal
       }).catch(errorHandler)
     };
   }
@@ -459,12 +484,12 @@ function commit(router, resolvePromise, location) {
     task: resolvePromise
   }), location);
 }
-function pushEntry(router, entryPromise, fromLocation) {
+function pushEntry(router, entryPromise, fromLocation, ac) {
   const {
     history
   } = router;
   const nextIndex = getHistoryState(router).index + 1;
-  return commitBase(router, entryPromise, fromLocation, (resolvedView, entry) => {
+  return commitBase(router, entryPromise, fromLocation, ac, (resolvedView, entry) => {
     const {
       location
     } = entry;
@@ -511,14 +536,14 @@ function commitReplace(router, resolvePromise, location) {
     task: resolvePromise
   }), location);
 }
-function replaceEntry(router, entryPromise, fromLocation) {
+function replaceEntry(router, entryPromise, fromLocation, ac) {
   const {
     history
   } = router;
   const {
     index
   } = getHistoryState(router);
-  return commitBase(router, entryPromise, fromLocation, (resolvedView, entry) => {
+  return commitBase(router, entryPromise, fromLocation, ac, (resolvedView, entry) => {
     const {
       location
     } = entry;
@@ -544,7 +569,8 @@ function replaceEntry(router, entryPromise, fromLocation) {
     });
   });
 }
-function commitBase(router, entryPromise, location, onResolved) {
+function commitBase(router, entryPromise, location, ac, onResolved) {
+  const core = router;
   const {
     currentGuard,
     onLoadingChange = util.noop
@@ -552,8 +578,16 @@ function commitBase(router, entryPromise, location, onResolved) {
   if (router.resolving) {
     // Cancel current resolve
     onLoadingChange();
+    // ...and stop its requests: the guard below discards the superseded
+    // chain's result, so its in-flight guards/loaders must not keep
+    // consuming the network until they settle on their own.
+    core.resolvingController?.abort();
   }
   router.resolving = location;
+  // External commits(plain tasks from resolveTo/preload) carry no
+  // controller; clearing the slot keeps a stale one from being aborted
+  // by a later supersede.
+  core.resolvingController = ac;
   onLoadingChange('pending');
   return (
     // The whole chain — route guards AND the view task — is guarded from
@@ -567,15 +601,19 @@ function commitBase(router, entryPromise, location, onResolved) {
       entry,
       resolvedView
     }) => {
+      // This chain settled: it is no longer in flight. Clearing the
+      // mark BEFORE onResolved matters because onResolved commits
+      // history, which synchronously re-enters cancel() through the
+      // router's own listen() handler — an already-settled chain must
+      // not be aborted(or fire a cancel signal) as if it were still
+      // running. Superseded chains park forever, so the mark is always
+      // ours to clear.
+      router.resolving = undefined;
       onResolved(resolvedView, entry);
       // The navigation consumed this resolution: drop its preload
       // cache slots so a later preload re-resolves fresh state.
       evictPreloadCache(router, entry.location);
     }).then(() => {
-      // This chain settled, so it is no longer in flight. Superseded
-      // chains park forever, so only the latest chain can reach here:
-      // the mark is always ours to clear.
-      router.resolving = undefined;
       onLoadingChange('resolved');
     }).catch(e => {
       router.resolving = undefined;
@@ -590,7 +628,10 @@ function commitBase(router, entryPromise, location, onResolved) {
  * the view resolves; the history entry is committed on the terminal
  * location when guards redirected. The guard phase is part of the
  * cancelable navigation: a superseding navigate or a `cancel()` while
- * guards are still running discards this navigation.
+ * guards are still running discards this navigation — and aborts the
+ * chain's `signal`, so guards and loaders observing it({@link
+ * GuardContext.signal}, {@link ResolveViewContext.signal}) stop their
+ * requests instead of only having their results dropped.
  * @group Methods
  * @category Router
  * @param router router instance
@@ -599,19 +640,29 @@ function commitBase(router, entryPromise, location, onResolved) {
  */
 function navigate(router, to, state) {
   const location = toLocation(router, to, state);
-  return pushEntry(router, resolveEntry(router, location), location);
+  // One controller per navigation round: guards and view loaders of the
+  // whole chain(including redirect hops) share its signal.
+  const ac = new AbortController();
+  return pushEntry(router, resolveEntry(router, location, {
+    signal: ac.signal
+  }), location, ac);
 }
 
 /**
  * Refresh the page. Route guards run before the view resolves; a redirect
- * replaces the current entry with the terminal location.
+ * replaces the current entry with the terminal location. The refresh is a
+ * cancelable navigation chain like {@link navigate}: superseding it or
+ * `cancel()` aborts its signal.
  * @group Methods
  * @category Router
  * @param router router instance
  */
 function refresh(router) {
   const location = getLocation(router);
-  return replaceEntry(router, resolveEntry(router, location), location);
+  const ac = new AbortController();
+  return replaceEntry(router, resolveEntry(router, location, {
+    signal: ac.signal
+  }), location, ac);
 }
 
 /**
@@ -661,12 +712,22 @@ function createHref({
 }
 
 /**
- * Cancel the current navigate.
+ * Cancel the current navigate. The in-flight chain's guards/loaders are
+ * aborted through their signal, not merely discarded.
  * @group Methods
  * @category Router
  * @param router router instance
  */
 function cancel(router) {
+  const core = router;
+  // Aborting is reserved for chains that are still running: a chain that
+  // just committed re-enters cancel() synchronously through listen()'s
+  // history handler and must not have its(possibly still-rendered) view
+  // contexts aborted after the fact.
+  if (router.resolving) {
+    core.resolvingController?.abort();
+    core.resolvingController = undefined;
+  }
   // The cancelled chain parks forever, so nothing else will clear the
   // in-flight mark: drop it here, or a later navigation would fire a
   // spurious cancel signal(`onLoadingChange()`) for a dead resolve.

package/dist/index.mjs

@@ -1,6 +1,6 @@
-import { parsePath, createPath } from 'history';
+import { createPath, parsePath } from 'history';
 import { match as match$1 } from 'path-to-regexp';
-import { reject, noop, createCurrentGuard } from './util.mjs';
+import { createCurrentGuard, reject, noop } from './util.mjs';
 
 /* eslint-disable max-classes-per-file */
 
@@ -24,9 +24,10 @@ class RedirectLoopError extends NativeRouterError {
  */
 class SearchError extends NativeRouterError {
   /** The raw search string that failed validation. */
+  search;
 
   /** The issues reported by the schema. */
-
+  issues;
   constructor(search, issues) {
     super(`Invalid search params "${search}": ${issues.map(({
       message,
@@ -72,6 +73,10 @@ const DEFAULT_PRELOAD_TTL = 30_000;
  *   `history index - baseIndex`; entries whose slot falls outside the
  *   memory window re-resolve lazily when landed on.
  * - `preloadCache`: router-level cache of {@link preload} results.
+ * - `resolvingController`: the in-flight chain's AbortController. It is
+ *   aborted(supersede/cancel) only while the chain is in flight; a
+ *   settled chain's controller is left alone so its contexts never
+ *   report `aborted` for a navigation that actually committed.
  */
 
 /**
@@ -208,7 +213,7 @@ function match(router, pathname) {
       const route = routes[i];
       const end = !route.children;
       const matched = route.path ? match$1(route.path, {
-        strict: true,
+        trailing: false,
         sensitive: true,
         decode: typeof decodeURIComponent === 'function' ? decodeURIComponent : undefined,
         end
@@ -271,7 +276,10 @@ function resolve(router, location) {
   } = router;
   return (matched ? resolveView(matched, {
     router,
-    location
+    location,
+    // One-shot resolves(warm-up, direct calls) are never superseded
+    // or cancelled: their loaders get a signal that never aborts.
+    signal: new AbortController().signal
   }) : Promise.reject(new NotFoundError(location.pathname))).catch(errorHandler);
 }
 
@@ -298,22 +306,37 @@ function resolveTo(router, to, state) {
  * levels re-run on every hop(keep side-effectful guards idempotent) —
  * carrying the original user state; at most
  * {@link MAX_REDIRECTS 10} redirects are followed before a
- * {@link RedirectLoopError} is thrown. An unmatched pathname keeps the
+ * An unmatched pathname keeps the
  * {@link resolve resolve} behavior: the task rejects with a
  * {@link NotFoundError} and is routed through `router.errorHandler`.
  *
+ * `opts.signal` is the abort signal of the whole chain: guards see it in
+ * their {@link GuardContext contexts}, the view task's
+ * {@link ResolveViewContext context} carries it on, and it is aborted
+ * once the navigation is superseded or cancelled. Standalone callers
+ * that pass nothing(e.g. {@link preload}) get a signal that never
+ * aborts — their resolution may be shared, so cancelling it on behalf of
+ * one consumer is not sound yet.
+ *
  * @group Methods
  * @category Router
  * @param router router instance
  * @param location the location to resolve; the object itself is never
  * mutated — a redirect rebinds the resolution to a new location
+ * @param opts options; `signal` is the chain's abort signal
  * @returns the terminal location and its resolve task
  */
-async function resolveEntry(router, location) {
+async function resolveEntry(router, location, opts) {
   const {
     resolveView,
     errorHandler
   } = router;
+  // The chain owner(navigate/refresh) passes its controller's signal;
+  // standalone resolutions get one more controller whose signal never
+  // aborts, so downstream consumers always observe a real signal.
+  const {
+    signal = new AbortController().signal
+  } = opts ?? {};
   for (let redirects = 0;; redirects++) {
     if (redirects > MAX_REDIRECTS) {
       throw new RedirectLoopError(location.pathname);
@@ -337,7 +360,8 @@ async function resolveEntry(router, location) {
       await route.beforeLoad?.({
         router,
         location,
-        params: mergeMatchedParams(matched, i)
+        params: mergeMatchedParams(matched, i),
+        signal
       }));
       if (target) {
         location = toLocation(router, target, location.state);
@@ -351,7 +375,8 @@ async function resolveEntry(router, location) {
       location,
       task: resolveView(matched, {
         router,
-        location
+        location,
+        signal
       }).catch(errorHandler)
     };
   }
@@ -457,12 +482,12 @@ function commit(router, resolvePromise, location) {
     task: resolvePromise
   }), location);
 }
-function pushEntry(router, entryPromise, fromLocation) {
+function pushEntry(router, entryPromise, fromLocation, ac) {
   const {
     history
   } = router;
   const nextIndex = getHistoryState(router).index + 1;
-  return commitBase(router, entryPromise, fromLocation, (resolvedView, entry) => {
+  return commitBase(router, entryPromise, fromLocation, ac, (resolvedView, entry) => {
     const {
       location
     } = entry;
@@ -509,14 +534,14 @@ function commitReplace(router, resolvePromise, location) {
     task: resolvePromise
   }), location);
 }
-function replaceEntry(router, entryPromise, fromLocation) {
+function replaceEntry(router, entryPromise, fromLocation, ac) {
   const {
     history
   } = router;
   const {
     index
   } = getHistoryState(router);
-  return commitBase(router, entryPromise, fromLocation, (resolvedView, entry) => {
+  return commitBase(router, entryPromise, fromLocation, ac, (resolvedView, entry) => {
     const {
       location
     } = entry;
@@ -542,7 +567,8 @@ function replaceEntry(router, entryPromise, fromLocation) {
     });
   });
 }
-function commitBase(router, entryPromise, location, onResolved) {
+function commitBase(router, entryPromise, location, ac, onResolved) {
+  const core = router;
   const {
     currentGuard,
     onLoadingChange = noop
@@ -550,8 +576,16 @@ function commitBase(router, entryPromise, location, onResolved) {
   if (router.resolving) {
     // Cancel current resolve
     onLoadingChange();
+    // ...and stop its requests: the guard below discards the superseded
+    // chain's result, so its in-flight guards/loaders must not keep
+    // consuming the network until they settle on their own.
+    core.resolvingController?.abort();
   }
   router.resolving = location;
+  // External commits(plain tasks from resolveTo/preload) carry no
+  // controller; clearing the slot keeps a stale one from being aborted
+  // by a later supersede.
+  core.resolvingController = ac;
   onLoadingChange('pending');
   return (
     // The whole chain — route guards AND the view task — is guarded from
@@ -565,15 +599,19 @@ function commitBase(router, entryPromise, location, onResolved) {
       entry,
       resolvedView
     }) => {
+      // This chain settled: it is no longer in flight. Clearing the
+      // mark BEFORE onResolved matters because onResolved commits
+      // history, which synchronously re-enters cancel() through the
+      // router's own listen() handler — an already-settled chain must
+      // not be aborted(or fire a cancel signal) as if it were still
+      // running. Superseded chains park forever, so the mark is always
+      // ours to clear.
+      router.resolving = undefined;
       onResolved(resolvedView, entry);
       // The navigation consumed this resolution: drop its preload
       // cache slots so a later preload re-resolves fresh state.
       evictPreloadCache(router, entry.location);
     }).then(() => {
-      // This chain settled, so it is no longer in flight. Superseded
-      // chains park forever, so only the latest chain can reach here:
-      // the mark is always ours to clear.
-      router.resolving = undefined;
       onLoadingChange('resolved');
     }).catch(e => {
       router.resolving = undefined;
@@ -588,7 +626,10 @@ function commitBase(router, entryPromise, location, onResolved) {
  * the view resolves; the history entry is committed on the terminal
  * location when guards redirected. The guard phase is part of the
  * cancelable navigation: a superseding navigate or a `cancel()` while
- * guards are still running discards this navigation.
+ * guards are still running discards this navigation — and aborts the
+ * chain's `signal`, so guards and loaders observing it({@link
+ * GuardContext.signal}, {@link ResolveViewContext.signal}) stop their
+ * requests instead of only having their results dropped.
  * @group Methods
  * @category Router
  * @param router router instance
@@ -597,19 +638,29 @@ function commitBase(router, entryPromise, location, onResolved) {
  */
 function navigate(router, to, state) {
   const location = toLocation(router, to, state);
-  return pushEntry(router, resolveEntry(router, location), location);
+  // One controller per navigation round: guards and view loaders of the
+  // whole chain(including redirect hops) share its signal.
+  const ac = new AbortController();
+  return pushEntry(router, resolveEntry(router, location, {
+    signal: ac.signal
+  }), location, ac);
 }
 
 /**
  * Refresh the page. Route guards run before the view resolves; a redirect
- * replaces the current entry with the terminal location.
+ * replaces the current entry with the terminal location. The refresh is a
+ * cancelable navigation chain like {@link navigate}: superseding it or
+ * `cancel()` aborts its signal.
  * @group Methods
  * @category Router
  * @param router router instance
  */
 function refresh(router) {
   const location = getLocation(router);
-  return replaceEntry(router, resolveEntry(router, location), location);
+  const ac = new AbortController();
+  return replaceEntry(router, resolveEntry(router, location, {
+    signal: ac.signal
+  }), location, ac);
 }
 
 /**
@@ -659,12 +710,22 @@ function createHref({
 }
 
 /**
- * Cancel the current navigate.
+ * Cancel the current navigate. The in-flight chain's guards/loaders are
+ * aborted through their signal, not merely discarded.
  * @group Methods
  * @category Router
  * @param router router instance
  */
 function cancel(router) {
+  const core = router;
+  // Aborting is reserved for chains that are still running: a chain that
+  // just committed re-enters cancel() synchronously through listen()'s
+  // history handler and must not have its(possibly still-rendered) view
+  // contexts aborted after the fact.
+  if (router.resolving) {
+    core.resolvingController?.abort();
+    core.resolvingController = undefined;
+  }
   // The cancelled chain parks forever, so nothing else will clear the
   // in-flight mark: drop it here, or a later navigation would fire a
   // spurious cancel signal(`onLoadingChange()`) for a dead resolve.

package/dist/types/router.d.ts

@@ -88,18 +88,29 @@ export declare function resolveTo<R extends BaseRoute = BaseRoute, V = any>(rout
  * levels re-run on every hop(keep side-effectful guards idempotent) —
  * carrying the original user state; at most
  * {@link MAX_REDIRECTS 10} redirects are followed before a
- * {@link RedirectLoopError} is thrown. An unmatched pathname keeps the
+ * An unmatched pathname keeps the
  * {@link resolve resolve} behavior: the task rejects with a
  * {@link NotFoundError} and is routed through `router.errorHandler`.
  *
+ * `opts.signal` is the abort signal of the whole chain: guards see it in
+ * their {@link GuardContext contexts}, the view task's
+ * {@link ResolveViewContext context} carries it on, and it is aborted
+ * once the navigation is superseded or cancelled. Standalone callers
+ * that pass nothing(e.g. {@link preload}) get a signal that never
+ * aborts — their resolution may be shared, so cancelling it on behalf of
+ * one consumer is not sound yet.
+ *
  * @group Methods
  * @category Router
  * @param router router instance
  * @param location the location to resolve; the object itself is never
  * mutated — a redirect rebinds the resolution to a new location
+ * @param opts options; `signal` is the chain's abort signal
  * @returns the terminal location and its resolve task
  */
-export declare function resolveEntry<R extends BaseRoute = BaseRoute, V = any>(router: RouterInstance<R, V>, location: Location): Promise<ResolvedEntry<V>>;
+export declare function resolveEntry<R extends BaseRoute = BaseRoute, V = any>(router: RouterInstance<R, V>, location: Location, opts?: {
+    signal?: AbortSignal;
+}): Promise<ResolvedEntry<V>>;
 /**
  * Resolve a target through the route guards(`redirect`/`beforeLoad`) and
  * cache the result at the router level, keyed by `pathname + search`.
@@ -147,7 +158,10 @@ export declare function commitReplace<R extends BaseRoute = BaseRoute, V = any>(
  * the view resolves; the history entry is committed on the terminal
  * location when guards redirected. The guard phase is part of the
  * cancelable navigation: a superseding navigate or a `cancel()` while
- * guards are still running discards this navigation.
+ * guards are still running discards this navigation — and aborts the
+ * chain's `signal`, so guards and loaders observing it({@link
+ * GuardContext.signal}, {@link ResolveViewContext.signal}) stop their
+ * requests instead of only having their results dropped.
  * @group Methods
  * @category Router
  * @param router router instance
@@ -157,7 +171,9 @@ export declare function commitReplace<R extends BaseRoute = BaseRoute, V = any>(
 export declare function navigate<R extends BaseRoute = BaseRoute, V = any>(router: RouterInstance<R, V>, to: string, state?: any): Promise<void>;
 /**
  * Refresh the page. Route guards run before the view resolves; a redirect
- * replaces the current entry with the terminal location.
+ * replaces the current entry with the terminal location. The refresh is a
+ * cancelable navigation chain like {@link navigate}: superseding it or
+ * `cancel()` aborts its signal.
  * @group Methods
  * @category Router
  * @param router router instance
@@ -195,7 +211,8 @@ export declare function back<R extends BaseRoute = BaseRoute, V = any>(router: R
  */
 export declare function createHref<R extends BaseRoute = BaseRoute, V = any>({ baseUrl, history }: RouterInstance<R, V>, to: string): string;
 /**
- * Cancel the current navigate.
+ * Cancel the current navigate. The in-flight chain's guards/loaders are
+ * aborted through their signal, not merely discarded.
  * @group Methods
  * @category Router
  * @param router router instance

package/dist/types/types.d.ts

@@ -79,32 +79,61 @@ export type SearchInput = Record<string, string | string[]>;
  * @category Route
  */
 export type SearchOutputOf<S> = S extends StandardSchemaV1<any, infer Output> ? Output : never;
+/** ASCII approximation of path-to-regexp's `ID_Start`. */
+type ParamStartChar = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' | '_' | '$';
+/** ASCII approximation of path-to-regexp's `ID_Continue`. */
+type ParamContinueChar = ParamStartChar | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
+type ParamValueOf<Name extends string, Mode extends 'param' | 'wildcard'> = Mode extends 'wildcard' ? {
+    [K in Name]: string[];
+} : {
+    [K in Name]: string;
+};
+/**
+ * Scan a segment char by char: `\\x` escapes the next char, `:name`
+ * starts a param, `*name` starts a wildcard, anything else is static
+ * text.
+ */
+type SegmentParamsOf<Seg extends string> = Seg extends `${infer Char}${infer Rest}` ? Char extends '\\' ? Rest extends `${string}${infer Tail}` ? SegmentParamsOf<Tail> : {} : Char extends ':' | '*' ? Rest extends `${infer First}${infer Rest2}` ? First extends ParamStartChar ? ParamNameOf<Rest2, First, Char extends '*' ? 'wildcard' : 'param'> : {} : {} : SegmentParamsOf<Rest> : {};
+/** Consume the identifier run started by a `ParamStartChar`. */
+type ParamNameOf<Rest extends string, Name extends string, Mode extends 'param' | 'wildcard'> = Rest extends `${infer Char}${infer Tail}` ? Char extends ParamContinueChar ? ParamNameOf<Tail, `${Name}${Char}`, Mode> : Char extends '?' | '(' | ')' | '[' | ']' | '+' | '!' | '*' ? {} : ParamValueOf<Name, Mode> & SegmentParamsOf<Rest> : ParamValueOf<Name, Mode>;
 /**
- * Params contributed by a single path segment: `:name` is required,
- * `:name?` is optional, anything else(static or wildcard) contributes
- * nothing.
+ * Params contributed by a single path segment, modeled after the
+ * path-to-regexp **8.4.2** string grammar(the version this package
+ * locks):
+ *
+ * - `:name` contributes a required `string` param wherever it appears
+ *   in the segment — `:id`, `page-:id`, `:from-:to` all work at
+ *   runtime and are modeled;
+ * - `*name` contributes a `string[]` wildcard param(the runtime
+ *   matcher splits a wildcard value by `/`).
+ *
+ * Everything else contributes nothing:
  *
- * Only the segment-exact forms of the path-to-regexp 6 syntax are
- * modeled. Prefix/suffix params(`/page-:id`), repetitions(`:id*`,
- * `:id+`) and custom regexes(`:id(\\d+)`) are matched at runtime but
- * not modeled here — they simply contribute no keys.
+ * - the v6-era suffixes `:id?`, `:id+`, `:id*`, `:id(\\d+)` are **not**
+ *   runtime syntax in 8.4.2 — the matcher throws a `PathError` when the
+ *   path is compiled, so they are deliberately left unmodeled instead
+ *   of endorsing a path that crashes;
+ * - quoted names(`:"x y"`) and non-ASCII identifier chars are not
+ *   modeled(the scanner only knows ASCII identifiers).
+ *
+ * Note: wildcard params surface as `string[]` at runtime while the
+ * router-level types(`Matched.params`,
+ * {@link GuardContext.params}) are `Record<string, string>` — the
+ * router does not model wildcard params.
  * @group Types
  * @category Route
  */
-export type PathParamsOf<Seg extends string> = Seg extends `:${infer Name}?` ? {
-    [K in Name & string]?: string;
-} : Seg extends `:${infer Name}` ? {
-    [K in Name & string]: string;
-} : {};
+export type PathParamsOf<Seg extends string> = SegmentParamsOf<Seg>;
 /**
  * Extract the params shape of a route path pattern. Splits the pattern
  * into `/`-separated segments and intersects the params of each, e.g.
- * `ExtractPathParams<'/users/:id/posts/:postId?'>` is
- * `{id: string} & {postId?: string}`.
+ * `ExtractPathParams<'/users/:id/files/*rest'>` is
+ * `{id: string} & {rest: string[]}`.
  *
- * Within the modeled path-to-regexp 6 syntax scope(see
- * {@link PathParamsOf}); wildcards(`*`) and static segments are
- * ignored. Distributes over unions of patterns.
+ * Within the modeled path-to-regexp 8.4.2 syntax scope(see
+ * {@link PathParamsOf}); static segments are ignored and v6-era
+ * suffixes(`:id?`, `:id(\\d+)`, …) contribute nothing because the
+ * runtime matcher rejects them. Distributes over unions of patterns.
  * @group Types
  * @category Route
  */
@@ -118,6 +147,13 @@ export type GuardContext<R extends BaseRoute = BaseRoute> = {
     router: RouterInstance<R>;
     location: Location;
     params: Record<string, string>;
+    /**
+     * Aborted when this navigation is superseded by a newer one or
+     * cancelled(see {@link RouterInstance.cancelAll cancel}); pass it to
+     * the guard's requests(e.g. `fetch(url, {signal})`) so a discarded
+     * navigation stops consuming the network.
+     */
+    signal: AbortSignal;
 };
 export type BaseRoute<T = any> = {
     path?: Path;
@@ -147,6 +183,12 @@ export type Matched<R extends BaseRoute = BaseRoute> = {
 export type ResolveViewContext<R extends BaseRoute> = {
     router: RouterInstance<R>;
     location: Location;
+    /**
+     * The navigation chain's abort signal: aborted when this navigation is
+     * superseded by a newer one or cancelled. Frameworks forward it into
+     * their data contexts so loaders can abort their requests.
+     */
+    signal: AbortSignal;
 };
 export type ResolveView<R extends BaseRoute, V> = (matched: Matched<R>[], ctx: ResolveViewContext<R>) => Promise<V>;
 export type Options<V> = {
@@ -191,3 +233,4 @@ export type RouterInstance<R extends BaseRoute, V = any> = {
     cancelAll(): void;
     resolving?: Location;
 } & RequiredOf<Options<V>, 'baseUrl' | 'maxStackDepth'>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@native-router/core",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
@@ -52,24 +52,24 @@
   },
   "dependencies": {
     "history": "^5.3.0",
-    "path-to-regexp": "^6.2.1"
+    "path-to-regexp": "^8.4.2"
   },
   "devDependencies": {
-    "@babel/core": "^7.22.9",
-    "@babel/preset-env": "^7.22.9",
-    "@babel/preset-typescript": "^7.22.5",
-    "@rollup/plugin-babel": "^6.0.3",
-    "@rollup/plugin-commonjs": "^25.0.4",
-    "@rollup/plugin-node-resolve": "^15.1.0",
-    "@rollup/plugin-replace": "^5.0.2",
-    "@types/node": "^20.4.5",
-    "@types/sinon": "^10.0.15",
+    "@babel/core": "^8.0.1",
+    "@babel/preset-env": "^8.0.2",
+    "@babel/preset-typescript": "^8.0.1",
+    "@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/sinon": "^22.0.0",
     "@typescript-eslint/eslint-plugin": "^6.2.0",
     "@typescript-eslint/parser": "^6.2.0",
-    "@vitest/coverage-v8": "^4.0.18",
-    "commitizen": "^4.3.0",
-    "core-js": "^3.31.1",
-    "cross-env": "^7.0.3",
+    "@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-config-airbnb": "^19.0.4",
     "eslint-config-airbnb-typescript": "^17.1.0",
@@ -81,21 +81,21 @@
     "eslint-plugin-prettier": "^5.0.0",
     "eslint-plugin-react": "^7.33.0",
     "eslint-plugin-react-hooks": "^4.6.0",
-    "gh-pages": "^5.0.0",
-    "husky": "^8.0.3",
-    "lint-staged": "^13.2.3",
-    "prettier": "^3.0.0",
-    "rollup": "^3.28.0",
+    "gh-pages": "^6.3.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.3.0",
+    "prettier": "^3.9.6",
+    "rollup": "^4.62.5",
+    "semantic-release": "^25.0.9",
     "should": "^13.2.3",
     "should-sinon": "0.0.6",
-    "sinon": "^15.2.0",
-    "terser": "^5.19.2",
-    "tsc-alias": "^1.8.7",
-    "typedoc": "^0.24.8",
+    "sinon": "^22.1.0",
+    "terser": "^5.50.0",
+    "tsc-alias": "^1.9.2",
+    "typedoc": "^0.28.20",
     "typedoc-plugin-mark-react-functional-components": "^0.2.2",
-    "typedoc-plugin-missing-exports": "^2.0.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.18",
-    "semantic-release": "^25.0.3"
+    "typedoc-plugin-missing-exports": "^4.1.4",
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.11"
   }
 }