@evolu/common 8.10.0 → 8.12.0

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

@@ -13,20 +13,41 @@ import {
   assertThrowsInstanceOf,
   assertTrue,
 } from "../Assert.ts";
+import * as fc from "fast-check";
 import { describe, it } from "node:test";
 import type { Brand } from "../Brand.ts";
+import { createBuffer } from "../Bytes.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,
+  maxMutationSize,
   testAppName,
   type EvoluPlatformDeps,
 } from "./Evolu.ts";
-import { createOwnerWebSocketTransport, testAppOwner } from "./Owner.ts";
+import {
+  createOwnerSecret,
+  createOwnerWebSocketTransport,
+  createSharedOwner,
+  testAppOwner,
+} from "./Owner.ts";
+import {
+  createProtocolBroadcastMessagesFromCrdtMessages,
+  createProtocolMessageBuffer,
+  createProtocolMessageFromCrdtMessages,
+  createTimestampsBuffer,
+  encodeAndEncryptDbChange,
+  encodeDbChange,
+  MessageType,
+  ProtocolErrorCode,
+  ProtocolMessageRangesMaxSize,
+} from "./Protocol.ts";
 import { createQueryBuilder } from "./Schema.ts";
 import {
   consoleEntryOrErrorBroadcastChannelName,
@@ -36,23 +57,37 @@ 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 { explicitAbortReason, testCreateDeps, testCreateRun } from "../Task.ts";
+import { testCreateId } from "../Test.ts";
 import {
   assertType,
   createIdFromString,
+  FiniteNumber,
   id,
   NonEmptyTrimmedString100,
   nullOr,
+  PositiveInt,
+  String as StringType,
   testName,
+  Name,
+  Uint8Array as Uint8ArrayType,
 } from "../Type.ts";
 import type { ExtractTyped } from "../Type.ts";
+import { DbChange } from "./Storage.ts";
+import { createTimestamp, type NodeId } from "./Timestamp.ts";
 import {
   testCreateBroadcastChannel,
   testCreateMessageChannel,
@@ -203,6 +238,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 +249,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 +273,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 +289,7 @@ describe("Evolu", () => {
           createDbWorker: testCreateWorker,
           createBroadcastChannel: testCreateBroadcastChannel,
           createMessageChannel: testCreateMessageChannel,
-          lockManager: testCreateLockManager(),
+          lockManager,
           sharedWorker: worker,
           reloadApp: constVoid,
           console,
@@ -247,8 +298,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 +312,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 +509,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 +529,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 +546,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 +580,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 +727,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 +832,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 +871,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 +1028,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 +1346,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 +1440,13 @@ describe("Evolu", () => {
         }, Error).message,
         disposedMessage,
       );
+
+      assertEqual(
+        assertThrowsInstanceOf(() => {
+          evolu.requestSync(testAppOwner.id);
+        }, Error).message,
+        disposedMessage,
+      );
     });
 
     it("delete methods are placeholders", async () => {
@@ -1315,6 +1770,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 +2077,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 +2087,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 () => {
@@ -1782,6 +2466,294 @@ describe("Evolu", () => {
     });
   });
 
+  describe("mutation size", () => {
+    const NoteId = id("Note");
+    const note = {
+      id: NoteId,
+      body: nullOr(StringType),
+      data: nullOr(Uint8ArrayType),
+      count: nullOr(FiniteNumber),
+    };
+    const SizeSchema = { note, _note: note };
+
+    const createSizeEvolu = createEvolu(SizeSchema, {
+      appName: testAppName,
+      appOwner: testAppOwner,
+      transports: [],
+    });
+
+    const noteId = NoteId.orThrow(createIdFromString("note"));
+
+    const getChanges = (inputs: ReadonlyArray<EvoluInput>) =>
+      inputs.flatMap((input) => (input.type === "Mutate" ? input.changes : []));
+
+    const tooLargeMessage = (size: number) =>
+      `The mutation of table 'note' is ${size} bytes, over maxMutationSize (640000). Bound the Types of its columns or check it with evolu.getMutationSize.`;
+
+    // The length of a blob that makes a note exactly maxMutationSize. Its
+    // length varint takes three bytes, two more than an empty blob's.
+    const getDataAtLimitLength = (evolu: Evolu<typeof SizeSchema>) =>
+      maxMutationSize -
+      evolu.getMutationSize("note", { data: new Uint8Array() }) -
+      2;
+
+    it("getMutationSize measures the change as it is encoded", async () => {
+      await using setup = await setupRunWithEvoluDeps();
+      const evolu = await setup.run.ok(createSizeEvolu);
+
+      const values = {
+        body: "Milk",
+        data: new Uint8Array(10),
+        count: FiniteNumber.orThrow(0.1),
+      };
+      const buffer = createBuffer();
+      encodeDbChange(buffer, {
+        timestamp: createTimestamp(),
+        change: DbChange.orThrow({
+          table: "note",
+          id: noteId,
+          values,
+          isInsert: false,
+          isDelete: true,
+        }),
+      });
+      assertEqual(evolu.getMutationSize("note", values), buffer.getLength());
+
+      // `id` and `isDeleted` are not columns.
+      assertEqual(
+        evolu.getMutationSize("note", { id: noteId, isDeleted: 1 }),
+        evolu.getMutationSize("note", {}),
+      );
+
+      // @ts-expect-error Only the schema's tables can be measured.
+      evolu.getMutationSize("unknown", {});
+      // @ts-expect-error Values must match their column's Type.
+      evolu.getMutationSize("note", { body: 1 });
+    });
+
+    it("encodes no string in more than three bytes per code unit", async () => {
+      await using setup = await setupRunWithEvoluDeps();
+      const evolu = await setup.run.ok(createSizeEvolu);
+
+      const assertAtMostThreeBytesPerCodeUnit = (value: string) => {
+        // A string also takes a length varint of up to three bytes, besides
+        // the type tag that null takes too.
+        assertTrue(
+          evolu.getMutationSize("note", { body: value }) -
+            evolu.getMutationSize("note", { body: null }) <=
+            3 * value.length + 3,
+        );
+      };
+
+      for (const value of [
+        "",
+        "€".repeat(200_000),
+        "😀".repeat(1_000),
+        "\uD800".repeat(1_000),
+        // JSON takes exactly three bytes per code unit here.
+        "0.1",
+        `[${"0.1,".repeat(999)}0.1]`,
+        "[".repeat(1_001) + "]".repeat(1_001),
+        noteId,
+        "2024-01-01T00:00:00.000Z",
+      ]) {
+        assertAtMostThreeBytesPerCodeUnit(value);
+      }
+
+      fc.assert(
+        fc.property(
+          fc.oneof(fc.string(), fc.string({ unit: "binary" }), fc.json()),
+          assertAtMostThreeBytesPerCodeUnit,
+        ),
+        { numRuns: 2_000 },
+      );
+    });
+
+    it("rejects a mutation over maxMutationSize before batching it", async () => {
+      await using setup = await setupRunWithEvoluDeps();
+      const { run, evoluInputs, postEvoluOutput } = setup;
+      const evolu = await run.ok(createSizeEvolu);
+
+      const dataAtLimitLength = getDataAtLimitLength(evolu);
+      const atLimit = { data: new Uint8Array(dataAtLimitLength) };
+      assertEqual(evolu.getMutationSize("note", atLimit), maxMutationSize);
+      const completed: Array<string> = [];
+
+      const { id } = evolu.insert("note", atLimit, {
+        onComplete: () => {
+          completed.push("at limit");
+        },
+      });
+      const error = assertThrowsInstanceOf(
+        () =>
+          evolu.insert(
+            "note",
+            { data: new Uint8Array(dataAtLimitLength + 1) },
+            {
+              onComplete: () => {
+                completed.push("over limit");
+              },
+            },
+          ),
+        Error,
+      );
+      assertEqual(error.message, tooLargeMessage(maxMutationSize + 1));
+
+      await testWaitForWorkerMessage();
+
+      // The mutation made before the rejected one is sent as usual.
+      assertEqual(
+        getChanges(evoluInputs).map((change) => change.id),
+        [id],
+      );
+      const mutate = evoluInputs.find((input) => input.type === "Mutate");
+      assertNotUndefined(mutate);
+      postEvoluOutput({
+        type: "OnPatchesByQuery",
+        patchesByQuery: new Map(),
+        onCompleteIds: mutate.onCompleteIds,
+      });
+      await testWaitForWorkerMessage();
+      assertEqual(completed, ["at limit"]);
+    });
+
+    it("lets plain text use the whole limit at a byte per character", async () => {
+      await using setup = await setupRunWithEvoluDeps();
+      const { run, evoluInputs } = setup;
+      const evolu = await run.ok(createSizeEvolu);
+
+      // Spaces keep the text from being encoded as Base64Url, which is smaller.
+      // A long text's length varint takes two more bytes than a short one's.
+      const length =
+        maxMutationSize - evolu.getMutationSize("note", { body: " " }) - 1;
+      assertEqual(
+        evolu.getMutationSize("note", { body: " ".repeat(length) }),
+        maxMutationSize,
+      );
+      assertTrue(length > 639_900);
+
+      evolu.update("note", { id: noteId, body: " ".repeat(length) });
+      const error = assertThrowsInstanceOf(
+        () =>
+          evolu.update("note", { id: noteId, body: " ".repeat(length + 1) }),
+        Error,
+      );
+      assertEqual(error.message, tooLargeMessage(maxMutationSize + 1));
+
+      await testWaitForWorkerMessage();
+      assertLength(getChanges(evoluInputs), 1);
+    });
+
+    it("saves a copy of each binary value", async () => {
+      await using setup = await setupRunWithEvoluDeps();
+      const { run, evoluInputs } = setup;
+      const evolu = await run.ok(createSizeEvolu);
+
+      const resizable = new ArrayBuffer(3, { maxByteLength: 8 });
+      const growing = new Uint8Array(resizable);
+      growing.set([1, 2, 3]);
+      const shared = new Uint8Array(new SharedArrayBuffer(3));
+      shared.set([4, 5, 6]);
+      const nodeBuffer = Buffer.from([7, 8, 9]);
+
+      evolu.insert("note", { data: growing });
+      evolu.insert("note", { data: shared });
+      evolu.insert("note", { data: nodeBuffer });
+
+      // Changes made before the batch is sent do not reach it.
+      resizable.resize(8);
+      growing.fill(0);
+      shared.fill(0);
+      nodeBuffer.fill(0);
+
+      await testWaitForWorkerMessage();
+
+      const saved = getChanges(evoluInputs).map((change) => change.values.data);
+      assertEqual(saved, [
+        new Uint8Array([1, 2, 3]),
+        new Uint8Array([4, 5, 6]),
+        new Uint8Array([7, 8, 9]),
+      ]);
+      for (const data of saved) {
+        assert(data instanceof Uint8Array, "Expected a Uint8Array.");
+        assertSame(Object.getPrototypeOf(data), Uint8Array.prototype);
+        assertFalse(data.buffer instanceof SharedArrayBuffer);
+        assertFalse((data.buffer as ArrayBuffer).resizable);
+      }
+    });
+
+    it("does not limit local-only tables but copies their binary values", async () => {
+      await using setup = await setupRunWithEvoluDeps();
+      const { run, evoluInputs } = setup;
+      const evolu = await run.ok(createSizeEvolu);
+
+      const data = new Uint8Array(maxMutationSize + 1);
+      evolu.insert("_note", { data });
+      data[0] = 1;
+
+      await testWaitForWorkerMessage();
+
+      const [change] = getChanges(evoluInputs);
+      assertNotUndefined(change);
+      const saved = change.values.data;
+      assert(saved instanceof Uint8Array, "Expected a Uint8Array.");
+      assertNotSame(saved, data);
+      assertEqual(saved.byteLength, maxMutationSize + 1);
+      assertEqual(saved[0], 0);
+    });
+
+    it("fits a change at the limit into one message next to the largest ranges section", async () => {
+      await using setup = await setupRunWithEvoluDeps();
+      const evolu = await setup.run.ok(createSizeEvolu);
+      const deps = testCreateDeps();
+      const values = { data: new Uint8Array(getDataAtLimitLength(evolu)) };
+      assertEqual(evolu.getMutationSize("note", values), maxMutationSize);
+
+      const message = {
+        timestamp: createTimestamp(),
+        change: DbChange.orThrow({
+          table: "note",
+          id: noteId,
+          values,
+          isInsert: true,
+          isDelete: null,
+        }),
+      };
+
+      // A request and a broadcast assert that the change fits.
+      createProtocolMessageFromCrdtMessages(deps)(testAppOwner, [message]);
+      createProtocolBroadcastMessagesFromCrdtMessages(deps)(testAppOwner, [
+        message,
+      ]);
+
+      // A relay's response can pair it with the largest ranges section.
+      const rangesMaxSize = ProtocolMessageRangesMaxSize.orThrow(100_000);
+      const timestamps = createTimestampsBuffer();
+      for (let index = 1; timestamps.getLength() < 99_900; index++) {
+        timestamps.add(
+          createTimestamp({
+            millis: createTimestamp().millis,
+            nodeId: index.toString(16).padStart(16, "0") as NodeId,
+          }),
+        );
+      }
+      const response = createProtocolMessageBuffer(testAppOwner.id, {
+        messageType: MessageType.Response,
+        errorCode: ProtocolErrorCode.NoError,
+        rangesMaxSize,
+      });
+      assertTrue(
+        response.canAddTimestampsRangeAndMessage(timestamps, {
+          timestamp: message.timestamp,
+          change: encodeAndEncryptDbChange(deps)(
+            message,
+            testAppOwner.encryptionKey,
+          ),
+        }),
+      );
+    });
+  });
+
   describe("exportDatabase", () => {
     it("throws when OnExport arrives without pending export", async () => {
       const channels: Array<{