@esmx/router-vue 3.0.0-rc.84 → 3.0.0-rc.92

package/dist/use.mjs

@@ -6,7 +6,12 @@ import {
   provide,
   ref
 } from "vue";
-import { createDependentProxy, createSymbolProperty } from "./util.mjs";
+import {
+  createDependentProxy,
+  createSymbolProperty,
+  defineRouterProperties,
+  isVue2
+} from "./util.mjs";
 const ROUTER_CONTEXT_KEY = Symbol("router-context");
 const ROUTER_INJECT_KEY = Symbol("router-inject");
 const ROUTER_VIEW_DEPTH_KEY = Symbol("router-view-depth");
@@ -24,9 +29,6 @@ function getCurrentProxy() {
   return instance.proxy;
 }
 function findRouterContext(vm) {
-  if (!vm) {
-    vm = getCurrentProxy();
-  }
   let context = routerContextProperty.get(vm);
   if (context) {
     return context;
@@ -75,6 +77,15 @@ export function useProvideRouter(router) {
   };
   provide(ROUTER_INJECT_KEY, context);
   routerContextProperty.set(proxy, context);
+  if (!isVue2) {
+    const app = getCurrentInstance().appContext.app;
+    defineRouterProperties(
+      app.config.globalProperties,
+      () => proxiedRouter,
+      () => proxiedRoute,
+      true
+    );
+  }
   const unwatch = router.afterEach((to) => {
     if (router.route === to) {
       to.syncTo(proxiedRoute);

package/dist/util.d.ts

@@ -1,5 +1,16 @@
+import type { Route, Router } from '@esmx/router';
 import type { Ref } from 'vue';
-export declare const isVue3: boolean;
+export declare const isVue2: boolean;
+/**
+ * Define $router and $route properties on a target object.
+ * Used to set up global properties for Vue components.
+ *
+ * @param target - The target object to define properties on (e.g., globalProperties or prototype)
+ * @param routerGetter - Getter function for $router (can use `this` in Vue 2)
+ * @param routeGetter - Getter function for $route (can use `this` in Vue 2)
+ * @param configurable - Whether the properties should be configurable (default: false)
+ */
+export declare function defineRouterProperties(target: Record<string, unknown>, routerGetter: (this: unknown) => Router, routeGetter: (this: unknown) => Route, configurable?: boolean): void;
 export declare function createSymbolProperty<T>(symbol: symbol): {
     readonly set: (instance: any, value: T) => void;
     readonly get: (instance: any) => T | undefined;

package/dist/util.mjs

@@ -1,5 +1,19 @@
 import { version } from "vue";
-export const isVue3 = version.startsWith("3.");
+export const isVue2 = version.startsWith("2.");
+export function defineRouterProperties(target, routerGetter, routeGetter, configurable = false) {
+  Object.defineProperties(target, {
+    $router: {
+      configurable,
+      enumerable: false,
+      get: routerGetter
+    },
+    $route: {
+      configurable,
+      enumerable: false,
+      get: routeGetter
+    }
+  });
+}
 export function createSymbolProperty(symbol) {
   return {
     set(instance, value) {

package/dist/util.test.d.ts

@@ -1 +1,4 @@
+/**
+ * @vitest-environment happy-dom
+ */
 export {};

package/dist/util.test.mjs

@@ -6,19 +6,20 @@ import { computed, nextTick, ref, version } from "vue";
 import {
   createDependentProxy,
   createSymbolProperty,
+  defineRouterProperties,
   isESModule,
-  isVue3,
+  isVue2,
   resolveComponent
 } from "./util.mjs";
 describe("util.ts - Utility Functions", () => {
-  describe("isVue3", () => {
-    it("should correctly identify Vue 3", () => {
-      expect(isVue3).toBe(version.startsWith("3."));
-      expect(typeof isVue3).toBe("boolean");
+  describe("isVue2", () => {
+    it("should correctly identify Vue 2", () => {
+      expect(isVue2).toBe(version.startsWith("2."));
+      expect(typeof isVue2).toBe("boolean");
     });
     it("should be consistent with Vue version check", () => {
-      const expectedResult = version.startsWith("3.");
-      expect(isVue3).toBe(expectedResult);
+      const expectedResult = version.startsWith("2.");
+      expect(isVue2).toBe(expectedResult);
     });
   });
   describe("createSymbolProperty", () => {
@@ -380,4 +381,224 @@ describe("util.ts - Utility Functions", () => {
       expect(spy).toHaveBeenCalled();
     });
   });
+  describe("defineRouterProperties", () => {
+    it("should define $router and $route properties on target object", () => {
+      const target = {};
+      const mockRouter = { push: vi.fn() };
+      const mockRoute = { path: "/test" };
+      const routerGetter = vi.fn(function() {
+        return mockRouter;
+      });
+      const routeGetter = vi.fn(function() {
+        return mockRoute;
+      });
+      defineRouterProperties(target, routerGetter, routeGetter);
+      expect(target).toHaveProperty("$router");
+      expect(target).toHaveProperty("$route");
+    });
+    it("should call getter functions when accessing properties", () => {
+      const target = {};
+      const mockRouter = { push: vi.fn() };
+      const mockRoute = { path: "/test" };
+      const routerGetter = vi.fn(function() {
+        return mockRouter;
+      });
+      const routeGetter = vi.fn(function() {
+        return mockRoute;
+      });
+      defineRouterProperties(target, routerGetter, routeGetter);
+      const router = target.$router;
+      const route = target.$route;
+      expect(routerGetter).toHaveBeenCalled();
+      expect(routeGetter).toHaveBeenCalled();
+      expect(router).toBe(mockRouter);
+      expect(route).toBe(mockRoute);
+    });
+    it("should use correct this context in getter functions", () => {
+      const target = { customProp: "test" };
+      const mockRouter = { push: vi.fn() };
+      const mockRoute = { path: "/test" };
+      const routerGetter = vi.fn(function() {
+        return this.customProp ? mockRouter : {};
+      });
+      const routeGetter = vi.fn(function() {
+        return this.customProp ? mockRoute : {};
+      });
+      defineRouterProperties(target, routerGetter, routeGetter);
+      const router = target.$router;
+      const route = target.$route;
+      expect(router).toBe(mockRouter);
+      expect(route).toBe(mockRoute);
+    });
+    it("should make properties non-enumerable by default", () => {
+      const target = {};
+      const mockRouter = { push: vi.fn() };
+      const mockRoute = { path: "/test" };
+      const routerGetter = vi.fn(function() {
+        return mockRouter;
+      });
+      const routeGetter = vi.fn(function() {
+        return mockRoute;
+      });
+      defineRouterProperties(target, routerGetter, routeGetter);
+      const descriptors = Object.getOwnPropertyDescriptors(target);
+      expect(descriptors.$router.enumerable).toBe(false);
+      expect(descriptors.$route.enumerable).toBe(false);
+    });
+    it("should make properties non-configurable by default", () => {
+      const target = {};
+      const mockRouter = { push: vi.fn() };
+      const mockRoute = { path: "/test" };
+      const routerGetter = vi.fn(function() {
+        return mockRouter;
+      });
+      const routeGetter = vi.fn(function() {
+        return mockRoute;
+      });
+      defineRouterProperties(target, routerGetter, routeGetter);
+      const descriptors = Object.getOwnPropertyDescriptors(target);
+      expect(descriptors.$router.configurable).toBe(false);
+      expect(descriptors.$route.configurable).toBe(false);
+    });
+    it("should make properties configurable when configurable option is true", () => {
+      const target = {};
+      const mockRouter = { push: vi.fn() };
+      const mockRoute = { path: "/test" };
+      const routerGetter = vi.fn(function() {
+        return mockRouter;
+      });
+      const routeGetter = vi.fn(function() {
+        return mockRoute;
+      });
+      defineRouterProperties(target, routerGetter, routeGetter, true);
+      const descriptors = Object.getOwnPropertyDescriptors(target);
+      expect(descriptors.$router.configurable).toBe(true);
+      expect(descriptors.$route.configurable).toBe(true);
+    });
+    it("should define properties as getters", () => {
+      const target = {};
+      const mockRouter = { push: vi.fn() };
+      const mockRoute = { path: "/test" };
+      const routerGetter = vi.fn(function() {
+        return mockRouter;
+      });
+      const routeGetter = vi.fn(function() {
+        return mockRoute;
+      });
+      defineRouterProperties(target, routerGetter, routeGetter);
+      const descriptors = Object.getOwnPropertyDescriptors(target);
+      expect(typeof descriptors.$router.get).toBe("function");
+      expect(typeof descriptors.$route.get).toBe("function");
+      expect(descriptors.$router.set).toBeUndefined();
+      expect(descriptors.$route.set).toBeUndefined();
+    });
+    it("should call getter each time property is accessed", () => {
+      const target = {};
+      const mockRouter = { push: vi.fn() };
+      const routerGetter = vi.fn(function() {
+        return mockRouter;
+      });
+      const routeGetter = vi.fn(function() {
+        return { path: "/test" };
+      });
+      defineRouterProperties(target, routerGetter, routeGetter);
+      target.$router;
+      target.$router;
+      target.$router;
+      expect(routerGetter).toHaveBeenCalledTimes(3);
+    });
+    it("should work with different target objects", () => {
+      const targets = [
+        {},
+        { existingProp: "value" },
+        /* @__PURE__ */ Object.create(null),
+        new class Test {
+        }()
+      ];
+      const mockRouter = { push: vi.fn() };
+      const mockRoute = { path: "/test" };
+      const routerGetter = vi.fn(function() {
+        return mockRouter;
+      });
+      const routeGetter = vi.fn(function() {
+        return mockRoute;
+      });
+      targets.forEach((target) => {
+        defineRouterProperties(target, routerGetter, routeGetter);
+        expect(target).toHaveProperty("$router");
+        expect(target).toHaveProperty("$route");
+        const router = target.$router;
+        const route = target.$route;
+        expect(router).toBe(mockRouter);
+        expect(route).toBe(mockRoute);
+      });
+    });
+    it("should preserve existing properties on target object", () => {
+      const target = {
+        existingProp: "value",
+        $existingRouter: "should not be affected"
+      };
+      const mockRouter = { push: vi.fn() };
+      const mockRoute = { path: "/test" };
+      const routerGetter = vi.fn(function() {
+        return mockRouter;
+      });
+      const routeGetter = vi.fn(function() {
+        return mockRoute;
+      });
+      defineRouterProperties(target, routerGetter, routeGetter);
+      expect(target.existingProp).toBe("value");
+      expect(target.$existingRouter).toBe("should not be affected");
+      expect(target).toHaveProperty("$router");
+      expect(target).toHaveProperty("$route");
+    });
+    it("should handle getter functions that return undefined", () => {
+      const target = {};
+      const routerGetter = vi.fn(function() {
+        return void 0;
+      });
+      const routeGetter = vi.fn(function() {
+        return void 0;
+      });
+      defineRouterProperties(target, routerGetter, routeGetter);
+      const router = target.$router;
+      const route = target.$route;
+      expect(router).toBeUndefined();
+      expect(route).toBeUndefined();
+      expect(routerGetter).toHaveBeenCalled();
+      expect(routeGetter).toHaveBeenCalled();
+    });
+    it("should handle getter functions that throw errors", () => {
+      const target = {};
+      const routerGetter = vi.fn(function() {
+        throw new Error("Router error");
+      });
+      const routeGetter = vi.fn(function() {
+        throw new Error("Route error");
+      });
+      defineRouterProperties(target, routerGetter, routeGetter);
+      expect(() => target.$router).toThrow("Router error");
+      expect(() => target.$route).toThrow("Route error");
+    });
+    it("should work with arrow functions as getters", () => {
+      const target = {};
+      const mockRouter = { push: vi.fn() };
+      const mockRoute = { path: "/test" };
+      const context = { customContext: "test" };
+      const routerGetter = vi.fn(() => mockRouter);
+      const routeGetter = vi.fn(() => mockRoute);
+      defineRouterProperties.call(
+        context,
+        target,
+        routerGetter,
+        routeGetter
+      );
+      const router = target.$router;
+      const route = target.$route;
+      expect(router).toBe(mockRouter);
+      expect(route).toBe(mockRoute);
+      expect(routerGetter).toHaveBeenCalled();
+      expect(routeGetter).toHaveBeenCalled();
+    });
+  });
 });

package/package.json

@@ -50,7 +50,7 @@
         "vue": "^3.5.0 || ^2.7.0"
     },
     "dependencies": {
-        "@esmx/router": "3.0.0-rc.84"
+        "@esmx/router": "3.0.0-rc.92"
     },
     "devDependencies": {
         "@biomejs/biome": "2.3.7",
@@ -62,7 +62,7 @@
         "vue": "3.5.23",
         "vue2": "npm:vue@2.7.16"
     },
-    "version": "3.0.0-rc.84",
+    "version": "3.0.0-rc.92",
     "type": "module",
     "private": false,
     "exports": {
@@ -81,5 +81,5 @@
         "template",
         "public"
     ],
-    "gitHead": "21f81d3d3083f4008b491d7d906d772ffb537007"
+    "gitHead": "29551aee397c15945595d0e34488e853ede02497"
 }

package/src/plugin.test.ts

@@ -155,9 +155,8 @@ describe('plugin.ts - RouterPlugin', () => {
             expect(routeDescriptor?.get).toBeDefined();
             expect(typeof routeDescriptor?.get).toBe('function');
 
-            // Verify the descriptor is properly configured for reactivity
             expect(routeDescriptor?.enumerable).toBe(false);
-            expect(routeDescriptor?.configurable).toBe(false);
+            expect(routeDescriptor?.configurable).toBe(true);
         });
 
         it('should provide consistent $router instance across components', async () => {
@@ -481,6 +480,253 @@ describe('plugin.ts - RouterPlugin', () => {
         });
     });
 
+    describe('$router and $route Access', () => {
+        it('should throw error when accessing $router without useProvideRouter', () => {
+            app = createApp({
+                render: () => h('div', 'Test App')
+            });
+
+            app.use(RouterPlugin);
+
+            const globalProperties = app.config.globalProperties;
+            expect(() => {
+                (globalProperties as any).$router;
+            }).toThrow(
+                '[@esmx/router-vue] Router not provided. Please call useProvideRouter() in your root component setup.'
+            );
+        });
+
+        it('should throw error when accessing $route without useProvideRouter', () => {
+            app = createApp({
+                render: () => h('div', 'Test App')
+            });
+
+            app.use(RouterPlugin);
+
+            const globalProperties = app.config.globalProperties;
+            expect(() => {
+                (globalProperties as any).$route;
+            }).toThrow(
+                '[@esmx/router-vue] Router not provided. Please call useProvideRouter() in your root component setup.'
+            );
+        });
+
+        it('should override default getters after useProvideRouter is called', async () => {
+            app = createApp({
+                setup() {
+                    useProvideRouter(router);
+                    return () => h('div', 'Test App');
+                }
+            });
+
+            app.use(RouterPlugin);
+            app.mount(container);
+            await nextTick();
+
+            const globalProperties = app.config.globalProperties;
+            expect(() => {
+                (globalProperties as any).$router;
+            }).not.toThrow();
+            expect(() => {
+                (globalProperties as any).$route;
+            }).not.toThrow();
+        });
+
+        it('should return correct router instance via $router', async () => {
+            let capturedRouter: Router | null = null;
+
+            const TestComponent = defineComponent({
+                mounted() {
+                    capturedRouter = this.$router;
+                },
+                render() {
+                    return h('div', 'Test');
+                }
+            });
+
+            app = createApp({
+                setup() {
+                    useProvideRouter(router);
+                    return () => h(TestComponent);
+                }
+            });
+
+            app.use(RouterPlugin);
+            app.mount(container);
+            await nextTick();
+
+            expect(capturedRouter).toBeDefined();
+            expect(capturedRouter).toBeInstanceOf(Router);
+            expect((capturedRouter as unknown as Router).route.path).toBe('/');
+        });
+
+        it('should return correct route via $route', async () => {
+            let capturedRoute: Route | null = null;
+
+            const TestComponent = defineComponent({
+                mounted() {
+                    capturedRoute = this.$route;
+                },
+                render() {
+                    return h('div', 'Test');
+                }
+            });
+
+            app = createApp({
+                setup() {
+                    useProvideRouter(router);
+                    return () => h(TestComponent);
+                }
+            });
+
+            app.use(RouterPlugin);
+            app.mount(container);
+            await nextTick();
+
+            expect(capturedRoute).toBeDefined();
+            expect((capturedRoute as unknown as Route).path).toBe('/');
+            expect((capturedRoute as unknown as Route).meta?.title).toBe(
+                'Home'
+            );
+        });
+
+        it('should update $route when navigation occurs', async () => {
+            const routes: string[] = [];
+
+            const TestComponent = defineComponent({
+                mounted() {
+                    routes.push(this.$route.path);
+                },
+                updated() {
+                    routes.push(this.$route.path);
+                },
+                render() {
+                    return h('div', this.$route.path);
+                }
+            });
+
+            app = createApp({
+                setup() {
+                    useProvideRouter(router);
+                    return () => h(TestComponent);
+                }
+            });
+
+            app.use(RouterPlugin);
+            app.mount(container);
+            await nextTick();
+
+            expect(routes).toContain('/');
+
+            await router.push('/about');
+            await nextTick();
+
+            expect(router.route.path).toBe('/about');
+        });
+
+        it('should provide same $router instance in nested components', async () => {
+            const routerInstances: Router[] = [];
+
+            const ChildComponent = defineComponent({
+                mounted() {
+                    routerInstances.push(this.$router);
+                },
+                render() {
+                    return h('div', 'Child');
+                }
+            });
+
+            const ParentComponent = defineComponent({
+                mounted() {
+                    routerInstances.push(this.$router);
+                },
+                render() {
+                    return h('div', [h('span', 'Parent'), h(ChildComponent)]);
+                }
+            });
+
+            app = createApp({
+                setup() {
+                    useProvideRouter(router);
+                    return () => h(ParentComponent);
+                }
+            });
+
+            app.use(RouterPlugin);
+            app.mount(container);
+            await nextTick();
+
+            expect(routerInstances.length).toBe(2);
+            expect(routerInstances[0]).toBe(routerInstances[1]);
+        });
+
+        it('should allow navigation via $router.push', async () => {
+            let capturedRouter: Router | null = null;
+
+            const TestComponent = defineComponent({
+                mounted() {
+                    capturedRouter = this.$router;
+                },
+                render() {
+                    return h('div', 'Test');
+                }
+            });
+
+            app = createApp({
+                setup() {
+                    useProvideRouter(router);
+                    return () => h(TestComponent);
+                }
+            });
+
+            app.use(RouterPlugin);
+            app.mount(container);
+            await nextTick();
+
+            expect(capturedRouter).toBeDefined();
+            const routerInstance = capturedRouter as unknown as Router;
+            expect(typeof routerInstance.push).toBe('function');
+
+            await routerInstance.push('/about');
+            await nextTick();
+
+            expect(router.route.path).toBe('/about');
+        });
+
+        it('should allow navigation via $router.replace', async () => {
+            let capturedRouter: Router | null = null;
+
+            const TestComponent = defineComponent({
+                mounted() {
+                    capturedRouter = this.$router;
+                },
+                render() {
+                    return h('div', 'Test');
+                }
+            });
+
+            app = createApp({
+                setup() {
+                    useProvideRouter(router);
+                    return () => h(TestComponent);
+                }
+            });
+
+            app.use(RouterPlugin);
+            app.mount(container);
+            await nextTick();
+
+            expect(capturedRouter).toBeDefined();
+            const routerInstance = capturedRouter as unknown as Router;
+            expect(typeof routerInstance.replace).toBe('function');
+
+            await routerInstance.replace('/about');
+            await nextTick();
+
+            expect(router.route.path).toBe('/about');
+        });
+    });
+
     describe('Advanced Plugin Features', () => {
         it('should support property descriptor configuration', () => {
             interface TestApp {
@@ -516,14 +762,13 @@ describe('plugin.ts - RouterPlugin', () => {
                 '$route'
             );
 
-            // Check descriptor properties - Object.defineProperties sets these to false by default
             expect(routerDescriptor?.get).toBeDefined();
-            expect(routerDescriptor?.enumerable).toBe(false); // Default value from Object.defineProperty
-            expect(routerDescriptor?.configurable).toBe(false); // Default value from Object.defineProperty
+            expect(routerDescriptor?.enumerable).toBe(false);
+            expect(routerDescriptor?.configurable).toBe(true);
 
             expect(routeDescriptor?.get).toBeDefined();
-            expect(routeDescriptor?.enumerable).toBe(false); // Default value from Object.defineProperty
-            expect(routeDescriptor?.configurable).toBe(false); // Default value from Object.defineProperty
+            expect(routeDescriptor?.enumerable).toBe(false);
+            expect(routeDescriptor?.configurable).toBe(true);
         });
 
         it('should handle different app instance structures', () => {

package/src/plugin.ts

@@ -1,7 +1,7 @@
 import { RouterLink } from './router-link';
 import { RouterView } from './router-view';
 import { getRoute, getRouter } from './use';
-import { isVue3 } from './util';
+import { defineRouterProperties, isVue2 } from './util';
 
 interface VueApp {
     config?: {
@@ -81,18 +81,24 @@ export const RouterPlugin = {
         if (!target) {
             throw new Error('[@esmx/router-vue] Invalid Vue app instance');
         }
-        Object.defineProperties(target, {
-            $router: {
-                get() {
-                    return getRouter(isVue3 ? null : this);
+        if (isVue2) {
+            defineRouterProperties(
+                target,
+                function (this: any) {
+                    return getRouter(this);
+                },
+                function (this: any) {
+                    return getRoute(this);
                 }
-            },
-            $route: {
-                get() {
-                    return getRoute(isVue3 ? null : this);
-                }
-            }
-        });
+            );
+        } else {
+            const throwError = () => {
+                throw new Error(
+                    '[@esmx/router-vue] Router not provided. Please call useProvideRouter() in your root component setup.'
+                );
+            };
+            defineRouterProperties(target, throwError, throwError, true);
+        }
 
         // Register global components
         vueApp.component('RouterLink', RouterLink);