refactor(src): 重构插件系统并添加 vue 插件兼容

Author: l246804

package.json

@@ -14,7 +14,11 @@
   "bugs": {
     "url": "https://github.com/vue-spark/vue-router-plugin-system/issues"
   },
-  "keywords": ["vue", "vue-router", "plugin"],
+  "keywords": [
+    "vue",
+    "vue-router",
+    "plugin"
+  ],
   "exports": {
     ".": "./dist/index.js",
     "./package.json": "./package.json"
@@ -38,7 +42,8 @@
     "lint": "eslint . --cache --cache-location ./node_modules/.cache/.eslint-cache",
     "lint:fix": "pnpm run lint --fix",
     "release": "bumpp && pnpm publish",
-    "prepublishOnly": "pnpm run build"
+    "prepublishOnly": "pnpm run build",
+    "prepare": "simple-git-hooks"
   },
   "peerDependencies": {
     "vue": "^3.0.0",

src/create-router.ts

@@ -0,0 +1,53 @@
+import type { RouterOptions as _RouterOptions, Router } from 'vue-router'
+import type { RouterPlugin } from './plugin'
+import { createRouter as _createRouter } from 'vue-router'
+import { RUN_WITH_APP_HANDLERS_KEY } from './meta-keys'
+import { prepareInstall } from './prepare-install'
+import { setupPlugin } from './setup-plugin'
+
+export interface RouterOptions extends _RouterOptions {
+  /**
+   * Plugins to be installed on the router.
+   */
+  plugins?: RouterPlugin[]
+}
+
+/**
+ * Equivalent to {@link createRouter} from `vue-router`, but with support for plugins.
+ * @param options {@link RouterOptions}
+ *
+ * @example
+ * ```ts
+ * const SomePlugin: RouterPlugin = (ctx) => {
+ *   // plugin implementation
+ * }
+ *
+ * createRouter({
+ *   history: createWebHistory(),
+ *   routes: [],
+ *   plugins: [SomePlugin()],
+ * })
+ * ```
+ */
+export function createRouter(options: RouterOptions): Router {
+  const router = _createRouter(options)
+
+  // 重写 install 方法
+  const { install } = router
+  router.install = (...args) => {
+    const [app] = args
+    prepareInstall({ app, router })
+    install.apply(router, args)
+
+    // 运行缓存的 runWithApp 函数
+    const runWithAppHandlers = (router[RUN_WITH_APP_HANDLERS_KEY] ??= [])
+    runWithAppHandlers.forEach(handler => handler(app))
+    runWithAppHandlers.length = 0
+  }
+
+  // 安装插件
+  const { plugins = [] } = options
+  plugins.forEach(plugin => setupPlugin({ router, plugin }))
+
+  return router
+}

src/create-vue-router-plugin.ts

@@ -0,0 +1,42 @@
+import type { App } from 'vue'
+import type { RouterPlugin } from './plugin'
+import { prepareInstall } from './prepare-install'
+import { setupPlugin } from './setup-plugin'
+
+export interface VueRouterPlugin extends RouterPlugin {
+  /**
+   * Install the plugin.
+   * @param app vue app
+   */
+  install: (app: App) => void
+}
+
+/**
+ * Create a {@link VueRouterPlugin} from a {@link RouterPlugin}.
+ * @param plugin {@link RouterPlugin}
+ * @returns Returns a {@link VueRouterPlugin}
+ * @example
+ * ```ts
+ * const SomePlugin = createVueRouterPlugin((ctx) => {
+ *   // plugin implementation
+ * })
+ *
+ * // must be installed after the router
+ * app.use(router).use(SomePlugin)
+ * ```
+ */
+export function createVueRouterPlugin(plugin: RouterPlugin): VueRouterPlugin {
+  return Object.assign(plugin, {
+    install(app: App) {
+      const router = app.config.globalProperties.$router
+      if (!router) {
+        throw new Error(
+          '[vue-router-plugin-system] Please install vue-router first.',
+        )
+      }
+
+      prepareInstall({ app, router })
+      setupPlugin({ router, plugin })
+    },
+  })
+}

src/index.ts

@@ -1,84 +1,3 @@
-import type { App } from 'vue'
-import type { RouterOptions as _RouterOptions, Router } from 'vue-router'
-import type { RouterPlugin, RouterPluginContext } from './plugin'
-import { effectScope } from 'vue'
-import { createRouter as _createRouter } from 'vue-router'
-import { APP_KEY } from './meta-keys'
-
-export interface RouterOptions extends _RouterOptions {
-  /**
-   * Plugins to be installed on the router.
-   */
-  plugins?: RouterPlugin[]
-}
-
-/**
- * Equivalent to {@link createRouter} from `vue-router`, but with support for plugins.
- * @param options {@link RouterOptions}
- *
- * @example
- * ```ts
- * createRouter({
- *   history: createWebHistory(),
- *   routes: [],
- *   plugins: [SomePlugin()],
- * })
- * ```
- */
-export function createRouter(options: RouterOptions): Router {
-  const router = _createRouter(options)
-  const { plugins = [] } = options
-
-  const effect = effectScope(true)
-  const runWithAppFns: ((app: App) => void)[] = []
-  const uninstallFns: (() => void)[] = []
-
-  const ctx: RouterPluginContext = {
-    router,
-
-    runWithApp(fn) {
-      // 将 fn 包装到 effect 中
-      const rawFn = fn
-      fn = function (this: any, ...args) {
-        return effect.run(() => rawFn.apply(this, args))
-      }
-
-      if (router[APP_KEY]) {
-        fn(router[APP_KEY])
-      } else {
-        runWithAppFns.push(fn)
-      }
-    },
-
-    onUninstall(fn) {
-      uninstallFns.push(fn)
-    },
-  }
-
-  // 在 effect 中执行插件
-  effect.run(() => {
-    plugins.forEach((plugin) => plugin(ctx))
-  })
-
-  // 重写 install 方法
-  const originalInstall = router.install
-  router.install = (app: App) => {
-    originalInstall(app)
-
-    router[APP_KEY] = app
-    runWithAppFns.forEach((fn) => fn(app))
-    runWithAppFns.length = 0
-
-    // TODO: use https://github.com/vuejs/core/pull/8801 if merged
-    const { unmount } = app
-    app.unmount = () => {
-      effect.stop()
-      delete router[APP_KEY]
-      uninstallFns.forEach((fn) => fn())
-      uninstallFns.length = 0
-      unmount.call(app)
-    }
-  }
-
-  return router
-}
+export * from './create-router'
+export * from './create-vue-router-plugin'
+export * from './plugin'

src/meta-keys.ts

@@ -1,12 +1,38 @@
-import type { App } from 'vue'
+import type { App, EffectScope } from 'vue'
+import type {
+  RouterPluginRunWithAppHandler,
+  RouterPluginUninstallHandler,
+} from './plugin'
 
 export const APP_KEY = Symbol('vue app')
+export const EFFECT_SCOPE_KEY = Symbol('vue effect scope')
+export const UNINSTALL_HANDLERS_KEY = Symbol('router plugin uninstall handlers')
+export const RUN_WITH_APP_HANDLERS_KEY = Symbol(
+  'router plugin run with app handlers',
+)
+export const PREPARED_FLAG_KEY = Symbol('router plugin system already prepared')
 
 declare module 'vue-router' {
   export interface Router {
     /**
      * The vue app instance.
      */
     [APP_KEY]?: App
+    /**
+     * The vue effect scope.
+     */
+    [EFFECT_SCOPE_KEY]?: EffectScope
+    /**
+     * The router plugin uninstall functions.
+     */
+    [UNINSTALL_HANDLERS_KEY]?: RouterPluginUninstallHandler[]
+    /**
+     * The router plugin run with app functions.
+     */
+    [RUN_WITH_APP_HANDLERS_KEY]?: RouterPluginRunWithAppHandler[]
+    /**
+     * The flag to indicate whether the router is prepared.
+     */
+    [PREPARED_FLAG_KEY]?: boolean
   }
 }

src/plugin.ts

@@ -1,6 +1,9 @@
 import type { App } from 'vue'
 import type { Router } from 'vue-router'
 
+export type RouterPluginUninstallHandler = () => void
+export type RouterPluginRunWithAppHandler = (app: App) => void
+
 export interface RouterPluginContext {
   /**
    * The router instance.
@@ -9,11 +12,11 @@ export interface RouterPluginContext {
   /**
    * Runs a function with the vue app.
    */
-  runWithApp: (fn: (app: App) => void) => void
+  runWithApp: (handler: RouterPluginRunWithAppHandler) => void
   /**
    * Register a function to be called when the plugin is uninstalled.
    */
-  onUninstall: (fn: () => void) => void
+  onUninstall: (handler: RouterPluginUninstallHandler) => void
 }
 
 export interface RouterPlugin {

src/prepare-install.ts

@@ -0,0 +1,46 @@
+import type { App } from 'vue'
+import type { Router } from 'vue-router'
+import {
+  APP_KEY,
+  EFFECT_SCOPE_KEY,
+  PREPARED_FLAG_KEY,
+  RUN_WITH_APP_HANDLERS_KEY,
+  UNINSTALL_HANDLERS_KEY,
+} from './meta-keys'
+
+/**
+ * 在正式安装到 vue app 前运行此函数，以准备安装
+ */
+export function prepareInstall({
+  app,
+  router,
+}: {
+  app: App
+  router: Router
+}): void {
+  if (router[PREPARED_FLAG_KEY]) {
+    return
+  }
+
+  // 避免重复执行后续操作
+  router[PREPARED_FLAG_KEY] = true
+
+  // 用于 setupPlugin 内访问 vue app
+  router[APP_KEY] = app
+
+  // 注册卸载函数
+  // TODO: use https://github.com/vuejs/core/pull/8801 if merged
+  const { unmount } = app
+  app.unmount = () => {
+    router[EFFECT_SCOPE_KEY]?.stop()
+    router[UNINSTALL_HANDLERS_KEY]?.forEach(handler => handler())
+
+    delete router[PREPARED_FLAG_KEY]
+    delete router[APP_KEY]
+    delete router[EFFECT_SCOPE_KEY]
+    delete router[UNINSTALL_HANDLERS_KEY]
+    delete router[RUN_WITH_APP_HANDLERS_KEY]
+
+    return unmount.call(app)
+  }
+}

src/setup-plugin.ts

@@ -0,0 +1,47 @@
+import type { Router } from 'vue-router'
+import type { RouterPlugin } from './plugin'
+import { effectScope } from 'vue'
+import {
+  APP_KEY,
+  EFFECT_SCOPE_KEY,
+  RUN_WITH_APP_HANDLERS_KEY,
+  UNINSTALL_HANDLERS_KEY,
+} from './meta-keys'
+
+/**
+ * 安装单一插件
+ */
+export function setupPlugin({
+  router,
+  plugin,
+}: {
+  router: Router
+  plugin: RouterPlugin
+}): void {
+  const scope = (router[EFFECT_SCOPE_KEY] ??= effectScope(true))
+  // 在 scope 中运行插件
+  scope.run(() => {
+    plugin({
+      router,
+      onUninstall(handler) {
+        const handlers = (router[UNINSTALL_HANDLERS_KEY] ??= [])
+        handlers.push(handler)
+      },
+      runWithApp(handler) {
+        // 在 scope 中运行 handler
+        const rawHandler = handler
+        handler = (...args) => {
+          return scope.run(() => rawHandler(...args))
+        }
+
+        if (router[APP_KEY]) {
+          handler(router[APP_KEY])
+        }
+        else {
+          const handlers = (router[RUN_WITH_APP_HANDLERS_KEY] ??= [])
+          handlers.push(handler)
+        }
+      },
+    })
+  })
+}

src/types/global.d.ts

@@ -0,0 +1,5 @@
+declare global {
+  const __DEV__: boolean
+}
+
+export {}