Equal

Creates a proxy that uses reference equality instead of structural equality.

When to use

Use when you need to compare a plain object or array by identity without mutating the original value.

Details

- 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; 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 byReferenceUnsafe).

See

• byReferenceUnsafe — same effect without a proxy (mutates the original)
• equals — the comparison function affected by this opt-out

Checks whether two values are deeply structurally equal.

When to use

Use when you need Effect's default structural equality check.

Details

Returns a boolean and never throws. Primitives are compared by value, and NaN equals NaN. Objects implementing Equal delegate to their [Equal.symbol] method; if only one operand implements Equal, the result is false.

Dates compare by ISO string, RegExps compare by string representation, arrays compare element-by-element, Maps and Sets compare entries order-independently, and plain objects compare enumerable keys recursively. Functions without an Equal implementation compare by reference. Circular references are handled when both structures are circular at the same depth.

Hash values are checked first as a fast-path rejection. The function also supports dual data-last usage: call it with one argument to get a curried predicate.

Gotchas

- Results are cached per object pair in a WeakMap. Objects must not be mutated after their first comparison. - Map and Set comparisons are O(n²) in size.

See

• Equal — the interface for custom equality
• isEqual — check whether a value implements Equal
• asEquivalence — wrap equals as an Equivalence

Checks whether a value implements the Equal interface.

When to use

Use when you need generic utility code to distinguish Equal implementors from plain values before calling [Equal.symbol] directly.

Details

- Pure function, no side effects. - Returns true if and only if u has a property keyed by symbol. - Acts as a TypeScript type guard, narrowing the input to Equal.

See

• Equal — the interface being checked
• symbol — the property key that signals Equal support

Wraps equals as an Equivalence<A>.

When to use

Use when you want to pass Equal.equals to APIs that require an Equivalence.

Details

- Returns a function (a: A, b: A) => boolean that delegates to equals. - Pure; allocates a thin wrapper on each call.

See

• equals — the underlying comparison function

The interface for types that define their own equality logic.

When to use

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.

Details

Any object that implements both [Equal.symbol] (equality) and [Hash.symbol] (hashing) is recognized by equals and by hash-based collections such as HashMap and HashSet.

- 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). - equals delegates to this method when both operands implement it. If only one operand implements Equal, they are considered unequal.

See

• symbol — the property key used by the equality method
• equals — the main comparison function
• isEqual — type guard for Equal implementors

Defines the unique string identifier for the Equal interface.

When to use

Use when you implement custom equality and need the computed property key for the equality method.

Details

This is a pure constant with no allocation or side effects.

See

• Equal — the interface that uses this symbol
• isEqual — type guard for Equal implementors

Marks an object permanently to use reference equality, without creating a proxy.

When to use

Use when you need reference equality without proxy allocation and accept permanently marking the original object for reference-only equality.

Details

- Adds obj to an internal WeakSet. From that point on, equals treats it as reference-only. - Returns the same object (not a copy or proxy), so byReferenceUnsafe(x) === x. - Does not affect the object's prototype, properties, or behavior beyond equality checks.

Gotchas

The marking is irreversible for the lifetime of the object.

See

• byReference — safer alternative that creates a proxy
• equals — the comparison function affected by this opt-out