effect 4.0.0-beta.2 → 4.0.0-beta.21

package/dist/Equal.d.ts

@@ -1,23 +1,137 @@
 /**
- * This module provides functionality for defining and working with equality between values.
- * It includes the `Equal` interface for types that can determine equality with other values
- * of the same type, and utilities for comparing values.
+ * Structural and custom equality for Effect values.
+ *
+ * The `Equal` module provides deep structural comparison for primitives, plain
+ * objects, arrays, Maps, Sets, Dates, and RegExps. Types that implement the
+ * {@link Equal} interface can supply their own comparison logic while staying
+ * compatible with the rest of the ecosystem (HashMap, HashSet, etc.).
+ *
+ * ## Mental model
+ *
+ * - **Structural equality** — two values are equal when their contents match,
+ *   not when they share the same reference.
+ * - **Hash-first shortcut** — before comparing fields, the module checks
+ *   {@link Hash.hash}. If the hashes differ the objects are unequal without
+ *   further traversal.
+ * - **Equal interface** — any object that implements both {@link symbol} (the
+ *   equality method) and `Hash.symbol` (the hash method) can define custom
+ *   comparison logic.
+ * - **Caching** — comparison results for object pairs are cached in a WeakMap.
+ *   This makes repeated checks fast but **requires immutability** after the
+ *   first comparison.
+ * - **By-reference opt-out** — {@link byReference} and {@link byReferenceUnsafe}
+ *   let you switch individual objects back to reference equality when you need
+ *   mutable identity semantics.
+ *
+ * ## Common tasks
+ *
+ * - Compare two values → {@link equals}
+ * - Check if a value implements `Equal` → {@link isEqual}
+ * - Use `equals` where an `Equivalence` is expected → {@link asEquivalence}
+ * - Implement custom equality on a class → implement {@link Equal} (see
+ *   example on the interface)
+ * - Opt an object out of structural equality → {@link byReference} /
+ *   {@link byReferenceUnsafe}
+ *
+ * ## Gotchas
+ *
+ * - Objects **must be treated as immutable** after their first equality check.
+ *   Results are cached; mutating an object afterwards yields stale results.
+ * - `NaN` is considered equal to `NaN` (unlike `===`).
+ * - Functions without an `Equal` implementation are compared by reference.
+ * - Map and Set comparisons are order-independent but O(n²) in size.
+ * - If only one of two objects implements `Equal`, they are never equal.
+ *
+ * ## Quickstart
+ *
+ * **Example** (basic structural comparison)
+ *
+ * ```ts
+ * import { Equal } from "effect"
+ *
+ * // Primitives
+ * console.log(Equal.equals(1, 1))       // true
+ * console.log(Equal.equals("a", "b"))   // false
+ *
+ * // Objects and arrays
+ * console.log(Equal.equals({ x: 1 }, { x: 1 })) // true
+ * console.log(Equal.equals([1, 2], [1, 2]))       // true
+ *
+ * // Curried form
+ * const is42 = Equal.equals(42)
+ * console.log(is42(42)) // true
+ * console.log(is42(0))  // false
+ * ```
+ *
+ * @see {@link equals} — the main comparison function
+ * @see {@link Equal} — the interface for custom equality
+ * @see {@link Hash} — the companion hashing module
  *
  * @since 2.0.0
  */
 import type { Equivalence } from "./Equivalence.ts";
 import * as Hash from "./Hash.ts";
 /**
- * The unique identifier used to identify objects that implement the `Equal` interface.
+ * The unique string identifier for the {@link Equal} interface.
+ *
+ * Use this as a computed property key when implementing custom equality on a
+ * class or object literal.
+ *
+ * When to use:
+ * - As the method name when implementing the {@link Equal} interface.
+ * - To check manually whether an object carries an equality method (prefer
+ *   {@link isEqual} instead).
+ *
+ * Behavior:
+ * - Pure constant — no allocation or side effects.
+ *
+ * **Example** (implementing Equal on a class)
+ *
+ * ```ts
+ * import { Equal, Hash } from "effect"
+ *
+ * class UserId implements Equal.Equal {
+ *   constructor(readonly id: string) {}
+ *
+ *   [Equal.symbol](that: Equal.Equal): boolean {
+ *     return that instanceof UserId && this.id === that.id
+ *   }
+ *
+ *   [Hash.symbol](): number {
+ *     return Hash.string(this.id)
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link Equal} — the interface that uses this symbol
+ * @see {@link isEqual} — type guard for `Equal` implementors
  *
  * @since 2.0.0
  */
 export declare const symbol = "~effect/interfaces/Equal";
 /**
- * An interface defining objects that can determine equality with other `Equal` objects.
- * Objects implementing this interface must also implement `Hash` for consistency.
+ * The interface for types that define their own equality logic.
+ *
+ * Any object that implements both `[Equal.symbol]` (equality) and
+ * `[Hash.symbol]` (hashing) is recognized by {@link equals} and by
+ * hash-based collections such as `HashMap` and `HashSet`.
+ *
+ * When to use:
+ * - When you need value-based equality for a class (e.g. domain IDs,
+ *   coordinates, money values).
+ * - When your type will be stored in `HashMap` or `HashSet`.
+ * - When the default structural comparison is too broad or too narrow for
+ *   your type.
+ *
+ * Behavior:
+ * - Extends `Hash.Hash`, so implementors **must** also provide `[Hash.symbol]`.
+ * - The hash contract: if `a[Equal.symbol](b)` returns `true`, then
+ *   `Hash.hash(a)` must equal `Hash.hash(b)`.
+ * - {@link equals} delegates to this method when both operands implement it.
+ *   If only one operand implements `Equal`, they are considered unequal.
+ *
+ * **Example** (coordinate with value equality)
  *
- * @example
  * ```ts
  * import { Equal, Hash } from "effect"
  *
@@ -34,8 +148,15 @@ export declare const symbol = "~effect/interfaces/Equal";
  *     return Hash.string(`${this.x},${this.y}`)
  *   }
  * }
+ *
+ * console.log(Equal.equals(new Coordinate(1, 2), new Coordinate(1, 2))) // true
+ * console.log(Equal.equals(new Coordinate(1, 2), new Coordinate(3, 4))) // false
  * ```
  *
+ * @see {@link symbol} — the property key used by the equality method
+ * @see {@link equals} — the main comparison function
+ * @see {@link isEqual} — type guard for `Equal` implementors
+ *
  * @category models
  * @since 2.0.0
  */
@@ -43,102 +164,128 @@ export interface Equal extends Hash.Hash {
     [symbol](that: Equal): boolean;
 }
 /**
- * Compares two values for structural equality. Returns `true` if the values are structurally equal, `false` otherwise.
- *
- * This function performs deep structural comparison:
- * - For primitive values: uses value equality (including NaN === NaN)
- * - For objects implementing `Equal` interface: uses their custom equality logic
- * - For Date objects: compares ISO string representations
- * - For RegExp objects: compares string representations
- * - For Arrays: recursively compares each element
- * - For Maps: compares keys and values structurally (order-independent)
- * - For Sets: compares values structurally (order-independent)
- * - For plain objects: compares all properties recursively
- * - Handles circular references correctly
- *
- * **Performance**: Results of object comparisons are cached using WeakMaps to optimize
- * repeated equality checks between the same object pairs.
- *
- * **⚠️ CRITICAL IMMUTABILITY REQUIREMENT**: Objects being compared must be treated as
- * immutable after their first equality computation. Equality results are cached, so
- * mutating an object after comparison will lead to stale cached values and incorrect
- * equality results. For mutable objects, use referential equality by implementing
- * custom `Equal` interface that compares object references, not content.
- *
- * **FORBIDDEN**: Modifying objects after `Equal.equals()` has been called on them
- * **ALLOWED**: Using immutable objects, or mutable objects with custom `Equal` interface
- * that uses referential equality (compares object references, not content)
- *
- * @example
+ * Compares two values for deep structural equality.
+ *
+ * When to use:
+ * - As the default equality check throughout Effect code.
+ * - In data-level assertions or conditional logic where structural comparison
+ *   is needed.
+ * - In its curried (single-argument) form to build reusable predicates.
+ *
+ * Behavior:
+ * - Returns a `boolean`; never throws.
+ * - Primitives: compared by value. `NaN` equals `NaN`.
+ * - Objects implementing {@link Equal}: delegates to their
+ *   `[Equal.symbol]` method. If only one operand implements `Equal`, the
+ *   result is `false`.
+ * - Dates: compared by ISO string representation.
+ * - RegExps: compared by string representation.
+ * - Arrays: element-by-element recursive comparison (order matters).
+ * - Maps / Sets: structural comparison of entries (order-independent, O(n²)).
+ * - Plain objects: all own and inherited enumerable keys are compared
+ *   recursively.
+ * - Functions without an `Equal` implementation are compared by reference.
+ * - Circular references are handled; two structures that are circular at the
+ *   same depth are considered equal.
+ * - Hash values are checked first as a fast-path rejection.
+ * - Results are cached per object pair in a WeakMap. **Objects must not be
+ *   mutated after their first comparison.**
+ * - Supports dual (data-last) usage: call with one argument to get a curried
+ *   predicate.
+ *
+ * **Example** (comparing values)
+ *
  * ```ts
  * import { Equal } from "effect"
- * import * as assert from "node:assert"
- *
- * // Primitive values
- * assert(Equal.equals(1, 1) === true)
- * assert(Equal.equals(NaN, NaN) === true)
- *
- * // Objects - structural comparison
- * assert(Equal.equals({ a: 1, b: 2 }, { a: 1, b: 2 }) === true)
- * assert(Equal.equals({ a: 1 }, { a: 1, b: 2 }) === false)
- *
- * // Arrays - recursive comparison
- * assert(Equal.equals([1, [2, 3]], [1, [2, 3]]) === true)
- * assert(Equal.equals([1, 2], [1, 3]) === false)
- *
- * // Date equality by ISO string
- * const date1 = new Date("2023-01-01")
- * const date2 = new Date("2023-01-01")
- * assert(Equal.equals(date1, date2) === true)
- *
- * // Maps and Sets - structural comparison
- * const map1 = new Map([["a", 1], ["b", 2]])
- * const map2 = new Map([["b", 2], ["a", 1]]) // different order
- * assert(Equal.equals(map1, map2) === true)
- *
- * // Curried version
- * const isEqualTo5 = Equal.equals(5)
- * assert(isEqualTo5(5) === true)
- * assert(isEqualTo5(3) === false)
+ *
+ * // Primitives
+ * console.log(Equal.equals(1, 1))         // true
+ * console.log(Equal.equals(NaN, NaN))     // true
+ * console.log(Equal.equals("a", "b"))     // false
+ *
+ * // Objects and arrays
+ * console.log(Equal.equals({ a: 1, b: 2 }, { a: 1, b: 2 })) // true
+ * console.log(Equal.equals([1, [2, 3]], [1, [2, 3]]))         // true
+ *
+ * // Dates
+ * console.log(Equal.equals(new Date("2024-01-01"), new Date("2024-01-01"))) // true
+ *
+ * // Maps (order-independent)
+ * const m1 = new Map([["a", 1], ["b", 2]])
+ * const m2 = new Map([["b", 2], ["a", 1]])
+ * console.log(Equal.equals(m1, m2)) // true
+ *
+ * // Curried form
+ * const is5 = Equal.equals(5)
+ * console.log(is5(5)) // true
+ * console.log(is5(3)) // false
  * ```
  *
+ * @see {@link Equal} — the interface for custom equality
+ * @see {@link isEqual} — check whether a value implements `Equal`
+ * @see {@link asEquivalence} — wrap `equals` as an `Equivalence`
+ *
  * @category equality
  * @since 2.0.0
  */
 export declare function equals<B>(that: B): <A>(self: A) => boolean;
 export declare function equals<A, B>(self: A, that: B): boolean;
 /**
- * Determines if a value implements the `Equal` interface.
+ * Checks whether a value implements the {@link Equal} interface.
+ *
+ * When to use:
+ * - To branch on whether a value supports custom equality before calling
+ *   its `[Equal.symbol]` method directly.
+ * - In generic utility code that needs to distinguish `Equal` implementors
+ *   from plain values.
+ *
+ * Behavior:
+ * - Pure function, no side effects.
+ * - Returns `true` if and only if `u` has a property keyed by
+ *   {@link symbol}.
+ * - Acts as a TypeScript type guard, narrowing the input to {@link Equal}.
+ *
+ * **Example** (type guard)
  *
- * @example
  * ```ts
  * import { Equal, Hash } from "effect"
- * import * as assert from "node:assert"
  *
- * class MyClass implements Equal.Equal {
+ * class Token implements Equal.Equal {
+ *   constructor(readonly value: string) {}
  *   [Equal.symbol](that: Equal.Equal): boolean {
- *     return that instanceof MyClass
+ *     return that instanceof Token && this.value === that.value
  *   }
  *   [Hash.symbol](): number {
- *     return 0
+ *     return Hash.string(this.value)
  *   }
  * }
  *
- * const instance = new MyClass()
- * assert(Equal.isEqual(instance) === true)
- * assert(Equal.isEqual({}) === false)
- * assert(Equal.isEqual(42) === false)
+ * console.log(Equal.isEqual(new Token("abc"))) // true
+ * console.log(Equal.isEqual({ x: 1 }))         // false
+ * console.log(Equal.isEqual(42))                // false
  * ```
  *
+ * @see {@link Equal} — the interface being checked
+ * @see {@link symbol} — the property key that signals `Equal` support
+ *
  * @category guards
  * @since 2.0.0
  */
 export declare const isEqual: (u: unknown) => u is Equal;
 /**
- * Creates an `Equivalence` instance using the `equals` function.
- * This allows the equality logic to be used with APIs that expect an `Equivalence`.
+ * Wraps {@link equals} as an `Equivalence<A>`.
+ *
+ * When to use:
+ * - When an API (e.g. `Array.dedupeWith`, `Equivalence.mapInput`) requires an
+ *   `Equivalence` and you want to reuse `Equal.equals`.
+ *
+ * Behavior:
+ * - Returns a function `(a: A, b: A) => boolean` that delegates to
+ *   {@link equals}.
+ * - Pure; allocates a thin wrapper on each call.
+ *
+ * **Example** (deduplicating with Equal semantics)
  *
- * @example
  * ```ts
  * import { Array, Equal } from "effect"
  *
@@ -147,70 +294,90 @@ export declare const isEqual: (u: unknown) => u is Equal;
  * console.log(result) // [1, 2, 3]
  * ```
  *
+ * @see {@link equals} — the underlying comparison function
+ *
  * @category instances
  * @since 2.0.0
  */
 export declare const asEquivalence: <A>() => Equivalence<A>;
 /**
- * Creates a proxy of an object that uses reference equality instead of structural equality.
+ * Creates a proxy that uses reference equality instead of structural equality.
  *
- * By default, plain objects and arrays use structural equality. This function creates
- * a proxy that behaves exactly like the original object but uses reference equality
- * for comparison purposes.
+ * When to use:
+ * - When you have a plain object or array that should be compared by identity
+ *   (reference), not by contents.
+ * - When you want to preserve the original object unchanged and get a new
+ *   reference-equal handle.
  *
- * @example
- * ```ts
- * import { Equal } from "effect"
- * import * as assert from "node:assert"
+ * Behavior:
+ * - Returns a `Proxy` wrapping `obj`. The proxy reads through to the
+ *   original, so property access is unchanged.
+ * - The proxy is registered in an internal WeakSet; {@link equals} returns
+ *   `false` for any pair where at least one operand is in that set (unless
+ *   they are the same reference).
+ * - Each call creates a **new** proxy, so `byReference(x) !== byReference(x)`.
+ * - Does **not** mutate the original object (unlike {@link byReferenceUnsafe}).
  *
- * const obj1 = { a: 1, b: 2 }
- * const obj2 = { a: 1, b: 2 }
+ * **Example** (opting out of structural equality)
  *
- * // Normal structural equality
- * assert(Equal.equals(obj1, obj2) === true)
+ * ```ts
+ * import { Equal } from "effect"
  *
- * // Create reference equality version
- * const obj1ByRef = Equal.byReference(obj1)
- * assert(Equal.equals(obj1ByRef, obj2) === false) // uses reference equality
- * assert(Equal.equals(obj1ByRef, obj1ByRef) === true) // same reference
+ * const a = { x: 1 }
+ * const b = { x: 1 }
  *
- * // Each call creates a new proxy instance
- * const obj1ByRef2 = Equal.byReference(obj1)
- * assert(Equal.equals(obj1ByRef, obj1ByRef2) === false) // different instances
+ * console.log(Equal.equals(a, b)) // true  (structural)
  *
- * // Proxy behaves like the original
- * assert(obj1ByRef.a === 1)
+ * const aRef = Equal.byReference(a)
+ * console.log(Equal.equals(aRef, b))    // false (reference)
+ * console.log(Equal.equals(aRef, aRef)) // true  (same reference)
+ * console.log(aRef.x)                   // 1     (proxy reads through)
  * ```
  *
+ * @see {@link byReferenceUnsafe} — same effect without a proxy (mutates the
+ *   original)
+ * @see {@link equals} — the comparison function affected by this opt-out
+ *
  * @category utility
  * @since 2.0.0
  */
 export declare const byReference: <T extends object>(obj: T) => T;
 /**
- * Marks an object to use reference equality instead of structural equality, without creating a proxy.
+ * Permanently marks an object to use reference equality, without creating a
+ * proxy.
  *
- * Unlike `byReference`, this function directly modifies the object's equality behavior
- * without creating a proxy wrapper. This is more performant but "unsafe" because
- * it permanently changes how the object is compared.
+ * When to use:
+ * - When you want reference equality semantics and can accept that the
+ *   original object is **permanently** modified.
+ * - When proxy overhead is unacceptable (hot paths, large collections).
+ *
+ * Behavior:
+ * - Adds `obj` to an internal WeakSet. From that point on, {@link equals}
+ *   treats it as reference-only.
+ * - Returns the **same** object (not a copy or proxy), so
+ *   `byReferenceUnsafe(x) === x`.
+ * - The marking is irreversible for the lifetime of the object.
+ * - Does **not** affect the object's prototype, properties, or behavior
+ *   beyond equality checks.
+ *
+ * **Example** (marking an object for reference equality)
  *
- * @example
  * ```ts
  * import { Equal } from "effect"
- * import * as assert from "node:assert"
  *
  * const obj1 = { a: 1, b: 2 }
  * const obj2 = { a: 1, b: 2 }
  *
- * // Mark obj1 for reference equality (modifies obj1 directly)
- * const obj1ByRef = Equal.byReferenceUnsafe(obj1)
- * assert(obj1ByRef === obj1) // Same object, no proxy created
- * assert(Equal.equals(obj1ByRef, obj2) === false) // uses reference equality
- * assert(Equal.equals(obj1ByRef, obj1ByRef) === true) // same reference
+ * Equal.byReferenceUnsafe(obj1)
  *
- * // The original obj1 is now permanently marked for reference equality
- * assert(Equal.equals(obj1, obj2) === false) // obj1 uses reference equality
+ * console.log(Equal.equals(obj1, obj2))   // false (reference)
+ * console.log(Equal.equals(obj1, obj1))   // true  (same reference)
+ * console.log(obj1 === Equal.byReferenceUnsafe(obj1)) // true (same object)
  * ```
  *
+ * @see {@link byReference} — safer alternative that creates a proxy
+ * @see {@link equals} — the comparison function affected by this opt-out
+ *
  * @category utility
  * @since 2.0.0
  */

package/dist/Equal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Equal.d.ts","sourceRoot":"","sources":["../src/Equal.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AAIjC;;;;GAIG;AACH,eAAO,MAAM,MAAM,6BAA6B,CAAA;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,KAAM,SAAQ,IAAI,CAAC,IAAI;IACtC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,KAAK,GAAG,OAAO,CAAA;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,OAAO,CAAA;AAC3D,wBAAgB,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAA;AAwMvD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,OAAO,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,KAA+B,CAAA;AAEzE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,aAAa,EAAE,CAAC,CAAC,OAAO,WAAW,CAAC,CAAC,CAAgB,CAAA;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,KAAG,CAA0C,CAAA;AAEjG;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,KAAG,CAG5D,CAAA"}
+{"version":3,"file":"Equal.d.ts","sourceRoot":"","sources":["../src/Equal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AAIjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,MAAM,6BAA6B,CAAA;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,WAAW,KAAM,SAAQ,IAAI,CAAC,IAAI;IACtC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,KAAK,GAAG,OAAO,CAAA;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,OAAO,CAAA;AAC3D,wBAAgB,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAA;AAwMvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,OAAO,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,KAA+B,CAAA;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,aAAa,EAAE,CAAC,CAAC,OAAO,WAAW,CAAC,CAAC,CAAgB,CAAA;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,KAAG,CAA0C,CAAA;AAEjG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,KAAG,CAG5D,CAAA"}