Advanced Usage

Declaring New Data Types

Primitive Data Types

To declare a schema for an opaque, non-generic data type, you can use Schema.declare with a type guard. The following example shows the low-level pattern with File.

Example (Declaring a Schema for File)

1
import { Schema } from "effect"
2

3
// Declare a schema for the File type using a type guard
4
const FileSchema = Schema.declare(
5
  (input: unknown): input is File => input instanceof File,
6
)
7

8
const decode = Schema.decodeUnknownSync(FileSchema)
9

10
// Decoding a valid File object
11
console.log(decode(new File([], "")))
12
/*
13
Output:
14
File { size: 0, type: '', name: '', lastModified: 1724774163056 }
15
*/
16

17
// Decoding an invalid input
18
decode(null)
19
/*
20
throws
21
SchemaError: Expected <Declaration>
22
*/

You can add identifier, title, and description annotations to make the declaration easier for people and schema interpreters to understand. identifier and title can also improve the default expected-value message.

Identifier: a unique name for the schema
Title: a brief, descriptive title
Description: a detailed explanation of the schema’s purpose

Example (Declaring a Schema with Annotations)

1
import { Schema } from "effect"
2

3
// Declare a schema for the File type with additional annotations
4
const FileSchema = Schema.declare(
5
  (input: unknown): input is File => input instanceof File,
6
  {
7
    // A unique identifier for the schema
8
    identifier: "File",
9
    // Detailed description of the schema
10
    description: "The `File` type in JavaScript",
11
  },
12
)
13

14
const decode = Schema.decodeUnknownSync(FileSchema)
15

16
// Decoding a valid File object
17
console.log(decode(new File([], "")))
18
/*
19
Output:
20
File { size: 0, type: '', name: '', lastModified: 1724774163056 }
21
*/
22

23
// Decoding an invalid input
24
decode(null)
25
/*
26
throws
27
SchemaError: Expected File
28
*/

Type Constructors

Type constructors are generic types that take one or more types as arguments and return a new type. To define a schema for a type constructor, you can use the Schema.declare function.

Example (Declaring a Schema for ReadonlySet<T>)

1
import {
2
  Effect,
3
  Schema,
4
  SchemaIssue,
5
  SchemaParser,
6
  SchemaTransformation,
7
} from "effect"
8

9
export const MyReadonlySet = <S extends Schema.Constraint>(
10
  // Schema for the elements of the Set
11
  item: S,
12
) =>
13
  Schema.declareConstructor<
14
    ReadonlySet<S["Type"]>,
15
    ReadonlySet<S["Encoded"]>
16
  >()(
17
    // Store the schema for the Set's elements
18
    [item],
19
    // Decoding function
20
    ([item]) =>
21
      (input, ast, options) => {
22
        if (input instanceof Set) {
23
          // Decode each element in the Set
24
          return Effect.map(
25
            SchemaParser.decodeUnknownEffect(Schema.Array(item))(
26
              Array.from(input.values()),
27
              options,
28
            ),
29
            // Return a ReadonlySet containing the decoded elements
30
            (values): ReadonlySet<S["Type"]> => new Set(values),
31
          )
32
        }
33
        // Handle invalid input
34
        return Effect.fail(new SchemaIssue.InvalidType(ast))
35
      },
36
    {
37
      expected: "ReadonlySet",
38
      // Define the encoding side by linking back to an Array schema
39
      toCodec: ([item]) =>
40
        Schema.link<ReadonlySet<S["Encoded"]>>()(
41
          Schema.Array(item),
42
          SchemaTransformation.transform({
43
            // Decode an array into a ReadonlySet
44
            decode: (values): ReadonlySet<S["Encoded"]> => new Set(values),
45
            // Encode a ReadonlySet back into an array
46
            encode: (set) => Array.from(set.values()),
47
          }),
48
        ),
49
    },
50
  )
51

52
// Define a schema for a ReadonlySet of numbers
53
const setOfNumbers = MyReadonlySet(Schema.FiniteFromString)
54

55
const decode = Schema.decodeUnknownSync(setOfNumbers)
56

57
console.log(decode(new Set(["1", "2", "3"]))) // Set(3) { 1, 2, 3 }
58

59
// Decode an invalid input
60
decode(null)
61
/*
62
throws
63
SchemaError: Expected ReadonlySet
64
*/
65

66
// Decode a Set with an invalid element
67
decode(new Set(["1", null, "3"]))
68
/*
69
throws
70
SchemaError: Expected string
71
  at [1]
72
*/

Adding Interpreter Annotations

When defining a new data type, schema interpreters such as Arbitrary or Formatter may not know how to handle the new type. This can result in an error, as the interpreter may lack the necessary information for generating instances or producing readable output:

Example (Attempting to Generate Arbitrary Values Without Required Annotations)

1
import { Schema } from "effect"
2

3
// Define a schema for the File type
4
const FileSchema = Schema.declare(
5
  (input: unknown): input is File => input instanceof File,
6
  {
7
    identifier: "File",
8
  },
9
)
10

11
// Try creating an Arbitrary instance for the schema
12
const arb = Schema.toArbitrary(FileSchema)
13
/*
14
throws:
15
Error: Missing annotation
16
details: Generating an Arbitrary for this schema requires an "arbitrary" annotation
17
schema (Declaration): File
18
*/

In the above example, attempting to generate arbitrary values for FileSchema fails because the interpreter lacks the necessary annotations. To resolve this, provide an annotation for generating arbitrary data:

Example (Adding Arbitrary Annotation for Custom File Schema)

1
import { Schema } from "effect"
2
import { FastCheck } from "effect/testing"
3

4
const FileSchema = Schema.declare(
5
  (input: unknown): input is File => input instanceof File,
6
  {
7
    identifier: "File",
8
    // Provide a function to generate random File instances
9
    toArbitrary: () => (fc) =>
10
      fc
11
        .tuple(fc.string(), fc.string())
12
        .map(([content, path]) => new File([content], path)),
13
  },
14
)
15

16
// Create an Arbitrary instance for the schema
17
const arb = Schema.toArbitrary(FileSchema)
18

19
// Generate sample files using the Arbitrary instance
20
const files = FastCheck.sample(arb, 2)
21
console.log(files)
22
/*
23
Example Output:
24
[
25
  File { size: 5, type: '', name: 'C', lastModified: 1706435571176 },
26
  File { size: 1, type: '', name: '98Ggmc', lastModified: 1706435571176 }
27
]
28
*/

For more details on how to add annotations for the Arbitrary interpreter, refer to the Arbitrary documentation.

Branded types

TypeScript’s type system is structural, which means that any two types that are structurally equivalent are considered the same. This can cause issues when types that are semantically different are treated as if they were the same.

Example (Structural Typing Issue)

1
type UserId = string
2
type Username = string
3

4
declare const getUser: (id: UserId) => object
5

6
const myUsername: Username = "gcanti"
7

8
getUser(myUsername) // This erroneously works

In the above example, UserId and Username are both aliases for the same type, string. This means that the getUser function can mistakenly accept a Username as a valid UserId, causing bugs and errors.

To prevent this, Effect introduces branded types. These types attach a unique identifier (or “brand”) to a type, allowing you to differentiate between structurally similar but semantically distinct types.

Example (Defining Branded Types)

1
import { Brand } from "effect"
2

3
type UserId = string & Brand.Brand<"UserId">
4
type Username = string
5

6
declare const getUser: (id: UserId) => object
7

8
const myUsername: Username = "gcanti"
9

10
// @errors: 2345
11
getUser(myUsername)

By defining UserId as a branded type, the getUser function can accept only values of type UserId, and not plain strings or other types that are compatible with strings. This helps to prevent bugs caused by accidentally passing the wrong type of value to the function.

There are two ways to define a schema for a branded type, depending on whether you:

want to define the schema from scratch
have already defined a branded type via effect/Brand and want to reuse it to define a schema

Defining a brand schema from scratch

To define a schema for a branded type from scratch, use the Schema.brand function.

Example (Creating a schema for a Branded Type)

1
import { Schema } from "effect"
2

3
const UserId = Schema.String.pipe(Schema.brand("UserId"))
4

5
// string & Brand<"UserId">
6
type UserId = typeof UserId.Type

Reusing an existing branded constructor

If you have already defined a branded type using the effect/Brand module, you can reuse it to define a schema using the Schema.fromBrand function.

Example (Reusing an Existing Branded Type)

1
import { Schema } from "effect"
2
import { Brand } from "effect"
3

4
// the existing branded type
5
type UserId = string & Brand.Brand<"UserId">
6

7
const UserId = Brand.nominal<UserId>()
8

9
// Define a schema for the branded type
10
const UserIdSchema = Schema.String.pipe(Schema.fromBrand("UserId", UserId))

Utilizing Default Constructors

The Schema.brand function includes a default constructor to facilitate the creation of branded values.

1
import { Schema } from "effect"
2

3
const UserId = Schema.String.pipe(Schema.brand("UserId"))
4

5
const userId = UserId.make("123") // => "123"

Property Signatures

Property signature combinators control a struct field independently on the encoded and decoded sides. They can make a key optional, allow undefined, provide defaults, attach key-level annotations, or rename the encoded key.

Basic Usage

A property signature can be defined with annotations to provide additional context about a field.

Example (Adding Annotations to a Property Signature)

1
import { Schema } from "effect"
2

3
const Person = Schema.Struct({
4
  name: Schema.String,
5
  age: Schema.FiniteFromString.pipe(
6
    Schema.annotateKey({
7
      title: "Age", // Annotation to label the age field
8
    }),
9
  ),
10
})

Use Schema.annotateKey for field metadata. When the external representation uses a different key, use Schema.encodeKeys on the struct.

Example (Mapping from a Different Key)

1
import { Schema } from "effect"
2

3
const Person = Schema.Struct({
4
  name: Schema.String,
5
  age: Schema.FiniteFromString, // Maps from "AGE" to "age"
6
}).pipe(Schema.encodeKeys({ age: "AGE" }))
7

8
console.log(Schema.decodeUnknownSync(Person)({ name: "name", AGE: "18" }))
9
// Output: { name: 'name', age: 18 }

Optional Fields

Basic Optional Property

Schema.optional makes a key optional and allows undefined when the key is present.

Decoding

Input	Output
`<missing value>`	remains `<missing value>`
`undefined`	remains `undefined`
`e: E`	transforms to `t: T`

Encoding

Input	Output
`<missing value>`	remains `<missing value>`
`undefined`	remains `undefined`
`t: T`	transforms back to `e: E`

Example (Defining an Optional Number Field)

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optional(Schema.FiniteFromString),
5
})
6

7
//     ┌─── { readonly quantity?: string | undefined; }
8
//     ▼
9
type Encoded = typeof Product.Encoded
10

11
//     ┌─── { readonly quantity?: number | undefined; }
12
//     ▼
13
type Type = typeof Product.Type
14

15
// Decoding examples
16

17
console.log(Schema.decodeUnknownSync(Product)({ quantity: "1" }))
18
// Output: { quantity: 1 }
19
console.log(Schema.decodeUnknownSync(Product)({}))
20
// Output: {}
21
console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
22
// Output: { quantity: undefined }
23

24
// Encoding examples
25

26
console.log(Schema.encodeSync(Product)({ quantity: 1 }))
27
// Output: { quantity: "1" }
28
console.log(Schema.encodeSync(Product)({}))
29
// Output: {}
30
console.log(Schema.encodeSync(Product)({ quantity: undefined }))
31
// Output: { quantity: undefined }

Optional with Nullability

Combine Schema.optional, Schema.NullOr, and an optional-field transformation when null should be treated as a missing value.

Decoding

Input	Output
`<missing value>`	remains `<missing value>`
`undefined`	remains `undefined`
`null`	transforms to `<missing value>`
`e: E`	transforms to `t: T`

Encoding

Input	Output
`<missing value>`	remains `<missing value>`
`undefined`	remains `undefined`
`t: T`	transforms back to `e: E`

Example (Handling Null as Missing Value)

1
import { Option, Predicate, Schema, SchemaGetter } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optional(Schema.NullOr(Schema.FiniteFromString)).pipe(
5
    Schema.decodeTo(Schema.optional(Schema.Finite), {
6
      decode: SchemaGetter.transformOptional((o) =>
7
        o.pipe(Option.filter(Predicate.isNotNull)),
8
      ),
9
      encode: SchemaGetter.transformOptional((o) => o),
10
    }),
11
  ),
12
})
13

14
//     ┌─── { readonly quantity?: string | null | undefined; }
15
//     ▼
16
type Encoded = typeof Product.Encoded
17

18
//     ┌─── { readonly quantity?: number | undefined; }
19
//     ▼
20
type Type = typeof Product.Type
21

22
// Decoding examples
23

24
console.log(Schema.decodeUnknownSync(Product)({ quantity: "1" }))
25
// Output: { quantity: 1 }
26
console.log(Schema.decodeUnknownSync(Product)({}))
27
// Output: {}
28
console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
29
// Output: { quantity: undefined }
30
console.log(Schema.decodeUnknownSync(Product)({ quantity: null }))
31
// Output: {}
32

33
// Encoding examples
34

35
console.log(Schema.encodeSync(Product)({ quantity: 1 }))
36
// Output: { quantity: "1" }
37
console.log(Schema.encodeSync(Product)({}))
38
// Output: {}
39
console.log(Schema.encodeSync(Product)({ quantity: undefined }))
40
// Output: { quantity: undefined }

Exact Optional Key

Schema.optionalKey makes the key optional without adding undefined to its value type. If the key is present, its value must be accepted by the wrapped schema.

Decoding

Input	Output
`<missing value>`	remains `<missing value>`
`undefined`	`SchemaError`
`e: E`	transforms to `t: T`

Encoding

Input	Output
`<missing value>`	remains `<missing value>`
`t: T`	transforms back to `e: E`

Example (Using Exactness with Optional Field)

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalKey(Schema.FiniteFromString),
5
})
6

7
//     ┌─── { readonly quantity?: string; }
8
//     ▼
9
type Encoded = typeof Product.Encoded
10

11
//     ┌─── { readonly quantity?: number; }
12
//     ▼
13
type Type = typeof Product.Type
14

15
// Decoding examples
16

17
console.log(Schema.decodeUnknownSync(Product)({ quantity: "1" }))
18
// Output: { quantity: 1 }
19
console.log(Schema.decodeUnknownSync(Product)({}))
20
// Output: {}
21
console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
22
/*
23
throws:
24
SchemaError: Expected string
25
  at ["quantity"]
26
*/
27

28
// Encoding examples
29

30
console.log(Schema.encodeSync(Product)({ quantity: 1 }))
31
// Output: { quantity: "1" }
32
console.log(Schema.encodeSync(Product)({}))
33
// Output: {}

Exact Optional Key with Nullability

Combine Schema.optionalKey, Schema.NullOr, and an optional-field transformation when null should be treated as a missing key but undefined should still be rejected.

Decoding

Input	Output
`<missing value>`	remains `<missing value>`
`null`	transforms to `<missing value>`
`undefined`	`SchemaError`
`e: E`	transforms to `t: T`

Encoding

Input	Output
`<missing value>`	remains `<missing value>`
`t: T`	transforms back to `e: E`

Example (Using Exactness and Handling Null as Missing Value with Optional Field)

1
import { Option, Predicate, Schema, SchemaGetter } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalKey(Schema.NullOr(Schema.FiniteFromString)).pipe(
5
    Schema.decodeTo(Schema.optionalKey(Schema.Finite), {
6
      decode: SchemaGetter.transformOptional((o) =>
7
        o.pipe(Option.filter(Predicate.isNotNull)),
8
      ),
9
      encode: SchemaGetter.transformOptional((o) => o),
10
    }),
11
  ),
12
})
13

14
//     ┌─── { readonly quantity?: string | null; }
15
//     ▼
16
type Encoded = typeof Product.Encoded
17

18
//     ┌─── { readonly quantity?: number; }
19
//     ▼
20
type Type = typeof Product.Type
21

22
// Decoding examples
23

24
console.log(Schema.decodeUnknownSync(Product)({ quantity: "1" }))
25
// Output: { quantity: 1 }
26
console.log(Schema.decodeUnknownSync(Product)({}))
27
// Output: {}
28
console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
29
/*
30
throws:
31
SchemaError: Expected string | null
32
  at ["quantity"]
33
*/
34
console.log(Schema.decodeUnknownSync(Product)({ quantity: null }))
35
// Output: {}
36

37
// Encoding examples
38

39
console.log(Schema.encodeSync(Product)({ quantity: 1 }))
40
// Output: { quantity: "1" }
41
console.log(Schema.encodeSync(Product)({}))
42
// Output: {}

Representing Optional Fields with never Type

When creating a schema to replicate a TypeScript type that includes optional fields with the never type, like:

1
type MyType = {
2
  readonly quantity?: never
3
}

the handling of these fields depends on the exactOptionalPropertyTypes setting in your tsconfig.json. This setting affects whether the schema should treat optional never-typed fields as simply absent or allow undefined as a value.

Example (exactOptionalPropertyTypes: false)

When this feature is turned off, you can employ the Schema.optional function. This approach allows the field to implicitly accept undefined as a value.

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optional(Schema.Never),
5
})
6

7
//     ┌─── { readonly quantity?: undefined; }
8
//     ▼
9
type Encoded = typeof Product.Encoded
10

11
//     ┌─── { readonly quantity?: undefined; }
12
//     ▼
13
type Type = typeof Product.Type

Example (exactOptionalPropertyTypes: true)

When this feature is turned on, use Schema.optionalKey so that the field can only be absent.

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalKey(Schema.Never),
5
})
6

7
//     ┌─── { readonly quantity?: never; }
8
//     ▼
9
type Encoded = typeof Product.Encoded
10

11
//     ┌─── { readonly quantity?: never; }
12
//     ▼
13
type Type = typeof Product.Type

Default Values

Use Schema.withDecodingDefaultType or Schema.withDecodingDefaultTypeKey to provide a decoded default. Constructor defaults are independent and can be added with Schema.withConstructorDefault.

Basic Default

This is the simplest use case. If the input is missing or undefined, the default value will be applied.

Operation	Behavior
Decoding	Applies the default value if the input is missing or `undefined`
Encoding	Transforms the input `t: T` back to `e: E`

Example (Applying Default When Field Is Missing or undefined)

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

3
const Product = Schema.Struct({
4
  quantity: Schema.FiniteFromString.pipe(
5
    Schema.withDecodingDefaultType(Effect.succeed(1)), // Default value for quantity
6
    Schema.withConstructorDefault(Effect.succeed(1)),
7
  ),
8
})
9

10
//     ┌─── { readonly quantity?: string | undefined; }
11
//     ▼
12
type Encoded = typeof Product.Encoded
13

14
//     ┌─── { readonly quantity: number; }
15
//     ▼
16
type Type = typeof Product.Type
17

18
// Decoding examples with default applied
19

20
console.log(Schema.decodeUnknownSync(Product)({}))
21
// Output: { quantity: 1 }
22

23
console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
24
// Output: { quantity: 1 }
25

26
console.log(Schema.decodeUnknownSync(Product)({ quantity: "2" }))
27
// Output: { quantity: 2 }
28

29
// Object construction examples with default applied
30

31
console.log(Product.make({}))
32
// Output: { quantity: 1 }
33

34
console.log(Product.make({ quantity: 2 }))
35
// Output: { quantity: 2 }

Default for a Missing Key

Use Schema.withDecodingDefaultTypeKey when the default should apply only if the key is missing, not when its value is undefined.

Operation	Behavior
Decoding	Applies the default value only if the input is missing
Encoding	Transforms the input `t: T` back to `e: E`

Example (Applying Default Only When Field Is Missing)

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

3
const Product = Schema.Struct({
4
  quantity: Schema.FiniteFromString.pipe(
5
    Schema.withDecodingDefaultTypeKey(Effect.succeed(1)), // Default value for quantity, only if quantity is not provided
6
  ),
7
})
8

9
//     ┌─── { readonly quantity?: string; }
10
//     ▼
11
type Encoded = typeof Product.Encoded
12

13
//     ┌─── { readonly quantity: number; }
14
//     ▼
15
type Type = typeof Product.Type
16

17
console.log(Schema.decodeUnknownSync(Product)({}))
18
// Output: { quantity: 1 }
19

20
console.log(Schema.decodeUnknownSync(Product)({ quantity: "2" }))
21
// Output: { quantity: 2 }
22

23
console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
24
/*
25
throws:
26
SchemaError: Expected string
27
  at ["quantity"]
28
*/

Default with Nullability

Combine an optional nullable field with SchemaGetter.transformOptional when missing, undefined, and null should all produce the default.

Operation	Behavior
Decoding	Applies the default value if the input is missing or `undefined` or `null`
Encoding	Transforms the input `t: T` back to `e: E`

Example (Applying Default When Field Is Missing or undefined or null)

1
import { Option, Predicate, Schema, SchemaGetter } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optional(Schema.NullOr(Schema.FiniteFromString)).pipe(
5
    Schema.decodeTo(Schema.Finite, {
6
      decode: SchemaGetter.transformOptional((o) =>
7
        o.pipe(
8
          Option.filter(Predicate.isNotNullish),
9
          Option.orElseSome(() => 1),
10
        ),
11
      ),
12
      encode: SchemaGetter.required(),
13
    }),
14
  ),
15
})
16

17
//     ┌─── { readonly quantity?: string | null | undefined; }
18
//     ▼
19
type Encoded = typeof Product.Encoded
20

21
//     ┌─── { readonly quantity: number; }
22
//     ▼
23
type Type = typeof Product.Type
24

25
console.log(Schema.decodeUnknownSync(Product)({}))
26
// Output: { quantity: 1 }
27

28
console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
29
// Output: { quantity: 1 }
30

31
console.log(Schema.decodeUnknownSync(Product)({ quantity: null }))
32
// Output: { quantity: 1 }
33

34
console.log(Schema.decodeUnknownSync(Product)({ quantity: "2" }))
35
// Output: { quantity: 2 }

Default for a Missing or Null Key

Use an exact optional nullable field when missing and null should produce the default but undefined should be rejected.

Operation	Behavior
Decoding	Applies the default value if the input is missing or `null`
Encoding	Transforms the input `t: T` back to `e: E`

Example (Applying Default Only When Field Is Missing or null)

1
import { Option, Predicate, Schema, SchemaGetter } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalKey(Schema.NullOr(Schema.FiniteFromString)).pipe(
5
    Schema.decodeTo(Schema.Finite, {
6
      decode: SchemaGetter.transformOptional((o) =>
7
        o.pipe(
8
          Option.filter(Predicate.isNotNull),
9
          Option.orElseSome(() => 1),
10
        ),
11
      ),
12
      encode: SchemaGetter.required(),
13
    }),
14
  ),
15
})
16

17
//     ┌─── { readonly quantity?: string | null; }
18
//     ▼
19
type Encoded = typeof Product.Encoded
20

21
//     ┌─── { readonly quantity: number; }
22
//     ▼
23
type Type = typeof Product.Type
24

25
console.log(Schema.decodeUnknownSync(Product)({}))
26
// Output: { quantity: 1 }
27

28
console.log(Schema.decodeUnknownSync(Product)({ quantity: null }))
29
// Output: { quantity: 1 }
30

31
console.log(Schema.decodeUnknownSync(Product)({ quantity: "2" }))
32
// Output: { quantity: 2 }
33

34
console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
35
/*
36
throws:
37
SchemaError: Expected string | null
38
  at ["quantity"]
39
*/

Optional Fields as Options

When working with optional fields, you may want to handle them as Option values. This approach allows you to explicitly manage the presence or absence of a field rather than relying on undefined or null.

Basic Optional with Option Type

Schema.OptionFromOptional converts a missing or undefined field to Option.none() and an existing value to Option.some().

Decoding

Input	Output
`<missing value>`	transforms to `Option.none()`
`undefined`	transforms to `Option.none()`
`e: E`	transforms to `Option.some(t: T)`

Encoding

Input	Output
`Option.none()`	transforms to `<missing value>`
`Option.some(t: T)`	transforms back to `e: E`

Example (Handling Optional Field as Option)

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.OptionFromOptional(Schema.FiniteFromString),
5
})
6

7
//     ┌─── { readonly quantity?: string | undefined; }
8
//     ▼
9
type Encoded = typeof Product.Encoded
10

11
//     ┌─── { readonly quantity: Option<number>; }
12
//     ▼
13
type Type = typeof Product.Type
14

15
console.log(Schema.decodeUnknownSync(Product)({}))
16
// Output: { quantity: { _id: 'Option', _tag: 'None' } }
17

18
console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
19
// Output: { quantity: { _id: 'Option', _tag: 'None' } }
20

21
console.log(Schema.decodeUnknownSync(Product)({ quantity: "2" }))
22
// Output: { quantity: { _id: 'Option', _tag: 'Some', value: 2 } }

Exact Optional Key as an Option

Schema.OptionFromOptionalKey converts a missing key to Option.none() while rejecting undefined when the key is present.

Decoding

Input	Output
`<missing value>`	transforms to `Option.none()`
`undefined`	`SchemaError`
`e: E`	transforms to `Option.some(t: T)`

Encoding

Input	Output
`Option.none()`	transforms to `<missing value>`
`Option.some(t: T)`	transforms back to `e: E`

Example (Using Exactness with Optional Field as Option)

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.OptionFromOptionalKey(Schema.FiniteFromString),
5
})
6

7
//     ┌─── { readonly quantity?: string; }
8
//     ▼
9
type Encoded = typeof Product.Encoded
10

11
//     ┌─── { readonly quantity: Option<number>; }
12
//     ▼
13
type Type = typeof Product.Type
14

15
console.log(Schema.decodeUnknownSync(Product)({}))
16
// Output: { quantity: { _id: 'Option', _tag: 'None' } }
17

18
console.log(Schema.decodeUnknownSync(Product)({ quantity: "2" }))
19
// Output: { quantity: { _id: 'Option', _tag: 'Some', value: 2 } }
20

21
console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
22
/*
23
throws:
24
SchemaError: Expected string
25
  at ["quantity"]
26
*/

Optional with Nullability

Schema.OptionFromOptionalNullOr also treats null as Option.none().

Decoding

Input	Output
`<missing value>`	transforms to `Option.none()`
`undefined`	transforms to `Option.none()`
`null`	transforms to `Option.none()`
`e: E`	transforms to `Option.some(t: T)`

Encoding

Input	Output
`Option.none()`	transforms to `<missing value>`
`Option.some(t: T)`	transforms back to `e: E`

Example (Handling Null as Missing Value with Optional Field as Option)

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.OptionFromOptionalNullOr(Schema.FiniteFromString),
5
})
6

7
//     ┌─── { readonly quantity?: string | null | undefined; }
8
//     ▼
9
type Encoded = typeof Product.Encoded
10

11
//     ┌─── { readonly quantity: Option<number>; }
12
//     ▼
13
type Type = typeof Product.Type
14

15
console.log(Schema.decodeUnknownSync(Product)({}))
16
// Output: { quantity: { _id: 'Option', _tag: 'None' } }
17

18
console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
19
// Output: { quantity: { _id: 'Option', _tag: 'None' } }
20

21
console.log(Schema.decodeUnknownSync(Product)({ quantity: null }))
22
// Output: { quantity: { _id: 'Option', _tag: 'None' } }
23

24
console.log(Schema.decodeUnknownSync(Product)({ quantity: "2" }))
25
// Output: { quantity: { _id: 'Option', _tag: 'Some', value: 2 } }

Exact Optional Nullable Key as an Option

Combine Schema.optionalKey, Schema.NullOr, and SchemaGetter.transformOptional when missing and null should become Option.none() but undefined should be rejected.

Decoding

Input	Output
`<missing value>`	transforms to `Option.none()`
`undefined`	`SchemaError`
`null`	transforms to `Option.none()`
`e: E`	transforms to `Option.some(t: T)`

Encoding

Input	Output
`Option.none()`	transforms to `<missing value>`
`Option.some(t: T)`	transforms back to `e: E`

Example (Using Exactness and Handling Null as Missing Value with Optional Field as Option)

1
import { Option, Predicate, Schema, SchemaGetter } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalKey(Schema.NullOr(Schema.FiniteFromString)).pipe(
5
    Schema.decodeTo(Schema.Option(Schema.Finite), {
6
      decode: SchemaGetter.transformOptional((o) =>
7
        Option.some(o.pipe(Option.filter(Predicate.isNotNull))),
8
      ),
9
      encode: SchemaGetter.transformOptional(Option.flatten),
10
    }),
11
  ),
12
})
13

14
//     ┌─── { readonly quantity?: string | null; }
15
//     ▼
16
type Encoded = typeof Product.Encoded
17

18
//     ┌─── { readonly quantity: Option<number>; }
19
//     ▼
20
type Type = typeof Product.Type
21

22
console.log(Schema.decodeUnknownSync(Product)({}))
23
// Output: { quantity: { _id: 'Option', _tag: 'None' } }
24

25
console.log(Schema.decodeUnknownSync(Product)({ quantity: null }))
26
// Output: { quantity: { _id: 'Option', _tag: 'None' } }
27

28
console.log(Schema.decodeUnknownSync(Product)({ quantity: "2" }))
29
// Output: { quantity: { _id: 'Option', _tag: 'Some', value: 2 } }
30

31
console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
32
/*
33
throws:
34
SchemaError: Expected string | null
35
  at ["quantity"]
36
*/

Optional Field Transformations

Optional to Optional

Use Schema.decodeTo with SchemaGetter.transformOptional to transform an optional encoded field into an optional decoded field. This lets the transformation decide whether the key is present on either side.

One common use case is treating a specific encoded value, such as an empty string, as an absent field in the decoded output.

The decoding and encoding getters receive an Option: None means the key is absent, and returning None omits it from the output.

Example (Omitting Empty Strings from the Output)

Consider an optional field of type string where empty strings in the input should be removed from the output.

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

3
const schema = Schema.Struct({
4
  nonEmpty: Schema.optionalKey(Schema.String).pipe(
5
    Schema.decodeTo(Schema.optionalKey(Schema.String), {
6
      //         ┌─── Option<string>
7
      //         ▼
8
      decode: SchemaGetter.transformOptional((maybeString) => {
9
        if (Option.isNone(maybeString)) {
10
          // If `maybeString` is `None`, the field is absent in the input.
11
          // Return Option.none() to omit it in the output.
12
          return Option.none()
13
        }
14
        // Extract the value from the `Some` instance
15
        const value = maybeString.value
16
        if (value === "") {
17
          // Treat empty strings as missing in the output
18
          // by returning Option.none().
19
          return Option.none()
20
        }
21
        // Include non-empty strings in the output.
22
        return Option.some(value)
23
      }),
24
      // In the encoding phase, you can decide to process the field
25
      // similarly to the decoding phase or use a different logic.
26
      // Here, the logic is left unchanged.
27
      //
28
      //         ┌─── Option<string>
29
      //         ▼
30
      encode: SchemaGetter.transformOptional((maybeString) => maybeString),
31
    }),
32
  ),
33
})
34

35
// Decoding examples
36

37
const decode = Schema.decodeUnknownSync(schema)
38

39
console.log(decode({}))
40
// Output: {}
41
console.log(decode({ nonEmpty: "" }))
42
// Output: {}
43
console.log(decode({ nonEmpty: "a non-empty string" }))
44
// Output: { nonEmpty: 'a non-empty string' }
45

46
// Encoding examples
47

48
const encode = Schema.encodeSync(schema)
49

50
console.log(encode({}))
51
// Output: {}
52
console.log(encode({ nonEmpty: "" }))
53
// Output: { nonEmpty: '' }
54
console.log(encode({ nonEmpty: "a non-empty string" }))
55
// Output: { nonEmpty: 'a non-empty string' }

You can simplify the decoding logic with Option.filter, which filters out unwanted values in a concise way.

Example (Using Option.filter for Decoding)

1
import { identity, Option, Schema, SchemaGetter } from "effect"
2

3
const schema = Schema.Struct({
4
  nonEmpty: Schema.optionalKey(Schema.String).pipe(
5
    Schema.decodeTo(Schema.optionalKey(Schema.String), {
6
      decode: SchemaGetter.transformOptional(Option.filter((s) => s !== "")),
7
      encode: SchemaGetter.transformOptional(identity),
8
    }),
9
  ),
10
})

Optional to Required

Use an optional schema on the encoded side and a required schema on the decoded side. SchemaGetter.transformOptional can supply a value when the encoded key is missing and omit selected values during encoding.

Example (Setting null as Default for Missing Field)

This example provides a null value when the encoded field is missing. During encoding, a decoded null value omits the field.

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

3
const schema = Schema.Struct({
4
  nullable: Schema.optionalKey(
5
    // Input schema for an optional string
6
    Schema.String,
7
  ).pipe(
8
    Schema.decodeTo(
9
      // Output schema allowing null or string
10
      Schema.NullOr(Schema.String),
11
      {
12
        //         ┌─── Option<string>
13
        //         ▼
14
        decode: SchemaGetter.transformOptional((maybeString) => {
15
          if (Option.isNone(maybeString)) {
16
            // If `maybeString` is `None`, the field is absent in the input.
17
            // Return `null` as the default value for the output.
18
            return Option.some(null)
19
          }
20
          // Extract the value from the `Some` instance
21
          // and use it as the output.
22
          return Option.some(maybeString.value)
23
        }),
24
        // During encoding, treat `null` as an absent field
25
        //
26
        //         ┌─── string | null
27
        //         ▼
28
        encode: SchemaGetter.transformOptional((maybeStringOrNull) =>
29
          Option.flatMap(maybeStringOrNull, (stringOrNull) =>
30
            stringOrNull === null
31
              ? // Omit the field by returning `None`
32
                Option.none()
33
              : // Include the field by returning `Some`
34
                Option.some(stringOrNull),
35
          ),
36
        ),
37
      },
38
    ),
39
  ),
40
})
41

42
// Decoding examples
43

44
const decode = Schema.decodeUnknownSync(schema)
45

46
console.log(decode({}))
47
// Output: { nullable: null }
48
console.log(decode({ nullable: "a value" }))
49
// Output: { nullable: 'a value' }
50

51
// Encoding examples
52

53
const encode = Schema.encodeSync(schema)
54

55
console.log(encode({ nullable: "a value" }))
56
// Output: { nullable: 'a value' }
57
console.log(encode({ nullable: null }))
58
// Output: {}

You can streamline the decoding and encoding logic using Option.getOrElse and Option.liftPredicate for concise and readable transformations.

Example (Using Option.getOrElse and Option.liftPredicate)

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

3
const schema = Schema.Struct({
4
  nullable: Schema.optionalKey(Schema.String).pipe(
5
    Schema.decodeTo(Schema.NullOr(Schema.String), {
6
      decode: SchemaGetter.transformOptional(Option.orElseSome(() => null)),
7
      encode: SchemaGetter.transformOptional(
8
        Option.filter((value) => value !== null),
9
      ),
10
    }),
11
  ),
12
})

Required to Optional

Use a required schema on the encoded side and an optional schema on the decoded side. The transformation can omit selected decoded values and must restore a required value during encoding.

Example (Handling Empty String as Missing Value)

In this example, the name field is required but treated as optional if it is an empty string. During decoding, an empty string in name is considered absent, while encoding ensures a value (using an empty string as a default if name is absent).

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

3
const schema = Schema.Struct({
4
  name: Schema.String.pipe(
5
    Schema.decodeTo(Schema.optionalKey(Schema.String), {
6
      //         ┌─── Option<string>
7
      //         ▼
8
      decode: SchemaGetter.transformOptional((maybeString) =>
9
        Option.flatMap(maybeString, (string) => {
10
          // Treat empty string as a missing value
11
          if (string === "") {
12
            // Omit the field by returning `None`
13
            return Option.none()
14
          }
15
          // Otherwise, return the string as is
16
          return Option.some(string)
17
        }),
18
      ),
19
      //         ┌─── Option<string>
20
      //         ▼
21
      encode: SchemaGetter.transformOptional((maybeString) => {
22
        // Check if the field is missing
23
        if (Option.isNone(maybeString)) {
24
          // Provide an empty string as default
25
          return Option.some("")
26
        }
27
        // Otherwise, return the string as is
28
        return maybeString
29
      }),
30
    }),
31
  ),
32
})
33

34
// Decoding examples
35

36
const decode = Schema.decodeUnknownSync(schema)
37

38
console.log(decode({ name: "John" }))
39
// Output: { name: 'John' }
40
console.log(decode({ name: "" }))
41
// Output: {}
42

43
// Encoding examples
44

45
const encode = Schema.encodeSync(schema)
46

47
console.log(encode({ name: "John" }))
48
// Output: { name: 'John' }
49
console.log(encode({}))
50
// Output: { name: '' }

You can streamline the decoding and encoding logic using Option.liftPredicate and Option.getOrElse for concise and readable transformations.

Example (Using Option.liftPredicate and Option.getOrElse)

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

3
const schema = Schema.Struct({
4
  name: Schema.String.pipe(
5
    Schema.decodeTo(Schema.optionalKey(Schema.String), {
6
      decode: SchemaGetter.transformOptional((maybeString) =>
7
        Option.flatMap(
8
          maybeString,
9
          Option.liftPredicate((s) => s !== ""),
10
        ),
11
      ),
12
      encode: SchemaGetter.transformOptional((maybeString) =>
13
        Option.some(Option.getOrElse(maybeString, () => "")),
14
      ),
15
    }),
16
  ),
17
})

Extending Schemas

Struct schemas expose their fields, which you can spread into a new struct or extend with Schema.fieldsAssign. Unions expose mapMembers, so the same field operation can be applied to every struct member.

Spreading Struct fields

Structs provide access to their fields through the fields property, which allows you to extend an existing struct by adding additional fields or combining fields from multiple structs.

Example (Adding New Fields)

1
import { Schema } from "effect"
2

3
const Original = Schema.Struct({
4
  a: Schema.String,
5
  b: Schema.String,
6
})
7

8
const Extended = Schema.Struct({
9
  ...Original.fields,
10
  // Adding new fields
11
  c: Schema.String,
12
  d: Schema.String,
13
})
14

15
//     ┌─── {
16
//     |      readonly a: string;
17
//     |      readonly b: string;
18
//     |      readonly c: string;
19
//     |      readonly d: string;
20
//     |    }
21
//     ▼
22
type Type = typeof Extended.Type

Example (Adding Additional Index Signatures)

1
import { Schema } from "effect"
2

3
const Original = Schema.Struct({
4
  a: Schema.String,
5
  b: Schema.String,
6
})
7

8
const Extended = Schema.StructWithRest(
9
  Schema.Struct(Original.fields),
10
  // Adding an index signature
11
  [Schema.Record(Schema.String, Schema.String)],
12
)
13

14
//     ┌─── {
15
//     │      readonly [x: string]: string;
16
//     |      readonly a: string;
17
//     |      readonly b: string;
18
//     |    }
19
//     ▼
20
type Type = typeof Extended.Type

Example (Combining Fields from Multiple Structs)

1
import { Schema } from "effect"
2

3
const Struct1 = Schema.Struct({
4
  a: Schema.String,
5
  b: Schema.String,
6
})
7

8
const Struct2 = Schema.Struct({
9
  c: Schema.String,
10
  d: Schema.String,
11
})
12

13
const Extended = Schema.Struct({
14
  ...Struct1.fields,
15
  ...Struct2.fields,
16
})
17

18
//     ┌─── {
19
//     |      readonly a: string;
20
//     |      readonly b: string;
21
//     |      readonly c: string;
22
//     |      readonly d: string;
23
//     |    }
24
//     ▼
25
type Type = typeof Extended.Type

The fieldsAssign Function

Schema.fieldsAssign(fields) is a concise form of struct.mapFields(Struct.assign(fields)). Use it directly on a struct, or map it over every member of a union.

Example (Adding Fields to Every Union Member)

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

3
const Struct = Schema.Struct({
4
  a: Schema.String,
5
})
6

7
const UnionOfStructs = Schema.Union([
8
  Schema.Struct({ b: Schema.String }),
9
  Schema.Struct({ c: Schema.String }),
10
])
11

12
const Extended = UnionOfStructs.mapMembers(
13
  Tuple.map(Schema.fieldsAssign(Struct.fields)),
14
)
15

16
//     ┌─── {
17
//     |        readonly a: string;
18
//     |    } & ({
19
//     |        readonly b: string;
20
//     |    } | {
21
//     |        readonly c: string;
22
//     |    })
23
//     ▼
24
type Type = typeof Extended.Type

Renaming Properties

Renaming a Property During Definition

To use a different key in the encoded representation, apply Schema.encodeKeys after defining the struct.

Example (Renaming a Required Property)

1
import { Schema } from "effect"
2

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

8
//     ┌─── { readonly c: string; readonly b: number; }
9
//     ▼
10
type Encoded = typeof schema.Encoded
11

12
//     ┌─── { readonly a: string; readonly b: number; }
13
//     ▼
14
type Type = typeof schema.Type
15

16
console.log(Schema.decodeUnknownSync(schema)({ c: "c", b: 1 }))
17
// Output: { a: "c", b: 1 }

Example (Renaming an Optional Property)

1
import { Schema } from "effect"
2

3
const schema = Schema.Struct({
4
  a: Schema.optional(Schema.String),
5
  b: Schema.Finite,
6
}).pipe(Schema.encodeKeys({ a: "c" }))
7

8
//     ┌─── { readonly b: number; readonly c?: string | undefined; }
9
//     ▼
10
type Encoded = typeof schema.Encoded
11

12
//     ┌─── { readonly a?: string | undefined; readonly b: number; }
13
//     ▼
14
type Type = typeof schema.Type
15

16
console.log(Schema.decodeUnknownSync(schema)({ c: "c", b: 1 }))
17
// Output: { a: 'c', b: 1 }
18

19
console.log(Schema.decodeUnknownSync(schema)({ b: 1 }))
20
// Output: { b: 1 }

Renaming Properties of an Existing Schema

For an existing struct, rename its decoded fields with mapFields, then use Schema.encodeKeys to preserve the original names in the encoded representation. For a union, apply the same operation to each member.

Example (Renaming Properties in a Struct Schema)

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

3
const Original = Schema.Struct({
4
  c: Schema.String,
5
  b: Schema.Finite,
6
})
7

8
// Renaming the "c" property to "a"
9
//
10
//
11
//      ┌─── Struct<{
12
//      |      readonly a: string;
13
//      |      readonly b: number;
14
//      |    }>
15
//      ▼
16
const Renamed = Original.mapFields((fields) => ({
17
  a: fields.c,
18
  ...Struct.omit(fields, ["c"]),
19
})).pipe(Schema.encodeKeys({ a: "c" }))
20

21
console.log(Schema.decodeUnknownSync(Renamed)({ c: "c", b: 1 }))
22
// Output: { a: "c", b: 1 }

Example (Renaming Properties in Union Schemas)

1
import { Schema } from "effect"
2

3
const Original = Schema.Union([
4
  Schema.Struct({
5
    a: Schema.String,
6
    b: Schema.Finite,
7
  }),
8
  Schema.Struct({
9
    a: Schema.String,
10
    d: Schema.Boolean,
11
  }),
12
])
13

14
// Use "c" for "a" in the encoded representation of every member
15
const Renamed = Original.mapMembers(
16
  ([first, second]) =>
17
    [
18
      first.pipe(Schema.encodeKeys({ a: "c" })),
19
      second.pipe(Schema.encodeKeys({ a: "c" })),
20
    ] as const,
21
)
22

23
console.log(Schema.decodeUnknownSync(Renamed)({ c: "c", b: 1 }))
24
// Output: { a: "c", b: 1 }
25

26
console.log(Schema.decodeUnknownSync(Renamed)({ c: "c", d: false }))
27
// Output: { a: "c", d: false }

Recursive Schemas

The Schema.suspend function is designed for defining schemas that reference themselves, such as in recursive data structures.

Example (Self-Referencing Schema)

In this example, the Category schema references itself through the subcategories field, which is an array of Category objects.

1
import { Schema } from "effect"
2

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

8
const Category = Schema.Struct({
9
  name: Schema.String,
10
  subcategories: Schema.Array(
11
    Schema.suspend((): Schema.Codec<Category> => Category),
12
  ),
13
})

Example (Type Inference Error)

1
import { Schema } from "effect"
2

3
// @errors: 7022
4
const Category = Schema.Struct({
5
  name: Schema.String,
6
  // @errors: 7022 7024
7
  subcategories: Schema.Array(Schema.suspend(() => Category)),
8
})

A Helpful Pattern to Simplify Schema Definition

As we’ve observed, it’s necessary to define an interface for the Type 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 Fields)

1
import { Schema } from "effect"
2

3
const fields = {
4
  name: Schema.String,
5
  // ...other fields as needed
6
}
7

8
// Define an interface for the Category schema,
9
// extending the Type of the defined fields
10
interface Category extends Schema.Struct.Type<typeof fields> {
11
  // Define `subcategories` using recursion
12
  readonly subcategories: ReadonlyArray<Category>
13
}
14

15
const Category = Schema.Struct({
16
  ...fields, // Spread in the base fields
17
  subcategories: Schema.Array(
18
    // Define `subcategories` using recursion
19
    Schema.suspend((): Schema.Codec<Category> => Category),
20
  ),
21
})

Mutually Recursive Schemas

You can also use Schema.suspend to create mutually recursive schemas, where two schemas reference each other. In the following example, Expression and Operation form a simple arithmetic expression tree by referencing each other.

Example (Defining Mutually Recursive Schemas)

1
import { Schema } from "effect"
2

3
interface Expression {
4
  readonly type: "expression"
5
  readonly value: number | Operation
6
}
7

8
interface Operation {
9
  readonly type: "operation"
10
  readonly operator: "+" | "-"
11
  readonly left: Expression
12
  readonly right: Expression
13
}
14

15
const Expression = Schema.Struct({
16
  type: Schema.Literal("expression"),
17
  value: Schema.Union([
18
    Schema.Finite,
19
    Schema.suspend((): Schema.Codec<Operation> => Operation),
20
  ]),
21
})
22

23
const Operation = Schema.Struct({
24
  type: Schema.Literal("operation"),
25
  operator: Schema.Literals(["+", "-"]),
26
  left: Expression,
27
  right: Expression,
28
})

Recursive Types with Different Encoded and Type

Defining a recursive schema where the Encoded type differs from the Type type adds another layer of complexity. In such cases, we need to define two interfaces: one for the Type type, as seen previously, and another for the Encoded type.

Example (Recursive Schema with Different Encoded and Type Definitions)

Let’s consider an example with an id field defined by Schema.FiniteFromString. Its Type is number, while its Encoded type is string. When we add this field to the Category schema, TypeScript raises an error:

1
import { Schema } from "effect"
2

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

8
interface Category extends Schema.Struct.Type<typeof fields> {
9
  readonly subcategories: ReadonlyArray<Category>
10
}
11

12
const Category = Schema.Struct({
13
  ...fields,
14
  subcategories: Schema.Array(
15
    // @errors: 2322
16
    Schema.suspend((): Schema.Codec<Category> => Category),
17
  ),
18
})

This fails because Schema.Codec<Category> defaults the encoded type to Category. The recursive edge must also specify CategoryEncoded:

1
import { Schema } from "effect"
2

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

8
interface Category extends Schema.Struct.Type<typeof fields> {
9
  readonly subcategories: ReadonlyArray<Category>
10
}
11

12
interface CategoryEncoded extends Schema.Struct.Encoded<typeof fields> {
13
  readonly subcategories: ReadonlyArray<CategoryEncoded>
14
}
15

16
const Category = Schema.Struct({
17
  ...fields,
18
  subcategories: Schema.Array(
19
    Schema.suspend((): Schema.Codec<Category, CategoryEncoded> => Category),
20
  ),
21
})