Skip to content

SchemaAST.ts

SchemaAST.ts overview

Represents Effect schemas as runtime trees.

Every Schema has an AST made from nodes for declarations, primitives, literals, arrays, objects, unions, suspended schemas, checks, annotations, encoding links, and parsing context. Most users work with the higher-level Schema module. Use SchemaAST when you need to inspect schema nodes, build ASTs programmatically, change encoded or decoded views, collect issues, or run low-level schema checks.

Since v4.0.0

Exports Grouped by Category

annotations
constants
- null
- undefined
constructors
- any
- bigInt
- boolean
- isPattern
- never
- number
- objectKeyword
- string
- symbol
- unknown
- void
guards
- isAST
- isAny
- isArrays
- isBigInt
- isBoolean
- isDeclaration
- isEnum
- isLiteral
- isNever
- isNull
- isNumber
- isObjectKeyword
- isObjects
- isString
- isSuspend
- isSymbol
- isTemplateLiteral
- isUndefined
- isUnion
- isUniqueSymbol
- isUnknown
- isVoid
models
options
- ParseOptions (interface)
predicates
- isOptional
transforming
- decodeTo
- flip
- optionalKey
- toEncoded
- toType

annotations

resolve

Returns all annotations from the AST node.

Details

If the node has Checks, returns annotations from the last check (which is where user-supplied annotations end up after .pipe(Schema.annotations(...))). Otherwise returns Base.annotations directly.

Example (Reading annotations)

import { Schema, SchemaAST } from "effect"

const schema = Schema.String.annotate({ title: "Name" })
const annotations = SchemaAST.resolve(schema.ast)
console.log(annotations?.title) // "Name"

See

resolveAt
resolveIdentifier
resolveTitle
resolveDescription

Signature

declare const resolve: (ast: AST) => Schema.Annotations.Annotations | undefined

Since v4.0.0

resolveAt

Returns a single annotation value by key from the AST node.

Details

Like resolve, reads from the last check’s annotations when checks are present. Returns undefined if the key is not found.

See

resolve

Signature

declare const resolveAt: <A>(key: string) => (ast: AST) => A | undefined

Since v4.0.0

resolveDescription

Returns the description annotation from the AST node, if set.

See

resolve
resolveTitle
resolveIdentifier

Signature

declare const resolveDescription: (ast: AST) => string | undefined

Since v4.0.0

resolveIdentifier

Returns the identifier annotation from the AST node, if set.

Details

The identifier is typically set by Schema.annotations({ identifier: "..." }) and is used for error messages and schema identification.

See

resolve
resolveTitle

Signature

declare const resolveIdentifier: (ast: AST) => string | undefined

Since v4.0.0

resolveTitle

Returns the title annotation from the AST node, if set.

See

resolve
resolveIdentifier
resolveDescription

Signature

declare const resolveTitle: (ast: AST) => string | undefined

Since v4.0.0

constants

null

Provides the singleton Null AST instance.

When to use

Use when you need the shared AST node for exact null values while inspecting or constructing schema ASTs.

Signature

declare const null: Null

Since v4.0.0

undefined

Provides the singleton Undefined AST instance.

When to use

Use when you need the shared AST node for exact undefined values while inspecting or constructing schema ASTs.

Signature

declare const undefined: Undefined

Since v4.0.0

constructors

any

Provides the singleton Any AST instance.

When to use

Use when you need the singleton AST node for the TypeScript any type and intentionally want parsing to accept every input value.

See

unknown for the sibling AST singleton that also accepts every value while preserving the safer unknown type

Signature

declare const any: Any

Since v4.0.0

bigInt

Provides the singleton BigInt AST instance.

When to use

Use to reuse the canonical BigInt AST node when constructing, inspecting, or transforming schemas at the AST level.

See

BigInt for the AST node class and string-codec behavior
isBigInt for narrowing an AST to a BigInt node

Signature

declare const bigInt: BigInt

Since v4.0.0

boolean

Provides the singleton Boolean AST instance.

When to use

Use to reuse the standard AST node that accepts either true or false when constructing schema ASTs directly.

See

Boolean for the AST node class
Literal for exact boolean literal AST nodes

Signature

declare const boolean: Boolean

Since v4.0.0

isPattern

Creates a Filter that validates strings by running RegExp.test.

When to use

Use when string validation should be represented as a schema Filter backed by a regular expression.

Details

The filter can be used with Schema.filter or attached directly to a String AST node through checks. The regular expression source is stored in annotations for serialization and arbitrary generation.

Gotchas

Use a non-global, non-sticky regular expression, or reset lastIndex yourself, because RegExp.test is stateful for expressions with the g or y flag.

Example (Validating an email pattern)

import { SchemaAST } from "effect"

const emailFilter = SchemaAST.isPattern(/^[^@]+@[^@]+$/)

See

Filter

Signature

declare const isPattern: (regExp: globalThis.RegExp, annotations?: Schema.Annotations.Filter) => Filter<string>

Since v4.0.0

never

Provides the singleton Never AST instance.

When to use

Use to reuse the canonical bottom-type AST node when constructing, comparing, or returning ASTs.

See

Never for the AST node class
isNever for narrowing an AST to a Never node

Signature

declare const never: Never

Since v4.0.0

number

Provides the singleton Number AST instance.

When to use

Use when you need the canonical SchemaAST node for schemas that accept any JavaScript number value.

See

Number for the AST node class and serialization behavior
Literal for exact finite numeric literal AST nodes

Signature

declare const number: Number

Since v4.0.0

objectKeyword

Provides the singleton ObjectKeyword AST instance.

When to use

Use to reuse the canonical AST node for the TypeScript object keyword when building or comparing SchemaAST values directly.

See

ObjectKeyword for the AST node class
isObjectKeyword for narrowing an AST to an ObjectKeyword node

Signature

declare const objectKeyword: ObjectKeyword

Since v3.10.0

string

Provides the singleton String AST instance.

When to use

Use as the shared SchemaAST node for unconstrained JavaScript strings.

See

String for the AST node class
isString for narrowing an AST to a string node

Signature

declare const string: String

Since v4.0.0

symbol

Provides the singleton Symbol AST instance.

When to use

Use to reuse the singleton AST node for schemas that match any JavaScript symbol value.

Gotchas

String-based codecs can encode only symbols registered with Symbol.for, because the implementation uses Symbol.keyFor.

See

UniqueSymbol for an AST node that matches one specific symbol

Signature

declare const symbol: Symbol

Since v4.0.0

unknown

Provides the singleton Unknown AST instance.

When to use

Use when you need the reusable AST singleton for a schema node that accepts every value while keeping parsed values opaque.

See

any for the singleton that accepts every value as any

Signature

declare const unknown: Unknown

Since v4.0.0

void

Provides the singleton Void AST instance.

When to use

Use when constructing or comparing AST nodes for TypeScript void return values whose result is intentionally ignored.

Details

The node parses any present runtime value as undefined; schemas may still expose void on their typed decoded and encoded sides.

See

Void for the AST node class
undefined for the sibling AST singleton that matches exactly undefined
isVoid for narrowing an AST to a Void node

Signature

declare const void: Void

Since v4.0.0

guards

isAST

Returns true if the value is an AST node (any variant).

Details

Uses the internal TypeId brand to distinguish AST nodes from arbitrary objects.

See

AST

Signature

declare const isAST: (u: unknown) => u is AST

Since v4.0.0

isAny

Narrows an AST to Any.

When to use

Use when you need to inspect a schema AST and handle the Any node variant specifically.

See

isUnknown for the guard for the Unknown node, whose parsed result is typed as unknown rather than any

Signature

declare const isAny: (ast: AST) => ast is Any

Since v4.0.0

isArrays

Narrows an AST to Arrays.

When to use

Use to recognize array-like AST nodes before reading their element, rest, or mutability metadata.

See

Arrays for the AST node type narrowed by this guard

Signature

declare const isArrays: (ast: AST) => ast is Arrays

Since v4.0.0

isBigInt

Narrows an AST to BigInt.

When to use

Use to identify bigint AST nodes while inspecting or transforming schema ASTs.

See

BigInt for the AST node matched by this guard
bigInt for the singleton instance; use isBigInt when narrowing an existing AST value

Signature

declare const isBigInt: (ast: AST) => ast is BigInt

Since v4.0.0

isBoolean

Narrows an AST to Boolean.

When to use

Use to identify the Boolean AST variant while inspecting, traversing, or transforming schema definitions.

See

Boolean for the AST node type matched by this guard
boolean for the singleton instance to use when constructing a boolean AST directly

Signature

declare const isBoolean: (ast: AST) => ast is Boolean

Since v4.0.0

isDeclaration

Narrows an AST to Declaration.

When to use

Use to recognize declaration AST nodes before running declaration-specific handling.

See

Declaration for the AST node type narrowed by this guard

Signature

declare const isDeclaration: (ast: AST) => ast is Declaration

Since v3.10.0

isEnum

Narrows an AST to Enum.

When to use

Use to recognize enum AST nodes before reading enum cases or running enum-specific handling.

See

Enum for the AST node type narrowed by this guard

Signature

declare const isEnum: (ast: AST) => ast is Enum

Since v4.0.0

isLiteral

Narrows an AST to Literal.

When to use

Use to recognize exact string, number, boolean, or bigint literal AST nodes.

See

Literal for the AST node type narrowed by this guard
LiteralValue for the values stored by literal nodes

Signature

declare const isLiteral: (ast: AST) => ast is Literal

Since v3.10.0

isNever

Narrows an AST to Never.

When to use

Use to detect the AST node for a schema that can never match before handling other schema variants.

See

Never for the AST node type narrowed by this guard
never for the singleton Never AST instance

Signature

declare const isNever: (ast: AST) => ast is Never

Since v4.0.0

isNull

Narrows an AST to Null.

When to use

Use to recognize an AST node that represents exactly the null literal when inspecting, traversing, or transforming schema ASTs.

See

Null for the AST node type narrowed by this guard
null for the singleton Null AST instance
isLiteral for exact primitive literal AST nodes

Signature

declare const isNull: (ast: AST) => ast is Null

Since v4.0.0

isNumber

Narrows an AST to Number.

When to use

Use to detect Number AST nodes while inspecting, traversing, or transforming schema ASTs.

Signature

declare const isNumber: (ast: AST) => ast is Number

Since v4.0.0

isObjectKeyword

Narrows an AST to ObjectKeyword.

When to use

Use to identify the AST node for the TypeScript object keyword when inspecting or transforming a Schema AST.

See

ObjectKeyword for the AST node matched by this guard
objectKeyword for the singleton ObjectKeyword AST instance
isObjects for struct and record AST nodes

Signature

declare const isObjectKeyword: (ast: AST) => ast is ObjectKeyword

Since v3.10.0

isObjects

Narrows an AST to Objects.

Signature

declare const isObjects: (ast: AST) => ast is Objects

Since v4.0.0

isString

Narrows an AST to String.

When to use

Use to detect schema AST nodes that match any string value while inspecting or transforming a Schema AST.

See

String for the AST node class narrowed by this guard
string for the singleton String AST instance
isLiteral for exact primitive literal AST nodes, including exact string literals

Signature

declare const isString: (ast: AST) => ast is String

Since v4.0.0

isSuspend

Narrows an AST to Suspend.

Signature

declare const isSuspend: (ast: AST) => ast is Suspend

Since v3.10.0

isSymbol

Narrows an AST to Symbol.

When to use

Use to narrow an AST node before handling the Symbol variant for schemas that accept any JavaScript symbol value.

See

isUniqueSymbol for the sibling guard that narrows the UniqueSymbol variant for one exact symbol value

Signature

declare const isSymbol: (ast: AST) => ast is Symbol

Since v4.0.0

isTemplateLiteral

Narrows an AST to TemplateLiteral.

Signature

declare const isTemplateLiteral: (ast: AST) => ast is TemplateLiteral

Since v3.10.0

isUndefined

Narrows an AST to Undefined.

When to use

Use to identify AST nodes that represent exactly the JavaScript undefined value.

See

isVoid for narrowing AST nodes that represent TypeScript void instead of exact undefined

Signature

declare const isUndefined: (ast: AST) => ast is Undefined

Since v4.0.0

isUnion

Narrows an AST to Union.

Signature

declare const isUnion: (ast: AST) => ast is Union<AST>

Since v3.10.0

isUniqueSymbol

Narrows an AST to UniqueSymbol.

Signature

declare const isUniqueSymbol: (ast: AST) => ast is UniqueSymbol

Since v3.10.0

isUnknown

Narrows an AST to Unknown.

When to use

Use when you need to inspect a schema AST and handle the Unknown node variant specifically.

See

isAny for the guard for the Any node, whose parsed result is typed as any rather than unknown

Signature

declare const isUnknown: (ast: AST) => ast is Unknown

Since v4.0.0

isVoid

Narrows an AST to Void.

When to use

Use to identify AST nodes that represent the TypeScript void type before handling Void-specific schema behavior.

See

isUndefined for narrowing AST nodes that represent the literal undefined value instead of TypeScript void

Signature

declare const isVoid: (ast: AST) => ast is Void

Since v4.0.0

models

AST (type alias)

Discriminated union of all AST node types.

Details

Every Schema has an .ast property of this type. Use the guard functions (isString, isObjects, etc.) to narrow to a specific variant, then access variant-specific fields.

All variants share the Base fields: annotations, checks, encoding, context.
Discriminate on the _tag field (e.g. "String", "Objects", "Union").

See

Base
isAST

Signature

type AST =
  | Declaration
  | Null
  | Undefined
  | Void
  | Never
  | Unknown
  | Any
  | String
  | Number
  | Boolean
  | BigInt
  | Symbol
  | Literal
  | UniqueSymbol
  | ObjectKeyword
  | Enum
  | TemplateLiteral
  | Arrays
  | Objects
  | Union
  | Suspend

Since v3.10.0

Any (class)

AST node representing the any type — every value matches.

See

any
isAny

Signature

declare class Any

Since v4.0.0

_tag (property)

Signature

readonly _tag: "Any"

Arrays (class)

AST node for array-like types — both tuples and arrays.

When to use

Use when constructing or inspecting AST nodes for tuple or array-like schemas, including rest elements.

Details

elements — positional element types (tuple elements). An element is optional if its Context.isOptional is true.
rest — the rest/variadic element types. When non-empty, the first entry is the “spread” type (e.g. ...Array<string>), and subsequent entries are trailing positional elements after the spread.
isMutable — whether the resulting array is readonly (false) or mutable (true).

Gotchas

Construction enforces TypeScript ordering rules: a required element cannot follow an optional one, and an optional element cannot follow a rest element.

Example (Inspecting a tuple AST)

import { Schema, SchemaAST } from "effect"

const schema = Schema.Tuple([Schema.String, Schema.Number])
const ast = schema.ast

if (SchemaAST.isArrays(ast)) {
  console.log(ast.elements.length) // 2
  console.log(ast.rest.length) // 0
}

See

isArrays
Objects

Signature

declare class Arrays {
  constructor(
    isMutable: boolean,
    elements: ReadonlyArray<AST>,
    rest: ReadonlyArray<AST>,
    annotations?: Schema.Annotations.Annotations,
    checks?: Checks,
    encoding?: Encoding,
    context?: Context,
    encodingChecks?: Checks
  )
}

Since v4.0.0

_rebuild (method)

Signature

declare const _rebuild: (
  recur: (ast: AST) => AST,
  checks: Checks | undefined,
  encodingChecks: Checks | undefined
) => Arrays

_tag (property)

Signature

readonly _tag: "Arrays"

isMutable (property)

Signature

readonly isMutable: boolean

elements (property)

Signature

readonly elements: ReadonlyArray<AST>

rest (property)

Signature

readonly rest: ReadonlyArray<AST>

encodingChecks (property)

Signature

readonly encodingChecks: readonly [Check<any>, ...Check<any>[]] | undefined

Base (class)

Represents the abstract base class for all AST node variants.

Details

Every AST node extends Base and inherits these fields:

annotations — user-supplied metadata (identifier, title, description, arbitrary keys).
checks — optional Checks for post-type-match validation.
encoding — optional Encoding chain for type ↔ wire transformations.
context — optional Context for per-property metadata.

Subclasses add a _tag discriminant and variant-specific data.

See

AST

Signature

declare class Base {
  constructor(
    annotations: Schema.Annotations.Annotations | undefined = undefined,
    checks: Checks | undefined = undefined,
    encoding: Encoding | undefined = undefined,
    context: Context | undefined = undefined
  )
}

Since v4.0.0

toString (method)

Signature

declare const toString: () => string

[TypeId] (property)

Signature

readonly [TypeId]: "~effect/Schema"

_tag (property)

Signature

readonly _tag: string

annotations (property)

Signature

readonly annotations: Schema.Annotations.Annotations | undefined

checks (property)

Signature

readonly checks: readonly [Check<any>, ...Check<any>[]] | undefined

encoding (property)

Signature

readonly encoding: readonly [Link, ...Link[]] | undefined

context (property)

Signature

readonly context: Context | undefined

BigInt (class)

AST node matching any bigint value.

Details

When serialized to a string-based codec, bigints are converted to/from their decimal string representation.

See

bigInt
isBigInt

Signature

declare class BigInt

Since v4.0.0

_tag (property)

Signature

readonly _tag: "BigInt"

Boolean (class)

AST node matching any boolean value (true or false).

See

boolean
isBoolean

Signature

declare class Boolean

Since v4.0.0

_tag (property)

Signature

readonly _tag: "Boolean"

Check (type alias)

A validation check — either a single Filter or a composite FilterGroup.

Details

Stored in the Checks array on Base.checks.

See

Filter
FilterGroup

Signature

type Check<T> = Filter<T> | FilterGroup<T>

Since v4.0.0

Checks (type alias)

Non-empty array of validation Check values attached to an AST node via Base.checks.

Details

Checks are run after basic type matching succeeds. They represent refinements like minLength, pattern, int, etc.

See

Check
Filter
FilterGroup

Signature

type Checks = readonly [Check<any>, ...Array<Check<any>>]

Since v4.0.0

Context (class)

Represents per-property metadata attached to AST nodes via Base.context.

Details

Tracks whether a property key is optional, mutable, has a constructor default, or carries key-level annotations. Typically set by helpers like optionalKey and Schema.mutableKey.

isOptional — the property key may be absent from the input.
isMutable — the property is readonly when false.
defaultValue — an Encoding applied during construction to supply missing values.
annotations — key-level annotations (e.g. description of the key itself).

See

optionalKey
isOptional

Signature

declare class Context {
  constructor(
    isOptional: boolean,
    isMutable: boolean,
    /** Used for constructor default values (e.g. `withConstructorDefault` API) */
    defaultValue: Encoding | undefined = undefined,
    annotations: Schema.Annotations.Key<unknown> | undefined = undefined
  )
}

Since v4.0.0

isOptional (property)

Signature

readonly isOptional: boolean

isMutable (property)

Signature

readonly isMutable: boolean

defaultValue (property)

Used for constructor default values (e.g. withConstructorDefault API)

Signature

readonly defaultValue: readonly [Link, ...Link[]] | undefined

annotations (property)

Signature

readonly annotations: Schema.Annotations.Key<unknown> | undefined

Declaration (class)

AST node for user-defined opaque types with custom parsing logic.

When to use

Use when you need a custom schema AST node because none of the built-in nodes fit.

Details

typeParameters — inner schemas this declaration is parameterized over (e.g. the element type for a custom collection).
run — factory that receives typeParameters and returns a parser that validates or transforms raw input.

See

isDeclaration

Signature

declare class Declaration {
  constructor(
    typeParameters: ReadonlyArray<AST>,
    run: (
      typeParameters: ReadonlyArray<AST>
    ) => (input: unknown, self: Declaration, options: ParseOptions) => Effect.Effect<any, SchemaIssue.Issue, any>,
    annotations?: Schema.Annotations.Annotations,
    checks?: Checks,
    encoding?: Encoding,
    context?: Context,
    encodingChecks?: Checks
  )
}

Since v3.10.0

_rebuild (method)

Signature

declare const _rebuild: (
  recur: (ast: AST) => AST,
  checks: Checks | undefined,
  encodingChecks: Checks | undefined
) => Declaration

_tag (property)

Signature

readonly _tag: "Declaration"

typeParameters (property)

Signature

readonly typeParameters: ReadonlyArray<AST>

run (property)

Signature

readonly run: (typeParameters: ReadonlyArray<AST>) => (input: unknown, self: Declaration, options: ParseOptions) => Effect.Effect<any, SchemaIssue.Issue, any>

encodingChecks (property)

Signature

readonly encodingChecks: readonly [Check<any>, ...Check<any>[]] | undefined

Encoding (type alias)

A non-empty chain of Link values representing the transformation steps between a schema’s decoded (type) form and its encoded (wire) form.

Details

Stored on Base.encoding. When undefined, the node has no encoding transformation (type and encoded forms are identical).

See

Link
toEncoded

Signature

type Encoding = readonly [Link, ...Array<Link>]

Since v4.0.0

Enum (class)

AST node representing a TypeScript enum.

Details

Holds enums as an array of [name, value] pairs where values are string | number. Parsing succeeds when the input matches any enum value.

See

isEnum

Signature

declare class Enum {
  constructor(
    enums: ReadonlyArray<readonly [string, string | number]>,
    annotations?: Schema.Annotations.Annotations,
    checks?: Checks,
    encoding?: Encoding,
    context?: Context
  )
}

Since v4.0.0

_tag (property)

Signature

readonly _tag: "Enum"

enums (property)

Signature

readonly enums: ReadonlyArray<readonly [string, string | number]>

Filter (class)

Represents a single validation check attached to an AST node.

Details

run — the validation function. Returns undefined on success, or an Issue on failure.
annotations — optional filter-level metadata (expected message, meta tags, arbitrary constraint hints).
aborted — when true, parsing stops immediately after this filter fails (no further checks run).

Use .annotate() to add metadata and .abort() to mark as aborting. Combine with another check via .and() to form a FilterGroup.

See

FilterGroup
Check
isPattern

Signature

declare class Filter<E> {
  constructor(
    run: (input: E, self: AST, options: ParseOptions) => SchemaIssue.Issue | undefined,
    annotations: Schema.Annotations.Filter | undefined = undefined,
    /**
     * Whether the parsing process should be aborted after this check has failed.
     */
    aborted: boolean = false
  )
}

Since v4.0.0

annotate (method)

Signature

declare const annotate: (annotations: Schema.Annotations.Filter) => Filter<E>

abort (method)

Signature

declare const abort: () => Filter<E>

and (method)

Signature

declare const and: (other: Check<E>, annotations?: Schema.Annotations.Filter) => FilterGroup<E>

_tag (property)

Signature

readonly _tag: "Filter"

run (property)

Signature

readonly run: (input: E, self: AST, options: ParseOptions) => SchemaIssue.Issue | undefined

annotations (property)

Signature

readonly annotations: Schema.Annotations.Filter | undefined

aborted (property)

Whether the parsing process should be aborted after this check has failed.

Signature

readonly aborted: boolean

Represents a composite validation check grouping multiple Check values.

Details

Created by calling .and() on a Filter or another FilterGroup. All inner checks are run; failures from aborted filters still stop evaluation.

See

Filter
Check

Signature

declare class FilterGroup<E> {
  constructor(
    checks: readonly [Check<E>, ...Array<Check<E>>],
    annotations: Schema.Annotations.Filter | undefined = undefined
  )
}

Since v4.0.0

annotate (method)

Signature

declare const annotate: (annotations: Schema.Annotations.Filter) => FilterGroup<E>

and (method)

Signature

declare const and: (other: Check<E>, annotations?: Schema.Annotations.Filter) => FilterGroup<E>

_tag (property)

Signature

readonly _tag: "FilterGroup"

checks (property)

Signature

readonly checks: readonly [Check<E>, ...Check<E>[]]

annotations (property)

Signature

readonly annotations: Schema.Annotations.Filter | undefined

IndexSignature (class)

Represents an index signature entry within an Objects node.

When to use

Use when constructing or inspecting object AST entries for record-like keys and values.

Details

parameter — the key type AST (e.g. String for string keys, TemplateLiteral for patterned keys).
type — the value type SchemaAST.
merge — optional KeyValueCombiner for handling duplicate keys.

Gotchas

Using Schema.optionalKey on the value type is not allowed for index signatures (throws at construction); use Schema.optional instead.

See

Objects
PropertySignature

Signature

declare class IndexSignature {
  constructor(parameter: AST, type: AST, merge: KeyValueCombiner | undefined)
}

Since v3.10.0

parameter (property)

Signature

readonly parameter: IndexSignatureParameter

type (property)

Signature

readonly type: AST

merge (property)

Signature

readonly merge: KeyValueCombiner | undefined

KeyValueCombiner (class)

Represents a bidirectional merge strategy for index signature key-value pairs.

Details

Used by IndexSignature when the same key appears multiple times (e.g. from Schema.extend or overlapping records). Provides separate decode and encode combiners that determine how duplicate entries are merged.

See

IndexSignature

Signature

declare class KeyValueCombiner {
  constructor(
    decode: Combiner.Combiner<readonly [key: PropertyKey, value: any]> | undefined,
    encode: Combiner.Combiner<readonly [key: PropertyKey, value: any]> | undefined
  )
}

Since v4.0.0

decode (property)

Signature

readonly decode: Combiner.Combiner<readonly [key: PropertyKey, value: any]> | undefined

encode (property)

Signature

readonly encode: Combiner.Combiner<readonly [key: PropertyKey, value: any]> | undefined

Link (class)

Represents a single step in an Encoding chain.

Details

A link pairs a target AST with a Transformation or Middleware that converts values between the current node and the target.

to — the AST node on the other side of this transformation step.
transformation — the bidirectional conversion logic (decode/encode).

Links are composed into a non-empty array (Encoding) attached to AST nodes that have a different encoded representation.

See

Encoding
decodeTo

Signature

declare class Link {
  constructor(
    to: AST,
    transformation:
      | SchemaTransformation.Transformation<any, any, any, any>
      | SchemaTransformation.Middleware<any, any, any, any, any, any>
  )
}

Since v4.0.0

to (property)

Signature

readonly to: AST

transformation (property)

Signature

readonly transformation: SchemaTransformation.Transformation<any, any, any, any> | SchemaTransformation.Middleware<any, any, any, any, any, any>

Literal (class)

AST node matching an exact primitive value (string, number, boolean, or bigint).

Details

Parsing succeeds only when the input is strictly equal (===) to the stored literal. Numeric literals must be finite — Infinity, -Infinity, and NaN are rejected at construction time.

Example (Creating a literal AST)

import { SchemaAST } from "effect"

const ast = new SchemaAST.Literal("active")
console.log(ast.literal) // "active"

See

LiteralValue
isLiteral

Signature

declare class Literal {
  constructor(
    literal: LiteralValue,
    annotations?: Schema.Annotations.Annotations,
    checks?: Checks,
    encoding?: Encoding,
    context?: Context
  )
}

Since v3.10.0

_tag (property)

Signature

readonly _tag: "Literal"

literal (property)

Signature

readonly literal: LiteralValue

LiteralValue (type alias)

The set of primitive types that can appear as a Literal value.

See

Literal

Signature

type LiteralValue = string | number | boolean | bigint

Since v3.10.0

Never (class)

AST node representing the never type — no value matches.

Details

Parsing always fails. Useful as a placeholder in unions or as the result of narrowing that eliminates all options.

See

never
isNever

Signature

declare class Never

Since v4.0.0

_tag (property)

Signature

readonly _tag: "Never"

Null (class)

AST node matching the null literal value.

Details

Parsing succeeds only when the input is exactly null.

See

null
isNull

Signature

declare class Null

Since v4.0.0

_tag (property)

Signature

readonly _tag: "Null"

Number (class)

AST node matching any number value (including NaN, Infinity, -Infinity).

Details

Default JSON serialization:

Finite numbers are serialized as JSON numbers.
Infinity, -Infinity, and NaN are serialized as JSON strings.

If the node has an isFinite or isInt check, the string fallback is skipped since non-finite values cannot occur.

See

number
isNumber

Signature

declare class Number

Since v4.0.0

_match (method)

Signature

declare const _match: (regexp: RegExp, s: string, options: ParseOptions) => number | undefined

_tag (property)

Signature

readonly _tag: "Number"

ObjectKeyword (class)

AST node matching the TypeScript object type — accepts objects, arrays, and functions (anything non-primitive and non-null).

See

objectKeyword
isObjectKeyword

Signature

declare class ObjectKeyword

Since v3.10.0

_tag (property)

Signature

readonly _tag: "ObjectKeyword"

Objects (class)

AST node for object-like schemas, including structs and records.

When to use

Use when constructing or inspecting AST nodes for structs or records rather than array-like schemas.

Details

propertySignatures — named properties with their types (struct fields).
indexSignatures — index signature entries (record patterns), each with a parameter AST for matching keys and a type AST for values.

An Objects node with no properties and no index signatures performs only a non-nullish check: it accepts any value except null and undefined, including primitive values.

Gotchas

Duplicate property names throw at construction time.

Example (Inspecting a struct AST)

import { Schema, SchemaAST } from "effect"

const schema = Schema.Struct({ name: Schema.String })
const ast = schema.ast

if (SchemaAST.isObjects(ast)) {
  for (const ps of ast.propertySignatures) {
    console.log(ps.name, ps.type._tag)
  }
  // "name" "String"
}

See

isObjects
PropertySignature
IndexSignature
Arrays

Signature

declare class Objects {
  constructor(
    propertySignatures: ReadonlyArray<PropertySignature>,
    indexSignatures: ReadonlyArray<IndexSignature>,
    annotations?: Schema.Annotations.Annotations,
    checks?: Checks,
    encoding?: Encoding,
    context?: Context,
    encodingChecks?: Checks
  )
}

Since v4.0.0

_rebuild (method)

Signature

declare const _rebuild: (
  recur: (ast: AST) => AST,
  recurParameter: (ast: AST) => AST,
  flipMerge: boolean,
  checks: Checks | undefined,
  encodingChecks: Checks | undefined
) => Objects

_tag (property)

Signature

readonly _tag: "Objects"

propertySignatures (property)

Signature

readonly propertySignatures: ReadonlyArray<PropertySignature>

indexSignatures (property)

Signature

readonly indexSignatures: ReadonlyArray<IndexSignature>

encodingChecks (property)

Signature

readonly encodingChecks: readonly [Check<any>, ...Check<any>[]] | undefined

PropertySignature (class)

Represents a named property within an Objects node.

Details

Pairs a name (any PropertyKey) with a type (AST). The property’s optionality and mutability are determined by the type’s Context.

See

Objects

Signature

declare class PropertySignature {
  constructor(name: PropertyKey, type: AST)
}

Since v3.10.0

name (property)

Signature

readonly name: PropertyKey

type (property)

Signature

readonly type: AST

String (class)

AST node matching any string value.

See

string
isString

Signature

declare class String

Since v4.0.0

_tag (property)

Signature

readonly _tag: "String"

Suspend (class)

AST node for lazy/recursive schemas.

Details

Wraps a thunk (() => AST) that is memoized on first call. Use this to define recursive or mutually recursive schemas without infinite loops at construction time.

Example (Defining recursive schema ASTs)

import { Schema, SchemaAST } from "effect"

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

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

// The recursive branch is a Suspend node

See

isSuspend

Signature

declare class Suspend {
  constructor(
    thunk: () => AST,
    annotations?: Schema.Annotations.Annotations,
    checks?: Checks,
    encoding?: Encoding,
    context?: Context
  )
}

Since v3.10.0

_tag (property)

Signature

readonly _tag: "Suspend"

thunk (property)

Signature

readonly thunk: () => AST

Symbol (class)

AST node matching any symbol value.

When to use

Use when you need the AST node class for schemas that match any JavaScript symbol value.

Details

When serialized to a string-based codec, symbols are converted via Symbol.keyFor and must be registered with Symbol.for.

See

symbol
isSymbol

Signature

declare class Symbol

Since v4.0.0

_tag (property)

Signature

readonly _tag: "Symbol"

TemplateLiteral (class)

AST node representing a TypeScript template literal type (e.g. `user_${string}`).

Details

parts is an array of AST nodes; each part contributes to matching strings at runtime.

See

isTemplateLiteral

Signature

declare class TemplateLiteral {
  constructor(
    parts: ReadonlyArray<AST>,
    annotations?: Schema.Annotations.Annotations,
    checks?: Checks,
    encoding?: Encoding,
    context?: Context
  )
}

Since v3.10.0

_tag (property)

Signature

readonly _tag: "TemplateLiteral"

parts (property)

Signature

readonly parts: ReadonlyArray<AST>

Undefined (class)

AST node matching the undefined value.

Details

Parsing succeeds only when the input is exactly undefined.

See

undefined
isUndefined

Signature

declare class Undefined

Since v4.0.0

_tag (property)

Signature

readonly _tag: "Undefined"

Union (class)

AST node representing a union of schemas.

Details

types — the member AST nodes.
mode — "anyOf" succeeds on the first match (like TypeScript unions); "oneOf" requires exactly one member to match (fails if multiple do).

During parsing, members are tried in order. An internal candidate index narrows which members to try based on the runtime type of the input and discriminant (“sentinel”) fields, making large unions efficient.

Example (Inspecting a union AST)

import { Schema, SchemaAST } from "effect"

const schema = Schema.Union([Schema.String, Schema.Number])
const ast = schema.ast

if (SchemaAST.isUnion(ast)) {
  console.log(ast.types.length) // 2
  console.log(ast.mode) // "anyOf"
}

See

isUnion

Signature

declare class Union<A> {
  constructor(
    types: ReadonlyArray<A>,
    mode: "anyOf" | "oneOf",
    annotations?: Schema.Annotations.Annotations,
    checks?: Checks,
    encoding?: Encoding,
    context?: Context,
    encodingChecks?: Checks
  )
}

Since v3.10.0

_rebuild (method)

Signature

declare const _rebuild: (
  recur: (ast: AST) => AST,
  checks: Checks | undefined,
  encodingChecks: Checks | undefined
) => Union<AST>

_tag (property)

Signature

readonly _tag: "Union"

types (property)

Signature

readonly types: ReadonlyArray<A>

mode (property)

Signature

readonly mode: "anyOf" | "oneOf"

encodingChecks (property)

Signature

readonly encodingChecks: readonly [Check<any>, ...Check<any>[]] | undefined

UniqueSymbol (class)

AST node matching a specific unique symbol value.

Details

Parsing succeeds only when the input is reference-equal to the stored symbol.

See

isUniqueSymbol

Signature

declare class UniqueSymbol {
  constructor(
    symbol: symbol,
    annotations?: Schema.Annotations.Annotations,
    checks?: Checks,
    encoding?: Encoding,
    context?: Context
  )
}

Since v3.10.0

_tag (property)

Signature

readonly _tag: "UniqueSymbol"

symbol (property)

Signature

readonly symbol: symbol

Unknown (class)

AST node representing the unknown type — every value matches.

Details

Unlike Any, this is type-safe: the parsed result is typed as unknown rather than any.

See

unknown
isUnknown

Signature

declare class Unknown

Since v4.0.0

_tag (property)

Signature

readonly _tag: "Unknown"

Void (class)

AST node matching TypeScript void return-value semantics.

When to use

Use when you need an AST node for a value whose result is intentionally ignored.

Details

Parsers built from this node accept any present runtime input and map it to undefined. Public schemas built from it may still expose void as their typed decoded and encoded representation.

See

undefined for the AST singleton that matches only exact undefined
void
isVoid

Signature

declare class Void

Since v4.0.0

_tag (property)

Signature

readonly _tag: "Void"

options

ParseOptions (interface)

Options that control schema parsing, validation, transformation, and output behavior.

Details

Pass to Schema.decodeUnknown, Schema.encode, and related APIs to customize error reporting, excess property handling, output key ordering, check execution, and asynchronous parser concurrency.

errors — "first" (default) stops at the first error; "all" collects every error.
onExcessProperty — "ignore" (default) strips unknown object keys; "error" fails; "preserve" keeps them.
propertyOrder — "none" (default) lets the system choose key order; "original" preserves input key order.
disableChecks — skips validation checks while still applying defaults and transformations.
concurrency — maximum number of async parse effects to run concurrently; defaults to 1, or use "unbounded".

Signature

export interface ParseOptions {
  /**
   * Controls how many parsing errors are reported.
   *
   * **Details**
   *
   * The default, `"first"`, stops at the first error. Set the option to `"all"`
   * to collect every parsing error, which can help with debugging or with
   * presenting more complete error messages to a user.
   *
   * @default "first"
   */
  readonly errors?: "first" | "all" | undefined

  /**
   * Controls how object parsing handles keys that are not declared by the schema.
   *
   * **Details**
   *
   * The default, `"ignore"`, strips unspecified properties from the output. Use
   * `"error"` to fail when an excess property is present, or `"preserve"` to
   * keep excess properties in the output.
   *
   * @default "ignore"
   */
  readonly onExcessProperty?: "ignore" | "error" | "preserve" | undefined

  /**
   * The `propertyOrder` option provides control over the order of object fields
   * in the output. This feature is useful when the sequence of keys is
   * important for the consuming processes or when maintaining the input order
   * enhances readability and usability.
   *
   * **Details**
   *
   * By default, the `propertyOrder` option is set to `"none"`. This means that
   * the internal system decides the order of keys to optimize parsing speed.
   *
   * Setting `propertyOrder` to `"original"` ensures that the keys are ordered
   * as they appear in the input during the decoding/encoding process.
   *
   * **Gotchas**
   *
   * The key order for `"none"` should not be considered stable and may change
   * in future updates without notice.
   *
   * @default "none"
   */
  readonly propertyOrder?: "none" | "original" | undefined

  /**
   * Whether to disable checks while still applying defaults and
   * transformations.
   */
  readonly disableChecks?: boolean | undefined

  /**
   * The maximum number of async effects to run concurrently.
   *
   * @default 1
   */
  readonly concurrency?: number | "unbounded" | undefined
}

Since v3.10.0

predicates

isOptional

Returns true if the AST node represents an optional property.

Details

Checks ast.context?.isOptional. Defaults to false when no Context is set.

See

optionalKey
Context

Signature

declare const isOptional: (ast: AST) => boolean

Since v4.0.0

transforming

decodeTo

Attaches a Transformation to the to AST, making it decode from the from AST and encode back to it.

Details

This is the low-level primitive behind Schema.transform and Schema.transformOrFail. It appends a Link to the to node’s encoding chain.

Returns a new AST with the same type as to.

See

Link
Encoding
flip

Signature

declare const decodeTo: <A extends AST>(
  from: AST,
  to: A,
  transformation: SchemaTransformation.Transformation<any, any, any, any>
) => A

Since v4.0.0

flip

Swaps the decode and encode directions of an AST’s Encoding chain.

Details

After flipping, what was decoding becomes encoding and vice versa. This is the core operation behind Schema.encode — encoding a value is decoding with a flipped SchemaAST.

Memoized: same input reference → same output reference.
Recursively walks composite nodes.

See

toType
toEncoded

Signature

declare const flip: (ast: AST) => AST

Since v4.0.0

optionalKey

Marks an AST node’s property key as optional by setting Context.isOptional to true.

Details

Also propagates the optional flag through the last link of the encoding chain if present.

See

isOptional
Context

Signature

declare const optionalKey: <A extends AST>(ast: A) => A

Since v4.0.0

toEncoded

Returns the encoded (wire-format) AST by flipping and then stripping encodings.

Details

Equivalent to toType(flip(ast)). This gives you the AST that describes the shape of the serialized/encoded data.

Memoized: same input reference → same output reference.

Example (Getting the encoded AST)

import { Schema, SchemaAST } from "effect"

const schema = Schema.NumberFromString
const encodedAst = SchemaAST.toEncoded(schema.ast)
console.log(encodedAst._tag) // "String"

See

toType
flip

Signature

declare const toEncoded: (ast: AST) => AST

Since v4.0.0

toType

Strips all encoding transformations from an AST, returning the decoded (type-level) representation.

Details

Memoized: same input reference → same output reference.
Recursively walks into composite nodes (Arrays, Objects, Union, Suspend).

Example (Getting the type AST)

import { Schema, SchemaAST } from "effect"

const schema = Schema.NumberFromString
const typeAst = SchemaAST.toType(schema.ast)
console.log(typeAst._tag) // "Number"

See

toEncoded
flip

Signature

declare const toType: <A extends AST>(ast: A) => A

Since v4.0.0