@evolu/common 8.12.0 → 8.13.0

package/src/Object.ts

@@ -305,6 +305,169 @@ export const excludeProp = <T extends object, K extends keyof T>(
   return rest;
 };
 
+/**
+ * Returns `next` with every part deep-equal to the same part of `previous`
+ * replaced by that part, or `previous` itself when the two are deep-equal.
+ *
+ * It keeps the identity of data that arrives as a new copy, such as a
+ * structured clone posted between workers, so unchanged parts can be compared
+ * with `===`, and a UI updates only what changed. Plain objects, arrays, and
+ * `Uint8Array`s are compared by their contents, and any other value by
+ * identity. The contents of a plain object are the properties an object spread
+ * copies. A changed object or array is returned as a new ordinary one. It walks
+ * the data as a tree, so a part referenced from several places is compared at
+ * each place, and a part that a cycle leads back to is returned as it is in
+ * `next`.
+ *
+ * An array item is compared with the previous item at its index, so removing or
+ * inserting an item compares every item after it with a different one. When
+ * `itemToKey` returns a key for an item, such as its ID, the item is compared
+ * with the previous item of the same key instead. Keys are compared as `Map`
+ * keys are, so each should be unique in its array; an item whose key several
+ * previous items share is compared with the last of them.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertNotSame,
+ *   assertSame,
+ *   isPlainObject,
+ *   shareStructure,
+ * } from "@evolu/common";
+ *
+ * const previous = {
+ *   user: { name: "Alice" },
+ *   todos: [{ title: "Buy milk" }],
+ * };
+ *
+ * // An equal copy gives the previous value back.
+ * assertSame(
+ *   shareStructure(previous, structuredClone(previous)),
+ *   previous,
+ * );
+ *
+ * // A change keeps every unchanged part.
+ * const next = shareStructure(previous, {
+ *   user: { name: "Alice" },
+ *   todos: [{ title: "Buy bread" }],
+ * });
+ * assertNotSame(next, previous);
+ * assertSame(next.user, previous.user);
+ * assertNotSame(next.todos, previous.todos);
+ *
+ * // A key compares each todo with the previous todo of the same ID.
+ * const todos = [
+ *   { id: 1, title: "Buy milk" },
+ *   { id: 2, title: "Walk the dog" },
+ * ];
+ * const remaining = shareStructure(
+ *   todos,
+ *   [{ id: 2, title: "Walk the dog" }],
+ *   (todo) => (isPlainObject(todo) ? todo.id : undefined),
+ * );
+ * assertSame(remaining[0], todos[1]);
+ * ```
+ */
+export const shareStructure = <T>(
+  previous: T,
+  next: T,
+  itemToKey?: (item: unknown) => unknown,
+): T => {
+  // The arrays and plain objects of `next` being compared, each with whether a
+  // cycle led back to it.
+  const isCycledByPart = new Map<object, boolean>();
+
+  const share = (previous: unknown, next: unknown): unknown => {
+    if (Object.is(previous, next)) return previous;
+
+    if (Array.isArray(previous) && Array.isArray(next)) {
+      const previousItems: ReadonlyArray<unknown> = previous;
+      return visit(next, () => {
+        // Array.from visits holes, which map would skip or keep as holes.
+        const previousByKey =
+          itemToKey &&
+          new Map(Array.from(previousItems, (item) => [itemToKey(item), item]));
+        let isEqual = previousItems.length === next.length;
+        const shared = Array.from(next, (item: unknown, index) => {
+          const key = itemToKey?.(item);
+          const previousItem =
+            key === undefined ? previousItems[index] : previousByKey?.get(key);
+          const sharedItem = share(previousItem, item);
+          if (!Object.is(sharedItem, previousItems[index])) isEqual = false;
+          return sharedItem;
+        });
+        return isEqual ? previousItems : shared;
+      });
+    }
+
+    if (isPlainObject(previous) && isPlainObject(next))
+      return visit(next, () => {
+        const keys = ownEnumerableKeys(next);
+        let isEqual = keys.length === ownEnumerableKeys(previous).length;
+        // Object.fromEntries defines each key, so `__proto__` stays own data.
+        const shared = Object.fromEntries(
+          keys.map((key) => {
+            const hasPrevious = Object.prototype.propertyIsEnumerable.call(
+              previous,
+              key,
+            );
+            const previousValue = hasPrevious
+              ? (previous as Record<PropertyKey, unknown>)[key]
+              : undefined;
+            const value = share(
+              previousValue,
+              (next as Record<PropertyKey, unknown>)[key],
+            );
+            if (!hasPrevious || !Object.is(value, previousValue))
+              isEqual = false;
+            return [key, value];
+          }),
+        );
+        return isEqual ? previous : shared;
+      });
+
+    // An indexed loop compares bytes far faster than `every`.
+    if (previous instanceof Uint8Array && next instanceof Uint8Array) {
+      if (previous.length !== next.length) return next;
+      for (let index = 0; index < previous.length; index++)
+        if (previous[index] !== next[index]) return next;
+      return previous;
+    }
+
+    return next;
+  };
+
+  // A cycle refers back to the part of `next` itself, so the part it leads back
+  // to is returned as it is, which keeps the cycle intact.
+  const visit = (part: object, compare: () => unknown): unknown => {
+    if (isCycledByPart.has(part)) {
+      isCycledByPart.set(part, true);
+      return part;
+    }
+    isCycledByPart.set(part, false);
+    const shared = compare();
+    const isCycled = isCycledByPart.get(part);
+    isCycledByPart.delete(part);
+    return isCycled ? part : shared;
+  };
+
+  return share(previous, next) as T;
+};
+
+// The keys an object spread copies: own enumerable strings and symbols.
+const ownEnumerableKeys = (object: object): ReadonlyArray<PropertyKey> => {
+  const symbols = Object.getOwnPropertySymbols(object);
+  return symbols.length === 0
+    ? Object.keys(object)
+    : [
+        ...Object.keys(object),
+        ...symbols.filter((symbol) =>
+          Object.prototype.propertyIsEnumerable.call(object, symbol),
+        ),
+      ];
+};
+
 /**
  * Creates a mutable Record.
  *

package/src/Resource.test.ts

@@ -77,7 +77,6 @@ const idleMutexSnapshot = {
   taken: 0,
   waiters: [],
   available: 1,
-  isIdle: true,
 };
 
 describe("BorrowedResource", () => {
@@ -672,7 +671,6 @@ describe("SharedResource", () => {
       );
 
       assertEqual(sharedResource.snapshot(), {
-        isIdle: true,
         leaseCount: 0,
         hasResource: false,
         idleDisposePending: false,
@@ -682,7 +680,6 @@ describe("SharedResource", () => {
       const lease = await run.ok(sharedResource.acquire);
 
       assertEqual(sharedResource.snapshot(), {
-        isIdle: false,
         leaseCount: 1,
         hasResource: true,
         idleDisposePending: false,
@@ -692,7 +689,6 @@ describe("SharedResource", () => {
       lease.release();
 
       assertEqual(sharedResource.snapshot(), {
-        isIdle: false,
         leaseCount: 0,
         hasResource: true,
         idleDisposePending: true,
@@ -713,7 +709,6 @@ describe("SharedResource", () => {
       lease.release();
 
       assertEqual(sharedResource.snapshot(), {
-        isIdle: false,
         leaseCount: 0,
         hasResource: true,
         idleDisposePending: false,
@@ -723,14 +718,13 @@ describe("SharedResource", () => {
           taken: 1,
           waiters: [],
           available: 0,
-          isIdle: false,
         },
       });
 
       await disposed;
     });
 
-    it("reports not idle while creating the first resource", async () => {
+    it("reports the held mutex while creating the first resource", async () => {
       await using run = testCreateRun();
       const gate = createGate();
 
@@ -742,11 +736,22 @@ describe("SharedResource", () => {
       );
 
       const acquire = run.ok(sharedResource.acquire);
-      const isIdleWhileCreating = sharedResource.snapshot().isIdle;
+      const snapshotWhileCreating = sharedResource.snapshot();
       gate.open();
       await acquire;
 
-      assertFalse(isIdleWhileCreating);
+      assertEqual(snapshotWhileCreating, {
+        leaseCount: 0,
+        hasResource: false,
+        idleDisposePending: false,
+        mutex: {
+          policy: "fifo",
+          permits: 1,
+          taken: 1,
+          waiters: [],
+          available: 0,
+        },
+      });
     });
 
     it("reports mutex waiters during a contended acquire", async () => {
@@ -953,9 +958,12 @@ describe("SharedResource", () => {
       await sharedResource[Symbol.asyncDispose]();
 
       assertEqual(resources.getDisposeCount(), 1);
-      const snapshot = sharedResource.snapshot();
-      assertTrue(snapshot.isIdle);
-      assertFalse(snapshot.idleDisposePending);
+      assertEqual(sharedResource.snapshot(), {
+        leaseCount: 0,
+        hasResource: false,
+        idleDisposePending: false,
+        mutex: idleMutexSnapshot,
+      });
     });
 
     it("awaits async resource disposal", async () => {
@@ -2774,7 +2782,6 @@ describe("SharedResourceByKey", () => {
           [
             "a",
             {
-              isIdle: false,
               leaseCount: 2,
               hasResource: true,
               idleDisposePending: false,
@@ -2784,7 +2791,6 @@ describe("SharedResourceByKey", () => {
           [
             "b",
             {
-              isIdle: false,
               leaseCount: 1,
               hasResource: true,
               idleDisposePending: false,
@@ -5412,7 +5418,6 @@ describe("SharedResourceByKeyWithClaims", () => {
           [
             "a",
             {
-              isIdle: false,
               leaseCount: 3,
               hasResource: true,
               idleDisposePending: false,
@@ -5422,7 +5427,6 @@ describe("SharedResourceByKeyWithClaims", () => {
           [
             "b",
             {
-              isIdle: false,
               leaseCount: 1,
               hasResource: true,
               idleDisposePending: false,

package/src/Resource.ts

@@ -279,12 +279,6 @@ export interface SharedResource<T extends Resource> extends AsyncDisposable {
 
 /** Snapshot returned by {@link SharedResource.snapshot}. */
 export interface SharedResourceSnapshot {
-  /**
-   * Whether the resource has no current value, no leases, no pending idle
-   * disposal, and no acquisition in progress.
-   */
-  readonly isIdle: boolean;
-
   /** Current active lease count. */
   readonly leaseCount: NonNegativeInt;
 
@@ -498,20 +492,12 @@ export const createSharedResource =
         return await run(callback(lease.resource, lease.created));
       },
 
-      snapshot: () => {
-        const mutexSnapshot = mutex.snapshot();
-        return {
-          isIdle:
-            heldLeases.size === 0 &&
-            !current &&
-            !idleDisposeFiber &&
-            mutexSnapshot.isIdle,
-          leaseCount: NonNegativeInt.orThrow(heldLeases.size),
-          hasResource: current !== undefined,
-          idleDisposePending: idleDisposeFiber !== undefined,
-          mutex: mutexSnapshot,
-        };
-      },
+      snapshot: () => ({
+        leaseCount: NonNegativeInt.orThrow(heldLeases.size),
+        hasResource: current !== undefined,
+        idleDisposePending: idleDisposeFiber !== undefined,
+        mutex: mutex.snapshot(),
+      }),
 
       [Symbol.asyncDispose]: () => sharedResourceRun[Symbol.asyncDispose](),
     };

package/src/Sqlite.ts

@@ -375,6 +375,13 @@ export const createSqlite =
             console.debug("begin");
             driver.exec(sql`begin;`);
 
+            // After errors such as SQLITE_FULL or SQLITE_IOERR, SQLite may roll
+            // back the transaction itself, and this rollback then fails with
+            // "no transaction is active". Disposal wraps both in a
+            // SuppressedError whose `suppressed` holds the original error. The
+            // data is consistent and nothing is lost.
+            // TODO: Rethink this when Evolu detects SQLITE_FULL, which needs
+            // the original error, not the failed rollback.
             using rollback = new DisposableStack();
             let shouldRollback = true;
             rollback.defer(() => {