@evolu/common 8.5.0 → 8.6.0

package/dist/src/Eq.d.ts

@@ -4,7 +4,8 @@
  * @module
  */
 import type { Order } from "./Order.ts";
-import type { JsonValue, JsonValueInput } from "./Type.ts";
+import type { IsData, JsonValue, JsonValueInput } from "./Type.ts";
+import type { CompileTimeError } from "./Types.ts";
 /**
  * Compares two values of the same type `A` for equality.
  *
@@ -22,47 +23,61 @@ import type { JsonValue, JsonValueInput } from "./Type.ts";
  * ### Example
  *
  * ```ts
- * import { createEqObject, eqNumber } from "@evolu/common";
+ * import {
+ *   assertFalse,
+ *   assertTrue,
+ *   createEqObject,
+ *   eqNumber,
+ * } from "@evolu/common";
  *
  * const eqPoint = createEqObject({ x: eqNumber, y: eqNumber });
  *
- * expect(eqPoint({ x: 1, y: 2 }, { x: 1, y: 2 })).toBe(true);
- * expect(eqPoint({ x: 1, y: 2 }, { x: 2, y: 1 })).toBe(false);
+ * assertTrue(eqPoint({ x: 1, y: 2 }, { x: 1, y: 2 }));
+ * assertFalse(eqPoint({ x: 1, y: 2 }, { x: 2, y: 1 }));
  * ```
  */
 export type Eq<in A> = (x: A, y: A) => boolean;
 /**
- * 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 declare const eqStrict: <A>(x: A, y: A) => boolean;
 /**
  * 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 declare const eqSameValueZero: <A>(x: A, y: A) => boolean;
-/** An {@link Eq} for strings using strict equality. */
+/** An {@link Eq} for strings using {@link eqStrict}. */
 export declare const eqString: Eq<string>;
 /** An {@link Eq} for numbers using {@link eqSameValueZero}. */
 export declare const eqNumber: Eq<number>;
-/** An {@link Eq} for bigints using strict equality. */
+/** An {@link Eq} for bigints using {@link eqStrict}. */
 export declare const eqBigInt: Eq<bigint>;
-/** An {@link Eq} for booleans using strict equality. */
+/** An {@link Eq} for booleans using {@link eqStrict}. */
 export declare const eqBoolean: Eq<boolean>;
 /** An {@link Eq} for `undefined`. */
 export declare const eqUndefined: Eq<undefined>;
@@ -77,32 +92,38 @@ export declare const eqFromOrder: <A>(order: Order<A>) => Eq<A>;
  * ### 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 declare const createEqArrayLike: <A>(item: Eq<A>) => Eq<ArrayLike<A>>;
 /**
- * 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 declare const eqArrayStrict: <A>(x: ArrayLike<A>, y: ArrayLike<A>) => boolean;
@@ -112,12 +133,27 @@ export declare const eqArrayStrict: <A>(x: ArrayLike<A>, y: ArrayLike<A>) => boo
  * ### 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 declare const eqArrayNumber: Eq<ArrayLike<number>>;
+/**
+ * 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 declare const eqUint8Array: Eq<Uint8Array>;
 /**
  * Creates an equivalence function for objects based on an equivalence for their
  * fields.
@@ -125,59 +161,72 @@ export declare const eqArrayNumber: Eq<ArrayLike<number>>;
  * ### 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 declare const createEqObject: <A>(eqs: { [K in keyof A]: Eq<A[K]>; }) => Eq<{ readonly [K in keyof A]: A[K]; }>;
 /**
- * Deeply compares two {@link JsonValue} values for equality.
+ * Compares two {@link Data} values.
  *
- * - 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.
+ * Primitive values use SameValueZero, so `NaN` equals itself and `0` equals
+ * `-0`. Arrays and Object properties are ordered and keyed respectively. Sets
+ * and Maps compare their elements and entries without regard to insertion
+ * order. Dates compare their time values, while Uint8Arrays compare their
+ * bytes. Cyclic and shared data graphs are supported.
+ *
+ * The compile-time validation recursively accepts ordinary interfaces whose
+ * properties consist only of Data. Runtime representation details are trusted;
+ * use the {@link Data} Type at an unknown boundary.
  *
  * ### Example
  *
  * ```ts
- * import { eqJsonValue, type JsonValue } from "@evolu/common";
+ * import { assertTrue, eqData } from "@evolu/common";
  *
- * const first: JsonValue = { profile: { name: "Ada" } };
- * const second: JsonValue = { profile: { name: "Ada" } };
+ * interface User {
+ *   readonly name: string;
+ *   readonly roles: ReadonlySet<string>;
+ * }
+ *
+ * const first: User = { name: "Ada", roles: new Set(["admin", "author"]) };
+ * const second: User = {
+ *   name: "Ada",
+ *   roles: new Set(["author", "admin"]),
+ * };
  *
- * expect(eqJsonValue(first, second)).toBe(true);
+ * assertTrue(eqData(first, second));
  * ```
  */
-export declare const eqJsonValue: (a: JsonValue, b: JsonValue) => boolean;
+export declare function eqData<Actual, Expected>(actual: Actual, expected: Expected, ...dataError: EqDataError<Actual | Expected>): boolean;
 /**
- * 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.
+ * Compares two {@link JsonValue} values using {@link eqData}.
  *
  * ### Example
  *
  * ```ts
- * import { eqJsonValueInput, type JsonValueInput } from "@evolu/common";
+ * import { assertTrue, eqJsonValue, type JsonValue } from "@evolu/common";
  *
- * const first: JsonValueInput = { profile: { name: "Ada" } };
- * const second: JsonValueInput = { profile: { name: "Ada" } };
+ * const first: JsonValue = { profile: { name: "Ada" } };
+ * const second: JsonValue = { profile: { name: "Ada" } };
  *
- * expect(eqJsonValueInput(first, second)).toBe(true);
+ * assertTrue(eqJsonValue(first, second));
  * ```
  */
-export declare const eqJsonValueInput: (a: JsonValueInput, b: JsonValueInput) => boolean;
+export declare const eqJsonValue: Eq<JsonValue>;
+/** Compares two {@link JsonValueInput} values using {@link eqData}. */
+export declare const eqJsonValueInput: Eq<JsonValueInput>;
+type EqDataError<Value> = IsData<Value> extends true ? [] : [
+    error: CompileTimeError<"eqData", "Actual and expected values must consist only of Data.">
+];
+export {};
 //# sourceMappingURL=Eq.d.ts.map

package/dist/src/Eq.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Eq.d.ts","sourceRoot":"","sources":["../../src/Eq.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAGV,SAAS,EACT,cAAc,EACf,MAAM,WAAW,CAAC;AAEnB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAG,OAAkB,CAAC;AAE5D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAG,OACpB,CAAC;AAE7B,uDAAuD;AACvD,eAAO,MAAM,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAY,CAAC;AAE7C,+DAA+D;AAC/D,eAAO,MAAM,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAmB,CAAC;AAEpD,uDAAuD;AACvD,eAAO,MAAM,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAY,CAAC;AAE7C,wDAAwD;AACxD,eAAO,MAAM,SAAS,EAAE,EAAE,CAAC,OAAO,CAAY,CAAC;AAE/C,qCAAqC;AACrC,eAAO,MAAM,WAAW,EAAE,EAAE,CAAC,SAAS,CAAY,CAAC;AAEnD,gCAAgC;AAChC,eAAO,MAAM,MAAM,EAAE,EAAE,CAAC,IAAI,CAAY,CAAC;AAEzC,mDAAmD;AACnD,eAAO,MAAM,WAAW,GACrB,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,KAAG,EAAE,CAAC,CAAC,CAEP,CAAC;AAEtB;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,iBAAiB,GAC3B,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAUhC,CAAC;AAEJ;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,aAAa,GA7FD,CAAC,uCARa,OAqG+B,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,uBAA4C,CAAC;AAEvE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,GACxB,CAAC,OAAO,GAAG,CAAC,IAAI,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAE,KAAG,EAAE,CAAC,EACzC,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAC9B,CASA,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,WAAW,MAAO,SAAS,KAAK,SAAS,KAAG,OAsExD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,gBAAgB,MACxB,cAAc,KACd,cAAc,KAChB,OAAsD,CAAC"}
+{"version":3,"file":"Eq.d.ts","sourceRoot":"","sources":["../../src/Eq.ts"],"names":[],"mappings":"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"}