Getting Started

You can import the necessary types and functions from the effect/Schema module:

Example (Namespace Import)

import * as Schema from "effect/Schema"

Example (Named Import)

import { Schema } from "effect"

Defining a schema

One common way to define a Schema is by utilizing the Struct constructor. This constructor allows you to create a new schema that outlines an object with specific properties. Each property in the object is defined by its own schema, which specifies the data type and any validation rules.

Example (Defining a Simple Object Schema)

This Person schema describes an object with a name (string) and age (number) property:

1
import { Schema } from "effect"
2

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

Extracting Inferred Types

Type

Once you’ve defined a schema, you can extract its inferred decoded type T in two ways:

Using the Schema.Schema.Type utility
Accessing the Type field directly on the schema

Example (Extracting Inferred Type)

1
import { Schema } from "effect"
2

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

8
// 1. Using the Schema.Schema.Type utility
9
type Person = Schema.Schema.Type<typeof Person>
10

11
// 2. Accessing the Type field directly
12
type Person2 = typeof Person.Type

The resulting type will look like this:

type Person = {
  readonly name: string
  readonly age: number
}

Alternatively, you can extract the Person type using the interface keyword, which may improve readability and performance in some cases.

Example (Extracting Type with an Interface)

1
import { Schema } from "effect"
2

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

8
interface Person extends Schema.Schema.Type<typeof Person> {}

Both approaches yield the same result, but using an interface provides benefits such as performance advantages and improved readability.

Encoded

For a schema viewed as a Codec<T, E, RD, RE>, the encoded type E can differ from the decoded type T. You can extract the encoded type in two ways:

Using the Schema.Codec.Encoded utility
Accessing the Encoded field directly on the schema

Example (Extracting the Encoded Type)

1
import { Schema } from "effect"
2

3
const Person = Schema.Struct({
4
  name: Schema.String,
5
  // a schema that decodes a string to a number
6
  age: Schema.FiniteFromString,
7
})
8

9
// 1. Using the Schema.Codec.Encoded utility
10
type PersonEncoded = Schema.Codec.Encoded<typeof Person>
11

12
// 2. Accessing the Encoded field directly
13
type PersonEncoded2 = typeof Person.Encoded

The resulting type is:

type PersonEncoded = {
  readonly name: string
  readonly age: string
}

Note that age is of type string in the Encoded type of the schema and is of type number in the Type type of the schema.

Alternatively, you can define the PersonEncoded type using the interface keyword, which can enhance readability and performance.

Example (Extracting Encoded Type with an Interface)

1
import { Schema } from "effect"
2

3
const Person = Schema.Struct({
4
  name: Schema.String,
5
  // a schema that decodes a string to a number
6
  age: Schema.FiniteFromString,
7
})
8

9
interface PersonEncoded extends Schema.Codec.Encoded<typeof Person> {}

Both approaches yield the same result, but using an interface provides benefits such as performance advantages and improved readability.

Services

A Codec<T, E, RD, RE> tracks its service requirements separately in each direction: RD contains the services required for decoding, while RE contains those required for encoding. You can extract both types in two ways:

Using the Schema.Codec.DecodingServices and Schema.Codec.EncodingServices utilities.
Accessing the DecodingServices and EncodingServices fields directly on the schema.

Example (Extracting the Service Requirements)

1
import { Schema } from "effect"
2

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

8
// 1. Using the Schema.Codec.DecodingServices / EncodingServices utilities
9
type PersonDecodingServices = Schema.Codec.DecodingServices<typeof Person>
10
type PersonEncodingServices = Schema.Codec.EncodingServices<typeof Person>
11

12
// 2. Accessing the DecodingServices / EncodingServices field directly
13
type PersonDecodingServices2 = typeof Person.DecodingServices
14
type PersonEncodingServices2 = typeof Person.EncodingServices

Readonly Types by Default

It’s important to note that by default, most constructors exported by effect/Schema return readonly types.

Example (Readonly Types in a Schema)

For instance, in the Person schema below:

1
import { Schema } from "effect"
2

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

the resulting inferred Type would be:

{
  readonly name: string;
  readonly age: number;
}

Decoding

When working with unknown data types in TypeScript, decoding them into a known structure can be challenging. Luckily, effect/Schema provides several functions to help with this process. Let’s explore how to decode unknown values using these functions.

API	Description
`decodeUnknownSync`	Synchronously decodes a value and throws an error if parsing fails.
`decodeUnknownExit`	Decodes a value and returns an Exit.
`decodeUnknownOption`	Decodes a value and returns an Option type.
`decodeUnknownResult`	Decodes a value and returns a Result type.
`decodeUnknownPromise`	Decodes a value and returns a `Promise`.
`decodeUnknownEffect`	Decodes a value and returns an Effect.

decodeUnknownSync

The Schema.decodeUnknownSync function is useful when you want to parse a value and immediately throw an error if the parsing fails.

Example (Using decodeUnknownSync for Immediate Decoding)

1
import { Schema } from "effect"
2

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

8
// Simulate an unknown input
9
const input: unknown = { name: "Alice", age: 30 }
10

11
// Example of valid input matching the schema
12
console.log(Schema.decodeUnknownSync(Person)(input))
13
// Output: { name: 'Alice', age: 30 }
14

15
// Example of invalid input that does not match the schema
16
console.log(Schema.decodeUnknownSync(Person)(null))
17
/*
18
throws:
19
SchemaError: Expected object
20
*/

decodeUnknownResult

The Schema.decodeUnknownResult function allows you to parse a value and receive the result as a Result, representing success (Success) or failure (Failure). This approach lets you handle parsing errors more gracefully without throwing exceptions.

Example (Using Schema.decodeUnknownResult for Error Handling)

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

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

8
const decode = Schema.decodeUnknownResult(Person)
9

10
// Simulate an unknown input
11
const input: unknown = { name: "Alice", age: 30 }
12

13
// Attempt decoding a valid input
14
const result1 = decode(input) // => Result.succeed({ name: "Alice", age: 30 })
15
if (Result.isSuccess(result1)) {
16
  console.log(result1.success)
17
  // Output: { name: 'Alice', age: 30 }
18
}
19

20
// Simulate decoding an invalid input
21
const result2 = decode(null)
22
if (Result.isFailure(result2)) {
23
  console.log(result2.failure.message)
24
  // Output: Expected object
25
}

decodeUnknownEffect

If a schema contains asynchronous transformations, the Sync, Option, Result, and Exit interpreters cannot execute them. Use Schema.decodeUnknownEffect or Schema.decodeUnknownPromise instead.

Example (Handling Asynchronous Decoding)

1
import { Effect, Schema, SchemaGetter } from "effect"
2

3
const PersonId = Schema.Finite
4

5
const Person = Schema.Struct({
6
  id: PersonId,
7
  name: Schema.String,
8
  age: Schema.Finite,
9
})
10

11
const asyncSchema = PersonId.pipe(
12
  Schema.decodeTo(Person, {
13
    // Decode with simulated async transformation
14
    decode: SchemaGetter.transformOrFail((id) =>
15
      Effect.succeed({ id, name: "name", age: 18 }).pipe(
16
        Effect.delay("10 millis"),
17
      ),
18
    ),
19
    encode: SchemaGetter.transformOrFail((person) =>
20
      Effect.succeed(person.id).pipe(Effect.delay("10 millis")),
21
    ),
22
  }),
23
)
24

25
// Attempting to use a synchronous decoder on an async schema
26
console.log(Schema.decodeUnknownExit(asyncSchema)(1))
27
/*
28
Output:
29
{
30
  _id: 'Exit',
31
  _tag: 'Failure',
32
  cause: { _id: 'Cause', failures: [ [Object] ] }
33
}
34
*/
35

36
// Decoding asynchronously with `Schema.decodeUnknownEffect`
37
Effect.runPromise(Schema.decodeUnknownEffect(asyncSchema)(1)).then(console.log)
38
/*
39
Output:
40
{ id: 1, name: 'name', age: 18 }
41
*/

In the code above, the first approach using Schema.decodeUnknownExit results in an error indicating that the transformation cannot be resolved synchronously. This occurs because Schema.decodeUnknownExit is not designed for async operations. The second approach, which uses Schema.decodeUnknownEffect, works correctly, allowing you to handle asynchronous transformations and return the expected result.

Encoding

The Schema module provides several encode* functions to encode data according to a schema:

API	Description
`encodeSync`	Synchronously encodes data and throws an error if encoding fails.
`encodeExit`	Encodes data and returns an Exit.
`encodeOption`	Encodes data and returns an Option type.
`encodeResult`	Encodes data and returns a Result type representing success or failure.
`encodePromise`	Encodes data and returns a `Promise`.
`encodeEffect`	Encodes data and returns an Effect.

Example (Using Schema.encodeSync for Immediate Encoding)

1
import { Schema } from "effect"
2

3
const Person = Schema.Struct({
4
  // Ensure name is a non-empty string
5
  name: Schema.NonEmptyString,
6
  // Allow age to be decoded from a string and encoded to a string
7
  age: Schema.FiniteFromString,
8
})
9

10
// Valid input: encoding succeeds and returns expected types
11
console.log(Schema.encodeSync(Person)({ name: "Alice", age: 30 }))
12
// Output: { name: 'Alice', age: '30' }
13

14
// Invalid input: encoding fails due to empty name string
15
console.log(Schema.encodeSync(Person)({ name: "", age: 30 }))
16
/*
17
throws:
18
SchemaError: Expected a value with a length of at least 1
19
  at ["name"]
20
*/

Note that during encoding, the number value 30 was converted to a string "30".

SchemaError

The Schema.decodeUnknownResult and Schema.encodeResult functions return a Result, with different success types for each direction:

decodeUnknownResult: (input: unknown) => Result<T, SchemaError>
encodeResult: (input: T) => Result<E, SchemaError>

where SchemaError is defined as follows (simplified):

interface SchemaError {
  readonly _tag: "SchemaError"
  readonly issue: SchemaIssue.Issue
}

In this structure, SchemaIssue.Issue represents an error that might occur during decoding or encoding. It is wrapped in a tagged error to make it easier to catch errors using Effect.catchTag. Decoding succeeds with the decoded type T, while encoding succeeds with the encoded type E. In either direction, a schema mismatch produces a Failure containing a SchemaError.

Parse Options

The options below provide control over both decoding and encoding behaviors.

Managing Excess Properties

By default, any properties not defined in the schema are removed from the output when parsing a value. This ensures the parsed data conforms strictly to the expected structure.

If you want to detect and handle unexpected properties, use the onExcessProperty option (default value: "ignore"), which allows you to raise an error for excess properties. This can be helpful when you need to validate and catch unanticipated properties.

Example (Setting onExcessProperty to "error")

1
import { Schema } from "effect"
2

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

8
// Excess properties are ignored by default
9
console.log(
10
  Schema.decodeUnknownSync(Person)({
11
    name: "Bob",
12
    age: 40,
13
    email: "bob@example.com", // Ignored
14
  }),
15
)
16
/*
17
Output:
18
{ name: 'Bob', age: 40 }
19
*/
20

21
// With `onExcessProperty` set to "error",
22
// an error is thrown for excess properties
23
Schema.decodeUnknownSync(Person)(
24
  {
25
    name: "Bob",
26
    age: 40,
27
    email: "bob@example.com", // Will raise an error
28
  },
29
  { onExcessProperty: "error" },
30
)
31
/*
32
throws
33
SchemaError: Expected no excess property
34
  at ["email"]
35
*/

To retain extra properties, set onExcessProperty to "preserve".

Example (Setting onExcessProperty to "preserve")

1
import { Schema } from "effect"
2

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

8
// Excess properties are preserved in the output
9
Schema.decodeUnknownSync(Person)(
10
  {
11
    name: "Bob",
12
    age: 40,
13
    email: "bob@example.com",
14
  },
15
  { onExcessProperty: "preserve" },
16
) // => { email: "bob@example.com", name: "Bob", age: 40 }

Receiving All Errors

The errors option enables you to retrieve all errors encountered during parsing. By default, only the first error is returned. Setting errors to "all" provides comprehensive error feedback, which can be useful for debugging or offering detailed validation feedback.

Example (Setting errors to "all")

1
import { Schema } from "effect"
2

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

8
// Attempt to parse with multiple issues in the input data
9
Schema.decodeUnknownSync(Person)(
10
  {
11
    name: "Bob",
12
    age: "abc",
13
    email: "bob@example.com",
14
  },
15
  { errors: "all", onExcessProperty: "error" },
16
)
17
/*
18
throws
19
SchemaError: Expected no excess property
20
  at ["email"]
21
Expected number
22
  at ["age"]
23
*/

Managing Property Order

The propertyOrder option provides control over the order of object fields in the output. This feature is particularly useful when the sequence of keys is important for the consuming processes or when maintaining the input order enhances readability and usability.

By default, the propertyOrder option is set to "none". This means that the internal system decides the order of keys to optimize parsing speed. The order of keys in this mode should not be considered stable, and it’s recommended not to rely on key ordering as it may change in future updates.

Setting propertyOrder to "original" ensures that the keys are ordered as they appear in the input during the decoding/encoding process.

Example (Synchronous Decoding)

1
import { Schema } from "effect"
2

3
const schema = Schema.Struct({
4
  a: Schema.Finite,
5
  b: Schema.Literal("b"),
6
  c: Schema.Finite,
7
})
8

9
// Default decoding, where property order is system-defined
10
Schema.decodeUnknownSync(schema)({ b: "b", c: 2, a: 1 }) // => { a: 1, b: "b", c: 2 }
11

12
// Decoding while preserving input order
13
Schema.decodeUnknownSync(schema)(
14
  { b: "b", c: 2, a: 1 },
15
  { propertyOrder: "original" },
16
) // => { b: "b", c: 2, a: 1 }

Example (Asynchronous Decoding)

1
import type { Duration } from "effect"
2
import { Effect, Schema, SchemaGetter } from "effect"
3

4
// Helper function to simulate an async operation in schema
5
const effectify = (duration: Duration.Input) =>
6
  Schema.Finite.pipe(
7
    Schema.decodeTo(Schema.Finite, {
8
      decode: SchemaGetter.transformOrFail((x) =>
9
        Effect.sleep(duration).pipe(Effect.andThen(Effect.succeed(x))),
10
      ),
11
      encode: SchemaGetter.passthrough(),
12
    }),
13
  )
14

15
// Define a structure with asynchronous behavior in each field
16
const schema = Schema.Struct({
17
  a: effectify("200 millis"),
18
  b: effectify("300 millis"),
19
  c: effectify("100 millis"),
20
})
21

22
// Default decoding, where property order is system-defined
23
Schema.decodeEffect(schema)({ a: 1, b: 2, c: 3 }, { concurrency: 3 })
24
  .pipe(Effect.runPromise)
25
  .then(console.log)
26
// Output decided internally: { a: 1, b: 2, c: 3 }
27

28
// Decoding while preserving input order
29
Schema.decodeEffect(schema)(
30
  { a: 1, b: 2, c: 3 },
31
  { concurrency: 3, propertyOrder: "original" },
32
)
33
  .pipe(Effect.runPromise)
34
  .then(console.log)
35
// Output preserving input order: { a: 1, b: 2, c: 3 }

Customizing Parsing Behavior at the Schema Level

The parseOptions annotation allows you to customize parsing behavior at different schema levels, enabling you to apply unique parsing settings to nested schemas within a structure. Options defined within a schema override parent-level settings and apply to all nested schemas.

Example (Using parseOptions to Customize Error Handling)

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

3
const schema = Schema.Struct({
4
  a: Schema.Struct({
5
    b: Schema.String,
6
    c: Schema.String,
7
  }).annotate({
8
    title: "first error only",
9
    // Limit errors to the first in this sub-schema
10
    parseOptions: { errors: "first" },
11
  }),
12
  d: Schema.String,
13
}).annotate({
14
  title: "all errors",
15
  // Capture all errors for the main schema
16
  parseOptions: { errors: "all" },
17
})
18

19
// Decode input with custom error-handling behavior
20
const result = Schema.decodeUnknownResult(schema)(
21
  { a: {} },
22
  { errors: "first" },
23
)
24
if (Result.isFailure(result)) {
25
  console.log(result.failure.message)
26
  result.failure.message // => 'Missing key\n  at ["a"]["b"]\nMissing key\n  at ["d"]'
27
}

Detailed Output Explanation:

In this example:

The main schema is configured to display all errors. Hence, you will see errors related to both the d field (since it’s missing) and any errors from the a subschema.
The subschema (a) is set to display only the first error. Although both b and c fields are missing, only the first missing field (b) is reported.

Type Guards

The Schema.is function provides a way to verify if a value conforms to a given schema. It acts as a type guard, taking a value of type unknown and determining if it matches the structure and type constraints defined in the schema.

Here’s how the Schema.is function works:

Schema Definition: Define a schema to describe the structure and constraints of the data type you expect. Its decoded type T is the target type checked by the type guard.
Type Guard Creation: Use the schema to create a user-defined type guard, (input: unknown) => input is T. This function can be used at runtime to check if a value meets the requirements of the schema.

Example (Creating and Using a Type Guard)

1
import { Schema } from "effect"
2

3
// Define a schema for a Person object
4
const Person = Schema.Struct({
5
  name: Schema.String,
6
  age: Schema.Finite,
7
})
8

9
// Generate a type guard from the schema
10
const isPerson = Schema.is(Person)
11

12
// Test the type guard with various inputs
13
isPerson({ name: "Alice", age: 30 }) // => true
14

15
isPerson(null) // => false
16

17
isPerson({}) // => false

The generated isPerson function has the following signature:

const isPerson: <Input>(input: Input) => input is Input & {
  readonly name: string
  readonly age: number
}

Assertions

While type guards verify whether a value conforms to a specific type, the Schema.asserts function goes further by asserting that an input matches the decoded type T described by the schema. If the input does not match the schema, it throws a detailed error, making it useful for runtime validation.

Example (Creating and Using an Assertion)

1
import { Schema } from "effect"
2

3
// Define a schema for a Person object
4
const Person = Schema.Struct({
5
  name: Schema.String,
6
  age: Schema.Finite,
7
})
8

9
// Define an assertion wrapper for the schema
10
const assertsPerson: (input: unknown) => asserts input is {
11
  readonly name: string
12
  readonly age: number
13
} = (input) => Schema.asserts(Person, input)
14

15
try {
16
  // Attempt to assert that the input matches the Person schema
17
  assertsPerson({ name: "Alice", age: "30" })
18
} catch (e: any) {
19
  console.error("The input does not match the schema:")
20
  console.error(e.message)
21
  e.message // => 'Expected number\n  at ["age"]'
22
}
23

24
// This input matches the schema and will not throw an error
25
assertsPerson({ name: "Alice", age: 30 })

The assertsPerson wrapper has the following signature:

const assertsPerson: (input: unknown) => asserts input is {
  readonly name: string
  readonly age: number
}

Naming Conventions

Schema names describe the decoded type and, when a transformation is involved, the encoded representation it is decoded from.

Schemas whose decoded and encoded types are the same are generally named after that type:

Schema.Finite describes finite numbers in both directions.
Schema.Date describes Date values in both directions.

For transformed schemas, a name of the form TFromE reads as “decode E into T”:

Schema.FiniteFromString decodes a string into a finite number and encodes the number back into a string.
Schema.DateFromString decodes an ISO-formatted string into a Date and encodes the Date back into a string.