@native-router/core 1.2.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
@@ -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,7 @@ 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
@@ -164,16 +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;
 /**
- * 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
  */
-export declare function mergeMatchedParams<R extends BaseRoute = BaseRoute>(matched: Matched<R>[]): Record<string, string>;
+export declare function mergeMatchedParams<R extends BaseRoute = BaseRoute>(matched: Matched<R>[], end?: number): Record<string, string>;
 /**
- * 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

package/dist/types/types.d.ts

@@ -22,9 +22,59 @@ export type HistoryState = {
 };
 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@native-router/core",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",