Data

The Data module simplifies creating and handling data structures in TypeScript. It provides tools for defining data types, ensuring equality between objects, and hashing data for efficient comparisons.

Value Equality

Plain JavaScript objects, arrays, tuples, Maps, and Sets get structural equality with Equal.equals by default. No special constructor is required. See Equal for the full explanation.

This means that two plain values are considered equal if they have the same structure and values.

struct

In plain JavaScript, objects are considered equal only if they refer to the exact same instance.

Example (Comparing Two Objects in Plain JavaScript)

1
const alice = { name: "Alice", age: 30 }
2

3
// This comparison is false because they are different instances
4
// @errors: 2839
5
console.log(alice === { name: "Alice", age: 30 }) // Output: false

However, Equal.equals lets you compare the same two objects based on their structure and content.

Example (Checking Equality of Plain Objects)

1
import { Equal } from "effect"
2

3
//      ┌─── { readonly name: string; readonly age: number; }
4
//      ▼
5
const alice = { name: "Alice", age: 30 }
6

7
// Check if Alice is equal to a new object
8
// with the same structure and values
9
console.log(Equal.equals(alice, { name: "Alice", age: 30 }))
10
Equal.equals(alice, { name: "Alice", age: 30 }) // => true

The comparison performed by Equal.equals is deep: nested objects are compared recursively, with no extra work required.

Example (Deep Comparison of Nested Objects)

1
import { Equal } from "effect"
2

3
const nested = { name: "Alice", nested_field: { value: 42 } }
4

5
// Nested objects are compared recursively, so this is true
6
console.log(
7
  Equal.equals(nested, { name: "Alice", nested_field: { value: 42 } }),
8
)
9
Equal.equals(nested, { name: "Alice", nested_field: { value: 42 } }) // => true

A different nested value makes the objects unequal, as you would expect.

Example (Nested Objects with Different Values)

1
import { Equal } from "effect"
2

3
const nested = { name: "Alice", nested_field: { value: 42 } }
4

5
console.log(
6
  Equal.equals(nested, { name: "Alice", nested_field: { value: 43 } }),
7
)
8
Equal.equals(nested, { name: "Alice", nested_field: { value: 43 } }) // => false

tuple

Plain arrays used as tuples are compared structurally as well.

Example (Checking Equality of Tuples)

1
import { Equal } from "effect"
2

3
//      ┌─── readonly [string, number]
4
//      ▼
5
const alice = ["Alice", 30] as const
6

7
// Check if Alice is equal to a new tuple
8
// with the same structure and values
9
console.log(Equal.equals(alice, ["Alice", 30]))
10
Equal.equals(alice, ["Alice", 30]) // => true

array

Plain arrays support structural equality too.

Example (Checking Equality of Arrays)

1
import { Equal } from "effect"
2

3
//      ┌─── readonly number[]
4
//      ▼
5
const numbers = [1, 2, 3, 4, 5]
6

7
// Check if the array is equal to a new array
8
// with the same values
9
console.log(Equal.equals(numbers, [1, 2, 3, 4, 5]))
10
Equal.equals(numbers, [1, 2, 3, 4, 5]) // => true

Constructors

The module introduces a concept known as “Case classes”, which automate various essential operations when defining data types. These operations include generating constructors, handling equality checks, and managing hashing.

Case classes can be defined in two primary ways:

as plain objects, using an ordinary factory function when you want a reusable constructor; equality and hashing come for free
as TypeScript classes using Class or TaggedClass, when you want a class-oriented structure with methods and custom logic

Constructor functions

A plain factory function that returns an object literal gives you a reusable constructor. Since plain objects have structural equality by default, no special helper is needed for equality or hashing.

Example (Defining a Constructor Function and Checking Equality)

In this example, a plain arrow function creates a constructor for Person. The resulting instances are plain objects, so they already support equality checks. You can compare them directly using Equal.equals.

1
import { Equal } from "effect"
2

3
interface Person {
4
  readonly name: string
5
}
6

7
// Create a constructor for `Person`
8
//
9
//      ┌─── (args: Person) => Person
10
//      ▼
11
const make = (args: Person): Person => ({ ...args })
12

13
const alice = make({ name: "Alice" })
14

15
console.log(Equal.equals(alice, make({ name: "Alice" })))
16
Equal.equals(alice, make({ name: "Alice" })) // => true
17

18
console.log(Equal.equals(alice, make({ name: "John" })))
19
Equal.equals(alice, make({ name: "John" })) // => false

Example (Defining and Comparing Nested Data)

This example demonstrates nested data structures, such as a Person type containing an Address. Both Person and Address constructors return plain objects, so equality checks work out of the box.

1
import { Equal } from "effect"
2

3
interface Address {
4
  readonly street: string
5
  readonly city: string
6
}
7

8
// Create a constructor for `Address`
9
const Address = (args: Address): Address => ({ ...args })
10

11
interface Person {
12
  readonly name: string
13
  readonly address: Address
14
}
15

16
// Create a constructor for `Person`
17
const Person = (args: Person): Person => ({ ...args })
18

19
const alice = Person({
20
  name: "Alice",
21
  address: Address({ street: "123 Main St", city: "Wonderland" }),
22
})
23

24
const anotherAlice = Person({
25
  name: "Alice",
26
  address: Address({ street: "123 Main St", city: "Wonderland" }),
27
})
28

29
console.log(Equal.equals(alice, anotherAlice))
30
Equal.equals(alice, anotherAlice) // => true

Since nested plain objects are also compared structurally by default, you don’t even need a separate Address constructor. An inline object literal works just as well.

Example (Using a Plain Object Literal for Nested Data)

1
import { Equal } from "effect"
2

3
interface Person {
4
  readonly name: string
5
  readonly address: {
6
    readonly street: string
7
    readonly city: string
8
  }
9
}
10

11
// Create a constructor for `Person`
12
const Person = (args: Person): Person => ({ ...args })
13

14
const alice = Person({
15
  name: "Alice",
16
  address: { street: "123 Main St", city: "Wonderland" },
17
})
18

19
const anotherAlice = Person({
20
  name: "Alice",
21
  address: { street: "123 Main St", city: "Wonderland" },
22
})
23

24
console.log(Equal.equals(alice, anotherAlice))
25
Equal.equals(alice, anotherAlice) // => true

Example (Defining and Comparing Recursive Data)

This example demonstrates a recursive structure defining a binary tree where each node can contain other nodes.

1
import { Equal } from "effect"
2

3
interface BinaryTree<T> {
4
  readonly value: T
5
  readonly left: BinaryTree<T> | null
6
  readonly right: BinaryTree<T> | null
7
}
8

9
// Create a constructor for `BinaryTree<number>`
10
const BinaryTree = (args: BinaryTree<number>): BinaryTree<number> => ({
11
  ...args,
12
})
13

14
const tree1 = BinaryTree({
15
  value: 0,
16
  left: BinaryTree({ value: 1, left: null, right: null }),
17
  right: null,
18
})
19

20
const tree2 = BinaryTree({
21
  value: 0,
22
  left: BinaryTree({ value: 1, left: null, right: null }),
23
  right: null,
24
})
25

26
console.log(Equal.equals(tree1, tree2))
27
Equal.equals(tree1, tree2) // => true

Tagged constructor functions

When you’re working with a data type that includes a tag field, like in disjoint union types, defining the tag manually for each instance can get repetitive.

Example (Defining a Tagged Constructor Manually)

Here, we create a Person type with a _tag field. Notice that the _tag needs to be specified for every new instance.

1
interface Person {
2
  readonly _tag: "Person" // the tag
3
  readonly name: string
4
}
5

6
const Person = (args: Person): Person => ({ ...args })
7

8
// Repeating `_tag: 'Person'` for each instance
9
const alice = Person({ _tag: "Person", name: "Alice" })
10
const bob = Person({ _tag: "Person", name: "Bob" })

To streamline this process, write a constructor function that adds the tag automatically. It follows the convention in the Effect ecosystem of naming the tag field as "_tag".

Example (Simplifying Tagging with a Constructor Function)

This way you define the tag just once, making instance creation simpler.

1
interface Person {
2
  readonly _tag: "Person" // the tag
3
  readonly name: string
4
}
5

6
const Person = (args: Omit<Person, "_tag">): Person => ({
7
  ...args,
8
  _tag: "Person",
9
})
10

11
// The `_tag` field is automatically added
12
const alice = Person({ name: "Alice" })
13
const bob = Person({ name: "Bob" })
14

15
console.log(alice)
16
alice // => { name: "Alice", _tag: "Person" }

Class

If you prefer working with classes instead of plain objects, you can use Data.Class as an alternative to a constructor function. This approach may feel more natural in scenarios where you want a class-oriented structure, complete with methods and custom logic.

Example (Using Data.Class for a Class-Oriented Structure)

Here’s how to define a Person class using Data.Class:

1
import { Data, Equal } from "effect"
2

3
// Define a Person class extending Data.Class
4
class Person extends Data.Class<{ name: string }> {}
5

6
// Create an instance of Person
7
const alice = new Person({ name: "Alice" })
8

9
// Check for equality between two instances
10
console.log(Equal.equals(alice, new Person({ name: "Alice" })))
11
Equal.equals(alice, new Person({ name: "Alice" })) // => true

One of the benefits of using classes is that you can easily add custom methods and getters. This allows you to extend the functionality of your data types.

Example (Adding Custom Getters to a Class)

In this example, we add a upperName getter to the Person class to return the name in uppercase:

1
import { Data } from "effect"
2

3
// Extend Person class with a custom getter
4
class Person extends Data.Class<{ name: string }> {
5
  get upperName() {
6
    return this.name.toUpperCase()
7
  }
8
}
9

10
// Create an instance and use the custom getter
11
const alice = new Person({ name: "Alice" })
12

13
console.log(alice.upperName)
14
alice.upperName // => "ALICE"

TaggedClass

If you prefer a class-based approach but also want the benefits of tagging for disjoint unions, Data.TaggedClass can be a helpful option. It works similarly to tagged but is tailored for class definitions.

Example (Defining a Tagged Class with Built-In Tagging)

Here’s how to define a Person class using Data.TaggedClass. Notice that the tag "Person" is automatically added:

1
import { Data, Equal } from "effect"
2

3
// Define a tagged class Person with the _tag "Person"
4
class Person extends Data.TaggedClass("Person")<{ name: string }> {}
5

6
// Create an instance of Person
7
const alice = new Person({ name: "Alice" })
8

9
console.log(alice)
10
// Output: Person { name: 'Alice', _tag: 'Person' }
11
alice._tag // => "Person"
12

13
// Check equality between two instances
14
console.log(Equal.equals(alice, new Person({ name: "Alice" })))
15
Equal.equals(alice, new Person({ name: "Alice" })) // => true

One benefit of using tagged classes is the ability to easily add custom methods and getters, extending the class’s functionality as needed.

Example (Adding Custom Getters to a Tagged Class)

In this example, we add a upperName getter to the Person class, which returns the name in uppercase:

1
import { Data } from "effect"
2

3
// Extend the Person class with a custom getter
4
class Person extends Data.TaggedClass("Person")<{ name: string }> {
5
  get upperName() {
6
    return this.name.toUpperCase()
7
  }
8
}
9

10
// Create an instance and use the custom getter
11
const alice = new Person({ name: "Alice" })
12

13
console.log(alice.upperName)
14
alice.upperName // => "ALICE"

Union of Tagged Structs

To create a disjoint union of tagged structs, you can use Data.TaggedEnum and Data.taggedEnum. These utilities make it straightforward to define and work with unions of plain objects.

Definition

The type passed to Data.TaggedEnum must be an object where the keys represent the tags, and the values define the structure of the corresponding data types.

Example (Defining a Tagged Union and Checking Equality)

1
import { Data, Equal } from "effect"
2

3
// Define a union type using TaggedEnum
4
type RemoteData = Data.TaggedEnum<{
5
  Loading: {}
6
  Success: { readonly data: string }
7
  Failure: { readonly reason: string }
8
}>
9

10
// Create constructors for each case in the union
11
const { Loading, Success, Failure } = Data.taggedEnum<RemoteData>()
12

13
// Instantiate different states
14
const state1 = Loading()
15
const state2 = Success({ data: "test" })
16
const state3 = Success({ data: "test" })
17
const state4 = Failure({ reason: "not found" })
18

19
// Check equality between states
20
console.log(Equal.equals(state2, state3))
21
Equal.equals(state2, state3) // => true
22
console.log(Equal.equals(state2, state4))
23
Equal.equals(state2, state4) // => false
24

25
// Display the states
26
console.log(state1)
27
state1 // => { _tag: "Loading" }
28
console.log(state2)
29
state2 // => { data: "test", _tag: "Success" }
30
console.log(state4)
31
state4 // => { reason: "not found", _tag: "Failure" }

$is and $match

The Data.taggedEnum provides $is and $match functions for convenient type guarding and pattern matching.

Example (Using Type Guards and Pattern Matching)

1
import { Data } from "effect"
2

3
type RemoteData = Data.TaggedEnum<{
4
  Loading: {}
5
  Success: { readonly data: string }
6
  Failure: { readonly reason: string }
7
}>
8

9
const { $is, $match, Loading, Success } = Data.taggedEnum<RemoteData>()
10

11
// Use `$is` to create a type guard for "Loading"
12
const isLoading = $is("Loading")
13

14
console.log(isLoading(Loading()))
15
isLoading(Loading()) // => true
16
console.log(isLoading(Success({ data: "test" })))
17
isLoading(Success({ data: "test" })) // => false
18

19
// Use `$match` for pattern matching
20
const matcher = $match({
21
  Loading: () => "this is a Loading",
22
  Success: ({ data }) => `this is a Success: ${data}`,
23
  Failure: ({ reason }) => `this is a Failure: ${reason}`,
24
})
25

26
console.log(matcher(Success({ data: "test" })))
27
matcher(Success({ data: "test" })) // => "this is a Success: test"

Adding Generics

You can create more flexible and reusable tagged unions by using TaggedEnum.WithGenerics. This approach allows you to define tagged unions that can handle different types dynamically.

Example (Using Generics with TaggedEnum)

1
import { Data } from "effect"
2

3
// Define a generic TaggedEnum for RemoteData
4
type RemoteData<Success, Failure> = Data.TaggedEnum<{
5
  Loading: {}
6
  Success: { data: Success }
7
  Failure: { reason: Failure }
8
}>
9

10
// Extend TaggedEnum.WithGenerics to add generics
11
interface RemoteDataDefinition extends Data.TaggedEnum.WithGenerics<2> {
12
  readonly taggedEnum: RemoteData<this["A"], this["B"]>
13
}
14

15
// Create constructors for the generic RemoteData
16
const { Loading, Failure, Success } = Data.taggedEnum<RemoteDataDefinition>()
17

18
// Instantiate each case with specific types
19
const loading = Loading()
20
const failure = Failure({ reason: "not found" })
21
const success = Success({ data: 1 })
22

23
success.data // => 1

Errors

In Effect, handling errors is simplified using specialized constructors:

Error
TaggedError

These constructors make defining custom error types straightforward, while also providing useful integrations like equality checks and structured error handling.

Error

Data.Error lets you create an Error type with extra fields beyond the typical message property.

Example (Creating a Custom Error with Additional Fields)

1
import { Data } from "effect"
2

3
// Define a custom error with additional fields
4
class NotFound extends Data.Error<{ message: string; file: string }> {}
5

6
// Create an instance of the custom error
7
const err = new NotFound({
8
  message: "Cannot find this file",
9
  file: "foo.txt",
10
})
11

12
console.log(err instanceof Error)
13
err instanceof Error // => true
14

15
console.log(err.file)
16
err.file // => "foo.txt"
17
console.log(err)
18
err.message // => "Cannot find this file"

You can yield an instance of NotFound directly in an Effect.gen, without needing to use Effect.fail.

Example (Yielding a Custom Error in Effect.gen)

1
import { Data, Effect } from "effect"
2

3
class NotFound extends Data.Error<{ message: string; file: string }> {}
4

5
const program = Effect.gen(function* () {
6
  yield* new NotFound({
7
    message: "Cannot find this file",
8
    file: "foo.txt",
9
  })
10
})
11

12
Effect.runPromise(program)
13
/*
14
throws:
15
NotFound [Error]: Cannot find this file
16
    ...stack trace... {
17
  file: 'foo.txt'
18
}
19
*/

TaggedError

Effect provides a TaggedError API to add a _tag field automatically to your custom errors. This simplifies error handling with APIs like Effect.catchTag or Effect.catchTags.

1
import { Data, Effect, Console } from "effect"
2

3
// Define a custom tagged error
4
class NotFound extends Data.TaggedError("NotFound")<{
5
  message: string
6
  file: string
7
}> {}
8

9
const program = Effect.gen(function* () {
10
  return yield* new NotFound({
11
    message: "Cannot find this file",
12
    file: "foo.txt",
13
  })
14
}).pipe(
15
  // Catch and handle the tagged error
16
  Effect.catchTag("NotFound", (err) =>
17
    Console.error(`${err.message} (${err.file})`),
18
  ),
19
)
20

21
await Effect.runPromise(program) // => undefined
22
// Output: Cannot find this file (foo.txt)

Native Cause Support

Errors created using Data.Error or Data.TaggedError can include a cause property, integrating with the native cause feature of JavaScript’s Error for more detailed error tracing.

Example (Using the cause Property)

1
import { Data, Effect } from "effect"
2

3
// Define an error with a cause property
4
class MyError extends Data.Error<{ cause: Error }> {}
5

6
const program = Effect.gen(function* () {
7
  yield* new MyError({
8
    cause: new Error("Something went wrong"),
9
  })
10
})
11

12
Effect.runPromise(program)
13
/*
14
throws:
15
MyError
16
    ...stack trace... {
17
  [cause]: Error: Something went wrong
18
      ...stack trace...
19
}
20
*/