@esmx/router 3.0.0-rc.18 → 3.0.0-rc.20

package/package.json

@@ -28,23 +28,20 @@
         }
     ],
     "dependencies": {
-        "normalize-url": "^8.0.1",
-        "path-to-regexp": "^6.2.2",
-        "url-parse": "^1.5.10"
+        "path-to-regexp": "^6.2.2"
     },
     "devDependencies": {
         "@biomejs/biome": "1.9.4",
-        "@esmx/lint": "3.0.0-rc.18",
-        "@gez/lint": "3.0.0-rc.9",
-        "@types/node": "22.13.10",
-        "@types/url-parse": "^1.4.11",
-        "@vitest/coverage-v8": "3.0.8",
-        "stylelint": "16.15.0",
+        "@esmx/lint": "3.0.0-rc.20",
+        "@types/node": "22.15.18",
+        "@vitest/coverage-v8": "3.1.3",
+        "happy-dom": "^18.0.1",
+        "stylelint": "16.19.1",
         "typescript": "5.8.2",
-        "unbuild": "2.0.0",
-        "vitest": "3.0.8"
+        "unbuild": "3.5.0",
+        "vitest": "3.1.3"
     },
-    "version": "3.0.0-rc.18",
+    "version": "3.0.0-rc.20",
     "type": "module",
     "private": false,
     "exports": {
@@ -63,5 +60,5 @@
         "template",
         "public"
     ],
-    "gitHead": "79ceb323f985dd88dbd7f1349f61f341b6d522c4"
+    "gitHead": "4c6490c23cbc148cb189b3f2cdae930eed901607"
 }

package/src/error.ts

@@ -0,0 +1,84 @@
+import type { Route } from './route';
+
+export class RouteError extends Error {
+    public readonly code: string;
+    public readonly to: Route;
+    public readonly from: Route | null;
+
+    constructor(
+        message: string,
+        code: string,
+        to: Route,
+        from: Route | null = null
+    ) {
+        super(message);
+        this.name = 'RouteError';
+        this.code = code;
+        this.to = to;
+        this.from = from;
+    }
+}
+
+export class RouteTaskCancelledError extends RouteError {
+    public readonly taskName: string;
+
+    constructor(taskName: string, to: Route, from: Route | null = null) {
+        super(
+            `Route task "${taskName}" was cancelled`,
+            'ROUTE_TASK_CANCELLED',
+            to,
+            from
+        );
+        this.name = 'RouteTaskCancelledError';
+        this.taskName = taskName;
+    }
+}
+
+export class RouteTaskExecutionError extends RouteError {
+    public readonly taskName: string;
+    public readonly originalError: Error;
+
+    constructor(
+        taskName: string,
+        to: Route,
+        from: Route | null = null,
+        originalError?: unknown
+    ) {
+        const error =
+            originalError instanceof Error
+                ? originalError
+                : new Error(String(originalError));
+        const message = `Route task "${taskName}" failed${error.message ? `: ${error.message}` : ''}`;
+        super(message, 'ROUTE_TASK_EXECUTION_ERROR', to, from);
+        this.name = 'RouteTaskExecutionError';
+        this.taskName = taskName;
+        this.originalError = error;
+    }
+}
+
+export class RouteNavigationAbortedError extends RouteError {
+    public readonly taskName: string;
+
+    constructor(taskName: string, to: Route, from: Route | null = null) {
+        super(
+            `Navigation was aborted by task "${taskName}"`,
+            'ROUTE_NAVIGATION_ABORTED',
+            to,
+            from
+        );
+        this.name = 'RouteNavigationAbortedError';
+        this.taskName = taskName;
+    }
+}
+
+export class RouteSelfRedirectionError extends RouteError {
+    constructor(fullPath: string, to: Route, from: Route | null = null) {
+        super(
+            `Detected a self-redirection to "${fullPath}". Aborting navigation.`,
+            'ROUTE_SELF_REDIRECTION',
+            to,
+            from
+        );
+        this.name = 'RouteSelfRedirectionError';
+    }
+}

package/src/increment-id.ts

@@ -0,0 +1,12 @@
+export class IncrementId {
+    private value = 0;
+    public equal(id: number) {
+        return this.value === id;
+    }
+    public next() {
+        return ++this.value;
+    }
+}
+
+export const PAGE_ID = new IncrementId();
+export const LAYER_ID = new IncrementId();

package/src/index.test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from 'vitest';
+import { Router as IndexRouter } from './index';
+import { Router } from './router';
+
+describe('index exports', () => {
+    it('should export Router correctly', () => {
+        expect(IndexRouter).toBe(Router);
+    });
+});

package/src/index.ts

@@ -1,3 +1,54 @@
-export { createRouter } from './router';
-export * from './types';
-export * from './utils';
+export { Router } from './router';
+export { Route } from './route';
+export { RouteTransition, ROUTE_TYPE_HANDLERS } from './route-transition';
+export {
+    // Utility types
+    type Awaitable,
+    // Core enums
+    RouterMode,
+    RouteType,
+    // Hook function types
+    type RouteConfirmHook,
+    type RouteConfirmHookResult,
+    type RouteVerifyHook,
+    type RouteHandleHook,
+    type RouteNotifyHook,
+    // Basic data types
+    type RouteMeta,
+    type RouteState,
+    type RouteHandleResult,
+    type RouteMatchType,
+    // Route location and config types
+    type RouteLocation,
+    type RouteLocationInput,
+    type RouteConfig,
+    type RouteParsedConfig,
+    type RouteMatchResult,
+    type RouteMatcher,
+    type RouteOptions,
+    // Router Layer types
+    type RouteLayerOptions,
+    type RouteLayerResult,
+    type RouterLayerOptions,
+    // Router MicroApp types
+    type RouterMicroApp,
+    type RouterMicroAppCallback,
+    type RouterMicroAppOptions,
+    // Router core types
+    type RouterOptions,
+    type RouterParsedOptions,
+    // RouterLink types
+    type RouterLinkType,
+    type RouterLinkAttributes,
+    type RouterLinkProps,
+    type RouterLinkResolved
+} from './types';
+
+// Error types
+export {
+    RouteError,
+    RouteTaskCancelledError,
+    RouteTaskExecutionError,
+    RouteNavigationAbortedError,
+    RouteSelfRedirectionError
+} from './error';

package/src/location.test.ts

@@ -0,0 +1,406 @@
+import { describe, expect, test } from 'vitest';
+import { normalizeURL, parseLocation } from './location';
+import type { RouteLocationInput } from './types';
+
+declare module 'vitest' {
+    interface ToEqURLMatchers {
+        toEqURL(expected: URL | string): void;
+    }
+    interface Assertion extends ToEqURLMatchers {}
+}
+
+expect.extend({
+    toEqURL: (received: URL, expected: URL | string) => {
+        if (!(received instanceof URL)) {
+            return {
+                message: () => `expected ${received} to be an instance of URL`,
+                pass: false
+            };
+        }
+        (received = new URL(received)).searchParams.sort();
+        (expected = new URL(expected)).searchParams.sort();
+        // biome-ignore lint/correctness/noSelfAssign:
+        received.hash = received.hash;
+        // biome-ignore lint/correctness/noSelfAssign:
+        expected.hash = expected.hash;
+        return {
+            message: () => `expected ${received.href} to be ${expected.href}`,
+            pass: received.href === expected.href
+        };
+    }
+});
+
+describe('normalizeURL', () => {
+    const testCases: Array<{
+        input: string | URL;
+        base: string;
+        expected: string;
+        description: string;
+    }> = [
+        {
+            input: '//example.com/path',
+            base: 'https://github.com',
+            expected: 'http://example.com/path',
+            description:
+                'should handle protocol-relative URLs (starting with //)'
+        },
+        {
+            input: 'http://github.com/path?a#h',
+            base: 'http://example.com',
+            expected: 'http://github.com/path?a#h',
+            description: 'should handle absolute URLs'
+        },
+        {
+            input: '/path',
+            base: 'http://example.com/en/',
+            expected: 'http://example.com/en/path',
+            description: 'should handle relative paths with a base URL'
+        },
+        {
+            input: 'github.com',
+            base: 'http://example.com',
+            expected: 'http://example.com/github.com',
+            description: 'should treat bare domains as relative paths'
+        },
+        {
+            input: new URL('http://example.com/path'),
+            base: 'http://example.com',
+            expected: 'http://example.com/path',
+            description: 'should handle URL objects'
+        },
+        {
+            input: '-a://example.com',
+            base: 'http://example.com',
+            expected: 'http://example.com/-a://example.com',
+            description:
+                'should treat strings that fail to parse as a protocol as relative paths'
+        }
+    ];
+
+    testCases.forEach(({ input, base, expected, description }) => {
+        test(description, () => {
+            const result = normalizeURL(input, new URL(base));
+            expect(result).toEqURL(expected);
+        });
+    });
+});
+
+describe('parseLocation', () => {
+    const testCases: Array<{
+        input: RouteLocationInput;
+        base: string;
+        expected: string;
+        description: string;
+    }> = [
+        {
+            input: '/products',
+            base: 'http://example.com',
+            expected: 'http://example.com/products',
+            description: 'should handle string paths'
+        },
+        {
+            input: { path: '/products' },
+            base: 'http://example.com',
+            expected: 'http://example.com/products',
+            description: 'should handle objects with a path property'
+        },
+        {
+            input: { url: '/products' },
+            base: 'http://example.com',
+            expected: 'http://example.com/products',
+            description: 'should handle objects with a url property'
+        },
+        {
+            input: {
+                path: '/products',
+                query: { id: '123', category: 'electronics' }
+            },
+            base: 'http://example.com',
+            expected: 'http://example.com/products?id=123&category=electronics',
+            description: 'should handle objects with query parameters'
+        },
+        {
+            input: { path: '/products', query: { id: '123' }, hash: 'details' },
+            base: 'http://example.com',
+            expected: 'http://example.com/products?id=123#details',
+            description: 'should handle objects with a hash'
+        },
+        {
+            input: { path: '/products', queryArray: { tag: ['new', 'sale'] } },
+            base: 'http://example.com',
+            expected: 'http://example.com/products?tag=new&tag=sale',
+            description: 'should handle objects with queryArray'
+        },
+        {
+            input: {
+                path: '/products',
+                query: { id: '123', category: 'electronics' },
+                queryArray: { tag: ['new', 'sale'] },
+                hash: 'details'
+            },
+            base: 'http://example.com',
+            expected:
+                'http://example.com/products?id=123&category=electronics&tag=new&tag=sale#details',
+            description: 'should handle complex objects with all properties'
+        },
+        {
+            input: {
+                path: '/products',
+                hash: '#a?a'
+            },
+            base: 'http://example.com',
+            expected: 'http://example.com/products#a?a',
+            description: 'should handle special hash characters correctly'
+        },
+        {
+            input: {
+                path: '/products',
+                hash: '#a?a#b'
+            },
+            base: 'http://example.com',
+            expected: 'http://example.com/products#a?a#b',
+            description: 'should handle special hash characters correctly'
+        },
+        {
+            input: {
+                path: '/products',
+                query: {
+                    id: null,
+                    category: void 0,
+                    symbol: Symbol(),
+                    fn: async () => '',
+                    obj: { a: 10 },
+                    big: 12345678901234567891234567890123456789n,
+                    a: Number.NaN,
+                    b: '',
+                    c: '0',
+                    d: 0,
+                    e: 1
+                } as any as Record<string, string>
+            },
+            base: 'http://example.com',
+            expected: `http://example.com/products?symbol=Symbol()&fn=${String(
+                async () => ''
+            )}&obj=${String({})}&big=12345678901234567891234567890123456789&b&c=0&d=0&e=1`,
+            description:
+                'should ignore null, undefined, and NaN query parameters'
+        },
+        {
+            input: { path: '/products', queryArray: { tag: [] } },
+            base: 'http://example.com',
+            expected: 'http://example.com/products',
+            description: 'should handle empty queryArray'
+        },
+        {
+            input: {
+                path: '/products?id=path&a',
+                query: { id: 'query' }
+            },
+            base: 'http://example.com',
+            expected: 'http://example.com/products?id=query&a',
+            description: 'query value should override query parameter in path'
+        },
+        {
+            input: {
+                path: '/products?id=path&a',
+                query: { id: 'query' },
+                queryArray: { id: ['queryArray'] }
+            },
+            base: 'http://example.com',
+            expected: 'http://example.com/products?id=queryArray&a',
+            description:
+                'queryArray value should override query and path parameters'
+        },
+        {
+            input: {
+                path: '/products?id=path&a',
+                queryArray: { id: ['queryArray'] }
+            },
+            base: 'http://example.com',
+            expected: 'http://example.com/products?id=queryArray&a',
+            description:
+                'queryArray value should override query parameter in path'
+        },
+        {
+            input: {
+                path: '?a&a=&a&a',
+                query: { a: '' },
+                queryArray: { a: ['', ''] }
+            },
+            base: 'http://example.com',
+            expected: 'http://example.com?a&a',
+            description:
+                'should handle empty strings and duplicate query parameters correctly'
+        },
+        {
+            input: { path: '/products?id=123', url: '/products?id=456' },
+            base: 'http://example.com',
+            expected: 'http://example.com/products?id=123',
+            description:
+                'path should take priority over url when both are present'
+        },
+        {
+            input: { url: '/products?id=456' },
+            base: 'http://example.com',
+            expected: 'http://example.com/products?id=456',
+            description: 'url should be used when path is not present'
+        },
+        {
+            input: {},
+            base: 'http://example.com',
+            expected: 'http://example.com/',
+            description: 'empty input object should default to base URL'
+        }
+    ];
+
+    testCases.forEach(({ input, base, expected, description }) => {
+        test(description, () => {
+            const result = parseLocation(input, new URL(base));
+            expect(result).toEqURL(expected);
+        });
+    });
+});
+
+describe('normalizeURL more', () => {
+    describe.for(
+        // biome-ignore format:
+        Object.entries({
+            'https://www.esmx.dev': {
+                '/': 'https://www.esmx.dev/',
+                '/new': 'https://www.esmx.dev/new',
+                '/new/': 'https://www.esmx.dev/new/',
+                '/new/100': 'https://www.esmx.dev/new/100',
+                '/new/100/': 'https://www.esmx.dev/new/100/',
+                '..': 'https://www.esmx.dev/',
+                '../': 'https://www.esmx.dev/',
+                '../new': 'https://www.esmx.dev/new',
+                '../new/': 'https://www.esmx.dev/new/',
+                '../new/100': 'https://www.esmx.dev/new/100',
+                '../new/100/': 'https://www.esmx.dev/new/100/',
+                '': 'https://www.esmx.dev/',
+                'new': 'https://www.esmx.dev/new',
+                'new/': 'https://www.esmx.dev/new/',
+                'new/100': 'https://www.esmx.dev/new/100',
+                'new/100/': 'https://www.esmx.dev/new/100/',
+                '.': 'https://www.esmx.dev/',
+                './': 'https://www.esmx.dev/',
+                './new': 'https://www.esmx.dev/new',
+                './new/': 'https://www.esmx.dev/new/',
+                './new/100': 'https://www.esmx.dev/new/100',
+                './new/100/': 'https://www.esmx.dev/new/100/',
+                '.a': 'https://www.esmx.dev/.a',
+                '..a': 'https://www.esmx.dev/..a',
+                '.a/': 'https://www.esmx.dev/.a/',
+                '..a/': 'https://www.esmx.dev/..a/',
+                'new/../.': 'https://www.esmx.dev/',
+            },
+            'https://www.esmx.dev/': {
+                '/': 'https://www.esmx.dev/',
+                '/new': 'https://www.esmx.dev/new',
+                '/new/': 'https://www.esmx.dev/new/',
+                '/new/100': 'https://www.esmx.dev/new/100',
+                '/new/100/': 'https://www.esmx.dev/new/100/',
+                '..': 'https://www.esmx.dev/',
+                '../': 'https://www.esmx.dev/',
+                '../new': 'https://www.esmx.dev/new',
+                '../new/': 'https://www.esmx.dev/new/',
+                '../new/100': 'https://www.esmx.dev/new/100',
+                '../new/100/': 'https://www.esmx.dev/new/100/',
+                '': 'https://www.esmx.dev/',
+                'new': 'https://www.esmx.dev/new',
+                'new/': 'https://www.esmx.dev/new/',
+                'new/100': 'https://www.esmx.dev/new/100',
+                'new/100/': 'https://www.esmx.dev/new/100/',
+                '.': 'https://www.esmx.dev/',
+                './': 'https://www.esmx.dev/',
+                './new': 'https://www.esmx.dev/new',
+                './new/': 'https://www.esmx.dev/new/',
+                './new/100': 'https://www.esmx.dev/new/100',
+                './new/100/': 'https://www.esmx.dev/new/100/',
+                '.a': 'https://www.esmx.dev/.a',
+                '..a': 'https://www.esmx.dev/..a',
+                '.a/': 'https://www.esmx.dev/.a/',
+                '..a/': 'https://www.esmx.dev/..a/',
+                'new/../.': 'https://www.esmx.dev/',
+            },
+            'https://www.esmx.dev/a/b/c': {
+                '/': 'https://www.esmx.dev/a/b/',
+                '/new': 'https://www.esmx.dev/a/b/new',
+                '/new/': 'https://www.esmx.dev/a/b/new/',
+                '/new/100': 'https://www.esmx.dev/a/b/new/100',
+                '/new/100/': 'https://www.esmx.dev/a/b/new/100/',
+                '..': 'https://www.esmx.dev/a/',
+                '../': 'https://www.esmx.dev/a/',
+                '../new': 'https://www.esmx.dev/a/new',
+                '../new/': 'https://www.esmx.dev/a/new/',
+                '../new/100': 'https://www.esmx.dev/a/new/100',
+                '../new/100/': 'https://www.esmx.dev/a/new/100/',
+                '': 'https://www.esmx.dev/a/b/c',
+                'new': 'https://www.esmx.dev/a/b/new',
+                'new/': 'https://www.esmx.dev/a/b/new/',
+                'new/100': 'https://www.esmx.dev/a/b/new/100',
+                'new/100/': 'https://www.esmx.dev/a/b/new/100/',
+                '.': 'https://www.esmx.dev/a/b/',
+                './': 'https://www.esmx.dev/a/b/',
+                './new': 'https://www.esmx.dev/a/b/new',
+                './new/': 'https://www.esmx.dev/a/b/new/',
+                './new/100': 'https://www.esmx.dev/a/b/new/100',
+                './new/100/': 'https://www.esmx.dev/a/b/new/100/',
+                '.a': 'https://www.esmx.dev/a/b/.a',
+                '..a': 'https://www.esmx.dev/a/b/..a',
+                '.a/': 'https://www.esmx.dev/a/b/.a/',
+                '..a/': 'https://www.esmx.dev/a/b/..a/',
+                'new/../.': 'https://www.esmx.dev/a/b/',
+                'new/.././a/../../x/': 'https://www.esmx.dev/a/x/',
+            },
+            'https://www.esmx.dev/a/b/c/': {
+                '/': 'https://www.esmx.dev/a/b/c/',
+                '/new': 'https://www.esmx.dev/a/b/c/new',
+                '/new/': 'https://www.esmx.dev/a/b/c/new/',
+                '/new/100': 'https://www.esmx.dev/a/b/c/new/100',
+                '/new/100/': 'https://www.esmx.dev/a/b/c/new/100/',
+                '..': 'https://www.esmx.dev/a/b/',
+                '../': 'https://www.esmx.dev/a/b/',
+                '../new': 'https://www.esmx.dev/a/b/new',
+                '../new/': 'https://www.esmx.dev/a/b/new/',
+                '../new/100': 'https://www.esmx.dev/a/b/new/100',
+                '../new/100/': 'https://www.esmx.dev/a/b/new/100/',
+                '': 'https://www.esmx.dev/a/b/c/',
+                'new': 'https://www.esmx.dev/a/b/c/new',
+                'new/': 'https://www.esmx.dev/a/b/c/new/',
+                'new/100': 'https://www.esmx.dev/a/b/c/new/100',
+                'new/100/': 'https://www.esmx.dev/a/b/c/new/100/',
+                '.': 'https://www.esmx.dev/a/b/c/',
+                './': 'https://www.esmx.dev/a/b/c/',
+                './new': 'https://www.esmx.dev/a/b/c/new',
+                './new/': 'https://www.esmx.dev/a/b/c/new/',
+                './new/100': 'https://www.esmx.dev/a/b/c/new/100',
+                './new/100/': 'https://www.esmx.dev/a/b/c/new/100/',
+                '.a': 'https://www.esmx.dev/a/b/c/.a',
+                '..a': 'https://www.esmx.dev/a/b/c/..a',
+                '.a/': 'https://www.esmx.dev/a/b/c/.a/',
+                '..a/': 'https://www.esmx.dev/a/b/c/..a/',
+                'new/.././': 'https://www.esmx.dev/a/b/c/',
+                'new/.././a/../../x/': 'https://www.esmx.dev/a/b/x/',
+            }
+        })
+    )(`base: $0`, ([base, cases]) => {
+        test.each(Object.entries(cases))(`input: $0`, (input, expected) => {
+            const url = normalizeURL(input, new URL(base));
+            expect(url).toEqURL(expected);
+
+            const pathSuffix = '?a&b=1&c=2&a=&a=4&base=10#hash';
+            const urlWithSuffix = normalizeURL(
+                input + pathSuffix,
+                new URL(base)
+            );
+            expect(urlWithSuffix).toEqURL(expected + pathSuffix);
+
+            const urlWithBaseSuffix = normalizeURL(
+                input + pathSuffix,
+                new URL(base + '?base=base#base')
+            );
+            expect(urlWithBaseSuffix).toEqURL(expected + pathSuffix);
+        });
+    });
+});