@evolu/common 8.13.0 → 8.15.0

package/src/local-first/Evolu.ts

@@ -385,6 +385,37 @@ export interface Evolu<
   /** {@link AppOwner}. */
   readonly appOwner: AppOwner;
 
+  /**
+   * Whether this device keeps the database, resolved once the shared worker
+   * serves it, or `Unknown` if this instance is disposed first.
+   *
+   * Apps tell the user when it is `NotPersisted`, because then data that has
+   * not synced is lost when the database closes. Apps must not tell the user
+   * that data is saved on the device when it is `Unknown`.
+   *
+   * ### Example
+   *
+   * ```ts
+   * import { assertEqual } from "@evolu/common";
+   * import type { DevicePersistence } from "@evolu/common/local-first";
+   *
+   * // The notice for `await evolu.devicePersistence`, or null for none.
+   * const persistenceNotice = (
+   *   devicePersistence: DevicePersistence,
+   * ): string | null =>
+   *   devicePersistence === "NotPersisted"
+   *     ? "Your data isn't kept on this device. Changes that haven't synced are lost when you close this tab."
+   *     : null;
+   *
+   * assertEqual(persistenceNotice("Unknown"), null);
+   * assertEqual(
+   *   persistenceNotice("NotPersisted"),
+   *   "Your data isn't kept on this device. Changes that haven't synced are lost when you close this tab.",
+   * );
+   * ```
+   */
+  readonly devicePersistence: Promise<DevicePersistence>;
+
   /**
    * Inserts a row and returns the generated {@link Id}.
    *
@@ -873,6 +904,28 @@ export interface Evolu<
  */
 export type UnuseOwner = () => void;
 
+/**
+ * Whether this device keeps an {@link Evolu} database, stating only what Evolu
+ * knows for sure.
+ *
+ * - `Persisted`: the platform stores it in the app's own file, as React Native
+ *   does.
+ * - `NotPersisted`: it is kept in memory, because {@link EvoluConfig.memoryOnly}
+ *   asks for that or the platform offers no persistent storage, as a browser
+ *   does in Safari's Private Browsing or a Firefox private window. Data that
+ *   has not synced is lost when the database closes.
+ * - `Unknown`: it is stored, but the platform may delete it. A browser can keep
+ *   storage only for a private session, as Chrome's incognito does without
+ *   telling the app, delete it after a while or when disk space runs low, and
+ *   let the user clear it.
+ *
+ * See [Will my data stay on the
+ * device?](https://www.evolu.dev/docs/faq#will-my-data-stay-on-the-device).
+ *
+ * @group Core
+ */
+export type DevicePersistence = "Persisted" | "NotPersisted" | "Unknown";
+
 /**
  * Represents app-level errors that can occur in {@link Evolu}.
  *
@@ -1125,6 +1178,20 @@ export interface SyncStateDep {
   readonly syncState: ReadonlyStore<SyncState | null>;
 }
 
+/**
+ * Asks the platform to keep stored databases until the user deletes them.
+ *
+ * Only unsynced local changes exist nowhere else, so each {@link Evolu} instance
+ * calls it after its first local mutation, when its
+ * {@link Evolu.devicePersistence} is `Unknown`. A platform provides it when its
+ * storage can be deleted without the user, as a browser's can.
+ *
+ * @group Construction
+ */
+export interface RequestPersistentStorageDep {
+  readonly requestPersistentStorage: () => void;
+}
+
 /**
  * Shared platform dependencies for creating {@link Evolu} instances.
  *
@@ -1143,7 +1210,7 @@ export type EvoluDeps = EvoluPlatformDeps &
  * Platform-specific dependencies required to create {@link EvoluDeps}.
  *
  * Provides worker and channel adapters plus optional platform integrations for
- * logging and synchronous UI flush.
+ * logging, synchronous UI flush, and persistent storage requests.
  *
  * @group Construction
  */
@@ -1154,7 +1221,8 @@ export type EvoluPlatformDeps = CreateDbWorkerDep &
   ReloadAppDep &
   SharedWorkerDep &
   Partial<ConsoleDep> &
-  Partial<FlushSyncDep>;
+  Partial<FlushSyncDep> &
+  Partial<RequestPersistentStorageDep>;
 
 /**
  * Creates shared dependencies used by all {@link createEvolu} instances on a
@@ -1234,9 +1302,7 @@ export const createEvoluDeps = (deps: EvoluPlatformDeps): EvoluDeps => {
         break;
 
       case "Waiting":
-      case "StorageUnavailable":
-        // Platform adapters act on these; see Builds and Storage in the Shared
-        // module.
+        // Platform adapters act on it; see Builds in the Shared module.
         break;
 
       case "Connected": {
@@ -1423,6 +1489,13 @@ export const createEvolu =
       exportDatabasePending = null;
     });
 
+    const devicePersistence = Promise.withResolvers<DevicePersistence>();
+    // A disposed instance never hears from its tenant, so awaiters settle.
+    disposer.defer(() => {
+      devicePersistence.resolve("Unknown");
+    });
+    let isPersistentStorageRequested = false;
+
     let postMessage: (input: EvoluInput) => void;
 
     // Scope worker/channel wiring and keep only postMessage outside.
@@ -1512,6 +1585,10 @@ export const createEvolu =
             break;
           }
 
+          case "OnDevicePersistence":
+            devicePersistence.resolve(message.devicePersistence);
+            break;
+
           default:
             exhaustiveCheck(message);
         }
@@ -1639,6 +1716,18 @@ export const createEvolu =
           );
         }
 
+        // Only unsynced local changes exist nowhere else, so the first one is
+        // when asking the platform to keep them starts to matter. Asking on
+        // load would show Firefox's permission prompt to every visitor.
+        if (!isPersistentStorageRequested) {
+          isPersistentStorageRequested = true;
+          void devicePersistence.promise.then((persistence) => {
+            if (persistence === "Unknown" && !disposed) {
+              run.deps.requestPersistentStorage?.();
+            }
+          });
+        }
+
         mutateBatch.push({
           change: { ...dbChange, ownerId: options?.ownerId ?? appOwner.id },
           onComplete: options?.onComplete,
@@ -1683,8 +1772,14 @@ export const createEvolu =
         "useOwner requires explicit non-empty transports when config.transports is empty.",
       );
 
+      // Post only what workers use. Forwarding the caller's object would copy
+      // an AppOwner's mnemonic into every worker.
+      const { id, encryptionKey } = owner;
       const syncOwner: SyncOwner = {
-        owner,
+        owner:
+          "writeKey" in owner
+            ? { id, encryptionKey, writeKey: owner.writeKey }
+            : { id, encryptionKey },
         transports: effectiveTransports,
       };
 
@@ -1722,6 +1817,7 @@ export const createEvolu =
         {
           name,
           appOwner,
+          devicePersistence: devicePersistence.promise,
 
           insert: createMutation("insert"),
           update: createMutation("update"),

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

@@ -42,6 +42,7 @@ import {
   type ProtocolTimestampMismatchError,
   SubscriptionFlags,
 } from "./Protocol.ts";
+import type { DevicePersistence } from "./Evolu.ts";
 import {
   createQueryBuilder,
   type EvoluSchema,
@@ -170,11 +171,11 @@ const setupSharedWorker = async ({
   createWebSocket = testCreateWebSocket({ throwOnCreate: true }),
   time,
   seed,
-  isPersistentStorageAvailable,
+  getDevicePersistence = () => Promise.resolve("Unknown"),
 }: {
   createWebSocket?: CreateWebSocket;
   time?: TestTime;
-  isPersistentStorageAvailable?: () => Promise<boolean>;
+  getDevicePersistence?: () => Promise<DevicePersistence>;
   /**
    * Seeds the worker's random bytes, which are otherwise the same for every
    * worker.
@@ -214,7 +215,7 @@ const setupSharedWorker = async ({
       createWebSocket,
       ...(time && { time }),
       ...(seed && { randomBytes: testCreateDeps({ seed }).randomBytes }),
-      ...(isPersistentStorageAvailable && { isPersistentStorageAvailable }),
+      getDevicePersistence,
     }),
   );
 
@@ -239,8 +240,10 @@ const setupSharedWorker = async ({
     releaseDbWorkerLeaderOnDispose = true,
     autoDispose = true,
     initialClock = createTimestamp(),
+    memoryOnly = false,
   }: {
     tenantName?: Name;
+    memoryOnly?: boolean;
     evoluChannel?: TestMessageChannel<EvoluOutput, EvoluInput>;
     releaseDbWorkerLeaderOnDispose?: boolean;
     autoDispose?: boolean;
@@ -289,7 +292,7 @@ const setupSharedWorker = async ({
       consoleLevel: "debug",
       sqliteSchema: testSqliteSchema,
       encryptionKey: testAppOwner.encryptionKey,
-      memoryOnly: false,
+      memoryOnly,
       evoluPort: evoluChannel.port1.native,
     };
 
@@ -339,7 +342,25 @@ const setupSharedWorker = async ({
   ) => {
     const instance = await createEvoluBeforeDbWorkerLeader(options);
     await instance.acquireDbWorkerLeader();
-    return instance;
+
+    // Once the DbWorker starts, the tenant adds the instance and tells it its
+    // device persistence first, so tests see only the outputs that follow.
+    const firstOutputs: Array<EvoluOutput> = [];
+    instance.evoluChannel.port2.onMessage = (output) => {
+      firstOutputs.push(output);
+    };
+    await testWaitForWorkerMessage();
+    instance.evoluChannel.port2.onMessage = null;
+    assertLength(firstOutputs, 1);
+    const [devicePersistenceOutput] = firstOutputs;
+    assert(
+      devicePersistenceOutput.type === "OnDevicePersistence",
+      "Expected the device persistence first.",
+    );
+
+    return Object.assign(instance, {
+      devicePersistence: devicePersistenceOutput.devicePersistence,
+    });
   };
 
   return {
@@ -607,17 +628,30 @@ describe("storage", () => {
   const isMemoryOnly = (output: SharedWorkerOutput | undefined): boolean =>
     getDbWorkerInit(output).memoryOnly;
 
+  /** Every device persistence the tenant sent to the instance so far. */
+  const receiveDevicePersistences = async (
+    evoluChannel: TestMessageChannel<EvoluOutput, EvoluInput>,
+  ): Promise<ReadonlyArray<DevicePersistence>> => {
+    const devicePersistences: Array<DevicePersistence> = [];
+    evoluChannel.port2.onMessage = (output) => {
+      if (output.type === "OnDevicePersistence") {
+        devicePersistences.push(output.devicePersistence);
+      }
+    };
+    await testWaitForWorkerMessage();
+    return devicePersistences;
+  };
+
   it("keeps every database in memory, replacements included, without persistent storage", async () => {
-    const isPersistentStorageAvailable = mock.fn(() => Promise.resolve(false));
-    await using setup = await setupSharedWorker({
-      isPersistentStorageAvailable,
-    });
+    const getDevicePersistence = mock.fn(() =>
+      Promise.resolve<DevicePersistence>("NotPersisted"),
+    );
+    await using setup = await setupSharedWorker({ getDevicePersistence });
     using disposer = new DisposableStack();
 
-    // The first tab heard it right after Connected.
-    assertEqual(setup.sharedWorkerOutputs, [{ type: "StorageUnavailable" }]);
     const first = await setup.createEvolu();
-    assertTrue(isMemoryOnly(setup.sharedWorkerOutputs.at(1)));
+    assertTrue(isMemoryOnly(setup.sharedWorkerOutputs.at(0)));
+    assertSame(first.devicePersistence, "NotPersisted");
 
     // A replacement DbWorker, as after its tab closed, keeps it in memory too.
     await first.releaseDbWorkerLeader();
@@ -625,8 +659,7 @@ describe("storage", () => {
     tab.port.postMessage({ type: "AnnounceTabLeader", consoleLevel: "debug" });
     await testWaitForWorkerMessage();
     await testWaitForWorkerMessage();
-    assertSame(tab.outputs.at(0)?.type, "StorageUnavailable");
-    const replacement = getDbWorkerInit(tab.outputs.at(1));
+    const replacement = getDbWorkerInit(tab.outputs.at(0));
     assertTrue(replacement.memoryOnly);
     using leaderPort = testCreateMessagePort<DbWorkerOutput, DbWorkerInput>(
       replacement.port,
@@ -638,29 +671,62 @@ describe("storage", () => {
     });
     await testWaitForWorkerMessage();
 
-    assertSame(isPersistentStorageAvailable.mock.callCount(), 1);
+    assertSame(getDevicePersistence.mock.callCount(), 1);
   });
 
-  it("keeps databases where the app configured them with persistent storage", async () => {
+  for (const devicePersistence of ["Persisted", "Unknown"] as const) {
+    it(`stores databases and tells instances ${devicePersistence} where the platform promises it`, async () => {
+      await using setup = await setupSharedWorker({
+        getDevicePersistence: () => Promise.resolve(devicePersistence),
+      });
+
+      const instance = await setup.createEvolu();
+
+      assertEqual(
+        setup.sharedWorkerOutputs.map(({ type }) => type),
+        ["DbWorkerInit"],
+      );
+      assertFalse(isMemoryOnly(setup.sharedWorkerOutputs.at(0)));
+      assertSame(instance.devicePersistence, devicePersistence);
+    });
+  }
+
+  it("tells an instance configured memoryOnly that its database is not persisted", async () => {
     await using setup = await setupSharedWorker({
-      isPersistentStorageAvailable: () => Promise.resolve(true),
+      getDevicePersistence: () => Promise.resolve("Persisted"),
     });
 
-    await setup.createEvolu();
+    const instance = await setup.createEvolu({ memoryOnly: true });
 
-    assertEqual(
-      setup.sharedWorkerOutputs.map(({ type }) => type),
-      ["DbWorkerInit"],
-    );
-    assertFalse(isMemoryOnly(setup.sharedWorkerOutputs.at(0)));
+    assertTrue(isMemoryOnly(setup.sharedWorkerOutputs.at(0)));
+    assertSame(instance.devicePersistence, "NotPersisted");
   });
 
-  it("keeps databases where the app configured them on platforms without the check", async () => {
-    await using setup = await setupSharedWorker();
+  it("tells a later instance of the same name the mode the first one chose", async () => {
+    await using setup = await setupSharedWorker({
+      getDevicePersistence: () => Promise.resolve("Persisted"),
+    });
+    const { run, worker } = setup;
+    await setup.createEvolu({ memoryOnly: true });
 
-    await setup.createEvolu();
+    const secondId: EvoluInstanceId = createId(run.deps);
+    await using _secondInstanceLock = await run.ok(acquireLeaderLock(secondId));
+    using secondChannel = testCreateMessageChannel<EvoluOutput, EvoluInput>();
+    worker.port.postMessage({
+      type: "CreateEvolu",
+      name: testName,
+      id: secondId,
+      consoleLevel: "debug",
+      sqliteSchema: testSqliteSchema,
+      encryptionKey: testAppOwner.encryptionKey,
+      memoryOnly: false,
+      evoluPort: secondChannel.port1.native,
+    });
+    await testWaitForWorkerMessage();
 
-    assertFalse(isMemoryOnly(setup.sharedWorkerOutputs.at(0)));
+    assertEqual(await receiveDevicePersistences(secondChannel), [
+      "NotPersisted",
+    ]);
   });
 });
 
@@ -681,6 +747,7 @@ describe("builds", () => {
         lockManager,
         createMessagePort: testCreateMessagePort,
         createWebSocket: testCreateWebSocket({ throwOnCreate: true }),
+        getDevicePersistence: () => Promise.resolve("Unknown" as const),
       }),
     );
     const outputs: Array<SharedWorkerOutput> = [];
@@ -7265,7 +7332,14 @@ describe("with one evolu instance", () => {
         memoryOnly: false,
         evoluPort: siblingChannel.port1.native,
       });
+      const siblingOutputs: Array<EvoluOutput> = [];
+      siblingChannel.port2.onMessage = (output) => {
+        siblingOutputs.push(output);
+      };
       await testWaitForWorkerMessage();
+      assertEqual(siblingOutputs, [
+        { type: "OnDevicePersistence", devicePersistence: "Unknown" },
+      ]);
       siblingChannel.port2.postMessage({
         type: "Mutate",
         changes: [
@@ -9644,6 +9718,10 @@ describe("with one evolu instance", () => {
         [siblingChannel.port1.native],
       );
       await testWaitForWorkerMessage();
+      // The tenant keeps the first instance's persistent database.
+      assertEqual(siblingOutputs.splice(0), [
+        { type: "OnDevicePersistence", devicePersistence: "Unknown" },
+      ]);
 
       const bytes = new Uint8Array([1, 2, 3]);
       const mutation: ExtractTyped<EvoluInput, "Mutate"> = {
@@ -10811,10 +10889,13 @@ describe("startup refusal", () => {
     });
     await testWaitForWorkerMessage();
     // The tab is told through its own connection, not the broadcast channel,
-    // and its instance is not answered: pending work stays pending.
+    // and its instance learns only its device persistence: pending work stays
+    // pending.
     assertEqual(firstTabOutputs(), [{ type: "Error", error: refusal }]);
     assertEqual(broadcasts, []);
-    assertEqual(evoluOutputs, []);
+    assertEqual(evoluOutputs.splice(0), [
+      { type: "OnDevicePersistence", devicePersistence: "Unknown" },
+    ]);
 
     // Later requests are dropped without a response.
     instance.evoluChannel.port2.postMessage({
@@ -10852,7 +10933,9 @@ describe("startup refusal", () => {
     );
     await testWaitForWorkerMessage();
     assertEqual(firstTabOutputs(), [{ type: "Error", error: refusal }]);
-    assertEqual(secondOutputs, []);
+    assertEqual(secondOutputs, [
+      { type: "OnDevicePersistence", devicePersistence: "Unknown" },
+    ]);
 
     // A tab that connects later is told once, through its own connection.
     const laterTab = setupTab(setup, disposer);