vitarx-router 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 朱冲林
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,14 @@
+# VitarxRouter
+
+________________________________________________________________________
+
+## 安装
+
+```shell
+npm install vitarx-router
+```
+
+## 使用
+```javascript
+import { Router } from 'vitarx-router'
+```

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './widget/index.js';
+export * from './router/index.js';

package/dist/router/helper.d.ts

@@ -0,0 +1,92 @@
+import { LazyLoad, Route, RouteLocation, RouterOptions } from './type.js';
+import { default as Router } from './router.js';
+import { default as WebHistoryRouter } from './web-history-router.js';
+import { default as MemoryRouter } from './memory-router.js';
+import { LazyLoader, Reactive, WidgetType } from 'vitarx';
+/**
+ * 定义路由表
+ *
+ * 使用defineRoutes定义路由表可以获得更好的代码提示。
+ *
+ * @param {Route[]} routes - 路由配置表
+ */
+export declare function defineRoutes(...routes: Route[]): Route[];
+/**
+ * 定义路由
+ *
+ * 使用defineRoute定义路由可以获得更好的代码提示。
+ *
+ * @param {Route} route - 路由配置
+ */
+export declare function defineRoute(route: Route): Route;
+/**
+ * 创建内存路由器
+ *
+ * 不支持浏览器的前进后退等操作，只能通过实例中的方法来管理路由。
+ *
+ * 你必须调用一次`router.replace(target)`方法来跳转到目标路由。
+ *
+ * @param {RouterOptions} options - 配置
+ * @return {MemoryRouter} - 内存路由器实例
+ */
+export declare function createRouter(options: RouterOptions & {
+    mode: 'memory';
+}): MemoryRouter;
+/**
+ * 创建History路由器
+ *
+ * 基于History API实现路由功能，支持浏览器前进后退、刷新等操作。
+ *
+ * 它与`MemoryRouter`路由不同的是，它不需要初始化过后调用`router.replace(target)`方法来替换默认路由，
+ * 内部会自动根据`window.location`去匹配路由。
+ *
+ * @param {RouterOptions} options - 路由配置
+ * @return {WebHistoryRouter} - HistoryRouter实例
+ */
+export declare function createRouter(options: RouterOptions | (RouterOptions & {
+    mode: 'path' | 'hash';
+})): WebHistoryRouter;
+/**
+ * 获取路由器实例
+ *
+ * 与使用`Router.instance`静态属性获取是一致的效果。
+ *
+ * @return {Router} - 路由器实例
+ * @throws {Error} - 如果路由器实例未初始化，则抛出异常
+ */
+export declare function useRouter<T extends Router>(): T;
+/**
+ * 获取当前`RouteLocation`对象
+ *
+ * 它是`Router.instance.currentRouteLocation`属性的助手函数，优化函数式编程体验。
+ *
+ * 简单示例：
+ * ```jsx
+ * import { useRoute } from 'vitarx-router'
+ *
+ * // 监听路由参数变化示例
+ * export default function App() {
+ *  const route = useRoute()
+ *  watch(()=>route.params.id, (newId, oldId) => {
+ *   console.log(`监听到id参数变化, 旧值：${oldId}, 新值：${newId}`)
+ *  })
+ *  return <div>当前路由参数ID：{route.params.id}</div>
+ * }
+ * ```
+ *
+ * @return {Readonly<Reactive<RouteLocation>>} - 只读的`RouteLocation`对象
+ */
+export declare function useRoute(): Readonly<Reactive<RouteLocation>>;
+/**
+ * ## 标记延迟加载
+ *
+ * 由于直接定义`() => import('./xxx.js')`会导致类型与函数式组件冲突，
+ * 在未执行函数之前难以有效判断其类型，所以这里使用Symbol标记懒加载器。
+ *
+ * @example
+ * lazy(() => import('./xxx.js'))
+ *
+ * @template T - WidgetType
+ * @param {LazyLoader<T>} lazyLoader - 函数返回的import即是惰性加载器
+ */
+export declare function lazy<T extends WidgetType>(lazyLoader: LazyLoader<T>): LazyLoad<T>;

package/dist/router/index.d.ts

@@ -0,0 +1,6 @@
+export type * from './type.js';
+export { NavigateStatus } from './type.js';
+export { default as Router } from './router.js';
+export { default as WebHistoryRouter } from './web-history-router.js';
+export { default as MemoryRouter } from './memory-router.js';
+export * from './helper.js';

package/dist/router/memory-router.d.ts

@@ -0,0 +1,45 @@
+import { default as Router } from './router.js';
+import { RouteLocation, RouterOptions } from './type.js';
+/**
+ * 基于内存实现的路由器
+ *
+ * 仅支持路由器操作前进、后退、跳转等操作
+ *
+ * > 注意：不要在浏览器端使用，因为浏览器端有原生的history对象，使用内存模式会和浏览器端的历史记录冲突，导致路由异常。
+ */
+export default class MemoryRouter extends Router {
+    protected _history: RouteLocation[];
+    protected _pendingGo: number | null;
+    constructor(options: RouterOptions<'memory'>);
+    private _currentIndex;
+    /**
+     * 当前历史路由索引
+     *
+     * @protected
+     */
+    protected get currentIndex(): number;
+    /**
+     * @inheritDoc
+     */
+    go(delta?: number): void;
+    /**
+     * @inheritDoc
+     */
+    protected initializeRouter(): void;
+    /**
+     * 添加历史记录
+     */
+    protected pushHistory(data: RouteLocation): void;
+    /**
+     * 替换历史记录
+     */
+    protected replaceHistory(data: RouteLocation): void;
+    /**
+     * 更新历史记录
+     *
+     * @param {RouteLocation} data - 目标路由
+     * @param {boolean} isReplace - 是否为替换操作
+     * @private
+     */
+    private _updateHistory;
+}

package/dist/router/router.d.ts

@@ -0,0 +1,414 @@
+import { _ScrollBehavior, _ScrollToOptions, BeforeEachCallbackResult, DynamicRouteRecord, HashStr, HistoryMode, InitializedRouterOptions, MatchResult, NavigateResult, Route, RouteIndex, RouteLocation, RouteName, RouteNormalized, RoutePath, RouterOptions, RouteTarget, ScrollTarget } from './type.js';
+import { Reactive, VNode, WidgetType } from 'vitarx';
+/**
+ * 路由器基类
+ */
+export default abstract class Router {
+    #private;
+    private readonly _options;
+    private readonly _namedRoutes;
+    private readonly _dynamicRoutes;
+    private readonly _pathRoutes;
+    private readonly _parentRoute;
+    private _currentTaskId;
+    private _taskCounter;
+    /**
+     * 是否正在执行 replace 操作
+     *
+     * @private
+     */
+    private _pendingReplace;
+    /**
+     * 是否正在执行 push 操作
+     *
+     * @private
+     */
+    private _pendingPush;
+    private _scrollBehaviorHandler;
+    private readonly _currentRouteLocation;
+    protected constructor(options: RouterOptions);
+    /**
+     * 获取单例实例
+     *
+     * @return {Router} - 路由器实例
+     */
+    static get instance(): Router;
+    private _isBrowser;
+    /**
+     * 是否运行在浏览器端
+     */
+    get isBrowser(): boolean;
+    private _scrollBehavior;
+    /**
+     * 滚动行为
+     *
+     * 如果options.scrollBehavior为函数，则scrollBehavior固定为auto'。
+     */
+    get scrollBehavior(): _ScrollBehavior;
+    /**
+     * 获取配置
+     *
+     * @return {Readonly<InitializedRouterOptions>} - 初始化配置
+     */
+    get options(): Readonly<InitializedRouterOptions>;
+    /**
+     * 路由器模式
+     */
+    get mode(): HistoryMode;
+    /**
+     * 获取所有路由映射
+     *
+     * map键值是path，值是路由对象
+     *
+     * @return {Map<string, Route>}
+     */
+    get pathRoutes(): ReadonlyMap<string, Route>;
+    /**
+     * 获取所有命名路由映射
+     *
+     * map键值是name，值是路由对象
+     *
+     * @return {Map<string, Route>}
+     */
+    get namedRoutes(): ReadonlyMap<string, Route>;
+    /**
+     * 动态路由记录
+     *
+     * map键值是path段长度，值是Array<{regex: RegExp,route:RouteNormalized}>
+     */
+    get dynamicRoutes(): Map<number, DynamicRouteRecord[]>;
+    /**
+     * ## 获取已规范的路由表
+     *
+     * 它的内存地址始终指向的是初始化时传入的路由表，但它的数据结构是经过内部规范化处理过的。
+     *
+     * 所有嵌套`Route`的path都会被自动补全为完整的路径
+     *
+     * > 注意：不要尝试修改已规范化的路由表！请使用`removeRoute`和`addRoute`方法实现路由的变更。
+     *
+     * @return {RouteNormalized[]}
+     */
+    get routes(): ReadonlyArray<RouteNormalized>;
+    /**
+     * 基本路径
+     */
+    get basePath(): `/${string}`;
+    /**
+     * 判断路由器是否初始化完成
+     *
+     * @return {boolean} - 如果初始化完成，返回true，否则返回false
+     */
+    get initialized(): boolean;
+    /**
+     * 受支持的`path`后缀名
+     */
+    get suffix(): Exclude<RouterOptions['suffix'], void>;
+    /**
+     * 当前路由数据
+     *
+     * 它是只读的，不要在外部修改它！
+     *
+     * @return {Readonly<RouteLocation>} - 当前路由数据
+     */
+    get currentRouteLocation(): Readonly<Reactive<RouteLocation>>;
+    /**
+     * 是否处于等待状态
+     *
+     * @protected
+     */
+    protected get isPendingNavigation(): boolean;
+    /**
+     * 等待替换完成的数据
+     *
+     * @protected
+     */
+    protected get pendingReplaceData(): RouteLocation | null;
+    /**
+     * 等待跳转完成的数据
+     *
+     * @protected
+     */
+    protected get pendingPushData(): RouteLocation | null;
+    /**
+     * 路由视图
+     *
+     * 内部方法，用于获取路由线路对应的视图元素虚拟节点。
+     *
+     * @internal
+     * @param {RouteNormalized} route - 路由对象
+     * @param {string} name - 视图名称
+     * @return {VNode<WidgetType> | undefined} - 视图元素虚拟节点
+     */
+    static routeView(route: RouteNormalized, name: string): VNode<WidgetType> | undefined;
+    /**
+     * 跳转指定的历史记录位置
+     *
+     * 如果未向该函数传参或delta相等于 0，则该函数与调用location.reload()具有相同的效果。
+     *
+     * @param {number} delta - 跳转的步数（正数为前进，负数为后退）
+     */
+    abstract go(delta?: number): void;
+    /**
+     * 后退到上一个历史记录
+     */
+    back(): void;
+    /**
+     * 前进到下一个历史记录
+     */
+    forward(): void;
+    /**
+     * 替换当前页面
+     *
+     * @param {RouteTarget} target - 目标
+     * @return {boolean} - 是否跳转成功，非内存模式始终返回true
+     */
+    replace(target: RouteTarget | RouteIndex): Promise<NavigateResult>;
+    /**
+     * 跳转到新的页面
+     *
+     * @param {RouteTarget} target - 目标
+     * @return {boolean} - 是否跳转成功，非内存模式始终返回true
+     */
+    push(target: RouteTarget | RouteIndex): Promise<NavigateResult>;
+    /**
+     * 删除路由
+     *
+     * @param {string} index 路由索引，如果/开头则匹配path，其他匹配name
+     * @param {boolean} isRemoveFromRoutes 是否从路由表中移除，内部递归时传递的参数，无需外部传入！
+     */
+    removeRoute(index: RouteIndex, isRemoveFromRoutes?: boolean): void;
+    /**
+     * 添加路由
+     *
+     * @param {Route} route - 路由描述对象
+     * @param {string} parent - 父路由的path或name，不传入则添加至路由表根节点
+     */
+    addRoute(route: Route, parent?: string): void;
+    /**
+     * 超找路由
+     *
+     * 传入的是`path`则会调用`matchRoute`方法，传入的是`name`则会调用`getNamedRoute`方法
+     *
+     * @param {RouteIndex|RouteTarget} target - 路由索引，如果index以/开头则匹配path，其他匹配name
+     * @return {RouteNormalized | undefined} - 路由对象，如果不存在则返回undefined
+     */
+    findRoute(target: RouteIndex | RouteTarget): RouteNormalized | undefined;
+    /**
+     * 查找命名路由
+     *
+     * @param {string} name - 路由名称
+     */
+    findNamedRoute(name: RouteName): RouteNormalized | undefined;
+    /**
+     * 初始化路由器
+     *
+     * 只能初始化一次，多次初始化无效。
+     *
+     * 如果你使用的`createRouter(options)`助手函数创建的路由器实例则无需调用该方法。
+     *
+     * @return {this} - 返回当前路由器实例
+     */
+    initialize(): this;
+    /**
+     * 此方法用于浏览器端滚动到指定位置
+     *
+     * @param scrollTarget
+     * @protected
+     */
+    scrollTo(scrollTarget: ScrollTarget | undefined): void;
+    /**
+     * 获取路由的父路由
+     *
+     * @param route - 路由对象
+     * @return {RouteNormalized | undefined}
+     */
+    findParentRoute(route: RouteNormalized): RouteNormalized | undefined;
+    /**
+     * 该方法提供给`RouterView`完成渲染时调用
+     *
+     * @internal
+     */
+    protected _completeViewRender(): void;
+    /**
+     * 完成导航
+     *
+     * 所有子类在完成导航的后续处理过后必须调用该方法！
+     *
+     * @param {RouteLocation} data - 如果是由`replace`或`push`方法发起的导航则无需传入此参数。
+     * @param {_ScrollToOptions} savedPosition - 保存的滚动位置信息，用于恢复滚动位置
+     * @protected
+     */
+    protected completeNavigation(data?: RouteLocation, savedPosition?: _ScrollToOptions): void;
+    /**
+     * 更新当前导航数据中的query参数
+     *
+     * 会同步更新`fullPath`
+     *
+     * @param {Record<string, string>} query - 新的query参数对象
+     * @protected
+     */
+    protected updateQuery(query: Record<string, string>): void;
+    /**
+     * 更新当前导航数据中的hash参数
+     *
+     * 会同步更新`fullPath`
+     *
+     * @param {`#${string}` | ''} hash - 新的hash参数，如果为空则表示无hash
+     * @protected
+     */
+    protected updateHash(hash: `#${string}` | ''): void;
+    /**
+     * 初始化路由器
+     *
+     * 子类可重写此方法以完成路由器的初始化
+     *
+     * @private
+     */
+    protected abstract initializeRouter(): void;
+    /**
+     * 路由匹配
+     *
+     *
+     * @param {string} path - 路径
+     *
+     * @return {MatchResult} 如果匹配失败则返回undefined
+     */
+    protected matchRoute(path: RoutePath): MatchResult;
+    /**
+     * 创建完整路径
+     *
+     * @protected
+     * @param path - 路径
+     * @param query - ?查询参数
+     * @param hash - #哈希值
+     */
+    protected makeFullPath(path: string, query: `?${string}` | '' | Record<string, string>, hash: HashStr): `${string}`;
+    /**
+     * 添加历史记录
+     *
+     * 子类必须实现该方法
+     *
+     * @param data
+     * @protected
+     */
+    protected abstract pushHistory(data: RouteLocation): void;
+    /**
+     * 替换历史记录
+     *
+     * 子类必须实现该方法
+     *
+     * @param {RouteLocation} data - 目标路由
+     * @protected
+     */
+    protected abstract replaceHistory(data: RouteLocation): void;
+    /**
+     * 判断是否相同的导航请求
+     *
+     * @param to
+     * @param from
+     * @protected
+     */
+    protected isSameNavigate(to: RouteLocation, from: RouteLocation): boolean;
+    /**
+     * 根据路由目标创建导航数据
+     *
+     * @param {RouteTarget} target - 路由目标
+     * @protected
+     */
+    protected createRouteLocation(target: RouteTarget): RouteLocation;
+    /**
+     * 触发路由前置守卫
+     *
+     * @param {DeepReadonly<RouteLocation>} to - 路由目标对象
+     * @param {DeepReadonly<RouteLocation>} from - 前路由对象
+     * @return {false | RouteTarget} - 返回false表示阻止导航，返回新的路由目标对象则表示导航到新的目标
+     */
+    protected onBeforeEach(to: DeepReadonly<RouteLocation>, from: DeepReadonly<RouteLocation>): BeforeEachCallbackResult;
+    /**
+     * 触发路由后置守卫
+     *
+     * @param {DeepReadonly<RouteLocation>} to - 路由目标对象
+     * @param {DeepReadonly<RouteLocation>} from - 前路由对象
+     */
+    protected onAfterEach(to: DeepReadonly<RouteLocation>, from: DeepReadonly<RouteLocation>): void;
+    /**
+     * 路由跳转的通用方法
+     *
+     * 仅供内部使用，外部请使用`push`|`replace`方法
+     *
+     * @protected
+     * @param {RouteTarget} target - 目标
+     * @return {Promise<NavigateResult>} - 是否导航成功
+     */
+    protected navigate(target: RouteTarget): Promise<NavigateResult>;
+    /**
+     * 更新路由数据
+     *
+     * @private
+     * @param {RouteLocation} newLocation - 新的路由数据对象
+     */
+    private updateRouteLocation;
+    /**
+     * 判断是否为允许的后缀
+     *
+     * @param suffix
+     * @private
+     */
+    private isAllowedSuffix;
+    /**
+     * 触发滚动行为
+     *
+     * @param {RouteLocation} to - 目标导航数据对象
+     * @param {RouteLocation} from - 前导航数据对象
+     * @param {_ScrollToOptions | undefined} savedPosition - 保存的滚动位置
+     * @private
+     */
+    private onScrollBehavior;
+    /**
+     * 从源路由表中删除路由
+     *
+     * @param route
+     * @protected
+     */
+    private removedFromRoutes;
+    /**
+     * 删除动态路由映射
+     *
+     * @param path
+     * @protected
+     */
+    private removeDynamicRoute;
+    /**
+     * 初始化路由表
+     *
+     * @param routes
+     */
+    private setupRoutes;
+    /**
+     * 注册路由
+     *
+     * @param {Route} route - 路由对象
+     * @param {RouteNormalized} group - 路由所在的分组
+     * @protected
+     */
+    private registerRoute;
+    /**
+     * 如果路径是严格匹配，则转换为小写
+     *
+     * @param path
+     * @private
+     */
+    private strictPath;
+    /**
+     * 记录路由
+     *
+     * @param {Route} route - 路由对象
+     * @protected
+     */
+    private recordRoute;
+    /**
+     * 添加动态路由
+     * @param route
+     */
+    private recordDynamicRoute;
+}