@esmx/router 3.0.0-rc.103

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,68 @@
+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;
+                }
+                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 || {},
+            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,101 @@
+import type { Router } from './router';
+import type { RouterMicroAppCallback, RouterMicroAppOptions } from './types';
+import { isBrowser, isPlainObject } from './util';
+
+/**
+ * Resolves the root container element.
+ * Supports a DOM selector string or a direct HTMLElement.
+ *
+ * @param rootConfig - The root container configuration, can be a selector string or an HTMLElement.
+ * @returns The resolved HTMLElement.
+ */
+export function resolveRootElement(
+    rootConfig?: string | HTMLElement
+): HTMLElement {
+    let el: HTMLElement | null = null;
+    // Direct HTMLElement provided
+    if (rootConfig instanceof HTMLElement) {
+        el = rootConfig;
+    }
+    if (typeof rootConfig === 'string' && rootConfig) {
+        try {
+            el = document.querySelector(rootConfig);
+        } catch (error) {
+            console.warn(`Failed to resolve root element: ${rootConfig}`);
+        }
+    }
+    if (el === null) {
+        el = document.createElement('div');
+    }
+    return el;
+}
+
+export class MicroApp {
+    public app: RouterMicroAppOptions | null = null;
+    public root: HTMLElement | null = null;
+    private _factory: RouterMicroAppCallback | null = null;
+
+    public _update(router: Router, force = false) {
+        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 = resolveRootElement(router.root);
+                const { rootStyle } = router.parsedOptions;
+                if (root && isPlainObject(rootStyle)) {
+                    Object.assign(root.style, router.parsedOptions.rootStyle);
+                }
+            }
+            if (root) {
+                app.mount(root);
+                if (root.parentNode === null) {
+                    document.body.appendChild(root);
+                }
+                this.root = root;
+            }
+            if (oldApp) {
+                oldApp.unmount();
+            }
+        }
+        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.app = null;
+        this.root?.remove();
+        this.root = null;
+        this._factory = null;
+    }
+}

package/src/navigation.ts

@@ -0,0 +1,202 @@
+import { PAGE_ID } from './increment-id';
+import type { RouterParsedOptions, RouteState } from './types';
+import { RouterMode } from './types';
+
+type NavigationSubscribe = (url: string, state: RouteState) => void;
+type NavigationGoResult = null | {
+    type: 'success';
+    url: string;
+    state: RouteState;
+};
+
+const PAGE_ID_KEY = '__pageId__';
+
+export class Navigation {
+    public readonly options: RouterParsedOptions;
+    private readonly _history: History | MemoryHistory;
+    private readonly _unSubscribePopState: () => void;
+    private _promiseResolve:
+        | ((url?: string | null, state?: RouteState) => void)
+        | null = null;
+
+    public constructor(
+        options: RouterParsedOptions,
+        onUpdated?: NavigationSubscribe
+    ) {
+        const history: History =
+            options.mode === RouterMode.history
+                ? window.history
+                : new MemoryHistory();
+        const onPopStateChange: NavigationSubscribe = (url, state) => {
+            const dispatchEvent = this._promiseResolve || onUpdated;
+            dispatchEvent?.(url, state);
+        };
+        const subscribePopState =
+            history instanceof MemoryHistory
+                ? history.onPopState(onPopStateChange)
+                : subscribeHtmlHistory(onPopStateChange);
+        this.options = options;
+        this._history = history;
+        this._unSubscribePopState = subscribePopState;
+    }
+    public get length(): number {
+        return this._history.length;
+    }
+
+    private _push(
+        history: History,
+        data: any,
+        url?: string | URL | null
+    ): RouteState {
+        const state = {
+            ...(data || {}),
+            [PAGE_ID_KEY]: PAGE_ID.next()
+        };
+        history.pushState(state, '', url);
+        return state;
+    }
+
+    private _replace(
+        history: History,
+        data: any,
+        url?: string | URL | null
+    ): RouteState {
+        const oldId = history.state?.[PAGE_ID_KEY];
+        const state = {
+            ...(data || {}),
+            [PAGE_ID_KEY]: typeof oldId === 'number' ? oldId : PAGE_ID.next()
+        };
+        history.replaceState(state, '', url);
+        return state;
+    }
+
+    public push(data: any, url?: string | URL | null): RouteState {
+        return this._push(this._history, data, url);
+    }
+
+    public replace(data: any, url?: string | URL | null): RouteState {
+        return this._replace(this._history, data, url);
+    }
+
+    public pushHistoryState(data: any, url?: string | URL | null) {
+        this._push(history, data, url);
+    }
+
+    public replaceHistoryState(data: any, url?: string | URL | null) {
+        this._replace(history, data, url);
+    }
+
+    public backHistoryState() {
+        return this._go(history, -1);
+    }
+
+    private _go(history: History, index: number): Promise<NavigationGoResult> {
+        if (this._promiseResolve) {
+            return Promise.resolve(null);
+        }
+        return new Promise<NavigationGoResult>((resolve) => {
+            this._promiseResolve = (url, state) => {
+                this._promiseResolve = null;
+                if (typeof url !== 'string') return resolve(null);
+                resolve({ type: 'success', url, state: state || {} });
+            };
+            setTimeout(this._promiseResolve, 80);
+            history.go(index);
+        });
+    }
+    public go(delta?: number): Promise<NavigationGoResult> {
+        return this._go(this._history, delta || 0);
+    }
+    public forward(): Promise<NavigationGoResult> {
+        return this.go(1);
+    }
+    public back(): Promise<NavigationGoResult> {
+        return this.go(-1);
+    }
+
+    public destroy() {
+        this._promiseResolve?.();
+        this._unSubscribePopState();
+    }
+}
+
+export class MemoryHistory implements History {
+    private _entries: Array<{ state: any; url: string }> = [];
+    private _index = -1;
+    private get _curEntry() {
+        const idx = this._index;
+        if (idx < 0 || idx >= this.length) return null;
+        return this._entries[idx];
+    }
+    private readonly _popStateCbs = new Set<NavigationSubscribe>();
+    public scrollRestoration: ScrollRestoration = 'auto';
+    // Return null when no current entry to align with browser history.state behavior
+    // Browser history.state can be null when no state was provided
+    public get state() {
+        return this._curEntry?.state ?? null;
+    }
+    public get url() {
+        return this._curEntry?.url ?? '';
+    }
+
+    constructor() {
+        this.pushState(null, '', '/');
+    }
+    public get length() {
+        return this._entries.length;
+    }
+
+    public pushState(
+        data: any,
+        unused: string,
+        url?: string | URL | null
+    ): void {
+        // Remove all entries after the current position
+        this._entries.splice(this._index + 1);
+        this._entries.push({ state: data, url: url?.toString() ?? this.url });
+        this._index = this._entries.length - 1;
+    }
+
+    public replaceState(
+        data: any,
+        unused: string,
+        url?: string | URL | null
+    ): void {
+        const curEntry = this._curEntry;
+        if (!curEntry) return;
+        curEntry.state = { ...data };
+        if (url) curEntry.url = url.toString();
+    }
+
+    public back(): void {
+        this.go(-1);
+    }
+    public forward(): void {
+        this.go(1);
+    }
+    public go(delta?: number): void {
+        if (!delta) return;
+        const newIdx = this._index + delta;
+        if (newIdx < 0 || newIdx >= this.length) return;
+        this._index = newIdx;
+        const entry = this._curEntry!;
+        // Simulate the async popstate event of html history as closely as possible
+        setTimeout(() => {
+            this._popStateCbs.forEach((cb) => cb(entry.url, entry.state));
+        });
+    }
+
+    public onPopState(cb: NavigationSubscribe) {
+        if (typeof cb !== 'function') return () => {};
+        this._popStateCbs.add(cb);
+        return () => this._popStateCbs.delete(cb);
+    }
+}
+
+function subscribeHtmlHistory(cb: NavigationSubscribe) {
+    // Use history.state || {} to handle null state from browser history
+    // Browser history.state can be null, but we normalize it to empty object
+    const wrapper = () => cb(location.href, history.state || {});
+    window.addEventListener('popstate', wrapper);
+    return () => window.removeEventListener('popstate', wrapper);
+}

package/src/options.ts

@@ -0,0 +1,135 @@
+import { createMatcher, createRouteMatches } from './matcher';
+import type { Router } from './router';
+import type { Route, RouterOptions, RouterParsedOptions } from './types';
+import { RouterMode } from './types';
+import { isBrowser } from './util';
+
+/**
+ * Gets the base URL object for the router.
+ * @param options - Router options.
+ * @returns The processed URL object.
+ */
+function getBaseUrl(options: RouterOptions): URL {
+    // Determine the URL source
+    let sourceUrl: string | URL;
+
+    if (options.base) {
+        sourceUrl = options.base;
+    } else if (isBrowser) {
+        sourceUrl = location.origin;
+    } else if (options.req) {
+        // Server-side: try to get it from the req object
+        const { req } = options;
+        const protocol =
+            req.headers['x-forwarded-proto'] ||
+            req.headers['x-forwarded-protocol'] ||
+            (req.socket && 'encrypted' in req.socket && req.socket.encrypted
+                ? 'https'
+                : 'http');
+        const host =
+            req.headers['x-forwarded-host'] ||
+            req.headers.host ||
+            req.headers['x-real-ip'] ||
+            'localhost';
+        const port = req.headers['x-forwarded-port'];
+        const path = req.url || '';
+
+        sourceUrl = `${protocol}://${host}${port ? `:${port}` : ''}${path}`;
+    } else {
+        sourceUrl = 'https://esmx.dev/';
+    }
+
+    // Parse the URL, falling back to a default on failure.
+    // Use a try-catch block with the standard URL constructor for robustness.
+    let base: URL;
+    try {
+        base = new URL('.', sourceUrl);
+    } catch (e) {
+        console.warn(
+            `Failed to parse base URL '${sourceUrl}', using default: https://esmx.dev/`
+        );
+        base = new URL('https://esmx.dev/');
+    }
+
+    // Clean up and return
+    base.search = base.hash = '';
+    return base;
+}
+
+export function parsedOptions(
+    options: RouterOptions = {}
+): RouterParsedOptions {
+    const base = getBaseUrl(options);
+    const routes = options.routes ?? [];
+    const compiledRoutes = createRouteMatches(routes);
+    return Object.freeze<RouterParsedOptions>({
+        rootStyle: options.rootStyle || false,
+        root: options.root || '',
+        context: options.context || {},
+        data: options.data || {},
+        req: options.req || null,
+        res: options.res || null,
+        layer: options.layer || false,
+        zIndex: options.zIndex || 10000,
+        base,
+        mode: isBrowser
+            ? (options.mode ?? RouterMode.history)
+            : RouterMode.memory,
+        routes,
+        apps:
+            typeof options.apps === 'function'
+                ? options.apps
+                : Object.assign({}, options.apps),
+        compiledRoutes,
+        matcher: createMatcher(routes, compiledRoutes),
+        normalizeURL: options.normalizeURL ?? ((url) => url),
+        fallback: options.fallback ?? fallback,
+        nextTick: options.nextTick ?? (() => {}),
+        handleBackBoundary: options.handleBackBoundary ?? (() => {}),
+        handleLayerClose: options.handleLayerClose ?? (() => {})
+    });
+}
+
+export function fallback(to: Route, from: Route | null, router: Router) {
+    const href = to.url.href;
+
+    // Server-side environment: handle application-level redirects and status codes
+    if (!isBrowser && router?.res) {
+        // Determine status code: prioritize route-specified code, default to 302 temporary redirect
+        let statusCode = 302;
+
+        // Validate redirect status code (3xx series)
+        const validRedirectCodes = [300, 301, 302, 303, 304, 307, 308];
+        if (to.statusCode && validRedirectCodes.includes(to.statusCode)) {
+            statusCode = to.statusCode;
+        } else if (to.statusCode) {
+            console.warn(
+                `Invalid redirect status code ${to.statusCode}, using default 302`
+            );
+        }
+
+        // Set redirect response
+        router.res.statusCode = statusCode;
+        router.res.setHeader('Location', href);
+        router.res.end();
+        return;
+    }
+
+    // Client-side environment: handle browser navigation
+    if (isBrowser) {
+        if (to.isPush) {
+            try {
+                const newWindow = window.open(href);
+                if (!newWindow) {
+                    location.href = href;
+                } else {
+                    newWindow.opener = null; // Sever the relationship between the new window and the current one
+                }
+                return newWindow;
+            } catch {}
+        }
+        location.href = href;
+    }
+
+    // Do nothing in a server environment without a res context
+}