SchemaAST
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.
Annotations
Signature
declare const resolve: (ast: AST) => Schema.Annotations.Annotations | undefined;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
Signature
declare const resolveAt: <A>(key: string) => (ast: AST) => A | undefined;resolveDescription
Returns the description annotation from the AST node, if set.
See
Signature
declare const resolveDescription: (ast: AST) => string | undefined;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
Signature
declare const resolveIdentifier: (ast: AST) => string | undefined;resolveTitle
Returns the title annotation from the AST node, if set.
See
Signature
declare const resolveTitle: (ast: AST) => string | undefined;Constructors
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
unknownfor the sibling AST singleton that also accepts every value while preserving the saferunknowntype
Signature
declare const any: Any;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
Signature
declare const bigInt: BigInt;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
Signature
declare const boolean: Boolean;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 is cloned and its lastIndex is reset before each test, so global and sticky expressions are deterministic and the provided regular expression is not mutated. The regular expression source is stored in annotations for serialization and arbitrary generation.
Gotchas
When deriving an arbitrary, only regExp.source is used. Regular expression flags are ignored because fast-check does not support them.
See
Signature
declare function isPattern(regExp: RegExp, annotations?: Filter): Filter<string>;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
Signature
declare const never: Never;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
Signature
declare const number: Number;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
ObjectKeywordfor the AST node classisObjectKeywordfor narrowing an AST to anObjectKeywordnode
Signature
declare const objectKeyword: ObjectKeyword;Provides the singleton String AST instance.
When to use
Use as the shared SchemaAST node for unconstrained JavaScript strings.
See
Signature
declare const string: String;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
UniqueSymbolfor an AST node that matches one specific symbol
Signature
declare const symbol: Symbol;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
anyfor the singleton that accepts every value asany
Signature
declare const unknown: Unknown;Guards
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
isUnknownfor the guard for theUnknownnode, whose parsed result is typed asunknownrather thanany
Signature
declare const isAny: (ast: AST) => ast is Any;Narrows an AST to Arrays.
When to use
Use to recognize array-like AST nodes before reading their element, rest, or mutability metadata.
See
Arraysfor the AST node type narrowed by this guard
Signature
declare const isArrays: (ast: AST) => ast is Arrays;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
Signature
declare function isAST(u: unknown): u is AST;Narrows an AST to BigInt.
When to use
Use to identify bigint AST nodes while inspecting or transforming schema ASTs.
See
Signature
declare const isBigInt: (ast: AST) => ast is BigInt;Narrows an AST to Boolean.
When to use
Use to identify the Boolean AST variant while inspecting, traversing, or transforming schema definitions.
See
Signature
declare const isBoolean: (ast: AST) => ast is Boolean;isDeclaration
Narrows an AST to Declaration.
When to use
Use to recognize declaration AST nodes before running declaration-specific handling.
See
Declarationfor the AST node type narrowed by this guard
Signature
declare const isDeclaration: (ast: AST) => ast is Declaration;Narrows an AST to Enum.
When to use
Use to recognize enum AST nodes before reading enum cases or running enum-specific handling.
See
Enumfor the AST node type narrowed by this guard
Signature
declare const isEnum: (ast: AST) => ast is Enum;Narrows an AST to Literal.
When to use
Use to recognize exact string, number, boolean, or bigint literal AST nodes.
See
Literalfor the AST node type narrowed by this guardLiteralValuefor the values stored by literal nodes
Signature
declare const isLiteral: (ast: AST) => ast is Literal;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
Signature
declare const isNever: (ast: AST) => ast is Never;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
Signature
declare const isNull: (ast: AST) => ast is Null;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;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
ObjectKeywordfor the AST node matched by this guardobjectKeywordfor the singletonObjectKeywordAST instanceisObjectsfor struct and record AST nodes
Signature
declare const isObjectKeyword: (ast: AST) => ast is ObjectKeyword;Narrows an AST to Objects.
Signature
declare const isObjects: (ast: AST) => ast is Objects;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
Signature
declare const isString: (ast: AST) => ast is String;Narrows an AST to Suspend.
Signature
declare const isSuspend: (ast: AST) => ast is Suspend;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
isUniqueSymbolfor the sibling guard that narrows theUniqueSymbolvariant for one exact symbol value
Signature
declare const isSymbol: (ast: AST) => ast is Symbol;isTemplateLiteral
Narrows an AST to TemplateLiteral.
Signature
declare const isTemplateLiteral: (ast: AST) => ast is TemplateLiteral;isUndefined
Narrows an AST to Undefined.
When to use
Use to identify AST nodes that represent exactly the JavaScript undefined value.
See
isVoidfor narrowing AST nodes that represent TypeScriptvoidinstead of exactundefined
Signature
declare const isUndefined: (ast: AST) => ast is Undefined;Narrows an AST to Union.
Signature
declare const isUnion: (ast: AST) => ast is Union<AST>;isUniqueSymbol
Narrows an AST to UniqueSymbol.
Signature
declare const isUniqueSymbol: (ast: AST) => ast is UniqueSymbol;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
isAnyfor the guard for theAnynode, whose parsed result is typed asanyrather thanunknown
Signature
declare const isUnknown: (ast: AST) => ast is Unknown;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
isUndefinedfor narrowing AST nodes that represent the literalundefinedvalue instead of TypeScriptvoid
Signature
declare const isVoid: (ast: AST) => ast is Void;Models
Signature
declare class Any extends Base {
constructor(
annotations: Annotations | undefined,
checks: readonly [Check<any>, Check<any>] | undefined,
encoding: readonly [Link, Link] | undefined,
context: Context | undefined,
);
readonly _tag: "Any";
}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.
See
Signature
declare class Arrays extends Base {
constructor(isMutable: boolean, elements: readonly Array<AST>, rest: readonly Array<AST>, annotations?: Annotations, checks?: readonly [Check<any>, Check<any>], encoding?: readonly [Link, Link], context?: Context, encodingChecks?: readonly [Check<any>, Check<any>]);
readonly _tag: "Arrays";
readonly elements: readonly Array<AST>;
readonly encodingChecks: readonly [Check<any>, Check<any>] | undefined;
readonly isMutable: boolean;
readonly rest: readonly Array<AST>;
}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
Signature
type AST =
| Declaration
| Null
| Undefined
| Void
| Never
| Unknown
| Any
| String
| Number
| Boolean
| BigInt
| Symbol
| Literal
| UniqueSymbol
| ObjectKeyword
| Enum
| TemplateLiteral
| Arrays
| Objects
| Union
| Suspend;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
Signature
declare class Base {
constructor(
annotations: Annotations | undefined,
checks: readonly [Check<any>, Check<any>] | undefined,
encoding: readonly [Link, Link] | undefined,
context: Context | undefined,
);
abstract readonly _tag: string;
readonly "~effect/Schema": "~effect/Schema";
readonly annotations: Annotations | undefined;
readonly checks: readonly [Check<any>, Check<any>] | undefined;
readonly context: Context | undefined;
readonly encoding: readonly [Link, Link] | undefined;
toString(): string;
}AST node matching any bigint value.
Details
When serialized to a string-based codec, bigints are converted to/from their decimal string representation.
See
Signature
declare class BigInt extends Base {
constructor(
annotations: Annotations | undefined,
checks: readonly [Check<any>, Check<any>] | undefined,
encoding: readonly [Link, Link] | undefined,
context: Context | undefined,
);
readonly _tag: "BigInt";
}Signature
declare class Boolean extends Base {
constructor(
annotations: Annotations | undefined,
checks: readonly [Check<any>, Check<any>] | undefined,
encoding: readonly [Link, Link] | undefined,
context: Context | undefined,
);
readonly _tag: "Boolean";
}A validation check — either a single Filter or a composite FilterGroup.
Details
Stored in the Checks array on Base.checks.
See
Signature
type Check<T> = Filter<T> | FilterGroup<T>;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
Signature
type Checks = readonly [Check<any>, ...Array<Check<any>>];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. - constructorDefault — a Link applied during construction to supply missing values. - annotations — key-level annotations (e.g. description of the key itself).
See
Signature
declare class Context {
constructor(
isOptional: boolean,
isMutable: boolean,
constructorDefault: Link | undefined,
annotations: Key<unknown> | undefined,
);
readonly annotations: Key<unknown> | undefined;
readonly constructorDefault: Link | undefined;
readonly isMutable: boolean;
readonly isOptional: boolean;
}Declaration
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
Signature
declare class Declaration extends Base {
constructor(typeParameters: readonly Array<AST>, run: (typeParameters: readonly Array<AST>) => (input: unknown, self: Declaration, options: ParseOptions) => Effect<any, Issue, any>, annotations?: Annotations, checks?: readonly [Check<any>, Check<any>], encoding?: readonly [Link, Link], context?: Context, encodingChecks?: readonly [Check<any>, Check<any>]);
readonly _tag: "Declaration";
readonly encodingChecks: readonly [Check<any>, Check<any>] | undefined;
readonly run: (typeParameters: readonly Array<AST>) => (input: unknown, self: Declaration, options: ParseOptions) => Effect<any, Issue, any>;
readonly typeParameters: readonly Array<AST>;
}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
Signature
type Encoding = readonly [Link, ...Array<Link>];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
Signature
declare class Enum extends Base {
constructor(enums: readonly Array<readonly [string, string | number]>, annotations?: Annotations, checks?: readonly [Check<any>, Check<any>], encoding?: readonly [Link, Link], context?: Context);
readonly _tag: "Enum";
readonly enums: readonly Array<readonly [string, string | number]>;
}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 annotations (expected message, representation, 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
Signature
declare class Filter<in E> extends Class {
constructor<in E>(run: (input: E, self: AST, options: ParseOptions) => Issue | undefined, annotations: Filter | undefined, aborted: boolean);
readonly _tag: "Filter";
readonly aborted: boolean;
readonly annotations: Filter | undefined;
readonly run: (input: E, self: AST, options: ParseOptions) => Issue | undefined;
abort(): Filter<E>;
and(other: Check<E>, annotations?: Filter): FilterGroup<E>;
annotate(annotations: Filter): Filter<E>;
}FilterGroup
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
Signature
declare class FilterGroup<in E> extends Class {
constructor<in E>(checks: readonly [Check<E>, Check<E>], annotations: Filter | undefined);
readonly _tag: "FilterGroup";
readonly annotations: Filter | undefined;
readonly checks: readonly [Check<E>, Check<E>];
and(other: Check<E>, annotations?: Filter): FilterGroup<E>;
annotate(annotations: Filter): FilterGroup<E>;
}IndexSignature
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.
Gotchas
Using Schema.optionalKey on the value type is not allowed for index signatures (throws at construction); use Schema.optional instead.
See
Signature
declare class IndexSignature {
constructor(parameter: AST, type: AST);
readonly parameter: IndexSignatureParameter;
readonly type: AST;
}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
Signature
declare class Link {
constructor(
to: AST,
transformation: Middleware<any, any, any, any, any, any> | Transformation<any, any, any, any>,
);
readonly to: AST;
readonly transformation:
| Middleware<any, any, any, any, any, any>
| Transformation<any, any, any, any>;
}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.
See
Signature
declare class Literal extends Base {
constructor(
literal: LiteralValue,
annotations?: Annotations,
checks?: readonly [Check<any>, Check<any>],
encoding?: readonly [Link, Link],
context?: Context,
);
readonly _tag: "Literal";
readonly literal: LiteralValue;
}LiteralValue type
Signature
type LiteralValue = string | number | boolean | bigint;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
Signature
declare class Never extends Base {
constructor(
annotations: Annotations | undefined,
checks: readonly [Check<any>, Check<any>] | undefined,
encoding: readonly [Link, Link] | undefined,
context: Context | undefined,
);
readonly _tag: "Never";
}AST node matching the null literal value.
Details
Parsing succeeds only when the input is exactly null.
See
Signature
declare class Null extends Base {
constructor(
annotations: Annotations | undefined,
checks: readonly [Check<any>, Check<any>] | undefined,
encoding: readonly [Link, Link] | undefined,
context: Context | undefined,
);
readonly _tag: "Null";
}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
Signature
declare class Number extends Base {
constructor(
annotations: Annotations | undefined,
checks: readonly [Check<any>, Check<any>] | undefined,
encoding: readonly [Link, Link] | undefined,
context: Context | undefined,
);
readonly _tag: "Number";
}ObjectKeyword
AST node matching the TypeScript object type — accepts objects, arrays, and functions (anything non-primitive and non-null).
See
Signature
declare class ObjectKeyword extends Base {
constructor(
annotations: Annotations | undefined,
checks: readonly [Check<any>, Check<any>] | undefined,
encoding: readonly [Link, Link] | undefined,
context: Context | undefined,
);
readonly _tag: "ObjectKeyword";
}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.
See
Signature
declare class Objects extends Base {
constructor(propertySignatures: readonly Array<PropertySignature>, indexSignatures: readonly Array<IndexSignature>, annotations?: Annotations, checks?: readonly [Check<any>, Check<any>], encoding?: readonly [Link, Link], context?: Context, encodingChecks?: readonly [Check<any>, Check<any>]);
readonly _tag: "Objects";
readonly encodingChecks: readonly [Check<any>, Check<any>] | undefined;
readonly indexSignatures: readonly Array<IndexSignature>;
readonly propertySignatures: readonly Array<PropertySignature>;
}PropertySignature
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
Signature
declare class PropertySignature {
constructor(name: PropertyKey, type: AST);
readonly name: PropertyKey;
readonly type: AST;
}Signature
declare class String extends Base {
constructor(
annotations: Annotations | undefined,
checks: readonly [Check<any>, Check<any>] | undefined,
encoding: readonly [Link, Link] | undefined,
context: Context | undefined,
);
readonly _tag: "String";
}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.
See
Signature
declare class Suspend extends Base {
constructor(
thunk: () => AST,
annotations?: Annotations,
checks?: readonly [Check<any>, Check<any>],
encoding?: readonly [Link, Link],
context?: Context,
);
readonly _tag: "Suspend";
readonly thunk: () => AST;
}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
Signature
declare class Symbol extends Base {
constructor(
annotations: Annotations | undefined,
checks: readonly [Check<any>, Check<any>] | undefined,
encoding: readonly [Link, Link] | undefined,
context: Context | undefined,
);
readonly _tag: "Symbol";
}TemplateLiteral
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
Signature
declare class TemplateLiteral extends Base {
constructor(parts: readonly Array<AST>, annotations?: Annotations, checks?: readonly [Check<any>, Check<any>], encoding?: readonly [Link, Link], context?: Context);
readonly _tag: "TemplateLiteral";
readonly parts: readonly Array<AST>;
}AST node matching the undefined value.
Details
Parsing succeeds only when the input is exactly undefined.
See
Signature
declare class Undefined extends Base {
constructor(
annotations: Annotations | undefined,
checks: readonly [Check<any>, Check<any>] | undefined,
encoding: readonly [Link, Link] | undefined,
context: Context | undefined,
);
readonly _tag: "Undefined";
}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.
See
Signature
declare class Union<A extends AST = AST> extends Base {
constructor<A extends AST = AST>(types: readonly Array<A>, mode: "anyOf" | "oneOf", annotations?: Annotations, checks?: readonly [Check<any>, Check<any>], encoding?: readonly [Link, Link], context?: Context, encodingChecks?: readonly [Check<any>, Check<any>]);
readonly _tag: "Union";
readonly encodingChecks: readonly [Check<any>, Check<any>] | undefined;
readonly mode: "anyOf" | "oneOf";
readonly types: readonly Array<A>;
}UniqueSymbol
AST node matching a specific unique symbol value.
Details
Parsing succeeds only when the input is reference-equal to the stored symbol.
See
Signature
declare class UniqueSymbol extends Base {
constructor(
symbol: symbol,
annotations?: Annotations,
checks?: readonly [Check<any>, Check<any>],
encoding?: readonly [Link, Link],
context?: Context,
);
readonly _tag: "UniqueSymbol";
readonly symbol: symbol;
}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
Signature
declare class Unknown extends Base {
constructor(
annotations: Annotations | undefined,
checks: readonly [Check<any>, Check<any>] | undefined,
encoding: readonly [Link, Link] | undefined,
context: Context | undefined,
);
readonly _tag: "Unknown";
}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
Signature
declare class Void extends Base {
constructor(
annotations: Annotations | undefined,
checks: readonly [Check<any>, Check<any>] | undefined,
encoding: readonly [Link, Link] | undefined,
context: Context | undefined,
);
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
interface ParseOptions {
readonly concurrency?: number | "unbounded";
readonly disableChecks?: boolean;
readonly errors?: "first" | "all";
readonly onExcessProperty?: "error" | "ignore" | "preserve";
readonly propertyOrder?: "none" | "original";
}Other
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
Signature
declare function isOptional(ast: AST): boolean;Transforming
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
Signature
declare function decodeTo<A extends AST>(
from: AST,
to: A,
transformation: Transformation<any, any, any, any>,
): A;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
Signature
declare const flip: (ast: AST) => AST;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
Signature
declare function optionalKey<A extends AST>(ast: A): A;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.
See
Signature
declare const toEncoded: (ast: AST) => AST;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).
See
Signature
declare const toType: <A extends AST>(ast: A) => A;
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 returnsBase.annotationsdirectly.See
resolveAtresolveIdentifierresolveTitleresolveDescription