refactor: centralize error and console message reporting from worker to tab via a single message channel.

Author: miccy

apps/web/src/app/(playgrounds)/playgrounds/minimal/EvoluMinimalExample.tsx

@@ -27,6 +27,15 @@ const Schema = {
 
 const deps = createEvoluDeps();
 
+deps.evoluError.subscribe(() => {
+  const error = deps.evoluError.get();
+  if (!error) return;
+
+  alert("🚨 Evolu error occurred! Check the console.");
+  // eslint-disable-next-line no-console
+  console.error(error);
+});
+
 // Create Evolu instance for the React web platform.
 const evolu = Evolu.createEvolu(deps)(Schema, {
   name: Evolu.SimpleName.orThrow("minimal-example"),
@@ -46,20 +55,6 @@ const evolu = Evolu.createEvolu(deps)(Schema, {
 // in tests via the EvoluProvider.
 const useEvolu = createUseEvolu(evolu);
 
-/**
- * Subscribe to Evolu errors (database, network, sync issues). These should not
- * happen in normal operation, so always log them for debugging. Show users a
- * friendly error message instead of technical details.
- */
-evolu.subscribeError(() => {
-  const error = evolu.getError();
-  if (!error) return;
-
-  alert("🚨 Evolu error occurred! Check the console.");
-  // eslint-disable-next-line no-console
-  console.error(error);
-});
-
 export const EvoluMinimalExample: FC = () => (
   <div className="min-h-screen px-8 py-8">
     <div className="mx-auto max-w-md">

bun.lock

@@ -49,7 +49,7 @@
     "@vitest/browser-playwright": "^4.0.17",
     "@vitest/coverage-v8": "^4.0.17",
     "rimraf": "^6.1.2",
-    "turbo": "^2.8.7",
+    "turbo": "^2.8.8",
     "typedoc": "^0.28.17",
     "typedoc-plugin-markdown": "^4.9.0",
     "typescript": "^5.9.3",

package.json

@@ -6,14 +6,20 @@
 
 import { dedupeArray, isNonEmptyArray } from "../Array.js";
 import { assertNonEmptyReadonlyArray } from "../Assert.js";
-import { type ConsoleDep, createConsole } from "../Console.js";
+import {
+  type Console,
+  type ConsoleDep,
+  type ConsoleEntry,
+  createConsole,
+} from "../Console.js";
 import {
   createRandomBytes,
   type EncryptionKey,
   type RandomBytesDep,
 } from "../Crypto.js";
 import { eqArrayNumber } from "../Eq.js";
 import { createUnknownError } from "../Error.js";
+import { exhaustiveCheck } from "../Function.js";
 import type { Listener, Unsubscribe } from "../Listeners.js";
 import type { FlushSyncDep, ReloadAppDep } from "../Platform.js";
 import { createDisposableDep, type DisposableStackDep } from "../Resources.js";
@@ -65,7 +71,7 @@ import {
 } from "./Schema.js";
 import type { DbChange, ValidDbChangeValues } from "./Storage.js";
 import type { SyncOwner } from "./Sync.js";
-import type { EvoluWorkerDep } from "./Worker.js";
+import type { EvoluTabOutput, EvoluWorkerDep } from "./Worker.js";
 
 export interface EvoluConfig {
   /**
@@ -571,18 +577,59 @@ export type EvoluPlatformDeps = ReloadAppDep &
   Partial<ConsoleDep> &
   Partial<FlushSyncDep>;
 
+const writeConsoleEntry = (console: Console, entry: ConsoleEntry): void => {
+  const method = console[entry.method] as (
+    ...args: ReadonlyArray<unknown>
+  ) => void;
+  method(...entry.args);
+};
+
 /** Creates Evolu dependencies from platform-specific dependencies. */
 export const createEvoluDeps = <D extends EvoluPlatformDeps>(
   deps: D,
 ): EvoluDeps => {
+  const { createMessageChannel, evoluWorker } = deps as D &
+    CreateMessageChannelDep &
+    EvoluWorkerDep;
   const disposableStack = new DisposableStack();
-  const evoluError = createErrorStore({ ...deps, disposableStack } as any);
+  const console = deps.console ?? createConsole();
+  const evoluError = disposableStack.use(createStore<EvoluError | null>(null));
+  const tabChannel = disposableStack.use(
+    createMessageChannel<EvoluTabOutput>(),
+  );
+
+  disposableStack.use(evoluWorker);
+
+  tabChannel.port2.onMessage = (output: EvoluTabOutput) => {
+    switch (output.type) {
+      case "ConsoleEntry": {
+        writeConsoleEntry(console, output.entry);
+        if (output.entry.method === "error") {
+          // Fallback when an error was logged without typed EvoluError payload.
+          evoluError.set(createUnknownError(output.entry.args));
+        }
+        break;
+      }
+      case "EvoluError": {
+        evoluError.set(output.error);
+        console.error(output.error);
+        break;
+      }
+      default:
+        exhaustiveCheck(output);
+    }
+  };
+
+  evoluWorker.port.postMessage(
+    { type: "InitTab", port: tabChannel.port1.native },
+    [tabChannel.port1.native],
+  );
 
   return {
     ...deps,
     disposableStack,
     ...createDisposableDep(disposableStack),
-    console: deps.console ?? createConsole(),
+    console,
     evoluError,
     randomBytes: createRandomBytes(),
   } as unknown as EvoluDeps;
@@ -606,28 +653,6 @@ export interface ErrorStoreDep {
   readonly evoluError: ReadonlyStore<EvoluError | null>;
 }
 
-const createErrorStore = (
-  deps: CreateMessageChannelDep & EvoluWorkerDep & DisposableStackDep,
-): Store<EvoluError | null> => {
-  const errorChannel = deps.disposableStack.use(
-    deps.createMessageChannel<EvoluError>(),
-  );
-  const evoluError = deps.disposableStack.use(
-    createStore<EvoluError | null>(null),
-  );
-
-  deps.evoluWorker.port.postMessage(
-    { type: "InitErrorStore", port: errorChannel.port1.native },
-    [errorChannel.port1.native],
-  );
-
-  errorChannel.port2.onMessage = (error) => {
-    evoluError.set(error);
-  };
-
-  return evoluError;
-};
-
 /**
  * Creates an {@link Evolu} instance for a platform configured with the specified
  * {@link EvoluSchema} and optional {@link EvoluConfig} providing a typed
@@ -681,10 +706,10 @@ export const createEvolu =
     } = config;
     const name =
       configName ??
-      appName ??
+      (appName ? SimpleName.orThrow(appName) : undefined) ??
       SimpleName.orThrow("default");
 
-    const errorStore = createStore<EvoluError | null>(null);
+    const errorStore = deps.evoluError as Store<EvoluError | null>;
     const rowsStore = createStore<QueryRowsMap>(new Map());
     const subscribedQueries = createSubscribedQueries(rowsStore);
     const loadingPromises = createLoadingPromises(subscribedQueries);

packages/common/src/local-first/Evolu.ts

@@ -4,10 +4,10 @@
  * @module
  */
 
+import type { ConsoleEntry } from "../Console.js";
 import { exhaustiveCheck } from "../Function.js";
 import { ok } from "../Result.js";
 import type { Task } from "../Task.js";
-import type { Typed } from "../Type.js";
 import type {
   SharedWorker as CommonSharedWorker,
   CreateMessagePortDep,
@@ -24,15 +24,25 @@ export interface EvoluWorkerDep {
   readonly evoluWorker: EvoluWorker;
 }
 
-export interface InitErrorStoreMessage extends Typed<"InitErrorStore"> {
-  readonly port: NativeMessagePort;
-}
-
-export interface InitEvoluMessage extends Typed<"InitEvolu"> {
-  readonly port: NativeMessagePort;
-}
+export type EvoluWorkerInput =
+  | {
+      readonly type: "InitTab";
+      readonly port: NativeMessagePort;
+    }
+  | {
+      readonly type: "InitEvolu";
+      readonly port: NativeMessagePort;
+    };
 
-export type EvoluWorkerInput = InitErrorStoreMessage | InitEvoluMessage;
+export type EvoluTabOutput =
+  | {
+      readonly type: "ConsoleEntry";
+      readonly entry: ConsoleEntry;
+    }
+  | {
+      readonly type: "EvoluError";
+      readonly error: EvoluError;
+    };
 
 export interface RunDbWorkerPortDep {
   readonly runDbWorkerPort: (
@@ -43,19 +53,35 @@ export interface RunDbWorkerPortDep {
 export const runEvoluWorkerScope =
   (deps: CreateMessagePortDep & RunDbWorkerPortDep) =>
   (self: EvoluWorkerScope<EvoluWorkerInput>): void => {
-    const errorStorePorts = new Set<MessagePort<EvoluError>>();
+    const tabPorts = new Set<MessagePort<EvoluTabOutput>>();
+    const queuedTabOutputs: Array<EvoluTabOutput> = [];
+
+    const postTabOutput = (output: EvoluTabOutput): void => {
+      if (tabPorts.size === 0) {
+        queuedTabOutputs.push(output);
+        return;
+      }
+      for (const port of tabPorts) port.postMessage(output);
+    };
 
     self.onError = (error) => {
-      for (const port of errorStorePorts) port.postMessage(error);
+      postTabOutput({ type: "EvoluError", error });
     };
 
     self.onConnect = (port) => {
       port.onMessage = (message) => {
         switch (message.type) {
-          case "InitErrorStore": {
-            errorStorePorts.add(
-              deps.createMessagePort<EvoluError>(message.port),
+          case "InitTab": {
+            const tabPort = deps.createMessagePort<EvoluTabOutput>(
+              message.port,
             );
+            tabPorts.add(tabPort);
+
+            if (queuedTabOutputs.length > 0) {
+              for (const output of queuedTabOutputs)
+                tabPort.postMessage(output);
+              queuedTabOutputs.length = 0;
+            }
             break;
           }
           case "InitEvolu": {

packages/common/src/local-first/Worker.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "vitest";
 // Force rebuild
 import { testCreateConsole } from "../../src/Console.js";
+import { createUnknownError } from "../../src/Error.js";
 import { lazyVoid } from "../../src/Function.js";
 import type {
   DbWorkerInput,
@@ -13,6 +14,7 @@ import {
 } from "../../src/local-first/Evolu.js";
 import type { AppOwner } from "../../src/local-first/Owner.js";
 import { createQueryBuilder } from "../../src/local-first/Schema.js";
+import type { EvoluTabOutput } from "../../src/local-first/Worker.js";
 import { SqliteBoolean } from "../../src/Sqlite.js";
 import { testCreateRun } from "../../src/Test.js";
 import { id, NonEmptyString100, nullOr } from "../../src/Type.js";
@@ -94,6 +96,7 @@ const createMockDeps = () => {
   let resetCount = 0;
   let mutateCount = 0;
   let closeCount = 0;
+  let tabPort: MockPort<EvoluTabOutput, never> | null = null;
 
   const deps = {
     reloadApp: () => {
@@ -103,9 +106,14 @@ const createMockDeps = () => {
     evoluWorker: {
       port: {
         postMessage: (
-          message: { type: "InitEvolu"; port: unknown },
+          message: { type: "InitTab" | "InitEvolu"; port: unknown },
           _transfer?: ReadonlyArray<unknown>,
         ) => {
+          if (message.type === "InitTab") {
+            tabPort = message.port as MockPort<EvoluTabOutput, never>;
+            return;
+          }
+
           if (message.type !== "InitEvolu") return;
           const dbPort = message.port as MockPort<
             DbWorkerOutput,
@@ -208,16 +216,21 @@ const createMockDeps = () => {
         native: {} as unknown,
         [Symbol.dispose]: () => {},
       },
+      [Symbol.dispose]: () => {},
     },
   };
 
   return {
     deps,
+    emitTabOutput: (output: EvoluTabOutput) => {
+      tabPort?.postMessage(output);
+    },
     getState: () => ({
       reloadCount,
       resetCount,
       mutateCount,
       closeCount,
+      hasTabPort: tabPort !== null,
       rows: [...rows],
     }),
   };
@@ -235,6 +248,34 @@ test("createEvoluDeps keeps provided console instance", () => {
   expect(evoluDeps.console).toBe(console);
 });
 
+test("createEvoluDeps updates evoluError store from tab output", () => {
+  const { deps, emitTabOutput, getState } = createMockDeps();
+  const evoluDeps = createEvoluDeps(deps as any);
+
+  expect(getState().hasTabPort).toBe(true);
+
+  const error = createUnknownError(new Error("tab-boom"));
+  emitTabOutput({ type: "EvoluError", error });
+
+  expect(evoluDeps.evoluError.get()).toEqual(error);
+});
+
+test("createEvoluDeps wraps console error entry into UnknownError", () => {
+  const { deps, emitTabOutput } = createMockDeps();
+  const evoluDeps = createEvoluDeps(deps as any);
+
+  emitTabOutput({
+    type: "ConsoleEntry",
+    entry: {
+      method: "error",
+      path: ["mock-worker"],
+      args: ["boom"],
+    },
+  });
+
+  expect(evoluDeps.evoluError.get()).toEqual(createUnknownError(["boom"]));
+});
+
 describe("createEvolu", () => {
   test("appOwner from config is exposed as evolu.appOwner", async () => {
     const { deps } = createMockDeps();