@native-router/core 1.1.0 → 1.3.0

package/dist/types/router.d.ts

@@ -1,5 +1,14 @@
 import { History } from 'history';
 import type { Location, Matched, Options, BaseRoute, RouterInstance, ResolveView } from './types';
+/**
+ * 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.
+ */
+export type ResolvedEntry<V> = {
+    location: Location;
+    task: Promise<V>;
+};
 /**
  * Create a router instance.
  * @group Methods
@@ -23,7 +32,7 @@ export declare function setOptions<R extends BaseRoute = BaseRoute, V = any>(rou
     currentGuard<T>(promise: Promise<T>): Promise<T>;
     cancelAll(): void;
     resolving?: Location;
-} & Required<Pick<Options<V>, "baseUrl">> & Omit<Options<V>, "baseUrl"> & Omit<Options<V>, "currentView">;
+} & Required<Pick<Options<V>, "baseUrl" | "maxStackDepth">> & Omit<Options<V>, "baseUrl" | "maxStackDepth"> & Omit<Options<V>, "currentView">;
 export declare function getLocation({ history }: Pick<RouterInstance<any>, 'history'>): {
     state: any;
     key: import("history").Key;
@@ -70,6 +79,51 @@ export declare function resolve<R extends BaseRoute = BaseRoute, V = any>(router
  * @returns resolve task(a promise)
  */
 export declare function resolveTo<R extends BaseRoute = BaseRoute, V = any>(router: RouterInstance<R, V>, to: string, state?: any): Promise<V>;
+/**
+ * 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
+ */
+export declare function resolveEntry<R extends BaseRoute = BaseRoute, V = any>(router: RouterInstance<R, V>, location: Location): Promise<ResolvedEntry<V>>;
+/**
+ * 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
+ */
+export declare function preload<R extends BaseRoute = BaseRoute, V = any>(router: RouterInstance<R, V>, to: string, opts?: {
+    ttl?: number;
+}): Promise<ResolvedEntry<V>>;
 /**
  * Commit the resolve task and push history.
  * @group Methods
@@ -89,7 +143,11 @@ export declare function commit<R extends BaseRoute = BaseRoute, V = any>(router:
  */
 export declare function commitReplace<R extends BaseRoute = BaseRoute, V = any>(router: RouterInstance<R, V>, resolvePromise: Promise<V>, location: Location): Promise<void>;
 /**
- * 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
@@ -98,7 +156,8 @@ 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.
+ * 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
@@ -141,7 +200,18 @@ export declare function createHref<R extends BaseRoute = BaseRoute, V = any>({ b
  * @category Router
  * @param router router instance
  */
-export declare function cancel<R extends BaseRoute = BaseRoute, V = any>({ cancelAll, onLoadingChange }: RouterInstance<R, V>): void;
+export declare function cancel<R extends BaseRoute = BaseRoute, V = any>(router: RouterInstance<R, V>): void;
+/**
+ * Restore/warm up the view stack by re-resolving every reachable entry
+ * of the in-memory location stack. Call it after a refresh: in-window
+ * back/forward then switch views without new resolves.
+ *
+ * 恢复/预热内存栈中的可达条目（窗口内有 location 的槽位），刷新后调用
+ * 可让窗口内前进/后退零请求。
+ * @group Methods
+ * @category Router
+ * @param router router instance
+ */
 export declare function initHistoryStack<R extends BaseRoute = BaseRoute, V = any>(router: RouterInstance<R, V>): Promise<void>;
 /**
  * Listen the history change.
@@ -153,7 +223,25 @@ export declare function initHistoryStack<R extends BaseRoute = BaseRoute, V = an
  */
 export declare function listen<R extends BaseRoute = BaseRoute, V = any>(router: RouterInstance<R, V>, onViewChange: (v: V) => void): () => void;
 /**
- * Get current route params from router.
+ * 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
+ */
+export declare function mergeMatchedParams<R extends BaseRoute = BaseRoute>(matched: Matched<R>[], end?: number): Record<string, string>;
+/**
+ * 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

package/dist/types/types.d.ts

@@ -4,15 +4,77 @@ export type Location<T = any> = HPath & {
     state?: T;
 };
 export type HistoryState = {
-    locationStack: Location[];
     index: number;
     state?: any;
+    /**
+     * Bounded window(tail entries) of the session location stack,
+     * serialized into the history entry so {@link create} can restore it
+     * after a refresh. Its length never exceeds `maxStackDepth`.
+     * 有界窗口：会话 locationStack 的尾部条目，刷新后据此恢复内存栈。
+     */
+    locationStack?: Location[];
+    /**
+     * Absolute stack index of `locationStack[0]`; omitted(or 0) means the
+     * window starts at the session root.
+     * locationStack[0] 对应的绝对 index，省略时为 0。
+     */
+    base?: number;
 };
 export type WrappedLocation = Location<HistoryState>;
 export type Awaitable<T> = T | Promise<T>;
+/**
+ * Params contributed by a single path segment: `:name` is required,
+ * `:name?` is optional, anything else(static or wildcard) 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.
+ * @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;
+} : {};
+/**
+ * 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}`.
+ *
+ * Within the modeled path-to-regexp 6 syntax scope(see
+ * {@link PathParamsOf}); wildcards(`*`) and static segments are
+ * ignored. Distributes over unions of patterns.
+ * @group Types
+ * @category Route
+ */
+export type ExtractPathParams<P extends string> = P extends `${infer Head}/${infer Rest}` ? PathParamsOf<Head> & ExtractPathParams<Rest> : PathParamsOf<P>;
+/**
+ * Context passed to a route guard({@link BaseRoute.beforeLoad beforeLoad}).
+ * `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> = {
+    router: RouterInstance<R>;
+    location: Location;
+    params: Record<string, string>;
+};
 export type BaseRoute<T = any> = {
     path?: Path;
     children?: BaseRoute<T>[];
+    /**
+     * Static redirect target. When set, navigating to this route is
+     * redirected to the target path before the view resolves.
+     */
+    redirect?: string;
+    /**
+     * Route guard invoked before the view resolves. Return a path string
+     * to redirect, or nothing(`undefined`) to continue.
+     */
+    beforeLoad?(ctx: GuardContext<BaseRoute<T>>): Awaitable<string | void>;
 } & Omit<T, 'path' | 'children'>;
 export type Matched<R extends BaseRoute = BaseRoute> = {
     route: R;
@@ -27,6 +89,22 @@ export type Options<V> = {
     currentView?: V;
     errorHandler?(e: Error): V | Promise<V>;
     onLoadingChange?(status?: 'pending' | 'resolved' | 'rejected'): void;
+    /**
+     * Max number of locations serialized into the history state window,
+     * see {@link HistoryState.locationStack}.
+     *
+     * Defaults to 100, at or above the per-tab history caps of mainstream
+     * browsers(Chromium/Gecko ~50, WebKit ~100). The window boundary can
+     * therefore only appear after the browser itself has already evicted
+     * entries: anything outside the window is unreachable to the user, so
+     * a bounded window is observationally equivalent to full serialization.
+     *
+     * 序列化进 history state 的栈窗口上限，默认 100，不低于主流浏览器
+     * 单标签历史上限（Chromium/Gecko 约 50、WebKit 约 100）。窗口边界只会在
+     * 浏览器自身裁剪历史之后才可能出现，用户不可达窗口外条目，行为与
+     * 全量序列化无可观察差异。
+     */
+    maxStackDepth?: number;
 };
 export type RequiredOf<T, K extends keyof T> = Required<Pick<T, K>> & Omit<T, K>;
 export type RouterInstance<R extends BaseRoute, V = any> = {
@@ -36,9 +114,15 @@ export type RouterInstance<R extends BaseRoute, V = any> = {
         location: WrappedLocation;
     };
     viewStack: V[];
+    /**
+     * In-memory location stack of the current session. On creation it is
+     * restored from the bounded window serialized in the history state,
+     * so in-window back/forward survive a refresh.
+     * 会话内存栈；create 时从 history state 的有界窗口恢复。
+     */
     locationStack: Location[];
     resolveView: ResolveView<R, V>;
     currentGuard<T>(promise: Promise<T>): Promise<T>;
     cancelAll(): void;
     resolving?: Location;
-} & RequiredOf<Options<V>, 'baseUrl'>;
+} & RequiredOf<Options<V>, 'baseUrl' | 'maxStackDepth'>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@native-router/core",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
@@ -27,14 +27,14 @@
     "dist"
   ],
   "scripts": {
-    "start": "npm test -- --watch",
+    "start": "vitest",
     "build": "rm -rf dist && rollup -c && tsc -p tsconfig.production.json && tsc-alias -p tsconfig.production.json",
     "commit": "lint-staged && git-cz -n",
-    "coverage": "nyc report --reporter=text-lcov > ./.nyc_output/coverage.txt",
+    "coverage": "vitest run --coverage",
     "lint": "eslint --fix src test *.js --ext .js,.jsx,.ts,.tsx",
     "doc:gen": "typedoc",
     "deploy": "npm run doc:gen && gh-pages -d dist",
-    "test": "cross-env NODE_ENV=test nyc mocha"
+    "test": "vitest run"
   },
   "repository": {
     "type": "git",
@@ -48,7 +48,7 @@
   },
   "homepage": "https://github.com/native-router/core",
   "engines": {
-    "node": ">=14"
+    "node": ">=18"
   },
   "dependencies": {
     "history": "^5.3.0",
@@ -58,22 +58,17 @@
     "@babel/core": "^7.22.9",
     "@babel/preset-env": "^7.22.9",
     "@babel/preset-typescript": "^7.22.5",
-    "@babel/register": "^7.22.5",
-    "@linaria/babel-preset": "^4.5.4",
-    "@linaria/core": "^4.5.4",
     "@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/mocha": "^10.0.1",
     "@types/node": "^20.4.5",
     "@types/sinon": "^10.0.15",
     "@typescript-eslint/eslint-plugin": "^6.2.0",
     "@typescript-eslint/parser": "^6.2.0",
-    "babel-plugin-module-resolver": "^5.0.0",
+    "@vitest/coverage-v8": "^4.0.18",
     "commitizen": "^4.3.0",
     "core-js": "^3.31.1",
-    "coveralls": "^3.1.1",
     "cross-env": "^7.0.3",
     "eslint": "^8.50.0",
     "eslint-config-airbnb": "^19.0.4",
@@ -83,17 +78,12 @@
     "eslint-plugin-compat": "^4.1.4",
     "eslint-plugin-import": "^2.27.5",
     "eslint-plugin-jsx-a11y": "^6.7.1",
-    "eslint-plugin-mocha": "^10.1.0",
     "eslint-plugin-prettier": "^5.0.0",
     "eslint-plugin-react": "^7.33.0",
     "eslint-plugin-react-hooks": "^4.6.0",
     "gh-pages": "^5.0.0",
-    "global-jsdom": "^9.0.1",
     "husky": "^8.0.3",
-    "jsdom": "^22.1.0",
     "lint-staged": "^13.2.3",
-    "mocha": "^10.2.0",
-    "nyc": "^15.1.0",
     "prettier": "^3.0.0",
     "rollup": "^3.28.0",
     "should": "^13.2.3",
@@ -105,6 +95,7 @@
     "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"
   }
 }