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

The Data module provides constructors for creating data types with built-in support for equality and hashing, eliminating the need for custom implementations.

This means that two values created using these constructors 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, the Data.struct constructor allows you to compare values based on their structure and content.

Example (Creating and Checking Equality of Structs)

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

3
//      ┌─── { readonly name: string; readonly age: number; }
4
//      ▼
5
const alice = Data.struct({ 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, Data.struct({ name: "Alice", age: 30 })))
10
// Output: true
11

12
// Check if Alice is equal to a plain JavaScript object
13
// with the same content
14
console.log(Equal.equals(alice, { name: "Alice", age: 30 }))
15
// Output: false

The comparison performed by Equal.equals is shallow, meaning nested objects are not compared recursively unless they are also created using Data.struct.

Example (Shallow Comparison with Nested Objects)

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

3
const nested = Data.struct({ name: "Alice", nested_field: { value: 42 } })
4

5
// This will be false because the nested objects are compared by reference
6
console.log(Equal.equals(nested, Data.struct({ name: "Alice", nested_field: { value: 42 } })))
7
// Output: false

To ensure nested objects are compared by structure, use Data.struct for them as well.

Example (Correctly Comparing Nested Objects)

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

3
const nested = Data.struct({
4
  name: "Alice",
5
  nested_field: Data.struct({ value: 42 }),
6
})
7

8
// Now, the comparison returns true
9
console.log(
10
  Equal.equals(
11
    nested,
12
    Data.struct({
13
      name: "Alice",
14
      nested_field: Data.struct({ value: 42 }),
15
    }),
16
  ),
17
)
18
// Output: true

tuple

To represent your data using tuples, you can use the Data.tuple constructor. This ensures that your tuples can be compared structurally.

Example (Creating and Checking Equality of Tuples)

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

3
//      ┌─── readonly [string, number]
4
//      ▼
5
const alice = Data.tuple("Alice", 30)
6

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

12
// Check if Alice is equal to a plain JavaScript tuple
13
// with the same content
14
console.log(Equal.equals(alice, ["Alice", 30]))
15
// Output: false

array

You can use Data.array to create an array-like data structure that supports structural equality.

Example (Creating and Checking Equality of Arrays)

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

3
//      ┌─── readonly number[]
4
//      ▼
5
const numbers = Data.array([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, Data.array([1, 2, 3, 4, 5])))
10
// Output: true
11

12
// Check if the array is equal to a plain JavaScript array
13
// with the same content
14
console.log(Equal.equals(numbers, [1, 2, 3, 4, 5]))
15
// Output: false

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 case or tagged
as TypeScript classes using Class or TaggedClass

case

The Data.case helper generates constructors and built-in support for equality checks and hashing for your data type.

Example (Defining a Case Class and Checking Equality)

In this example, Data.case is used to create a constructor for Person. The resulting instances have built-in support for equality checks, allowing you to compare them directly using Equal.equals.

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

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

7
// Create a constructor for `Person`
8
//
9
//      ┌─── (args: { readonly name: string; }) => Person
10
//      ▼
11
const make = Data.case<Person>()
12

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

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

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

Example (Defining and Comparing Nested Case Classes)

This example demonstrates using Data.case to create nested data structures, such as a Person type containing an Address. Both Person and Address constructors support equality checks.

1
import { Data, 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 = Data.case<Address>()
10

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

16
// Create a constructor for `Person`
17
const Person = Data.case<Person>()
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
// Output: true

Alternatively, you can use Data.struct to create nested data structures without defining a separate Address constructor.

Example (Using Data.struct for Nested Objects)

1
import { Data, 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 = Data.case<Person>()
13

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

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

24
console.log(Equal.equals(alice, anotherAlice))
25
// Output: true

Example (Defining and Comparing Recursive Case Classes)

This example demonstrates a recursive structure using Data.case to define a binary tree where each node can contain other nodes.

1
import { Data, 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`
10
const BinaryTree = Data.case<BinaryTree<number>>()
11

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

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

24
console.log(Equal.equals(tree1, tree2))
25
// Output: true

tagged

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. Using the case approach requires you to specify the tag field every time, which can be cumbersome.

Example (Defining a Tagged Case Class Manually)

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

1
import { Data } from "effect"
2

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

8
const Person = Data.case<Person>()
9

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

To streamline this process, the Data.tagged helper automatically adds the tag. It follows the convention in the Effect ecosystem of naming the tag field as "_tag".

Example (Using Data.tagged to Simplify Tagging)

The Data.tagged helper allows you to define the tag just once, making instance creation simpler.

1
import { Data } from "effect"
2

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

8
const Person = Data.tagged<Person>("Person")
9

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

14
console.log(alice)
15
// Output: { name: 'Alice', _tag: 'Person' }

Class

If you prefer working with classes instead of plain objects, you can use Data.Class as an alternative to Data.case. 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
// Output: 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
// Output: 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

12
// Check equality between two instances
13
console.log(Equal.equals(alice, new Person({ name: "Alice" })))
14
// Output: 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
// Output: 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)) // Output: true
21
console.log(Equal.equals(state2, state4)) // Output: false
22

23
// Display the states
24
console.log(state1) // Output: { _tag: 'Loading' }
25
console.log(state2) // Output: { data: 'test', _tag: 'Success' }
26
console.log(state4) // Output: { 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
// Output: true
16
console.log(isLoading(Success({ data: "test" })))
17
// Output: 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
// Output: "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 })

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
// Output: true
14

15
console.log(err.file)
16
// Output: foo.txt
17
console.log(err)
18
/*
19
Output:
20
NotFound [Error]: Cannot find this file
21
  file: 'foo.txt'
22
  ... stack trace ...
23
*/

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
Error: Cannot find this file
16
    at ... {
17
  name: '(FiberFailure) Error',
18
  [Symbol(effect/Runtime/FiberFailure/Cause)]: {
19
    _tag: 'Fail',
20
    error: NotFound [Error]: Cannot find this file
21
        at ...stack trace...
22
      file: 'foo.txt'
23
    }
24
  }
25
}
26
*/

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
  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) => Console.error(`${err.message} (${err.file})`)),
17
)
18

19
Effect.runPromise(program)
20
// 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
Error: An error has occurred
16
    at ... {
17
  name: '(FiberFailure) Error',
18
  [Symbol(effect/Runtime/FiberFailure/Cause)]: {
19
    _tag: 'Fail',
20
    error: MyError
21
        at ...
22
      [cause]: Error: Something went wrong
23
          at ...
24
*/