@native-router/core 1.2.0 → 1.4.0

package/dist/types/errors.d.ts

@@ -1,5 +1,22 @@
+import type { StandardSchemaV1 } from './types';
 export declare class NativeRouterError extends Error {
 }
 export declare class NotFoundError extends NativeRouterError {
     constructor(pathname: string);
 }
+export declare class RedirectLoopError extends NativeRouterError {
+    constructor(target?: string);
+}
+/**
+ * Thrown when a route {@link BaseRoute.search search schema} rejects the
+ * location search. Issues are formatted as `path: message` pairs joined
+ * with `; `, e.g.
+ * `Invalid search params "?page=abc": page: Expected a positive integer`.
+ */
+export declare class SearchError extends NativeRouterError {
+    /** The raw search string that failed validation. */
+    readonly search: string;
+    /** The issues reported by the schema. */
+    readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
+    constructor(search: string, issues: ReadonlyArray<StandardSchemaV1.Issue>);
+}

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
 export * from './router';
 export * from './errors';
+export * from './search';
 export type * from './types';

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/search.d.ts

@@ -0,0 +1,45 @@
+import type { SearchInput, SearchOutputOf, StandardSchemaV1 } from './types';
+/**
+ * Parse a raw search string(e.g. `?page=2&tag=a&tag=b`) into the plain
+ * input object consumed by {@link StandardSchemaV1 search schemas}:
+ * single-valued keys are strings, keys repeated in the query string are
+ * arrays of their values. An empty search is `{}`.
+ *
+ * This is also the degraded shape every search API falls back to when no
+ * schema is given.
+ * @group Methods
+ * @category Route
+ * @param search the raw `location.search` string, with or without `?`
+ * @returns the input object for schema validation
+ */
+export declare function parseSearchInput(search: string): SearchInput;
+/**
+ * Validate a search string with a {@link StandardSchemaV1} schema — any
+ * zod/valibot/arktype schema works, no hard dependency. The string is
+ * first degraded via {@link parseSearchInput}, then parsed by the schema,
+ * so schemas can coerce(`'2'` → `2`) and normalize along the way.
+ *
+ * Async schemas(`validate` returning a promise) are awaited.
+ *
+ * @group Methods
+ * @category Route
+ * @param schema the search schema
+ * @param search the raw `location.search` string
+ * @returns the parsed(and possibly coerced) output of the schema
+ * @throws {SearchError} when the schema reports issues
+ */
+export declare function parseSearch<S extends StandardSchemaV1>(schema: S, search: string): Promise<SearchOutputOf<S>>;
+/**
+ * Synchronous flavor of {@link parseSearch}, for render-time reads(see
+ * `useSearch` of `@native-router/react`) and route guards.
+ *
+ * @group Methods
+ * @category Route
+ * @param schema the search schema — must validate synchronously
+ * @param search the raw `location.search` string
+ * @returns the parsed(and possibly coerced) output of the schema
+ * @throws {SearchError} when the schema reports issues
+ * @throws when the schema validates asynchronously; use {@link parseSearch}
+ * for async schemas instead
+ */
+export declare function parseSearchSync<S extends StandardSchemaV1>(schema: S, search: string): SearchOutputOf<S>;

package/dist/types/types.d.ts

@@ -22,9 +22,124 @@ export type HistoryState = {
 };
 export type WrappedLocation = Location<HistoryState>;
 export type Awaitable<T> = T | Promise<T>;
+/**
+ * The [Standard Schema](https://standardschema.dev) interface, version 1 —
+ * the common validation interface implemented by zod, valibot and arktype.
+ *
+ * Inlined type-only from `@standard-schema/spec` so the core keeps zero
+ * extra runtime dependencies: any schema exposing `~standard` works.
+ * @group Types
+ * @category Route
+ */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+export declare namespace StandardSchemaV1 {
+    interface Props<Input = unknown, Output = Input> {
+        /** The version number of the standard. */
+        readonly version: 1;
+        /** The vendor name of the schema library. */
+        readonly vendor: string;
+        /** Validates unknown input values. */
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+    }
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    interface SuccessResult<Output> {
+        /** The typed output value. */
+        readonly value: Output;
+        /** The issues of the input value. */
+        readonly issues?: undefined;
+    }
+    interface FailureResult {
+        /** The issues of the input value. */
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    interface Issue {
+        /** The issue message. */
+        readonly message: string;
+        /** The issue path. */
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment>;
+    }
+    interface PathSegment {
+        /** The key of the path segment. */
+        readonly key: PropertyKey;
+    }
+}
+/**
+ * The plain input object a search string degrades into before schema
+ * validation: single-valued keys are strings, keys repeated in the query
+ * string are arrays of their values.
+ * @group Types
+ * @category Route
+ */
+export type SearchInput = Record<string, string | string[]>;
+/**
+ * Parsed output type of a {@link StandardSchemaV1 search schema}.
+ * @group Types
+ * @category Route
+ */
+export type SearchOutputOf<S> = S extends StandardSchemaV1<any, infer Output> ? Output : never;
+/**
+ * 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;
+    /**
+     * Optional Standard Schema(zod/valibot/arktype, ...) validator of the
+     * route search. Frameworks parse `location.search` with it at resolve
+     * time(see `parseSearch`) and inject the parsed output into their data
+     * contexts; a validation failure fails the resolve like any other
+     * navigation error.
+     */
+    search?: StandardSchemaV1;
+    /**
+     * 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.4.0",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",