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)

import { Schema } from "@effect/schema"

// Declare a schema for the File type using a type guard
const FileFromSelf = Schema.declare(
  (input: unknown): input is File => input instanceof File
)

const decode = Schema.decodeUnknownSync(FileFromSelf)

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

// Decoding an invalid input
decode(null)
/*
throws
ParseError: Expected <declaration schema>, actual null
*/

Adding Annotations

Annotations like identifier and description are useful for improving error messages and making schemas self-documenting.

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.

A “title” should be concise, while a “description” provides a more detailed explanation of the purpose of the data described by the schema.

Example (Adding Annotations)

import { Schema } from "@effect/schema"

// Declare a schema for the File type with additional annotations
const FileFromSelf = Schema.declare(
  (input: unknown): input is File => input instanceof File,
  {
    // A unique identifier for the schema
    identifier: "FileFromSelf",
    // Detailed description of the schema
    description: "The `File` type in JavaScript"
  }
)

const decode = Schema.decodeUnknownSync(FileFromSelf)

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

// Decoding an invalid input
decode(null)
/*
throws
ParseError: Expected FileFromSelf, actual null
*/

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

import { ParseResult, Schema } from "@effect/schema"

export const MyReadonlySet = <A, I, R>(
  // Schema for the elements of the Set
  item: Schema.Schema<A, I, R>
): Schema.Schema<ReadonlySet<A>, ReadonlySet<I>, R> =>
  Schema.declare(
    // Store the schema for the Set's elements
    [item],
    {
      // Decoding function
      decode: (item) => (input, parseOptions, ast) => {
        if (input instanceof Set) {
          // Decode each element in the Set
          const elements = ParseResult.decodeUnknown(Schema.Array(item))(
            Array.from(input.values()),
            parseOptions
          )
          // Return a ReadonlySet containing the decoded elements
          return ParseResult.map(
            elements,
            (as): ReadonlySet<A> => new Set(as)
          )
        }
        // Handle invalid input
        return ParseResult.fail(new ParseResult.Type(ast, input))
      },
      // Encoding function
      encode: (item) => (input, parseOptions, ast) => {
        if (input instanceof Set) {
          // Encode each element in the Set
          const elements = ParseResult.encodeUnknown(Schema.Array(item))(
            Array.from(input.values()),
            parseOptions
          )
          // Return a ReadonlySet containing the encoded elements
          return ParseResult.map(
            elements,
            (is): ReadonlySet<I> => new Set(is)
          )
        }
        // Handle invalid input
        return ParseResult.fail(new ParseResult.Type(ast, input))
      }
    },
    {
      description: `ReadonlySet<${Schema.format(item)}>`
    }
  )

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

const decode = Schema.decodeUnknownSync(setOfNumbers)

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

// Decode an invalid input
decode(null)
/*
throws
ParseError: Expected ReadonlySet<NumberFromString>, actual null
*/

// Decode a Set with an invalid element
decode(new Set(["1", null, "3"]))
/*
throws
ParseError: ReadonlyArray<NumberFromString>
└─ [1]
   └─ NumberFromString
      └─ Encoded side transformation failure
         └─ Expected string, actual null
*/

Decoding/Encoding Limitations

The decoding and encoding functions cannot rely on context (the Requirements type parameter) and cannot handle asynchronous effects. This means that only synchronous operations are supported within these functions.

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 (Missing Annotations)

import { Arbitrary, Schema } from "@effect/schema"

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

// Try creating an Arbitrary instance for the schema
const arb = Arbitrary.make(FileFromSelf)
/*
throws:
Error: Missing annotation
details: Generating an Arbitrary for this schema requires an "arbitrary" annotation
schema (Declaration): FileFromSelf
*/

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

import { Arbitrary, FastCheck, Pretty, Schema } from "@effect/schema"

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

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

// Generate sample files using the Arbitrary instance
const files = FastCheck.sample(arb, 2)
console.log(files)
/*
Example Output:
[
  File { size: 5, type: '', name: 'C', lastModified: 1706435571176 },
  File { size: 1, type: '', name: '98Ggmc', lastModified: 1706435571176 }
]
*/

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)

type UserId = string
type Username = string

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

const myUsername: Username = "gcanti"

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)

import { Brand } from "effect"

type UserId = string & Brand.Brand<"UserId">
type Username = string

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

const myUsername: Username = "gcanti"

// @ts-expect-error
getUser(myUsername)
/*
Argument of type 'string' is not assignable to parameter of type 'UserId'.
  Type 'string' is not assignable to type 'Brand<"UserId">'.ts(2345)
*/

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)

import { Schema } from "@effect/schema"

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

// string & Brand<"UserId">
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)

import { Schema } from "@effect/schema"

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

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

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

import { Schema } from "@effect/schema"
import { Brand } from "effect"

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

const UserId = Brand.nominal<UserId>()

// Define a schema for the branded type
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.

import { Schema } from "@effect/schema"

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

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

Let’s start with the simple definition of a property signature that can be used to add annotations:

import { Schema } from "@effect/schema"

const Person = Schema.Struct({
  name: Schema.String,
  age: Schema.propertySignature(Schema.NumberFromString).annotations({
    title: "Age"
  })
})

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
FormToken	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
FormToken	":" 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)

import { Schema } from "@effect/schema"

const Person = Schema.Struct({
  name: Schema.String,
  age: Schema.propertySignature(Schema.NumberFromString).pipe(
    Schema.fromKey("AGE") // Maps from "AGE" to "age"
  )
})

console.log(Schema.decodeUnknownSync(Person)({ name: "name", AGE: "18" }))
// 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

Schema.optional(schema: Schema<A, I, R>) defines a basic optional property.

Decoding

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

Encoding

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

Example

import { Schema } from "@effect/schema"

const schema = Schema.Struct({
  a: Schema.optional(Schema.NumberFromString)
})

// { readonly a?: number | undefined; }
type Type = typeof schema.Type

// { readonly a?: string | undefined; }
type Encoded = typeof schema.Encoded

console.log(Schema.decodeUnknownSync(schema)({ a: "1" }))
// Output: { a: 1 }
console.log(Schema.decodeUnknownSync(schema)({}))
// Output: {}
console.log(Schema.decodeUnknownSync(schema)({ a: undefined }))
// Output: { a: undefined }
console.log(Schema.encodeSync(schema)({ a: 1 }))
// Output: { a: "1" }
console.log(Schema.encodeSync(schema)({}))
// Output: {}
console.log(Schema.encodeSync(schema)({ a: undefined }))
// Output: { a: undefined }

Optional with Nullability

Schema.optionalWith(schema: Schema<A, I, R>, { nullable: true }) allows handling of null values as equivalent to missing values.

Decoding

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

Encoding

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

Example

import { Schema } from "@effect/schema"

const schema = Schema.Struct({
  a: Schema.optionalWith(Schema.NumberFromString, { nullable: true })
})

// { readonly a?: number | undefined; }
type Type = typeof schema.Type

// { readonly a?: string | null | undefined; }
type Encoded = typeof schema.Encoded

console.log(Schema.decodeUnknownSync(schema)({ a: "1" }))
// Output: { a: 1 }
console.log(Schema.decodeUnknownSync(schema)({}))
// Output: {}
console.log(Schema.decodeUnknownSync(schema)({ a: undefined }))
// Output: { a: undefined }
console.log(Schema.decodeUnknownSync(schema)({ a: null }))
// Output: {}
console.log(Schema.encodeSync(schema)({ a: 1 }))
// Output: { a: "1" }
console.log(Schema.encodeSync(schema)({}))
// Output: {}
console.log(Schema.encodeSync(schema)({ a: undefined }))
// Output: { a: undefined }

Optional with Exactness

Schema.optionalWith(schema: Schema<A, I, R>, { exact: true }) ensures that only the exact types specified are handled, excluding undefined.

Decoding

• <missing value> remains <missing value>
• Input i: I transforms to a: A

Encoding

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

Example

import { Schema } from "@effect/schema"

const schema = Schema.Struct({
  a: Schema.optionalWith(Schema.NumberFromString, { exact: true })
})

// { readonly a?: number; }
type Type = typeof schema.Type

// { readonly a?: string; }
type Encoded = typeof schema.Encoded

console.log(Schema.decodeUnknownSync(schema)({ a: "1" }))
// Output: { a: 1 }
console.log(Schema.decodeUnknownSync(schema)({}))
// Output: {}
console.log(Schema.decodeUnknownSync(schema)({ a: undefined }))
/*
throws:
ParseError: { readonly a?: NumberFromString }
└─ ["a"]
   └─ NumberFromString
      └─ Encoded side transformation failure
         └─ Expected string, actual undefined
*/
console.log(Schema.encodeSync(schema)({ a: 1 }))
// Output: { a: "1" }
console.log(Schema.encodeSync(schema)({}))
// Output: {}

Combining Nullability and Exactness

Schema.optionalWith(schema: Schema<A, I, R>, { exact: true, nullable: true }) combines handling for exact types and null values.

Decoding

• <missing value> remains <missing value>
• null transforms to <missing value>
• Input i: I transforms to a: A

Encoding

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

Example

import { Schema } from "@effect/schema"

const schema = Schema.Struct({
  a: Schema.optionalWith(Schema.NumberFromString, {
    exact: true,
    nullable: true
  })
})

// { readonly a?: number; }
type Type = typeof schema.Type

// { readonly a?: string | null; }
type Encoded = typeof schema.Encoded

console.log(Schema.decodeUnknownSync(schema)({ a: "1" }))
// Output: { a: 1 }
console.log(Schema.decodeUnknownSync(schema)({}))
// Output: {}
console.log(Schema.decodeUnknownSync(schema)({ a: undefined }))
/*
throws:
ParseError: (Struct (Encoded side) <-> Struct (Type side))
└─ Encoded side transformation failure
   └─ Struct (Encoded side)
      └─ ["a"]
         └─ NumberFromString | null
            ├─ NumberFromString
            │  └─ Encoded side transformation failure
            │     └─ Expected string, actual undefined
            └─ Expected null, actual undefined
*/
console.log(Schema.decodeUnknownSync(schema)({ a: null }))
// Output: {}
console.log(Schema.encodeSync(schema)({ a: 1 }))
// Output: { a: "1" }
console.log(Schema.encodeSync(schema)({}))
// Output: {}

Representing Optional Fields with never Type

When defining types in TypeScript that include optional fields with the type never, such as:

type MyType = {
  readonly foo?: never
}

the approach varies based on the exactOptionalPropertyTypes configuration in your tsconfig.json

TypeScript Configuration: 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.

import { Schema } from "@effect/schema"

const schema = Schema.Struct({
  a: Schema.optional(Schema.Never)
})

// { readonly a?: undefined; }
type Type = typeof schema.Type

// { readonly a?: undefined; }
type Encoded = typeof schema.Encoded

TypeScript Configuration: exactOptionalPropertyTypes = true

When this feature is turned on, the Schema.optionalWith function is recommended. It ensures stricter enforcement of the field’s absence.

import { Schema } from "@effect/schema"

const schema = Schema.Struct({
  foo: Schema.optionalWith(Schema.Never, { exact: true })
})

// { readonly a?: never; }
type Type = typeof schema.Type

// { readonly a?: never; }
type Encoded = typeof schema.Encoded

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 most straightforward use case. If the input is missing or undefined, the default value will be used.

Syntax

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

Decoding: Translates missing or undefined inputs to a default value

Encoding: Input a: A transforms back to i: I

Example

import { Schema } from "@effect/schema"

const Product = Schema.Struct({
  name: Schema.String,
  price: Schema.NumberFromString,
  quantity: Schema.optionalWith(Schema.NumberFromString, {
    default: () => 1 // Default value for quantity
  })
})

// Applying defaults in the decoding phase

console.log(
  Schema.decodeUnknownSync(Product)({ name: "Laptop", price: "999" })
)
// Output: { name: 'Laptop', price: 999, quantity: 1 }

console.log(
  Schema.decodeUnknownSync(Product)({
    name: "Laptop",
    price: "999",
    quantity: "2"
  })
)
// Output: { name: 'Laptop', price: 999, quantity: 2 }

// Applying defaults in the constructor

console.log(Product.make({ name: "Laptop", price: 999 }))
// Output: { name: 'Laptop', price: 999, quantity: 1 }

console.log(Product.make({ name: "Laptop", price: 999, quantity: 2 }))
// Output: { name: 'Laptop', price: 999, quantity: 2 }

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

Decoding: Applies the default value only if the input is missing

Encoding: Input a: A transforms back to i: I

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

Decoding: Treats null, undefined, or missing inputs as defaults

Encoding: Input a: A transforms back to i: I

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

Decoding: Defaults are applied when values are null or missing

Encoding: Input a: A transforms back to i: I

Optional Fields as Options

In many cases you may want to transform an optional field into an Option type. This approach allows you to explicitly manage whether a field is present or not, rather than relying on undefined or null.

Basic Optional with Option Type

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

Syntax

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

Decoding

• Missing values or undefined are converted to Option.none()
• Provided values (i: I) are converted to Option.some(a: A)

Encoding

• Option.none() results in the value being omitted
• Option.some(a: A) is converted back to the original input (i: I)

Example

import { Schema } from "@effect/schema"

const Product = Schema.Struct({
  name: Schema.String,
  price: Schema.NumberFromString,
  quantity: Schema.optionalWith(Schema.NumberFromString, { as: "Option" })
})

console.log(
  Schema.decodeUnknownSync(Product)({ name: "Laptop", price: "999" })
)
// Output: { name: 'Laptop', price: 999, quantity: none() }

console.log(
  Schema.decodeUnknownSync(Product)({
    name: "Laptop",
    price: "999",
    quantity: "2"
  })
)
// Output: { name: 'Laptop', price: 999, quantity: some(2) }

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

• Only truly missing values are converted to Option.none()
• Provided values (i: I) are converted to Option.some(a)

Encoding

• Option.none() results in the value being omitted
• Option.some(a: A) is converted back to the original input (i: I)

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

• Treats missing, undefined, and null values all as Option.none()
• Provided values (i: I) are converted to Option.some(a: A)

Encoding

• Option.none() results in the value being omitted
• Option.some(a: A) is converted back to the original input (i: I)

Combining Exactness and Nullability

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

Syntax

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

Decoding

• Missing or null values lead to Option.none()
• Provided values (i: I) are converted to Option.some(a: A)

Encoding

• Option.none() results in the value being omitted
• Option.some(a: A) is converted back to the original input (i: I)

Optional Fields Primitives

optionalToOptional

The Schema.optionalToOptional API is used to manage the transformation from an optional field to another optional field. With this, we can control both the output type and the presence or absence of the field.

For example a common use case is to equate a specific value in the source field with the absence of value in the destination field.

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>

You can transform the type by specifying a schema for to, which can be different from the schema of from. Additionally, you can control the presence or absence of the field using decode and encode, with the following meanings:

• Option.none() as an argument means the value is missing in the input
• Option.none() as a return value means the value will be missing in the output

Example

Suppose we have an optional field of type string, and we want to exclude empty strings from the output. In other words, if the input contains an empty string, we want the field to be absent in the output.

import { Schema } from "@effect/schema"
import { identity, Option } from "effect"

const schema = Schema.Struct({
  a: Schema.optionalToOptional(Schema.String, Schema.String, {
    decode: (input) => {
      if (Option.isNone(input)) {
        // If the field is absent in the input, returning `Option.none()`
        // will make it absent in the output too
        return Option.none()
      }
      const value = input.value
      if (value === "") {
        // If the field is present in the input but is an empty string,
        // returning `Option.none()` will make it absent in the output
        return Option.none()
      }
      // If the field is present in the input and is not an empty string,
      // returning `Option.some` will make it present in the output
      return Option.some(value)
    },
    // Here in the encoding part, we can decide to handle things
    // in the same way as in the decoding phase or handle them differently.
    // For example, we can leave everything unchanged
    // and use the identity function
    encode: identity
  })
})

const decode = Schema.decodeUnknownSync(schema)

console.log(decode({}))
// Output: {}
console.log(decode({ a: "" }))
// Output: {}
console.log(decode({ a: "a non-empty string" }))
// Output: { a: 'a non-empty string' }

const encode = Schema.encodeSync(schema)

console.log(encode({}))
// Output: {}
console.log(encode({ a: "" }))
// Output: { a: '' }
console.log(encode({ a: "foo" }))
// Output: { a: 'foo' }

optionalToRequired

The Schema.optionalToRequired API allows us to transform an optional field into a required one, applying custom logic if the field is absent 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>

You can control the presence or absence of the field using decode and encode, with the following meanings:

• Option.none() as an argument means the value is missing in the input
• Option.none() as a return value means the value will be missing in the output

Example

For instance, a common use case is to assign a default value to the field in the output if it’s missing in the input.

import { Schema } from "@effect/schema"
import { Option } from "effect"

const schema = Schema.Struct({
  a: Schema.optionalToRequired(Schema.String, Schema.String, {
    decode: (input) => {
      if (Option.isNone(input)) {
        // If the field is absent in the input,
        // we can return the default value for the field in the output
        return "default value"
      }
      // If the field is present in the input,
      // return its value as it is in the output
      return input.value
    },
    // During encoding, we can choose to handle things differently,
    // or simply return the same value present in the input for the output
    encode: (a) => Option.some(a)
  })
})

const decode = Schema.decodeUnknownSync(schema)

console.log(decode({}))
// Output: { a: 'default value' }
console.log(decode({ a: "foo" }))
// Output: { a: 'foo' }

const encode = Schema.encodeSync(schema)

console.log(encode({ a: "foo" }))
// Output: { a: 'foo' }

requiredToOptional

This API allows developers to specify how a field that is normally required can be treated as optional based on custom logic.

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>

You can control the presence or absence of the field using decode and encode, with the following meanings:

• Option.none() as an argument means the value is missing in the input
• Option.none() as a return value means the value will be missing in the output

Example

Let’s look at a practical example where a field name that is typically required can be considered optional if it’s an empty string during decoding, and ensure there is always a value during encoding by providing a default.

import { Schema } from "@effect/schema"
import { Option } from "effect"

const schema = Schema.Struct({
  name: Schema.requiredToOptional(Schema.String, Schema.String, {
    // empty string is considered as absent
    decode: Option.liftPredicate((s) => s !== ""),
    encode: Option.getOrElse(() => "")
  })
})

const decode = Schema.decodeUnknownSync(schema)

console.log(decode({ name: "John" }))
// Output: { name: 'John' }
console.log(decode({ name: "" }))
// Output: {}

const encode = Schema.encodeSync(schema)

console.log(encode({ name: "John" }))
// Output: { name: 'John' }
console.log(encode({}))
// Output: { name: '' }

Extending Schemas

Spreading Struct fields

Structs expose their fields through a fields property. This feature can be utilized to extend an existing struct with additional fields or to merge fields from another struct.

Example (Adding Fields)

import { Schema } from "@effect/schema"

const Struct1 = Schema.Struct({
  a: Schema.String,
  b: Schema.String
})

const Extended = Schema.Struct({
  ...Struct1.fields,
  // other fields
  c: Schema.String,
  d: Schema.String
})

Example (Integrating Additional Index Signatures)

import { Schema } from "@effect/schema"

const Struct = Schema.Struct({
  a: Schema.String,
  b: Schema.String
})

const Extended = Schema.Struct(
  Struct.fields,
  Schema.Record({ key: Schema.String, value: Schema.String })
)

Example (Merging Fields from Two Structs)

import { Schema } from "@effect/schema"

const Struct1 = Schema.Struct({
  a: Schema.String,
  b: Schema.String
})

const Struct2 = Schema.Struct({
  c: Schema.String,
  d: Schema.String
})

const Extended = Schema.Struct({
  ...Struct1.fields,
  ...Struct2.fields
})

The extend function

The Schema.extend function offers a structured way to extend schemas, particularly useful when direct field spreading is insufficient—for instance, when you need to extend a struct with a union of structs.

Extension Support Limitations

Note that not all extensions are supported, and their support depends on the nature of the involved schemas.

Possible 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

Example (Extending a Struct with a Union of Structs)

import { Schema } from "@effect/schema"

const Struct = Schema.Struct({
  a: Schema.String
})

const UnionOfStructs = Schema.Union(
  Schema.Struct({ b: Schema.String }),
  Schema.Struct({ c: Schema.String })
)

const Extended = Schema.extend(Struct, UnionOfStructs)

This example shows an attempt to extend a struct with another struct where field names overlap, leading to an error:

import { Schema } from "@effect/schema"

const Struct = Schema.Struct({
  a: Schema.String
})

const OverlappingUnion = Schema.Union(
  Schema.Struct({ a: Schema.Number }), // duplicate key
  Schema.Struct({ d: Schema.String })
)

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

Example (Extending a refinement of Schema.String with another refinement)

import { Schema } from "@effect/schema"

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

// Schema.Schema<number & Brand<"Positive"> & Brand<"Int">, number, never>
const PositiveInteger = Schema.asSchema(Schema.extend(Positive, Integer))

Schema.decodeUnknownSync(PositiveInteger)(-1)
/*
throws
ParseError: Int & Brand<"Int">
└─ From side refinement failure
  └─ Positive & Brand<"Positive">
      └─ Predicate refinement failure
        └─ Expected Positive & Brand<"Positive">, actual -1
*/

Schema.decodeUnknownSync(PositiveInteger)(1.1)
/*
throws
ParseError: Int & Brand<"Int">
└─ Predicate refinement failure
  └─ Expected Int & Brand<"Int">, actual 1.1
*/

Renaming Properties

Renaming a Property During Definition

To rename a property directly during schema creation, you can utilize the Schema.fromKey function. This function is particularly useful when you want to map properties from the input object to different names in the resulting schema object.

Example (Renaming a Required Property)

import { Schema } from "@effect/schema"

const schema = Schema.Struct({
  a: Schema.propertySignature(Schema.String).pipe(Schema.fromKey("c")),
  b: Schema.Number
})

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

Example (Renaming an Optional Property)

import { Schema } from "@effect/schema"

const schema = Schema.Struct({
  a: Schema.optional(Schema.String).pipe(Schema.fromKey("c")),
  b: Schema.Number
})

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

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

Note that Schema.optional returns a PropertySignature, which simplifies the process by eliminating the need for explicit Schema.propertySignature usage as required in the previous example.

Renaming Properties of an Existing Schema

For existing schemas, the rename API offers a way to systematically change property names across a schema, even within complex structures like unions.

Example (Renaming Properties in a Struct Schema)

import { Schema } from "@effect/schema"

// Original Schema
const originalSchema = Schema.Struct({
  c: Schema.String,
  b: Schema.Number
})

// Renaming the "c" property to "a"
const renamedSchema = Schema.rename(originalSchema, { c: "a" })

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

Example (Renaming Properties in Union Schemas)

import { Schema } from "@effect/schema"

const originalSchema = Schema.Union(
  Schema.Struct({
    c: Schema.String,
    b: Schema.Number
  }),
  Schema.Struct({
    c: Schema.String,
    d: Schema.Boolean
  })
)

// Renaming the "c" property to "a" for all members
const renamedSchema = Schema.rename(originalSchema, { c: "a" })

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

console.log(Schema.decodeUnknownSync(renamedSchema)({ c: "c", d: false }))
// Output: { d: false, a: 'c' }

Recursive Schemas

The Schema.suspend function is useful when you need to define a schema that depends on itself, like in the case of recursive data structures.

Example

In this example, the Category schema depends on itself because it has a field subcategories that is an array of Category objects.

import { Schema } from "@effect/schema"

interface Category {
  readonly name: string
  readonly subcategories: ReadonlyArray<Category>
}

const Category = Schema.Struct({
  name: Schema.String,
  subcategories: Schema.Array(
    Schema.suspend((): Schema.Schema<Category> => Category)
  )
})

Correct Inference

It is necessary to define the Category type and add an explicit type annotation because otherwise TypeScript would struggle to infer types correctly. Without this annotation, you might encounter the error message:

import { Schema } from "@effect/schema"

// @ts-expect-error
const Category = Schema.Struct({
  name: Schema.String,
  // @ts-expect-error
  subcategories: Schema.Array(Schema.suspend(() => Category))
})
/*
'Category' implicitly has type 'any' because it does not have a type annotation and is
referenced directly or indirectly in its own initializer.ts(7022)
*/

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.

import { Schema } from "@effect/schema"

const fields = {
  name: Schema.String
  // ...possibly other fields
}

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

const Category = Schema.Struct({
  ...fields, // Include the fields
  subcategories: Schema.Array(
    // Define `subcategories` using recursion
    Schema.suspend((): Schema.Schema<Category> => Category)
  )
})

Mutually Recursive Schemas

Here’s an example of two mutually recursive schemas, Expression and Operation, that represent a simple arithmetic expression tree.

import { Schema } from "@effect/schema"

interface Expression {
  readonly type: "expression"
  readonly value: number | Operation
}

interface Operation {
  readonly type: "operation"
  readonly operator: "+" | "-"
  readonly left: Expression
  readonly right: Expression
}

const Expression = Schema.Struct({
  type: Schema.Literal("expression"),
  value: Schema.Union(
    Schema.Number,
    Schema.suspend((): Schema.Schema<Operation> => Operation)
  )
})

const Operation = Schema.Struct({
  type: Schema.Literal("operation"),
  operator: Schema.Literal("+", "-"),
  left: Expression,
  right: Expression
})

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

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:

import { Schema } from "@effect/schema"

const fields = {
  id: Schema.NumberFromString,
  name: Schema.String
}

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

const Category = Schema.Struct({
  ...fields,
  subcategories: Schema.Array(
    // @ts-expect-error
    Schema.suspend((): Schema.Schema<Category> => Category)
  )
})
/*
Type 'Struct<{ subcategories: Array$<suspend<Category, Category, never>>; id: typeof NumberFromString; name: typeof String$; }>' is not assignable to type 'Schema<Category, Category, never>'.
  The types of 'Encoded.id' are incompatible between these types.
    Type 'string' is not assignable to type 'number'.ts(2322)
*/

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:

import { Schema } from "@effect/schema"

const fields = {
  id: Schema.NumberFromString,
  name: Schema.String
}

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

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

const Category = Schema.Struct({
  ...fields,
  subcategories: Schema.Array(
    Schema.suspend(
      (): Schema.Schema<Category, CategoryEncoded> => Category
    )
  )
})