@native-router/core 1.1.0 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 [![npm](https://img.shields.io/npm/v/@native-router/core.svg)](https://www.npmjs.com/package/@native-router/core)
-[![Build Status](https://github.com/wmzy/@native-router/core/actions/workflows/ci.yml/badge.svg)](https://github.com/wmzy/@native-router/core/actions)
-[![Coverage](https://img.shields.io/codecov/c/github/wmzy/@native-router/core.svg)](https://codecov.io/gh/wmzy/@native-router/core)
+[![Build Status](https://github.com/native-router/core/actions/workflows/ci.yml/badge.svg)](https://github.com/native-router/core/actions)
+[![Coverage](https://img.shields.io/codecov/c/github/native-router/core.svg)](https://codecov.io/gh/native-router/core)
 [![install size](https://packagephobia.now.sh/badge?p=@native-router/core)](https://packagephobia.now.sh/result?p=@native-router/core)
 
 # Native Router React
@@ -18,6 +18,10 @@ English | [简体中文](./README-zh_CN.md)
 - Most unused features can be tree-shaking
 - SSR support
 
+## Matching semantics
+
+Routes are matched in declaration order and the first match wins — there is no sorting by specificity. Trailing slashes are significant (`/users/` does not match `/users`). Matching is case-sensitive.
+
 ## Install
 
 ```bash
@@ -76,4 +80,4 @@ See [demos](/demos/) for a complete example.
 
 ## Documentation 
 
-[API](https://wmzy.github.io/@native-router/core/modules.html)
+[API](https://native-router.github.io/core/modules.html)

package/dist/index.cjs

@@ -13,6 +13,8 @@ class NotFoundError extends NativeRouterError {
   }
 }
 
+const DEFAULT_MAX_STACK_DEPTH = 100;
+
 /**
  * Create a router instance.
  * @group Methods
@@ -26,12 +28,15 @@ class NotFoundError extends NativeRouterError {
 function create(routes, history, resolveView, options) {
   const [currentGuard, cancelAll] = util.createCurrentGuard();
   const {
-    index,
-    locationStack
+    index
   } = getHistoryState({
     history: history
   });
-  const viewStack = new Array(locationStack.length).fill(null);
+  // 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;
   }
@@ -45,7 +50,8 @@ function create(routes, history, resolveView, options) {
     cancelAll,
     errorHandler: util.reject,
     ...options,
-    baseUrl: options?.baseUrl || ''
+    baseUrl: options?.baseUrl || '',
+    maxStackDepth: options?.maxStackDepth || DEFAULT_MAX_STACK_DEPTH
   };
 }
 function setOptions(router, options) {
@@ -60,14 +66,43 @@ function getLocation({
     state: state.state
   };
 }
-function getHistoryState(router) {
+
+/**
+ * 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.
+ */
+function restoreLocationStack(history) {
+  const state = history.location.state || {};
   const {
-    location
-  } = router.history;
-  const state = location.state || {};
+    locationStack,
+    base
+  } = state;
+  return locationStack?.length ? [...new Array(base || 0), ...locationStack] : [getLocation({
+    history
+  })];
+}
+
+/**
+ * Serialize the tail window of the in-memory stack, bounded by
+ * `maxStackDepth`, together with the absolute index of its first entry.
+ */
+function serializeStack(router) {
+  const {
+    locationStack,
+    maxStackDepth
+  } = router;
+  const windowed = locationStack.slice(-maxStackDepth);
+  return {
+    base: locationStack.length - windowed.length,
+    locationStack: windowed
+  };
+}
+function getHistoryState(router) {
+  const state = router.history.location.state || {};
   return {
-    index: state.index || 0,
-    locationStack: state.locationStack || [getLocation(router)]
+    index: state.index || 0
   };
 }
 function getCurrentView(router) {
@@ -189,8 +224,8 @@ function commit(router, resolvePromise, location) {
     router.viewStack = [...router.viewStack.slice(0, nextIndex), resolvedView];
     history.push(location, {
       index: nextIndex,
-      locationStack: router.locationStack,
-      state: location.state
+      state: location.state,
+      ...serializeStack(router)
     });
   });
 }
@@ -215,8 +250,8 @@ function commitReplace(router, resolvePromise, location) {
     router.viewStack[index] = resolvedView;
     history.replace(location, {
       index,
-      locationStack: router.locationStack,
-      state: location.state
+      state: location.state,
+      ...serializeStack(router)
     });
   });
 }
@@ -324,16 +359,21 @@ function cancel({
   cancelAll();
   onLoadingChange();
 }
+
+/**
+ * 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
+ */
 function initHistoryStack(router) {
-  const {
-    history: history$1
-  } = router;
-  const {
-    locationStack
-  } = getHistoryState(router);
-  return Promise.all(locationStack.map(l => resolve(router, l))).then(views => {
+  return Promise.all(router.locationStack.map(location => location ? resolve(router, location) : Promise.resolve(null))).then(views => {
     router.viewStack = views;
-    history$1.replace(history.createPath(history$1.location), history$1.location.state);
   });
 }
 
@@ -358,11 +398,18 @@ function listen(router, onViewChange) {
     const index = state?.index || 0;
     const view = router.viewStack[index];
     onViewChange(view);
-    if (!view) refresh(router);
-    if (action === 'POP') {
+    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);
+    } else if (action === 'POP') {
+      // Sync the current window into the landed entry so a later
+      // refresh("refresh → back → refresh again") still restores it.
       history$1.replace(history.createPath(history$1.location), {
         ...state,
-        locationStack: router.locationStack
+        index,
+        ...serializeStack(router)
       });
     }
   });
@@ -374,7 +421,24 @@ function listen(router, onViewChange) {
 }
 
 /**
- * Get current route params from router.
+ * Merge params of all matched levels. Params of deeper levels override
+ * the same keys of shallower ones.
+ * @group Methods
+ * @category Router
+ * @param matched matched route levels, see {@link match}
+ * @returns the merged params object
+ */
+function mergeMatchedParams(matched) {
+  return matched.reduce((params, {
+    params: levelParams
+  }) => ({
+    ...params,
+    ...levelParams
+  }), {});
+}
+
+/**
+ * Get current route params from router. Merges params of all matched levels.
  * @group Methods
  * @category Router
  * @param router router instance
@@ -386,7 +450,7 @@ function getParams(router) {
   } = getHistoryState(router);
   const matched = router.viewStack[index];
   if (!matched || !matched.length) return {};
-  return matched[matched.length - 1]?.params ?? {};
+  return mergeMatchedParams(matched);
 }
 
 exports.NativeRouterError = NativeRouterError;
@@ -405,6 +469,7 @@ exports.go = go;
 exports.initHistoryStack = initHistoryStack;
 exports.listen = listen;
 exports.match = match;
+exports.mergeMatchedParams = mergeMatchedParams;
 exports.navigate = navigate;
 exports.refresh = refresh;
 exports.resolve = resolve;

package/dist/index.mjs

@@ -11,6 +11,8 @@ class NotFoundError extends NativeRouterError {
   }
 }
 
+const DEFAULT_MAX_STACK_DEPTH = 100;
+
 /**
  * Create a router instance.
  * @group Methods
@@ -24,12 +26,15 @@ class NotFoundError extends NativeRouterError {
 function create(routes, history, resolveView, options) {
   const [currentGuard, cancelAll] = createCurrentGuard();
   const {
-    index,
-    locationStack
+    index
   } = getHistoryState({
     history: history
   });
-  const viewStack = new Array(locationStack.length).fill(null);
+  // 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;
   }
@@ -43,7 +48,8 @@ function create(routes, history, resolveView, options) {
     cancelAll,
     errorHandler: reject,
     ...options,
-    baseUrl: options?.baseUrl || ''
+    baseUrl: options?.baseUrl || '',
+    maxStackDepth: options?.maxStackDepth || DEFAULT_MAX_STACK_DEPTH
   };
 }
 function setOptions(router, options) {
@@ -58,14 +64,43 @@ function getLocation({
     state: state.state
   };
 }
-function getHistoryState(router) {
+
+/**
+ * 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.
+ */
+function restoreLocationStack(history) {
+  const state = history.location.state || {};
   const {
-    location
-  } = router.history;
-  const state = location.state || {};
+    locationStack,
+    base
+  } = state;
+  return locationStack?.length ? [...new Array(base || 0), ...locationStack] : [getLocation({
+    history
+  })];
+}
+
+/**
+ * Serialize the tail window of the in-memory stack, bounded by
+ * `maxStackDepth`, together with the absolute index of its first entry.
+ */
+function serializeStack(router) {
+  const {
+    locationStack,
+    maxStackDepth
+  } = router;
+  const windowed = locationStack.slice(-maxStackDepth);
+  return {
+    base: locationStack.length - windowed.length,
+    locationStack: windowed
+  };
+}
+function getHistoryState(router) {
+  const state = router.history.location.state || {};
   return {
-    index: state.index || 0,
-    locationStack: state.locationStack || [getLocation(router)]
+    index: state.index || 0
   };
 }
 function getCurrentView(router) {
@@ -187,8 +222,8 @@ function commit(router, resolvePromise, location) {
     router.viewStack = [...router.viewStack.slice(0, nextIndex), resolvedView];
     history.push(location, {
       index: nextIndex,
-      locationStack: router.locationStack,
-      state: location.state
+      state: location.state,
+      ...serializeStack(router)
     });
   });
 }
@@ -213,8 +248,8 @@ function commitReplace(router, resolvePromise, location) {
     router.viewStack[index] = resolvedView;
     history.replace(location, {
       index,
-      locationStack: router.locationStack,
-      state: location.state
+      state: location.state,
+      ...serializeStack(router)
     });
   });
 }
@@ -322,16 +357,21 @@ function cancel({
   cancelAll();
   onLoadingChange();
 }
+
+/**
+ * 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
+ */
 function initHistoryStack(router) {
-  const {
-    history
-  } = router;
-  const {
-    locationStack
-  } = getHistoryState(router);
-  return Promise.all(locationStack.map(l => resolve(router, l))).then(views => {
+  return Promise.all(router.locationStack.map(location => location ? resolve(router, location) : Promise.resolve(null))).then(views => {
     router.viewStack = views;
-    history.replace(createPath(history.location), history.location.state);
   });
 }
 
@@ -356,11 +396,18 @@ function listen(router, onViewChange) {
     const index = state?.index || 0;
     const view = router.viewStack[index];
     onViewChange(view);
-    if (!view) refresh(router);
-    if (action === 'POP') {
+    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);
+    } else if (action === 'POP') {
+      // Sync the current window into the landed entry so a later
+      // refresh("refresh → back → refresh again") still restores it.
       history.replace(createPath(history.location), {
         ...state,
-        locationStack: router.locationStack
+        index,
+        ...serializeStack(router)
       });
     }
   });
@@ -372,7 +419,24 @@ function listen(router, onViewChange) {
 }
 
 /**
- * Get current route params from router.
+ * Merge params of all matched levels. Params of deeper levels override
+ * the same keys of shallower ones.
+ * @group Methods
+ * @category Router
+ * @param matched matched route levels, see {@link match}
+ * @returns the merged params object
+ */
+function mergeMatchedParams(matched) {
+  return matched.reduce((params, {
+    params: levelParams
+  }) => ({
+    ...params,
+    ...levelParams
+  }), {});
+}
+
+/**
+ * Get current route params from router. Merges params of all matched levels.
  * @group Methods
  * @category Router
  * @param router router instance
@@ -384,7 +448,7 @@ function getParams(router) {
   } = getHistoryState(router);
   const matched = router.viewStack[index];
   if (!matched || !matched.length) return {};
-  return matched[matched.length - 1]?.params ?? {};
+  return mergeMatchedParams(matched);
 }
 
-export { NativeRouterError, NotFoundError, back, cancel, commit, commitReplace, create, createHref, forward, getCurrentView, getLocation, getParams, go, initHistoryStack, listen, match, navigate, refresh, resolve, resolveTo, setOptions, toLocation };
+export { NativeRouterError, NotFoundError, back, cancel, commit, commitReplace, create, createHref, forward, getCurrentView, getLocation, getParams, go, initHistoryStack, listen, match, mergeMatchedParams, navigate, refresh, resolve, resolveTo, setOptions, toLocation };

package/dist/types/router.d.ts

@@ -23,7 +23,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;
@@ -142,6 +142,17 @@ export declare function createHref<R extends BaseRoute = BaseRoute, V = any>({ b
  * @param router router instance
  */
 export declare function cancel<R extends BaseRoute = BaseRoute, V = any>({ cancelAll, onLoadingChange }: 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 +164,16 @@ 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 all matched levels. Params of deeper levels override
+ * the same keys of shallower ones.
+ * @group Methods
+ * @category Router
+ * @param matched matched route levels, see {@link match}
+ * @returns the merged params object
+ */
+export declare function mergeMatchedParams<R extends BaseRoute = BaseRoute>(matched: Matched<R>[]): Record<string, string>;
+/**
+ * Get current route params from router. Merges params of all matched levels.
  * @group Methods
  * @category Router
  * @param router router instance

package/dist/types/types.d.ts

@@ -4,9 +4,21 @@ 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>;
@@ -27,6 +39,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 +64,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.2.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"
   }
 }