@evolu/web 3.1.2 → 3.3.0

package/dist/src/local-first/Evolu.js

@@ -1,57 +1,343 @@
-import { exhaustiveCheck } from "@evolu/common";
-import { createEvoluDeps as createCommonEvoluDeps } from "@evolu/common/local-first";
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { exhaustiveCheck, trySync, } from "@evolu/common";
+import { BuildWaiting, BuildWaitingRequest, buildsBroadcastChannelName, createEvoluDeps as createCommonEvoluDeps, } from "@evolu/common/local-first";
 import { reloadApp } from "../Platform.js";
 import { createBroadcastChannel, createMessageChannel, createSharedWorker, createWorker, installOneTabSharedWorkerPolyfill, } from "../Worker.js";
-/** Creates Evolu dependencies for the web platform. */
+/**
+ * Creates Evolu dependencies for the web platform.
+ *
+ * When another build of the app waits for this one, this tab reloads to load
+ * the build the server now serves: at once if the user is not in the tab,
+ * otherwise once they leave it. See Builds in the Shared module of
+ * `@evolu/common`. A tab whose database refuses to start with
+ * {@link UnsupportedDbVersionError} reloads once for each stored version, even
+ * while the user is in it, because the server may now serve a build that
+ * supports the database. The error is reported when the reloaded build refuses
+ * it too, or when the tab has no session storage. A tab whose worker was
+ * relaunched without its state, as WebKit does when the process hosting it
+ * ends, also reloads at once.
+ *
+ * When the page enters the browser's back-forward cache, as Safari does on
+ * every navigation away, this tab ends its part as if it closed: it stops the
+ * database workers it hosts, so another tab takes them over, and it reloads if
+ * the user comes back to it.
+ *
+ * Where the browser offers no persistent storage, as in Safari's Private
+ * Browsing, the database is kept in memory, and
+ * {@link StorageUnavailableDep.onStorageUnavailable} lets the app tell the
+ * user.
+ *
+ * A custom {@link ReloadApp} replaces the default page reload, for example to
+ * save state first. It should end by reloading the page, because the other
+ * build waits until this tab reloads or closes, and a page restored from the
+ * back-forward cache cannot work until it reloads.
+ */
 export const createEvoluDeps = (deps = {}) => {
-    installOneTabSharedWorkerPolyfill();
-    const createDbWorker = () => createWorker(new Worker(new URL("Db.worker.js", import.meta.url), {
-        type: "module",
-    }));
-    const webSharedWorker = createSharedWorker(new SharedWorker(new URL("Shared.worker.js", import.meta.url), {
-        type: "module",
-    }));
-    let onSharedWorkerMessage = null;
-    const sharedWorker = {
-        ...webSharedWorker,
-        port: {
-            ...webSharedWorker.port,
-            get onMessage() {
-                return onSharedWorkerMessage;
-            },
-            set onMessage(fn) {
-                onSharedWorkerMessage = fn;
-                webSharedWorker.port.onMessage = fn
-                    ? (message) => {
-                        switch (message.type) {
-                            case "DbWorkerInit": {
-                                fn(message);
-                                break;
-                            }
-                            case "SharedWorkerUnsupported": {
-                                if (deps.onSharedWorkerUnsupported) {
-                                    deps.onSharedWorkerUnsupported();
-                                }
-                                else {
-                                    alert("This browser supports Evolu in one tab only. Close this tab and use the already open tab.");
-                                }
-                                break;
-                            }
-                            default:
-                                exhaustiveCheck(message);
-                        }
+    const env_1 = { stack: [], error: void 0, hasError: false };
+    try {
+        installOneTabSharedWorkerPolyfill();
+        const reloadThisApp = deps.reloadApp ?? reloadApp;
+        // A page an automatic reload loaded never announces its build, so two builds
+        // cannot keep reloading each other.
+        const isAutomaticReload = takeAutomaticReload();
+        // Waiting workers this tab already reloaded for. A reload that loaded the
+        // running build again did not help, so the tab does not repeat it.
+        const reloadedForWorkerIds = getReloadedForWorkerIds();
+        // Versions a refusal already reloaded this tab for, read once, so every
+        // refusal before this page unloads reloads it.
+        const refusalReloadVersions = getRefusalReloadVersions();
+        let connectedWorkerId = null;
+        let waitingWorkerId = null;
+        // Workers announced before this tab connected. The lock can pass to this
+        // tab's worker first, and their tabs may not answer a request, for example
+        // when frozen, so the tab handles them once it connects.
+        const earlyAnnouncedWorkerIds = new Set();
+        // Checks whether the user left this tab while another build waits.
+        let focusCheckId = null;
+        const disposer = __addDisposableResource(env_1, new DisposableStack(), false);
+        const buildsBroadcastChannel = disposer.use(createBroadcastChannel(buildsBroadcastChannelName));
+        const stopFocusCheck = () => {
+            if (focusCheckId === null)
+                return;
+            clearInterval(focusCheckId);
+            focusCheckId = null;
+        };
+        disposer.defer(stopFocusCheck);
+        const announceWaitingBuild = () => {
+            if (waitingWorkerId === null || isAutomaticReload)
+                return;
+            buildsBroadcastChannel.postMessage({
+                type: "BuildWaiting",
+                workerId: waitingWorkerId,
+            });
+        };
+        const reloadForWaitingBuild = (workerId) => {
+            stopFocusCheck();
+            // Without session storage, the reloaded page could announce in turn.
+            if (!markAutomaticReload(workerId))
+                return;
+            reloadThisApp();
+        };
+        const handleWaitingBuild = (workerId) => {
+            if (workerId === connectedWorkerId || reloadedForWorkerIds.has(workerId)) {
+                return;
+            }
+            if (!document.hasFocus()) {
+                reloadForWaitingBuild(workerId);
+                return;
+            }
+            // Focus can leave the page from a frame without a window event.
+            focusCheckId ??= setInterval(() => {
+                if (!document.hasFocus())
+                    reloadForWaitingBuild(workerId);
+            }, 1000);
+        };
+        // Builds of different releases share the channel, so messages are validated.
+        buildsBroadcastChannel.onMessage = (message) => {
+            if (BuildWaitingRequest.is(message)) {
+                announceWaitingBuild();
+            }
+            else if (BuildWaiting.is(message)) {
+                if (connectedWorkerId === null) {
+                    earlyAnnouncedWorkerIds.add(message.workerId);
+                }
+                else
+                    handleWaitingBuild(message.workerId);
+            }
+        };
+        const handleSharedWorkerMessage = (message, forward) => {
+            // WebKit can relaunch a SharedWorker without its state when the process
+            // hosting it ends, and connect the tabs' existing ports to the new worker
+            // (https://bugs.webkit.org/show_bug.cgi?id=318873). A worker tells a tab
+            // at most once that it waits and once that it connected, both with its own
+            // id, so only then does a tab hear from a worker with another id. The
+            // tab's state, including the databases it asked for while it waited, ended
+            // with the old worker, so it reloads at once.
+            const knownWorkerId = connectedWorkerId ?? waitingWorkerId;
+            if ((message.type === "Waiting" || message.type === "Connected") &&
+                knownWorkerId !== null &&
+                message.workerId !== knownWorkerId) {
+                reloadThisApp();
+                return;
+            }
+            switch (message.type) {
+                case "DbWorkerInit": {
+                    forward(message);
+                    break;
+                }
+                case "Error": {
+                    // The page is about to reload, so the error is not reported.
+                    if (message.error.type === "UnsupportedDbVersionError" &&
+                        !refusalReloadVersions.has(String(message.error.storedVersion)) &&
+                        markRefusalReload(message.error)) {
+                        reloadThisApp();
+                        break;
+                    }
+                    forward(message);
+                    break;
+                }
+                case "Waiting": {
+                    waitingWorkerId = message.workerId;
+                    announceWaitingBuild();
+                    forward(message);
+                    break;
+                }
+                case "Connected": {
+                    waitingWorkerId = null;
+                    connectedWorkerId = message.workerId;
+                    forward(message);
+                    for (const workerId of earlyAnnouncedWorkerIds) {
+                        handleWaitingBuild(workerId);
+                    }
+                    // An announcement may have come before this tab started.
+                    buildsBroadcastChannel.postMessage({
+                        type: "BuildWaitingRequest",
+                    });
+                    break;
+                }
+                case "StorageUnavailable": {
+                    deps.onStorageUnavailable?.();
+                    forward(message);
+                    break;
+                }
+                case "SharedWorkerUnsupported": {
+                    if (deps.onSharedWorkerUnsupported) {
+                        deps.onSharedWorkerUnsupported();
                     }
-                    : null;
+                    else {
+                        alert("This browser supports Evolu in one tab only. Close this tab and use the already open tab.");
+                    }
+                    break;
+                }
+                default:
+                    exhaustiveCheck(message);
+            }
+        };
+        // Disposing the deps ends the DbWorkers this tab hosts, which releases their
+        // database locks for the tab that takes over.
+        const dbWorkers = new Set();
+        disposer.defer(() => {
+            for (const dbWorker of dbWorkers)
+                dbWorker[Symbol.dispose]();
+        });
+        const createDbWorker = () => {
+            const dbWorker = createWorker(new Worker(new URL("Db.worker.js", import.meta.url), {
+                type: "module",
+            }));
+            dbWorkers.add(dbWorker);
+            return dbWorker;
+        };
+        const webSharedWorker = createSharedWorker(new SharedWorker(new URL("Shared.worker.js", import.meta.url), {
+            type: "module",
+        }));
+        let onSharedWorkerMessage = null;
+        const sharedWorker = {
+            ...webSharedWorker,
+            port: {
+                ...webSharedWorker.port,
+                get onMessage() {
+                    return onSharedWorkerMessage;
+                },
+                set onMessage(fn) {
+                    onSharedWorkerMessage = fn;
+                    webSharedWorker.port.onMessage = fn
+                        ? (message) => {
+                            handleSharedWorkerMessage(message, fn);
+                        }
+                        : null;
+                },
             },
-        },
-    };
-    return createCommonEvoluDeps({
-        ...deps,
-        createDbWorker,
-        createBroadcastChannel,
-        createMessageChannel,
-        lockManager: navigator.locks,
-        reloadApp,
-        sharedWorker,
+        };
+        const evoluDeps = disposer.use(createCommonEvoluDeps({
+            ...deps,
+            createDbWorker,
+            createBroadcastChannel,
+            createMessageChannel,
+            lockManager: navigator.locks,
+            reloadApp: reloadThisApp,
+            sharedWorker,
+        }));
+        // A page entering the back-forward cache is frozen with its DbWorkers, which
+        // keep their database locks, so the other tabs would stall. WebKit also
+        // releases the page's own locks, so a restored page would work with state
+        // the other tabs gave up on. The page therefore ends its part as if it
+        // closed, and reloads when it is shown again.
+        const reloadRestoredPage = (event) => {
+            if (event.persisted)
+                reloadThisApp();
+        };
+        const handlePageHide = (event) => {
+            if (!event.persisted)
+                return;
+            addEventListener("pageshow", reloadRestoredPage, { once: true });
+            disposables.dispose();
+        };
+        addEventListener("pagehide", handlePageHide);
+        disposer.defer(() => {
+            removeEventListener("pagehide", handlePageHide);
+        });
+        const disposables = disposer.move();
+        return {
+            ...evoluDeps,
+            [Symbol.dispose]: () => {
+                disposables.dispose();
+            },
+        };
+    }
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
+    }
+    finally {
+        __disposeResources(env_1);
+    }
+};
+// Marks, for the tab's session, that Evolu reloaded the page for another build.
+const automaticReloadKey = "evolu:automatic-reload";
+// Holds, for the tab's session, every waiting worker Evolu reloaded it for.
+const reloadedForKey = "evolu:reloaded-for";
+// Removes the mark, so only the page the reload loaded sees it.
+const takeAutomaticReload = () => {
+    const item = trySync(() => {
+        const value = sessionStorage.getItem(automaticReloadKey);
+        sessionStorage.removeItem(automaticReloadKey);
+        return value;
     });
+    return item.ok && item.value !== null;
+};
+const getReloadedForWorkerIds = () => {
+    const item = trySync(() => sessionStorage.getItem(reloadedForKey));
+    return new Set(item.ok && item.value !== null ? item.value.split(",") : []);
+};
+const markAutomaticReload = (workerId) => trySync(() => {
+    const workerIds = new Set(sessionStorage.getItem(reloadedForKey)?.split(","));
+    workerIds.add(workerId);
+    sessionStorage.setItem(reloadedForKey, [...workerIds].join(","));
+    sessionStorage.setItem(automaticReloadKey, "1");
+}).ok;
+// Holds, for the tab's session, every stored database version a refusal
+// reloaded the page for. Each version reloads it once, so refusals of several
+// databases cannot keep reloading it, and a build that refuses them again
+// reports the error instead.
+const refusalReloadKey = "evolu:refusal-reloads";
+const getRefusalReloadVersions = () => {
+    const item = trySync(() => sessionStorage.getItem(refusalReloadKey));
+    return new Set(item.ok && item.value !== null ? item.value.split(",") : []);
 };
+// Adds to the stored versions, which include those marked earlier in this page.
+const markRefusalReload = (error) => trySync(() => {
+    const versions = new Set(sessionStorage.getItem(refusalReloadKey)?.split(","));
+    versions.add(String(error.storedVersion));
+    sessionStorage.setItem(refusalReloadKey, [...versions].join(","));
+}).ok;

package/dist/src/local-first/Shared.worker.js

@@ -53,13 +53,21 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
 /// <reference lib="webworker" />
 import { installPolyfills } from "@evolu/common/polyfills";
 installPolyfills();
-import { createWebSocket, ok, waitForAbort } from "@evolu/common";
-import { initSharedWorker } from "@evolu/common/local-first";
+import { createUnknownError, createWebSocket, ok, tryAsync, waitForAbort, } from "@evolu/common";
+import { consoleEntryOrErrorBroadcastChannelName, initSharedWorker, } from "@evolu/common/local-first";
 import { createRun } from "../Task.js";
-import { createOneTabSharedWorkerSelfPolyfill, createSharedWorkerSelf, createWorkerDeps, } from "../Worker.js";
+import { addUncaughtErrorListener, createBroadcastChannel, createOneTabSharedWorkerSelfPolyfill, createSharedWorkerSelf, createWorkerDeps, } from "../Worker.js";
+const errors = createBroadcastChannel(consoleEntryOrErrorBroadcastChannelName);
+// Each tab logs an uncaught error, including a Run defect, and sets it as its
+// evoluError.
+addUncaughtErrorListener(self, (error) => {
+    errors.postMessage({ type: "Error", error: createUnknownError(error) });
+});
 const run = createRun({
     ...createWorkerDeps(),
     createWebSocket,
+    // Safari's Private Browsing offers no OPFS; see Storage in the Shared module.
+    isPersistentStorageAvailable: async () => (await tryAsync(() => navigator.storage.getDirectory())).ok,
     lockManager: navigator.locks,
 });
 void run(async (run) => {
@@ -68,7 +76,9 @@ void run(async (run) => {
         if ("onconnect" in self) {
             const env_2 = { stack: [], error: void 0, hasError: false };
             try {
-                const _ = __addDisposableResource(env_2, await run.ok(initSharedWorker(createSharedWorkerSelf(self))), true);
+                // A panic closes the worker, so tabs that connect later start another.
+                const workerSelf = __addDisposableResource(env_2, createSharedWorkerSelf(self), false);
+                const _ = __addDisposableResource(env_2, await run.ok(initSharedWorker(workerSelf)), true);
                 return await run(waitForAbort);
             }
             catch (e_1) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolu/web",
-  "version": "3.1.2",
+  "version": "3.3.0",
   "description": "Evolu for web",
   "keywords": [
     "evolu",
@@ -32,11 +32,10 @@
     "README.md"
   ],
   "dependencies": {
-    "@evolu/sqlite-wasm": "2.2.4",
-    "idb-keyval": "^6.2.2"
+    "@evolu/sqlite-wasm": "2.2.4"
   },
   "devDependencies": {
-    "@evolu/common": "8.10.0",
+    "@evolu/common": "8.13.0",
     "@evolu/typescript-config": "0.1.1",
     "@types/node": "^24.10.9",
     "@types/sharedworker": "^0.0.229",
@@ -45,7 +44,7 @@
     "user-agent-data-types": "^0.4.2"
   },
   "peerDependencies": {
-    "@evolu/common": "^8.10.0"
+    "@evolu/common": "^8.13.0"
   },
   "publishConfig": {
     "access": "public"

package/src/Platform.test.ts

@@ -6,8 +6,9 @@ import {
   PositiveInt,
   testStubGlobal,
 } from "@evolu/common";
-import { test } from "node:test";
+import { mock, test } from "node:test";
 import { availableParallelism, isApplePlatform } from "./index.ts";
+import { reloadApp } from "./Platform.ts";
 
 for (const platform of ["macOS", "MacIntel", "iPhone", "iPad", "iPod"]) {
   test(`isApplePlatform recognizes ${platform}`, () => {
@@ -43,3 +44,30 @@ test("availableParallelism returns the validated browser value", () => {
   assertType<typeof parallelism, PositiveInt>();
   assertEqual(parallelism, 128);
 });
+
+test("reloadApp reloads the current page", () => {
+  const reload = mock.fn<() => void>();
+  const replace = mock.fn<(url: string) => void>();
+  using _document = testStubGlobal("document", {});
+  using _location = testStubGlobal("location", { reload, replace });
+
+  reloadApp();
+
+  assertEqual(reload.mock.callCount(), 1);
+  assertEqual(replace.mock.callCount(), 0);
+});
+
+test("reloadApp loads a given URL instead", () => {
+  const reload = mock.fn<() => void>();
+  const replace = mock.fn<(url: string) => void>();
+  using _document = testStubGlobal("document", {});
+  using _location = testStubGlobal("location", { reload, replace });
+
+  reloadApp("/signed-out");
+
+  assertEqual(
+    replace.mock.calls.map((call) => call.arguments),
+    [["/signed-out"]],
+  );
+  assertEqual(reload.mock.callCount(), 0);
+});

package/src/Platform.ts

@@ -16,5 +16,6 @@ export const reloadApp: ReloadApp = (url) => {
     return;
   }
 
-  location.replace(url ?? "/");
+  if (url === undefined) location.reload();
+  else location.replace(url);
 };