Equivalence

The Equivalence module provides a way to define equivalence relations between values in TypeScript. An equivalence relation is a binary relation that is reflexive, symmetric, and transitive, establishing a formal notion of when two values should be considered equivalent.

What is Equivalence?

An Equivalence<A> represents a function that compares two values of type A and determines if they are equivalent. This is more flexible and customizable than simple equality checks using ===.

Here’s the structure of an Equivalence:

interface Equivalence<A> {
  (self: A, that: A): boolean
}

Using Built-in Equivalences

The module provides several built-in equivalence relations for common data types:

Example (Using Built-in Equivalences)

1
import { Equivalence } from "effect"
2

3
console.log(Equivalence.string("apple", "apple"))
4
// Output: true
5

6
console.log(Equivalence.string("apple", "orange"))
7
// Output: false
8

9
console.log(Equivalence.Date(new Date(2023, 1, 1), new Date(2023, 1, 1)))
10
// Output: true
11

12
console.log(Equivalence.Date(new Date(2023, 1, 1), new Date(2023, 10, 1)))
13
// Output: false

Deriving Equivalences

For more complex data structures, you may need custom equivalences. The Equivalence module lets you derive new Equivalence instances from existing ones with the Equivalence.mapInput function.

Example (Creating a Custom Equivalence for Objects)

1
import { Equivalence } from "effect"
2

3
interface User {
4
  readonly id: number
5
  readonly name: string
6
}
7

8
// Create an equivalence that compares User objects based only on the id
9
const equivalence = Equivalence.mapInput(
10
  Equivalence.number, // Base equivalence for comparing numbers
11
  (user: User) => user.id, // Function to extract the id from a User
12
)
13

14
// Compare two User objects: they are equivalent if their ids are the same
15
console.log(equivalence({ id: 1, name: "Alice" }, { id: 1, name: "Al" }))
16
// Output: true

The Equivalence.mapInput function takes two arguments:

1. The existing Equivalence you want to use as a base (Equivalence.number in this case, for comparing numbers).
2. A function that extracts the value used for the equivalence check from your data structure ((user: User) => user.id in this case).