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

package/dist/route-transition.d.ts

@@ -0,0 +1,53 @@
+import { Route } from './route';
+import type { Router } from './router';
+import { RouteType } from './types';
+import type { RouteConfirmHook, RouteConfirmHookResult, RouteLocationInput, RouteNotifyHook } from './types';
+/**
+ * Route transition hooks responsible for handling different stages of the navigation process.
+ * Each hook is responsible for a specific aspect of route transition.
+ */
+export declare const ROUTE_TRANSITION_HOOKS: {
+    fallback(to: Route, from: Route | null, router: Router): Promise<RouteConfirmHookResult>;
+    override(to: Route, from: Route | null, router: Router): Promise<RouteConfirmHookResult>;
+    asyncComponent(to: Route, from: Route | null, router: Router): Promise<RouteConfirmHookResult>;
+    beforeLeave(to: Route, from: Route | null, router: Router): Promise<RouteConfirmHookResult>;
+    beforeEnter(to: Route, from: Route | null, router: Router): Promise<RouteConfirmHookResult>;
+    beforeUpdate(to: Route, from: Route | null, router: Router): Promise<RouteConfirmHookResult>;
+    beforeEach(to: Route, from: Route | null, router: Router): Promise<RouteConfirmHookResult>;
+    confirm(to: Route, from: Route | null, router: Router): Promise<RouteConfirmHookResult>;
+};
+/**
+ * Route type handlers configuration.
+ * Maps each route type to its corresponding navigation handler function.
+ * These handlers perform the actual navigation operations like updating browser state,
+ * managing micro-app updates, and handling different navigation patterns.
+ */
+export declare const ROUTE_TYPE_HANDLERS: {
+    push(to: Route, from: Route | null, router: Router): void;
+    replace(to: Route, from: Route | null, router: Router): void;
+    restartApp(to: Route, from: Route | null, router: Router): void;
+    pushWindow(to: Route, from: Route | null, router: Router): unknown;
+    replaceWindow(to: Route, from: Route | null, router: Router): unknown;
+    pushLayer(to: Route, from: Route | null, router: Router): Promise<import("./types").RouteLayerResult>;
+    default(to: Route, from: Route | null, router: Router): void;
+};
+/**
+ * Route Transition Manager
+ * Responsible for managing all route transition logic, including guard execution,
+ * task processing, and status updates.
+ */
+export declare class RouteTransition {
+    private readonly router;
+    route: Route | null;
+    private _controller;
+    readonly guards: {
+        beforeEach: RouteConfirmHook[];
+        afterEach: RouteNotifyHook[];
+    };
+    constructor(router: Router);
+    beforeEach(guard: RouteConfirmHook): () => void;
+    afterEach(guard: RouteNotifyHook): () => void;
+    destroy(): void;
+    to(toType: RouteType, toInput: RouteLocationInput): Promise<Route>;
+    private _runTask;
+}

package/dist/route-transition.mjs

@@ -0,0 +1,307 @@
+import { Route } from "./route.mjs";
+import {
+  RouteTaskController,
+  createRouteTask
+} from "./route-task.mjs";
+import { RouteType } from "./types.mjs";
+import {
+  isRouteMatched,
+  isUrlEqual,
+  isValidConfirmHookResult,
+  removeFromArray
+} from "./util.mjs";
+export const ROUTE_TRANSITION_HOOKS = {
+  async fallback(to, from, router) {
+    if (to.matched.length === 0) {
+      return router.parsedOptions.fallback;
+    }
+  },
+  async override(to, from, router) {
+    var _a, _b;
+    const result = await ((_b = (_a = to.config) == null ? void 0 : _a.override) == null ? void 0 : _b.call(_a, to, from, router));
+    if (isValidConfirmHookResult(result)) {
+      return result;
+    }
+  },
+  async asyncComponent(to, from, router) {
+    await Promise.all(
+      to.matched.map(async (matched) => {
+        const { asyncComponent, component } = matched;
+        if (!component && typeof asyncComponent === "function") {
+          try {
+            const result = await asyncComponent();
+            matched.component = result;
+          } catch {
+            throw new Error(
+              `Async component '${matched.compilePath}' is not a valid component.`
+            );
+          }
+        }
+      })
+    );
+  },
+  async beforeLeave(to, from, router) {
+    if (!(from == null ? void 0 : from.matched.length)) return;
+    const leavingRoutes = from.matched.filter(
+      (fromRoute) => !to.matched.some((toRoute) => toRoute === fromRoute)
+    );
+    for (let i = leavingRoutes.length - 1; i >= 0; i--) {
+      const route = leavingRoutes[i];
+      if (route.beforeLeave) {
+        const result = await route.beforeLeave(to, from, router);
+        if (isValidConfirmHookResult(result)) {
+          return result;
+        }
+      }
+    }
+  },
+  async beforeEnter(to, from, router) {
+    if (!to.matched.length) return;
+    const enteringRoutes = to.matched.filter(
+      (toRoute) => !(from == null ? void 0 : from.matched.some((fromRoute) => fromRoute === toRoute))
+    );
+    for (const route of enteringRoutes) {
+      if (route.beforeEnter) {
+        const result = await route.beforeEnter(to, from, router);
+        if (isValidConfirmHookResult(result)) {
+          return result;
+        }
+      }
+    }
+  },
+  async beforeUpdate(to, from, router) {
+    if (!isRouteMatched(to, from, "route")) return;
+    if (!from || to.matched.length !== from.matched.length) return;
+    const isSameRouteSet = to.matched.every(
+      (toRoute, index) => toRoute === from.matched[index]
+    );
+    if (!isSameRouteSet) return;
+    if (!isRouteMatched(to, from, "exact")) {
+      for (const route of to.matched) {
+        if (route.beforeUpdate) {
+          const result = await route.beforeUpdate(to, from, router);
+          if (isValidConfirmHookResult(result)) {
+            return result;
+          }
+        }
+      }
+    }
+  },
+  async beforeEach(to, from, router) {
+    const transition = router.transition;
+    for (const guard of transition.guards.beforeEach) {
+      const result = await guard(to, from, router);
+      if (isValidConfirmHookResult(result)) {
+        return result;
+      }
+    }
+  },
+  async confirm(to, from, router) {
+    if (to.confirm) {
+      const result = await to.confirm(to, from, router);
+      if (isValidConfirmHookResult(result)) {
+        return result;
+      }
+    }
+    switch (to.type) {
+      case RouteType.push:
+        return ROUTE_TYPE_HANDLERS.push;
+      case RouteType.replace:
+        return ROUTE_TYPE_HANDLERS.replace;
+      case RouteType.restartApp:
+        return ROUTE_TYPE_HANDLERS.restartApp;
+      case RouteType.pushWindow:
+        return ROUTE_TYPE_HANDLERS.pushWindow;
+      case RouteType.replaceWindow:
+        return ROUTE_TYPE_HANDLERS.replaceWindow;
+      case RouteType.pushLayer:
+        return ROUTE_TYPE_HANDLERS.pushLayer;
+      default:
+        return ROUTE_TYPE_HANDLERS.default;
+    }
+  }
+};
+export const ROUTE_TYPE_HANDLERS = {
+  push(to, from, router) {
+    router.transition.route = to;
+    router.microApp._update(router);
+    if (!isUrlEqual(to.url, from == null ? void 0 : from.url)) {
+      const newState = router.navigation.push(to.state, to.url);
+      to.applyNavigationState(newState);
+    } else {
+      const newState = router.navigation.replace(to.state, to.url);
+      to.applyNavigationState(newState);
+    }
+  },
+  replace(to, from, router) {
+    router.transition.route = to;
+    router.microApp._update(router);
+    const newState = router.navigation.replace(to.state, to.url);
+    to.applyNavigationState(newState);
+  },
+  restartApp(to, from, router) {
+    router.transition.route = to;
+    router.microApp._update(router, true);
+    const newState = router.navigation.replace(to.state, to.url);
+    to.applyNavigationState(newState);
+  },
+  pushWindow(to, from, router) {
+    return router.parsedOptions.fallback(to, from, router);
+  },
+  replaceWindow(to, from, router) {
+    return router.parsedOptions.fallback(to, from, router);
+  },
+  async pushLayer(to, from, router) {
+    const { promise } = await router.createLayer(to);
+    return promise;
+  },
+  default(to, from, router) {
+    router.transition.route = to;
+    router.microApp._update(router);
+    if (!isUrlEqual(to.url, from == null ? void 0 : from.url)) {
+      const newState = router.navigation.replace(to.state, to.url);
+      to.applyNavigationState(newState);
+    }
+  }
+};
+const ROUTE_TRANSITION_PIPELINE = {
+  [RouteType.push]: [
+    ROUTE_TRANSITION_HOOKS.fallback,
+    ROUTE_TRANSITION_HOOKS.override,
+    ROUTE_TRANSITION_HOOKS.beforeLeave,
+    ROUTE_TRANSITION_HOOKS.beforeEach,
+    ROUTE_TRANSITION_HOOKS.beforeUpdate,
+    ROUTE_TRANSITION_HOOKS.beforeEnter,
+    ROUTE_TRANSITION_HOOKS.asyncComponent,
+    ROUTE_TRANSITION_HOOKS.confirm
+  ],
+  [RouteType.replace]: [
+    ROUTE_TRANSITION_HOOKS.fallback,
+    ROUTE_TRANSITION_HOOKS.override,
+    ROUTE_TRANSITION_HOOKS.beforeLeave,
+    ROUTE_TRANSITION_HOOKS.beforeEach,
+    ROUTE_TRANSITION_HOOKS.beforeUpdate,
+    ROUTE_TRANSITION_HOOKS.beforeEnter,
+    ROUTE_TRANSITION_HOOKS.asyncComponent,
+    ROUTE_TRANSITION_HOOKS.confirm
+  ],
+  [RouteType.pushWindow]: [
+    ROUTE_TRANSITION_HOOKS.fallback,
+    ROUTE_TRANSITION_HOOKS.override,
+    // ROUTE_TRANSITION_HOOKS.beforeLeave
+    ROUTE_TRANSITION_HOOKS.beforeEach,
+    // ROUTE_TRANSITION_HOOKS.beforeUpdate
+    // ROUTE_TRANSITION_HOOKS.beforeEnter
+    // ROUTE_TRANSITION_HOOKS.asyncComponent
+    ROUTE_TRANSITION_HOOKS.confirm
+  ],
+  [RouteType.replaceWindow]: [
+    ROUTE_TRANSITION_HOOKS.fallback,
+    ROUTE_TRANSITION_HOOKS.override,
+    ROUTE_TRANSITION_HOOKS.beforeLeave,
+    ROUTE_TRANSITION_HOOKS.beforeEach,
+    // ROUTE_TRANSITION_HOOKS.beforeUpdate
+    // ROUTE_TRANSITION_HOOKS.beforeEnter
+    // ROUTE_TRANSITION_HOOKS.asyncComponent
+    ROUTE_TRANSITION_HOOKS.confirm
+  ],
+  [RouteType.pushLayer]: [
+    ROUTE_TRANSITION_HOOKS.fallback,
+    ROUTE_TRANSITION_HOOKS.override,
+    // ROUTE_TRANSITION_HOOKS.beforeLeave
+    ROUTE_TRANSITION_HOOKS.beforeEach,
+    // ROUTE_TRANSITION_HOOKS.beforeUpdate
+    // ROUTE_TRANSITION_HOOKS.beforeEnter
+    // ROUTE_TRANSITION_HOOKS.asyncComponent
+    ROUTE_TRANSITION_HOOKS.confirm
+  ],
+  [RouteType.restartApp]: [
+    ROUTE_TRANSITION_HOOKS.fallback,
+    // ROUTE_TRANSITION_HOOKS.override,
+    ROUTE_TRANSITION_HOOKS.beforeLeave,
+    ROUTE_TRANSITION_HOOKS.beforeEach,
+    ROUTE_TRANSITION_HOOKS.beforeUpdate,
+    ROUTE_TRANSITION_HOOKS.beforeEnter,
+    ROUTE_TRANSITION_HOOKS.asyncComponent,
+    ROUTE_TRANSITION_HOOKS.confirm
+  ],
+  [RouteType.unknown]: [
+    ROUTE_TRANSITION_HOOKS.fallback,
+    // ROUTE_TRANSITION_HOOKS.override,
+    ROUTE_TRANSITION_HOOKS.beforeLeave,
+    ROUTE_TRANSITION_HOOKS.beforeEach,
+    ROUTE_TRANSITION_HOOKS.beforeUpdate,
+    ROUTE_TRANSITION_HOOKS.beforeEnter,
+    ROUTE_TRANSITION_HOOKS.asyncComponent,
+    ROUTE_TRANSITION_HOOKS.confirm
+  ]
+};
+export class RouteTransition {
+  router;
+  route = null;
+  // Task controller for the current transition.
+  _controller = null;
+  // Guard arrays, responsible for storing navigation guards.
+  guards = {
+    beforeEach: [],
+    afterEach: []
+  };
+  constructor(router) {
+    this.router = router;
+  }
+  beforeEach(guard) {
+    this.guards.beforeEach.push(guard);
+    return () => {
+      removeFromArray(this.guards.beforeEach, guard);
+    };
+  }
+  afterEach(guard) {
+    this.guards.afterEach.push(guard);
+    return () => {
+      removeFromArray(this.guards.afterEach, guard);
+    };
+  }
+  destroy() {
+    var _a;
+    (_a = this._controller) == null ? void 0 : _a.abort();
+    this._controller = null;
+  }
+  async to(toType, toInput) {
+    const from = this.route;
+    const to = await this._runTask(
+      new Route({
+        options: this.router.parsedOptions,
+        toType,
+        toInput,
+        from: (from == null ? void 0 : from.url) ?? null
+      }),
+      from
+    );
+    if (typeof to.handle === "function") {
+      to.handleResult = await to.handle(to, from, this.router);
+    }
+    if (to.handle) {
+      for (const guard of this.guards.afterEach) {
+        guard(to, from, this.router);
+      }
+    }
+    return to;
+  }
+  async _runTask(to, from) {
+    var _a;
+    (_a = this._controller) == null ? void 0 : _a.abort();
+    this._controller = new RouteTaskController();
+    const taskFunctions = ROUTE_TRANSITION_PIPELINE[to.type] || ROUTE_TRANSITION_PIPELINE[RouteType.unknown];
+    const tasks = taskFunctions.map((taskFn) => ({
+      name: taskFn.name,
+      task: taskFn
+    }));
+    return createRouteTask({
+      to,
+      from,
+      tasks,
+      controller: this._controller,
+      router: this.router
+    });
+  }
+}

package/dist/route-transition.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/route-transition.test.mjs

@@ -0,0 +1,146 @@
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { Router } from "./router.mjs";
+import { RouteType, RouterMode } from "./types.mjs";
+describe("Route Transition Tests", () => {
+  let router;
+  beforeEach(async () => {
+    router = new Router({
+      mode: RouterMode.memory,
+      base: new URL("http://localhost:3000/"),
+      routes: [
+        { path: "/", component: () => "Home" },
+        { path: "/user/:id", component: () => "User" },
+        { path: "/about", component: () => "About" },
+        {
+          path: "/async",
+          asyncComponent: () => Promise.resolve("Async")
+        }
+      ]
+    });
+    await router.replace("/");
+  });
+  afterEach(() => {
+    router.destroy();
+  });
+  describe("Basic transitions", () => {
+    test("should successfully transition to new route", async () => {
+      const route = await router.push("/user/123");
+      expect(route.path).toBe("/user/123");
+      expect(route.params.id).toBe("123");
+      expect(route.handle).not.toBe(null);
+    });
+    test("should handle async component loading", async () => {
+      const route = await router.push("/async");
+      expect(route.path).toBe("/async");
+      expect(route.handle).not.toBe(null);
+    });
+  });
+  describe("Error handling", () => {
+    test("should handle non-existent routes", async () => {
+      const route = await router.push("/non-existent");
+      expect(route.matched).toHaveLength(0);
+      expect(route.config).toBe(null);
+    });
+    test("should handle component loading errors", async () => {
+      const errorRouter = new Router({
+        mode: RouterMode.memory,
+        base: new URL("http://localhost:3000/"),
+        routes: [
+          { path: "/", component: () => "Home" },
+          {
+            path: "/error",
+            asyncComponent: () => Promise.reject(new Error("Loading failed"))
+          }
+        ]
+      });
+      await errorRouter.replace("/");
+      await expect(errorRouter.push("/error")).rejects.toThrow();
+      errorRouter.destroy();
+    });
+  });
+  describe("Concurrent navigation", () => {
+    test("should handle concurrent navigation attempts", async () => {
+      const promises = Array.from(
+        { length: 5 },
+        (_, i) => router.push(`/user/${i + 1}`).catch((err) => err)
+      );
+      const results = await Promise.all(promises);
+      const successResults = results.filter((r) => !(r instanceof Error));
+      const abortedResults = results.filter((r) => r instanceof Error);
+      expect(successResults).toHaveLength(1);
+      expect(abortedResults).toHaveLength(4);
+      const successResult = successResults[0];
+      expect(router.route.path).toBe(successResult.path);
+      expect(router.route.params.id).toBe(successResult.params.id);
+    });
+  });
+  describe("Route guards", () => {
+    let guardRouter;
+    let guardLog;
+    beforeEach(async () => {
+      guardLog = [];
+      guardRouter = new Router({
+        mode: RouterMode.memory,
+        base: new URL("http://localhost:3000/"),
+        routes: [
+          { path: "/", component: () => "Home" },
+          {
+            path: "/protected",
+            component: () => "Protected",
+            beforeEnter: () => {
+              guardLog.push("beforeEnter-protected");
+              return false;
+            }
+          },
+          {
+            path: "/allowed",
+            component: () => "Allowed",
+            beforeEnter: () => {
+              guardLog.push("beforeEnter-allowed");
+            }
+          }
+        ]
+      });
+      await guardRouter.replace("/");
+    });
+    afterEach(() => {
+      guardRouter.destroy();
+    });
+    test("should block navigation when guard returns false", async () => {
+      await expect(guardRouter.push("/protected")).rejects.toThrow();
+      expect(guardLog).toContain("beforeEnter-protected");
+      expect(guardRouter.route.path).toBe("/");
+    });
+    test("should allow navigation when guard returns true", async () => {
+      const route = await guardRouter.push("/allowed");
+      expect(guardLog).toContain("beforeEnter-allowed");
+      expect(route.path).toBe("/allowed");
+      expect(guardRouter.route.path).toBe("/allowed");
+    });
+  });
+  describe("Navigation types", () => {
+    test("should correctly set route type for push navigation", async () => {
+      const route = await router.push("/user/123");
+      expect(route.type).toBe(RouteType.push);
+    });
+    test("should correctly set route type for replace navigation", async () => {
+      const route = await router.replace("/user/123");
+      expect(route.type).toBe(RouteType.replace);
+    });
+  });
+  describe("Route parameters and query", () => {
+    test("should correctly extract route parameters", async () => {
+      const route = await router.push("/user/456");
+      expect(route.params.id).toBe("456");
+      expect(route.path).toBe("/user/456");
+    });
+    test("should handle query parameters", async () => {
+      const route = await router.push(
+        "/user/123?tab=profile&active=true"
+      );
+      expect(route.params.id).toBe("123");
+      expect(route.query.tab).toBe("profile");
+      expect(route.query.active).toBe("true");
+    });
+  });
+});

package/dist/route.d.ts

@@ -0,0 +1,72 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type RouteConfirmHook, type RouteHandleHook, type RouteHandleResult, type RouteLayerOptions, type RouteLocationInput, type RouteMatchResult, type RouteMeta, type RouteOptions, type RouteParsedConfig, type RouteState, RouteType } from './types';
+/**
+ * Configuration for non-enumerable properties in Route class
+ * These properties will be hidden during object traversal and serialization
+ */
+export declare const NON_ENUMERABLE_PROPERTIES: string[];
+/**
+ * Append user-provided parameters to URL path
+ * @param match Route matching result
+ * @param toInput User-provided route location object
+ * @param base Base URL
+ * @param to Current parsed URL object
+ */
+export declare function applyRouteParams(match: RouteMatchResult, toInput: RouteLocationInput, base: URL, to: URL): void;
+/**
+ * Route class provides complete route object functionality
+ */
+export declare class Route {
+    private _handled;
+    private _handle;
+    private _handleResult;
+    private readonly _options;
+    readonly statusCode: number | null;
+    readonly state: RouteState;
+    readonly keepScrollPosition: boolean;
+    /** Custom confirm handler that overrides default route-transition confirm logic */
+    readonly confirm: RouteConfirmHook | null;
+    /** Layer configuration for layer routes */
+    readonly layer: RouteLayerOptions | null;
+    readonly type: RouteType;
+    readonly req: IncomingMessage | null;
+    readonly res: ServerResponse | null;
+    readonly context: Record<string | symbol, any>;
+    readonly url: URL;
+    readonly path: string;
+    readonly fullPath: string;
+    readonly hash: string;
+    readonly params: Record<string, string>;
+    readonly query: Record<string, string | undefined>;
+    readonly queryArray: Record<string, string[] | undefined>;
+    readonly meta: RouteMeta;
+    readonly matched: readonly RouteParsedConfig[];
+    readonly config: RouteParsedConfig | null;
+    constructor(routeOptions?: Partial<RouteOptions>);
+    get isPush(): boolean;
+    get handle(): RouteHandleHook | null;
+    set handle(val: RouteHandleHook | null);
+    get handleResult(): RouteHandleResult | null;
+    set handleResult(val: RouteHandleResult | null);
+    /**
+     * Set handle function with validation logic wrapper
+     */
+    setHandle(val: RouteHandleHook | null): void;
+    /**
+     * Apply navigation-generated state to current route
+     * Used by route handlers to add system state like pageId
+     * @param navigationState Navigation-generated state to apply
+     */
+    applyNavigationState(navigationState: Partial<RouteState>): void;
+    /**
+     * Sync all properties of current route to target route object
+     * Used for route object updates in reactive systems
+     * @param targetRoute Target route object
+     */
+    syncTo(targetRoute: Route): void;
+    /**
+     * Clone current route instance
+     * Returns a new Route instance with same configuration and state
+     */
+    clone(): Route;
+}