Advanced Usage

Declaring New Data Types

Primitive Data Types

To declare a schema for a primitive data type, such as File, you can use the Schema.declare function along with a type guard.

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 FileFromSelf = Schema.declare((input: unknown): input is File => input instanceof File)
5

6
const decode = Schema.decodeUnknownSync(FileFromSelf)
7

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

15
// Decoding an invalid input
16
decode(null)
17
/*
18
throws
19
ParseError: Expected <declaration schema>, actual null
20
*/

To enhance the default error message, you can add annotations, particularly the identifier, title, and description annotations (none of these annotations are required, but they are encouraged for good practice and can make your schema “self-documenting”). These annotations will be utilized by the messaging system to return more meaningful messages.

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 FileFromSelf = Schema.declare((input: unknown): input is File => input instanceof File, {
5
  // A unique identifier for the schema
6
  identifier: "FileFromSelf",
7
  // Detailed description of the schema
8
  description: "The `File` type in JavaScript",
9
})
10

11
const decode = Schema.decodeUnknownSync(FileFromSelf)
12

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

20
// Decoding an invalid input
21
decode(null)
22
/*
23
throws
24
ParseError: Expected FileFromSelf, actual null
25
*/

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<A>)

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

3
export const MyReadonlySet = <A, I, R>(
4
  // Schema for the elements of the Set
5
  item: Schema.Schema<A, I, R>,
6
): Schema.Schema<ReadonlySet<A>, ReadonlySet<I>, R> =>
7
  Schema.declare(
8
    // Store the schema for the Set's elements
9
    [item],
10
    {
11
      // Decoding function
12
      decode: (item) => (input, parseOptions, ast) => {
13
        if (input instanceof Set) {
14
          // Decode each element in the Set
15
          const elements = ParseResult.decodeUnknown(Schema.Array(item))(
16
            Array.from(input.values()),
17
            parseOptions,
18
          )
19
          // Return a ReadonlySet containing the decoded elements
20
          return ParseResult.map(elements, (as): ReadonlySet<A> => new Set(as))
21
        }
22
        // Handle invalid input
23
        return ParseResult.fail(new ParseResult.Type(ast, input))
24
      },
25
      // Encoding function
26
      encode: (item) => (input, parseOptions, ast) => {
27
        if (input instanceof Set) {
28
          // Encode each element in the Set
29
          const elements = ParseResult.encodeUnknown(Schema.Array(item))(
30
            Array.from(input.values()),
31
            parseOptions,
32
          )
33
          // Return a ReadonlySet containing the encoded elements
34
          return ParseResult.map(elements, (is): ReadonlySet<I> => new Set(is))
35
        }
36
        // Handle invalid input
37
        return ParseResult.fail(new ParseResult.Type(ast, input))
38
      },
39
    },
40
    {
41
      description: `ReadonlySet<${Schema.format(item)}>`,
42
    },
43
  )
44

45
// Define a schema for a ReadonlySet of numbers
46
const setOfNumbers = MyReadonlySet(Schema.NumberFromString)
47

48
const decode = Schema.decodeUnknownSync(setOfNumbers)
49

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

52
// Decode an invalid input
53
decode(null)
54
/*
55
throws
56
ParseError: Expected ReadonlySet<NumberFromString>, actual null
57
*/
58

59
// Decode a Set with an invalid element
60
decode(new Set(["1", null, "3"]))
61
/*
62
throws
63
ParseError: ReadonlyArray<NumberFromString>
64
└─ [1]
65
   └─ NumberFromString
66
      └─ Encoded side transformation failure
67
         └─ Expected string, actual null
68
*/

Adding Compilers Annotations

When defining a new data type, some compilers like Arbitrary or Pretty may not know how to handle the new type. This can result in an error, as the compiler may lack the necessary information for generating instances or producing readable output:

Example (Attempting to Generate Arbitrary Values Without Required Annotations)

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

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

8
// Try creating an Arbitrary instance for the schema
9
const arb = Arbitrary.make(FileFromSelf)
10
/*
11
throws:
12
Error: Missing annotation
13
details: Generating an Arbitrary for this schema requires an "arbitrary" annotation
14
schema (Declaration): FileFromSelf
15
*/

In the above example, attempting to generate arbitrary values for the FileFromSelf schema fails because the compiler lacks necessary annotations. To resolve this, you need to provide annotations for generating arbitrary data:

Example (Adding Arbitrary Annotation for Custom File Schema)

1
import { Arbitrary, FastCheck, Pretty, Schema } from "effect"
2

3
const FileFromSelf = Schema.declare((input: unknown): input is File => input instanceof File, {
4
  identifier: "FileFromSelf",
5
  // Provide a function to generate random File instances
6
  arbitrary: () => (fc) =>
7
    fc.tuple(fc.string(), fc.string()).map(([content, path]) => new File([content], path)),
8
})
9

10
// Create an Arbitrary instance for the schema
11
const arb = Arbitrary.make(FileFromSelf)
12

13
// Generate sample files using the Arbitrary instance
14
const files = FastCheck.sample(arb, 2)
15
console.log(files)
16
/*
17
Example Output:
18
[
19
  File { size: 5, type: '', name: 'C', lastModified: 1706435571176 },
20
  File { size: 1, type: '', name: '98Ggmc', lastModified: 1706435571176 }
21
]
22
*/

For more details on how to add annotations for the Arbitrary compiler, 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

Note that you can use unique symbols as brands to ensure uniqueness across modules / packages.

Example (Using a unique symbol as a Brand)

1
import { Schema } from "effect"
2

3
const UserIdBrand: unique symbol = Symbol.for("UserId")
4

5
const UserId = Schema.String.pipe(Schema.brand(UserIdBrand))
6

7
// string & Brand<typeof UserIdBrand>
8
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))

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") // Creates a branded UserId

Property Signatures

A PropertySignature represents a transformation from a “From” field to a “To” field. This allows you to define mappings between incoming data fields and your internal model.

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.propertySignature(Schema.NumberFromString).annotations({
6
    title: "Age", // Annotation to label the age field
7
  }),
8
})

A PropertySignature type contains several parameters, each providing details about the transformation between the source field (From) and the target field (To). Let’s take a look at what each of these parameters represents:

age: PropertySignature<ToToken, ToType, FromKey, FromToken, FromType, HasDefault, Context>

Parameter	Description
`age`	Key of the “To” field
`ToToken`	Indicates field requirement: `"?:"` for optional, `":"` for required
`ToType`	Type of the “To” field
`FromKey`	(Optional, default = `never`) Indicates the source field key, typically the same as “To” field key unless specified
`FromToken`	Indicates source field requirement: `"?:"` for optional, `":"` for required
`FromType`	Type of the “From” field
`HasDefault`	Indicates if there is a constructor default value (Boolean)

In the example above, the PropertySignature type for age is:

PropertySignature<":", number, never, ":", string, false, never>

This means:

Parameter	Description
`age`	Key of the “To” field
`ToToken`	`":"` indicates that the `age` field is required
`ToType`	Type of the `age` field is `number`
`FromKey`	`never` indicates that the decoding occurs from the same field named `age`
`FromToken`	`":"` indicates that the decoding occurs from a required `age` field
`FromType`	Type of the “From” field is `string`
`HasDefault`	`false`: indicates there is no default value

Sometimes, the source field (the “From” field) may have a different name from the field in your internal model. You can map between these fields using the Schema.fromKey function.

Example (Mapping from a Different Key)

1
import { Schema } from "effect"
2

3
const Person = Schema.Struct({
4
  name: Schema.String,
5
  age: Schema.propertySignature(Schema.NumberFromString).pipe(
6
    Schema.fromKey("AGE"), // Maps from "AGE" to "age"
7
  ),
8
})
9

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

When you map from "AGE" to "age", the PropertySignature type changes to:

PropertySignature<":", number, never, ":", string, false, never>
PropertySignature<":", number, "AGE", ":", string, false, never>

Optional Fields

Basic Optional Property

The syntax:

Schema.optional(schema: Schema<A, I, R>)

creates an optional property within a schema, allowing fields to be omitted or set to undefined.

Decoding

Input	Output
`<missing value>`	remains `<missing value>`
`undefined`	remains `undefined`
`i: I`	transforms to `a: A`

Encoding

Input	Output
`<missing value>`	remains `<missing value>`
`undefined`	remains `undefined`
`a: A`	transforms back to `i: I`

Example (Defining an Optional Number Field)

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optional(Schema.NumberFromString),
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 }

Exposed Values

You can access the original schema type (before it was marked as optional) using the from property.

Example (Accessing the Original Schema)

1
import { Schema } from "effect"
2

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

7
//      ┌─── typeof Schema.NumberFromString
8
//      ▼
9
const from = Product.fields.quantity.from

Optional with Nullability

The syntax:

Schema.optionalWith(schema: Schema<A, I, R>, { nullable: true })

creates an optional property within a schema, treating null values the same as missing values.

Decoding

Input	Output
`<missing value>`	remains `<missing value>`
`undefined`	remains `undefined`
`null`	transforms to `<missing value>`
`i: I`	transforms to `a: A`

Encoding

Input	Output
`<missing value>`	remains `<missing value>`
`undefined`	remains `undefined`
`a: A`	transforms back to `i: I`

Example (Handling Null as Missing Value)

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalWith(Schema.NumberFromString, {
5
    nullable: true,
6
  }),
7
})
8

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

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

17
// Decoding examples
18

19
console.log(Schema.decodeUnknownSync(Product)({ quantity: "1" }))
20
// Output: { quantity: 1 }
21
console.log(Schema.decodeUnknownSync(Product)({}))
22
// Output: {}
23
console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
24
// Output: { quantity: undefined }
25
console.log(Schema.decodeUnknownSync(Product)({ quantity: null }))
26
// Output: {}
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: {}
34
console.log(Schema.encodeSync(Product)({ quantity: undefined }))
35
// Output: { quantity: undefined }

Exposed Values

You can access the original schema type (before it was marked as optional) using the from property.

Example (Accessing the Original Schema)

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalWith(Schema.NumberFromString, {
5
    nullable: true,
6
  }),
7
})
8

9
//      ┌─── typeof Schema.NumberFromString
10
//      ▼
11
const from = Product.fields.quantity.from

Optional with Exactness

The syntax:

Schema.optionalWith(schema: Schema<A, I, R>, { exact: true })

creates an optional property while enforcing strict typing. This means that only the specified type (excluding undefined) is accepted. Any attempt to decode undefined results in an error.

Decoding

Input	Output
`<missing value>`	remains `<missing value>`
`undefined`	`ParseError`
`i: I`	transforms to `a: A`

Encoding

Input	Output
`<missing value>`	remains `<missing value>`
`a: A`	transforms back to `i: I`

Example (Using Exactness with Optional Field)

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalWith(Schema.NumberFromString, { exact: true }),
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
ParseError: { readonly quantity?: NumberFromString }
25
└─ ["quantity"]
26
   └─ NumberFromString
27
      └─ Encoded side transformation failure
28
         └─ Expected string, actual undefined
29
*/
30

31
// Encoding examples
32

33
console.log(Schema.encodeSync(Product)({ quantity: 1 }))
34
// Output: { quantity: "1" }
35
console.log(Schema.encodeSync(Product)({}))
36
// Output: {}

Exposed Values

You can access the original schema type (before it was marked as optional) using the from property.

Example (Accessing the Original Schema)

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalWith(Schema.NumberFromString, { exact: true }),
5
})
6

7
//      ┌─── typeof Schema.NumberFromString
8
//      ▼
9
const from = Product.fields.quantity.from

Combining Nullability and Exactness

The syntax:

Schema.optionalWith(schema: Schema<A, I, R>, { exact: true, nullable: true })

allows you to define an optional property that enforces strict typing (exact type only) while also treating null as equivalent to a missing value.

Decoding

Input	Output
`<missing value>`	remains `<missing value>`
`null`	transforms to `<missing value>`
`undefined`	`ParseError`
`i: I`	transforms to `a: A`

Encoding

Input	Output
`<missing value>`	remains `<missing value>`
`a: A`	transforms back to `i: I`

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

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalWith(Schema.NumberFromString, {
5
    exact: true,
6
    nullable: true,
7
  }),
8
})
9

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

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

18
// Decoding examples
19

20
console.log(Schema.decodeUnknownSync(Product)({ quantity: "1" }))
21
// Output: { quantity: 1 }
22
console.log(Schema.decodeUnknownSync(Product)({}))
23
// Output: {}
24
console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
25
/*
26
throws:
27
ParseError: (Struct (Encoded side) <-> Struct (Type side))
28
└─ Encoded side transformation failure
29
   └─ Struct (Encoded side)
30
      └─ ["quantity"]
31
         └─ NumberFromString | null
32
            ├─ NumberFromString
33
            │  └─ Encoded side transformation failure
34
            │     └─ Expected string, actual undefined
35
            └─ Expected null, actual undefined
36
*/
37
console.log(Schema.decodeUnknownSync(Product)({ quantity: null }))
38
// Output: {}
39

40
// Encoding examples
41

42
console.log(Schema.encodeSync(Product)({ quantity: 1 }))
43
// Output: { quantity: "1" }
44
console.log(Schema.encodeSync(Product)({}))
45
// Output: {}

Exposed Values

You can access the original schema type (before it was marked as optional) using the from property.

Example (Accessing the Original Schema)

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalWith(Schema.NumberFromString, {
5
    exact: true,
6
    nullable: true,
7
  }),
8
})
9

10
//      ┌─── typeof Schema.NumberFromString
11
//      ▼
12
const from = Product.fields.quantity.from

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, the Schema.optionalWith function is recommended. It ensures stricter enforcement of the field’s absence.

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalWith(Schema.Never, { exact: true }),
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

The default option in Schema.optionalWith allows you to set default values that are applied during both decoding and object construction phases. This feature ensures that even if certain properties are not provided by the user, the system will automatically use the specified default values.

The Schema.optionalWith function offers several ways to control how defaults are applied during decoding and encoding. You can fine-tune whether defaults are applied only when the input is completely missing, or even when null or undefined values are provided.

Basic Default

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

Syntax

Schema.optionalWith(schema: Schema<A, I, R>, { default: () => A })

Operation	Behavior
Decoding	Applies the default value if the input is missing or `undefined`
Encoding	Transforms the input `a: A` back to `i: I`

Example (Applying Default When Field Is Missing or undefined)

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalWith(Schema.NumberFromString, {
5
    default: () => 1, // Default value for quantity
6
  }),
7
})
8

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

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

17
// Decoding examples with default applied
18

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

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

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

28
// Object construction examples with default applied
29

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

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

Exposed Values

You can access the original schema type (before it was marked as optional) using the from property.

Example (Accessing the Original Schema)

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalWith(Schema.NumberFromString, {
5
    default: () => 1, // Default value for quantity
6
  }),
7
})
8

9
//      ┌─── typeof Schema.NumberFromString
10
//      ▼
11
const from = Product.fields.quantity.from

Default with Exactness

When you want the default value to be applied only if the field is completely missing (not when it’s undefined), you can use the exact option.

Syntax

Schema.optionalWith(schema: Schema<A, I, R>, {
  default: () => A,
  exact: true
})

Operation	Behavior
Decoding	Applies the default value only if the input is missing
Encoding	Transforms the input `a: A` back to `i: I`

Example (Applying Default Only When Field Is Missing)

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalWith(Schema.NumberFromString, {
5
    default: () => 1, // Default value for quantity
6
    exact: true, // Only apply default if quantity is not provided
7
  }),
8
})
9

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

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

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

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

24
console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
25
/*
26
throws:
27
ParseError: (Struct (Encoded side) <-> Struct (Type side))
28
└─ Encoded side transformation failure
29
   └─ Struct (Encoded side)
30
      └─ ["quantity"]
31
         └─ NumberFromString
32
            └─ Encoded side transformation failure
33
               └─ Expected string, actual undefined
34
*/

Default with Nullability

In cases where you want null values to trigger the default behavior, you can use the nullable option. This ensures that if a field is set to null, it will be replaced by the default value.

Syntax

Schema.optionalWith(schema: Schema<A, I, R>, {
  default: () => A,
  nullable: true
})

Operation	Behavior
Decoding	Applies the default value if the input is missing or `undefined` or `null`
Encoding	Transforms the input `a: A` back to `i: I`

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

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalWith(Schema.NumberFromString, {
5
    default: () => 1, // Default value for quantity
6
    nullable: true, // Apply default if quantity is null
7
  }),
8
})
9

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

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

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

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

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

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

Combining Exactness and Nullability

For a more strict approach, you can combine both exact and nullable options. This way, the default value is applied only when the field is null or missing, and not when it’s explicitly set to undefined.

Syntax

Schema.optionalWith(schema: Schema<A, I, R>, {
  default: () => A,
  exact: true,
  nullable: true
})

Operation	Behavior
Decoding	Applies the default value if the input is missing or `null`
Encoding	Transforms the input `a: A` back to `i: I`

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

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalWith(Schema.NumberFromString, {
5
    default: () => 1, // Default value for quantity
6
    exact: true, // Only apply default if quantity is not provided
7
    nullable: true, // Apply default if quantity is null
8
  }),
9
})
10

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

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

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

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

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

28
console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
29
/*
30
throws:
31
ParseError: (Struct (Encoded side) <-> Struct (Type side))
32
└─ Encoded side transformation failure
33
   └─ Struct (Encoded side)
34
      └─ ["quantity"]
35
         └─ NumberFromString
36
            └─ Encoded side transformation failure
37
               └─ Expected string, actual undefined
38
*/

Optional Fields as Options

When working with optional fields, you may want to handle them as Option types. 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

You can configure a schema to treat optional fields as Option types, where missing or undefined values are converted to Option.none() and existing values are wrapped in Option.some().

Syntax

optionalWith(schema: Schema<A, I, R>, { as: "Option" })

Decoding

Input	Output
`<missing value>`	transforms to `Option.none()`
`undefined`	transforms to `Option.none()`
`i: I`	transforms to `Option.some(a: A)`

Encoding

Input	Output
`Option.none()`	transforms to `<missing value>`
`Option.some(a: A)`	transforms back to `i: I`

Example (Handling Optional Field as Option)

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalWith(Schema.NumberFromString, { as: "Option" }),
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 } }

Exposed Values

You can access the original schema type (before it was marked as optional) using the from property.

Example (Accessing the Original Schema)

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalWith(Schema.NumberFromString, { as: "Option" }),
5
})
6

7
//      ┌─── typeof Schema.NumberFromString
8
//      ▼
9
const from = Product.fields.quantity.from

Optional with Exactness

The exact option ensures that the default behavior of the optional field applies only when the field is entirely missing, not when it is undefined.

Syntax

optionalWith(schema: Schema<A, I, R>, {
  as: "Option",
  exact: true
})

Decoding

Input	Output
`<missing value>`	transforms to `Option.none()`
`undefined`	`ParseError`
`i: I`	transforms to `Option.some(a: A)`

Encoding

Input	Output
`Option.none()`	transforms to `<missing value>`
`Option.some(a: A)`	transforms back to `i: I`

Example (Using Exactness with Optional Field as Option)

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalWith(Schema.NumberFromString, {
5
    as: "Option",
6
    exact: true,
7
  }),
8
})
9

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

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

18
console.log(Schema.decodeUnknownSync(Product)({}))
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 } }
23

24
console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
25
/*
26
throws:
27
ParseError: (Struct (Encoded side) <-> Struct (Type side))
28
└─ Encoded side transformation failure
29
   └─ Struct (Encoded side)
30
      └─ ["quantity"]
31
         └─ NumberFromString
32
            └─ Encoded side transformation failure
33
               └─ Expected string, actual undefined
34
*/

Exposed Values

You can access the original schema type (before it was marked as optional) using the from property.

Example (Accessing the Original Schema)

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalWith(Schema.NumberFromString, {
5
    as: "Option",
6
    exact: true,
7
  }),
8
})
9

10
//      ┌─── typeof Schema.NumberFromString
11
//      ▼
12
const from = Product.fields.quantity.from

Optional with Nullability

The nullable option extends the default behavior to treat null as equivalent to Option.none(), alongside missing or undefined values.

Syntax

optionalWith(schema: Schema<A, I, R>, {
  as: "Option",
  nullable: true
})

Decoding

Input	Output
`<missing value>`	transforms to `Option.none()`
`undefined`	transforms to `Option.none()`
`null`	transforms to `Option.none()`
`i: I`	transforms to `Option.some(a: A)`

Encoding

Input	Output
`Option.none()`	transforms to `<missing value>`
`Option.some(a: A)`	transforms back to `i: I`

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.optionalWith(Schema.NumberFromString, {
5
    as: "Option",
6
    nullable: true,
7
  }),
8
})
9

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

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

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

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

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

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

Exposed Values

You can access the original schema type (before it was marked as optional) using the from property.

Example (Accessing the Original Schema)

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalWith(Schema.NumberFromString, {
5
    as: "Option",
6
    nullable: true,
7
  }),
8
})
9

10
//      ┌─── typeof Schema.NumberFromString
11
//      ▼
12
const from = Product.fields.quantity.from

Combining Exactness and Nullability

When both exact and nullable options are used together, only null and missing fields are treated as Option.none(), while undefined is considered an invalid value.

Syntax

optionalWith(schema: Schema<A, I, R>, {
  as: "Option",
  exact: true,
  nullable: true
})

Decoding

Input	Output
`<missing value>`	transforms to `Option.none()`
`undefined`	`ParseError`
`null`	transforms to `Option.none()`
`i: I`	transforms to `Option.some(a: A)`

Encoding

Input	Output
`Option.none()`	transforms to `<missing value>`
`Option.some(a: A)`	transforms back to `i: I`

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

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalWith(Schema.NumberFromString, {
5
    as: "Option",
6
    exact: true,
7
    nullable: true,
8
  }),
9
})
10

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

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

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

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

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

28
console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
29
/*
30
throws:
31
ParseError: (Struct (Encoded side) <-> Struct (Type side))
32
└─ Encoded side transformation failure
33
   └─ Struct (Encoded side)
34
      └─ ["quantity"]
35
         └─ NumberFromString
36
            └─ Encoded side transformation failure
37
               └─ Expected string, actual undefined
38
*/

Exposed Values

You can access the original schema type (before it was marked as optional) using the from property.

Example (Accessing the Original Schema)

1
import { Schema } from "effect"
2

3
const Product = Schema.Struct({
4
  quantity: Schema.optionalWith(Schema.NumberFromString, {
5
    as: "Option",
6
    exact: true,
7
    nullable: true,
8
  }),
9
})
10

11
//      ┌─── typeof Schema.NumberFromString
12
//      ▼
13
const from = Product.fields.quantity.from

Optional Fields Primitives

optionalToOptional

The Schema.optionalToOptional API allows you to manage transformations from an optional field in the input to an optional field in the output. This can be useful for controlling both the output type and whether a field is present or absent based on specific criteria.

One common use case for optionalToOptional is handling fields where a specific input value, such as an empty string, should be treated as an absent field in the output.

Syntax

const optionalToOptional = <FA, FI, FR, TA, TI, TR>(
  from: Schema<FA, FI, FR>,
  to: Schema<TA, TI, TR>,
  options: {
    readonly decode: (o: Option.Option<FA>) => Option.Option<TI>,
    readonly encode: (o: Option.Option<TI>) => Option.Option<FA>
  }
): PropertySignature<"?:", TA, never, "?:", FI, false, FR | TR>

In this function:

The from parameter specifies the input schema, and to specifies the output schema.
The decode and encode functions define how the field should be interpreted on both sides:
- Option.none() as an input argument indicates a missing field in the input.
- Returning Option.none() from either function will omit the field in 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 } from "effect"
2

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

33
// Decoding examples
34

35
const decode = Schema.decodeUnknownSync(schema)
36

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

44
// Encoding examples
45

46
const encode = Schema.encodeSync(schema)
47

48
console.log(encode({}))
49
// Output: {}
50
console.log(encode({ nonEmpty: "" }))
51
// Output: { nonEmpty: '' }
52
console.log(encode({ nonEmpty: "a non-empty string" }))
53
// 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 } from "effect"
2

3
const schema = Schema.Struct({
4
  nonEmpty: Schema.optionalToOptional(Schema.String, Schema.String, {
5
    decode: Option.filter((s) => s !== ""),
6
    encode: identity,
7
  }),
8
})

optionalToRequired

The Schema.optionalToRequired API lets you transform an optional field into a required one, with custom logic to handle cases when the field is missing in the input.

Syntax

const optionalToRequired = <FA, FI, FR, TA, TI, TR>(
  from: Schema<FA, FI, FR>,
  to: Schema<TA, TI, TR>,
  options: {
    readonly decode: (o: Option.Option<FA>) => TI,
    readonly encode: (ti: TI) => Option.Option<FA>
  }
): PropertySignature<":", TA, never, "?:", FI, false, FR | TR>

In this function:

from specifies the input schema, while to specifies the output schema.
The decode and encode functions define the transformation behavior:
- Passing Option.none() to decode means the field is absent in the input. The function can then return a default value for the output.
- Returning Option.none() in encode will omit the field in the output.

Example (Setting null as Default for Missing Field)

This example demonstrates how to use optionalToRequired to provide a null default value when the nullable field is missing in the input. During encoding, fields with a value of null are omitted from the output.

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

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

36
// Decoding examples
37

38
const decode = Schema.decodeUnknownSync(schema)
39

40
console.log(decode({}))
41
// Output: { nullable: null }
42
console.log(decode({ nullable: "a value" }))
43
// Output: { nullable: 'a value' }
44

45
// Encoding examples
46

47
const encode = Schema.encodeSync(schema)
48

49
console.log(encode({ nullable: "a value" }))
50
// Output: { nullable: 'a value' }
51
console.log(encode({ nullable: null }))
52
// 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 } from "effect"
2

3
const schema = Schema.Struct({
4
  nullable: Schema.optionalToRequired(Schema.String, Schema.NullOr(Schema.String), {
5
    decode: Option.getOrElse(() => null),
6
    encode: Option.liftPredicate((value) => value !== null),
7
  }),
8
})

requiredToOptional

The requiredToOptional API allows you to transform a required field into an optional one, applying custom logic to determine when the field can be omitted.

Syntax

const requiredToOptional = <FA, FI, FR, TA, TI, TR>(
  from: Schema<FA, FI, FR>,
  to: Schema<TA, TI, TR>,
  options: {
    readonly decode: (fa: FA) => Option.Option<TI>
    readonly encode: (o: Option.Option<TI>) => FA
  }
): PropertySignature<"?:", TA, never, ":", FI, false, FR | TR>

With decode and encode functions, you control the presence or absence of the field:

Option.none() as an argument in decode means the field is missing in the input.
Option.none() as a return value from encode means the field will be omitted in the output.

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 } from "effect"
2

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

30
// Decoding examples
31

32
const decode = Schema.decodeUnknownSync(schema)
33

34
console.log(decode({ name: "John" }))
35
// Output: { name: 'John' }
36
console.log(decode({ name: "" }))
37
// Output: {}
38

39
// Encoding examples
40

41
const encode = Schema.encodeSync(schema)
42

43
console.log(encode({ name: "John" }))
44
// Output: { name: 'John' }
45
console.log(encode({}))
46
// 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 } from "effect"
2

3
const schema = Schema.Struct({
4
  name: Schema.requiredToOptional(Schema.String, Schema.String, {
5
    decode: Option.liftPredicate((s) => s !== ""),
6
    encode: Option.getOrElse(() => ""),
7
  }),
8
})

Extending Schemas

Schemas in effect can be extended in multiple ways, allowing you to combine or enhance existing types with additional fields or functionality. One common method is to use the fields property available in Struct schemas. This property provides a convenient way to add fields or merge fields from different structs while retaining the original Struct type. This approach also makes it easier to access and modify fields.

For more complex cases, such as extending a struct with a union, you may want to use the Schema.extend function, which offers flexibility in scenarios where direct field spreading may not be sufficient.

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.Struct(
9
  Original.fields,
10
  // Adding an index signature
11
  Schema.Record({ key: Schema.String, value: 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 extend function

The Schema.extend function provides a structured method to expand schemas, especially useful when direct field spreading isn’t sufficient—such as when you need to extend a struct with a union of other structs.

Supported extensions include:

Schema.String with another Schema.String refinement or a string literal
Schema.Number with another Schema.Number refinement or a number literal
Schema.Boolean with another Schema.Boolean refinement or a boolean literal
A struct with another struct where overlapping fields support extension
A struct with in index signature
A struct with a union of supported schemas
A refinement of a struct with a supported schema
A suspend of a struct with a supported schema
A transformation between structs where the “from” and “to” sides have no overlapping fields with the target struct

Example (Extending a Struct with a Union of Structs)

1
import { Schema } 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 = Schema.extend(Struct, UnionOfStructs)
13

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

Example (Attempting to Extend Structs with Conflicting Fields)

This example demonstrates an attempt to extend a struct with another struct that contains overlapping field names, resulting in an error due to conflicting types.

1
import { Schema } from "effect"
2

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

7
const OverlappingUnion = Schema.Union(
8
  Schema.Struct({ a: Schema.Number }), // conflicting type for key "a"
9
  Schema.Struct({ d: Schema.String }),
10
)
11

12
const Extended = Schema.extend(Struct, OverlappingUnion)
13
/*
14
throws:
15
Error: Unsupported schema or overlapping types
16
at path: ["a"]
17
details: cannot extend string with number
18
*/

Example (Extending a Refinement with Another Refinement)

In this example, we extend two refinements, Integer and Positive, creating a schema that enforces both integer and positivity constraints.

1
import { Schema } from "effect"
2

3
const Integer = Schema.Int.pipe(Schema.brand("Int"))
4
const Positive = Schema.Positive.pipe(Schema.brand("Positive"))
5

6
//      ┌─── Schema<number & Brand<"Positive"> & Brand<"Int">, number, never>
7
//      ▼
8
const PositiveInteger = Schema.asSchema(Schema.extend(Positive, Integer))
9

10
Schema.decodeUnknownSync(PositiveInteger)(-1)
11
/*
12
throws
13
ParseError: positive & Brand<"Positive"> & int & Brand<"Int">
14
└─ From side refinement failure
15
   └─ positive & Brand<"Positive">
16
      └─ Predicate refinement failure
17
         └─ Expected a positive number, actual -1
18
*/
19

20
Schema.decodeUnknownSync(PositiveInteger)(1.1)
21
/*
22
throws
23
ParseError: positive & Brand<"Positive"> & int & Brand<"Int">
24
└─ Predicate refinement failure
25
   └─ Expected an integer, actual 1.1
26
*/

Renaming Properties

Renaming a Property During Definition

To rename a property directly during schema creation, you can utilize the Schema.fromKey function.

Example (Renaming a Required Property)

1
import { Schema } from "effect"
2

3
const schema = Schema.Struct({
4
  a: Schema.propertySignature(Schema.String).pipe(Schema.fromKey("c")),
5
  b: Schema.Number,
6
})
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).pipe(Schema.fromKey("c")),
5
  b: Schema.Number,
6
})
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 }

Using Schema.optional automatically returns a PropertySignature, making it unnecessary to explicitly use Schema.propertySignature as required for renaming required fields in the previous example.

Renaming Properties of an Existing Schema

For existing schemas, the Schema.rename API offers a way to systematically change property names across a schema, even within complex structures like unions, though in case of structs you lose the original field types.

Example (Renaming Properties in a Struct Schema)

1
import { Schema } from "effect"
2

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

8
// Renaming the "c" property to "a"
9
//
10
//
11
//      ┌─── SchemaClass<{
12
//      |      readonly a: string;
13
//      |      readonly b: number;
14
//      |    }>
15
//      ▼
16
const Renamed = Schema.rename(Original, { c: "a" })
17

18
console.log(Schema.decodeUnknownSync(Renamed)({ c: "c", b: 1 }))
19
// 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
    c: Schema.String,
6
    b: Schema.Number,
7
  }),
8
  Schema.Struct({
9
    c: Schema.String,
10
    d: Schema.Boolean,
11
  }),
12
)
13

14
// Renaming the "c" property to "a" for all members
15
//
16
//      ┌─── SchemaClass<{
17
//      |      readonly a: string;
18
//      |      readonly b: number;
19
//      |    } | {
20
//      |      readonly a: string;
21
//      |      readonly d: number;
22
//      |    }>
23
//      ▼
24
const Renamed = Schema.rename(Original, { c: "a" })
25

26
console.log(Schema.decodeUnknownSync(Renamed)({ c: "c", b: 1 }))
27
// Output: { a: "c", b: 1 }
28

29
console.log(Schema.decodeUnknownSync(Renamed)({ c: "c", d: false }))
30
// 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(Schema.suspend((): Schema.Schema<Category> => Category)),
11
})

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.Schema<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.Number,
19
    Schema.suspend((): Schema.Schema<Operation> => Operation),
20
  ),
21
})
22

23
const Operation = Schema.Struct({
24
  type: Schema.Literal("operation"),
25
  operator: Schema.Literal("+", "-"),
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: suppose we want to add an id field to the Category schema, where the schema for id is NumberFromString. It’s important to note that NumberFromString is a schema that transforms a string into a number, so the Type and Encoded types of NumberFromString differ, being number and string respectively. 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.NumberFromString,
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.Schema<Category> => Category),
17
  ),
18
})

This error occurs because the explicit annotation Schema.Schema<Category> is no longer sufficient and needs to be adjusted by explicitly adding the Encoded type:

1
import { Schema } from "effect"
2

3
const fields = {
4
  id: Schema.NumberFromString,
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.Schema<Category, CategoryEncoded> => Category),
20
  ),
21
})