fix: allow page to skip the rendering (#266)

Author: sirily11

packages/core/src/core/core.tsx

@@ -20,7 +20,7 @@ import {
   StorageInterface,
   StoredRoute,
 } from "@rx-lab/common";
-import { RedirectError } from "@rx-lab/errors";
+import { RedirectError, SkipError } from "@rx-lab/errors";
 import { encodeStateKey, stateCache } from "@rx-lab/storage";
 import React from "react";
 import { Renderer } from "./renderer";
@@ -331,6 +331,11 @@ export class Core<T extends Container<BaseChatroomInfo, BaseMessage>>
           // ignore it
           return;
         }
+
+        if (e instanceof SkipError) {
+          return;
+        }
+
         console.error(e);
         const props: ErrorPageProps = {
           error: e,
@@ -512,6 +517,13 @@ export class Core<T extends Container<BaseChatroomInfo, BaseMessage>>
           },
         );
       }
+
+      // skip the current render
+      if (e instanceof SkipError) {
+        // immediately timeout the current render
+        this.lastCommitUpdateTime = 0;
+      }
+
       throw e;
     }
   }

packages/errors/src/errorCode.ts

@@ -16,4 +16,6 @@ export enum ErrorCode {
   DuplicateKeyProps = 1004,
   // Redirect
   RedirectToNewLocation = 1005,
+  // Skip
+  Skip = 1006,
 }

packages/errors/src/errors/index.ts

@@ -3,3 +3,4 @@ export * from "./unsupportedReactInstance";
 export * from "./missingRequiredKeyProps";
 export * from "./duplicatedKeyProps";
 export * from "./redirect";
+export * from "./skip";

packages/errors/src/errors/skip.ts

@@ -0,0 +1,16 @@
+import { ErrorCode } from "../errorCode";
+import { CustomError } from "./error";
+
+/**
+ * Represents an error thrown when a page's rendering should be skipped for the current request.
+ * This is typically used in middleware or routing logic to indicate that the regular page
+ * rendering flow should be bypassed without treating it as a failure condition.
+ *
+ * @throws {SkipError} When the page rendering should be skipped
+ * @extends {CustomError}
+ */
+export class SkipError extends CustomError {
+  constructor() {
+    super("Skip error", ErrorCode.Skip);
+  }
+}

packages/router/src/index.ts

@@ -8,6 +8,7 @@ export {
   matchRouteWithPath,
 } from "./router";
 export { redirect } from "./redirect";
+export { skip } from "./skip";
 
 interface SuspendableProps {
   children: any;

packages/router/src/skip.ts

@@ -0,0 +1,25 @@
+import { SkipError } from "@rx-lab/errors";
+
+/**
+ * Immediately terminates the current render operation and triggers a new render.
+ * Useful for handling conditional rendering flows or invalidating the current render pass.
+ *
+ * Note: This operation can only be called during render, and will throw an error if called
+ * during event handlers or effects.
+ *
+ * @throws {Error} If called outside of component render
+ *
+ * @example
+ * ```tsx
+ * export default function Page() {
+ *   if (shouldSkip) {
+ *     skip(); // Abandon current render and start fresh
+ *   }
+ *
+ *   return <div>Content</div>;
+ * }
+ * ```
+ */
+export function skip() {
+  throw new SkipError();
+}

tests/telegram-e2e-tests/src/nav/skip/skip.spec.tsx

@@ -0,0 +1,54 @@
+import { Telegram, Utils } from "@rx-lab/testing";
+
+const {
+  PORT,
+  Api,
+  initialize,
+  TestingEnvironment,
+  MessageType,
+  DEFAULT_RENDERING_WAIT_TIME,
+} = Telegram;
+const { sleep } = Utils;
+
+const chatroomId = 2104;
+
+describe("skip the page", () => {
+  let api: Telegram.Api<any>;
+  let coreApi: any;
+
+  beforeAll(async () => {
+    api = new Api({
+      baseUrl: `http://0.0.0.0:${PORT}`,
+    });
+  });
+
+  it("should skip the page rendering", async () => {
+    const { core } = await initialize({
+      filename: import.meta.url,
+      environment: TestingEnvironment.LongPolling,
+      api,
+      chatroomId,
+    });
+    coreApi = core;
+
+    await api.chatroom.sendMessageToChatroom(chatroomId, {
+      content: "Hello",
+      type: MessageType.Text,
+    });
+    await sleep(DEFAULT_RENDERING_WAIT_TIME);
+    let messages = await api.chatroom.getMessagesByChatroom(chatroomId);
+    expect(messages.data.count).toBe(2);
+
+    await api.chatroom.sendMessageToChatroom(chatroomId, {
+      content: "skip",
+      type: MessageType.Text,
+    });
+    await sleep(DEFAULT_RENDERING_WAIT_TIME);
+    messages = await api.chatroom.getMessagesByChatroom(chatroomId);
+    expect(messages.data.count).toBe(3);
+  });
+
+  afterEach(async () => {
+    await coreApi?.onDestroy();
+  });
+});

tests/telegram-e2e-tests/src/nav/skip/src/app/page.tsx

@@ -0,0 +1,10 @@
+import { PageProps } from "@rx-lab/common";
+import { skip } from "@rx-lab/router";
+
+export default function Page({ text }: PageProps) {
+  if (text === "skip") {
+    skip();
+  }
+
+  return <div>Page</div>;
+}