@native-router/core 1.2.0 → 1.3.0

package/dist/index.cjs

@@ -12,9 +12,44 @@ class NotFoundError extends NativeRouterError {
     super(`Can't find the path: ${pathname}`);
   }
 }
+class RedirectLoopError extends NativeRouterError {
+  constructor(target) {
+    super(`Redirect loop detected${target ? ` after following redirects to: ${target}` : ''}`);
+  }
+}
 
 const DEFAULT_MAX_STACK_DEPTH = 100;
 
+/** Max redirects followed by {@link resolveEntry} before giving up. */
+const MAX_REDIRECTS = 10;
+
+/** Default cache lifetime of {@link preload} results, in milliseconds. */
+const DEFAULT_PRELOAD_TTL = 30_000;
+
+/**
+ * A location resolved through the route guards, together with the view task
+ * of its final target. When guards redirected, `location` is the terminal
+ * location and `task` resolves the view of the target route.
+ */
+
+/**
+ * Cache record of {@link preload}: the resolution promise of the
+ * prefetched target(every hit within the TTL awaits the very same
+ * promise, which also deduplicates concurrent callers) plus its
+ * expiry timestamp.
+ */
+
+/**
+ * Bookkeeping every {@link create}d router carries on top of
+ * {@link RouterInstance}. Declared in this module(instead of types.ts)
+ * to keep the public instance type surface stable:
+ * - `baseIndex`: absolute history index of `locationStack[0]`. The
+ *   physical(window-relative) stack slot of a history entry is
+ *   `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.
+ */
+
 /**
  * Create a router instance.
  * @group Methods
@@ -27,25 +62,30 @@ const DEFAULT_MAX_STACK_DEPTH = 100;
  */
 function create(routes, history, resolveView, options) {
   const [currentGuard, cancelAll] = util.createCurrentGuard();
+  const instanceHistory = history;
+  const state = instanceHistory.location.state || {};
   const {
     index
   } = getHistoryState({
-    history: history
+    history: instanceHistory
   });
-  // Restore the session stack from the bounded window serialized in the
-  // current entry state; entries before the window become placeholders.
-  // Legacy index-only state(1.x) degrades to a single-entry stack.
-  const locationStack = restoreLocationStack(history);
-  const viewStack = new Array(Math.max(index + 1, locationStack.length)).fill(null);
-  if (options?.currentView) {
-    viewStack[index] = options.currentView;
-  }
-  return {
+  // Restore the session window from the bounded location window in the
+  // current entry state. Window-less legacy(1.x index-only) states degrade
+  // to a single-entry window aligned with the landed position.
+  const locationStack = restoreLocationStack(instanceHistory);
+  const baseIndex = state.locationStack?.length ? state.base || 0 :
+  // Degraded window: its only entry IS the landed position.
+  index;
+  const router = {
     routes: Array.isArray(routes) ? routes : [routes],
     resolveView,
-    history: history,
+    history: instanceHistory,
     locationStack,
-    viewStack,
+    // The view stack is window-relative, so it is exactly as long as the
+    // location window and stays bounded by maxStackDepth with it.
+    viewStack: new Array(locationStack.length).fill(null),
+    baseIndex,
+    preloadCache: new Map(),
     currentGuard,
     cancelAll,
     errorHandler: util.reject,
@@ -53,6 +93,16 @@ function create(routes, history, resolveView, options) {
     baseUrl: options?.baseUrl || '',
     maxStackDepth: options?.maxStackDepth || DEFAULT_MAX_STACK_DEPTH
   };
+  if (options?.currentView) {
+    const physical = index - baseIndex;
+    // Hand-crafted or corrupted state may land the index outside the
+    // restored window; skip the write instead of creating a string-keyed
+    // property on the array(a negative index would).
+    if (physical >= 0 && physical < router.viewStack.length) {
+      router.viewStack[physical] = options.currentView;
+    }
+  }
+  return router;
 }
 function setOptions(router, options) {
   return Object.assign(router, options);
@@ -68,34 +118,34 @@ function getLocation({
 }
 
 /**
- * Restore the in-memory location stack from the bounded window in the
- * current history entry state. Slots before the window become
- * placeholders(`undefined`) so {@link initHistoryStack} can skip them
- * and a POP onto them still falls back to a lazy refresh.
+ * Restore the bounded location window serialized in the current history
+ * entry state, as-is: entries before the window start are outside the
+ * memory window(see {@link RouterCore.baseIndex}) and re-resolve lazily
+ * when landed on. Window-less legacy(1.x index-only) state degrades to a
+ * single-entry window.
  */
 function restoreLocationStack(history) {
   const state = history.location.state || {};
-  const {
-    locationStack,
-    base
-  } = state;
-  return locationStack?.length ? [...new Array(base || 0), ...locationStack] : [getLocation({
+  return state.locationStack?.length ? [...state.locationStack] : [getLocation({
     history
   })];
 }
 
 /**
- * Serialize the tail window of the in-memory stack, bounded by
- * `maxStackDepth`, together with the absolute index of its first entry.
+ * Serialize the memory window together with the absolute index of its
+ * first entry, so a refresh can restore it. The memory window is trimmed
+ * on every push, so it is already bounded by `maxStackDepth`; the cap
+ * only matters when `maxStackDepth` was lowered via
+ * {@link setOptions} after the fact.
  */
 function serializeStack(router) {
   const {
     locationStack,
     maxStackDepth
   } = router;
-  const windowed = locationStack.slice(-maxStackDepth);
+  const windowed = locationStack.length > maxStackDepth ? locationStack.slice(-maxStackDepth) : locationStack;
   return {
-    base: locationStack.length - windowed.length,
+    base: router.baseIndex + (locationStack.length - windowed.length),
     locationStack: windowed
   };
 }
@@ -105,8 +155,17 @@ function getHistoryState(router) {
     index: state.index || 0
   };
 }
+
+/**
+ * Physical(window-relative) view slot of an absolute history index.
+ * Slots before the window start(negative) or past its end read as
+ * `undefined`, driving the lazy refresh fallback of {@link listen}.
+ */
+function viewAt(router, index) {
+  return router.viewStack[index - router.baseIndex];
+}
 function getCurrentView(router) {
-  return router.viewStack[getHistoryState(router).index];
+  return viewAt(router, getHistoryState(router).index);
 }
 
 /**
@@ -206,6 +265,158 @@ function resolveTo(router, to, state) {
   return resolve(router, location);
 }
 
+/**
+ * Resolve a location through the route guards(`redirect`/`beforeLoad`).
+ *
+ * Guards run per matched level from the shallowest to the deepest. A guard
+ * returning a path string(redirect) restarts the resolution at the new
+ * location — from the shallowest level again, so guards of shallower
+ * 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
+ * {@link resolve resolve} behavior: the task rejects with a
+ * {@link NotFoundError} and is routed through `router.errorHandler`.
+ *
+ * @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
+ * @returns the terminal location and its resolve task
+ */
+async function resolveEntry(router, location) {
+  const {
+    resolveView,
+    errorHandler
+  } = router;
+  for (let redirects = 0;; redirects++) {
+    if (redirects > MAX_REDIRECTS) {
+      throw new RedirectLoopError(location.pathname);
+    }
+    const matched = match(router, location.pathname);
+    if (!matched) {
+      return {
+        location,
+        task: Promise.reject(new NotFoundError(location.pathname)).catch(errorHandler)
+      };
+    }
+    let redirected = false;
+    for (let i = 0; i < matched.length; i++) {
+      const {
+        route
+      } = matched[i];
+      // `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)
+      }));
+      if (target) {
+        location = toLocation(router, target, location.state);
+        redirected = true;
+        break;
+      }
+    }
+    // eslint-disable-next-line no-continue -- the redirect loop restarts the outer resolution pass
+    if (redirected) continue;
+    return {
+      location,
+      task: resolveView(matched, {
+        router,
+        location
+      }).catch(errorHandler)
+    };
+  }
+}
+
+/**
+ * Resolve a target through the route guards(`redirect`/`beforeLoad`) and
+ * cache the result at the router level, keyed by `pathname + search`.
+ *
+ * Within its TTL(`opts.ttl`, default 30s) repeated and concurrent calls
+ * return the very same entry promise, so concurrent callers share one
+ * resolution(in-flight dedup) and repeated prefetches reuse the resolved
+ * view task instead of re-running guards and `resolveView`. A rejected
+ * resolution(guard error, redirect loop) is evicted from the cache, so
+ * the next call retries it. Committing a navigation({@link commit} or
+ * {@link commitReplace}) consumes the entry and evicts its cache slot —
+ * a later preload re-resolves fresh state, while callers still holding
+ * the old entry keep their references.
+ *
+ * @group Methods
+ * @category Router
+ * @param router router instance
+ * @param to path string
+ * @param opts options; `ttl` is the cache lifetime in milliseconds
+ * @returns the terminal location and its resolve task
+ */
+function preload(router, to, opts) {
+  const cache = preloadCacheOf(router);
+  const location = toLocation(router, to);
+  const key = preloadLocationKey(location);
+  const cached = cache.get(key);
+  if (cached && Date.now() < cached.expires) {
+    return cached.entry;
+  }
+  prunePreloadCache(cache);
+  const entry = resolveEntry(router, location);
+  const record = {
+    entry,
+    expires: Date.now() + (opts?.ttl ?? DEFAULT_PRELOAD_TTL)
+  };
+  cache.set(key, record);
+  entry.then(resolved => {
+    record.terminal = resolved.location;
+  }, () => {
+    // Never cache a failure: evict the slot(this record only, a newer
+    // preload may already have replaced it) so the next call retries.
+    if (cache.get(key)?.entry === entry) cache.delete(key);
+  });
+  return entry;
+}
+function preloadLocationKey(location) {
+  return location.pathname + location.search;
+}
+
+/**
+ * Drop expired records. Runs on every cache write, so distinct prefetched
+ * targets never accumulate beyond their TTL in a long session.
+ */
+function prunePreloadCache(cache) {
+  const now = Date.now();
+  cache.forEach((record, key) => {
+    if (record.expires <= now) cache.delete(key);
+  });
+}
+
+/**
+ * Evict the cache slots consumed by a committed navigation. A redirecting
+ * entry is cached under its pre-redirect key while its terminal location
+ * differs, so records whose terminal resolves to the committed location
+ * are dropped too; in-flight records(terminal not yet known) are left to
+ * the TTL.
+ */
+function evictPreloadCache(router, location) {
+  const cache = preloadCacheOf(router);
+  const key = preloadLocationKey(location);
+  cache.delete(key);
+  cache.forEach((record, k) => {
+    if (record.terminal && preloadLocationKey(record.terminal) === key) {
+      cache.delete(k);
+    }
+  });
+}
+function preloadCacheOf(router) {
+  const core = router;
+  // create() always seeds the cache; the lazy path keeps hand-built
+  // router-shaped objects working.
+  return core.preloadCache ??= new Map();
+}
+
 /**
  * Commit the resolve task and push history.
  * @group Methods
@@ -215,13 +426,43 @@ function resolveTo(router, to, state) {
  * @param location the location to resolved
  */
 function commit(router, resolvePromise, location) {
+  // Wrap the raw task so external callers share the guarded entry
+  // pipeline; the entry location is the given one, as-is.
+  return pushEntry(router, Promise.resolve({
+    location,
+    task: resolvePromise
+  }), location);
+}
+function pushEntry(router, entryPromise, fromLocation) {
   const {
     history
   } = router;
   const nextIndex = getHistoryState(router).index + 1;
-  return commitBase(router, resolvePromise, location, resolvedView => {
-    router.locationStack = [...router.locationStack.slice(0, nextIndex), location];
-    router.viewStack = [...router.viewStack.slice(0, nextIndex), resolvedView];
+  return commitBase(router, entryPromise, fromLocation, (resolvedView, entry) => {
+    const {
+      location
+    } = entry;
+    let next = nextIndex - router.baseIndex;
+    if (next < 0 || next > router.locationStack.length) {
+      // The current entry sits outside the memory window(a push while an
+      // out-of-window lazy refresh is still pending): restart the window
+      // at the pushed position. Out-of-window neighbours re-resolve
+      // lazily when landed on.
+      router.baseIndex = nextIndex;
+      router.locationStack = [];
+      router.viewStack = [];
+      next = 0;
+    }
+    router.locationStack = [...router.locationStack.slice(0, next), location];
+    router.viewStack = [...router.viewStack.slice(0, next), resolvedView];
+    // Bound the memory window: evict the oldest entries once the stack
+    // outgrows maxStackDepth, shifting the window base along.
+    if (router.locationStack.length > router.maxStackDepth) {
+      const evicted = router.locationStack.length - router.maxStackDepth;
+      router.locationStack = router.locationStack.slice(evicted);
+      router.viewStack = router.viewStack.slice(evicted);
+      router.baseIndex += evicted;
+    }
     history.push(location, {
       index: nextIndex,
       state: location.state,
@@ -239,15 +480,37 @@ function commit(router, resolvePromise, location) {
  * @param location the location to resolved
  */
 function commitReplace(router, resolvePromise, location) {
+  return replaceEntry(router, Promise.resolve({
+    location,
+    task: resolvePromise
+  }), location);
+}
+function replaceEntry(router, entryPromise, fromLocation) {
   const {
     history
   } = router;
   const {
     index
   } = getHistoryState(router);
-  return commitBase(router, resolvePromise, location, resolvedView => {
-    router.locationStack[index] = location;
-    router.viewStack[index] = resolvedView;
+  return commitBase(router, entryPromise, fromLocation, (resolvedView, entry) => {
+    const {
+      location
+    } = entry;
+    const physical = index - router.baseIndex;
+    if (physical < 0 || physical >= router.locationStack.length) {
+      // The landed entry is outside the memory window(the browser evicted
+      // older history past the window, or a window-less legacy state).
+      // Restart the window at the landed position — placeholders for the
+      // unknown gap slots are gone, so neighbouring out-of-window entries
+      // re-resolve lazily on every POP, consistent with the rare
+      // browser-evicted paths.
+      router.baseIndex = index;
+      router.locationStack = [location];
+      router.viewStack = [resolvedView];
+    } else {
+      router.locationStack[physical] = location;
+      router.viewStack[physical] = resolvedView;
+    }
     history.replace(location, {
       index,
       state: location.state,
@@ -255,7 +518,7 @@ function commitReplace(router, resolvePromise, location) {
     });
   });
 }
-function commitBase(router, resolvePromise, location, onResolved) {
+function commitBase(router, entryPromise, location, onResolved) {
   const {
     currentGuard,
     onLoadingChange = util.noop
@@ -266,16 +529,42 @@ function commitBase(router, resolvePromise, location, onResolved) {
   }
   router.resolving = location;
   onLoadingChange('pending');
-  return currentGuard(resolvePromise).then(onResolved)
-  // eslint-disable-next-line no-void
-  .then(() => void onLoadingChange('resolved')).catch(e => {
-    onLoadingChange('rejected');
-    throw e;
-  });
+  return (
+    // The whole chain — route guards AND the view task — is guarded from
+    // the very start: a superseding navigation or a cancel() while slow
+    // guards are still running parks this chain forever, exactly like
+    // during the view phase.
+    currentGuard(entryPromise.then(entry => entry.task.then(resolvedView => ({
+      entry,
+      resolvedView
+    })))).then(({
+      entry,
+      resolvedView
+    }) => {
+      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;
+      onLoadingChange('rejected');
+      throw e;
+    })
+  );
 }
 
 /**
- * Navigate to a new path.
+ * Navigate to a new path. Route guards(`redirect`/`beforeLoad`) run before
+ * 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.
  * @group Methods
  * @category Router
  * @param router router instance
@@ -284,20 +573,19 @@ function commitBase(router, resolvePromise, location, onResolved) {
  */
 function navigate(router, to, state) {
   const location = toLocation(router, to, state);
-  const viewPromise = resolve(router, location);
-  return commit(router, viewPromise, location);
+  return pushEntry(router, resolveEntry(router, location), location);
 }
 
 /**
- * Refresh the page.
+ * Refresh the page. Route guards run before the view resolves; a redirect
+ * replaces the current entry with the terminal location.
  * @group Methods
  * @category Router
  * @param router router instance
  */
 function refresh(router) {
   const location = getLocation(router);
-  const viewPromise = resolve(router, location);
-  return commitReplace(router, viewPromise, location);
+  return replaceEntry(router, resolveEntry(router, location), location);
 }
 
 /**
@@ -352,12 +640,13 @@ function createHref({
  * @category Router
  * @param router router instance
  */
-function cancel({
-  cancelAll,
-  onLoadingChange = util.noop
-}) {
-  cancelAll();
-  onLoadingChange();
+function cancel(router) {
+  // 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.
+  router.resolving = undefined;
+  router.cancelAll();
+  router.onLoadingChange?.();
 }
 
 /**
@@ -372,7 +661,7 @@ function cancel({
  * @param router router instance
  */
 function initHistoryStack(router) {
-  return Promise.all(router.locationStack.map(location => location ? resolve(router, location) : Promise.resolve(null))).then(views => {
+  return Promise.all(router.locationStack.map(location => resolve(router, location))).then(views => {
     router.viewStack = views;
   });
 }
@@ -396,13 +685,15 @@ function listen(router, onViewChange) {
     cancel(router);
     const state = location.state;
     const index = state?.index || 0;
-    const view = router.viewStack[index];
+    const view = viewAt(router, index);
     onViewChange(view);
     if (!view) {
-      // Lazy fallback for placeholder slots and legacy-shaped state:
-      // re-resolving the landed entry also re-serializes the window
-      // into it via the replace commit.
-      refresh(router);
+      // Lazy fallback for out-of-window slots and window-less legacy
+      // state: re-resolving the landed entry also re-serializes the
+      // window into it via the replace commit. A guard failure here
+      // must not surface as an unhandled rejection — the landed entry
+      // simply keeps its(unknown) view.
+      refresh(router).catch(util.noop);
     } else if (action === 'POP') {
       // Sync the current window into the landed entry so a later
       // refresh("refresh → back → refresh again") still restores it.
@@ -421,15 +712,20 @@ function listen(router, onViewChange) {
 }
 
 /**
- * Merge params of all matched levels. Params of deeper levels override
+ * Merge params of the matched levels. Params of deeper levels override
  * the same keys of shallower ones.
+ *
+ * When `end` is given, only the levels up to and including `end` are
+ * merged — the accumulated params a level at index `end` sees(shallow →
+ * current level). Omitting `end` merges every level.
  * @group Methods
  * @category Router
  * @param matched matched route levels, see {@link match}
+ * @param end the index of the last level to merge, defaults to the deepest
  * @returns the merged params object
  */
-function mergeMatchedParams(matched) {
-  return matched.reduce((params, {
+function mergeMatchedParams(matched, end) {
+  return matched.slice(0, end === undefined ? matched.length : end + 1).reduce((params, {
     params: levelParams
   }) => ({
     ...params,
@@ -438,7 +734,11 @@ function mergeMatchedParams(matched) {
 }
 
 /**
- * Get current route params from router. Merges params of all matched levels.
+ * Get current route params from router. The params are re-derived by
+ * matching the current entry of {@link RouterInstance.locationStack} so
+ * they stay correct even when the view stack holds resolved views
+ * (e.g. React elements) instead of match results. Merges params of all
+ * matched levels; deeper levels override shallower ones.
  * @group Methods
  * @category Router
  * @param router router instance
@@ -448,13 +748,14 @@ function getParams(router) {
   const {
     index
   } = getHistoryState(router);
-  const matched = router.viewStack[index];
-  if (!matched || !matched.length) return {};
-  return mergeMatchedParams(matched);
+  const location = router.locationStack[index - router.baseIndex];
+  if (!location) return {};
+  return mergeMatchedParams(match(router, location.pathname) ?? []);
 }
 
 exports.NativeRouterError = NativeRouterError;
 exports.NotFoundError = NotFoundError;
+exports.RedirectLoopError = RedirectLoopError;
 exports.back = back;
 exports.cancel = cancel;
 exports.commit = commit;
@@ -471,8 +772,10 @@ exports.listen = listen;
 exports.match = match;
 exports.mergeMatchedParams = mergeMatchedParams;
 exports.navigate = navigate;
+exports.preload = preload;
 exports.refresh = refresh;
 exports.resolve = resolve;
+exports.resolveEntry = resolveEntry;
 exports.resolveTo = resolveTo;
 exports.setOptions = setOptions;
 exports.toLocation = toLocation;