@evolu/common 8.10.0 → 8.11.0

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

@@ -18,15 +18,22 @@ import type { Brand } from "../Brand.ts";
 import type { ConsoleEntry, TestConsole } from "../Console.ts";
 import { testCreateConsole } from "../Console.ts";
 import { constVoid } from "../Function.ts";
-import type { DbWorkerInit } from "./Db.ts";
+import type { DbWorkerInit, UnsupportedDbVersionError } from "./Db.ts";
 import {
   AppName,
   createEvolu,
   createEvoluDeps,
+  type Evolu,
+  type EvoluConfig,
   testAppName,
   type EvoluPlatformDeps,
 } from "./Evolu.ts";
-import { createOwnerWebSocketTransport, testAppOwner } from "./Owner.ts";
+import {
+  createOwnerSecret,
+  createOwnerWebSocketTransport,
+  createSharedOwner,
+  testAppOwner,
+} from "./Owner.ts";
 import { createQueryBuilder } from "./Schema.ts";
 import {
   consoleEntryOrErrorBroadcastChannelName,
@@ -36,21 +43,30 @@ import {
   type EvoluInput,
   type EvoluOutput,
   type SharedWorker,
+  type SharedWorkerId,
   type SharedWorkerInput,
   type SharedWorkerOutput,
+  type SyncState,
 } from "./Shared.ts";
-import { testCreateLockManager } from "../LockManager.ts";
+import {
+  acquireLeaderLock,
+  type LockManagerDep,
+  testCreateLockManager,
+} from "../LockManager.ts";
 import { installPolyfills } from "../Polyfills.ts";
 import { err, ok } from "../Result.ts";
 import { SqliteBoolean } from "../Sqlite.ts";
 import { explicitAbortReason, testCreateRun } from "../Task.ts";
+import { testCreateId } from "../Test.ts";
 import {
   assertType,
   createIdFromString,
   id,
   NonEmptyTrimmedString100,
   nullOr,
+  PositiveInt,
   testName,
+  Name,
 } from "../Type.ts";
 import type { ExtractTyped } from "../Type.ts";
 import {
@@ -203,6 +219,8 @@ describe("Evolu", () => {
       }),
     );
 
+    assertThrowsInstanceOf(() => AppName.orThrow("a".repeat(42)), Error);
+
     const appName = AppName.orThrow("my-app");
     assertType<typeof appName, AppName>();
     assertType<typeof AppName.Input, string>();
@@ -212,12 +230,22 @@ describe("Evolu", () => {
   describe("createEvoluDeps", () => {
     const setupCreateEvoluDeps = async (
       console: TestConsole = testCreateConsole(),
+      lockManager: LockManagerDep["lockManager"] = testCreateLockManager(),
     ): Promise<{
       readonly deps: ReturnType<typeof createEvoluDeps>;
       readonly messages: Array<SharedWorkerInput>;
+      readonly sharedWorkerPort: MessagePort<
+        SharedWorkerOutput,
+        SharedWorkerInput
+      >;
       readonly consoleEntryOrErrorBroadcastChannel: {
         readonly postMessage: (message: ConsoleEntryOrError) => void;
       };
+      /**
+       * Sends the worker's Connected message, as a worker holding its lock
+       * does.
+       */
+      readonly connect: (workerId: SharedWorkerId) => Promise<void>;
       readonly [Symbol.dispose]: () => void;
     }> => {
       using disposer = new DisposableStack();
@@ -226,7 +254,11 @@ describe("Evolu", () => {
       );
 
       const messages: Array<SharedWorkerInput> = [];
+      const sharedWorkerPort: {
+        value: MessagePort<SharedWorkerOutput, SharedWorkerInput> | null;
+      } = { value: null };
       worker.self.onConnect = (port) => {
+        sharedWorkerPort.value = port;
         port.onMessage = (message) => {
           messages.push(message);
         };
@@ -238,7 +270,7 @@ describe("Evolu", () => {
           createDbWorker: testCreateWorker,
           createBroadcastChannel: testCreateBroadcastChannel,
           createMessageChannel: testCreateMessageChannel,
-          lockManager: testCreateLockManager(),
+          lockManager,
           sharedWorker: worker,
           reloadApp: constVoid,
           console,
@@ -247,8 +279,10 @@ describe("Evolu", () => {
 
       await testWaitForWorkerMessage();
 
-      assertLength(messages, 1);
-      assertSame(messages[0].type, "AnnounceTabLeader");
+      // A tab says nothing until its worker connects.
+      assertEqual(messages, []);
+      const port = sharedWorkerPort.value;
+      assertNotNull(port);
       const consoleEntryOrErrorBroadcastChannel = disposer.use(
         testCreateBroadcastChannel<ConsoleEntryOrError>(
           consoleEntryOrErrorBroadcastChannelName,
@@ -259,21 +293,110 @@ describe("Evolu", () => {
       return {
         deps,
         messages,
+        sharedWorkerPort: port,
         consoleEntryOrErrorBroadcastChannel,
+        connect: async (workerId) => {
+          port.postMessage({
+            type: "Connected",
+            workerId,
+            syncStateChannelName: `evolu:sync-state:${workerId}`,
+          });
+          await testWaitForWorkerMessage();
+        },
         [Symbol.dispose]: () => disposables.dispose(),
       };
     };
 
-    it("posts AnnounceTabLeader with console level to worker", async () => {
+    it("reports an OtherBuildRunningError its worker sends and clears it once the worker connects", async () => {
+      using setup = await setupCreateEvoluDeps();
+
+      setup.sharedWorkerPort.postMessage({
+        type: "Error",
+        error: { type: "OtherBuildRunningError" },
+      });
+      await testWaitForWorkerMessage();
+      assertEqual(setup.deps.evoluError.get(), {
+        type: "OtherBuildRunningError",
+      });
+
+      await setup.connect(testCreateId()<"SharedWorker">());
+      assertSame(setup.deps.evoluError.get(), null);
+    });
+
+    it("keeps another error when its worker connects", async () => {
+      using setup = await setupCreateEvoluDeps();
+      const error: UnsupportedDbVersionError = {
+        type: "UnsupportedDbVersionError",
+        storedVersion: PositiveInt.orThrow(3),
+        supportedVersion: PositiveInt.orThrow(2),
+      };
+
+      setup.sharedWorkerPort.postMessage({ type: "Error", error });
+      await testWaitForWorkerMessage();
+      await setup.connect(testCreateId()<"SharedWorker">());
+
+      assertEqual(setup.deps.evoluError.get(), error);
+    });
+
+    it("says nothing to a worker that reports it waits", async () => {
+      using setup = await setupCreateEvoluDeps();
+
+      setup.sharedWorkerPort.postMessage({
+        type: "Waiting",
+        workerId: testCreateId()<"SharedWorker">(),
+      });
+      await testWaitForWorkerMessage();
+
+      assertEqual(setup.messages, []);
+      assertSame(setup.deps.evoluError.get(), null);
+    });
+
+    it("says nothing to a worker that reports it keeps databases in memory", async () => {
+      using setup = await setupCreateEvoluDeps();
+
+      setup.sharedWorkerPort.postMessage({ type: "StorageUnavailable" });
+      await testWaitForWorkerMessage();
+
+      assertEqual(setup.messages, []);
+      assertSame(setup.deps.evoluError.get(), null);
+    });
+
+    it("announces itself as tab leader with its console level once its worker connects", async () => {
       const testConsole = testCreateConsole();
       using setup = await setupCreateEvoluDeps(testConsole);
-      const { messages } = setup;
+      const { messages, connect } = setup;
 
-      assertLength(messages, 1);
-      assertEqual(messages[0], {
-        type: "AnnounceTabLeader",
-        consoleLevel: testConsole.getLevel(),
-      });
+      await connect(testCreateId()<"SharedWorker">());
+
+      assertEqual(messages, [
+        { type: "RequestSyncState" },
+        { type: "AnnounceTabLeader", consoleLevel: testConsole.getLevel() },
+      ]);
+    });
+
+    it("competes for tab leadership only with tabs of its worker", async () => {
+      const lockManager = testCreateLockManager();
+      await using run = testCreateRun({ lockManager });
+      const createWorkerId = testCreateId();
+      const worker = createWorkerId<"SharedWorker">();
+      // The tab's worker holds this lock for its lifetime.
+      await using _workerBuildLock = await run.ok(acquireLeaderLock("tab"));
+      using first = await setupCreateEvoluDeps(undefined, lockManager);
+      using second = await setupCreateEvoluDeps(undefined, lockManager);
+      using ofOtherWorker = await setupCreateEvoluDeps(undefined, lockManager);
+      await first.connect(worker);
+      await second.connect(worker);
+      await ofOtherWorker.connect(createWorkerId<"SharedWorker">());
+      const isLeader = (setup: typeof first): boolean =>
+        setup.messages.some((message) => message.type === "AnnounceTabLeader");
+
+      assertTrue(isLeader(first));
+      assertFalse(isLeader(second));
+      assertTrue(isLeader(ofOtherWorker));
+
+      first[Symbol.dispose]();
+      await testWaitForWorkerMessage();
+      assertTrue(isLeader(second));
     });
 
     it("initializes db worker from shared worker init output", async () => {
@@ -367,6 +490,11 @@ describe("Evolu", () => {
           port.onMessage = (message) => {
             messages.push(message);
           };
+          port.postMessage({
+            type: "Connected",
+            workerId: testCreateId()<"SharedWorker">(),
+            syncStateChannelName: "evolu:sync-state:worker",
+          });
         };
         worker.connect();
 
@@ -382,8 +510,11 @@ describe("Evolu", () => {
         await testWaitForWorkerMessage();
 
         assertNotUndefined(deps.console);
-        assertLength(messages, 1);
-        assertSame(messages[0].type, "AnnounceTabLeader");
+        const messageTypes = ["RequestSyncState", "AnnounceTabLeader"];
+        assertEqual(
+          messages.map((message) => message.type),
+          messageTypes,
+        );
         using consoleEntryOrErrorBroadcastChannel =
           testCreateBroadcastChannel<ConsoleEntryOrError>(
             consoleEntryOrErrorBroadcastChannelName,
@@ -396,8 +527,10 @@ describe("Evolu", () => {
 
         await testWaitForWorkerMessage();
 
-        assertLength(messages, 1);
-        assertSame(messages[0].type, "AnnounceTabLeader");
+        assertEqual(
+          messages.map((message) => message.type),
+          messageTypes,
+        );
         assertEqual(deps.evoluError.get(), {
           type: "UnknownError",
           error: ["boom"],
@@ -428,6 +561,84 @@ describe("Evolu", () => {
       assertEqual(testConsole.getEntriesSnapshot(), [entry]);
     });
 
+    it("follows the sync state channel its worker names", async () => {
+      using setup = await setupCreateEvoluDeps();
+      const { deps, messages, connect } = setup;
+      const workerId = testCreateId()<"SharedWorker">();
+      using channel = testCreateBroadcastChannel<SyncState>(
+        `evolu:sync-state:${workerId}`,
+      );
+      using otherChannel = testCreateBroadcastChannel<SyncState>(
+        "evolu:sync-state:other-worker",
+      );
+      const createState = (label: string): SyncState => ({
+        transports: [],
+        tenants: [{ name: Name.orThrow(label), refused: false, owners: [] }],
+      });
+
+      // Nothing reaches the tab before its worker names the channel.
+      channel.postMessage(createState("early"));
+      await testWaitForWorkerMessage();
+      assertSame(deps.syncState.get(), null);
+
+      await connect(workerId);
+      assertEqual(messages.at(0), { type: "RequestSyncState" });
+      channel.postMessage(createState("requested"));
+      await testWaitForWorkerMessage();
+      assertEqual(deps.syncState.get(), createState("requested"));
+
+      channel.postMessage(createState("changed"));
+      await testWaitForWorkerMessage();
+      assertEqual(deps.syncState.get(), createState("changed"));
+
+      // Another worker's channel is never heard.
+      otherChannel.postMessage(createState("other"));
+      await testWaitForWorkerMessage();
+      assertEqual(deps.syncState.get(), createState("changed"));
+    });
+
+    it("listens on its worker's channel before asking for a snapshot", async () => {
+      const name = "evolu:sync-state:worker";
+      using worker = testCreateSharedWorker<
+        SharedWorkerInput,
+        SharedWorkerOutput
+      >();
+      worker.self.onConnect = (port) => {
+        port.onMessage = constVoid;
+        port.postMessage({
+          type: "Connected",
+          workerId: testCreateId()<"SharedWorker">(),
+          syncStateChannelName: name,
+        });
+      };
+      worker.connect();
+      using channel = testCreateBroadcastChannel<SyncState>(name);
+      const requested: SyncState = { transports: [], tenants: [] };
+      // A worker on another thread can broadcast its answer before the tab's
+      // postMessage returns.
+      const port = new Proxy(worker.port, {
+        get: (target, property) =>
+          property === "postMessage"
+            ? (message: SharedWorkerInput) => {
+                if (message.type === "RequestSyncState")
+                  channel.postMessage(requested);
+                target.postMessage(message);
+              }
+            : (Reflect.get(target, property) as unknown),
+      });
+
+      using deps = createEvoluDeps({
+        createDbWorker: testCreateWorker,
+        createBroadcastChannel: testCreateBroadcastChannel,
+        createMessageChannel: testCreateMessageChannel,
+        lockManager: testCreateLockManager(),
+        sharedWorker: { port, [Symbol.dispose]: constVoid },
+        reloadApp: constVoid,
+      });
+      await testWaitForWorkerMessage();
+      assertEqual(deps.syncState.get(), requested);
+    });
+
     it("maps ConsoleEntry error output to deps.evoluError store", async () => {
       using setup = await setupCreateEvoluDeps();
       const { deps, consoleEntryOrErrorBroadcastChannel } = setup;
@@ -497,6 +708,78 @@ describe("Evolu", () => {
       assertEqual(deps.evoluError.get(), error);
     });
 
+    for (const source of ["SharedWorker", "Error", "ConsoleEntry"] as const) {
+      it(`preserves the first startup refusal while logging a later ${source} message`, async () => {
+        const testConsole = testCreateConsole();
+        using setup = await setupCreateEvoluDeps(testConsole);
+        const { deps, sharedWorkerPort, consoleEntryOrErrorBroadcastChannel } =
+          setup;
+        assertSame(deps.evoluError.get(), null);
+
+        const initialError = {
+          type: "UnknownError",
+          error: "before refusal",
+        } as const;
+        consoleEntryOrErrorBroadcastChannel.postMessage({
+          type: "Error",
+          error: initialError,
+        });
+        await testWaitForWorkerMessage();
+        assertEqual(deps.evoluError.get(), initialError);
+
+        let notifications = 0;
+        deps.evoluError.subscribe(() => {
+          notifications++;
+        });
+        const refusal: UnsupportedDbVersionError = {
+          type: "UnsupportedDbVersionError",
+          storedVersion: PositiveInt.orThrow(2),
+          supportedVersion: PositiveInt.orThrow(1),
+        };
+        sharedWorkerPort.postMessage({ type: "Error", error: refusal });
+        await testWaitForWorkerMessage();
+        const storedRefusal = deps.evoluError.get();
+        assertEqual(storedRefusal, refusal);
+        assertSame(notifications, 1);
+
+        const laterRefusal: UnsupportedDbVersionError = {
+          ...refusal,
+          storedVersion: PositiveInt.orThrow(3),
+        };
+        const laterError = {
+          type: "UnknownError",
+          error: "after refusal",
+        } as const;
+        const laterEntry: ConsoleEntry = {
+          method: "error",
+          path: source === "ConsoleEntry" ? ["worker"] : [],
+          args: [source === "SharedWorker" ? laterRefusal : laterError],
+        };
+        if (source === "SharedWorker") {
+          sharedWorkerPort.postMessage({ type: "Error", error: laterRefusal });
+        } else if (source === "Error") {
+          consoleEntryOrErrorBroadcastChannel.postMessage({
+            type: "Error",
+            error: laterError,
+          });
+        } else {
+          consoleEntryOrErrorBroadcastChannel.postMessage({
+            type: "ConsoleEntry",
+            entry: laterEntry,
+          });
+        }
+        await testWaitForWorkerMessage();
+
+        assertSame(deps.evoluError.get(), storedRefusal);
+        assertSame(notifications, 1);
+        assertEqual(testConsole.getEntriesSnapshot(), [
+          { method: "error", path: [], args: [initialError] },
+          { method: "error", path: [], args: [refusal] },
+          laterEntry,
+        ]);
+      });
+    }
+
     it("throws for unknown tab output type", () => {
       const consoleEntryOrErrorBroadcastChannel: {
         value: {
@@ -530,13 +813,18 @@ describe("Evolu", () => {
       }, Error);
     });
 
-    it("dispose cleans up resources", () => {
+    it("dispose cleans up resources", async () => {
       const worker = testCreateSharedWorker<
         SharedWorkerInput,
         SharedWorkerOutput
       >();
       worker.self.onConnect = (port) => {
         port.onMessage = constVoid;
+        port.postMessage({
+          type: "Connected",
+          workerId: testCreateId()<"SharedWorker">(),
+          syncStateChannelName: "evolu:sync-state:worker",
+        });
       };
       worker.connect();
 
@@ -564,16 +852,93 @@ describe("Evolu", () => {
         reloadApp: constVoid,
       });
 
-      assertLength(broadcastChannels, 1);
+      // The console/error channel, then the sync state channel its worker names.
+      assertSame(broadcastChannels.length, 1);
+      await testWaitForWorkerMessage();
+      assertLength(broadcastChannels, 2);
       assertFalse(broadcastChannels[0].isDisposed());
+      assertFalse(broadcastChannels[1].isDisposed());
       assertFalse(workerDisposed);
       deps[Symbol.dispose]();
       assertTrue(broadcastChannels[0].isDisposed());
+      assertTrue(broadcastChannels[1].isDisposed());
       assertTrue(workerDisposed);
     });
   });
 
+  describe("local tables", () => {
+    const LocalSchema = { _todo: Schema.todo };
+    const config: EvoluConfig = {
+      appName: testAppName,
+      appOwner: testAppOwner,
+      transports: [],
+    };
+
+    it("keeps useOwner available for an instance with only local tables", async () => {
+      const messages: Array<SharedWorkerInput> = [];
+      await using setup = await setupRunWithEvoluDeps({
+        onSharedWorkerPostMessage: (message) => {
+          messages.push(message);
+        },
+      });
+      const evolu = await setup.run.ok(createEvolu(LocalSchema, config));
+      assertType<typeof evolu, Evolu<typeof LocalSchema>>();
+      assertSame(evolu.appOwner, testAppOwner);
+      assertEqual(evolu.name, `AppName-${createIdFromString(testAppOwner.id)}`);
+      await testWaitForWorkerMessage();
+      assertEqual(setup.evoluInputs, []);
+      const message = messages.find(
+        (message) => message.type === "CreateEvolu",
+      );
+      assertNotUndefined(message);
+      assertSame(message.encryptionKey, testAppOwner.encryptionKey);
+      assertFalse(message.memoryOnly);
+
+      evolu.insert("_todo", {
+        title: NonEmptyTrimmedString100.orThrow("Local"),
+      });
+      await testWaitForWorkerMessage();
+      assertTrue(setup.evoluInputs.some((input) => input.type === "Mutate"));
+      assertFalse(setup.evoluInputs.some((input) => input.type === "UseOwner"));
+      const unuseOwner = evolu.useOwner(testAppOwner, [testOwnerTransport]);
+      await testWaitForWorkerMessage();
+      assertTrue(setup.evoluInputs.some((input) => input.type === "UseOwner"));
+      unuseOwner();
+      await evolu[Symbol.asyncDispose]();
+      assertThrowsInstanceOf(
+        () =>
+          evolu.insert("_todo", {
+            title: NonEmptyTrimmedString100.orThrow("Disposed"),
+          }),
+        Error,
+      );
+    });
+  });
+
   describe("createEvolu", () => {
+    it("uses the default relay when transports are omitted", async () => {
+      await using setup = await setupRunWithEvoluDeps();
+      await setup.run.ok(
+        createEvolu(Schema, {
+          appName: testAppName,
+          appOwner: testAppOwner,
+        }),
+      );
+      await testWaitForWorkerMessage();
+      const input = setup.evoluInputs.find(
+        (input) => input.type === "UseOwner",
+      );
+      assertNotUndefined(input);
+      assertEqual(input.actions, [
+        {
+          action: "add",
+          owner: {
+            owner: testAppOwner,
+            transports: [{ type: "WebSocket", url: "wss://free.evoluhq.com" }],
+          },
+        },
+      ]);
+    });
     it("resolves name from appName and appOwner hash", async () => {
       await using setup = await setupRunWithEvoluDeps();
       const { run } = setup;
@@ -644,6 +1009,70 @@ describe("Evolu", () => {
       assertNonNullable(message.evoluPort);
     });
 
+    describe("requestSync", () => {
+      it("preserves pending owner operations and returns immediately", async () => {
+        await using setup = await setupRunWithEvoluDeps();
+        const { run, evoluInputs } = setup;
+        const evolu = await run.ok(testCreateEvolu);
+        const sharedOwner = createSharedOwner(createOwnerSecret(run.deps));
+        const owner = { owner: sharedOwner, transports: [testOwnerTransport] };
+        assertNotSame(sharedOwner.id, evolu.appOwner.id);
+
+        const unuse = evolu.useOwner(sharedOwner, [testOwnerTransport]);
+        const result = evolu.requestSync(sharedOwner.id);
+        assertType<typeof result, void>();
+        assertSame(result, undefined);
+        unuse();
+        evolu.requestSync(sharedOwner.id);
+        assertEqual(evoluInputs, []);
+
+        await testWaitForWorkerMessage();
+        assertEqual(evoluInputs, [
+          {
+            type: "UseOwner",
+            actions: [{ action: "add", owner }],
+          },
+          {
+            type: "UseOwner",
+            actions: [
+              { action: "sync", ownerId: sharedOwner.id },
+              { action: "remove", owner },
+            ],
+          },
+          {
+            type: "UseOwner",
+            actions: [{ action: "sync", ownerId: sharedOwner.id }],
+          },
+        ]);
+      });
+
+      it("drops pending requests on disposal", async () => {
+        await using setup = await setupRunWithEvoluDeps();
+        const { run, evoluInputs } = setup;
+        const evolu = await run.ok(testCreateEvolu);
+        evolu.requestSync(testAppOwner.id);
+        await evolu[Symbol.asyncDispose]();
+        await testWaitForWorkerMessage();
+        assertEqual(evoluInputs, []);
+      });
+
+      it("preserves registration, mutation, and sync request order", async () => {
+        await using setup = await setupRunWithEvoluDeps();
+        const { run, evoluInputs } = setup;
+        const evolu = await run.ok(testCreateEvolu);
+        evolu.useOwner(testAppOwner, [testOwnerTransport]);
+        evolu.insert("todo", {
+          title: NonEmptyTrimmedString100.orThrow("Before sync"),
+        });
+        evolu.requestSync(testAppOwner.id);
+        await testWaitForWorkerMessage();
+        assertEqual(
+          evoluInputs.map(({ type }) => type),
+          ["UseOwner", "Mutate", "UseOwner"],
+        );
+      });
+    });
+
     describe("useOwner", () => {
       it("auto-uses appOwner in a microtask when transports are configured", async () => {
         await using setup = await setupRunWithEvoluDeps();
@@ -898,7 +1327,7 @@ describe("Evolu", () => {
       assertEqual(evoluInputs, [{ type: "Export" }]);
     });
 
-    it("throws from sync methods after dispose", async () => {
+    it("throws from synchronous methods after disposal", async () => {
       await using setup = await setupRunWithEvoluDeps();
       const { run } = setup;
       const evolu = await run.ok(testCreateEvolu);
@@ -992,6 +1421,13 @@ describe("Evolu", () => {
         }, Error).message,
         disposedMessage,
       );
+
+      assertEqual(
+        assertThrowsInstanceOf(() => {
+          evolu.requestSync(testAppOwner.id);
+        }, Error).message,
+        disposedMessage,
+      );
     });
 
     it("delete methods are placeholders", async () => {
@@ -1315,6 +1751,229 @@ describe("Evolu", () => {
   });
 
   describe("query behavior", () => {
+    it("subscribeQuery catches a refresh between loading and subscribing", async () => {
+      await using setup = await setupRunWithEvoluDeps();
+      const { run, evoluInputs, postEvoluOutput } = setup;
+      const evolu = await run.ok(testCreateEvolu);
+
+      const initialLoad = evolu.loadQuery(todoTitleQuery);
+      await testWaitForWorkerMessage();
+      postEvoluOutput({
+        type: "OnPatchesByQuery",
+        patchesByQuery: new Map([
+          [todoTitleQuery, [{ op: "replaceAll", value: [] }]],
+        ]),
+        onCompleteIds: [],
+      });
+      const initialRows = await initialLoad;
+      assertEqual(initialRows, []);
+
+      evoluInputs.length = 0;
+      postEvoluOutput({ type: "RefreshQueries" });
+      await testWaitForWorkerMessage();
+      assertEqual(evoluInputs, []);
+
+      let notifications = 0;
+      const unsubscribe = evolu.subscribeQuery(todoTitleQuery)(() => {
+        notifications += 1;
+      });
+      // React use() must still see fulfilled rows if another render happens
+      // before the worker answers the refresh queued by subscription.
+      const cachedLoad = evolu.loadQuery(todoTitleQuery);
+      assert("status" in cachedLoad, "Cached promises expose React status");
+      assertSame(cachedLoad.status, "fulfilled");
+      assert("value" in cachedLoad, "Fulfilled promises expose cached rows");
+      assertSame(cachedLoad.value, initialRows);
+      assertSame(await cachedLoad, initialRows);
+      assertSame(notifications, 0);
+      await testWaitForWorkerMessage();
+      assertEqual(evoluInputs, [
+        { type: "Query", queries: new Set([todoTitleQuery]) },
+      ]);
+
+      postEvoluOutput({
+        type: "OnPatchesByQuery",
+        patchesByQuery: new Map([
+          [
+            todoTitleQuery,
+            [{ op: "replaceAll", value: [{ title: "Synced" }] }],
+          ],
+        ]),
+        onCompleteIds: [],
+      });
+      await testWaitForWorkerMessage();
+      assertEqual(evolu.getQueryRows(todoTitleQuery), [{ title: "Synced" }]);
+      assertEqual(notifications, 1);
+      // React use() sees a new fulfilled promise after the refresh.
+      const refreshedLoad = evolu.loadQuery(todoTitleQuery);
+      assertNotSame(refreshedLoad, cachedLoad);
+      assertEqual(await refreshedLoad, [{ title: "Synced" }]);
+      unsubscribe();
+    });
+
+    it("subscribeQuery catches a mutation while the initial read is pending", async () => {
+      await using setup = await setupRunWithEvoluDeps();
+      const { run, evoluInputs, postEvoluOutput } = setup;
+      const evolu = await run.ok(testCreateEvolu);
+
+      const initialLoad = evolu.loadQuery(todoTitleQuery);
+      await testWaitForWorkerMessage();
+      evolu.insert("todo", { title: NonEmptyTrimmedString100.orThrow("New") });
+      await testWaitForWorkerMessage();
+      evoluInputs.length = 0;
+
+      const unsubscribe = evolu.subscribeQuery(todoTitleQuery)(constVoid);
+      assertSame(evolu.loadQuery(todoTitleQuery), initialLoad);
+      await testWaitForWorkerMessage();
+      assertEqual(evoluInputs, [
+        { type: "Query", queries: new Set([todoTitleQuery]) },
+      ]);
+
+      // The old read completes first. Its promise must still settle, and the
+      // new subscription must retain the loading entry for the fresh response.
+      postEvoluOutput({
+        type: "OnPatchesByQuery",
+        patchesByQuery: new Map([
+          [todoTitleQuery, [{ op: "replaceAll", value: [] }]],
+        ]),
+        onCompleteIds: [],
+      });
+      assertEqual(await initialLoad, []);
+      assertSame(evolu.loadQuery(todoTitleQuery), initialLoad);
+
+      postEvoluOutput({
+        type: "OnPatchesByQuery",
+        patchesByQuery: new Map([
+          [todoTitleQuery, [{ op: "replaceAll", value: [{ title: "New" }] }]],
+        ]),
+        onCompleteIds: [],
+      });
+      await testWaitForWorkerMessage();
+      assertEqual(evolu.getQueryRows(todoTitleQuery), [{ title: "New" }]);
+      assertEqual(await evolu.loadQuery(todoTitleQuery), [{ title: "New" }]);
+      unsubscribe();
+    });
+
+    it("subscribeQuery reuses valid pending and completed reads", async () => {
+      await using setup = await setupRunWithEvoluDeps();
+      const { run, evoluInputs, postEvoluOutput } = setup;
+      const evolu = await run.ok(testCreateEvolu);
+
+      const initialLoad = evolu.loadQuery(todoTitleQuery);
+      await testWaitForWorkerMessage();
+      evoluInputs.length = 0;
+      const unsubscribe = evolu.subscribeQuery(todoTitleQuery)(constVoid);
+      assertSame(evolu.loadQuery(todoTitleQuery), initialLoad);
+      await testWaitForWorkerMessage();
+      assertEqual(evoluInputs, []);
+
+      postEvoluOutput({
+        type: "OnPatchesByQuery",
+        patchesByQuery: new Map([
+          [todoTitleQuery, [{ op: "replaceAll", value: [] }]],
+        ]),
+        onCompleteIds: [],
+      });
+      await initialLoad;
+      unsubscribe();
+
+      const unsubscribeAgain = evolu.subscribeQuery(todoTitleQuery)(constVoid);
+      assertSame(evolu.loadQuery(todoTitleQuery), initialLoad);
+      await testWaitForWorkerMessage();
+      assertEqual(evoluInputs, []);
+      unsubscribeAgain();
+    });
+
+    it("subscribeQuery keeps refreshed rows cached after unsubscribe until the next invalidation", async () => {
+      await using setup = await setupRunWithEvoluDeps();
+      const { run, evoluInputs, postEvoluOutput } = setup;
+      const evolu = await run.ok(testCreateEvolu);
+
+      const initialLoad = evolu.loadQuery(todoTitleQuery);
+      await testWaitForWorkerMessage();
+      postEvoluOutput({
+        type: "OnPatchesByQuery",
+        patchesByQuery: new Map([
+          [todoTitleQuery, [{ op: "replaceAll", value: [] }]],
+        ]),
+        onCompleteIds: [],
+      });
+      await initialLoad;
+      postEvoluOutput({ type: "RefreshQueries" });
+      await testWaitForWorkerMessage();
+      evoluInputs.length = 0;
+
+      const unsubscribe = evolu.subscribeQuery(todoTitleQuery)(constVoid);
+      await testWaitForWorkerMessage();
+      assertEqual(evoluInputs, [
+        { type: "Query", queries: new Set([todoTitleQuery]) },
+      ]);
+      unsubscribe();
+      evoluInputs.length = 0;
+
+      // The refresh response still replaces the cached rows.
+      postEvoluOutput({
+        type: "OnPatchesByQuery",
+        patchesByQuery: new Map([
+          [
+            todoTitleQuery,
+            [{ op: "replaceAll", value: [{ title: "Synced" }] }],
+          ],
+        ]),
+        onCompleteIds: [],
+      });
+      await testWaitForWorkerMessage();
+      assertEqual(evolu.getQueryRows(todoTitleQuery), [{ title: "Synced" }]);
+      const cachedLoad = evolu.loadQuery(todoTitleQuery);
+      assertEqual(await cachedLoad, [{ title: "Synced" }]);
+      await testWaitForWorkerMessage();
+      assertEqual(evoluInputs, []);
+
+      // The next invalidation drops the unsubscribed cache without a read.
+      postEvoluOutput({ type: "RefreshQueries" });
+      await testWaitForWorkerMessage();
+      assertEqual(evoluInputs, []);
+      const reload = evolu.loadQuery(todoTitleQuery);
+      assertNotSame(reload, cachedLoad);
+      await testWaitForWorkerMessage();
+      assertEqual(evoluInputs, [
+        { type: "Query", queries: new Set([todoTitleQuery]) },
+      ]);
+    });
+
+    it("subscribeQuery reuses the refreshing entry for repeated subscriptions in one tick", async () => {
+      await using setup = await setupRunWithEvoluDeps();
+      const { run, evoluInputs, postEvoluOutput } = setup;
+      const evolu = await run.ok(testCreateEvolu);
+
+      const initialLoad = evolu.loadQuery(todoTitleQuery);
+      await testWaitForWorkerMessage();
+      postEvoluOutput({
+        type: "OnPatchesByQuery",
+        patchesByQuery: new Map([
+          [todoTitleQuery, [{ op: "replaceAll", value: [] }]],
+        ]),
+        onCompleteIds: [],
+      });
+      await initialLoad;
+      postEvoluOutput({ type: "RefreshQueries" });
+      await testWaitForWorkerMessage();
+      evoluInputs.length = 0;
+
+      // React StrictMode subscribes, unsubscribes, and subscribes again
+      // synchronously.
+      const unsubscribeFirst = evolu.subscribeQuery(todoTitleQuery)(constVoid);
+      const refreshingLoad = evolu.loadQuery(todoTitleQuery);
+      unsubscribeFirst();
+      const unsubscribe = evolu.subscribeQuery(todoTitleQuery)(constVoid);
+      assertSame(evolu.loadQuery(todoTitleQuery), refreshingLoad);
+      await testWaitForWorkerMessage();
+      assertEqual(evoluInputs, [
+        { type: "Query", queries: new Set([todoTitleQuery]) },
+      ]);
+      unsubscribe();
+    });
+
     it("loadQuery reuses pending promise and sends one Query message", async () => {
       await using setup = await setupRunWithEvoluDeps();
       const { run, evoluInputs } = setup;
@@ -1399,7 +2058,7 @@ describe("Evolu", () => {
       );
     });
 
-    it("RefreshQueries re-queries pending unsubscribed loadQuery", async () => {
+    it("RefreshQueries reads a pending unsubscribed loadQuery once, when it is subscribed", async () => {
       await using setup = await setupRunWithEvoluDeps();
       const { run, evoluInputs, postEvoluOutput } = setup;
       const evolu = await run.ok(testCreateEvolu);
@@ -1409,12 +2068,18 @@ describe("Evolu", () => {
 
       evoluInputs.length = 0;
       postEvoluOutput({ type: "RefreshQueries" });
+      await testWaitForWorkerMessage();
 
+      assertEqual(evoluInputs, []);
+
+      const unsubscribe = evolu.subscribeQuery(todoTitleQuery)(constVoid);
       await testWaitForWorkerMessage();
 
       assertEqual(evoluInputs, [
         { type: "Query", queries: new Set([todoTitleQuery]) },
       ]);
+
+      unsubscribe();
     });
 
     it("RefreshQueries re-queries subscribed query without loadQuery", async () => {