@evolu/web 3.0.0-next.0 → 3.0.0

package/src/Sqlite.ts

@@ -3,6 +3,7 @@ import { bytesToHex, createPreparedStatementsCache, ok } from "@evolu/common";
 import sqlite3InitModule, {
   type Database,
   type PreparedStatement,
+  type SAHPoolUtil,
 } from "@evolu/sqlite-wasm";
 
 // @ts-expect-error Missing types.
@@ -23,26 +24,51 @@ globalThis.sqlite3ApiConfig = {
 // Init ASAP.
 const sqlite3Promise = sqlite3InitModule();
 
+const fileName = "evolu1.db";
+
 export const createWasmSqliteDriver: CreateSqliteDriver =
   (name, options) => async () => {
     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);
 
-    const stack = new globalThis.DisposableStack();
+    using disposer = new DisposableStack();
+    const useDatabase = (database: Database): Database =>
+      disposer.adopt(database, (database) => {
+        database.close();
+      });
+
+    let deleteDatabaseFile = false;
+    const createOpfsSAHPoolVfs = async (
+      options: Parameters<typeof sqlite3.installOpfsSAHPoolVfs>[0],
+    ): Promise<SAHPoolUtil> => {
+      const pool = await sqlite3.installOpfsSAHPoolVfs(options);
+      if (pool.isPaused()) await pool.unpauseVfs();
+      disposer.defer(() => {
+        if (deleteDatabaseFile) pool.unlink(`/${fileName}`);
+        pool.pauseVfs();
+      });
+      return pool;
+    };
+
     let db: Database;
+
     switch (options?.mode) {
       case "memory":
-        db = new sqlite3.oo1.DB(":memory:");
+        db = useDatabase(new sqlite3.oo1.DB(":memory:"));
         break;
+
       case "encrypted": {
-        const pool = await sqlite3.installOpfsSAHPoolVfs({
+        // MultipleCiphers encryption requires its VFS wrapper for OPFS SAH-pool.
+        // @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);
+        const pool = await createOpfsSAHPoolVfs({
           directory: `.${name}`,
         });
-        db = new pool.OpfsSAHPoolDb(
-          "file:evolu1.db?vfs=multipleciphers-opfs-sahpool",
+        db = useDatabase(
+          new pool.OpfsSAHPoolDb(
+            // SQLite normalizes this URI filename to SAH-pool path "/evolu1.db".
+            `file:${fileName}?vfs=multipleciphers-opfs-sahpool`,
+          ),
         );
         db.exec(`
           PRAGMA cipher = 'sqlcipher';
@@ -50,17 +76,14 @@ export const createWasmSqliteDriver: CreateSqliteDriver =
         `);
         break;
       }
+
       default: {
-        const pool = await sqlite3.installOpfsSAHPoolVfs({ name });
-        db = new pool.OpfsSAHPoolDb("file:evolu1.db");
+        const pool = await createOpfsSAHPoolVfs({ name });
+        db = useDatabase(new pool.OpfsSAHPoolDb(`file:${fileName}`));
       }
     }
 
-    db = stack.adopt(db, (db) => {
-      db.close();
-    });
-
-    const cache = stack.use(
+    const cache = disposer.use(
       createPreparedStatementsCache<PreparedStatement>(
         (sql) => db.prepare(sql),
         (statement) => {
@@ -69,6 +92,8 @@ export const createWasmSqliteDriver: CreateSqliteDriver =
       ),
     );
 
+    const disposables = disposer.move();
+
     return ok({
       exec: (query) => {
         const prepared = cache.get(query);
@@ -101,9 +126,13 @@ export const createWasmSqliteDriver: CreateSqliteDriver =
 
       export: () => sqlite3.capi.sqlite3_js_db_export(db),
 
+      deleteDatabase: () => {
+        deleteDatabaseFile = true;
+        disposables.dispose();
+      },
+
       [Symbol.dispose]: () => {
-        // poolUtil.unlink?
-        stack.dispose();
+        disposables.dispose();
       },
     });
   };

package/src/Task.ts

@@ -1,57 +1,21 @@
 /**
- * Web platform-specific Task utilities.
+ * Web-specific Task utilities.
  *
  * @module
  */
 
 import {
   createRun as createCommonRun,
-  createUnknownError,
-  ok,
-  type CreateRun,
-  type LeaderLock,
+  type DisposableRun,
   type Run,
-  type RunDeps,
+  type RunCustomDeps,
 } from "@evolu/common";
 
 /**
- * Creates a {@link LeaderLock} backed by the Web Locks API.
+ * Creates a root {@link Run} for the browser.
  *
- * Waiting for the browser lock is intentionally unabortable. If a caller starts
- * waiting and its {@link Run} or fiber is later aborted, the underlying Web
- * Locks request keeps waiting until the browser grants the lock. Only the
- * returned lease releases it.
- */
-export const createLeaderLock = (): LeaderLock => ({
-  lock: (name) => async () => {
-    const acquired = Promise.withResolvers<void>();
-    const release = Promise.withResolvers<void>();
-
-    void globalThis.navigator.locks.request(
-      `evolu-leaderlock-${name}`,
-      { mode: "exclusive" },
-      async () => {
-        acquired.resolve();
-        await release.promise;
-      },
-    );
-
-    await acquired.promise;
-
-    return ok({
-      [Symbol.asyncDispose]: async () => {
-        release.resolve();
-        return Promise.resolve();
-      },
-    });
-  },
-});
-
-/**
- * Creates {@link Run} for the browser with global error handling.
- *
- * Registers `error` and `unhandledrejection` handlers that log errors to the
- * console. Handlers are removed when the Run is disposed.
+ * Defects are reported with the browser's global `reportError`. A custom
+ * `reportDefect` dependency overrides the browser default.
  *
  * ### Example
  *
@@ -62,33 +26,22 @@ export const createLeaderLock = (): LeaderLock => ({
  *   }),
  * });
  *
- * await using run = createRun({ console });
- * await using stack = new AsyncDisposableStack();
- *
- * stack.use(await run.orThrow(startApp()));
+ * const run = createRun({ console });
+ * const appPromise = run.ok(startApp());
  * ```
  */
-export const createRun: CreateRun<RunDeps> = <D>(
-  deps?: D,
-): Run<RunDeps & D> => {
-  const run = createCommonRun(deps);
-  const console = run.deps.console.child("global");
-
-  globalThis.addEventListener(
-    "error",
-    (event) => {
-      console.error("error", createUnknownError(event.error));
-    },
-    { signal: run.signal },
-  );
-
-  globalThis.addEventListener(
-    "unhandledrejection",
-    (event) => {
-      console.error("unhandledrejection", createUnknownError(event.reason));
-    },
-    { signal: run.signal },
-  );
-
-  return run;
-};
+export function createRun(): DisposableRun;
+export function createRun<D extends object>(
+  deps: RunCustomDeps<D>,
+): DisposableRun<D>;
+export function createRun<D extends object>(
+  deps?: RunCustomDeps<D>,
+): DisposableRun | DisposableRun<D> {
+  const reportDefect = (reported: unknown): void => {
+    globalThis.reportError(reported);
+  };
+
+  return deps === undefined
+    ? createCommonRun({ reportDefect })
+    : createCommonRun<D>({ reportDefect, ...deps });
+}

package/src/Worker.ts

@@ -1,4 +1,8 @@
 import type {
+  BroadcastChannel,
+  CreateBroadcastChannel,
+  CreateBroadcastChannelDep,
+  CreateMessageChannelDep,
   CreateMessagePort,
   MessageChannel,
   MessagePort,
@@ -10,14 +14,49 @@ import type {
   WorkerDeps,
   WorkerSelf,
 } from "@evolu/common";
-import { assert, createConsole, createConsoleStoreOutput } from "@evolu/common";
+import {
+  assert,
+  createConsole,
+  createConsoleStoreOutput,
+  disposable,
+} from "@evolu/common";
 
 /** Creates a {@link Worker} from a Web Worker. */
 export const createWorker = <Input, Output>(
   nativeWorker: globalThis.Worker,
 ): Worker<Input, Output> => wrap(nativeWorker);
 
-/** Creates an Evolu {@link SharedWorker} from a Web SharedWorker. */
+/**
+ * Installs a one-tab SharedWorker polyfill backed by a Web Worker.
+ *
+ * Use it before constructing a SharedWorker in browsers without native
+ * SharedWorker support.
+ */
+export const installOneTabSharedWorkerPolyfill = (): void => {
+  if (typeof globalThis.SharedWorker === "function") return;
+
+  Object.defineProperty(globalThis, "SharedWorker", {
+    configurable: true,
+    writable: true,
+    value: class {
+      readonly port: globalThis.MessagePort;
+
+      constructor(scriptURL: string | URL, options?: WorkerOptions) {
+        this.port = new globalThis.Worker(
+          scriptURL,
+          options,
+        ) as unknown as globalThis.MessagePort;
+      }
+    },
+  });
+};
+
+/**
+ * Creates a {@link SharedWorker} from a Web SharedWorker.
+ *
+ * Call {@link installOneTabSharedWorkerPolyfill} first to support browsers
+ * without native SharedWorker support.
+ */
 export const createSharedWorker = <Input, Output = never>(
   nativeSharedWorker: globalThis.SharedWorker,
 ): SharedWorker<Input, Output> => {
@@ -44,14 +83,16 @@ export const createMessageChannel = <Input, Output = never>(): MessageChannel<
   Output
 > => {
   const channel = new globalThis.MessageChannel();
-  const stack = new DisposableStack();
+  using disposer = new DisposableStack();
+
+  const port1 = disposer.use(wrap<Input, Output>(channel.port1));
+  const port2 = disposer.use(wrap<Output, Input>(channel.port2));
+  const disposables = disposer.move();
 
   return {
-    port1: stack.use(wrap<Input, Output>(channel.port1)),
-    port2: stack.use(wrap<Output, Input>(channel.port2)),
-    [Symbol.dispose]: () => {
-      stack.dispose();
-    },
+    port1,
+    port2,
+    [Symbol.dispose]: () => disposables.dispose(),
   };
 };
 
@@ -63,6 +104,47 @@ export const createMessageChannel = <Input, Output = never>(): MessageChannel<
 export const createMessagePort: CreateMessagePort = (nativePort) =>
   wrap(nativePort as unknown as globalThis.MessagePort);
 
+/** Creates an Evolu {@link BroadcastChannel} from a Web BroadcastChannel. */
+export const createBroadcastChannel: CreateBroadcastChannel = <
+  Input,
+  Output = Input,
+>(
+  name: string,
+): BroadcastChannel<Input, Output> => {
+  const nativeBroadcastChannel = new globalThis.BroadcastChannel(name);
+  using disposer = new DisposableStack();
+  let disposed = false;
+
+  disposer.defer(() => {
+    disposed = true;
+    nativeBroadcastChannel.onmessage = null;
+    nativeBroadcastChannel.close();
+  });
+
+  let onMessageHandler: ((message: Output) => void) | null = null;
+
+  return disposable<BroadcastChannel<Input, Output>>(
+    {
+      postMessage: (message) => {
+        nativeBroadcastChannel.postMessage(message);
+      },
+      get onMessage() {
+        return disposed ? null : onMessageHandler;
+      },
+      set onMessage(fn) {
+        if (disposed) return;
+        onMessageHandler = fn;
+        nativeBroadcastChannel.onmessage = fn
+          ? (event: MessageEvent<Output>) => {
+              fn(event.data);
+            }
+          : null;
+      },
+    },
+    disposer,
+  );
+};
+
 /**
  * Creates an Evolu {@link WorkerSelf} from a Web `DedicatedWorkerGlobalScope`
  * (`self` inside a dedicated worker).
@@ -99,23 +181,109 @@ export const createSharedWorkerSelf = <Input, Output = never>(
   return self;
 };
 
+/**
+ * Creates a one-tab {@link SharedWorkerSelf} polyfill for browsers without
+ * native SharedWorker support.
+ *
+ * Delivers one synthetic `onConnect` port, queues startup messages until
+ * `onMessage` is set, and does not share state across tabs.
+ */
+export const createOneTabSharedWorkerSelfPolyfill = <Input, Output = never>(
+  nativeSelf: globalThis.DedicatedWorkerGlobalScope,
+): SharedWorkerSelf<Input, Output> => {
+  using disposer = new DisposableStack();
+
+  let onConnectHandler: ((port: MessagePort<Output, Input>) => void) | null =
+    null;
+  let onMessageHandler: ((message: Input) => void) | null = null;
+  const messages: Array<Input> = [];
+  let connected = false;
+
+  disposer.defer(() => {
+    messages.length = 0;
+    onConnectHandler = null;
+    onMessageHandler = null;
+    nativeSelf.onmessage = null;
+    nativeSelf.close();
+  });
+
+  const disposables = disposer.move();
+
+  nativeSelf.onmessage = (event: MessageEvent<Input>) => {
+    if (disposables.disposed) return;
+
+    const handler = onMessageHandler;
+    if (handler) handler(event.data);
+    else messages.push(event.data);
+  };
+
+  const flushMessages = (): void => {
+    for (const message of messages.splice(0)) {
+      const handler = onMessageHandler;
+      if (!handler) return;
+      handler(message);
+    }
+  };
+
+  const port: MessagePort<Output, Input> = {
+    postMessage: (message, transfer) => {
+      if (disposables.disposed) return;
+      if (transfer == null) nativeSelf.postMessage(message);
+      else nativeSelf.postMessage(message, [...transfer]);
+    },
+
+    get onMessage() {
+      return disposables.disposed ? null : onMessageHandler;
+    },
+    set onMessage(fn) {
+      if (disposables.disposed) return;
+      onMessageHandler = fn;
+      if (fn) flushMessages();
+    },
+
+    native: nativeSelf as unknown as NativeMessagePort<Output, Input>,
+
+    [Symbol.dispose]: () => disposables.dispose(),
+  };
+
+  const connect = (): void => {
+    if (connected || !onConnectHandler) return;
+    connected = true;
+    onConnectHandler(port);
+  };
+
+  return {
+    get onConnect() {
+      return onConnectHandler;
+    },
+    set onConnect(fn) {
+      if (disposables.disposed) return;
+      onConnectHandler = fn;
+      connect();
+    },
+    [Symbol.dispose]: () => disposables.dispose(),
+  };
+};
+
 /** Creates deps shared by web worker entry points. */
-export const createWorkerDeps = (): WorkerDeps => {
+export const createWorkerDeps = (): WorkerDeps &
+  CreateBroadcastChannelDep &
+  CreateMessageChannelDep => {
   const consoleStoreOutput = createConsoleStoreOutput();
   const console = createConsole({ output: consoleStoreOutput });
 
   return {
     console,
     consoleStoreOutputEntry: consoleStoreOutput.entry,
+    createBroadcastChannel,
+    createMessageChannel,
     createMessagePort,
   };
 };
 
 const wrap = <Input, Output>(
   native:
-    | DedicatedWorkerGlobalScope
-    | globalThis.MessagePort
-    | globalThis.Worker,
+    DedicatedWorkerGlobalScope | globalThis.MessagePort | globalThis.Worker,
 ): MessagePort<Input, Output> => {
   let onMessageHandler: ((message: Output) => void) | null = null;
 
@@ -144,7 +312,7 @@ const wrap = <Input, Output>(
 
     [Symbol.dispose]: () => {
       native.onmessage = null;
-      if (native instanceof globalThis.Worker) native.terminate();
+      if ("terminate" in native) native.terminate();
       else native.close();
     },
   };

package/src/index.ts

@@ -1,4 +1,5 @@
-export * from "./local-first/index.js";
-export * from "./Sqlite.js";
-export * from "./Task.js";
-export * from "./Worker.js";
+export * from "./local-first/index.ts";
+export { availableParallelism } from "./Platform.ts";
+export * from "./Sqlite.ts";
+export * from "./Task.ts";
+export * from "./Worker.ts";

package/src/local-first/Db.worker.ts

@@ -6,16 +6,15 @@ installPolyfills();
 
 import { createRandomBytes } from "@evolu/common";
 import { startDbWorker } from "@evolu/common/local-first";
-import { createWasmSqliteDriver } from "../Sqlite.js";
-import { createLeaderLock, createRun } from "../Task.js";
-import { createWorkerDeps, createWorkerSelf } from "../Worker.js";
+import { createWasmSqliteDriver } from "../Sqlite.ts";
+import { createRun } from "../Task.ts";
+import { createWorkerDeps, createWorkerSelf } from "../Worker.ts";
 
-// TODO: Disposal.
 const run = createRun({
   ...createWorkerDeps(),
   createSqliteDriver: createWasmSqliteDriver,
-  leaderLock: createLeaderLock(),
+  lockManager: globalThis.navigator.locks,
   randomBytes: createRandomBytes(),
 });
 
-run(startDbWorker(createWorkerSelf(self)));
+void run(startDbWorker(createWorkerSelf(self)));

package/src/local-first/Evolu.ts

@@ -1,17 +1,21 @@
-import type { ConsoleDep } from "@evolu/common";
+import { exhaustiveCheck, type ConsoleDep } from "@evolu/common";
 import type {
+  SharedWorker as CommonSharedWorker,
   CreateDbWorker,
   DbWorkerInit,
   EvoluDeps,
   SharedWorkerInput,
+  SharedWorkerOutput,
 } from "@evolu/common/local-first";
 import { createEvoluDeps as createCommonEvoluDeps } from "@evolu/common/local-first";
-import { reloadApp } from "../Platform.js";
+import { reloadApp } from "../Platform.ts";
 import {
+  createBroadcastChannel,
   createMessageChannel,
   createSharedWorker,
   createWorker,
-} from "../Worker.js";
+  installOneTabSharedWorkerPolyfill,
+} from "../Worker.ts";
 
 // // TODO: Redesign.
 // // eslint-disable-next-line evolu/require-pure-annotation
@@ -20,8 +24,20 @@ import {
 //   secureStorage: createWebAuthnStore({ randomBytes: createRandomBytes() }),
 // });
 
+export interface SharedWorkerUnsupported {
+  readonly type: "SharedWorkerUnsupported";
+}
+
+export interface SharedWorkerUnsupportedDep {
+  readonly onSharedWorkerUnsupported: () => void;
+}
+
 /** Creates Evolu dependencies for the web platform. */
-export const createEvoluDeps = (deps: Partial<ConsoleDep> = {}): EvoluDeps => {
+export const createEvoluDeps = (
+  deps: Partial<ConsoleDep> & Partial<SharedWorkerUnsupportedDep> = {},
+): EvoluDeps => {
+  installOneTabSharedWorkerPolyfill();
+
   const createDbWorker: CreateDbWorker = () =>
     createWorker<DbWorkerInit, never>(
       new Worker(new URL("Db.worker.js", import.meta.url), {
@@ -29,16 +45,59 @@ export const createEvoluDeps = (deps: Partial<ConsoleDep> = {}): EvoluDeps => {
       }),
     );
 
-  const sharedWorker = createSharedWorker<SharedWorkerInput>(
+  const webSharedWorker = createSharedWorker<
+    SharedWorkerInput,
+    SharedWorkerOutput
+  >(
     new SharedWorker(new URL("Shared.worker.js", import.meta.url), {
       type: "module",
     }),
   );
+  let onSharedWorkerMessage: ((message: SharedWorkerOutput) => void) | null =
+    null;
+  const sharedWorker: CommonSharedWorker = {
+    ...webSharedWorker,
+    port: {
+      ...webSharedWorker.port,
+      get onMessage() {
+        return onSharedWorkerMessage;
+      },
+      set onMessage(fn) {
+        onSharedWorkerMessage = fn;
+        webSharedWorker.port.onMessage = fn
+          ? (message: SharedWorkerOutput | SharedWorkerUnsupported) => {
+              switch (message.type) {
+                case "DbWorkerInit": {
+                  fn(message);
+                  break;
+                }
+
+                case "SharedWorkerUnsupported": {
+                  if (deps.onSharedWorkerUnsupported) {
+                    deps.onSharedWorkerUnsupported();
+                  } else {
+                    globalThis.alert(
+                      "This browser supports Evolu in one tab only. Close this tab and use the already open tab.",
+                    );
+                  }
+                  break;
+                }
+
+                default:
+                  exhaustiveCheck(message);
+              }
+            }
+          : null;
+      },
+    },
+  };
 
   return createCommonEvoluDeps({
     ...deps,
     createDbWorker,
+    createBroadcastChannel,
     createMessageChannel,
+    lockManager: globalThis.navigator.locks,
     reloadApp,
     sharedWorker,
   });

package/src/local-first/Shared.worker.ts

@@ -1,18 +1,58 @@
 /// <reference lib="webworker" />
-declare const self: SharedWorkerGlobalScope;
+declare const self: DedicatedWorkerGlobalScope | SharedWorkerGlobalScope;
 
 import { installPolyfills } from "@evolu/common/polyfills";
 installPolyfills();
 
-import { createWebSocket } from "@evolu/common";
+import { createWebSocket, ok, waitForAbort } from "@evolu/common";
+import type {
+  SharedWorkerInput,
+  SharedWorkerOutput,
+} from "@evolu/common/local-first";
 import { initSharedWorker } from "@evolu/common/local-first";
-import { createRun } from "../Task.js";
-import { createSharedWorkerSelf, createWorkerDeps } from "../Worker.js";
+import type { SharedWorkerUnsupported } from "./Evolu.ts";
+import { createRun } from "../Task.ts";
+import {
+  createOneTabSharedWorkerSelfPolyfill,
+  createSharedWorkerSelf,
+  createWorkerDeps,
+} from "../Worker.ts";
 
-// No disposal (`await using`) is needed — a SharedWorker lives forever.
 const run = createRun({
   ...createWorkerDeps(),
   createWebSocket,
+  lockManager: globalThis.navigator.locks,
 });
 
-run(initSharedWorker(createSharedWorkerSelf(self)));
+void run(async (run) => {
+  if ("onconnect" in self) {
+    await using _ = await run.ok(
+      initSharedWorker(createSharedWorkerSelf(self)),
+    );
+    return await run(waitForAbort);
+  }
+
+  using workerSelf = createOneTabSharedWorkerSelfPolyfill<
+    SharedWorkerInput,
+    SharedWorkerOutput
+  >(self);
+
+  await globalThis.navigator.locks.request(
+    "evolu-one-tab-sharedworker-polyfill",
+    { ifAvailable: true, mode: "exclusive" },
+    async (lock) => {
+      if (!lock) {
+        const message: SharedWorkerUnsupported = {
+          type: "SharedWorkerUnsupported",
+        };
+        self.postMessage(message);
+        return;
+      }
+
+      await using _ = await run.ok(initSharedWorker(workerSelf));
+      await run(waitForAbort);
+    },
+  );
+
+  return ok();
+});

package/src/local-first/index.ts

@@ -1 +1 @@
-export * from "./Evolu.js";
+export * from "./Evolu.ts";