@evolu/web 2.3.0 → 3.0.0-next.0

package/dist/test/SharedWebWorker.test.js

@@ -1,248 +0,0 @@
-import { expect, test, vi, beforeEach, afterEach } from "vitest";
-import { createSharedWebWorker } from "../src/SharedWebWorker.js";
-import { SimpleName, wait } from "@evolu/common";
-// Mock BroadcastChannel
-class MockBroadcastChannel {
-    onmessage = null;
-    name;
-    constructor(name) {
-        this.name = name;
-    }
-    postMessage = vi.fn();
-    close = vi.fn();
-}
-// Mock Web Locks API
-const mockLocks = {
-    request: vi.fn(),
-};
-// Mock Web Worker
-class MockWorker {
-    onmessage = null;
-    postMessage = vi.fn();
-    terminate = vi.fn();
-}
-beforeEach(() => {
-    // Create a spy for BroadcastChannel constructor
-    globalThis.BroadcastChannel = vi.fn().mockImplementation(function (name) {
-        return new MockBroadcastChannel(name);
-    });
-    globalThis.document = {}; // Simulate browser environment
-    // Mock navigator.locks properly - remove the globalThis.navigator assignment
-    Object.defineProperty(globalThis.navigator, "locks", {
-        value: mockLocks,
-        writable: true,
-        configurable: true,
-    });
-    vi.clearAllMocks();
-});
-afterEach(() => {
-    vi.restoreAllMocks();
-});
-test("createSharedWebWorker creates BroadcastChannel and requests lock", () => {
-    const mockCreateWorker = vi.fn(() => new MockWorker());
-    const sharedWorker = createSharedWebWorker(SimpleName.orThrow("test-worker"), mockCreateWorker);
-    // Should create BroadcastChannel with namespaced name
-    expect(globalThis.BroadcastChannel).toHaveBeenCalledWith("evolu-sharedwebworker-test-worker");
-    // Should request owner-ready immediately
-    const channelInstance = vi.mocked(globalThis.BroadcastChannel).mock.results[0]
-        .value;
-    expect(channelInstance.postMessage).toHaveBeenCalledWith({
-        type: "request-owner-ready",
-    });
-    // Should attempt to acquire Web Lock
-    expect(mockLocks.request).toHaveBeenCalledWith("evolu-sharedwebworker-test-worker", expect.any(Function));
-    // Should return worker interface
-    expect(sharedWorker).toHaveProperty("postMessage");
-    expect(sharedWorker).toHaveProperty("onMessage");
-    expect(typeof sharedWorker.postMessage).toBe("function");
-    expect(typeof sharedWorker.onMessage).toBe("function");
-});
-test("createSharedWebWorker returns no-op on server", () => {
-    // Simulate server environment
-    delete globalThis.document;
-    const mockCreateWorker = vi.fn();
-    const sharedWorker = createSharedWebWorker(SimpleName.orThrow("test-worker"), mockCreateWorker);
-    // Should not create BroadcastChannel or request locks
-    expect(globalThis.BroadcastChannel).not.toHaveBeenCalled();
-    expect(mockLocks.request).not.toHaveBeenCalled();
-    // Should return no-op worker
-    expect(sharedWorker.postMessage).toBeDefined();
-    expect(sharedWorker.onMessage).toBeDefined();
-    // Restore document for other tests
-    globalThis.document = {};
-});
-test("createSharedWebWorker queues messages when owner not ready", () => {
-    const mockCreateWorker = vi.fn(() => new MockWorker());
-    const sharedWorker = createSharedWebWorker(SimpleName.orThrow("test-worker"), mockCreateWorker);
-    const channelInstance = vi.mocked(globalThis.BroadcastChannel).mock.results[0]
-        .value;
-    // Send message before owner is ready
-    sharedWorker.postMessage({ type: "test-message" });
-    // Should not send to channel yet (owner not ready)
-    expect(channelInstance.postMessage).toHaveBeenCalledTimes(1); // Only request-owner-ready
-    // Simulate owner-ready message
-    const ownerReadyEvent = new MessageEvent("message", {
-        data: { type: "owner-ready" },
-    });
-    channelInstance.onmessage?.(ownerReadyEvent);
-    // Should now send the queued message
-    expect(channelInstance.postMessage).toHaveBeenCalledWith({
-        type: "to-worker",
-        message: { type: "test-message" },
-    });
-});
-test("createSharedWebWorker forwards messages when owner ready", () => {
-    const mockCreateWorker = vi.fn(() => new MockWorker());
-    const sharedWorker = createSharedWebWorker(SimpleName.orThrow("test-worker"), mockCreateWorker);
-    const channelInstance = vi.mocked(globalThis.BroadcastChannel).mock.results[0]
-        .value;
-    // Simulate owner-ready message
-    const ownerReadyEvent = new MessageEvent("message", {
-        data: { type: "owner-ready" },
-    });
-    channelInstance.onmessage?.(ownerReadyEvent);
-    // Send message after owner is ready
-    sharedWorker.postMessage({ type: "test-message" });
-    // Should send directly to channel
-    expect(channelInstance.postMessage).toHaveBeenCalledWith({
-        type: "to-worker",
-        message: { type: "test-message" },
-    });
-});
-test("createSharedWebWorker handles onMessage callback", () => {
-    const mockCreateWorker = vi.fn(() => new MockWorker());
-    const onMessageCallback = vi.fn();
-    const sharedWorker = createSharedWebWorker(SimpleName.orThrow("test-worker"), mockCreateWorker);
-    sharedWorker.onMessage(onMessageCallback);
-    const channelInstance = vi.mocked(globalThis.BroadcastChannel).mock.results[0]
-        .value;
-    // Simulate message from worker
-    const workerMessage = new MessageEvent("message", {
-        data: { type: "from-worker", message: { result: "test" } },
-    });
-    channelInstance.onmessage?.(workerMessage);
-    // Should call the callback
-    expect(onMessageCallback).toHaveBeenCalledWith({ result: "test" });
-});
-test("createSharedWebWorker handles multiple tabs - first tab becomes owner", async () => {
-    let lockCallback;
-    // Mock locks.request to capture the callback but not execute it immediately
-    mockLocks.request.mockImplementation((_name, callback) => {
-        if (!lockCallback) {
-            lockCallback = callback;
-            // Simulate first tab acquiring the lock
-            setTimeout(() => {
-                void lockCallback?.();
-            }, 0);
-        }
-        return Promise.resolve();
-    });
-    const mockCreateWorker = vi.fn(() => new MockWorker());
-    // Create first tab (will become owner)
-    createSharedWebWorker(SimpleName.orThrow("test-worker"), mockCreateWorker);
-    // Create second tab
-    createSharedWebWorker(SimpleName.orThrow("test-worker"), mockCreateWorker);
-    // Both tabs should create BroadcastChannels
-    expect(globalThis.BroadcastChannel).toHaveBeenCalledTimes(2);
-    const tab1Channel = vi.mocked(globalThis.BroadcastChannel).mock.results[0]
-        .value;
-    const tab2Channel = vi.mocked(globalThis.BroadcastChannel).mock.results[1]
-        .value;
-    // Both tabs should request owner-ready
-    expect(tab1Channel.postMessage).toHaveBeenCalledWith({
-        type: "request-owner-ready",
-    });
-    expect(tab2Channel.postMessage).toHaveBeenCalledWith({
-        type: "request-owner-ready",
-    });
-    // Wait for lock acquisition
-    await wait("10ms")();
-    // Only first tab should create worker (it became owner)
-    expect(mockCreateWorker).toHaveBeenCalledTimes(1);
-    // First tab should announce ownership
-    expect(tab1Channel.postMessage).toHaveBeenCalledWith({ type: "owner-ready" });
-});
-test("createSharedWebWorker handles cross-tab message forwarding", () => {
-    const mockCreateWorker = vi.fn(() => new MockWorker());
-    // Create two tabs
-    const tab1 = createSharedWebWorker(SimpleName.orThrow("test-worker"), mockCreateWorker);
-    const tab2 = createSharedWebWorker(SimpleName.orThrow("test-worker"), mockCreateWorker);
-    const tab1Channel = vi.mocked(globalThis.BroadcastChannel).mock.results[0]
-        .value;
-    const tab2Channel = vi.mocked(globalThis.BroadcastChannel).mock.results[1]
-        .value;
-    // Simulate tab1 receiving owner-ready (tab1 becomes aware of owner)
-    const ownerReadyEvent = new MessageEvent("message", {
-        data: { type: "owner-ready" },
-    });
-    tab1Channel.onmessage?.(ownerReadyEvent);
-    // Simulate tab2 receiving owner-ready
-    tab2Channel.onmessage?.(ownerReadyEvent);
-    // Both tabs send messages
-    tab1.postMessage({ from: "tab1" });
-    tab2.postMessage({ from: "tab2" });
-    // Both should forward to channel
-    expect(tab1Channel.postMessage).toHaveBeenCalledWith({
-        type: "to-worker",
-        message: { from: "tab1" },
-    });
-    expect(tab2Channel.postMessage).toHaveBeenCalledWith({
-        type: "to-worker",
-        message: { from: "tab2" },
-    });
-});
-test("createSharedWebWorker handles worker responses across tabs", () => {
-    const mockCreateWorker = vi.fn(() => new MockWorker());
-    const tab1Callback = vi.fn();
-    const tab2Callback = vi.fn();
-    // Create two tabs
-    const tab1 = createSharedWebWorker(SimpleName.orThrow("test-worker"), mockCreateWorker);
-    const tab2 = createSharedWebWorker(SimpleName.orThrow("test-worker"), mockCreateWorker);
-    // Set up message callbacks
-    tab1.onMessage(tab1Callback);
-    tab2.onMessage(tab2Callback);
-    const tab1Channel = vi.mocked(globalThis.BroadcastChannel).mock.results[0]
-        .value;
-    const tab2Channel = vi.mocked(globalThis.BroadcastChannel).mock.results[1]
-        .value;
-    // Simulate worker response broadcast
-    const workerResponse = new MessageEvent("message", {
-        data: { type: "from-worker", message: { result: "shared-result" } },
-    });
-    // Both tabs receive the same worker response
-    tab1Channel.onmessage?.(workerResponse);
-    tab2Channel.onmessage?.(workerResponse);
-    // Both callbacks should be called with the same data
-    expect(tab1Callback).toHaveBeenCalledWith({ result: "shared-result" });
-    expect(tab2Callback).toHaveBeenCalledWith({ result: "shared-result" });
-});
-test("createSharedWebWorker multi-tab scenario", () => {
-    const mockCreateWorker = vi.fn(() => new MockWorker());
-    const channelInstances = [];
-    // Track all BroadcastChannel instances
-    globalThis.BroadcastChannel = vi.fn().mockImplementation(function (name) {
-        const instance = new MockBroadcastChannel(name);
-        channelInstances.push(instance);
-        // Override postMessage to broadcast to all instances with same name
-        instance.postMessage = vi.fn().mockImplementation((data) => {
-            channelInstances
-                .filter((ch) => ch.name === name)
-                .forEach((ch) => ch.onmessage?.(new MessageEvent("message", { data })));
-        });
-        return instance;
-    });
-    // Mock lock - only first caller gets the lock
-    let lockAcquired = false;
-    mockLocks.request.mockImplementation((_name, callback) => {
-        if (!lockAcquired) {
-            lockAcquired = true;
-            void callback(); // First tab becomes owner
-        }
-        return Promise.resolve();
-    });
-    // Create two tabs
-    createSharedWebWorker(SimpleName.orThrow("test-worker"), mockCreateWorker);
-    createSharedWebWorker(SimpleName.orThrow("test-worker"), mockCreateWorker);
-    // Only first tab should create worker (owner)
-    expect(mockCreateWorker).toHaveBeenCalledTimes(1);
-});

package/src/SharedWebWorker.ts

@@ -1,149 +0,0 @@
-/**
- * SharedWebWorker (WebWorker + BroadcastChannel + Web Locks)
- *
- * A SharedWebWorker is a Web Worker that is shared across multiple browser
- * tabs. This implementation provides a shared worker-like experience even in
- * browsers that do not support the native SharedWorker API.
- *
- * Unlike a true SharedWorker (which uses MessagePorts for direct, tab-specific
- * communication), this approach uses BroadcastChannel for cross-tab messaging
- * and Web Locks to ensure only one tab owns and runs the actual Worker
- * instance.
- *
- * All tabs communicate via BroadcastChannel, so every message is broadcast to
- * all tabs, and each tab must filter/process only relevant messages. This is
- * less efficient than MessagePorts, but it works everywhere and is "good
- * enough" for most use cases.
- *
- * See the protocol and coordination logic below for details.
- *
- * @module SharedWebWorker
- */
-
-import { constVoid, SimpleName, Worker } from "@evolu/common";
-
-/**
- * Ownership protocol explanation:
- *
- * - When a tab becomes the owner (acquires the lock), it announces ownership by
- *   posting { type: "owner-ready" } to the BroadcastChannel. This notifies all
- *   currently open tabs.
- * - Tabs that open later may miss this announcement, since BroadcastChannel does
- *   not replay messages. Therefore, new tabs request ownership status by
- *   posting { type: "request-owner-ready" }, and the owner responds with {
- *   type: "owner-ready" }.
- * - Once a tab receives "owner-ready", it knows where to send messages and does
- *   not need to ask again.
- * - This ensures all tabs, regardless of when they open, can reliably detect the
- *   current owner.
- *
- * Internal note:
- *
- * - Announcing ownership is for immediate notification of already-open tabs.
- * - Requesting ownership is a fallback for tabs that open later and miss the
- *   announcement.
- * - Both are required for robust cross-tab coordination.
- */
-type SharedWebWorkerChannelMessage<Input, Output> =
-  | { type: "owner-ready" }
-  | { type: "request-owner-ready" }
-  | { type: "to-worker"; message: Input }
-  | { type: "from-worker"; message: Output };
-
-/**
- * Creates a shared Web Worker using BroadcastChannel and Web Locks. This allows
- * multiple tabs to share a single Web Worker instance. The first tab to acquire
- * the lock becomes the owner and runs the worker. Other tabs act as proxies,
- * forwarding messages to the owner.
- */
-export const createSharedWebWorker = <Input, Output>(
-  name: SimpleName,
-  createWebWorker: () => globalThis.Worker,
-): Worker<Input, Output> => {
-  // Server.
-  if (typeof document === "undefined")
-    return {
-      postMessage: constVoid,
-      onMessage: constVoid,
-    };
-
-  const namespacedName = `evolu-sharedwebworker-${name}`;
-  const channel = new BroadcastChannel(namespacedName);
-
-  let worker: globalThis.Worker | undefined;
-  let onMessageCallback: ((message: Output) => void) | undefined;
-  let ownerReady = false;
-
-  const pendingMessages: Array<Input> = [];
-
-  // Listen for owner-ready and worker responses
-  channel.onmessage = (
-    event: MessageEvent<SharedWebWorkerChannelMessage<Input, Output>>,
-  ) => {
-    const data = event.data;
-    if (data.type === "owner-ready") {
-      ownerReady = true;
-      // Flush pending messages to the new owner
-      for (const message of pendingMessages) {
-        channel.postMessage({ type: "to-worker", message });
-      }
-      pendingMessages.length = 0;
-    } else if (!worker && data.type === "from-worker") {
-      onMessageCallback?.(data.message);
-    }
-  };
-
-  // Request owner-ready when not the owner
-  channel.postMessage({ type: "request-owner-ready" });
-
-  // Try to acquire the lock and become the owner
-  void navigator.locks.request(namespacedName, async () => {
-    worker = createWebWorker();
-
-    // Flush pending messages to the worker
-    for (const message of pendingMessages) {
-      worker.postMessage(message);
-    }
-    pendingMessages.length = 0;
-
-    // Forward messages from channel to worker
-    channel.onmessage = (
-      event: MessageEvent<SharedWebWorkerChannelMessage<Input, Output>>,
-    ) => {
-      const data = event.data;
-      if (data.type === "to-worker") {
-        worker!.postMessage(data.message);
-      } else if (data.type === "request-owner-ready") {
-        // Respond to request
-        channel.postMessage({ type: "owner-ready" });
-      }
-    };
-
-    // Forward messages from worker to channel
-    worker.onmessage = (event: MessageEvent<Output>) => {
-      channel.postMessage({ type: "from-worker", message: event.data });
-      onMessageCallback?.(event.data);
-    };
-
-    // Announce ownership
-    channel.postMessage({ type: "owner-ready" });
-
-    // Hold the lock forever
-    await new Promise(constVoid);
-  });
-
-  return {
-    postMessage: (message: Input) => {
-      if (worker) {
-        worker.postMessage(message);
-      } else if (ownerReady) {
-        channel.postMessage({ type: "to-worker", message });
-      } else {
-        pendingMessages.push(message);
-      }
-    },
-    onMessage: (callback) => {
-      onMessageCallback = callback;
-    },
-  };
-};

package/src/WasmSqliteDriver.ts

@@ -1,118 +0,0 @@
-import {
-  bytesToHex,
-  createPreparedStatementsCache,
-  CreateSqliteDriver,
-  SqliteDriver,
-  SqliteRow,
-} from "@evolu/common";
-import sqlite3InitModule, {
-  Database,
-  PreparedStatement,
-} from "@evolu/sqlite-wasm";
-
-// @ts-expect-error Missing types.
-globalThis.sqlite3ApiConfig = {
-  warn: (arg: unknown) => {
-    // Ignore irrelevant warning.
-    // https://github.com/sqlite/sqlite-wasm/issues/62
-    if (
-      typeof arg === "string" &&
-      arg.startsWith("Ignoring inability to install OPFS sqlite3_vfs")
-    )
-      return;
-    // eslint-disable-next-line no-console
-    console.warn(arg);
-  },
-};
-
-// Init ASAP.
-const sqlite3Promise = sqlite3InitModule();
-
-export const createWasmSqliteDriver: CreateSqliteDriver = async (
-  name,
-  options,
-) => {
-  const sqlite3 = await sqlite3Promise;
-  // This is used to make OPFS default vfs for multipleciphers
-  // @ts-expect-error Missing types (update @evolu/sqlite-wasm types)
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-call
-  sqlite3.capi.sqlite3mc_vfs_create("opfs", 1);
-
-  let db: Database;
-  if (options?.memory) {
-    db = new sqlite3.oo1.DB(":memory:");
-  } else if (options?.encryptionKey) {
-    const pool = await sqlite3.installOpfsSAHPoolVfs({ directory: `.${name}` });
-    db = new pool.OpfsSAHPoolDb(
-      "file:evolu1.db?vfs=multipleciphers-opfs-sahpool",
-    );
-    db.exec(`
-      PRAGMA cipher = 'sqlcipher';
-      PRAGMA legacy = 4;
-      PRAGMA key = "x'${bytesToHex(options.encryptionKey)}'";
-    `);
-  } else {
-    const pool = await sqlite3.installOpfsSAHPoolVfs({ name });
-    db = new pool.OpfsSAHPoolDb("file:evolu1.db");
-  }
-
-  let isDisposed = false;
-
-  const cache = createPreparedStatementsCache<PreparedStatement>(
-    (sql) => db.prepare(sql),
-    (statement) => {
-      statement.finalize();
-    },
-  );
-
-  const driver: SqliteDriver = {
-    exec: (query, isMutation) => {
-      const prepared = cache.get(query);
-
-      if (prepared) {
-        prepared.bind(query.parameters);
-
-        if (isMutation) {
-          prepared.stepReset();
-          return {
-            rows: [] as ReadonlyArray<SqliteRow>,
-            changes: db.changes(),
-          };
-        }
-
-        const rows = [];
-        while (prepared.step()) {
-          rows.push(prepared.get({}));
-        }
-        prepared.reset();
-
-        return {
-          rows: rows as ReadonlyArray<SqliteRow>,
-          changes: 0,
-        };
-      }
-
-      const rows = db.exec(query.sql, {
-        returnValue: "resultRows",
-        rowMode: "object",
-        bind: query.parameters,
-      }) as ReadonlyArray<SqliteRow>;
-
-      const changes = db.changes();
-
-      return { rows, changes };
-    },
-
-    export: () => sqlite3.capi.sqlite3_js_db_export(db),
-
-    [Symbol.dispose]: () => {
-      if (isDisposed) return;
-      isDisposed = true;
-      // poolUtil.unlink?
-      cache[Symbol.dispose]();
-      db.close();
-    },
-  };
-
-  return driver;
-};

package/src/WebWorker.ts

@@ -1,54 +0,0 @@
-/**
- * Typed wrapper for Web Worker
- *
- * While Comlink DX is nice, there are still memory leaks and unresolved bugs.
- * Use plain Web Worker with a typed wrapper if maximum performance and
- * reliability are required.
- *
- * @module
- */
-
-import { constVoid, Worker } from "@evolu/common";
-
-/**
- * Wraps a Web Worker to provide a typed interface for sending and receiving
- * messages.
- */
-export const wrapWebWorker = <Input, Output>(
-  createWebWorker: () => globalThis.Worker,
-): Worker<Input, Output> => {
-  // Server.
-  if (typeof document === "undefined")
-    return {
-      postMessage: constVoid,
-      onMessage: constVoid,
-    };
-
-  const webWorker = createWebWorker();
-
-  const worker: Worker<Input, Output> = {
-    postMessage: (message) => {
-      webWorker.postMessage(message);
-    },
-
-    onMessage: (callback) => {
-      webWorker.onmessage = (event: MessageEvent<Output>) => {
-        callback(event.data);
-      };
-    },
-  };
-
-  return worker;
-};
-
-export const wrapWebWorkerSelf = <Input, Output>(
-  worker: Worker<Input, Output>,
-): void => {
-  worker.onMessage((message) => {
-    postMessage(message);
-  });
-
-  self.onmessage = (event: MessageEvent<Input>) => {
-    worker.postMessage(event.data);
-  };
-};

package/src/local-first/Platform.ts

@@ -1,9 +0,0 @@
-import { ReloadApp } from "@evolu/common/local-first";
-
-export const reloadApp: ReloadApp = (url: string) => {
-  if (typeof document === "undefined") {
-    return;
-  }
-
-  location.replace(url);
-};