@evolu/web 3.3.0 → 3.4.0

package/dist/src/local-first/Evolu.d.ts

@@ -1,27 +1,11 @@
 import { type ConsoleDep, type ReloadAppDep } from "@evolu/common";
-import type { EvoluDeps } from "@evolu/common/local-first";
+import type { EvoluDeps, RequestPersistentStorageDep } from "@evolu/common/local-first";
 export interface SharedWorkerUnsupported {
     readonly type: "SharedWorkerUnsupported";
 }
 export interface SharedWorkerUnsupportedDep {
     readonly onSharedWorkerUnsupported: () => void;
 }
-export interface StorageUnavailableDep {
-    /**
-     * Called when the browser offers no persistent storage, as in Safari's
-     * Private Browsing, so every database is kept in memory. See Storage in the
-     * Shared module of `@evolu/common`.
-     *
-     * The app keeps working. Data synced with a relay comes back, as on a new
-     * device, and nothing stays on the device once the tabs close. That suits
-     * someone checking their app on a borrowed phone, so a message such as
-     * "Nothing from this session is kept on this device." tells the user what to
-     * expect. Data that exists only locally, or has not synced yet, is lost when
-     * the tab hosting the database closes or navigates away, even while other
-     * tabs stay open.
-     */
-    readonly onStorageUnavailable: () => void;
-}
 /**
  * Creates Evolu dependencies for the web platform.
  *
@@ -42,14 +26,25 @@ export interface StorageUnavailableDep {
  * 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.
+ * Browsing or a Firefox private window, the database is kept in memory, and
+ * {@link Evolu.devicePersistence} resolves to `NotPersisted`, so the app can
+ * tell the user. Data that exists only locally, or has not synced yet, is lost
+ * when the tab hosting the database closes or navigates away, even while other
+ * tabs stay open.
+ *
+ * After the first local mutation of a database the browser stores, this tab
+ * asks the browser once with `navigator.storage.persist()` not to delete the
+ * site's data when disk space runs low. Chrome and Safari decide silently, and
+ * Firefox asks the user, so every tab asks until the user allows it. A custom
+ * {@link RequestPersistentStorageDep.requestPersistentStorage} replaces the
+ * request, for example with `constVoid` to never ask. See [Will my data stay on
+ * the
+ * device?](https://www.evolu.dev/docs/faq#will-my-data-stay-on-the-device).
  *
  * 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 declare const createEvoluDeps: (deps?: Partial<ConsoleDep> & Partial<ReloadAppDep> & Partial<SharedWorkerUnsupportedDep> & Partial<StorageUnavailableDep>) => EvoluDeps;
+export declare const createEvoluDeps: (deps?: Partial<ConsoleDep> & Partial<ReloadAppDep> & Partial<SharedWorkerUnsupportedDep> & Partial<RequestPersistentStorageDep>) => EvoluDeps;
 //# sourceMappingURL=Evolu.d.ts.map

package/dist/src/local-first/Evolu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Evolu.d.ts","sourceRoot":"","sources":["../../../src/local-first/Evolu.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,UAAU,EAEf,KAAK,YAAY,EAElB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAIV,SAAS,EAIV,MAAM,2BAA2B,CAAC;AAgBnC,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;CAC1C;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,yBAAyB,EAAE,MAAM,IAAI,CAAC;CAChD;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,oBAAoB,EAAE,MAAM,IAAI,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,eAAe,UACpB,OAAO,CAAC,UAAU,CAAC,GACvB,OAAO,CAAC,YAAY,CAAC,GACrB,OAAO,CAAC,0BAA0B,CAAC,GACnC,OAAO,CAAC,qBAAqB,CAAC,KAC/B,SAiPF,CAAC"}
+{"version":3,"file":"Evolu.d.ts","sourceRoot":"","sources":["../../../src/local-first/Evolu.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,UAAU,EAEf,KAAK,YAAY,EAElB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAKV,SAAS,EACT,2BAA2B,EAI5B,MAAM,2BAA2B,CAAC;AAgBnC,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;CAC1C;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,yBAAyB,EAAE,MAAM,IAAI,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,eAAe,UACpB,OAAO,CAAC,UAAU,CAAC,GACvB,OAAO,CAAC,YAAY,CAAC,GACrB,OAAO,CAAC,0BAA0B,CAAC,GACnC,OAAO,CAAC,2BAA2B,CAAC,KACrC,SAsPF,CAAC"}

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

@@ -50,7 +50,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
-import { exhaustiveCheck, trySync, } from "@evolu/common";
+import { exhaustiveCheck, tryAsync, 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";
@@ -74,9 +74,20 @@ import { createBroadcastChannel, createMessageChannel, createSharedWorker, creat
  * 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.
+ * Browsing or a Firefox private window, the database is kept in memory, and
+ * {@link Evolu.devicePersistence} resolves to `NotPersisted`, so the app can
+ * tell the user. Data that exists only locally, or has not synced yet, is lost
+ * when the tab hosting the database closes or navigates away, even while other
+ * tabs stay open.
+ *
+ * After the first local mutation of a database the browser stores, this tab
+ * asks the browser once with `navigator.storage.persist()` not to delete the
+ * site's data when disk space runs low. Chrome and Safari decide silently, and
+ * Firefox asks the user, so every tab asks until the user allows it. A custom
+ * {@link RequestPersistentStorageDep.requestPersistentStorage} replaces the
+ * request, for example with `constVoid` to never ask. See [Will my data stay on
+ * the
+ * device?](https://www.evolu.dev/docs/faq#will-my-data-stay-on-the-device).
  *
  * 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
@@ -105,6 +116,7 @@ export const createEvoluDeps = (deps = {}) => {
         const earlyAnnouncedWorkerIds = new Set();
         // Checks whether the user left this tab while another build waits.
         let focusCheckId = null;
+        let isPersistentStorageRequested = false;
         const disposer = __addDisposableResource(env_1, new DisposableStack(), false);
         const buildsBroadcastChannel = disposer.use(createBroadcastChannel(buildsBroadcastChannelName));
         const stopFocusCheck = () => {
@@ -206,11 +218,6 @@ export const createEvoluDeps = (deps = {}) => {
                     });
                     break;
                 }
-                case "StorageUnavailable": {
-                    deps.onStorageUnavailable?.();
-                    forward(message);
-                    break;
-                }
                 case "SharedWorkerUnsupported": {
                     if (deps.onSharedWorkerUnsupported) {
                         deps.onSharedWorkerUnsupported();
@@ -259,7 +266,18 @@ export const createEvoluDeps = (deps = {}) => {
                 },
             },
         };
+        const requestPersistentStorage = () => {
+            if (isPersistentStorageRequested)
+                return;
+            isPersistentStorageRequested = true;
+            void tryAsync(async () => {
+                if (await navigator.storage.persisted())
+                    return;
+                await navigator.storage.persist();
+            });
+        };
         const evoluDeps = disposer.use(createCommonEvoluDeps({
+            requestPersistentStorage,
             ...deps,
             createDbWorker,
             createBroadcastChannel,

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

@@ -66,8 +66,12 @@ addUncaughtErrorListener(self, (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,
+    // Safari's Private Browsing and Firefox's private windows offer no OPFS, and
+    // a browser may delete it, as Chrome's incognito does when the session ends;
+    // see Storage in the Shared module.
+    getDevicePersistence: async () => (await tryAsync(() => navigator.storage.getDirectory())).ok
+        ? "Unknown"
+        : "NotPersisted",
     lockManager: navigator.locks,
 });
 void run(async (run) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolu/web",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Evolu for web",
   "keywords": [
     "evolu",
@@ -35,7 +35,7 @@
     "@evolu/sqlite-wasm": "2.2.4"
   },
   "devDependencies": {
-    "@evolu/common": "8.13.0",
+    "@evolu/common": "8.14.0",
     "@evolu/typescript-config": "0.1.1",
     "@types/node": "^24.10.9",
     "@types/sharedworker": "^0.0.229",
@@ -44,7 +44,7 @@
     "user-agent-data-types": "^0.4.2"
   },
   "peerDependencies": {
-    "@evolu/common": "^8.13.0"
+    "@evolu/common": "^8.14.0"
   },
   "publishConfig": {
     "access": "public"

package/src/local-first/Evolu.test.ts

@@ -148,26 +148,59 @@ describe("createEvoluDeps", () => {
     });
   });
 
-  describe("storage unavailable", () => {
-    const workerId = createIdFromString<"SharedWorker">("worker");
+  describe("persistent storage request", () => {
+    const setupStorage = (isPersisted: boolean) => ({
+      persisted: mock.fn(() => Promise.resolve(isPersisted)),
+      persist: mock.fn(() => Promise.resolve(true)),
+    });
 
-    it("tells the app when its worker keeps databases in memory", () => {
-      const onStorageUnavailable = mock.fn<() => void>();
-      using setup = setupWebEvoluDeps({ onStorageUnavailable });
-      setup.connect(workerId);
+    it("asks the browser once to keep the site's data", async () => {
+      const storage = setupStorage(false);
+      using setup = setupWebEvoluDeps({ storage });
 
-      setup.post({ type: "StorageUnavailable" });
+      setup.deps.requestPersistentStorage?.();
+      setup.deps.requestPersistentStorage?.();
+      await waitForMacrotask();
 
-      assertSame(onStorageUnavailable.mock.callCount(), 1);
+      assertSame(storage.persisted.mock.callCount(), 1);
+      assertSame(storage.persist.mock.callCount(), 1);
     });
 
-    it("works without a callback", () => {
-      using setup = setupWebEvoluDeps();
-      setup.connect(workerId);
+    it("does not ask when the site's data is already persistent", async () => {
+      const storage = setupStorage(true);
+      using setup = setupWebEvoluDeps({ storage });
 
-      setup.post({ type: "StorageUnavailable" });
+      setup.deps.requestPersistentStorage?.();
+      await waitForMacrotask();
 
-      assertSame(setup.reloadApp.mock.callCount(), 0);
+      assertSame(storage.persist.mock.callCount(), 0);
+    });
+
+    it("ignores a browser that refuses to answer", async () => {
+      const storage = {
+        persisted: mock.fn(() =>
+          Promise.reject(new TypeError("Storage is disabled.")),
+        ),
+        persist: mock.fn(() => Promise.resolve(true)),
+      };
+      using setup = setupWebEvoluDeps({ storage });
+
+      setup.deps.requestPersistentStorage?.();
+      await waitForMacrotask();
+
+      assertSame(storage.persist.mock.callCount(), 0);
+    });
+
+    it("uses the app's request instead", async () => {
+      const storage = setupStorage(false);
+      const requestPersistentStorage = mock.fn<() => void>();
+      using setup = setupWebEvoluDeps({ storage, requestPersistentStorage });
+
+      setup.deps.requestPersistentStorage?.();
+      await waitForMacrotask();
+
+      assertSame(requestPersistentStorage.mock.callCount(), 1);
+      assertSame(storage.persisted.mock.callCount(), 0);
     });
   });
 
@@ -443,7 +476,8 @@ const setupWebEvoluDeps = ({
   isSessionStorageAvailable = true,
   refusalReloads,
   reloadedFor,
-  onStorageUnavailable,
+  storage,
+  requestPersistentStorage,
 }: {
   hasFocus?: boolean;
   isAutomaticReload?: boolean;
@@ -452,7 +486,9 @@ const setupWebEvoluDeps = ({
   refusalReloads?: string;
   /** The stored waiting workers, as a previous page load left them. */
   reloadedFor?: string;
-  onStorageUnavailable?: () => void;
+  /** Stands in for `navigator.storage`. */
+  storage?: Pick<StorageManager, "persist" | "persisted">;
+  requestPersistentStorage?: () => void;
 } = {}) => {
   using disposer = new DisposableStack();
   const sharedWorkerPort = createClosableNativePort<unknown>();
@@ -539,12 +575,17 @@ const setupWebEvoluDeps = ({
   );
   let hasFocus = initialHasFocus;
   disposer.use(testStubGlobal("document", { hasFocus: () => hasFocus }));
+  if (storage) {
+    disposer.use(
+      testStubGlobal("navigator", { locks: navigator.locks, storage }),
+    );
+  }
   const reloadApp = mock.fn<ReloadApp>();
 
   const deps = createEvoluDeps({
     console: createConsole({ level: "silent" }),
     reloadApp,
-    ...(onStorageUnavailable && { onStorageUnavailable }),
+    ...(requestPersistentStorage && { requestPersistentStorage }),
   });
   const builds = channels.find(
     (channel) => channel.name === buildsBroadcastChannelName,

package/src/local-first/Evolu.ts

@@ -1,5 +1,6 @@
 import {
   exhaustiveCheck,
+  tryAsync,
   trySync,
   type ConsoleDep,
   type ReloadApp,
@@ -10,7 +11,9 @@ import type {
   SharedWorker as CommonSharedWorker,
   CreateDbWorker,
   DbWorkerInit,
+  Evolu,
   EvoluDeps,
+  RequestPersistentStorageDep,
   SharedWorkerId,
   SharedWorkerInput,
   SharedWorkerOutput,
@@ -38,23 +41,6 @@ export interface SharedWorkerUnsupportedDep {
   readonly onSharedWorkerUnsupported: () => void;
 }
 
-export interface StorageUnavailableDep {
-  /**
-   * Called when the browser offers no persistent storage, as in Safari's
-   * Private Browsing, so every database is kept in memory. See Storage in the
-   * Shared module of `@evolu/common`.
-   *
-   * The app keeps working. Data synced with a relay comes back, as on a new
-   * device, and nothing stays on the device once the tabs close. That suits
-   * someone checking their app on a borrowed phone, so a message such as
-   * "Nothing from this session is kept on this device." tells the user what to
-   * expect. Data that exists only locally, or has not synced yet, is lost when
-   * the tab hosting the database closes or navigates away, even while other
-   * tabs stay open.
-   */
-  readonly onStorageUnavailable: () => void;
-}
-
 /**
  * Creates Evolu dependencies for the web platform.
  *
@@ -75,9 +61,20 @@ export interface StorageUnavailableDep {
  * 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.
+ * Browsing or a Firefox private window, the database is kept in memory, and
+ * {@link Evolu.devicePersistence} resolves to `NotPersisted`, so the app can
+ * tell the user. Data that exists only locally, or has not synced yet, is lost
+ * when the tab hosting the database closes or navigates away, even while other
+ * tabs stay open.
+ *
+ * After the first local mutation of a database the browser stores, this tab
+ * asks the browser once with `navigator.storage.persist()` not to delete the
+ * site's data when disk space runs low. Chrome and Safari decide silently, and
+ * Firefox asks the user, so every tab asks until the user allows it. A custom
+ * {@link RequestPersistentStorageDep.requestPersistentStorage} replaces the
+ * request, for example with `constVoid` to never ask. See [Will my data stay on
+ * the
+ * device?](https://www.evolu.dev/docs/faq#will-my-data-stay-on-the-device).
  *
  * 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
@@ -88,7 +85,7 @@ export const createEvoluDeps = (
   deps: Partial<ConsoleDep> &
     Partial<ReloadAppDep> &
     Partial<SharedWorkerUnsupportedDep> &
-    Partial<StorageUnavailableDep> = {},
+    Partial<RequestPersistentStorageDep> = {},
 ): EvoluDeps => {
   installOneTabSharedWorkerPolyfill();
   const reloadThisApp = deps.reloadApp ?? reloadApp;
@@ -110,6 +107,7 @@ export const createEvoluDeps = (
   const earlyAnnouncedWorkerIds = new Set<SharedWorkerId>();
   // Checks whether the user left this tab while another build waits.
   let focusCheckId: ReturnType<typeof setInterval> | null = null;
+  let isPersistentStorageRequested = false;
 
   using disposer = new DisposableStack();
   const buildsBroadcastChannel = disposer.use(
@@ -225,12 +223,6 @@ export const createEvoluDeps = (
         break;
       }
 
-      case "StorageUnavailable": {
-        deps.onStorageUnavailable?.();
-        forward(message);
-        break;
-      }
-
       case "SharedWorkerUnsupported": {
         if (deps.onSharedWorkerUnsupported) {
           deps.onSharedWorkerUnsupported();
@@ -292,8 +284,18 @@ export const createEvoluDeps = (
     },
   };
 
+  const requestPersistentStorage = (): void => {
+    if (isPersistentStorageRequested) return;
+    isPersistentStorageRequested = true;
+    void tryAsync(async () => {
+      if (await navigator.storage.persisted()) return;
+      await navigator.storage.persist();
+    });
+  };
+
   const evoluDeps = disposer.use(
     createCommonEvoluDeps({
+      requestPersistentStorage,
       ...deps,
       createDbWorker,
       createBroadcastChannel,

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

@@ -42,9 +42,13 @@ addUncaughtErrorListener(self, (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,
+  // Safari's Private Browsing and Firefox's private windows offer no OPFS, and
+  // a browser may delete it, as Chrome's incognito does when the session ends;
+  // see Storage in the Shared module.
+  getDevicePersistence: async () =>
+    (await tryAsync(() => navigator.storage.getDirectory())).ok
+      ? "Unknown"
+      : "NotPersisted",
   lockManager: navigator.locks,
 });