SchemaAST

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 the node's annotations directly.

See

• resolveAt
• resolveIdentifier
• resolveTitle
• resolveDescription

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

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

See

• resolve
• resolveTitle
• 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

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

See

• resolve
• resolveIdentifier
• resolveDescription

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

Constructs a Any.

Constructs a Arrays.

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

Constructs a 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

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

Constructs a Boolean.

Constructs a Context.

Constructs a Declaration.

Constructs a Enum. Numeric values must be finite.

Constructs a Filter.

Constructs a FilterGroup.

Constructs a IndexSignature.

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

Arbitrary metadata preserves both regExp.source and regExp.flags. Implementations that cannot consume all flags may still use the source as a generation hint because the Schema filter validates every generated value. JSON Schema has no way to carry JavaScript regular-expression flags. The generated pattern contains the source only, so validation can differ when the RegExp uses flags or relies on JavaScript's non-Unicode behavior.

See

• Filter

Constructs a Link.

Constructs a Literal.

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

Constructs a Never.

Constructs a Null.

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

Constructs a Number.

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

Constructs a ObjectKeyword.

Constructs a Objects.

Constructs a PropertySignature.

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

Constructs a String.

Constructs a Suspend.

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

Constructs a Symbol.

Constructs a TemplateLiteral.

Gotchas

Throws if a part contains an encoding, including inside unions or nested template literals. Parts must describe their values without transformations.

Constructs a Undefined.

Constructs a Union.

Constructs a UniqueSymbol.

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

Constructs a Unknown.

Constructs a Void.

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

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

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

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

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

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

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

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

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

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

Narrows an AST to Number.

When to use

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

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

Narrows an AST to 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

• 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

Narrows an AST to 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

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

Narrows an AST to TemplateLiteral.

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

Narrows an AST to Union.

Narrows an AST to 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

• isAny for the guard for the Any node, whose parsed result is typed as any rather than 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

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

AST node representing the any type — every value matches.

See

• any
• isAny

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's isOptional field 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

• isArrays
• Objects

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 annotations, checks, encoding, and context fields.
• Discriminate on the _tag field (e.g. "String", "Objects", "Union").

See

• isAST

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

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

See

• boolean
• isBoolean

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

Details

Stored in an AST node's Checks array.

See

• Filter
• FilterGroup

Non-empty array of validation Check values attached to an AST node's checks field.

Details

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

See

• Check
• Filter
• FilterGroup

Represents per-property metadata attached to an AST node's context field.

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

• Schema.optionalKey
• isOptional

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. The Effect returned by the parser must complete synchronously.

See

• isDeclaration

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 an AST node's encoding field. When undefined, the node has no encoding transformation (type and encoded forms are identical).

See

• Link
• toEncoded

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

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

• FilterGroup
• Check
• isPattern

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

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

• Objects
• PropertySignature

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

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, preserving the input value. Both 0 and -0 are accepted by either zero literal, and parsing preserves the input's sign. Numeric literals must be finite. Infinity, -Infinity, and NaN are rejected at construction time.

See

• LiteralValue
• isLiteral

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

See

• Literal

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

AST node matching the null literal value.

Details

Parsing succeeds only when the input is exactly null.

See

• null
• isNull

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

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

See

• objectKeyword
• isObjectKeyword

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

• isObjects
• PropertySignature
• IndexSignature
• Arrays

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

AST node matching any string value.

See

• string
• isString

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

• isSuspend

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

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

AST node matching the undefined value.

Details

Parsing succeeds only when the input is exactly undefined.

See

• undefined
• isUndefined

AST node representing a union of schemas.

Details

• types — the member AST nodes.
• options.mode selects matching behavior. "anyOf" succeeds on the first match; "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

• isUnion

AST node matching a specific unique symbol value.

Details

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

See

• isUniqueSymbol

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

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

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, check execution, and product concurrency. Options apply throughout the parse; schema annotations do not override them.

• errors — "first" (default) stops at the first error; "all" collects every error.
• onExcessProperty — "ignore" (default) strips unknown object keys; "error" fails.
• disableChecks — skips validation checks while still applying defaults and transformations.
• concurrency — controls concurrent parsing of tuple elements, array elements, struct fields, and record entries using the same semantics as Effect.forEach; the default is sequential.
• reportInput — includes rejected input values in value-bearing schema issues.

Object property order is unspecified, including in values passed to checks. Decoding and encoding do not guarantee preservation of input key order.

Local matching options stored on Union nodes.

Returns true if the AST node represents an optional property.

Details

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

See

• Schema.optionalKey
• Context

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.decodeTo. 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

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

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

• toType
• flip

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

• toEncoded
• flip