@oiij/auto-router 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 oiij
+
+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,109 @@
+# Use auto-Router 🚀
+
+[![NPM version](https://img.shields.io/npm/v/@oiij/auto-router)](https://www.npmjs.com/package/@oiij/auto-router)
+[![MIT-license](https://img.shields.io/npm/l/@oiij/auto-router)](https://github.com/oiij/use/blob/main/packages/auto-router/LICENSE)
+
+## 项目简介 📦
+
+Use auto-Router 是一个 Vue Router 工具库，为 Vue 3 应用提供自动路由管理、Keep-Alive 管理等实用功能，帮助开发者更高效地管理应用路由。
+
+## 功能特点 ✨
+
+### 自动路由管理 🛣️
+
+- 🔄 自动解析和排序路由（支持数字前缀排序）
+- 📊 路由扁平化处理
+- 🎯 支持嵌套路由元数据继承
+- 📝 自动规范化路由名称
+
+### Keep-Alive 管理 💾
+
+- 🚀 自动管理页面缓存
+- 📦 基于路由元数据的缓存配置
+- 🎨 支持动态缓存控制
+
+### 加载状态管理 ⏳
+
+- 📊 自动跟踪路由加载状态
+- 🔄 基于导航守卫的状态管理
+- 🎯 响应式的加载状态计算属性
+
+### 类型安全 🔒
+
+- 📝 完整的 TypeScript 类型定义
+- 💡 提供准确的类型推断和代码提示
+- 🎯 支持 Vue 3 的 Composition API 类型系统
+
+## 安装 📥
+
+### 使用 pnpm 🐱
+
+```bash
+pnpm add @oiij/auto-router
+```
+
+### 使用 npm 📦
+
+```bash
+npm install @oiij/auto-router
+```
+
+### 使用 yarn 🧶
+
+```bash
+yarn add @oiij/auto-router
+```
+
+## 快速开始 🌟
+
+### 基础使用
+
+```vue
+<script setup>
+import { useAutoRouter } from '@oiij/auto-router'
+
+const { loading, routes, currentRoutePath } = useAutoRouter()
+</script>
+
+<template>
+  <div>
+    <div v-if="loading">
+      加载中...
+    </div>
+    <div v-else>
+      <p>当前路由: {{ currentRoutePath }}</p>
+      <nav>
+        <router-link
+          v-for="route in routes"
+          :key="route.path"
+          :to="route.path"
+        >
+          {{ route.meta?.title }}
+        </router-link>
+      </nav>
+    </div>
+  </div>
+</template>
+```
+
+## 在线文档 📚
+
+[在线文档](https://oiij-use.vercel.app/auto-router/auto-router) 📖
+
+## 贡献指南 🤝
+
+欢迎贡献代码、报告问题或提出新功能建议！
+
+1. Fork 本仓库 🍴
+2. 创建您的特性分支 (`git checkout -b feature/amazing-feature`) 🌿
+3. 提交您的更改 (`git commit -m 'Add some amazing feature'`) 💾
+4. 推送到分支 (`git push origin feature/amazing-feature`) 🚀
+5. 打开一个 Pull Request 📥
+
+## 许可证 📄
+
+本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情 📑
+
+## 联系方式 📞
+
+- GitHub: [https://github.com/oiij/use](https://github.com/oiij/use) 🌟

package/auto-router.d.ts

@@ -0,0 +1,93 @@
+/* eslint-disable */
+/* prettier-ignore */
+// biome-ignore format: off
+// biome-ignore lint: off
+// @ts-nocheck
+// Vue Router 路由元数据类型扩展
+// 这个文件扩展了 vue-router 的 RouteMeta 接口
+// 确保此文件包含在项目的 tsconfig.json 中
+
+import 'vue-router'
+
+// 为了确保这个文件被当作一个模块，添加至少一个 export 声明
+export {}
+
+declare module 'vue-router' {
+  interface RouteMeta {
+    /**
+     * 路由标题
+     */
+    title?: string
+
+    /**
+     * 路由描述
+     */
+    description?: string
+
+    /**
+     * 路由图标
+     */
+    icon?: string
+
+    /**
+     * 图标颜色
+     */
+    iconColor?: string
+
+    /**
+     * 排序权重（数字越小越靠前）
+     */
+    sort?: number
+
+    /**
+     * 布局组件名称
+     */
+    layout?: string
+
+    /**
+     * 过渡动画名称
+     */
+    transitionName?: string
+
+    /**
+     * 是否启用 Keep-Alive 缓存
+     */
+    keepAlive?: boolean
+
+    /**
+     * 是否为根路由
+     */
+    root?: boolean
+
+    /**
+     * 路由分组信息（用于导航菜单等）
+     */
+    group?: {
+      /**
+       * 分组标题
+       */
+      title?: string
+
+      /**
+       * 分组描述
+       */
+      description?: string
+
+      /**
+       * 分组图标
+       */
+      icon?: string
+
+      /**
+       * 分组图标颜色
+       */
+      iconColor?: string
+
+      /**
+       * 分组排序权重
+       */
+      sort?: number
+    }
+  }
+}
+

package/dist/index.d.mts

@@ -0,0 +1,45 @@
+import { AutoRouterInstance } from "./setup-auto-router.mjs";
+import { App } from "vue";
+
+//#region src/index.d.ts
+/**
+ * 获取自动路由实例
+ *
+ * @returns 自动路由实例，包含路由配置和工具方法
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useAutoRouter } from '@oiij/auto-router'
+ *
+ * const { routes, flattenRoutes, keepAlivePath } = useAutoRouter()
+ * </script>
+ * ```
+ */
+declare function useAutoRouter(): AutoRouterInstance;
+/**
+ * 创建自动路由插件
+ *
+ * 必须在 Vue Router 之后安装
+ *
+ * @returns Vue 插件对象
+ *
+ * @example
+ * ```ts
+ * import { createApp } from 'vue'
+ * import { createRouter } from 'vue-router'
+ * import { createAutoRouter } from '@oiij/auto-router'
+ *
+ * const app = createApp(App)
+ * const router = createRouter({ ... })
+ *
+ * app.use(router)
+ * app.use(createAutoRouter())
+ * app.mount('#app')
+ * ```
+ */
+declare function createAutoRouter(): {
+  install(app: App): void;
+};
+//#endregion
+export { type AutoRouterInstance, createAutoRouter, useAutoRouter };

package/dist/index.mjs

@@ -0,0 +1,56 @@
+import { setupAutoRouter } from "./setup-auto-router.mjs";
+import { inject } from "vue";
+
+//#region src/index.ts
+const __INJECTION_KEY__ = Symbol("auto-router");
+/**
+* 获取自动路由实例
+*
+* @returns 自动路由实例，包含路由配置和工具方法
+*
+* @example
+* ```vue
+* <script setup>
+* import { useAutoRouter } from '@oiij/auto-router'
+*
+* const { routes, flattenRoutes, keepAlivePath } = useAutoRouter()
+* <\/script>
+* ```
+*/
+function useAutoRouter() {
+	const router = inject(__INJECTION_KEY__);
+	if (!router) throw new Error("Auto router is not provided. Make sure to install createAutoRouter plugin.");
+	return router;
+}
+/**
+* 创建自动路由插件
+*
+* 必须在 Vue Router 之后安装
+*
+* @returns Vue 插件对象
+*
+* @example
+* ```ts
+* import { createApp } from 'vue'
+* import { createRouter } from 'vue-router'
+* import { createAutoRouter } from '@oiij/auto-router'
+*
+* const app = createApp(App)
+* const router = createRouter({ ... })
+*
+* app.use(router)
+* app.use(createAutoRouter())
+* app.mount('#app')
+* ```
+*/
+function createAutoRouter() {
+	return { install(app) {
+		const router = app.config.globalProperties.$router;
+		if (!router) throw new Error("Router instance is not found on this Vue app. This plugin should be installed after Vue Router.");
+		const autoRouter = setupAutoRouter(router);
+		app.provide(__INJECTION_KEY__, autoRouter);
+	} };
+}
+
+//#endregion
+export { createAutoRouter, useAutoRouter };

package/dist/plugin.d.mts

@@ -0,0 +1,20 @@
+import { EditableTreeNode } from "vue-router/unplugin";
+
+//#region src/plugin.d.ts
+/**
+ * 为路由添加元数据
+ *
+ * 从路由路径中提取排序编号（例如：01_home -> sort: 1）
+ * 并规范化路由名称（移除数字前缀）
+ *
+ * @param route - 可编辑的路由树节点
+ *
+ * @example
+ * ```ts
+ * // 路径: 01_home
+ * // 结果: { sort: 1, name: '/home', path: '/home' }
+ * ```
+ */
+declare function appendRouterMeta(route: EditableTreeNode): void;
+//#endregion
+export { appendRouterMeta };

package/dist/plugin.mjs

@@ -0,0 +1,28 @@
+//#region src/plugin.ts
+/**
+* 为路由添加元数据
+*
+* 从路由路径中提取排序编号（例如：01_home -> sort: 1）
+* 并规范化路由名称（移除数字前缀）
+*
+* @param route - 可编辑的路由树节点
+*
+* @example
+* ```ts
+* // 路径: 01_home
+* // 结果: { sort: 1, name: '/home', path: '/home' }
+* ```
+*/
+function appendRouterMeta(route) {
+	const sortMatch = route.path.match(/(\d+)_/);
+	const sortNum = sortMatch ? Number(sortMatch[1]) : null;
+	if (sortNum !== null && !Number.isNaN(sortNum)) route.addToMeta({ sort: sortNum });
+	if (route.name) {
+		const newName = route.name.replace(/\d+_/g, "");
+		route.name = newName.startsWith("/") ? newName : `/${newName}`;
+		if (route.path !== "") route.path = route.name;
+	}
+}
+
+//#endregion
+export { appendRouterMeta };

package/dist/setup-auto-router.d.mts

@@ -0,0 +1,39 @@
+import { ComputedRef } from "vue";
+import { RouteLocationNormalizedLoaded, RouteRecordRaw } from "vue-router";
+
+//#region src/setup-auto-router.d.ts
+/**
+ * 自动路由实例接口
+ */
+type AutoRouterInstance = {
+  /**
+   * 加载状态
+   */
+  loading: ComputedRef<boolean>;
+  /**
+   * 原始路由配置
+   */
+  routesRaw: readonly RouteRecordRaw[];
+  /**
+   * 解析并排序后的路由配置
+   */
+  routes: RouteRecordRaw[];
+  /**
+   * 扁平化的路由列表（将所有子路由提取到一级）
+   */
+  flattenRoutes: RouteRecordRaw[];
+  /**
+   * 需要缓存的路由路径列表
+   */
+  keepAlivePath: ComputedRef<string[]>;
+  /**
+   * 当前路由
+   */
+  currentRoute: ComputedRef<RouteLocationNormalizedLoaded>;
+  /**
+   * 当前路由路径
+   */
+  currentRoutePath: ComputedRef<string>;
+};
+//#endregion
+export { AutoRouterInstance };

package/dist/setup-auto-router.mjs

@@ -0,0 +1,88 @@
+import { computed, ref } from "vue";
+import { cloneDeep } from "es-toolkit";
+import { routes as routes$1 } from "vue-router/auto-routes";
+
+//#region src/setup-auto-router.ts
+/**
+* 解析路由配置
+*
+* 处理以下逻辑：
+* 1. 从子路由的 index 页面继承 group 元数据
+* 2. 将空路径的子路由路径设置为父路由路径
+* 3. 根据 sort 元数据排序路由
+*
+* @param routes - 原始路由配置
+* @returns 解析后的路由配置
+*/
+function parseRoutes(routes) {
+	return routes.map((route) => {
+		const indexMeta = (route.children?.find((f) => f.path === ""))?.meta?.group;
+		return {
+			...route,
+			meta: {
+				...route.meta,
+				...indexMeta
+			},
+			children: route.children?.map((child) => ({
+				...child,
+				path: child.path === "" ? route.path : child.path
+			})).toSorted((a, b) => (a.meta?.sort ?? Infinity) - (b.meta?.sort ?? Infinity))
+		};
+	}).toSorted((a, b) => (a.meta?.sort ?? Infinity) - (b.meta?.sort ?? Infinity));
+}
+/**
+* 扁平化路由配置
+*
+* 将嵌套的路由结构展平为一维数组
+*
+* @param routes - 路由配置
+* @returns 扁平化后的路由数组
+*/
+function flattenRoutes(routes) {
+	return cloneDeep(routes).flatMap((route) => route.children ?? route);
+}
+/**
+* 设置自动路由
+*
+* 解析路由配置，提供路由工具方法
+*
+* @param router - Vue Router 实例
+* @returns 自动路由实例
+*
+* @example
+* ```ts
+* import { setupAutoRouter } from '@oiij/auto-router'
+* import { router } from './router'
+*
+* const autoRouter = setupAutoRouter(router)
+* console.log(autoRouter.routes) // 解析后的路由
+* console.log(autoRouter.flattenRoutes) // 扁平化路由
+* ```
+*/
+function setupAutoRouter(router) {
+	const loading = ref(false);
+	router.beforeEach((to, from, next) => {
+		loading.value = true;
+		next();
+	});
+	router.afterEach(() => {
+		loading.value = false;
+	});
+	const routes = parseRoutes(cloneDeep(routes$1));
+	const flattenRoutesCache = flattenRoutes(routes);
+	const keepAlivePath = computed(() => flattenRoutesCache.filter((f) => f.meta?.keepAlive).map((m) => m.path));
+	const currentRoute = computed(() => router.currentRoute.value);
+	const currentRoutePath = computed(() => currentRoute.value.path);
+	return {
+		loading: computed(() => loading.value),
+		routesRaw: routes$1,
+		routes,
+		flattenRoutes: flattenRoutesCache,
+		keepAlivePath,
+		currentRoute,
+		currentRoutePath
+	};
+}
+
+//#endregion
+export { setupAutoRouter };

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@oiij/auto-router",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "Vue Router utilities and composables for Vue 3",
+  "author": "oiij",
+  "license": "MIT",
+  "homepage": "https://github.com/oiij/use",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:oiij/use.git"
+  },
+  "bugs": "https://github.com/oiij/use/issues",
+  "keywords": [
+    "@oiij/auto-router",
+    "vue-routes",
+    "vue3",
+    "composables"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.mts",
+      "import": "./dist/plugin.mjs"
+    },
+    "./auto-router": {
+      "types": "./auto-router.d.ts"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "auto-router.d.ts",
+    "dist",
+    "package.json"
+  ],
+  "peerDependencies": {
+    "vue": "^3.5.27",
+    "vue-router": "^5.0.2"
+  },
+  "dependencies": {
+    "es-toolkit": "^1.44.0"
+  },
+  "devDependencies": {
+    "vue": "^3.5.27",
+    "vue-router": "^5.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "tsdown --watch",
+    "build": "tsc --noEmit && tsdown",
+    "bumpp": "bumpp --no-push"
+  }
+}