@evolu/web 3.1.2 → 3.3.0

package/src/Sqlite.test.ts

@@ -1,7 +1,11 @@
 import {
+  AbortError,
+  assert,
   assertEqual,
   assertEqualBytes,
+  assertSame,
   assertTrue,
+  assertType,
   EncryptionKey,
   Name,
   sql,
@@ -9,6 +13,90 @@ import {
 } from "@evolu/common";
 import { describe, it, mock } from "node:test";
 
+// OPFS with an optional pool directory. Each pool file lists the error names
+// its next openings reject with, in order.
+const opfsMock = (() => {
+  const state = {
+    closedAccessHandleCount: 0,
+    directoryNames: [] as Array<string>,
+    getDirectoryCount: 0,
+    hasOpaqueDirectory: true,
+    openedAccessHandleCount: 0,
+    poolFiles: null as Array<Array<string>> | null,
+  };
+
+  const opaqueDirectory = {
+    // for await also iterates a sync iterable.
+    values: function* () {
+      yield { kind: "directory" };
+      for (const errorNames of state.poolFiles ?? [])
+        yield {
+          kind: "file",
+          createSyncAccessHandle: () => {
+            const errorName = errorNames.shift();
+            if (errorName !== undefined)
+              return Promise.reject(new DOMException("Held", errorName));
+            state.openedAccessHandleCount += 1;
+            return Promise.resolve({
+              close: () => {
+                state.closedAccessHandleCount += 1;
+              },
+            });
+          },
+        };
+    },
+  };
+
+  const poolDirectory = {
+    getDirectoryHandle: (name: string) => {
+      state.directoryNames.push(name);
+      return state.hasOpaqueDirectory
+        ? Promise.resolve(opaqueDirectory)
+        : Promise.reject(new DOMException("Missing", "NotFoundError"));
+    },
+  };
+
+  const root = {
+    getDirectoryHandle: (name: string) => {
+      state.directoryNames.push(name);
+      return state.poolFiles
+        ? Promise.resolve(poolDirectory)
+        : Promise.reject(new DOMException("Missing", "NotFoundError"));
+    },
+  };
+
+  Object.defineProperty(navigator, "storage", {
+    configurable: true,
+    value: {
+      getDirectory: () => {
+        state.getDirectoryCount += 1;
+        return Promise.resolve(root);
+      },
+    },
+  });
+
+  return {
+    reset: (
+      poolFiles: Array<Array<string>> | null = null,
+      { hasOpaqueDirectory = true } = {},
+    ) => {
+      state.closedAccessHandleCount = 0;
+      state.directoryNames.length = 0;
+      state.getDirectoryCount = 0;
+      state.hasOpaqueDirectory = hasOpaqueDirectory;
+      state.openedAccessHandleCount = 0;
+      state.poolFiles = poolFiles;
+    },
+    state,
+  };
+})();
+
+// Lets resolved mocks settle before test time advances.
+const flushMicrotasks = (): Promise<void> =>
+  new Promise((resolve) => {
+    setImmediate(resolve);
+  });
+
 const sqliteMock = (() => {
   class PreparedStatement {
     finalized = false;
@@ -29,10 +117,6 @@ const sqliteMock = (() => {
       return { data: "prepared" };
     }
 
-    reset(): void {
-      this.resetCount += 1;
-    }
-
     finalize(): void {
       this.finalized = true;
     }
@@ -105,6 +189,10 @@ const sqliteMock = (() => {
   const sqlite3 = {
     capi: {
       sqlite3_js_db_export: mock.fn(() => new Uint8Array([1, 2, 3])),
+      sqlite3_reset: mock.fn((statement: PreparedStatement) => {
+        statement.resetCount += 1;
+        return 0;
+      }),
       sqlite3mc_vfs_create: mock.fn(),
     },
     installOpfsSAHPoolVfs: mock.fn(() => Promise.resolve(pool)),
@@ -115,6 +203,7 @@ const sqliteMock = (() => {
     consoleWarn: mock.fn<typeof console.warn>(),
     pool,
     reset: () => {
+      opfsMock.reset();
       state.closedDatabases.length = 0;
       state.createdDatabases.length = 0;
       state.deletedFilenames.length = 0;
@@ -128,6 +217,7 @@ const sqliteMock = (() => {
       pool.unpauseVfs.mock.resetCalls();
       pool.unlink.mock.resetCalls();
       sqlite3.capi.sqlite3_js_db_export.mock.resetCalls();
+      sqlite3.capi.sqlite3_reset.mock.resetCalls();
       sqlite3.capi.sqlite3mc_vfs_create.mock.resetCalls();
       sqlite3.installOpfsSAHPoolVfs.mock.resetCalls();
     },
@@ -193,6 +283,7 @@ describe("createWasmSqliteDriver coverage helpers", () => {
 
     assertEqual(sqliteMock.sqlite3.installOpfsSAHPoolVfs.mock.callCount(), 0);
     assertEqual(sqliteMock.state.createdDatabases[0]?.filename, ":memory:");
+    assertEqual(opfsMock.state.getDirectoryCount, 0);
   });
 
   it("executes non-prepared query and exports database", async () => {
@@ -354,3 +445,89 @@ describe("createWasmSqliteDriver coverage helpers", () => {
     );
   });
 });
+
+describe("createWasmSqliteDriver held pool files", () => {
+  for (const errorName of ["InvalidStateError", "NoModificationAllowedError"])
+    it(`sets up the pool once a file held with ${errorName} is released`, async () => {
+      sqliteMock.reset();
+      opfsMock.reset([[], [errorName, errorName]]);
+
+      await using run = testCreateRun();
+      const driver = run.ok(createWasmSqliteDriver(Name.orThrow("MockPlain")));
+      await flushMicrotasks();
+
+      assertEqual(opfsMock.state.directoryNames, [".MockPlain", ".opaque"]);
+      run.deps.time.advance("49ms");
+      await flushMicrotasks();
+      assertEqual(sqliteMock.sqlite3.installOpfsSAHPoolVfs.mock.callCount(), 0);
+
+      // The retry delay doubles after each held pass.
+      run.deps.time.advance("1ms");
+      await flushMicrotasks();
+      run.deps.time.advance("99ms");
+      await flushMicrotasks();
+      assertEqual(sqliteMock.sqlite3.installOpfsSAHPoolVfs.mock.callCount(), 0);
+
+      run.deps.time.advance("1ms");
+      using _driver = await driver;
+
+      // The free file opens on each of the three passes, the held one once.
+      assertEqual(sqliteMock.sqlite3.installOpfsSAHPoolVfs.mock.callCount(), 1);
+      assertEqual(opfsMock.state.openedAccessHandleCount, 4);
+      assertEqual(opfsMock.state.closedAccessHandleCount, 4);
+    });
+
+  it("sets up the pool at once when its directory has no files yet", async () => {
+    sqliteMock.reset();
+    opfsMock.reset([], { hasOpaqueDirectory: false });
+
+    await using run = testCreateRun();
+    using _driver = await run.ok(
+      createWasmSqliteDriver(Name.orThrow("MockPlain")),
+    );
+
+    assertEqual(opfsMock.state.directoryNames, [".MockPlain", ".opaque"]);
+    assertEqual(opfsMock.state.openedAccessHandleCount, 0);
+    assertEqual(sqliteMock.sqlite3.installOpfsSAHPoolVfs.mock.callCount(), 1);
+  });
+
+  it("warns once when pool files stay held for five seconds", async () => {
+    sqliteMock.reset();
+    opfsMock.reset([Array.from({ length: 12 }, () => "InvalidStateError")]);
+
+    await using run = testCreateRun();
+    const driver = run.ok(createWasmSqliteDriver(Name.orThrow("MockPlain")));
+    for (let second = 0; second < 12; second += 1) {
+      await flushMicrotasks();
+      run.deps.time.advance("1s");
+    }
+    using _driver = await driver;
+
+    const warnings = run.deps.console
+      .getEntriesSnapshot()
+      .filter((entry) => entry.method === "warn");
+    assertEqual(
+      warnings.map((entry) => entry.args),
+      [
+        [
+          "Waiting for an ended DbWorker to release the files of database MockPlain.",
+        ],
+      ],
+    );
+  });
+
+  it("fails before setting up the pool when a file cannot be opened", async () => {
+    sqliteMock.reset();
+    opfsMock.reset([["UnknownError"]]);
+
+    await using run = testCreateRun();
+    const result = await run.abortable(
+      createWasmSqliteDriver(Name.orThrow("MockPlain")),
+    );
+
+    assert(!result.ok, "Expected the driver to fail.");
+    assertType(AbortError, result.error);
+    assertSame(result.error.reason.type, "PanicAbortReason");
+    assertEqual(sqliteMock.sqlite3.installOpfsSAHPoolVfs.mock.callCount(), 0);
+  });
+});

package/src/Sqlite.ts

@@ -4,6 +4,10 @@ import {
   createPreparedStatementsCache,
   exhaustiveCheck,
   ok,
+  performanceDurationBetween,
+  PositiveMillis,
+  sleep,
+  tryAsync,
 } from "@evolu/common";
 import sqlite3InitModule, {
   type Database,
@@ -32,7 +36,7 @@ const sqlite3Promise = sqlite3InitModule();
 const fileName = "evolu1.db";
 
 export const createWasmSqliteDriver: CreateSqliteDriver =
-  (name, options) => async () => {
+  (name, options) => async (run) => {
     const sqlite3 = await sqlite3Promise;
 
     using disposer = new DisposableStack();
@@ -45,6 +49,69 @@ export const createWasmSqliteDriver: CreateSqliteDriver =
     const createOpfsSAHPoolVfs = async (
       options: Parameters<typeof sqlite3.installOpfsSAHPoolVfs>[0],
     ): Promise<SAHPoolUtil> => {
+      // Evolu opens a database only while it holds the database lock, but a
+      // DbWorker that ended without closing it, because its tab closed,
+      // crashed or navigated away, can hold pool files after the lock has
+      // passed on: WebKit releases a terminated worker's locks and its files
+      // separately, in no set order. sqlite-wasm cannot set up a pool with a
+      // held file, and it then deletes the pool directory, which the held file
+      // usually but not always prevents. Only a worker that has ended can hold
+      // the files, and it can only release them, so the pool is set up once
+      // every file opens.
+      const canOpenPoolFiles = async (): Promise<boolean> => {
+        const root = await navigator.storage.getDirectory();
+        // sqlite-wasm keeps the pool in `.${name}/.opaque` in both OPFS modes.
+        const poolDirectory = await tryAsync(() =>
+          root.getDirectoryHandle(`.${name}`),
+        );
+        if (!poolDirectory.ok) return true;
+        const opaqueDirectory = await tryAsync(() =>
+          poolDirectory.value.getDirectoryHandle(".opaque"),
+        );
+        if (!opaqueDirectory.ok) return true;
+        for await (const handle of opaqueDirectory.value.values()) {
+          if (handle.kind !== "file") continue;
+          const accessHandle = await tryAsync(() =>
+            handle.createSyncAccessHandle(),
+          );
+          if (!accessHandle.ok) {
+            // WebKit rejects a held file with InvalidStateError, other
+            // engines with NoModificationAllowedError, as the spec says.
+            // WebKit also uses InvalidStateError for a closed or invalid
+            // handle and a stopped context. A retry opens fresh handles from
+            // a new listing, and a stopped context ends the loop with its
+            // worker, so retrying those is harmless.
+            if (
+              accessHandle.error instanceof DOMException &&
+              (accessHandle.error.name === "InvalidStateError" ||
+                accessHandle.error.name === "NoModificationAllowedError")
+            )
+              return false;
+            throw accessHandle.error;
+          }
+          accessHandle.value.close();
+        }
+        return true;
+      };
+
+      const waitStart = run.deps.time.performance.now();
+      let retryDelay = 50;
+      let isWaitReported = false;
+      while (!(await canOpenPoolFiles())) {
+        const waited = performanceDurationBetween(
+          waitStart,
+          run.deps.time.performance.now(),
+        );
+        if (!isWaitReported && waited >= 5000) {
+          isWaitReported = true;
+          run.deps.console.warn(
+            `Waiting for an ended DbWorker to release the files of database ${name}.`,
+          );
+        }
+        await run.ok(sleep(PositiveMillis.orThrow(retryDelay)));
+        retryDelay = Math.min(retryDelay * 2, 1000);
+      }
+
       const pool = await sqlite3.installOpfsSAHPoolVfs(options);
       if (pool.isPaused()) await pool.unpauseVfs();
       disposer.defer(() => {
@@ -111,18 +178,24 @@ export const createWasmSqliteDriver: CreateSqliteDriver =
         const prepared = cache.get(query);
 
         if (prepared) {
-          if (query.parameters.length > 0) prepared.bind(query.parameters);
-
-          const rows = [];
-          while (prepared.step()) {
-            rows.push(prepared.get({}));
+          try {
+            if (query.parameters.length > 0) prepared.bind(query.parameters);
+
+            const rows = [];
+            while (prepared.step()) {
+              rows.push(prepared.get({}));
+            }
+
+            return {
+              rows: rows as ReadonlyArray<SqliteRow>,
+              changes: db.changes(),
+            };
+          } finally {
+            // SQLite refuses to bind a statement whose step failed until it is
+            // reset. That reset returns the step's error again, which
+            // PreparedStatement.reset would throw over the original one.
+            sqlite3.capi.sqlite3_reset(prepared);
           }
-          prepared.reset();
-
-          return {
-            rows: rows as ReadonlyArray<SqliteRow>,
-            changes: db.changes(),
-          };
         }
 
         const rows = db.exec(query.sql, {

package/src/Task.test.ts

@@ -1,14 +1,9 @@
-import {
-  assertEqual,
-  assertNonNullable,
-  assertTrue,
-  testStubGlobal,
-} from "@evolu/common";
+import { assertEqual, assertSame, testStubGlobal } from "@evolu/common";
 import { describe, it, mock } from "node:test";
 import { createRun } from "./Task.ts";
 
 describe("createRun", () => {
-  it("createRun reports defects with global reportError", async () => {
+  it("createRun reports a panic's defect with global reportError", async () => {
     const reportError = mock.fn<(error: unknown) => void>();
     using _reportError = testStubGlobal("reportError", reportError);
     await using run = createRun();
@@ -17,13 +12,7 @@ describe("createRun", () => {
     run.panic(defect);
 
     assertEqual(reportError.mock.callCount(), 1);
-    const reported = reportError.mock.calls[0]?.arguments[0];
-    assertNonNullable(reported);
-    assertTrue(typeof reported === "object");
-    assertEqual(Reflect.get(reported, "reason"), {
-      type: "PanicAbortReason",
-      defect,
-    });
+    assertSame(reportError.mock.calls[0]?.arguments[0], defect);
   });
 
   it("createRun preserves a custom reportDefect", async () => {

package/src/Task.ts

@@ -6,6 +6,7 @@
 
 import {
   createRun as createCommonRun,
+  defectToError,
   type DisposableRun,
   type Run,
   type RunCustomDeps,
@@ -14,13 +15,16 @@ import {
 /**
  * Creates a root {@link Run} for the browser.
  *
- * Defects are reported with the browser's global `reportError`. A custom
- * `reportDefect` dependency overrides the browser default.
+ * Defects are reported with the browser's global `reportError` as an `Error`
+ * from {@link defectToError}, because browsers show any other value only as
+ * unhelpful text. A custom `reportDefect` dependency overrides the browser
+ * default.
  *
  * ### Example
  *
  * ```ts
  * import {
+ *   assertEqual,
  *   createConsole,
  *   createConsoleFormatter,
  *   ok,
@@ -36,7 +40,7 @@ import {
  * await using run = createRun({ console });
  * const appPromise = run.ok(() => ok("started"));
  *
- * expect(await appPromise).toBe("started");
+ * assertEqual(await appPromise, "started");
  * ```
  */
 export function createRun(): DisposableRun;
@@ -49,7 +53,7 @@ export function createRun<D extends object>(
   deps?: RunCustomDeps<D>,
 ): DisposableRun | DisposableRun<D> {
   const reportDefect = (reported: unknown): void => {
-    reportError(reported);
+    reportError(defectToError(reported));
   };
 
   return deps === undefined

package/src/Worker.test.ts

@@ -1,5 +1,7 @@
 import {
   assertEqual,
+  assertFalse,
+  assertLength,
   assertNonNullable,
   assertSame,
   assertThrowsInstanceOf,
@@ -9,6 +11,7 @@ import {
 } from "@evolu/common";
 import { describe, it, mock, test } from "node:test";
 import {
+  addUncaughtErrorListener,
   createBroadcastChannel,
   createOneTabSharedWorkerSelfPolyfill,
   createMessageChannel,
@@ -450,6 +453,62 @@ test("createSharedWorkerSelf asserts when a connection arrives before onConnect
   );
 });
 
+describe("addUncaughtErrorListener", () => {
+  const dispatch = (
+    scope: EventTarget,
+    type: "error" | "unhandledrejection",
+    fields: object,
+  ): Event => {
+    const event = Object.assign(new Event(type, { cancelable: true }), fields);
+    scope.dispatchEvent(event);
+    return event;
+  };
+
+  it("passes uncaught errors and unhandled rejections without canceling them", () => {
+    const scope = new EventTarget();
+    const listener = mock.fn<(error: Error) => void>();
+    using _listener = addUncaughtErrorListener(scope, listener);
+    const error = new Error("uncaught");
+    const reason = new Error("rejected");
+
+    const errorEvent = dispatch(scope, "error", { error });
+    const rejectionEvent = dispatch(scope, "unhandledrejection", { reason });
+
+    const errors = listener.mock.calls.map((call) => call.arguments[0]);
+    assertLength(errors, 2);
+    assertSame(errors[0], error);
+    assertSame(errors[1], reason);
+    assertFalse(errorEvent.defaultPrevented);
+    assertFalse(rejectionEvent.defaultPrevented);
+  });
+
+  it("passes a thrown non-Error as an Error", () => {
+    const scope = new EventTarget();
+    const listener = mock.fn<(error: Error) => void>();
+    using _listener = addUncaughtErrorListener(scope, listener);
+
+    dispatch(scope, "error", { error: null });
+    dispatch(scope, "unhandledrejection", { reason: "rejected" });
+
+    assertEqual(
+      listener.mock.calls.map((call) => call.arguments[0].message),
+      ["Defect: null", 'Defect: "rejected"'],
+    );
+  });
+
+  it("stops passing errors after disposal", () => {
+    const scope = new EventTarget();
+    const listener = mock.fn<(error: Error) => void>();
+    const uncaughtErrorListener = addUncaughtErrorListener(scope, listener);
+
+    uncaughtErrorListener[Symbol.dispose]();
+    dispatch(scope, "error", { error: new Error("uncaught") });
+    dispatch(scope, "unhandledrejection", { reason: new Error("rejected") });
+
+    assertSame(listener.mock.callCount(), 0);
+  });
+});
+
 test("createWorkerDeps stores console output entries and exposes createMessagePort", () => {
   const deps = createWorkerDeps();
 

package/src/Worker.ts

@@ -18,8 +18,10 @@ import {
   assertNonNullable,
   createConsole,
   createConsoleStoreOutput,
+  defectToError,
   disposable,
 } from "@evolu/common";
+import type { createRun } from "./Task.ts";
 
 /** Creates a {@link Worker} from a Web Worker. */
 export const createWorker = <Input, Output>(
@@ -159,7 +161,9 @@ export const createWorkerSelf = <Input, Output = never>(
  * Creates an Evolu {@link SharedWorkerSelf} from a Web `SharedWorkerGlobalScope`
  * (`self` inside a shared worker).
  *
- * Disposing closes the shared worker scope for all connected clients.
+ * Disposing closes the shared worker scope for all connected clients. Browsers
+ * never pass a shared worker's uncaught errors to its pages; see
+ * {@link addUncaughtErrorListener}.
  */
 export const createSharedWorkerSelf = <Input, Output = never>(
   nativeSelf: SharedWorkerGlobalScope,
@@ -271,6 +275,67 @@ export const createOneTabSharedWorkerSelfPolyfill = <Input, Output = never>(
   };
 };
 
+/**
+ * Passes each uncaught error and unhandled rejection of a worker global scope
+ * to `listener` as an `Error` from {@link defectToError}.
+ *
+ * Browsers never pass a shared worker's uncaught errors to a page's error
+ * handlers, and no worker passes its unhandled rejections to its page. A shared
+ * worker calls this with its global scope, `self`, to send them to its pages,
+ * for example over a BroadcastChannel. Defects of a Run from {@link createRun}
+ * arrive too, because it reports them with `reportError`, which dispatches
+ * "error" on the global scope.
+ *
+ * The events stay uncanceled, so the browser still logs them, and a dedicated
+ * worker still passes its uncaught errors to its page. The listeners stay until
+ * disposal, so they also receive errors after a Run's panic.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertEqual } from "@evolu/common";
+ * import { addUncaughtErrorListener } from "@evolu/web";
+ *
+ * const messages: Array<string> = [];
+ * // A worker passes its global scope, `self`.
+ * const scope = new EventTarget();
+ * using _listener = addUncaughtErrorListener(scope, (error) => {
+ *   messages.push(error.message);
+ * });
+ *
+ * scope.dispatchEvent(
+ *   Object.assign(new Event("error"), { error: new Error("unexpected") }),
+ * );
+ * assertEqual(messages, ["unexpected"]);
+ * ```
+ */
+export const addUncaughtErrorListener = (
+  scope: EventTarget,
+  listener: (error: Error) => void,
+): Disposable => {
+  using disposer = new DisposableStack();
+  const { signal } = disposer.adopt(new AbortController(), (controller) => {
+    controller.abort();
+  });
+
+  scope.addEventListener(
+    "error",
+    (event) => {
+      listener(defectToError((event as ErrorEvent).error));
+    },
+    { signal },
+  );
+  scope.addEventListener(
+    "unhandledrejection",
+    (event) => {
+      listener(defectToError((event as PromiseRejectionEvent).reason));
+    },
+    { signal },
+  );
+
+  return disposable({}, disposer);
+};
+
 /** Creates deps shared by web worker entry points. */
 export const createWorkerDeps = (): WorkerDeps &
   CreateBroadcastChannelDep &