@esmx/router-vue 3.0.0-rc.17 → 3.0.0-rc.19

package/dist/util.test.mjs

@@ -0,0 +1,319 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { version } from "vue";
+import {
+  createSymbolProperty,
+  isESModule,
+  isVue3,
+  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");
+    });
+    it("should be consistent with Vue version check", () => {
+      const expectedResult = version.startsWith("3.");
+      expect(isVue3).toBe(expectedResult);
+    });
+  });
+  describe("createSymbolProperty", () => {
+    let testSymbol;
+    let symbolProperty;
+    let testInstance;
+    beforeEach(() => {
+      testSymbol = Symbol("test-symbol");
+      symbolProperty = createSymbolProperty(testSymbol);
+      testInstance = {};
+    });
+    describe("set method", () => {
+      it("should set value using symbol as key", () => {
+        const testValue = "test-value";
+        symbolProperty.set(testInstance, testValue);
+        expect(testInstance[testSymbol]).toBe(testValue);
+      });
+      it("should handle different value types", () => {
+        const stringValue = "string-value";
+        const numberValue = 42;
+        const objectValue = { key: "value" };
+        const arrayValue = [1, 2, 3];
+        const stringProperty = createSymbolProperty(
+          Symbol("string")
+        );
+        const numberProperty = createSymbolProperty(
+          Symbol("number")
+        );
+        const objectProperty = createSymbolProperty(
+          Symbol("object")
+        );
+        const arrayProperty = createSymbolProperty(
+          Symbol("array")
+        );
+        stringProperty.set(testInstance, stringValue);
+        numberProperty.set(testInstance, numberValue);
+        objectProperty.set(testInstance, objectValue);
+        arrayProperty.set(testInstance, arrayValue);
+        expect(stringProperty.get(testInstance)).toBe(stringValue);
+        expect(numberProperty.get(testInstance)).toBe(numberValue);
+        expect(objectProperty.get(testInstance)).toBe(objectValue);
+        expect(arrayProperty.get(testInstance)).toBe(arrayValue);
+      });
+      it("should overwrite existing value", () => {
+        const firstValue = "first-value";
+        const secondValue = "second-value";
+        symbolProperty.set(testInstance, firstValue);
+        expect(symbolProperty.get(testInstance)).toBe(firstValue);
+        symbolProperty.set(testInstance, secondValue);
+        expect(symbolProperty.get(testInstance)).toBe(secondValue);
+      });
+    });
+    describe("get method", () => {
+      it("should return undefined for non-existent symbol", () => {
+        const result = symbolProperty.get(testInstance);
+        expect(result).toBeUndefined();
+      });
+      it("should return correct value after setting", () => {
+        const testValue = "retrieved-value";
+        symbolProperty.set(testInstance, testValue);
+        const result = symbolProperty.get(testInstance);
+        expect(result).toBe(testValue);
+      });
+      it("should return undefined after value is deleted", () => {
+        const testValue = "temporary-value";
+        symbolProperty.set(testInstance, testValue);
+        delete testInstance[testSymbol];
+        const result = symbolProperty.get(testInstance);
+        expect(result).toBeUndefined();
+      });
+    });
+    describe("symbol isolation", () => {
+      it("should not interfere with different symbols", () => {
+        const symbol1 = Symbol("symbol1");
+        const symbol2 = Symbol("symbol2");
+        const property1 = createSymbolProperty(symbol1);
+        const property2 = createSymbolProperty(symbol2);
+        const value1 = "value1";
+        const value2 = "value2";
+        property1.set(testInstance, value1);
+        property2.set(testInstance, value2);
+        expect(property1.get(testInstance)).toBe(value1);
+        expect(property2.get(testInstance)).toBe(value2);
+        expect(property1.get(testInstance)).not.toBe(value2);
+        expect(property2.get(testInstance)).not.toBe(value1);
+      });
+      it("should work with multiple instances", () => {
+        const instance1 = {};
+        const instance2 = {};
+        const testValue1 = "instance1-value";
+        const testValue2 = "instance2-value";
+        symbolProperty.set(instance1, testValue1);
+        symbolProperty.set(instance2, testValue2);
+        expect(symbolProperty.get(instance1)).toBe(testValue1);
+        expect(symbolProperty.get(instance2)).toBe(testValue2);
+      });
+    });
+    describe("type safety", () => {
+      it("should maintain type information through generic", () => {
+        const interfaceSymbol = Symbol("interface");
+        const interfaceProperty = createSymbolProperty(interfaceSymbol);
+        const testObject = { name: "test", count: 5 };
+        interfaceProperty.set(testInstance, testObject);
+        const result = interfaceProperty.get(testInstance);
+        expect(result).toEqual(testObject);
+        expect(result == null ? void 0 : result.name).toBe("test");
+        expect(result == null ? void 0 : result.count).toBe(5);
+      });
+    });
+  });
+  describe("isESModule", () => {
+    describe("should return true for ES modules", () => {
+      it("should identify module with __esModule property", () => {
+        const esModule = { __esModule: true };
+        expect(isESModule(esModule)).toBe(true);
+      });
+      it("should identify module with Symbol.toStringTag", () => {
+        const esModule = { [Symbol.toStringTag]: "Module" };
+        expect(isESModule(esModule)).toBe(true);
+      });
+      it("should identify module with both properties", () => {
+        const esModule = {
+          __esModule: true,
+          [Symbol.toStringTag]: "Module"
+        };
+        expect(isESModule(esModule)).toBe(true);
+      });
+      it("should handle truthy __esModule values", () => {
+        const testCases = [
+          { __esModule: true },
+          { __esModule: 1 },
+          { __esModule: "true" },
+          { __esModule: {} },
+          { __esModule: [] }
+        ];
+        testCases.forEach((moduleObj) => {
+          expect(isESModule(moduleObj)).toBe(true);
+        });
+      });
+    });
+    describe("should return false for non-ES modules", () => {
+      it("should return false for null", () => {
+        expect(isESModule(null)).toBe(false);
+      });
+      it("should return false for undefined", () => {
+        expect(isESModule(void 0)).toBe(false);
+      });
+      it("should return false for plain objects", () => {
+        const plainObject = { key: "value" };
+        expect(isESModule(plainObject)).toBe(false);
+      });
+      it("should return false for objects with falsy __esModule", () => {
+        const testCases = [
+          { __esModule: false },
+          { __esModule: 0 },
+          { __esModule: "" },
+          { __esModule: null },
+          { __esModule: void 0 }
+        ];
+        testCases.forEach((moduleObj) => {
+          expect(isESModule(moduleObj)).toBe(false);
+        });
+      });
+      it("should return false for objects with wrong Symbol.toStringTag", () => {
+        const testCases = [
+          { [Symbol.toStringTag]: "Object" },
+          { [Symbol.toStringTag]: "Function" },
+          { [Symbol.toStringTag]: "Array" },
+          { [Symbol.toStringTag]: "" },
+          { [Symbol.toStringTag]: null }
+        ];
+        testCases.forEach((moduleObj) => {
+          expect(isESModule(moduleObj)).toBe(false);
+        });
+      });
+      it("should return false for primitive values", () => {
+        const primitives = ["string", 42, true, false, Symbol("test")];
+        primitives.forEach((primitive) => {
+          expect(isESModule(primitive)).toBe(false);
+        });
+      });
+    });
+  });
+  describe("resolveComponent", () => {
+    describe("should return null for falsy inputs", () => {
+      const falsyValues = [null, void 0, false, 0, "", Number.NaN];
+      falsyValues.forEach((value) => {
+        it(`should return null for ${value}`, () => {
+          expect(resolveComponent(value)).toBeNull();
+        });
+      });
+    });
+    describe("should handle ES modules", () => {
+      it("should return default export when available", () => {
+        const defaultComponent = { name: "DefaultComponent" };
+        const esModule = {
+          __esModule: true,
+          default: defaultComponent,
+          namedExport: { name: "NamedComponent" }
+        };
+        const result = resolveComponent(esModule);
+        expect(result).toBe(defaultComponent);
+      });
+      it("should return the module itself when no default export", () => {
+        const esModule = {
+          __esModule: true,
+          namedExport: { name: "NamedComponent" }
+        };
+        const result = resolveComponent(esModule);
+        expect(result).toBe(esModule);
+      });
+      it("should prefer default export over module when both exist", () => {
+        const defaultComponent = { name: "DefaultComponent" };
+        const esModule = {
+          __esModule: true,
+          default: defaultComponent,
+          name: "ModuleComponent"
+        };
+        const result = resolveComponent(esModule);
+        expect(result).toBe(defaultComponent);
+        expect(result).not.toBe(esModule);
+      });
+      it("should handle modules with Symbol.toStringTag", () => {
+        const defaultComponent = { name: "SymbolTagComponent" };
+        const esModule = {
+          [Symbol.toStringTag]: "Module",
+          default: defaultComponent
+        };
+        const result = resolveComponent(esModule);
+        expect(result).toBe(defaultComponent);
+      });
+      it("should handle falsy default export", () => {
+        const falsyDefaults = [null, void 0, false, 0, ""];
+        falsyDefaults.forEach((falsyDefault) => {
+          const esModule = {
+            __esModule: true,
+            default: falsyDefault,
+            fallback: { name: "FallbackComponent" }
+          };
+          const result = resolveComponent(esModule);
+          expect(result).toBe(esModule);
+        });
+      });
+    });
+    describe("should handle non-ES modules", () => {
+      it("should return component directly for non-ES modules", () => {
+        const component = { name: "RegularComponent" };
+        const result = resolveComponent(component);
+        expect(result).toBe(component);
+      });
+      it("should return function components directly", () => {
+        const functionComponent = () => ({ name: "FunctionComponent" });
+        const result = resolveComponent(functionComponent);
+        expect(result).toBe(functionComponent);
+      });
+      it("should return class components directly", () => {
+        class ClassComponent {
+          name = "ClassComponent";
+        }
+        const result = resolveComponent(ClassComponent);
+        expect(result).toBe(ClassComponent);
+      });
+    });
+    describe("edge cases", () => {
+      it("should handle circular references in modules", () => {
+        const esModule = {
+          __esModule: true
+        };
+        esModule.default = esModule;
+        const result = resolveComponent(esModule);
+        expect(result).toBe(esModule);
+      });
+      it("should handle deeply nested default exports", () => {
+        const actualComponent = { name: "DeepComponent" };
+        const esModule = {
+          __esModule: true,
+          default: {
+            default: {
+              default: actualComponent
+            }
+          }
+        };
+        const result = resolveComponent(esModule);
+        expect(result).toEqual({
+          default: {
+            default: actualComponent
+          }
+        });
+      });
+      it("should handle modules with both __esModule and Symbol.toStringTag", () => {
+        const defaultComponent = { name: "BothPropertiesComponent" };
+        const esModule = {
+          __esModule: true,
+          [Symbol.toStringTag]: "Module",
+          default: defaultComponent
+        };
+        const result = resolveComponent(esModule);
+        expect(result).toBe(defaultComponent);
+      });
+    });
+  });
+});

package/dist/vue2.d.ts

@@ -0,0 +1,13 @@
+import type { Route, Router } from '@esmx/router';
+declare module 'vue/types/vue' {
+    interface Vue {
+        readonly $router: Router;
+        readonly $route: Route;
+    }
+}
+declare module 'vue2/types/vue' {
+    interface Vue {
+        readonly $router: Router;
+        readonly $route: Route;
+    }
+}

package/dist/vue3.d.ts

@@ -0,0 +1,13 @@
+import type { Route, Router } from '@esmx/router';
+import type { RouterLink } from './router-link';
+import type { RouterView } from './router-view';
+declare module 'vue' {
+    interface ComponentCustomProperties {
+        readonly $router: Router;
+        readonly $route: Route;
+    }
+    interface GlobalComponents {
+        RouterLink: typeof RouterLink;
+        RouterView: typeof RouterView;
+    }
+}

package/package.json

@@ -1,5 +1,24 @@
 {
     "name": "@esmx/router-vue",
+    "description": "Vue integration for @esmx/router - A universal router that works seamlessly with both Vue 2.7+ and Vue 3",
+    "keywords": [
+        "vue",
+        "router",
+        "routing",
+        "vue-router",
+        "composition-api",
+        "typescript",
+        "universal",
+        "vue2",
+        "vue3",
+        "navigation",
+        "esmx",
+        "esm",
+        "single-page-application",
+        "spa",
+        "framework",
+        "frontend"
+    ],
     "template": "library",
     "scripts": {
         "lint:js": "biome check --write --no-errors-on-unmatched",
@@ -28,26 +47,24 @@
         }
     ],
     "peerDependencies": {
-        "vue": "^3.0.0"
+        "vue": "^3.5.0 || ^2.7.0"
     },
     "dependencies": {
-        "@esmx/router": "3.0.0-rc.17"
+        "@esmx/router": "3.0.0-rc.19"
     },
     "devDependencies": {
         "@biomejs/biome": "1.9.4",
-        "@esmx/lint": "3.0.0-rc.17",
-        "@gez/lint": "3.0.0-rc.9",
-        "@types/node": "22.13.10",
-        "@vitest/coverage-v8": "3.0.8",
-        "@vue/runtime-core": "^3.4.27",
-        "@vue/runtime-dom": "^3.4.27",
-        "stylelint": "16.15.0",
+        "@esmx/lint": "3.0.0-rc.19",
+        "@types/node": "22.15.18",
+        "@vitest/coverage-v8": "3.1.3",
+        "stylelint": "16.19.1",
         "typescript": "5.8.2",
-        "unbuild": "2.0.0",
-        "vitest": "3.0.8",
-        "vue": "^3.4.27"
+        "unbuild": "3.5.0",
+        "vitest": "3.1.3",
+        "vue": "3.5.13",
+        "vue2": "npm:vue@2.7.16"
     },
-    "version": "3.0.0-rc.17",
+    "version": "3.0.0-rc.19",
     "type": "module",
     "private": false,
     "exports": {
@@ -66,5 +83,5 @@
         "template",
         "public"
     ],
-    "gitHead": "5304ac6ef7a3b5d3bcb2db59cceb3f35723c2409"
+    "gitHead": "83a9cfac4a91b2b54ac576e120bb4541f4cce9d6"
 }

package/src/index.test.ts

@@ -0,0 +1,263 @@
+/**
+ * @vitest-environment happy-dom
+ */
+import { describe, expect, it } from 'vitest';
+import * as RouterVueModule from './index';
+
+describe('index.ts - Package Entry Point', () => {
+    describe('Composition API Exports', () => {
+        it('should export useRouter function', () => {
+            expect(RouterVueModule.useRouter).toBeDefined();
+            expect(typeof RouterVueModule.useRouter).toBe('function');
+        });
+
+        it('should export useRoute function', () => {
+            expect(RouterVueModule.useRoute).toBeDefined();
+            expect(typeof RouterVueModule.useRoute).toBe('function');
+        });
+
+        it('should export useProvideRouter function', () => {
+            expect(RouterVueModule.useProvideRouter).toBeDefined();
+            expect(typeof RouterVueModule.useProvideRouter).toBe('function');
+        });
+
+        it('should export useLink function', () => {
+            expect(RouterVueModule.useLink).toBeDefined();
+            expect(typeof RouterVueModule.useLink).toBe('function');
+        });
+    });
+
+    describe('Options API Exports', () => {
+        it('should export getRouter function', () => {
+            expect(RouterVueModule.getRouter).toBeDefined();
+            expect(typeof RouterVueModule.getRouter).toBe('function');
+        });
+
+        it('should export getRoute function', () => {
+            expect(RouterVueModule.getRoute).toBeDefined();
+            expect(typeof RouterVueModule.getRoute).toBe('function');
+        });
+    });
+
+    describe('Component Exports', () => {
+        it('should export RouterLink component', () => {
+            expect(RouterVueModule.RouterLink).toBeDefined();
+            expect(typeof RouterVueModule.RouterLink).toBe('object');
+            expect(RouterVueModule.RouterLink.name).toBe('RouterLink');
+            expect(typeof RouterVueModule.RouterLink.setup).toBe('function');
+        });
+
+        it('should export RouterView component', () => {
+            expect(RouterVueModule.RouterView).toBeDefined();
+            expect(typeof RouterVueModule.RouterView).toBe('object');
+            expect(RouterVueModule.RouterView.name).toBe('RouterView');
+            expect(typeof RouterVueModule.RouterView.setup).toBe('function');
+        });
+    });
+
+    describe('Plugin Exports', () => {
+        it('should export RouterPlugin', () => {
+            expect(RouterVueModule.RouterPlugin).toBeDefined();
+            expect(typeof RouterVueModule.RouterPlugin).toBe('object');
+            expect(typeof RouterVueModule.RouterPlugin.install).toBe(
+                'function'
+            );
+        });
+    });
+
+    describe('Export Completeness', () => {
+        it('should export all expected functions and components', () => {
+            const expectedExports = [
+                // Composition API
+                'useRouter',
+                'useRoute',
+                'useProvideRouter',
+                'useLink',
+                // Options API
+                'getRouter',
+                'getRoute',
+                // Components
+                'RouterLink',
+                'RouterView',
+                // Plugin
+                'RouterPlugin'
+            ];
+
+            expectedExports.forEach((exportName) => {
+                expect(RouterVueModule).toHaveProperty(exportName);
+                expect(
+                    RouterVueModule[exportName as keyof typeof RouterVueModule]
+                ).toBeDefined();
+            });
+        });
+
+        it('should not export unexpected items', () => {
+            const actualExports = Object.keys(RouterVueModule);
+            const expectedExports = [
+                'useRouter',
+                'useRoute',
+                'useProvideRouter',
+                'useLink',
+                'getRouter',
+                'getRoute',
+                'RouterLink',
+                'RouterView',
+                'RouterPlugin'
+            ];
+
+            // Check that we don't have unexpected exports
+            const unexpectedExports = actualExports.filter(
+                (exportName) => !expectedExports.includes(exportName)
+            );
+
+            expect(unexpectedExports).toEqual([]);
+        });
+    });
+
+    describe('Function Signatures', () => {
+        it('should have correct function signatures for Composition API', () => {
+            // These should throw expected errors when called without proper context
+            expect(() => {
+                RouterVueModule.useRouter();
+            }).toThrow('useRouter() can only be called during setup()');
+
+            expect(() => {
+                RouterVueModule.useRoute();
+            }).toThrow('useRoute() can only be called during setup()');
+
+            expect(() => {
+                RouterVueModule.useLink({
+                    to: '/test',
+                    type: 'push',
+                    exact: 'include'
+                });
+            }).toThrow('useRouter() can only be called during setup()');
+        });
+
+        it('should have correct function signatures for Options API', () => {
+            expect(() => {
+                try {
+                    RouterVueModule.getRouter({} as Record<string, unknown>);
+                } catch (error: unknown) {
+                    // Expected to throw context error when called without router
+                    expect((error as Error).message).toContain(
+                        'Router context not found'
+                    );
+                }
+            }).not.toThrow();
+
+            expect(() => {
+                try {
+                    RouterVueModule.getRoute({} as Record<string, unknown>);
+                } catch (error: unknown) {
+                    // Expected to throw context error when called without router
+                    expect((error as Error).message).toContain(
+                        'Router context not found'
+                    );
+                }
+            }).not.toThrow();
+        });
+    });
+
+    describe('Component Properties', () => {
+        it('should have RouterLink with correct properties', () => {
+            const { RouterLink } = RouterVueModule;
+
+            expect(RouterLink.name).toBe('RouterLink');
+            expect(RouterLink.props).toBeDefined();
+            expect(RouterLink.setup).toBeDefined();
+
+            // Check required props
+            expect(RouterLink.props.to).toBeDefined();
+            expect(RouterLink.props.to.required).toBe(true);
+
+            // Check default props
+            expect(RouterLink.props.type.default).toBe('push');
+            expect(RouterLink.props.exact.default).toBe('include');
+            expect(RouterLink.props.tag.default).toBe('a');
+            expect(RouterLink.props.event.default).toBe('click');
+        });
+
+        it('should have RouterView with correct properties', () => {
+            const { RouterView } = RouterVueModule;
+
+            expect(RouterView.name).toBe('RouterView');
+            expect(RouterView.setup).toBeDefined();
+            // RouterView should not have props
+            expect(RouterView.props).toBeUndefined();
+        });
+    });
+
+    describe('Plugin Interface', () => {
+        it('should have RouterPlugin with install method', () => {
+            const { RouterPlugin } = RouterVueModule;
+
+            expect(RouterPlugin.install).toBeDefined();
+            expect(typeof RouterPlugin.install).toBe('function');
+
+            // Test plugin install signature - should throw for null input
+            expect(() => {
+                RouterPlugin.install(null);
+            }).toThrow();
+        });
+    });
+
+    describe('Module Structure', () => {
+        it('should be a proper ES module', () => {
+            // Check that the module exports are properly structured
+            expect(typeof RouterVueModule).toBe('object');
+            expect(RouterVueModule).not.toBeNull();
+
+            // Verify it's not a default export
+            expect('default' in RouterVueModule).toBe(false);
+        });
+
+        it('should have consistent export naming', () => {
+            // All function exports should be camelCase
+            const functionExports = [
+                'useRouter',
+                'useRoute',
+                'useProvideRouter',
+                'useLink',
+                'getRouter',
+                'getRoute'
+            ];
+
+            functionExports.forEach((exportName) => {
+                expect(exportName).toMatch(/^[a-z][a-zA-Z]*$/);
+            });
+
+            // Component exports should be PascalCase
+            const componentExports = [
+                'RouterLink',
+                'RouterView',
+                'RouterPlugin'
+            ];
+
+            componentExports.forEach((exportName) => {
+                expect(exportName).toMatch(/^[A-Z][a-zA-Z]*$/);
+            });
+        });
+    });
+
+    describe('TypeScript Integration', () => {
+        it('should provide proper TypeScript types', () => {
+            // These checks verify that TypeScript types are properly exported
+            // The actual type checking is done by the TypeScript compiler
+
+            // Verify functions have proper types
+            expect(typeof RouterVueModule.useRouter).toBe('function');
+            expect(typeof RouterVueModule.useRoute).toBe('function');
+            expect(typeof RouterVueModule.getRouter).toBe('function');
+            expect(typeof RouterVueModule.getRoute).toBe('function');
+
+            // Verify components have proper structure
+            expect(RouterVueModule.RouterLink).toHaveProperty('name');
+            expect(RouterVueModule.RouterLink).toHaveProperty('props');
+            expect(RouterVueModule.RouterLink).toHaveProperty('setup');
+
+            expect(RouterVueModule.RouterView).toHaveProperty('name');
+            expect(RouterVueModule.RouterView).toHaveProperty('setup');
+        });
+    });
+});