@evolu/common 8.11.0 → 8.13.0

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

@@ -5,15 +5,13 @@
  */
 import type { NonEmptyReadonlyArray } from "../Array.ts";
 import type { Brand } from "../Brand.ts";
-import type { DecryptWithXChaCha20Poly1305Error } from "../Crypto.ts";
 import type { RandomDep } from "../Random.ts";
 import type { SqliteDep } from "../Sqlite.ts";
 import type { Task } from "../Task.ts";
-import { Boolean, Id, type InferType, NonNegativeInt, Null, type ObjectType, PositiveInt, String, type Typed, type TypeError, type UnionType } from "../Type.ts";
+import { Boolean, Id, type InferType, NonNegativeInt, Null, type ObjectType, String, type Typed, type TypeError, type UnionType } from "../Type.ts";
 import type { Awaitable } from "../Types.ts";
 import type { OwnerError, OwnerIdBytes } from "./Owner.ts";
 import { OwnerId, OwnerWriteKey } from "./Owner.ts";
-import type { ProtocolInvalidDataError, ProtocolTimestampMismatchError } from "./Protocol.ts";
 import { Timestamp, TimestampBytes } from "./Timestamp.ts";
 /**
  * Configuration for {@link Storage}, such as quota checks.
@@ -36,9 +34,10 @@ export interface StorageConfig {
      * The callback returns a boolean rather than an error because error handling
      * and logging are the responsibility of the callback implementation.
      *
-     * Relay deployments configure this callback. Client applications can observe
-     * a denied relay write as a `ProtocolQuotaError` by subscribing once to the
-     * shared `EvoluErrorDep.evoluError` store returned by `createEvoluDeps`.
+     * Relay deployments configure this callback. Client applications observe a
+     * denied relay write as a {@link ProtocolQuotaError} in the `failure` of that
+     * relay's route, which {@link syncStateToOwnerSyncStatus} reports as the
+     * owner's `Error` status.
      *
      * ### Example
      *
@@ -71,7 +70,7 @@ export interface StorageConfig {
      * );
      * ```
      */
-    readonly isOwnerWithinQuota: (ownerId: OwnerId, requiredBytes: PositiveInt) => Awaitable<boolean>;
+    readonly isOwnerWithinQuota: (ownerId: OwnerId, requiredBytes: NonNegativeInt) => Awaitable<boolean>;
 }
 /**
  * Replica storage used by Evolu's synchronization protocol.
@@ -123,7 +122,10 @@ export interface Storage {
      * Write encrypted {@link CrdtMessage}s to storage.
      *
      * Stores none of the messages and returns the cause when the batch cannot be
-     * accepted.
+     * accepted. A client storage that cannot decrypt, verify, or decode a message
+     * skips it and stores the rest, as the built-in client storage does, because
+     * the peer offers the message again in every round, and rejecting the batch
+     * would end each round.
      *
      * Must use a mutex per ownerId to ensure sequential processing and proper
      * protocol logic handling during sync operations.
@@ -152,15 +154,17 @@ export interface StorageQuotaError extends OwnerError, Typed<"StorageQuotaError"
 /**
  * Expected reasons why {@link Storage.writeMessages} stored none of a batch.
  *
- * Each implementation returns the members that apply to it. The built-in relay
- * storage currently stores opaque encrypted messages and rejects batches over
- * quota. The built-in client storage decrypts and validates incoming messages
- * before updating its clock and database tables. The contract permits quota
- * checks on either side.
+ * The built-in relay storage stores opaque encrypted messages and rejects
+ * batches over quota. The built-in client storage decrypts and validates
+ * incoming messages before updating its clock and database tables. It skips a
+ * message that fails instead of rejecting its batch, and sync state shows it as
+ * the route's `skippedError` without ending the sync round, so a message is
+ * never a reason to reject a batch. The contract permits quota checks on either
+ * side.
  *
  * @group Core
  */
-export type StorageWriteMessagesError = DecryptWithXChaCha20Poly1305Error | ProtocolInvalidDataError | ProtocolTimestampMismatchError | StorageQuotaError;
+export type StorageWriteMessagesError = StorageQuotaError;
 /**
  * A cryptographic hash used for efficiently comparing collections of
  * {@link TimestampBytes}es.
@@ -465,5 +469,5 @@ export declare const readOwnerUsageOrDefault: (deps: SqliteDep) => (ownerIdBytes
  *
  * @group SQLite
  */
-export declare const updateOwnerUsage: (deps: SqliteDep) => (ownerIdBytes: OwnerIdBytes, storedBytes: PositiveInt, firstTimestamp: TimestampBytes, lastTimestamp: TimestampBytes) => void;
+export declare const updateOwnerUsage: (deps: SqliteDep) => (ownerIdBytes: OwnerIdBytes, storedBytes: NonNegativeInt, firstTimestamp: TimestampBytes, lastTimestamp: TimestampBytes) => void;
 //# sourceMappingURL=Storage.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Storage.d.ts","sourceRoot":"","sources":["../../../src/local-first/Storage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Storage.d.ts","sourceRoot":"","sources":["../../../src/local-first/Storage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAGzD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvC,OAAO,EACL,OAAO,EAEP,EAAE,EACF,KAAK,SAAS,EAEd,cAAc,EACd,IAAI,EAGJ,KAAK,UAAU,EAGf,MAAM,EACN,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAS,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAClE,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIpD,OAAO,EAGL,SAAS,EACT,cAAc,EACf,MAAM,gBAAgB,CAAC;AAExB;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkDG;IACH,QAAQ,CAAC,kBAAkB,EAAE,CAC3B,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,cAAc,KAC1B,SAAS,CAAC,OAAO,CAAC,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,cAAc,CAAC;IAE5D,QAAQ,CAAC,WAAW,EAAE,CACpB,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,cAAc,KAChB,WAAW,CAAC;IAEjB;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,EAAE,CAC1B,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,EACtC,UAAU,CAAC,EAAE,eAAe,KACzB,aAAa,CAAC,gBAAgB,CAAC,CAAC;IAErC,QAAQ,CAAC,cAAc,EAAE,CACvB,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,cAAc,EACnB,UAAU,EAAE,eAAe,KACxB,cAAc,CAAC;IAEpB,QAAQ,CAAC,OAAO,EAAE,CAChB,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,CAAC,SAAS,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,KAAK,OAAO,KACpE,IAAI,CAAC;IAEV;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,CACzB,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,aAAa,KACpB,OAAO,CAAC;IAEb,kEAAkE;IAClE,QAAQ,CAAC,WAAW,EAAE,CACpB,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,aAAa,KACpB,IAAI,CAAC;IAEV;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,aAAa,EAAE,CACtB,YAAY,EAAE,YAAY,EAC1B,QAAQ,EAAE,qBAAqB,CAAC,oBAAoB,CAAC,KAClD,IAAI,CAAC,IAAI,EAAE,yBAAyB,CAAC,CAAC;IAE3C,qDAAqD;IACrD,QAAQ,CAAC,YAAY,EAAE,CACrB,OAAO,EAAE,YAAY,EACrB,SAAS,EAAE,cAAc,KACtB,iBAAiB,CAAC;IAEvB,mDAAmD;IACnD,QAAQ,CAAC,WAAW,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,CAAC;CACvD;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,iBACf,SAAQ,UAAU,EAAE,KAAK,CAAC,mBAAmB,CAAC;CAAG;AAEnD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,yBAAyB,GAAG,iBAAiB,CAAC;AAE1D;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,eAAe,kFAA2C,CAAC;AAExE;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAEvB,WAAW,CAAC;AAEjB;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;CACtC;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,kBAAkB,CAAC;AAElE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,eAE9B,CAAC;AACF;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,SAAS;aACpB,WAAW,EAAE,CAAC;aACd,IAAI,EAAE,CAAC;aACP,UAAU,EAAE,CAAC;CACL,CAAC;AAEX;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAEnE;;;;GAIG;AACH,MAAM,WAAW,SAAU,SAAQ,SAAS;IAC1C,QAAQ,CAAC,IAAI,EAAE,OAAO,SAAS,CAAC,IAAI,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAiB,SAAQ,SAAS;IACjD,QAAQ,CAAC,IAAI,EAAE,OAAO,SAAS,CAAC,WAAW,CAAC;IAC5C,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAgB,SAAQ,SAAS;IAChD,QAAQ,CAAC,IAAI,EAAE,OAAO,SAAS,CAAC,UAAU,CAAC;IAC3C,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;CACpD;AAED;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,SAAS,GAAG,gBAAgB,GAAG,eAAe,CAAC;AAEnE;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACpC;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,KAAK,CAAC,mBAAmB,CAAC,CAAC;AAExE;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;CAC3B;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,OAC5B,EAAE,UACE,MAAM,QACR,MAAM,KACX,WAYD,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,cAAc,w+BAA4C,CAAC;AACxE,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,MAAM,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,yjCAgB/B,CAAC;AACF,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAC,MAAM,CAAC;AAEpE;;;;GAIG;AACH,MAAM,WAAW,wBAAyB,SAAQ,SAAS,CAAC,qBAAqB,CAAC;IAChF,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAChD;AAED;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,OAAO,MAAM,CAAC;IAC9B,QAAQ,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,mBAAmB,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,OAAO,OAAO,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,SAAS,CAAC,OAAO,OAAO,EAAE,OAAO,IAAI,CAAC,CAAC,CAAC;CACtE,CAMC,CAAC;AACH,MAAM,WAAW,QAAS,SAAQ,SAAS,CAAC,OAAO,QAAQ,CAAC;CAAG;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAC7C,OAAO,EACP,kBAAkB,GAAG,aAAa,GAAG,eAAe,GAAG,cAAc,CACtE;IACC;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,CACxB,OAAO,EAAE,YAAY,EACrB,SAAS,EAAE,cAAc,EACzB,QAAQ,EAAE,8BAA8B,KACrC,OAAO,CAAC;IAEb;;;OAGG;IACH,QAAQ,CAAC,qBAAqB,EAAE,CAC9B,YAAY,EAAE,YAAY,EAC1B,eAAe,EAAE,qBAAqB,CAAC,cAAc,CAAC,KACnD,aAAa,CAAC,cAAc,CAAC,CAAC;CACpC;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,CAAC;CAC/C;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,SAAS,CAAC;AAEtD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,uBAAuB,SAC5B,iBAAiB,KACtB,iBA2FD,CAAC;AAMH;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,SAAU,SAAS,KAAG,IAgE/D,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,8BAA8B,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE7E;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,cAC1B,cAAc,kBACT,cAAc,iBACf,cAAc,KAC5B,CACD,QAAQ,EAAE,8BAA8B,EACxC,cAAc,EAAE,cAAc,EAC9B,aAAa,EAAE,cAAc,CAS9B,CAAC;AAoeF;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,cAC3B,cAAc,KACxB,WAGF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,eACxB,aAAa,CAAC,cAAc,CAAC,KACxC,WAUE,CAAC;AAkYN;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,SACvB,SAAS,eACN,YAAY,SAAS,cAAc,KAAG,cA4E/C,CAAC;AAEJ;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,SAC3B,SAAS,oBAEA,YAAY,oBACR,cAAc,KAC/B;IACD,QAAQ,CAAC,WAAW,EAAE,cAAc,GAAG,IAAI,CAAC;IAC5C,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,cAAc,CAAC;CA6BxC,CAAC;AAEJ;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,SACpB,SAAS,oBAEA,YAAY,eACb,cAAc,kBACX,cAAc,iBACf,cAAc,KAC5B,IAYF,CAAC"}

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

@@ -6,7 +6,7 @@
 import { sha256 } from "@noble/hashes/sha2.js";
 import { firstInArray, isNonEmptyArray } from "../Array.js";
 import { assert, assertNonNullable } from "../Assert.js";
-import { concatBytes } from "../Bytes.js";
+import { concatByteArrays } from "../Bytes.js";
 import { decrement } from "../Number.js";
 import { err, ok } from "../Result.js";
 import { sql, SqliteValue } from "../Sqlite.js";
@@ -116,7 +116,9 @@ export const createBaseSqliteStorage = (deps) => ({
         return insertTimestamp(deps)(ownerId, timestamp, level, strategy);
     },
     getExistingTimestamps: (ownerIdBytes, timestampsBytes) => {
-        const concatenatedTimestamps = concatBytes(...timestampsBytes);
+        // A batch can hold hundreds of thousands of timestamps, too many to spread
+        // into concatBytes.
+        const concatenatedTimestamps = concatByteArrays(timestampsBytes);
         const result = deps.sqlite.exec(sql `
       with recursive
         split_timestamps(timestampBytes, pos) as (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolu/common",
-  "version": "8.11.0",
+  "version": "8.13.0",
   "description": "TypeScript library and local-first platform",
   "keywords": [
     "evolu",

package/src/Bytes.test.ts

@@ -23,6 +23,7 @@ import {
   ByteSizeLiteralTiB,
   byteSizeToByteLength,
   type ByteSize,
+  concatByteArrays,
   createBuffer,
   createRunLengthEncoder,
   decodeFlags,
@@ -96,6 +97,32 @@ describe("BufferError", () => {
   });
 });
 
+describe("concatByteArrays", () => {
+  it("copies arrays into one", () => {
+    const first = new Uint8Array([1]);
+    const result = concatByteArrays([
+      first,
+      new Uint8Array(),
+      new Uint8Array([2, 3]),
+    ]);
+    assertEqual(result, new Uint8Array([1, 2, 3]));
+    assertEqual(concatByteArrays([]), new Uint8Array());
+
+    first[0] = 9;
+    assertEqual(result[0], 1);
+  });
+
+  it("copies more arrays than a call can spread", () => {
+    const arrays = Array.from(
+      { length: 200_000 },
+      (_, index) => new Uint8Array([index % 256]),
+    );
+    const result = concatByteArrays(arrays);
+    assertEqual(result.length, 200_000);
+    assertEqual(result[199_999], 199_999 % 256);
+  });
+});
+
 describe("Buffer", () => {
   it("extends, shifts, and resets bytes", () => {
     const buffer = createBuffer();

package/src/Bytes.ts

@@ -20,7 +20,11 @@
  * @module
  */
 
-import { bytesToUtf8, utf8ToBytes } from "@noble/ciphers/utils.js";
+import {
+  bytesToUtf8,
+  concatBytes as nobleConcatBytes,
+  utf8ToBytes,
+} from "@noble/ciphers/utils.js";
 import { assert } from "./Assert.ts";
 import { err, ok, type Result } from "./Result.ts";
 import { safelyStringifyUnknownValue } from "./String.ts";
@@ -44,9 +48,61 @@ import {
   union,
   type UnionError,
 } from "./Type.ts";
-export { bytesToHex, concatBytes, hexToBytes } from "@noble/ciphers/utils.js";
+export { bytesToHex, hexToBytes } from "@noble/ciphers/utils.js";
 export { bytesToUtf8, utf8ToBytes };
 
+/**
+ * Copies several Uint8Arrays into one.
+ *
+ * Each array is a separate argument, so it is meant for a few arrays. Spreading
+ * many arrays into it overflows the call stack; use {@link concatByteArrays}
+ * when their count is not bounded.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertEqual, concatBytes } from "@evolu/common";
+ *
+ * assertEqual(
+ *   concatBytes(new Uint8Array([1]), new Uint8Array([2, 3])),
+ *   new Uint8Array([1, 2, 3]),
+ * );
+ * ```
+ */
+export const concatBytes: typeof nobleConcatBytes = nobleConcatBytes;
+
+/**
+ * Copies an array of Uint8Arrays into one.
+ *
+ * Unlike {@link concatBytes}, it takes the arrays as one array, so it works for
+ * any number of them, such as the timestamps of a batch received from a peer.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertEqual, concatByteArrays } from "@evolu/common";
+ *
+ * assertEqual(
+ *   concatByteArrays([new Uint8Array([1]), new Uint8Array([2, 3])]),
+ *   new Uint8Array([1, 2, 3]),
+ * );
+ * ```
+ */
+export const concatByteArrays = (
+  arrays: ReadonlyArray<Uint8Array>,
+): Uint8Array => {
+  let length = 0;
+  for (const array of arrays) length += array.length;
+
+  const result = new Uint8Array(length);
+  let offset = 0;
+  for (const array of arrays) {
+    result.set(array, offset);
+    offset += array.length;
+  }
+  return result;
+};
+
 /**
  * Custom error for {@link Buffer}-related failures like premature end of data.
  * Provides better stack traces for debugging binary protocol issues.

package/src/Callbacks.test.ts

@@ -64,3 +64,23 @@ test("Callbacks dispose clears pending callbacks", () => {
 
   assertFalse(called);
 });
+
+test("Callbacks unregister removes a callback without executing it", () => {
+  const deps = testCreateDeps();
+  const callbacks = createCallbacks(deps);
+
+  let calls = 0;
+  const unregisteredId = callbacks.register(() => {
+    calls++;
+  });
+  const keptId = callbacks.register(() => {
+    calls += 10;
+  });
+
+  callbacks.unregister(unregisteredId);
+  callbacks.execute(unregisteredId);
+  assertSame(calls, 0);
+
+  callbacks.execute(keptId);
+  assertSame(calls, 10);
+});

package/src/Callbacks.ts

@@ -13,7 +13,8 @@ import type { Callback } from "./Types.ts";
  * Request-response correlation for callbacks across boundaries.
  *
  * Stores callbacks with unique IDs and executes them once with an optional
- * argument. Executed callbacks are automatically removed.
+ * argument. Executed callbacks are automatically removed. A callback whose
+ * response will never come is removed with `unregister`.
  *
  * This is useful for correlating asynchronous request-response operations
  * across boundaries where callback functions cannot be passed directly (e.g.,
@@ -43,6 +44,14 @@ import type { Callback } from "./Types.ts";
  * callbacks.execute(noArgumentId);
  * assertEqual(noArgumentCalls, 1);
  *
+ * // A callback whose response will never come
+ * const failedId = callbacks.register(() => {
+ *   noArgumentCalls++;
+ * });
+ * callbacks.unregister(failedId);
+ * callbacks.execute(failedId);
+ * assertEqual(noArgumentCalls, 1);
+ *
  * // Typed callback
  * using stringCallbacks = createCallbacks<string>(deps);
  * let received = "";
@@ -71,6 +80,9 @@ export interface Callbacks<T = undefined> extends Disposable {
   readonly execute: T extends undefined
     ? (id: Id) => undefined
     : (id: Id, arg: T) => undefined;
+
+  /** Removes a callback associated with the given ID without executing it. */
+  readonly unregister: (id: Id) => void;
 }
 
 /** Creates a {@link Callbacks} registry for managing callbacks. */
@@ -101,6 +113,10 @@ export const createCallbacks = <T = undefined>(
 
     execute,
 
+    unregister: (id) => {
+      callbackMap.delete(id);
+    },
+
     [Symbol.dispose]: () => {
       callbackMap.clear();
     },

package/src/Error.ts

@@ -18,7 +18,9 @@ import { type InferType, typed, type TypedType, Unknown } from "./Type.ts";
  * The `error` property contains error details (including `message`, `stack`,
  * and `cause` if available), a string, or a fallback value.
  *
- * Use {@link createUnknownError} to create instances.
+ * Use {@link createUnknownError} to create instances. It turns an `Error` into a
+ * plain object, so the error can be posted between workers, for example in sync
+ * state, with its message and stack.
  */
 export const UnknownError: TypedType<
   "UnknownError",
@@ -31,9 +33,13 @@ export interface UnknownError extends InferType<typeof UnknownError> {}
 /**
  * Creates an {@link UnknownError} from an unknown error.
  *
- * Error objects cannot be directly structured-cloned (for worker messaging) or
- * JSON-serialized because their properties (`message`, `stack`, `cause`) are
- * non-enumerable. This function extracts those properties into a plain object.
+ * An `Error` becomes a plain object of its own properties, such as `message`
+ * and `stack`. A `cause` that is an `Error` is converted the same way, a
+ * function is dropped, and any other property is kept as it is. An `Error`'s
+ * properties are not enumerable, so JSON and comparisons by content miss them,
+ * and a structured clone creates a new `Error`. Any other value is
+ * structured-cloned, or described by `String` when it cannot be, or as
+ * `"[Unserializable Object]"` when even that throws.
  */
 export const createUnknownError = (error: unknown): UnknownError => {
   const convertError = (err: Error): Record<string, unknown> => {

package/src/Object.test.ts

@@ -4,6 +4,7 @@ import {
   assertEqual,
   assertFalse,
   assertNonNullable,
+  assertNotSame,
   assertSame,
   assertTrue,
 } from "./Assert.ts";
@@ -25,6 +26,7 @@ import {
   objectFrom,
   objectFromEntries,
   objectToEntries,
+  shareStructure,
 } from "./Object.ts";
 import { assertType } from "./Type.ts";
 
@@ -356,6 +358,300 @@ test("excludeProp", () => {
   assertEqual(excluded, { b: 2, c: 3 });
 });
 
+describe("shareStructure", () => {
+  it("returns the previous value when the next one is deep-equal", () => {
+    const previous = {
+      name: "Alice",
+      tags: ["a", "b", Number.NaN],
+      nested: { items: [{ id: 1 }, { id: 2 }], missing: null },
+      count: Number.NaN,
+    };
+
+    assertSame(shareStructure(previous, structuredClone(previous)), previous);
+    assertSame(shareStructure(1, 1), 1);
+    const nullPrototype = Object.assign(Object.create(null) as object, {
+      a: 1,
+    });
+    assertSame(shareStructure(nullPrototype, { a: 1 }), nullPrototype);
+  });
+
+  it("keeps every unchanged part of a changed value", () => {
+    const previous = {
+      user: { name: "Alice" },
+      todos: [{ title: "Buy milk" }, { title: "Walk the dog" }],
+    };
+    const next = structuredClone(previous);
+    next.todos[1] = { title: "Walk the cat" };
+
+    const shared = shareStructure(previous, next);
+    assertNotSame(shared, previous);
+    assertEqual(shared, next);
+    assertSame(shared.user, previous.user);
+    assertNotSame(shared.todos, previous.todos);
+    assertSame(shared.todos[0], previous.todos[0]);
+    assertNotSame(shared.todos[1], previous.todos[1]);
+  });
+
+  it("treats added and removed keys and resized arrays as changes", () => {
+    const previous: Record<string, { readonly id: number }> = {
+      a: { id: 1 },
+      b: { id: 2 },
+    };
+
+    const added = shareStructure(previous, {
+      a: { id: 1 },
+      b: { id: 2 },
+      c: { id: 3 },
+    });
+    assertNotSame(added, previous);
+    assertSame(added.a, previous.a);
+
+    const removed = shareStructure(previous, { a: { id: 1 } });
+    assertNotSame(removed, previous);
+    assertEqual(removed, { a: { id: 1 } });
+    assertSame(removed.a, previous.a);
+
+    // A key whose value is undefined is still a key.
+    const withUndefined = shareStructure<Record<string, unknown>>(
+      { a: 1 },
+      { a: 1, b: undefined },
+    );
+    assertEqual(Object.keys(withUndefined), ["a", "b"]);
+    // So is a renamed key with the same number of keys.
+    const renamed = shareStructure<Record<string, unknown>>(
+      { a: undefined },
+      { b: undefined },
+    );
+    assertEqual(Object.keys(renamed), ["b"]);
+
+    const items = [{ id: 1 }, { id: 2 }];
+    const longer = shareStructure(items, [{ id: 1 }, { id: 2 }, { id: 3 }]);
+    assertNotSame(longer, items);
+    assertSame(longer[0], items[0]);
+    const shorter = shareStructure(items, [{ id: 1 }]);
+    assertNotSame(shorter, items);
+    assertEqual(shorter, [{ id: 1 }]);
+    // An item that is undefined is still an item.
+    assertEqual(shareStructure<ReadonlyArray<unknown>>([1], [1, undefined]), [
+      1,
+      undefined,
+    ]);
+  });
+
+  it("returns the next value when its kind differs", () => {
+    const object = { a: 1 };
+    const array = [1];
+    const bytes = Uint8Array.of(1);
+    const pairs: ReadonlyArray<readonly [unknown, unknown]> = [
+      [object, null],
+      [null, object],
+      [array, null],
+      [null, array],
+      [array, { 0: 1 }],
+      [bytes, null],
+      [null, bytes],
+      [array, bytes],
+    ];
+
+    for (const [previous, next] of pairs)
+      assertSame(shareStructure(previous, next), next);
+  });
+
+  it("compares the properties an object spread copies", () => {
+    const hidden = Object.defineProperty({ a: 1 }, "b", { value: 2 });
+    const shared = shareStructure<Record<string, unknown>>(hidden, { b: 2 });
+    assertNotSame(shared, hidden);
+    assertEqual(shared, { b: 2 });
+
+    const symbol = Symbol("symbol");
+    const plain = { a: 1 };
+    assertSame(
+      shareStructure<object>(
+        plain,
+        Object.defineProperty({ a: 1 }, symbol, { value: 2 }),
+      ),
+      plain,
+    );
+    const previous = { a: 1, [symbol]: { id: 1 } };
+    assertSame(shareStructure(previous, { ...previous }), previous);
+    const changedSymbol = shareStructure(previous, {
+      a: 1,
+      [symbol]: { id: 2 },
+    });
+    assertNotSame(changedSymbol, previous);
+    assertEqual(changedSymbol[symbol], { id: 2 });
+    const changedString = shareStructure(previous, { ...previous, a: 2 });
+    assertSame(changedString[symbol], previous[symbol]);
+    const withoutSymbol = shareStructure<object>(previous, { a: 1 });
+    assertNotSame(withoutSymbol, previous);
+    assertFalse(symbol in withoutSymbol);
+  });
+
+  it("returns a part that a cycle leads back to as it is in the next value", () => {
+    interface Node {
+      readonly id: number;
+      readonly items: Array<unknown>;
+    }
+    const createValue = () => {
+      const node: Node = { id: 1, items: [] };
+      node.items.push(node);
+      return { unchanged: { id: 2 }, node };
+    };
+    const previous = createValue();
+    const next = createValue();
+
+    const shared = shareStructure(previous, next);
+    assertSame(shared.unchanged, previous.unchanged);
+    assertSame(shared.node, next.node);
+    assertSame(shared.node.items[0], shared.node);
+    assertSame(shareStructure(previous.node, next.node), next.node);
+  });
+
+  it("compares a part referenced from several places at each place", () => {
+    const shared = { id: 1 };
+    const previous = { a: shared, b: shared };
+
+    assertSame(shareStructure(previous, structuredClone(previous)), previous);
+  });
+
+  it("compares an array item with the previous item of the same key", () => {
+    const itemToKey = (item: unknown): unknown =>
+      isPlainObject(item) ? item.id : undefined;
+    const previous = {
+      items: [
+        { id: 1, meta: { tag: "a" } },
+        { id: 2, meta: { tag: "b" } },
+        { id: 3, meta: { tag: "c" } },
+      ],
+    };
+
+    // Removing an item keeps the objects of the items after it.
+    const removed = shareStructure(
+      previous,
+      { items: [structuredClone(previous.items[1]), { id: 3, meta: null }] },
+      itemToKey,
+    );
+    assertEqual(removed, {
+      items: [
+        { id: 2, meta: { tag: "b" } },
+        { id: 3, meta: null },
+      ],
+    });
+    assertSame(removed.items[0], previous.items[1]);
+
+    // Moved items keep their objects in a new array.
+    const moved = shareStructure(
+      previous,
+      { items: structuredClone(previous.items).toReversed() },
+      itemToKey,
+    );
+    assertNotSame(moved.items, previous.items);
+    assertSame(moved.items[0], previous.items[2]);
+    assertSame(moved.items[2], previous.items[0]);
+
+    // A changed item keeps its unchanged parts.
+    const changed = shareStructure<ReadonlyArray<Record<string, unknown>>>(
+      previous.items,
+      [{ id: 2, meta: { tag: "b" }, done: true }],
+      itemToKey,
+    );
+    assertSame(changed[0]?.meta, previous.items[1].meta);
+
+    // An item with a new key has no previous item to share with.
+    const added = shareStructure(
+      previous.items,
+      [{ id: 4, meta: { tag: "a" } }],
+      itemToKey,
+    );
+    assertNotSame(added[0]?.meta, previous.items[0].meta);
+
+    // An item without a key is compared with the item at its index.
+    const unkeyed = [{ tag: "a" }, { tag: "b" }];
+    assertSame(
+      shareStructure(unkeyed, structuredClone(unkeyed), itemToKey),
+      unkeyed,
+    );
+  });
+
+  it("compares Uint8Arrays by their bytes", () => {
+    const previous = { blob: Uint8Array.of(1, 2, 3) };
+
+    assertSame(shareStructure(previous, structuredClone(previous)), previous);
+    const changed = shareStructure(previous, { blob: Uint8Array.of(1, 2, 4) });
+    assertNotSame(changed, previous);
+    assertEqual(changed.blob, Uint8Array.of(1, 2, 4));
+    assertNotSame(
+      shareStructure(previous, { blob: Uint8Array.of(1, 2) }),
+      previous,
+    );
+    assertNotSame(
+      shareStructure(previous, { blob: Uint8Array.of(1, 2, 3, 4) }),
+      previous,
+    );
+  });
+
+  it("compares a hole in an array as a missing item", () => {
+    const previous = [1, 2, 3];
+    // oxlint-disable-next-line no-sparse-arrays -- The hole is what is tested.
+    const next = [1, , 3];
+
+    const shared = shareStructure<ReadonlyArray<number | undefined>>(
+      previous,
+      next,
+    );
+    assertNotSame(shared, previous);
+    assertSame(shared[1], undefined);
+
+    // A hole in a keyed previous array has no key.
+    // oxlint-disable-next-line no-sparse-arrays -- The hole is what is tested.
+    const sparse = [, { id: 1 }];
+    const keyed = shareStructure<ReadonlyArray<unknown>>(
+      sparse,
+      [{ id: 1 }],
+      (item) => (isPlainObject(item) ? item.id : undefined),
+    );
+    assertEqual(keyed, [{ id: 1 }]);
+    assertSame(keyed[0], sparse[1]);
+  });
+
+  it("compares values other than plain objects and arrays by identity", () => {
+    const date = new Date(0);
+    assertNotSame(shareStructure(date, new Date(0)), date);
+
+    class Example {
+      readonly value = "example";
+    }
+    const example = new Example();
+    assertNotSame(shareStructure(example, new Example()), example);
+
+    assertTrue(Object.is(shareStructure(0, -0), -0));
+  });
+
+  it("keeps a __proto__ key as own data of an ordinary object", () => {
+    const next = JSON.parse(
+      '{"__proto__": {"polluted": true}, "b": 1}',
+    ) as Record<string, unknown>;
+
+    const shared = shareStructure<Record<string, unknown>>({ b: 2 }, next);
+    assertSame(Object.getPrototypeOf(shared), Object.prototype);
+    assertTrue(Object.hasOwn(shared, "__proto__"));
+    assertEqual(Object.getOwnPropertyDescriptor(shared, "__proto__")?.value, {
+      polluted: true,
+    });
+    assertFalse("polluted" in {});
+
+    // An empty `__proto__` value is not mistaken for Object.prototype.
+    const empty = shareStructure<Record<string, unknown>>(
+      {},
+      JSON.parse('{"__proto__": {}}') as Record<string, unknown>,
+    );
+    assertNotSame(
+      Object.getOwnPropertyDescriptor(empty, "__proto__")?.value,
+      Object.prototype,
+    );
+  });
+});
+
 test("createMutableRecord", () => {
   const values = createMutableRecord<string, number>();
   values.__proto__ = 123;