@esmx/router 3.0.0-rc.12 → 3.0.0-rc.122

package/package.json

@@ -1,66 +1,93 @@
 {
-    "name": "@esmx/router",
-    "template": "library",
-    "scripts": {
-        "lint:js": "biome check --write --no-errors-on-unmatched",
-        "lint:css": "stylelint '**/*.{css,vue}' --fix --aei",
-        "lint:type": "tsc --noEmit",
-        "test": "vitest run --pass-with-no-tests",
-        "coverage": "vitest run --coverage --pass-with-no-tests",
-        "build": "unbuild"
+  "name": "@esmx/router",
+  "description": "Framework-agnostic universal router for browser and Node.js SSR, with micro-frontend and layer navigation support",
+  "keywords": [
+    "router",
+    "routing",
+    "ssr",
+    "micro-frontend",
+    "typescript",
+    "universal",
+    "navigation",
+    "esmx",
+    "esm",
+    "spa",
+    "framework",
+    "frontend"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/esmnext/esmx.git",
+    "directory": "packages/router"
+  },
+  "homepage": "https://github.com/esmnext/esmx",
+  "bugs": {
+    "url": "https://github.com/esmnext/esmx/issues"
+  },
+  "license": "MIT",
+  "template": "library",
+  "contributors": [
+    {
+      "name": "lzxb",
+      "url": "https://github.com/lzxb"
     },
-    "contributors": [
-        {
-            "name": "lzxb",
-            "url": "https://github.com/lzxb"
-        },
-        {
-            "name": "RockShi1994",
-            "url": "https://github.com/RockShi1994"
-        },
-        {
-            "name": "jerrychan7",
-            "url": "https://github.com/jerrychan7"
-        },
-        {
-            "name": "wesloong",
-            "url": "https://github.com/wesloong"
-        }
-    ],
-    "dependencies": {
-        "path-to-regexp": "^6.2.2",
-        "url-parse": "^1.5.10"
+    {
+      "name": "RockShi1994",
+      "url": "https://github.com/RockShi1994"
     },
-    "devDependencies": {
-        "@biomejs/biome": "1.9.4",
-        "@esmx/lint": "3.0.0-rc.12",
-        "@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",
-        "typescript": "5.8.2",
-        "unbuild": "2.0.0",
-        "vitest": "3.0.8"
+    {
+      "name": "jerrychan7",
+      "url": "https://github.com/jerrychan7"
     },
-    "version": "3.0.0-rc.12",
-    "type": "module",
-    "private": false,
-    "exports": {
-        ".": {
-            "import": "./dist/index.mjs",
-            "types": "./dist/index.d.ts"
-        }
-    },
-    "module": "dist/index.mjs",
-    "types": "./dist/index.d.ts",
-    "files": [
-        "lib",
-        "src",
-        "dist",
-        "*.mjs",
-        "template",
-        "public"
-    ],
-    "gitHead": "7d2c2fc4fe2cc98ebdbc12560f19637ca04398e5"
-}
+    {
+      "name": "wesloong",
+      "url": "https://github.com/wesloong"
+    }
+  ],
+  "dependencies": {
+    "path-to-regexp": "^6.2.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.7",
+    "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "3.2.6",
+    "happy-dom": "^20.0.10",
+    "typescript": "5.9.3",
+    "unbuild": "3.6.1",
+    "vitest": "3.2.6"
+  },
+  "version": "3.0.0-rc.122",
+  "type": "module",
+  "private": false,
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "module": "dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "lib",
+    "src",
+    "dist",
+    "*.mjs",
+    "template",
+    "public"
+  ],
+  "gitHead": "3e692857ccb65e7d1fdf689e30eb5d935e8bda77",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "lint:js": "biome check --write --no-errors-on-unmatched",
+    "lint:css": "pnpm run lint:js",
+    "lint:type": "tsc --noEmit",
+    "test": "vitest run --pass-with-no-tests",
+    "coverage": "vitest run --coverage --pass-with-no-tests",
+    "build": "unbuild"
+  }
+}

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.ts

@@ -1,3 +1,67 @@
-export { createRouter } from './router';
-export * from './types';
-export * from './utils';
+// Error types
+export {
+    RouteError,
+    RouteNavigationAbortedError,
+    RouteSelfRedirectionError,
+    RouteTaskCancelledError,
+    RouteTaskExecutionError
+} from './error';
+export { Route } from './route';
+export { Router } from './router';
+export {
+    type RouteConfig,
+    // Hook function types
+    type RouteConfirmHook,
+    type RouteConfirmHookResult,
+    type RouteHandleHook,
+    type RouteHandleResult,
+    // Router Layer types
+    type RouteLayerOptions,
+    type RouteLayerResult,
+    // Route location and config types
+    type RouteLocation,
+    type RouteLocationInput,
+    type RouteMatcher,
+    type RouteMatchResult,
+    type RouteMatchType,
+    // Basic data types
+    type RouteMeta,
+    type RouteNotifyHook,
+    type RouteOptions,
+    type RouteParsedConfig,
+    type RouterLayerOptions,
+    type RouterLinkAttributes,
+    type RouterLinkProps,
+    type RouterLinkResolved,
+    // RouterLink types
+    type RouterLinkType,
+    // Router MicroApp types
+    type RouterMicroApp,
+    type RouterMicroAppCallback,
+    type RouterMicroAppOptions,
+    // Core enums
+    RouterMode,
+    // Router core types
+    type RouterOptions,
+    type RouterParsedOptions,
+    type RouteState,
+    RouteType,
+    type RouteVerifyHook
+} from './types';
+
+// =================== Re-exporting deprecated types ===================
+
+import type { Router } from './router';
+import type { Route, RouteLocation, RouteLocationInput } from './types';
+
+/** @deprecated Use `Router` directly instead of `RouterInstance`. */
+export type RouterInstance = Router;
+
+/** @deprecated Use `RouteLocationInput` directly instead of `RouterRawLocation`. */
+export type RouterRawLocation = RouteLocationInput;
+
+/** @deprecated Use `RouteLocation` directly instead of `RouterLocation`. */
+export type RouterLocation = RouteLocation;
+
+/** @deprecated Use `Route` directly instead of `RouteRecord`. */
+export type RouteRecord = Route;

package/src/location.ts

@@ -0,0 +1,124 @@
+import type { RouteLocation, RouteLocationInput } from './types';
+import { isNotNullish } from './util';
+
+/**
+ * Normalizes a URL input into a URL object.
+ * @param url - The URL or string to normalize.
+ * @param base - The base URL to resolve against if the input is relative.
+ * @returns A URL object.
+ */
+export function normalizeURL(url: string | URL, base: URL): URL {
+    if (url instanceof URL) {
+        return url;
+    }
+
+    // Handle protocol-relative URLs (e.g., //example.com)
+    if (url.startsWith('//')) {
+        // Use the current base URL's protocol for security and consistency
+        const protocol = base.protocol;
+        return new URL(`${protocol}${url}`);
+    }
+
+    // Handle root-relative paths
+    if (url.startsWith('/')) {
+        const newBase = new URL('.', base);
+        const parsed = new URL(url, newBase);
+        // This ensures that the path is resolved relative to the base's path directory.
+        parsed.pathname = newBase.pathname.slice(0, -1) + parsed.pathname;
+        return parsed;
+    }
+
+    try {
+        // Try to parse as an absolute URL.
+        // This is the WHATWG standard approach (new URL()) and works consistently across all modern browsers and Node.js.
+        // We use a try-catch block because the standard URL constructor throws an error for invalid URLs.
+        //
+        // NOTE: While `URL.parse()` might be observed in Chromium-based browsers (e.g., Chrome, Edge),
+        // it is a non-standard, legacy feature implemented by the V8 engine for Node.js compatibility.
+        // It is not part of the WHATWG URL Standard and is not supported by other browsers like Firefox or Safari.
+        // Therefore, relying on it would compromise cross-browser compatibility.
+        return new URL(url);
+    } catch (e) {
+        // Otherwise, parse as a relative URL
+        return new URL(url, base);
+    }
+}
+
+/**
+ * Parses a RouteLocationInput object into a full URL.
+ * @param toInput - The route location input.
+ * @param baseURL - The base URL to resolve against.
+ * @returns The parsed URL object.
+ */
+export function parseLocation(toInput: RouteLocationInput, baseURL: URL): URL {
+    if (typeof toInput === 'string') {
+        return normalizeURL(toInput, baseURL);
+    }
+    const url = normalizeURL(toInput.path ?? toInput.url ?? '', baseURL);
+    const searchParams = url.searchParams;
+
+    // Priority: queryArray > query > query in path
+    const mergedQuery: Record<string, string | string[]> = {};
+
+    // First, add query values
+    if (toInput.query) {
+        Object.entries(toInput.query).forEach(([key, value]) => {
+            if (typeof value !== 'undefined') {
+                mergedQuery[key] = value;
+            }
+        });
+    }
+
+    // Then, add queryArray values (higher priority)
+    if (toInput.queryArray) {
+        Object.entries(toInput.queryArray).forEach(([key, value]) => {
+            if (typeof value !== 'undefined') {
+                mergedQuery[key] = value;
+            }
+        });
+    }
+
+    Object.entries(mergedQuery).forEach(([key, value]) => {
+        searchParams.delete(key); // Clear previous params with the same name
+        value = Array.isArray(value) ? value : [value];
+        value
+            .filter((v) => isNotNullish(v) && !Number.isNaN(v))
+            .forEach((v) => {
+                searchParams.append(key, String(v));
+            });
+    });
+
+    // Set the hash (URL fragment identifier)
+    if (toInput.hash) {
+        url.hash = toInput.hash;
+    }
+
+    return url;
+}
+
+/**
+ * Resolves RouteLocationInput with fallback from previous route
+ * @param toInput - The route location input
+ * @param from - The previous route URL (optional)
+ * @returns Resolved RouteLocation object
+ */
+export function resolveRouteLocationInput(
+    toInput: RouteLocationInput = '/',
+    from: URL | null = null
+): RouteLocation {
+    if (typeof toInput === 'string') {
+        return { path: toInput };
+    }
+
+    if (
+        toInput &&
+        typeof toInput === 'object' &&
+        typeof toInput.path !== 'string' &&
+        typeof toInput.url !== 'string' &&
+        from !== null
+    ) {
+        return { ...toInput, url: from.href };
+    }
+
+    return toInput;
+}

package/src/matcher.ts

@@ -0,0 +1,71 @@
+import { compile, match } from 'path-to-regexp';
+import type { RouteConfig, RouteMatcher, RouteParsedConfig } from './types';
+
+export function createMatcher(
+    routes: RouteConfig[],
+    compiledRoutes = createRouteMatches(routes)
+): RouteMatcher {
+    return (
+        toURL: URL,
+        baseURL: URL,
+        cb?: (item: RouteParsedConfig) => boolean
+    ) => {
+        const matchPath = toURL.pathname.substring(baseURL.pathname.length - 1);
+        const matches: RouteParsedConfig[] = [];
+        const params: Record<string, string | string[]> = {};
+        const collectMatchingRoutes = (
+            routes: RouteParsedConfig[]
+        ): boolean => {
+            for (const item of routes) {
+                if (cb && !cb(item)) {
+                    continue;
+                }
+                // Depth-first traversal
+                if (
+                    item.children.length &&
+                    collectMatchingRoutes(item.children)
+                ) {
+                    matches.unshift(item);
+                    return true;
+                }
+                // At this point, children exist but none matched — if requireIndex is true, skip self-match
+                if (item.requireIndex && item.children.length) continue;
+                const result = item.match(matchPath);
+                if (result) {
+                    matches.unshift(item);
+                    if (typeof result === 'object') {
+                        Object.assign(params, result.params);
+                    }
+                    return true;
+                }
+            }
+            return false;
+        };
+        collectMatchingRoutes(compiledRoutes);
+        return { matches: Object.freeze(matches), params };
+    };
+}
+
+export function createRouteMatches(
+    routes: RouteConfig[],
+    base = ''
+): RouteParsedConfig[] {
+    return routes.map((route: RouteConfig): RouteParsedConfig => {
+        const compilePath = joinPathname(route.path, base);
+        return {
+            ...route,
+            compilePath,
+            match: match(compilePath),
+            compile: compile(compilePath),
+            meta: route.meta || {},
+            requireIndex: route.requireIndex ?? false,
+            children: Array.isArray(route.children)
+                ? createRouteMatches(route.children, compilePath)
+                : []
+        };
+    });
+}
+
+export function joinPathname(pathname: string, base = '') {
+    return '/' + `${base}/${pathname}`.split('/').filter(Boolean).join('/');
+}

package/src/micro-app.ts

@@ -0,0 +1,153 @@
+import type { Router } from './router';
+import type { RouterMicroAppCallback, RouterMicroAppOptions } from './types';
+import { isBrowser, isPlainObject } from './util';
+
+/**
+ * Gets the root container element by ID.
+ * If not found, creates a new div with the given ID and appends it to document.body.
+ *
+ * @param appId - The application container ID.
+ * @returns The resolved HTMLElement.
+ */
+export function getRootElement(appId: string): HTMLElement {
+    const el = document.getElementById(appId);
+    if (el) {
+        return el;
+    }
+    const newEl = document.createElement('div');
+    newEl.id = appId;
+    document.body.appendChild(newEl);
+    return newEl;
+}
+
+export class MicroApp {
+    public app: RouterMicroAppOptions | null = null;
+    public root: HTMLElement | null = null;
+    private _factory: RouterMicroAppCallback | null = null;
+    private destroyed = false;
+
+    public _update(router: Router, force = false) {
+        if (this.destroyed) {
+            throw new Error('MicroApp has been destroyed');
+        }
+        const factory = this._getNextFactory(router);
+        if (!force && factory === this._factory) {
+            return;
+        }
+        const oldApp = this.app;
+        // Create the new application
+        const app = factory ? factory(router) : null;
+        if (isBrowser && app) {
+            let root: HTMLElement | null = this.root;
+            if (root === null) {
+                root = getRootElement(router.appId);
+                const { rootStyle } = router.parsedOptions;
+                if (root && isPlainObject(rootStyle)) {
+                    Object.assign(root.style, router.parsedOptions.rootStyle);
+                }
+                this.root = root;
+            }
+            if (root) {
+                const isHydration = root.hasAttribute('data-ssr');
+                if (isHydration) {
+                    const appRoot = root.firstElementChild as HTMLElement;
+                    if (appRoot) {
+                        if (app.hydration) {
+                            app.hydration(appRoot);
+                        } else {
+                            throw new Error(
+                                'SSR content detected but hydration function not provided'
+                            );
+                        }
+                    } else {
+                        // No child elements (e.g., Vue 2 comment nodes), fallback to mount
+                        const el = document.createElement('div');
+                        root.appendChild(el);
+                        try {
+                            app.mount(el);
+                        } catch (e) {
+                            el.remove();
+                            throw e;
+                        }
+                    }
+                    // Remove data-ssr attribute after hydration
+                    root.removeAttribute('data-ssr');
+                } else {
+                    // Capture all existing children before inserting the new container.
+                    // Old app may have created multiple sibling nodes during its lifecycle.
+                    const oldChildren = Array.from(root.childNodes);
+                    const el = document.createElement('div');
+                    root.appendChild(el);
+                    try {
+                        app.mount(el);
+                    } catch (e) {
+                        el.remove();
+                        throw e;
+                    }
+                    if (oldApp) {
+                        try {
+                            oldApp.unmount();
+                        } catch (e) {
+                            // eslint-disable-next-line no-console
+                            console.error(
+                                '[@esmx/router] MicroApp unmount failed during route transition. Check the framework unmount hook returned by your render function (Vue: app.unmount, React: root.unmount, etc.).',
+                                e
+                            );
+                        }
+                    }
+                    // Remove old children that are still attached to the DOM.
+                    // Some frameworks may have already removed their own nodes during unmount.
+                    oldChildren.forEach((child) => {
+                        if (child.parentNode) {
+                            child.remove();
+                        }
+                    });
+                }
+            }
+        }
+        this.app = app;
+        this._factory = factory;
+    }
+
+    private _getNextFactory({
+        route,
+        options
+    }: Router): RouterMicroAppCallback | null {
+        if (!route.matched || route.matched.length === 0) {
+            return null;
+        }
+        const name = route.matched[0].app;
+        if (
+            typeof name === 'string' &&
+            options.apps &&
+            typeof options.apps === 'object'
+        ) {
+            return options.apps[name] || null;
+        }
+        if (typeof name === 'function') {
+            return name;
+        }
+        if (typeof options.apps === 'function') {
+            return options.apps;
+        }
+        return null;
+    }
+
+    public destroy() {
+        this.app?.unmount();
+        this._clearRoot();
+        this.app = null;
+        this.root = null;
+        this._factory = null;
+        this.destroyed = true;
+    }
+
+    private _clearRoot(): void {
+        if (!this.root) {
+            return;
+        }
+        Array.from(this.root.childNodes).forEach((child) => {
+            child.remove();
+        });
+    }
+}