@vobs/router 1.1.0 → 1.2.0

package/dist/index.d.cts

@@ -0,0 +1,215 @@
+import { Signal } from '@vobs/reactivity';
+import { VobsNode, InjectionKey, VobsPlugin } from '@vobs/vobs';
+export { RouterDebugEvent, RouterDebugEventType, createRouterDebugId, emitRouterDebug, subscribeRouterDebug } from './debug.cjs';
+import '@vobs/runtime';
+
+type RouteParams = Readonly<Record<string, string>>;
+type RouteQueryValue = string | readonly string[];
+type RouteQuery = Readonly<Record<string, RouteQueryValue>>;
+type RouteMeta = Readonly<Record<string, unknown>>;
+interface RouteLocation {
+    readonly path: string;
+    readonly fullPath: string;
+    readonly params: RouteParams;
+    readonly query: RouteQuery;
+    readonly hash: string;
+    readonly name: string | undefined;
+    readonly meta: RouteMeta;
+    readonly record: RouteRecord | null;
+    readonly matched: readonly RouteRecord[];
+    readonly state?: unknown;
+}
+interface RouteComponentProps {
+    readonly route: RouteLocation;
+    readonly params: RouteParams;
+    readonly query: RouteQuery;
+    readonly children?: VobsNode;
+}
+type RouteComponent = (props: RouteComponentProps) => VobsNode;
+type RouteComponentModule = RouteComponent | {
+    default: RouteComponent;
+};
+type RouteComponentLoader = () => PromiseLike<RouteComponentModule>;
+interface LazyRouteComponent {
+    readonly kind: 'vobs-lazy-route';
+    readonly load: RouteComponentLoader;
+}
+type RouteComponentDefinition = RouteComponent | LazyRouteComponent;
+interface RouteLoaderContext {
+    readonly route: RouteLocation;
+    readonly navigationId?: number;
+    readonly dataRequestId?: number;
+}
+type RouteLoader = (context: RouteLoaderContext) => unknown | PromiseLike<unknown>;
+interface RouteRecord {
+    readonly path?: string;
+    readonly component?: RouteComponentDefinition;
+    readonly source?: string;
+    readonly name?: string;
+    readonly meta?: Record<string, unknown>;
+    readonly loader?: RouteLoader;
+    readonly action?: RouteLoader;
+    readonly children?: readonly RouteRecord[];
+}
+type RouteQueryInput = Record<string, unknown> | URLSearchParams;
+interface RouteLocationRaw {
+    readonly path?: string;
+    readonly name?: string;
+    readonly params?: Record<string, unknown>;
+    readonly query?: RouteQueryInput;
+    readonly hash?: string;
+    readonly state?: unknown;
+}
+type RouteTarget = string | RouteLocationRaw;
+type NavigationGuardResult = void | boolean | RouteTarget;
+type NavigationGuard = (to: RouteLocation, from: RouteLocation) => NavigationGuardResult | PromiseLike<NavigationGuardResult>;
+declare class NavigationCancelledError extends Error {
+    readonly code = "NAVIGATION_CANCELLED";
+    constructor();
+}
+declare class NavigationRedirectError extends Error {
+    readonly code = "NAVIGATION_REDIRECT_LIMIT";
+    constructor();
+}
+interface RouterHistory {
+    readonly location: string;
+    /** 当前 history 条目携带的导航 state（push/replace 时写入，popstate/初始启动时回读）。 */
+    readonly state?: unknown;
+    push(path: string, state?: unknown): void;
+    replace(path: string, state?: unknown): void;
+    back(): void;
+    listen(listener: (path: string, state: unknown) => void): () => void;
+}
+interface RouterOptions {
+    readonly routes: readonly RouteRecord[];
+    readonly history?: RouterHistory;
+}
+interface RouterViewState {
+    readonly status: 'ready' | 'loading' | 'error' | 'not-found';
+    readonly component?: RouteComponent;
+    readonly layouts?: readonly RouteComponent[];
+    readonly error?: Error;
+    readonly retry: () => void;
+}
+interface RouteDebugNode {
+    readonly id: string;
+    readonly path: string;
+    readonly name?: string;
+    readonly component: string;
+    readonly lazy: boolean;
+    readonly loader: boolean;
+    readonly action: boolean;
+    readonly status: 'ready' | 'loading' | 'error';
+    readonly meta: RouteMeta;
+    readonly source?: string;
+    readonly children: readonly RouteDebugNode[];
+}
+interface RouteErrorTrace {
+    readonly id: number;
+    readonly phase: 'navigation' | 'render' | 'lazy' | 'loader' | 'action' | 'fetcher';
+    readonly route: string;
+    readonly message: string;
+    readonly stack?: string;
+    readonly timestamp: number;
+    readonly requestId?: number;
+    readonly navigationId?: number;
+}
+interface NavigationTrace {
+    readonly id: number;
+    readonly from: string;
+    readonly to: string;
+    readonly status: 'success' | 'redirected' | 'cancelled' | 'error';
+    readonly source: 'push' | 'replace' | 'history';
+    readonly startedAt: number;
+    readonly endedAt: number;
+    readonly duration: number;
+    readonly redirect?: string;
+    readonly error?: string;
+}
+interface NavigationState {
+    readonly status: 'idle' | 'loading' | 'error';
+    readonly from: string;
+    readonly to: string;
+    readonly traceId?: number;
+    readonly error?: string;
+}
+interface RouterPerformanceMetrics {
+    readonly navigationCount: number;
+    readonly averageNavigationDuration: number;
+    readonly slowNavigationCount: number;
+}
+type RouterDataRequestKind = 'loader' | 'action' | 'fetcher';
+interface RouterDataRequestTrace {
+    readonly id: number;
+    readonly kind: RouterDataRequestKind;
+    readonly key: string;
+    readonly route?: string;
+    readonly status: 'loading' | 'success' | 'error' | 'cancelled';
+    readonly startedAt: number;
+    readonly endedAt?: number;
+    readonly duration?: number;
+    readonly result?: unknown;
+    readonly error?: string;
+    readonly navigationId?: number;
+    readonly trigger?: 'navigation' | 'revalidate' | 'manual' | 'resource';
+    readonly environment?: 'client' | 'server';
+}
+interface RouterDataRequestOptions {
+    readonly route?: string;
+    readonly navigationId?: number;
+    readonly trigger?: 'navigation' | 'revalidate' | 'manual' | 'resource';
+    readonly environment?: 'client' | 'server';
+}
+type RouterDevToolsEvent = 'navigation:start' | 'navigation:end' | 'route:update' | 'data-request' | 'error';
+interface RouterDevToolsAPI {
+    getRouteTree(): readonly RouteDebugNode[];
+    getCurrentRoute(): RouteLocation;
+    getNavigationState(): NavigationState;
+    getNavigationHistory(): readonly NavigationTrace[];
+    getPerformanceMetrics(): RouterPerformanceMetrics;
+    getDataRequests(): readonly RouterDataRequestTrace[];
+    getErrors(): readonly RouteErrorTrace[];
+    trackDataRequest<T>(kind: RouterDataRequestKind, key: string, task: () => T | PromiseLike<T>, options?: RouterDataRequestOptions | string): Promise<T>;
+    runAction<T>(key: string, task: () => T | PromiseLike<T>): Promise<T>;
+    runFetcher<T>(key: string, task: () => T | PromiseLike<T>): Promise<T>;
+    reportError(phase: RouteErrorTrace['phase'], error: unknown, route?: string, context?: {
+        readonly requestId?: number;
+        readonly navigationId?: number;
+    }): void;
+    revalidate(route?: string): Promise<void>;
+    subscribe(event: RouterDevToolsEvent, callback: (payload: unknown) => void): () => void;
+}
+interface Router {
+    readonly currentRoute: Signal<RouteLocation>;
+    readonly history: RouterHistory;
+    resolve(to: RouteTarget): RouteLocation;
+    push(to: RouteTarget): Promise<RouteLocation | false>;
+    replace(to: RouteTarget): Promise<RouteLocation | false>;
+    back(): void;
+    beforeEach(guard: NavigationGuard): () => void;
+    getViewState(route: RouteLocation): RouterViewState;
+    readonly devtools: RouterDevToolsAPI;
+    destroy(): void;
+}
+interface RouterViewProps {
+    readonly router?: Router;
+    readonly loading?: () => VobsNode | null | undefined;
+    readonly notFound?: (route: RouteLocation) => VobsNode | null | undefined;
+    readonly error?: (error: Error, retry: () => void) => VobsNode | null | undefined;
+}
+interface RouterPluginOptions {
+    readonly router?: Router;
+    readonly routes?: readonly RouteRecord[];
+    readonly history?: RouterHistory;
+}
+declare const ROUTER_KEY: InjectionKey<Router>;
+declare function lazy(loader: RouteComponentLoader): LazyRouteComponent;
+declare function createMemoryHistory(initial?: string): RouterHistory;
+declare function createBrowserHistory(base?: string): RouterHistory;
+declare function createRouter(options: RouterOptions): Router;
+declare function RouterView(props?: RouterViewProps): VobsNode;
+declare function useRouter(): Router;
+declare function useRoute(): Signal<RouteLocation>;
+declare function routerPlugin(options?: RouterPluginOptions): VobsPlugin;
+
+export { type LazyRouteComponent, NavigationCancelledError, type NavigationGuard, type NavigationGuardResult, NavigationRedirectError, type NavigationState, type NavigationTrace, ROUTER_KEY, type RouteComponent, type RouteComponentDefinition, type RouteComponentLoader, type RouteComponentModule, type RouteComponentProps, type RouteDebugNode, type RouteErrorTrace, type RouteLoader, type RouteLoaderContext, type RouteLocation, type RouteLocationRaw, type RouteMeta, type RouteParams, type RouteQuery, type RouteQueryInput, type RouteQueryValue, type RouteRecord, type RouteTarget, type Router, type RouterDataRequestKind, type RouterDataRequestOptions, type RouterDataRequestTrace, type RouterDevToolsAPI, type RouterDevToolsEvent, type RouterHistory, type RouterOptions, type RouterPerformanceMetrics, type RouterPluginOptions, RouterView, type RouterViewProps, type RouterViewState, createBrowserHistory, createMemoryHistory, createRouter, lazy, routerPlugin, useRoute, useRouter };

package/dist/index.d.ts

@@ -0,0 +1,215 @@
+import { Signal } from '@vobs/reactivity';
+import { VobsNode, InjectionKey, VobsPlugin } from '@vobs/vobs';
+export { RouterDebugEvent, RouterDebugEventType, createRouterDebugId, emitRouterDebug, subscribeRouterDebug } from './debug.js';
+import '@vobs/runtime';
+
+type RouteParams = Readonly<Record<string, string>>;
+type RouteQueryValue = string | readonly string[];
+type RouteQuery = Readonly<Record<string, RouteQueryValue>>;
+type RouteMeta = Readonly<Record<string, unknown>>;
+interface RouteLocation {
+    readonly path: string;
+    readonly fullPath: string;
+    readonly params: RouteParams;
+    readonly query: RouteQuery;
+    readonly hash: string;
+    readonly name: string | undefined;
+    readonly meta: RouteMeta;
+    readonly record: RouteRecord | null;
+    readonly matched: readonly RouteRecord[];
+    readonly state?: unknown;
+}
+interface RouteComponentProps {
+    readonly route: RouteLocation;
+    readonly params: RouteParams;
+    readonly query: RouteQuery;
+    readonly children?: VobsNode;
+}
+type RouteComponent = (props: RouteComponentProps) => VobsNode;
+type RouteComponentModule = RouteComponent | {
+    default: RouteComponent;
+};
+type RouteComponentLoader = () => PromiseLike<RouteComponentModule>;
+interface LazyRouteComponent {
+    readonly kind: 'vobs-lazy-route';
+    readonly load: RouteComponentLoader;
+}
+type RouteComponentDefinition = RouteComponent | LazyRouteComponent;
+interface RouteLoaderContext {
+    readonly route: RouteLocation;
+    readonly navigationId?: number;
+    readonly dataRequestId?: number;
+}
+type RouteLoader = (context: RouteLoaderContext) => unknown | PromiseLike<unknown>;
+interface RouteRecord {
+    readonly path?: string;
+    readonly component?: RouteComponentDefinition;
+    readonly source?: string;
+    readonly name?: string;
+    readonly meta?: Record<string, unknown>;
+    readonly loader?: RouteLoader;
+    readonly action?: RouteLoader;
+    readonly children?: readonly RouteRecord[];
+}
+type RouteQueryInput = Record<string, unknown> | URLSearchParams;
+interface RouteLocationRaw {
+    readonly path?: string;
+    readonly name?: string;
+    readonly params?: Record<string, unknown>;
+    readonly query?: RouteQueryInput;
+    readonly hash?: string;
+    readonly state?: unknown;
+}
+type RouteTarget = string | RouteLocationRaw;
+type NavigationGuardResult = void | boolean | RouteTarget;
+type NavigationGuard = (to: RouteLocation, from: RouteLocation) => NavigationGuardResult | PromiseLike<NavigationGuardResult>;
+declare class NavigationCancelledError extends Error {
+    readonly code = "NAVIGATION_CANCELLED";
+    constructor();
+}
+declare class NavigationRedirectError extends Error {
+    readonly code = "NAVIGATION_REDIRECT_LIMIT";
+    constructor();
+}
+interface RouterHistory {
+    readonly location: string;
+    /** 当前 history 条目携带的导航 state（push/replace 时写入，popstate/初始启动时回读）。 */
+    readonly state?: unknown;
+    push(path: string, state?: unknown): void;
+    replace(path: string, state?: unknown): void;
+    back(): void;
+    listen(listener: (path: string, state: unknown) => void): () => void;
+}
+interface RouterOptions {
+    readonly routes: readonly RouteRecord[];
+    readonly history?: RouterHistory;
+}
+interface RouterViewState {
+    readonly status: 'ready' | 'loading' | 'error' | 'not-found';
+    readonly component?: RouteComponent;
+    readonly layouts?: readonly RouteComponent[];
+    readonly error?: Error;
+    readonly retry: () => void;
+}
+interface RouteDebugNode {
+    readonly id: string;
+    readonly path: string;
+    readonly name?: string;
+    readonly component: string;
+    readonly lazy: boolean;
+    readonly loader: boolean;
+    readonly action: boolean;
+    readonly status: 'ready' | 'loading' | 'error';
+    readonly meta: RouteMeta;
+    readonly source?: string;
+    readonly children: readonly RouteDebugNode[];
+}
+interface RouteErrorTrace {
+    readonly id: number;
+    readonly phase: 'navigation' | 'render' | 'lazy' | 'loader' | 'action' | 'fetcher';
+    readonly route: string;
+    readonly message: string;
+    readonly stack?: string;
+    readonly timestamp: number;
+    readonly requestId?: number;
+    readonly navigationId?: number;
+}
+interface NavigationTrace {
+    readonly id: number;
+    readonly from: string;
+    readonly to: string;
+    readonly status: 'success' | 'redirected' | 'cancelled' | 'error';
+    readonly source: 'push' | 'replace' | 'history';
+    readonly startedAt: number;
+    readonly endedAt: number;
+    readonly duration: number;
+    readonly redirect?: string;
+    readonly error?: string;
+}
+interface NavigationState {
+    readonly status: 'idle' | 'loading' | 'error';
+    readonly from: string;
+    readonly to: string;
+    readonly traceId?: number;
+    readonly error?: string;
+}
+interface RouterPerformanceMetrics {
+    readonly navigationCount: number;
+    readonly averageNavigationDuration: number;
+    readonly slowNavigationCount: number;
+}
+type RouterDataRequestKind = 'loader' | 'action' | 'fetcher';
+interface RouterDataRequestTrace {
+    readonly id: number;
+    readonly kind: RouterDataRequestKind;
+    readonly key: string;
+    readonly route?: string;
+    readonly status: 'loading' | 'success' | 'error' | 'cancelled';
+    readonly startedAt: number;
+    readonly endedAt?: number;
+    readonly duration?: number;
+    readonly result?: unknown;
+    readonly error?: string;
+    readonly navigationId?: number;
+    readonly trigger?: 'navigation' | 'revalidate' | 'manual' | 'resource';
+    readonly environment?: 'client' | 'server';
+}
+interface RouterDataRequestOptions {
+    readonly route?: string;
+    readonly navigationId?: number;
+    readonly trigger?: 'navigation' | 'revalidate' | 'manual' | 'resource';
+    readonly environment?: 'client' | 'server';
+}
+type RouterDevToolsEvent = 'navigation:start' | 'navigation:end' | 'route:update' | 'data-request' | 'error';
+interface RouterDevToolsAPI {
+    getRouteTree(): readonly RouteDebugNode[];
+    getCurrentRoute(): RouteLocation;
+    getNavigationState(): NavigationState;
+    getNavigationHistory(): readonly NavigationTrace[];
+    getPerformanceMetrics(): RouterPerformanceMetrics;
+    getDataRequests(): readonly RouterDataRequestTrace[];
+    getErrors(): readonly RouteErrorTrace[];
+    trackDataRequest<T>(kind: RouterDataRequestKind, key: string, task: () => T | PromiseLike<T>, options?: RouterDataRequestOptions | string): Promise<T>;
+    runAction<T>(key: string, task: () => T | PromiseLike<T>): Promise<T>;
+    runFetcher<T>(key: string, task: () => T | PromiseLike<T>): Promise<T>;
+    reportError(phase: RouteErrorTrace['phase'], error: unknown, route?: string, context?: {
+        readonly requestId?: number;
+        readonly navigationId?: number;
+    }): void;
+    revalidate(route?: string): Promise<void>;
+    subscribe(event: RouterDevToolsEvent, callback: (payload: unknown) => void): () => void;
+}
+interface Router {
+    readonly currentRoute: Signal<RouteLocation>;
+    readonly history: RouterHistory;
+    resolve(to: RouteTarget): RouteLocation;
+    push(to: RouteTarget): Promise<RouteLocation | false>;
+    replace(to: RouteTarget): Promise<RouteLocation | false>;
+    back(): void;
+    beforeEach(guard: NavigationGuard): () => void;
+    getViewState(route: RouteLocation): RouterViewState;
+    readonly devtools: RouterDevToolsAPI;
+    destroy(): void;
+}
+interface RouterViewProps {
+    readonly router?: Router;
+    readonly loading?: () => VobsNode | null | undefined;
+    readonly notFound?: (route: RouteLocation) => VobsNode | null | undefined;
+    readonly error?: (error: Error, retry: () => void) => VobsNode | null | undefined;
+}
+interface RouterPluginOptions {
+    readonly router?: Router;
+    readonly routes?: readonly RouteRecord[];
+    readonly history?: RouterHistory;
+}
+declare const ROUTER_KEY: InjectionKey<Router>;
+declare function lazy(loader: RouteComponentLoader): LazyRouteComponent;
+declare function createMemoryHistory(initial?: string): RouterHistory;
+declare function createBrowserHistory(base?: string): RouterHistory;
+declare function createRouter(options: RouterOptions): Router;
+declare function RouterView(props?: RouterViewProps): VobsNode;
+declare function useRouter(): Router;
+declare function useRoute(): Signal<RouteLocation>;
+declare function routerPlugin(options?: RouterPluginOptions): VobsPlugin;
+
+export { type LazyRouteComponent, NavigationCancelledError, type NavigationGuard, type NavigationGuardResult, NavigationRedirectError, type NavigationState, type NavigationTrace, ROUTER_KEY, type RouteComponent, type RouteComponentDefinition, type RouteComponentLoader, type RouteComponentModule, type RouteComponentProps, type RouteDebugNode, type RouteErrorTrace, type RouteLoader, type RouteLoaderContext, type RouteLocation, type RouteLocationRaw, type RouteMeta, type RouteParams, type RouteQuery, type RouteQueryInput, type RouteQueryValue, type RouteRecord, type RouteTarget, type Router, type RouterDataRequestKind, type RouterDataRequestOptions, type RouterDataRequestTrace, type RouterDevToolsAPI, type RouterDevToolsEvent, type RouterHistory, type RouterOptions, type RouterPerformanceMetrics, type RouterPluginOptions, RouterView, type RouterViewProps, type RouterViewState, createBrowserHistory, createMemoryHistory, createRouter, lazy, routerPlugin, useRoute, useRouter };