@evolu/common 8.4.0 → 8.6.0

package/dist/src/Eq.js

@@ -3,38 +3,48 @@
  *
  * @module
  */
+import { getObjectKind } from "./Object.js";
 /**
- * Compares two values with strict equality (`===`).
+ * Compares two values using SameValue equality (`Object.is`).
  *
- * Strict equality considers `NaN` unequal to itself. Use {@link eqSameValueZero}
- * when values can contain `NaN` and equality must be reflexive.
+ * SameValue considers `NaN` equal to itself, distinguishes `0` from `-0`, and
+ * compares objects by reference identity.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertFalse, assertTrue, eqStrict } from "@evolu/common";
+ *
+ * assertTrue(eqStrict(NaN, NaN));
+ * assertFalse(eqStrict(0, -0));
+ * ```
  */
-export const eqStrict = (x, y) => x === y;
+export const eqStrict = (x, y) => Object.is(x, y);
 /**
  * Compares two values using SameValueZero equality.
  *
  * SameValueZero is the standard equality algorithm used by `Map`, `Set`, and
- * `Array.prototype.includes`. It behaves like strict equality except that `NaN`
- * equals itself. Both algorithms consider `0` and `-0` equal.
+ * `Array.prototype.includes`. Like SameValue, it considers `NaN` equal to
+ * itself, but unlike SameValue, it considers `0` and `-0` equal.
  *
  * ### Example
  *
  * ```ts
- * import { eqSameValueZero } from "@evolu/common";
+ * import { assertFalse, assertTrue, eqSameValueZero } from "@evolu/common";
  *
- * expect(eqSameValueZero(NaN, NaN)).toBe(true);
- * expect(eqSameValueZero(0, -0)).toBe(true);
- * expect(eqSameValueZero({}, {})).toBe(false);
+ * assertTrue(eqSameValueZero(NaN, NaN));
+ * assertTrue(eqSameValueZero(0, -0));
+ * assertFalse(eqSameValueZero({}, {}));
  * ```
  */
 export const eqSameValueZero = (x, y) => x === y || Object.is(x, y);
-/** An {@link Eq} for strings using strict equality. */
+/** An {@link Eq} for strings using {@link eqStrict}. */
 export const eqString = eqStrict;
 /** An {@link Eq} for numbers using {@link eqSameValueZero}. */
 export const eqNumber = eqSameValueZero;
-/** An {@link Eq} for bigints using strict equality. */
+/** An {@link Eq} for bigints using {@link eqStrict}. */
 export const eqBigInt = eqStrict;
-/** An {@link Eq} for booleans using strict equality. */
+/** An {@link Eq} for booleans using {@link eqStrict}. */
 export const eqBoolean = eqStrict;
 /** An {@link Eq} for `undefined`. */
 export const eqUndefined = eqStrict;
@@ -49,15 +59,20 @@ export const eqFromOrder = (order) => (x, y) => order(x, y) === 0;
  * ### Example
  *
  * ```ts
- * import { createEqArrayLike, eqNumber } from "@evolu/common";
+ * import {
+ *   assertFalse,
+ *   assertTrue,
+ *   createEqArrayLike,
+ *   eqNumber,
+ * } from "@evolu/common";
  *
  * const eqArrayNumber = createEqArrayLike(eqNumber);
  *
- * expect(eqArrayNumber([1, 2, 3], [1, 2, 3])).toBe(true);
- * expect(
+ * assertTrue(eqArrayNumber([1, 2, 3], [1, 2, 3]));
+ * assertTrue(
  *   eqArrayNumber(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3])),
- * ).toBe(true);
- * expect(eqArrayNumber([1, 2, 3], [1, 2, 4])).toBe(false);
+ * );
+ * assertFalse(eqArrayNumber([1, 2, 3], [1, 2, 4]));
  * ```
  */
 export const createEqArrayLike = (item) => (x, y) => {
@@ -72,19 +87,20 @@ export const createEqArrayLike = (item) => (x, y) => {
     return true;
 };
 /**
- * Compares two array-like structures by strict reference equality (`===`).
+ * Compares two array-like structures element by element using {@link eqStrict}.
  *
- * Useful for structural sharing checks where elements are compared by identity.
+ * Useful for structural sharing checks where objects are compared by reference
+ * identity. `NaN` elements are equal, while `0` and `-0` elements differ.
  *
  * ### Example
  *
  * ```ts
- * import { eqArrayStrict } from "@evolu/common";
+ * import { assertFalse, assertTrue, eqArrayStrict } from "@evolu/common";
  *
  * const a = { x: 1 };
  * const b = { x: 1 };
- * expect(eqArrayStrict([a, a], [a, a])).toBe(true);
- * expect(eqArrayStrict([a], [b])).toBe(false);
+ * assertTrue(eqArrayStrict([a, a], [a, a]));
+ * assertFalse(eqArrayStrict([a], [b]));
  * ```
  */
 export const eqArrayStrict = /*#__PURE__*/ createEqArrayLike(eqStrict);
@@ -94,12 +110,27 @@ export const eqArrayStrict = /*#__PURE__*/ createEqArrayLike(eqStrict);
  * ### Example
  *
  * ```ts
- * import { eqArrayNumber } from "@evolu/common";
+ * import { assertTrue, eqArrayNumber } from "@evolu/common";
  *
- * expect(eqArrayNumber([1, NaN], [1, NaN])).toBe(true);
+ * assertTrue(eqArrayNumber([1, NaN], [1, NaN]));
  * ```
  */
 export const eqArrayNumber = /*#__PURE__*/ createEqArrayLike(eqNumber);
+/**
+ * Compares two Uint8Arrays by byte value.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertFalse, assertTrue, eqUint8Array } from "@evolu/common";
+ *
+ * assertTrue(eqUint8Array(new Uint8Array([1, 2]), new Uint8Array([1, 2])));
+ * assertFalse(
+ *   eqUint8Array(new Uint8Array([1, 2]), new Uint8Array([1, 3])),
+ * );
+ * ```
+ */
+export const eqUint8Array = eqArrayNumber;
 /**
  * Creates an equivalence function for objects based on an equivalence for their
  * fields.
@@ -107,12 +138,17 @@ export const eqArrayNumber = /*#__PURE__*/ createEqArrayLike(eqNumber);
  * ### Example
  *
  * ```ts
- * import { createEqObject, eqNumber } from "@evolu/common";
+ * import {
+ *   assertFalse,
+ *   assertTrue,
+ *   createEqObject,
+ *   eqNumber,
+ * } from "@evolu/common";
  *
  * const eqObjectNumber = createEqObject({ a: eqNumber });
  *
- * expect(eqObjectNumber({ a: 1 }, { a: 1 })).toBe(true);
- * expect(eqObjectNumber({ a: 1 }, { a: 2 })).toBe(false);
+ * assertTrue(eqObjectNumber({ a: 1 }, { a: 1 }));
+ * assertFalse(eqObjectNumber({ a: 1 }, { a: 2 }));
  * ```
  */
 export const createEqObject = (eqs) => (x, y) => {
@@ -125,111 +161,271 @@ export const createEqObject = (eqs) => (x, y) => {
     }
     return true;
 };
+export function eqData(actual, expected) {
+    return eqDataInternal(actual, expected, {
+        pairs: [],
+        rightsByLeft: new Map(),
+    });
+}
 /**
- * Deeply compares two {@link JsonValue} values for equality.
- *
- * - Uses an iterative approach with a stack to handle large or deeply nested
- *   objects without risking stack overflow.
- * - Defensively handles circular references in runtime values without looping,
- *   although cyclic values are not valid JSON.
- * - Unlike JSON.stringify, this function directly compares values, avoiding
- *   serialization overhead and leveraging short-circuit evaluation for faster
- *   failure on mismatched structures.
+ * Compares two {@link JsonValue} values using {@link eqData}.
  *
  * ### Example
  *
  * ```ts
- * import { eqJsonValue, type JsonValue } from "@evolu/common";
+ * import { assertTrue, eqJsonValue, type JsonValue } from "@evolu/common";
  *
  * const first: JsonValue = { profile: { name: "Ada" } };
  * const second: JsonValue = { profile: { name: "Ada" } };
  *
- * expect(eqJsonValue(first, second)).toBe(true);
+ * assertTrue(eqJsonValue(first, second));
  * ```
  */
-export const eqJsonValue = (a, b) => {
-    const stack = [[a, b]];
-    const seen = new WeakMap();
-    while (stack.length > 0) {
-        const [x, y] = stack.pop();
-        if (x === y)
-            continue;
-        const typeX = typeof x;
-        const typeY = typeof y;
-        if (typeX !== typeY || x === null || y === null)
+export const eqJsonValue = eqData;
+/** Compares two {@link JsonValueInput} values using {@link eqData}. */
+export const eqJsonValueInput = eqData;
+const eqDataInternal = (actual, expected, context) => {
+    const frames = [{ kind: "Compare", actual, expected }];
+    const attempts = [];
+    const retryFailedCandidate = (_frame) => {
+        const attempt = attempts.pop();
+        if (attempt === undefined)
             return false;
-        if (typeX === "number" && isNaN(x) && isNaN(y)) {
-            continue;
-        }
-        if (typeX === "object") {
-            const isArrayX = Array.isArray(x);
-            const isArrayY = Array.isArray(y);
-            if (isArrayX !== isArrayY)
-                return false;
-            const xObj = x;
-            const yObj = y;
-            if (seen.has(xObj)) {
-                const ySet = seen.get(xObj);
-                if (ySet.has(yObj)) {
-                    continue;
-                }
-                ySet.add(yObj);
+        rollbackEqDataContext(context, attempt.contextCheckpoint);
+        frames.length = attempt.frameCheckpoint;
+        frames.push(attempt.retry);
+        return true;
+    };
+    while (frames.length > 0) {
+        const frame = frames.pop();
+        if (frame.kind === "Compare") {
+            const x = frame.actual;
+            const y = frame.expected;
+            if (eqSameValueZero(x, y))
+                continue;
+            if (typeof x !== typeof y) {
+                frames.push({ kind: "Fail" });
+                continue;
+            }
+            if (typeof x !== "object" ||
+                x === null ||
+                typeof y !== "object" ||
+                y === null) {
+                frames.push({ kind: "Fail" });
+                continue;
+            }
+            const rights = context.rightsByLeft.get(x);
+            if (rights?.has(y))
+                continue;
+            if (rights === undefined) {
+                context.rightsByLeft.set(x, new Set([y]));
             }
             else {
-                const ySet = new WeakSet();
-                ySet.add(yObj);
-                seen.set(xObj, ySet);
+                rights.add(y);
+            }
+            context.pairs.push([x, y]);
+            const xKind = getObjectKind(x);
+            const yKind = getObjectKind(y);
+            if (xKind !== yKind) {
+                frames.push({ kind: "Fail" });
+                continue;
             }
-            if (isArrayX && isArrayY) {
-                const xArr = x;
-                const yArr = y;
-                if (xArr.length !== yArr.length)
-                    return false;
-                for (let i = 0; i < xArr.length; i++) {
-                    stack.push([xArr[i], yArr[i]]);
+            if (xKind === "Array") {
+                const xArray = x;
+                const yArray = y;
+                if (xArray.length !== yArray.length ||
+                    Reflect.ownKeys(xArray).length !== xArray.length + 1 ||
+                    Reflect.ownKeys(yArray).length !== yArray.length + 1) {
+                    frames.push({ kind: "Fail" });
+                    continue;
+                }
+                let valid = true;
+                for (let index = 0; index < xArray.length; index++) {
+                    const xDescriptor = Object.getOwnPropertyDescriptor(xArray, index);
+                    const yDescriptor = Object.getOwnPropertyDescriptor(yArray, index);
+                    if (xDescriptor === undefined ||
+                        yDescriptor === undefined ||
+                        !("value" in xDescriptor) ||
+                        !("value" in yDescriptor)) {
+                        valid = false;
+                        break;
+                    }
+                    frames.push({
+                        kind: "Compare",
+                        actual: xDescriptor.value,
+                        expected: yDescriptor.value,
+                    });
                 }
+                if (!valid)
+                    frames.push({ kind: "Fail" });
+                continue;
             }
-            else {
-                const xObjTyped = x;
-                const yObjTyped = y;
-                const xKeys = Object.keys(xObjTyped);
-                const yKeys = Object.keys(yObjTyped);
-                if (xKeys.length !== yKeys.length)
-                    return false;
-                const yKeySet = new Set(yKeys);
-                for (const key of xKeys) {
-                    if (!yKeySet.has(key))
-                        return false;
-                    stack.push([xObjTyped[key], yObjTyped[key]]);
+            switch (xKind) {
+                case "Date":
+                    if (!Object.is(Date.prototype.getTime.call(x), Date.prototype.getTime.call(y))) {
+                        frames.push({ kind: "Fail" });
+                    }
+                    continue;
+                case "Uint8Array":
+                    if (!eqUint8Array(x, y)) {
+                        frames.push({ kind: "Fail" });
+                    }
+                    continue;
+                case "Set": {
+                    const xSet = x;
+                    const ySet = y;
+                    if (Reflect.ownKeys(x).length !== 0 ||
+                        Reflect.ownKeys(y).length !== 0 ||
+                        xSet.size !== ySet.size) {
+                        frames.push({ kind: "Fail" });
+                        continue;
+                    }
+                    frames.push({
+                        kind: "Set",
+                        actual: Array.from(xSet),
+                        actualIndex: 0,
+                        unmatched: Array.from(ySet),
+                        candidateIndex: 0,
+                    });
+                    continue;
+                }
+                case "Map": {
+                    const xMap = x;
+                    const yMap = y;
+                    if (Reflect.ownKeys(x).length !== 0 ||
+                        Reflect.ownKeys(y).length !== 0 ||
+                        xMap.size !== yMap.size) {
+                        frames.push({ kind: "Fail" });
+                        continue;
+                    }
+                    frames.push({
+                        kind: "Map",
+                        actual: Array.from(xMap),
+                        actualIndex: 0,
+                        unmatched: Array.from(yMap),
+                        candidateIndex: 0,
+                    });
+                    continue;
+                }
+                case "Object": {
+                    const xKeys = Reflect.ownKeys(x);
+                    const yKeys = Reflect.ownKeys(y);
+                    if (xKeys.length !== yKeys.length) {
+                        frames.push({ kind: "Fail" });
+                        continue;
+                    }
+                    let valid = true;
+                    for (const key of xKeys) {
+                        if (typeof key !== "string") {
+                            valid = false;
+                            break;
+                        }
+                        const xDescriptor = Object.getOwnPropertyDescriptor(x, key);
+                        const yDescriptor = Object.getOwnPropertyDescriptor(y, key);
+                        if (xDescriptor === undefined ||
+                            yDescriptor === undefined ||
+                            !("value" in xDescriptor) ||
+                            !("value" in yDescriptor) ||
+                            !xDescriptor.enumerable ||
+                            !yDescriptor.enumerable) {
+                            valid = false;
+                            break;
+                        }
+                        frames.push({
+                            kind: "Compare",
+                            actual: xDescriptor.value,
+                            expected: yDescriptor.value,
+                        });
+                    }
+                    if (!valid)
+                        frames.push({ kind: "Fail" });
+                    continue;
                 }
+                case "Unsupported":
+                    frames.push({ kind: "Fail" });
+                    continue;
             }
         }
-        else {
-            return false;
+        if (frame.kind === "Set") {
+            if (frame.actualIndex === frame.actual.length)
+                continue;
+            if (frame.candidateIndex === frame.unmatched.length) {
+                frames.push({ kind: "Fail" });
+                continue;
+            }
+            const attempt = {
+                contextCheckpoint: context.pairs.length,
+                frameCheckpoint: frames.length,
+                retry: { ...frame, candidateIndex: frame.candidateIndex + 1 },
+            };
+            attempts.push(attempt);
+            frames.push({ kind: "CommitSet", match: frame });
+            frames.push({
+                kind: "Compare",
+                actual: frame.actual[frame.actualIndex],
+                expected: frame.unmatched[frame.candidateIndex],
+            });
+            continue;
+        }
+        if (frame.kind === "Map") {
+            if (frame.actualIndex === frame.actual.length)
+                continue;
+            if (frame.candidateIndex === frame.unmatched.length) {
+                frames.push({ kind: "Fail" });
+                continue;
+            }
+            const [actualKey, actualValue] = frame.actual[frame.actualIndex];
+            const [expectedKey, expectedValue] = frame.unmatched[frame.candidateIndex];
+            const attempt = {
+                contextCheckpoint: context.pairs.length,
+                frameCheckpoint: frames.length,
+                retry: { ...frame, candidateIndex: frame.candidateIndex + 1 },
+            };
+            attempts.push(attempt);
+            frames.push({ kind: "CommitMap", match: frame });
+            frames.push({
+                kind: "Compare",
+                actual: actualValue,
+                expected: expectedValue,
+            });
+            frames.push({
+                kind: "Compare",
+                actual: actualKey,
+                expected: expectedKey,
+            });
+            continue;
         }
+        if (frame.kind === "CommitSet") {
+            attempts.pop();
+            frame.match.unmatched.splice(frame.match.candidateIndex, 1);
+            frames.push({
+                ...frame.match,
+                actualIndex: frame.match.actualIndex + 1,
+                candidateIndex: 0,
+            });
+            continue;
+        }
+        if (frame.kind === "CommitMap") {
+            attempts.pop();
+            frame.match.unmatched.splice(frame.match.candidateIndex, 1);
+            frames.push({
+                ...frame.match,
+                actualIndex: frame.match.actualIndex + 1,
+                candidateIndex: 0,
+            });
+            continue;
+        }
+        if (!retryFailedCandidate(frame))
+            return false;
     }
     return true;
 };
-/**
- * Deeply compares two {@link JsonValueInput} values for equality.
- *
- * - Uses an iterative approach with a stack to handle large or deeply nested
- *   objects without risking stack overflow.
- * - Defensively handles circular references in runtime values without looping,
- *   although cyclic values are not valid JSON.
- * - Unlike JSON.stringify, this function directly compares values, avoiding
- *   serialization overhead and leveraging short-circuit evaluation for faster
- *   failure on mismatched structures.
- *
- * ### Example
- *
- * ```ts
- * import { eqJsonValueInput, type JsonValueInput } from "@evolu/common";
- *
- * const first: JsonValueInput = { profile: { name: "Ada" } };
- * const second: JsonValueInput = { profile: { name: "Ada" } };
- *
- * expect(eqJsonValueInput(first, second)).toBe(true);
- * ```
- */
-export const eqJsonValueInput = (a, b) => eqJsonValue(a, b);
+const rollbackEqDataContext = (context, checkpoint) => {
+    while (context.pairs.length > checkpoint) {
+        const [left, right] = context.pairs.pop();
+        const rights = context.rightsByLeft.get(left);
+        rights.delete(right);
+        if (rights.size === 0)
+            context.rightsByLeft.delete(left);
+    }
+};