Schema to Equivalence

Schema.toEquivalence derives an Equivalence for a schema’s Type. Nested values are compared according to the corresponding nested schemas.

Example (Comparing Structs)

1
import { Schema } from "effect"
2

3
const Person = Schema.Struct({
4
  name: Schema.String,
5
  age: Schema.Finite,
6
  tags: Schema.Array(Schema.String),
7
})
8

9
const equivalence = Schema.toEquivalence(Person)
10

11
equivalence(
12
  { name: "John", age: 23, tags: ["admin"] },
13
  { name: "John", age: 23, tags: ["admin"] },
14
) // => true
15

16
equivalence(
17
  { name: "John", age: 23, tags: ["admin"] },
18
  { name: "John", age: 24, tags: ["admin"] },
19
) // => false

For a struct, only fields described by the schema participate in the derived equivalence. Arrays and nested structs are compared recursively.

Broad Schemas

Schema.Any, Schema.Unknown, Schema.ObjectKeyword, and an empty Schema.Struct({}) use Equal.equals. Equal.equals performs deep structural comparison for objects and arrays rather than defaulting to reference equality.

Example (Structural Equality for an Empty Struct)

1
import { Schema } from "effect"
2

3
const equivalence = Schema.toEquivalence(Schema.Struct({}))
4

5
equivalence({ nested: [1, 2] }, { nested: [1, 2] }) // => true

Declarations

Declarations are opaque to automatic derivation. Provide a toEquivalence annotation when the declaration needs behavior other than Equal.equals.

Example (Defining Equivalence for a Class)

1
import { Schema } from "effect"
2

3
class User {
4
  constructor(
5
    readonly id: number,
6
    readonly displayName: string,
7
  ) {}
8
}
9

10
const UserSchema = Schema.instanceOf(User, {
11
  toEquivalence: () => (self, that) => self.id === that.id,
12
})
13

14
const equivalence = Schema.toEquivalence(UserSchema)
15

16
equivalence(new User(1, "Alice"), new User(1, "Alicia")) // => true

Parameterized declarations receive the derived equivalence for each type parameter in the annotation callback.

Overrides

Use Schema.overrideToEquivalence to replace the equivalence derived for an existing schema.

Example (Comparing a Struct by One Field)

1
import { Schema } from "effect"
2

3
const User = Schema.Struct({
4
  id: Schema.Finite,
5
  displayName: Schema.String,
6
}).pipe(Schema.overrideToEquivalence(() => (self, that) => self.id === that.id))
7

8
const equivalence = Schema.toEquivalence(User)
9

10
equivalence({ id: 1, displayName: "Alice" }, { id: 1, displayName: "Alicia" }) // => true
11

12
equivalence({ id: 1, displayName: "Alice" }, { id: 2, displayName: "Alice" }) // => false