Class APIs

When working with schemas, you can use Schema.Class instead of a plain Schema.Struct when your domain model benefits from class instances.

Classes offer several features that simplify the schema creation process:

Schema and class in one definition: The class itself can be used anywhere a schema is expected.
Validated construction: The constructor and make check their input.
Shared behavior: Instances can expose methods and getters.
Structural equality: Instances can be compared with Equal.equals.

Definition

To define a class using Schema.Class, you need to specify:

The class type as the Self type parameter.
A stable identifier used in diagnostics and schema metadata.
The fields of the class.

Example (Defining a Schema Class)

1
import { Schema } from "effect"
2

3
class Person extends Schema.Class<Person>("Person")({
4
  id: Schema.Finite,
5
  name: Schema.NonEmptyString,
6
}) {}

In this example, Person is both a schema and a TypeScript class.

Example (Creating Instances)

1
import { Schema } from "effect"
2

3
class Person extends Schema.Class<Person>("Person")({
4
  id: Schema.Finite,
5
  name: Schema.NonEmptyString,
6
}) {}
7

8
console.log(new Person({ id: 1, name: "John" }))
9
/*
10
Output:
11
Person { id: 1, name: 'John' }
12
*/
13

14
// Using the factory function
15
console.log(Person.make({ id: 1, name: "John" }))
16
/*
17
Output:
18
Person { id: 1, name: 'John' }
19
*/

Class Schemas are Transformations

Class schemas transform a struct schema into a declaration schema that represents the class.

When decoding, a plain object is converted into an instance of the class.
When encoding, a class instance is converted back into a plain object.

Example (Decoding and Encoding a Class)

1
import { Schema } from "effect"
2

3
class Person extends Schema.Class<Person>("Person")({
4
  id: Schema.Finite,
5
  name: Schema.NonEmptyString,
6
}) {}
7

8
const person = Person.make({ id: 1, name: "John" })
9

10
// Decode from a plain object into a class instance
11
const decoded = Schema.decodeUnknownSync(Person)({ id: 1, name: "John" })
12
console.log(decoded)
13
// Output: Person { id: 1, name: 'John' }
14

15
// Encode a class instance back into a plain object
16
const encoded = Schema.encodeUnknownSync(Person)(person)
17
console.log(encoded)
18
// Output: { id: 1, name: 'John' }

Defining Classes Without Fields

When your schema does not require any fields, you can define a class with an empty object.

Example (Defining and Using a Class Without Arguments)

1
import { Schema } from "effect"
2

3
// Define a class with no fields
4
class NoArgs extends Schema.Class<NoArgs>("NoArgs")({}) {}
5

6
// Create an instance using the default constructor
7
const noargs1 = new NoArgs() // => new NoArgs({})
8

9
// Alternatively, create an instance by explicitly passing an empty object
10
const noargs2 = new NoArgs({}) // => new NoArgs()

Defining Classes With Filters

Filters allow you to validate input when decoding, encoding, or creating an instance. Instead of specifying raw fields, you can pass a Schema.Struct with a filter applied.

Example (Applying a Filter to a Schema Class)

1
import { Schema } from "effect"
2

3
class WithFilter extends Schema.Class<WithFilter>("WithFilter")(
4
  Schema.Struct({
5
    a: Schema.FiniteFromString,
6
    b: Schema.FiniteFromString,
7
  }).check(
8
    Schema.makeFilter(
9
      ({ a, b }) => a >= b || "a must be greater than or equal to b",
10
    ),
11
  ),
12
) {}
13

14
// Constructor
15
console.log(new WithFilter({ a: 1, b: 2 }))
16
/*
17
throws:
18
a must be greater than or equal to b
19
*/
20

21
// Decoding
22
console.log(Schema.decodeUnknownSync(WithFilter)({ a: "1", b: "2" }))
23
/*
24
throws:
25
a must be greater than or equal to b
26
*/

Validating Properties via Class Constructors

When you define a class using Schema.Class, the constructor automatically checks that the provided properties adhere to the schema’s rules.

Defining and Instantiating a Valid Class Instance

The constructor ensures that each property, like id and name, adheres to the schema. For instance, id must be a number, and name must be a non-empty string.

Example (Creating a Valid Instance)

1
import { Schema } from "effect"
2

3
class Person extends Schema.Class<Person>("Person")({
4
  id: Schema.Finite,
5
  name: Schema.NonEmptyString,
6
}) {}
7

8
// Create an instance with valid properties
9
const john = new Person({ id: 1, name: "John" }) // => new Person({ id: 1, name: "John" })

Handling Invalid Properties

If invalid properties are provided during instantiation, the constructor throws an error, explaining why the validation failed.

Example (Creating an Instance with Invalid Properties)

1
import { Schema } from "effect"
2

3
class Person extends Schema.Class<Person>("Person")({
4
  id: Schema.Finite,
5
  name: Schema.NonEmptyString,
6
}) {}
7

8
// Attempt to create an instance with an invalid `name`
9
new Person({ id: 1, name: "" })
10
/*
11
throws:
12
Expected a value with a length of at least 1
13
  at ["name"]
14
*/

The error clearly specifies that the name field failed to meet the NonEmptyString requirement.

Bypassing Checks

In some scenarios, you might want to bypass the validation logic. While not generally recommended, the library provides an option to do so.

Example (Bypassing Checks)

1
import { Schema } from "effect"
2

3
class Person extends Schema.Class<Person>("Person")({
4
  id: Schema.Finite,
5
  name: Schema.NonEmptyString,
6
}) {}
7

8
// Skip the schema checks during instantiation
9
const john = new Person({ id: 1, name: "" }, { disableChecks: true })

Structural Equality

Equal.equals compares class instances structurally, including nested objects and arrays.

Example (Comparing Instances by Value)

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

3
class Person extends Schema.Class<Person>("Person")({
4
  name: Schema.NonEmptyString,
5
  hobbies: Schema.Array(Schema.String),
6
}) {}
7

8
const john1 = new Person({
9
  name: "John",
10
  hobbies: ["reading", "coding"],
11
})
12
const john2 = new Person({
13
  name: "John",
14
  hobbies: ["reading", "coding"],
15
})
16

17
Equal.equals(john1, john2) // => true

Extending Classes with Custom Logic

Schema classes provide the flexibility to include custom getters and methods, allowing you to extend their functionality beyond the defined fields.

Adding Custom Getters

A getter can be used to derive computed values from the fields of the class. For example, a Person class can include a getter to return the name property in uppercase.

Example (Adding a Getter for Uppercase Name)

1
import { Schema } from "effect"
2

3
class Person extends Schema.Class<Person>("Person")({
4
  id: Schema.Finite,
5
  name: Schema.NonEmptyString,
6
}) {
7
  // Custom getter to return the name in uppercase
8
  get upperName() {
9
    return this.name.toUpperCase()
10
  }
11
}
12

13
const john = new Person({ id: 1, name: "John" })
14

15
// Use the custom getter
16
console.log(john.upperName)
17
// Output: "JOHN"

Adding Custom Methods

In addition to getters, you can define methods to encapsulate more complex logic or operations involving the class’s fields.

Example (Adding a Method)

1
import { Schema } from "effect"
2

3
class Person extends Schema.Class<Person>("Person")({
4
  id: Schema.Finite,
5
  name: Schema.NonEmptyString,
6
}) {
7
  // Custom method to return a greeting
8
  greet() {
9
    return `Hello, my name is ${this.name}.`
10
  }
11
}
12

13
const john = new Person({ id: 1, name: "John" })
14

15
// Use the custom method
16
console.log(john.greet())
17
// Output: "Hello, my name is John."

Leveraging Classes as Schema Definitions

When you define a class with Schema.Class, it serves both as a schema and as a class. This dual functionality allows the class to be used wherever a schema is required.

Example (Using a Class in an Array Schema)

1
import { Schema } from "effect"
2

3
class Person extends Schema.Class<Person>("Person")({
4
  id: Schema.Finite,
5
  name: Schema.NonEmptyString,
6
}) {}
7

8
// Use the Person class in an array schema
9
const Persons = Schema.Array(Person)
10

11
//     ┌─── readonly Person[]
12
//     ▼
13
type Type = typeof Persons.Type

Exposed Values

The class also includes a fields static property, which outlines the fields defined during the class creation.

Example (Accessing the fields Property)

1
import { Schema } from "effect"
2

3
class Person extends Schema.Class<Person>("Person")({
4
  id: Schema.Finite,
5
  name: Schema.NonEmptyString,
6
}) {}
7

8
//       ┌─── {
9
//       |      readonly id: Schema.Finite;
10
//       |      readonly name: Schema.NonEmptyString;
11
//       |    }
12
//       ▼
13
Person.fields

Adding Annotations

Pass annotations as the second argument after the fields or struct. The identifier passed to Schema.Class is also stored as the default identifier annotation.

Example (Annotating a Class Schema)

1
import { Schema } from "effect"
2

3
class Person extends Schema.Class<Person>("Person")(
4
  {
5
    id: Schema.Finite,
6
    name: Schema.NonEmptyString,
7
  },
8
  { title: "Person model" },
9
) {}
10

11
Person.identifier // => "Person"
12
Person.ast.annotations?.title // => "Person model"

Recursive Schemas

The Schema.suspend combinator is useful when you need to define a schema that depends on itself, like in the case of recursive data structures. In this example, the Category schema depends on itself because it has a field subcategories that is an array of Category objects.

Example (Self-Referencing Schema)

1
import { Schema } from "effect"
2

3
// Define a Category schema with a recursive subcategories field
4
class Category extends Schema.Class<Category>("Category")({
5
  name: Schema.String,
6
  subcategories: Schema.Array(
7
    Schema.suspend((): Schema.Codec<Category> => Category),
8
  ),
9
}) {}

Example (Missing Type Annotation Error)

1
import { Schema } from "effect"
2

3
// @errors: 2506 7024
4
class Category extends Schema.Class<Category>("Category")({
5
  name: Schema.String,
6
  subcategories: Schema.Array(Schema.suspend(() => Category)),
7
}) {}

Mutually Recursive Schemas

Sometimes, schemas depend on each other in a mutually recursive way. For instance, an arithmetic expression tree might include Expression nodes that can either be numbers or Operation nodes, which in turn reference Expression nodes.

Example (Arithmetic Expression Tree)

1
import { Schema } from "effect"
2

3
class Expression extends Schema.Class<Expression>("Expression")({
4
  type: Schema.Literal("expression"),
5
  value: Schema.Union([
6
    Schema.Finite,
7
    Schema.suspend((): Schema.Codec<Operation> => Operation),
8
  ]),
9
}) {}
10

11
class Operation extends Schema.Class<Operation>("Operation")({
12
  type: Schema.Literal("operation"),
13
  operator: Schema.Literals(["+", "-"]),
14
  left: Expression,
15
  right: Expression,
16
}) {}

Recursive Types with Different Encoded and Type

Defining recursive schemas where the Encoded type differs from the Type type requires an explicit encoded representation. For instance, FiniteFromString has number as its Type and string as its Encoded.

In such cases, we need to define an interface for the Encoded type.

Let’s add an id field to the Category schema using FiniteFromString. When we add this field to the Category schema, TypeScript raises an error:

1
import { Schema } from "effect"
2

3
class Category extends Schema.Class<Category>("Category")({
4
  id: Schema.FiniteFromString,
5
  name: Schema.String,
6
  subcategories: Schema.Array(
7
    // @errors: 2322
8
    Schema.suspend((): Schema.Codec<Category> => Category),
9
  ),
10
}) {}

The Schema.Codec<Category> annotation assumes that both the Type and Encoded are Category. Supply the recursive encoded type as the second parameter instead:

Example (Adjusting the Schema with Explicit Encoded Type)

1
import { Schema } from "effect"
2

3
interface CategoryEncoded {
4
  readonly id: string
5
  readonly name: string
6
  readonly subcategories: ReadonlyArray<CategoryEncoded>
7
}
8

9
class Category extends Schema.Class<Category>("Category")({
10
  id: Schema.FiniteFromString,
11
  name: Schema.String,
12
  subcategories: Schema.Array(
13
    Schema.suspend((): Schema.Codec<Category, CategoryEncoded> => Category),
14
  ),
15
}) {}

As we’ve observed, it’s necessary to define an interface for the Encoded of the schema to enable recursive schema definition, which can complicate things and be quite tedious. One pattern to mitigate this is to separate the field responsible for recursion from all other fields.

Example (Separating Recursive Field)

1
import { Schema } from "effect"
2

3
const fields = {
4
  id: Schema.FiniteFromString,
5
  name: Schema.String,
6
  // ...possibly other fields
7
}
8

9
interface CategoryEncoded extends Schema.Struct.Encoded<typeof fields> {
10
  // Define `subcategories` using recursion
11
  readonly subcategories: ReadonlyArray<CategoryEncoded>
12
}
13

14
class Category extends Schema.Class<Category>("Category")({
15
  ...fields, // Include the fields
16
  subcategories: Schema.Array(
17
    // Define `subcategories` using recursion
18
    Schema.suspend((): Schema.Codec<Category, CategoryEncoded> => Category),
19
  ),
20
}) {}

Tagged Class Variants

Schema.TaggedClass automatically adds a _tag field, while Schema.TaggedError also creates a yieldable Error. Both use the tag as their identifier by default.

Example (Creating Tagged Classes and Errors)

1
import { Schema } from "effect"
2

3
// Define a tagged class with a "name" field
4
class TaggedPerson extends Schema.TaggedClass<TaggedPerson>()("TaggedPerson", {
5
  name: Schema.String,
6
}) {}
7

8
// Define a tagged error with a "status" field
9
class HttpError extends Schema.TaggedError<HttpError>()("HttpError", {
10
  status: Schema.Finite,
11
}) {}
12

13
const joe = new TaggedPerson({ name: "Joe" })
14
console.log(joe._tag)
15
// Output: "TaggedPerson"
16

17
const error = new HttpError({ status: 404 })
18
console.log(error._tag)
19
// Output: "HttpError"
20

21
console.log(error.stack) // access the stack trace

Extending Existing Classes

The extend static utility allows you to enhance an existing schema class by adding additional fields and functionality. This approach helps in building on top of existing schemas without redefining them from scratch.

Example (Extending a Schema Class)

1
import { Schema } from "effect"
2

3
// Define the base class
4
class Person extends Schema.Class<Person>("Person")({
5
  id: Schema.Finite,
6
  name: Schema.NonEmptyString,
7
}) {
8
  // A custom getter that converts the name to uppercase
9
  get upperName() {
10
    return this.name.toUpperCase()
11
  }
12
}
13

14
// Extend the base class to include an "age" field
15
class PersonWithAge extends Person.extend<PersonWithAge>("PersonWithAge")({
16
  age: Schema.Finite,
17
}) {
18
  // A custom getter to check if the person is an adult
19
  get isAdult() {
20
    return this.age >= 18
21
  }
22
}
23

24
// Usage
25
const john = new PersonWithAge({ id: 1, name: "John", age: 25 })
26
console.log(john.upperName) // Output: "JOHN"
27
console.log(john.isAdult) // Output: true