alepha 0.19.3 → 0.19.4

package/src/react/router/__tests__/$page.browser.spec.tsx

@@ -882,4 +882,161 @@ describe("$page browser tests", () => {
       });
     });
   });
+
+  describe("transition supersession", () => {
+    it("should not commit a stale slow transition when a newer navigation already won", async () => {
+      let resolvePageA: ((value: { data: string }) => void) | undefined;
+      const pageARendered = vi.fn();
+      const pageBRendered = vi.fn();
+
+      class App {
+        pageA = $page({
+          path: "/page-a",
+          loader: () =>
+            new Promise<{ data: string }>((resolve) => {
+              resolvePageA = resolve;
+            }),
+          component: ({ data }: { data: string }) => {
+            pageARendered();
+            return <div data-testid="page-a">A: {data}</div>;
+          },
+        });
+
+        pageB = $page({
+          path: "/page-b",
+          component: () => {
+            pageBRendered();
+            return <div data-testid="page-b">B</div>;
+          },
+        });
+      }
+
+      alepha = Alepha.create().with(AlephaReact).with(App);
+      await alepha.start();
+
+      const router = alepha.inject(ReactRouter);
+
+      // Start navigating to /page-a — its loader hangs, push() will not
+      // resolve until we manually resolve the loader below.
+      const pushAPromise = router.push("/page-a");
+
+      // Yield so the in-flight transition for /page-a actually starts and
+      // reaches the awaited loader before pushB enters the race.
+      await new Promise((r) => setTimeout(r, 0));
+
+      // Navigate to /page-b before /page-a finishes loading. This should
+      // supersede the in-flight /page-a transition.
+      await act(async () => {
+        await router.push("/page-b");
+      });
+
+      // /page-b should now be the committed router state.
+      expect(router.state.name).toBe("pageB");
+      expect(router.state.url.pathname).toBe("/page-b");
+
+      // Now resolve /page-a's loader: this is the race window where the
+      // stale /page-a transition could overwrite /page-b.
+      resolvePageA?.({ data: "loaded" });
+      await act(async () => {
+        await pushAPromise;
+      });
+
+      // Stale /page-a must NOT have committed.
+      expect(router.state.name).toBe("pageB");
+      expect(router.state.url.pathname).toBe("/page-b");
+      // /page-a's component must never have been instantiated.
+      expect(pageARendered).not.toHaveBeenCalled();
+    });
+
+    it("should not fire onEnter for a stale superseded page", async () => {
+      let resolvePageA: (() => void) | undefined;
+      const pageAOnEnter = vi.fn();
+      const pageBOnEnter = vi.fn();
+
+      class App {
+        pageA = $page({
+          path: "/page-a",
+          loader: () =>
+            new Promise<void>((resolve) => {
+              resolvePageA = resolve;
+            }),
+          onEnter: pageAOnEnter,
+          component: () => <div data-testid="page-a">A</div>,
+        });
+
+        pageB = $page({
+          path: "/page-b",
+          onEnter: pageBOnEnter,
+          component: () => <div data-testid="page-b">B</div>,
+        });
+      }
+
+      alepha = Alepha.create().with(AlephaReact).with(App);
+      await alepha.start();
+
+      const router = alepha.inject(ReactRouter);
+
+      const pushAPromise = router.push("/page-a");
+      await new Promise((r) => setTimeout(r, 0));
+
+      await act(async () => {
+        await router.push("/page-b");
+      });
+
+      expect(router.state.name).toBe("pageB");
+      expect(pageBOnEnter).toHaveBeenCalledTimes(1);
+      expect(pageAOnEnter).not.toHaveBeenCalled();
+
+      // Resolve the stale loader: it must remain a no-op.
+      resolvePageA?.();
+      await act(async () => {
+        await pushAPromise;
+      });
+
+      expect(router.state.name).toBe("pageB");
+      expect(pageAOnEnter).not.toHaveBeenCalled();
+      expect(pageBOnEnter).toHaveBeenCalledTimes(1);
+    });
+
+    it("should not call pushState for a stale superseded transition", async () => {
+      let resolvePageA: (() => void) | undefined;
+
+      class App {
+        pageA = $page({
+          path: "/page-a",
+          loader: () =>
+            new Promise<void>((resolve) => {
+              resolvePageA = resolve;
+            }),
+          component: () => <div data-testid="page-a">A</div>,
+        });
+
+        pageB = $page({
+          path: "/page-b",
+          component: () => <div data-testid="page-b">B</div>,
+        });
+      }
+
+      alepha = Alepha.create().with(AlephaReact).with(App);
+      await alepha.start();
+
+      const router = alepha.inject(ReactRouter);
+
+      const pushAPromise = router.push("/page-a");
+      await new Promise((r) => setTimeout(r, 0));
+
+      await act(async () => {
+        await router.push("/page-b");
+      });
+      expect(window.location.pathname).toBe("/page-b");
+
+      resolvePageA?.();
+      await act(async () => {
+        await pushAPromise;
+      });
+
+      // The stale /page-a transition must not have rewritten the URL bar.
+      expect(window.location.pathname).toBe("/page-b");
+    });
+  });
 });

package/src/react/router/providers/ReactBrowserProvider.ts

@@ -79,6 +79,17 @@ export class ReactBrowserProvider {
     from?: string;
   };
 
+  /**
+   * Monotonic counter used to detect stale (superseded) transitions.
+   *
+   * Each call to `render()` captures `++this.transitionId` and any
+   * subsequent `render()` invalidates older in-flight transitions.
+   * This prevents a slow page from racing past a newer navigation
+   * (e.g. user clicks /pageA which has a 2s loader, then clicks /pageB
+   * — pageB must remain the committed page).
+   */
+  protected transitionId = 0;
+
   public get state(): ReactRouterState {
     return this.alepha.store.get("alepha.react.router.state")!;
   }
@@ -167,12 +178,21 @@ export class ReactBrowserProvider {
       options,
     });
 
+    const myTransitionId = ++this.transitionId;
+
     await this.render({
       url,
       previous: options.force ? [] : this.state.layers,
       meta: options.meta,
+      transitionId: myTransitionId,
     });
 
+    // A newer navigation has superseded us — bail out without touching
+    // history, otherwise we'd push a duplicate/stale entry.
+    if (myTransitionId !== this.transitionId) {
+      return;
+    }
+
     // when redirecting in browser
     if (this.state.url.pathname + this.state.url.search !== url) {
       this.pushState(this.state.url.pathname + this.state.url.search);
@@ -183,6 +203,7 @@ export class ReactBrowserProvider {
   }
 
   protected async render(options: RouterRenderOptions = {}): Promise<void> {
+    const myTransitionId = options.transitionId ?? ++this.transitionId;
     const previous = options.previous ?? this.state.layers;
     const url = options.url ?? this.url;
     const start = this.dateTimeProvider.now();
@@ -196,12 +217,25 @@ export class ReactBrowserProvider {
       to: url,
     });
 
+    const isStale = () => this.transitionId !== myTransitionId;
+
     const redirect = await this.router.transition(
       new URL(`http://localhost${url}`),
       previous,
       options.meta,
+      isStale,
     );
 
+    // A newer navigation has superseded us between the time we awaited
+    // transition() and now. Drop everything: don't follow redirects, don't
+    // log success, don't clear `transitioning` (the newer render owns it).
+    if (isStale()) {
+      this.log.debug("Transition superseded — discarding stale result", {
+        to: url,
+      });
+      return;
+    }
+
     if (redirect) {
       this.log.info("Redirecting to", {
         redirect,
@@ -307,4 +341,9 @@ export interface RouterRenderOptions {
   url?: string;
   previous?: PreviousLayerData[];
   meta?: Record<string, any>;
+  /**
+   * Transition id used to detect supersession by a newer navigation.
+   * When omitted, render() allocates a fresh id internally.
+   */
+  transitionId?: number;
 }

package/src/react/router/providers/ReactBrowserRouterProvider.ts

@@ -51,6 +51,7 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
     url: URL,
     previous: PreviousLayerData[] = [],
     meta = {},
+    isStale: () => boolean = () => false,
   ): Promise<string | void> {
     const { pathname, search } = url;
 
@@ -101,6 +102,13 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
           state,
           previous,
         );
+        // A newer navigation already won — bail before committing or
+        // emitting any further events. The caller (ReactBrowserProvider)
+        // also re-checks staleness, but stopping here avoids running
+        // success hooks for a transition the user no longer wants.
+        if (isStale()) {
+          return;
+        }
         if (redirect) {
           return redirect;
         }
@@ -120,6 +128,13 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
       });
       await this.alepha.events.emit("react:transition:success", { state });
     } catch (e) {
+      // If we were superseded mid-flight, swallow the error: the user has
+      // already moved on, and an error UI for an abandoned page would
+      // overwrite the newer page they actually want.
+      if (isStale()) {
+        return;
+      }
+
       this.log.error("Transition has failed", e);
 
       let element: ReactNode | undefined;
@@ -151,6 +166,13 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
       });
     }
 
+    // Final supersession check before any side effects (onLeave/onEnter,
+    // store mutation, head rewrite). Stale transitions must be a complete
+    // no-op from this point on.
+    if (isStale()) {
+      return;
+    }
+
     // [feature]: local hook for leaving a page
     if (previous) {
       for (let i = 0; i < previous.length; i++) {