Union<A>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"
}export class class Union<A extends AST = AST>class Union {
_tag: 'Union';
types: ReadonlyArray<A>;
mode: "anyOf" | "oneOf";
encodingChecks: Checks | undefined;
getParser: (recur: (ast: AST) => SchemaParser.Parser) => SchemaParser.Parser;
_rebuild: (recur: (ast: AST) => AST, checks: Checks | undefined, encodingChecks: Checks | undefined) => Union<AST>;
recur: (recur: (ast: AST) => AST) => Union<AST>;
flip: (recur: (ast: AST) => AST) => Union<AST>;
matchPart: (s: string, options: ParseOptions) => LiteralValue | undefined;
getExpected: (getExpected: (ast: AST) => string) => string;
annotations: Schema.Annotations.Annotations | undefined;
checks: Checks | undefined;
encoding: Encoding | undefined;
context: Context | undefined;
toString: () => string;
}
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"
}
Union<function (type parameter) A in Union<A extends AST = AST>A extends type AST =
| Declaration
| Null
| Undefined
| Void
| Never
| Unknown
| Any
| String
| Number
| Boolean
| BigInt
| Symbol
| Literal
| UniqueSymbol
| ObjectKeyword
| Enum
| TemplateLiteral
| Arrays
| Objects
| Union<AST>
| Suspend
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").
AST = type AST =
| Declaration
| Null
| Undefined
| Void
| Never
| Unknown
| Any
| String
| Number
| Boolean
| BigInt
| Symbol
| Literal
| UniqueSymbol
| ObjectKeyword
| Enum
| TemplateLiteral
| Arrays
| Objects
| Union<AST>
| Suspend
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").
AST> extends class BaseRepresents 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.
Base {
readonly Union<A extends AST = AST>._tag: "Union"_tag = "Union"
readonly Union<A extends AST = AST>.types: readonly A[]types: interface ReadonlyArray<T>ReadonlyArray<function (type parameter) A in Union<A extends AST = AST>A>
readonly Union<A extends AST = AST>.mode: "anyOf" | "oneOf"mode: "anyOf" | "oneOf"
readonly Union<A extends AST = AST>.encodingChecks: Checks | undefinedencodingChecks: type Checks = readonly [
Check<any>,
...Check<any>[]
]
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.
Checks | undefined
constructor(
types: readonly A[]types: interface ReadonlyArray<T>ReadonlyArray<function (type parameter) A in Union<A extends AST = AST>A>,
mode: "anyOf" | "oneOf"mode: "anyOf" | "oneOf",
annotations: | Schema.Annotations.Annotations
| undefined
annotations?: import SchemaSchema.Annotations.interface Annotations.AnnotationsThis interface is used to define the annotations that can be attached to a
schema. You can extend this interface to define your own annotations.
Details
Note that both a missing key or undefined is used to indicate that the
annotation is not present.
This means that can remove any annotation by setting it to undefined.
Example (Defining your own annotations)
import { Schema } from "effect"
// Extend the Annotations interface with a custom `version` annotation
declare module "effect/Schema" {
namespace Annotations {
interface Annotations {
readonly version?:
| readonly [major: number, minor: number, patch: number]
| undefined
}
}
}
// The `version` annotation is now recognized by the TypeScript compiler
const schema = Schema.String.annotate({ version: [1, 2, 0] })
// const version: readonly [major: number, minor: number, patch: number] | undefined
const version = Schema.resolveAnnotations(schema)?.["version"]
if (version) {
// Access individual parts of the version
console.log(version[1])
// Output: 2
}
Annotations,
checks: Checkschecks?: type Checks = readonly [
Check<any>,
...Check<any>[]
]
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.
Checks,
encoding: Encodingencoding?: type Encoding = readonly [Link, ...Link[]]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).
Encoding,
context: Contextcontext?: class Contextclass Context {
isOptional: boolean;
isMutable: boolean;
defaultValue: Encoding | undefined;
annotations: Schema.Annotations.Key<unknown> | undefined;
}
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).
Context,
encodingChecks: ChecksencodingChecks?: type Checks = readonly [
Check<any>,
...Check<any>[]
]
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.
Checks
) {
super(annotations: | Schema.Annotations.Annotations
| undefined
annotations, checks: Checkschecks, encoding: Encodingencoding, context: Contextcontext)
this.Union<A extends AST = AST>.types: readonly A[]types = types: readonly A[]types
this.Union<A extends AST = AST>.mode: "anyOf" | "oneOf"mode = mode: "anyOf" | "oneOf"mode
this.Union<A extends AST = AST>.encodingChecks: Checks | undefinedencodingChecks = encodingChecks: ChecksencodingChecks
}
/** @internal */
function Union(recur: (ast: AST) => SchemaParser.Parser): SchemaParser.ParsergetParser(recur: (ast: AST) => SchemaParser.Parserrecur: (ast: ASTast: type AST =
| Declaration
| Null
| Undefined
| Void
| Never
| Unknown
| Any
| String
| Number
| Boolean
| BigInt
| Symbol
| Literal
| UniqueSymbol
| ObjectKeyword
| Enum
| TemplateLiteral
| Arrays
| Objects
| Union<AST>
| Suspend
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").
AST) => import SchemaParserSchemaParser.Parser): import SchemaParserSchemaParser.Parser {
// oxlint-disable-next-line @typescript-eslint/no-this-alias
const const ast: thisast = this
return (oinput: Option.Option<unknown>oinput, options: ParseOptions(parameter) options: {
errors: "first" | "all" | undefined;
onExcessProperty: "ignore" | "error" | "preserve" | undefined;
propertyOrder: "none" | "original" | undefined;
disableChecks: boolean | undefined;
concurrency: number | "unbounded" | undefined;
}
options) => {
if (oinput: Option.Option<unknown>oinput._tag: "None" | "Some"_tag === "None") {
return import EffectEffect.const succeed: <A>(value: A) => Effect<A>Creates an Effect that always succeeds with a given value.
When to use
Use when an effect should complete successfully with a specific value without any errors
or external dependencies.
Example (Creating a successful effect)
import { Effect } from "effect"
// Creating an effect that represents a successful scenario
//
// ┌─── Effect<number, never, never>
// ▼
const success = Effect.succeed(42)
succeed(oinput: Option.None<unknown>(parameter) oinput: {
_tag: "None";
_op: "None";
valueOrUndefined: undefined;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
oinput)
}
const const input: unknowninput = oinput: Option.Some<unknown>(parameter) oinput: {
_tag: "Some";
_op: "Some";
value: A;
valueOrUndefined: A;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
oinput.Some<unknown>.value: unknownvalue
const const candidates: ReadonlyArray<AST>candidates = function getCandidates(
input: any,
types: ReadonlyArray<AST>
): ReadonlyArray<AST>
The goal is to reduce the number of a union members that will be checked.
This is useful to reduce the number of issues that will be returned.
getCandidates(const input: unknowninput, const ast: thisast.Union<A extends AST = AST>.types: readonly A[]types)
const const state: {
ast: this
recur: (ast: AST) => SchemaParser.Parser
oinput: Option.Some<unknown>
input: unknown
out: undefined
successes: never[]
issues:
| Arr.NonEmptyArray<SchemaIssue.Issue>
| undefined
options: ParseOptions
}
state = {
ast: thisast,
recur: (ast: AST) => SchemaParser.Parserrecur,
oinput: Option.Some<unknown>(property) oinput: {
_tag: "Some";
_op: "Some";
value: A;
valueOrUndefined: A;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
oinput,
input: unknowninput,
out: undefinedout: var undefinedundefined,
successes: never[]successes: [],
issues: | [SchemaIssue.Issue, ...SchemaIssue.Issue[]]
| undefined
issues: var undefinedundefined as import ArrArr.type NonEmptyArray<A> = [A, ...A[]]A mutable array guaranteed to have at least one element.
When to use
Use when mutation is acceptable and non-emptiness must be tracked at the type
level.
Details
This is the mutable counterpart of
NonEmptyReadonlyArray
. Most Array
module functions return NonEmptyArray when the result is guaranteed
non-empty.
Example (Typing a mutable non-empty array)
import type { Array } from "effect"
const nonEmpty: Array.NonEmptyArray<number> = [1, 2, 3]
nonEmpty.push(4)
NonEmptyArray<import SchemaIssueSchemaIssue.type Issue =
| SchemaIssue.Leaf
| SchemaIssue.Filter
| SchemaIssue.Encoding
| SchemaIssue.Pointer
| SchemaIssue.Composite
| SchemaIssue.AnyOf
The root discriminated union of all validation error nodes.
When to use
Use when typing the error channel in Effect<A, Issue, R> results from
schema parsing, or when writing custom formatters or issue-tree walkers.
Details
Every node has a _tag field for pattern-matching. The union includes both
terminal
Leaf
types and composite types that wrap inner issues:
Filter
,
Encoding
,
Pointer
,
Composite
,
AnyOf
. All Issue instances have a toString() that delegates to
the default formatter, so String(issue) produces a human-readable message.
Issue> | undefined,
options: ParseOptions(property) options: {
errors: "first" | "all" | undefined;
onExcessProperty: "ignore" | "error" | "preserve" | undefined;
propertyOrder: "none" | "original" | undefined;
disableChecks: boolean | undefined;
concurrency: number | "unbounded" | undefined;
}
options
}
const const concurrency:
| {
concurrency: number
}
| undefined
concurrency = const resolveConcurrency: (
value: number | "unbounded" | undefined
) =>
| {
concurrency: number
}
| undefined
resolveConcurrency(options: ParseOptions(parameter) options: {
errors: "first" | "all" | undefined;
onExcessProperty: "ignore" | "error" | "preserve" | undefined;
propertyOrder: "none" | "original" | undefined;
disableChecks: boolean | undefined;
concurrency: number | "unbounded" | undefined;
}
options?.ParseOptions.concurrency?: number | "unbounded" | undefinedThe maximum number of async effects to run concurrently.
concurrency)
const const eff:
| Effect.Effect<void, SchemaIssue.Issue, any>
| undefined
eff = const parseUnion: (
initialState: {
readonly recur: (
ast: AST
) => SchemaParser.Parser
readonly ast: Union
readonly oinput: Option.Option<unknown>
readonly input: unknown
readonly options: ParseOptions
out: Option.Option<unknown> | undefined
successes: Array<AST>
issues: Array<SchemaIssue.Issue> | undefined
},
items: ReadonlyArray<AST>,
options?: IterateEagerOptions
) =>
| Effect.Effect<void, SchemaIssue.Issue, any>
| undefined
parseUnion(const state: {
ast: this
recur: (ast: AST) => SchemaParser.Parser
oinput: Option.Some<unknown>
input: unknown
out: undefined
successes: never[]
issues:
| Arr.NonEmptyArray<SchemaIssue.Issue>
| undefined
options: ParseOptions
}
state, const candidates: ReadonlyArray<AST>candidates, const concurrency:
| {
concurrency: number
}
| undefined
concurrency ? { ...const concurrency: {
concurrency: number
}
concurrency, orderedStep?: boolean | undefinedorderedStep: true } : var undefinedundefined)
if (!const eff:
| Effect.Effect<void, SchemaIssue.Issue, any>
| undefined
eff) {
return const state: {
ast: this
recur: (ast: AST) => SchemaParser.Parser
oinput: Option.Some<unknown>
input: unknown
out: undefined
successes: never[]
issues:
| Arr.NonEmptyArray<SchemaIssue.Issue>
| undefined
options: ParseOptions
}
state.out: undefinedout
? import EffectEffect.const succeed: <A>(value: A) => Effect<A>Creates an Effect that always succeeds with a given value.
When to use
Use when an effect should complete successfully with a specific value without any errors
or external dependencies.
Example (Creating a successful effect)
import { Effect } from "effect"
// Creating an effect that represents a successful scenario
//
// ┌─── Effect<number, never, never>
// ▼
const success = Effect.succeed(42)
succeed(const state: {
ast: this
recur: (ast: AST) => SchemaParser.Parser
oinput: Option.Some<unknown>
input: unknown
out: undefined
successes: never[]
issues:
| Arr.NonEmptyArray<SchemaIssue.Issue>
| undefined
options: ParseOptions
}
state.out: neverout)
: import EffectEffect.const fail: <E>(
error: E
) => Effect<never, E>
Creates an Effect that represents a recoverable error.
When to use
Use to explicitly signal a recoverable error in an Effect.
Details
The error keeps propagating unless it is handled. You can handle tagged
errors with functions like
catchTag
or
catchTags
.
Example (Creating a failed effect)
import { Data, Effect } from "effect"
class OperationFailedError extends Data.TaggedError("OperationFailedError")<{}> {}
// ┌─── Effect<never, OperationFailedError, never>
// ▼
const failure = Effect.fail(
new OperationFailedError()
)
fail(new import SchemaIssueSchemaIssue.constructor AnyOf(ast: Union, actual: unknown, issues: ReadonlyArray<SchemaIssue.Issue>): SchemaIssue.AnyOfRepresents a schema issue produced when a value does not match any member of a union schema.
When to use
Use when you need to inspect which union members were attempted and why each
failed.
Details
ast is the Union AST node.
actual is the raw input value (plain unknown).
issues contains per-member failures. When empty, the formatter falls
back to the union's expected annotation.
AnyOf(const ast: thisast, const input: unknowninput, const state: {
ast: this
recur: (ast: AST) => SchemaParser.Parser
oinput: Option.Some<unknown>
input: unknown
out: undefined
successes: never[]
issues:
| Arr.NonEmptyArray<SchemaIssue.Issue>
| undefined
options: ParseOptions
}
state.issues: | [SchemaIssue.Issue, ...SchemaIssue.Issue[]]
| undefined
issues ?? []))
}
return import EffectEffect.const flatMap: {
<A, B, E1, R1>(
f: (a: A) => Effect<B, E1, R1>
): <E, R>(
self: Effect<A, E, R>
) => Effect<B, E1 | E, R1 | R>
<A, E, R, B, E1, R1>(
self: Effect<A, E, R>,
f: (a: A) => Effect<B, E1, R1>
): Effect<B, E | E1, R | R1>
}
flatMap(const eff: Effect.Effect<
void,
SchemaIssue.Issue,
any
>
const eff: {
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
eff, (_: void_) => {
return const state: {
ast: this
recur: (ast: AST) => SchemaParser.Parser
oinput: Option.Some<unknown>
input: unknown
out: undefined
successes: never[]
issues:
| Arr.NonEmptyArray<SchemaIssue.Issue>
| undefined
options: ParseOptions
}
state.out: undefinedout
? import EffectEffect.const succeed: <A>(value: A) => Effect<A>Creates an Effect that always succeeds with a given value.
When to use
Use when an effect should complete successfully with a specific value without any errors
or external dependencies.
Example (Creating a successful effect)
import { Effect } from "effect"
// Creating an effect that represents a successful scenario
//
// ┌─── Effect<number, never, never>
// ▼
const success = Effect.succeed(42)
succeed(const state: {
ast: this
recur: (ast: AST) => SchemaParser.Parser
oinput: Option.Some<unknown>
input: unknown
out: undefined
successes: never[]
issues:
| Arr.NonEmptyArray<SchemaIssue.Issue>
| undefined
options: ParseOptions
}
state.out: neverout)
: import EffectEffect.const fail: <E>(
error: E
) => Effect<never, E>
Creates an Effect that represents a recoverable error.
When to use
Use to explicitly signal a recoverable error in an Effect.
Details
The error keeps propagating unless it is handled. You can handle tagged
errors with functions like
catchTag
or
catchTags
.
Example (Creating a failed effect)
import { Data, Effect } from "effect"
class OperationFailedError extends Data.TaggedError("OperationFailedError")<{}> {}
// ┌─── Effect<never, OperationFailedError, never>
// ▼
const failure = Effect.fail(
new OperationFailedError()
)
fail(new import SchemaIssueSchemaIssue.constructor AnyOf(ast: Union, actual: unknown, issues: ReadonlyArray<SchemaIssue.Issue>): SchemaIssue.AnyOfRepresents a schema issue produced when a value does not match any member of a union schema.
When to use
Use when you need to inspect which union members were attempted and why each
failed.
Details
ast is the Union AST node.
actual is the raw input value (plain unknown).
issues contains per-member failures. When empty, the formatter falls
back to the union's expected annotation.
AnyOf(const ast: thisast, const input: unknowninput, const state: {
ast: this
recur: (ast: AST) => SchemaParser.Parser
oinput: Option.Some<unknown>
input: unknown
out: undefined
successes: never[]
issues:
| Arr.NonEmptyArray<SchemaIssue.Issue>
| undefined
options: ParseOptions
}
state.issues: | [SchemaIssue.Issue, ...SchemaIssue.Issue[]]
| undefined
issues ?? []))
})
}
}
private function Union(recur: (ast: AST) => AST, checks: Checks | undefined, encodingChecks: Checks | undefined): Union<AST>_rebuild(recur: (ast: AST) => ASTrecur: (ast: ASTast: type AST =
| Declaration
| Null
| Undefined
| Void
| Never
| Unknown
| Any
| String
| Number
| Boolean
| BigInt
| Symbol
| Literal
| UniqueSymbol
| ObjectKeyword
| Enum
| TemplateLiteral
| Arrays
| Objects
| Union<AST>
| Suspend
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").
AST) => type AST =
| Declaration
| Null
| Undefined
| Void
| Never
| Unknown
| Any
| String
| Number
| Boolean
| BigInt
| Symbol
| Literal
| UniqueSymbol
| ObjectKeyword
| Enum
| TemplateLiteral
| Arrays
| Objects
| Union<AST>
| Suspend
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").
AST, checks: Checks | undefinedchecks: type Checks = readonly [
Check<any>,
...Check<any>[]
]
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.
Checks | undefined, encodingChecks: Checks | undefinedencodingChecks: type Checks = readonly [
Check<any>,
...Check<any>[]
]
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.
Checks | undefined) {
const const types: ReadonlyArray<AST>types = function mapOrSame<AST>(as: readonly AST[], f: (a: AST) => AST): readonly AST[] (+1 overload)Maps over the array but will return the original array if no changes occur.
mapOrSame(this.Union<A extends AST = AST>.types: readonly A[]types, recur: (ast: AST) => ASTrecur)
return const types: ReadonlyArray<AST>types === this.Union<A extends AST = AST>.types: readonly A[]types && checks: Checks | undefinedchecks === this.Base.checks: Checks | undefinedchecks && encodingChecks: Checks | undefinedencodingChecks === this.Union<A extends AST = AST>.encodingChecks: Checks | undefinedencodingChecks ?
this :
new constructor Union<AST>(types: readonly AST[], mode: "anyOf" | "oneOf", annotations?: Schema.Annotations.Annotations, checks?: Checks, encoding?: Encoding, context?: Context, encodingChecks?: Checks): Union<AST>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"
}
Union(const types: ReadonlyArray<AST>types, this.Union<A extends AST = AST>.mode: "anyOf" | "oneOf"mode, this.Base.annotations: Schema.Annotations.Annotations | undefinedannotations, checks: Checks | undefinedchecks, var undefinedundefined, this.Base.context: Context | undefinedcontext, encodingChecks: Checks | undefinedencodingChecks)
}
/** @internal */
function Union(recur: (ast: AST) => AST): Union<AST>recur(recur: (ast: AST) => ASTrecur: (ast: ASTast: type AST =
| Declaration
| Null
| Undefined
| Void
| Never
| Unknown
| Any
| String
| Number
| Boolean
| BigInt
| Symbol
| Literal
| UniqueSymbol
| ObjectKeyword
| Enum
| TemplateLiteral
| Arrays
| Objects
| Union<AST>
| Suspend
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").
AST) => type AST =
| Declaration
| Null
| Undefined
| Void
| Never
| Unknown
| Any
| String
| Number
| Boolean
| BigInt
| Symbol
| Literal
| UniqueSymbol
| ObjectKeyword
| Enum
| TemplateLiteral
| Arrays
| Objects
| Union<AST>
| Suspend
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").
AST) {
return this.function Union(recur: (ast: AST) => AST, checks: Checks | undefined, encodingChecks: Checks | undefined): Union<AST>_rebuild(recur: (ast: AST) => ASTrecur, this.Base.checks: Checks | undefinedchecks, this.Union<A extends AST = AST>.encodingChecks: Checks | undefinedencodingChecks)
}
/** @internal */
function Union(recur: (ast: AST) => AST): Union<AST>flip(recur: (ast: AST) => ASTrecur: (ast: ASTast: type AST =
| Declaration
| Null
| Undefined
| Void
| Never
| Unknown
| Any
| String
| Number
| Boolean
| BigInt
| Symbol
| Literal
| UniqueSymbol
| ObjectKeyword
| Enum
| TemplateLiteral
| Arrays
| Objects
| Union<AST>
| Suspend
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").
AST) => type AST =
| Declaration
| Null
| Undefined
| Void
| Never
| Unknown
| Any
| String
| Number
| Boolean
| BigInt
| Symbol
| Literal
| UniqueSymbol
| ObjectKeyword
| Enum
| TemplateLiteral
| Arrays
| Objects
| Union<AST>
| Suspend
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").
AST) {
return this.function Union(recur: (ast: AST) => AST, checks: Checks | undefined, encodingChecks: Checks | undefined): Union<AST>_rebuild(recur: (ast: AST) => ASTrecur, this.Union<A extends AST = AST>.encodingChecks: Checks | undefinedencodingChecks, this.Base.checks: Checks | undefinedchecks)
}
/** @internal */
function Union(s: string, options: ParseOptions): LiteralValue | undefinedmatchPart(s: strings: string, options: ParseOptions(parameter) options: {
errors: "first" | "all" | undefined;
onExcessProperty: "ignore" | "error" | "preserve" | undefined;
propertyOrder: "none" | "original" | undefined;
disableChecks: boolean | undefined;
concurrency: number | "unbounded" | undefined;
}
options: ParseOptions): type LiteralValue =
| string
| number
| bigint
| boolean
The set of primitive types that can appear as a
Literal
value.
LiteralValue | undefined {
for (const const type: A extends AST = ASTtype of this.Union<A extends AST = AST>.types: readonly A[]types) {
const const out: LiteralValue | undefinedout = (const type: ASTtype as type TemplateLiteralPart =
| String
| Number
| BigInt
| Literal
| TemplateLiteral
| Union<TemplateLiteralPart>
TemplateLiteralPart).function matchPart(s: string, options: ParseOptions): LiteralValue | undefinedmatchPart(s: strings, options: ParseOptions(parameter) options: {
errors: "first" | "all" | undefined;
onExcessProperty: "ignore" | "error" | "preserve" | undefined;
propertyOrder: "none" | "original" | undefined;
disableChecks: boolean | undefined;
concurrency: number | "unbounded" | undefined;
}
options)
if (const out: LiteralValue | undefinedout !== var undefinedundefined) return const out: LiteralValueout
}
return var undefinedundefined
}
/** @internal */
function Union(getExpected: (ast: AST) => string): stringgetExpected(getExpected: (ast: AST) => stringgetExpected: (ast: ASTast: type AST =
| Declaration
| Null
| Undefined
| Void
| Never
| Unknown
| Any
| String
| Number
| Boolean
| BigInt
| Symbol
| Literal
| UniqueSymbol
| ObjectKeyword
| Enum
| TemplateLiteral
| Arrays
| Objects
| Union<AST>
| Suspend
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").
AST) => string): string {
const const expected: unknownexpected = this.Base.annotations: Schema.Annotations.Annotations | undefinedannotations?.unknownexpected
if (typeof const expected: unknownexpected === "string") return const expected: stringexpected
if (this.Union<A extends AST = AST>.types: readonly A[]types.ReadonlyArray<A>.length: numberGets the length of the array. This is a number one higher than the highest element defined in an array.
length === 0) return "never"
const const types: string[]types = this.Union<A extends AST = AST>.types: readonly A[]types.ReadonlyArray<A>.map<string>(callbackfn: (value: A, index: number, array: readonly A[]) => string, thisArg?: any): string[]Calls a defined callback function on each element of an array, and returns an array that contains the results.
map((type: A extends AST = ASTtype) => {
const const encoded: ASTencoded = const toEncoded: (ast: AST) => ASTReturns 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"
toEncoded(type: ASTtype)
switch (const encoded: ASTencoded._tag: | "Declaration"
| "Null"
| "Undefined"
| "Void"
| "Never"
| "Unknown"
| "Any"
| "String"
| "Number"
| "Boolean"
| "BigInt"
| "Symbol"
| "Literal"
| "UniqueSymbol"
| "ObjectKeyword"
| "Enum"
| "TemplateLiteral"
| "Arrays"
| "Objects"
| "Union"
| "Suspend"
_tag) {
case "Arrays": {
const const literals: Array<Literal>literals = const encoded: Arraysconst encoded: {
_tag: 'Arrays';
isMutable: boolean;
elements: ReadonlyArray<AST>;
rest: ReadonlyArray<AST>;
encodingChecks: Checks | undefined;
getParser: (recur: (ast: AST) => SchemaParser.Parser) => SchemaParser.Parser;
_rebuild: (recur: (ast: AST) => AST, checks: Checks | undefined, encodingChecks: Checks | undefined) => Arrays;
recur: (recur: (ast: AST) => AST) => Arrays;
flip: (recur: (ast: AST) => AST) => Arrays;
getExpected: () => string;
annotations: Schema.Annotations.Annotations | undefined;
checks: Checks | undefined;
encoding: Encoding | undefined;
context: Context | undefined;
toString: () => string;
}
encoded.Arrays.elements: ReadonlyArray<AST>elements.ReadonlyArray<AST>.filter<Literal>(predicate: (value: AST, index: number, array: readonly AST[]) => value is Literal, thisArg?: any): Literal[] (+1 overload)Returns the elements of an array that meet the condition specified in a callback function.
filter(const isLiteral: (
ast: AST
) => ast is Literal
isLiteral)
if (const literals: Array<Literal>literals.Array<Literal>.length: numberGets or sets the length of the array. This is a number one higher than the highest index in the array.
length > 0) {
return `${function formatIsMutable(
isMutable: boolean | undefined
): string
formatIsMutable(const encoded: Arraysconst encoded: {
_tag: 'Arrays';
isMutable: boolean;
elements: ReadonlyArray<AST>;
rest: ReadonlyArray<AST>;
encodingChecks: Checks | undefined;
getParser: (recur: (ast: AST) => SchemaParser.Parser) => SchemaParser.Parser;
_rebuild: (recur: (ast: AST) => AST, checks: Checks | undefined, encodingChecks: Checks | undefined) => Arrays;
recur: (recur: (ast: AST) => AST) => Arrays;
flip: (recur: (ast: AST) => AST) => Arrays;
getExpected: () => string;
annotations: Schema.Annotations.Annotations | undefined;
checks: Checks | undefined;
encoding: Encoding | undefined;
context: Context | undefined;
toString: () => string;
}
encoded.Arrays.isMutable: booleanisMutable)}[ ${
const literals: Array<Literal>literals.Array<Literal>.map<string>(callbackfn: (value: Literal, index: number, array: Literal[]) => string, thisArg?: any): string[]Calls a defined callback function on each element of an array, and returns an array that contains the results.
map((e: Literal(parameter) e: {
_tag: 'Literal';
literal: LiteralValue;
getParser: () => SchemaParser.Parser;
matchPart: (s: string, _options: ParseOptions) => LiteralValue | undefined;
toCodecJson: () => AST;
toCodecStringTree: () => AST;
getExpected: () => string;
annotations: Schema.Annotations.Annotations | undefined;
checks: Checks | undefined;
encoding: Encoding | undefined;
context: Context | undefined;
toString: () => string;
}
e) => getExpected: (ast: AST) => stringgetExpected(e: Literal(parameter) e: {
_tag: 'Literal';
literal: LiteralValue;
getParser: () => SchemaParser.Parser;
matchPart: (s: string, _options: ParseOptions) => LiteralValue | undefined;
toCodecJson: () => AST;
toCodecStringTree: () => AST;
getExpected: () => string;
annotations: Schema.Annotations.Annotations | undefined;
checks: Checks | undefined;
encoding: Encoding | undefined;
context: Context | undefined;
toString: () => string;
}
e) + function formatIsOptional(
isOptional: boolean | undefined
): string
formatIsOptional(e: Literal(parameter) e: {
_tag: 'Literal';
literal: LiteralValue;
getParser: () => SchemaParser.Parser;
matchPart: (s: string, _options: ParseOptions) => LiteralValue | undefined;
toCodecJson: () => AST;
toCodecStringTree: () => AST;
getExpected: () => string;
annotations: Schema.Annotations.Annotations | undefined;
checks: Checks | undefined;
encoding: Encoding | undefined;
context: Context | undefined;
toString: () => string;
}
e.Base.context: Context | undefinedcontext?.Context.isOptional: boolean | undefinedisOptional)).Array<string>.join(separator?: string): stringAdds all the elements of an array into a string, separated by the specified separator string.
join(", ")
}, ... ]`
}
break
}
case "Objects": {
const const literals: Array<PropertySignature>literals = const encoded: Objectsconst encoded: {
_tag: 'Objects';
propertySignatures: ReadonlyArray<PropertySignature>;
indexSignatures: ReadonlyArray<IndexSignature>;
encodingChecks: Checks | undefined;
getParser: (recur: (ast: AST) => SchemaParser.Parser) => SchemaParser.Parser;
_rebuild: (recur: (ast: AST) => AST, recurParameter: (ast: AST) => AST, flipMerge: boolean, checks: Checks | undefined, encodingChecks: Checks | undefined) => Objects;
flip: (recur: (ast: AST) => AST) => AST;
recur: (recur: (ast: AST) => AST, recurParameter?: (ast: AST) => AST) => AST;
getExpected: () => string;
annotations: Schema.Annotations.Annotations | undefined;
checks: Checks | undefined;
encoding: Encoding | undefined;
context: Context | undefined;
toString: () => string;
}
encoded.Objects.propertySignatures: ReadonlyArray<PropertySignature>propertySignatures.ReadonlyArray<PropertySignature>.filter(predicate: (value: PropertySignature, index: number, array: readonly PropertySignature[]) => unknown, thisArg?: any): PropertySignature[] (+1 overload)Returns the elements of an array that meet the condition specified in a callback function.
filter((ps: PropertySignature(parameter) ps: {
name: PropertyKey;
type: AST;
}
ps) => const isLiteral: (
ast: AST
) => ast is Literal
isLiteral(ps: PropertySignature(parameter) ps: {
name: PropertyKey;
type: AST;
}
ps.PropertySignature.type: ASTtype))
if (const literals: Array<PropertySignature>literals.Array<T>.length: numberGets or sets the length of the array. This is a number one higher than the highest index in the array.
length > 0) {
return `{ ${
const literals: Array<PropertySignature>literals.Array<PropertySignature>.map<string>(callbackfn: (value: PropertySignature, index: number, array: PropertySignature[]) => string, thisArg?: any): string[]Calls a defined callback function on each element of an array, and returns an array that contains the results.
map((ps: PropertySignature(parameter) ps: {
name: PropertyKey;
type: AST;
}
ps) =>
`${function formatIsMutable(
isMutable: boolean | undefined
): string
formatIsMutable(ps: PropertySignature(parameter) ps: {
name: PropertyKey;
type: AST;
}
ps.PropertySignature.type: ASTtype.Base.context: Context | undefinedcontext?.Context.isMutable: boolean | undefinedisMutable)}${function formatPropertyKey(name: PropertyKey): stringformatPropertyKey(ps: PropertySignature(parameter) ps: {
name: PropertyKey;
type: AST;
}
ps.PropertySignature.name: PropertyKeyname)}${
function formatIsOptional(
isOptional: boolean | undefined
): string
formatIsOptional(ps: PropertySignature(parameter) ps: {
name: PropertyKey;
type: AST;
}
ps.PropertySignature.type: ASTtype.Base.context: Context | undefinedcontext?.Context.isOptional: boolean | undefinedisOptional)
}: ${getExpected: (ast: AST) => stringgetExpected(ps: PropertySignature(parameter) ps: {
name: PropertyKey;
type: AST;
}
ps.PropertySignature.type: ASTtype)}`
).Array<string>.join(separator?: string): stringAdds all the elements of an array into a string, separated by the specified separator string.
join(", ")
}, ... }`
}
break
}
}
return getExpected: (ast: AST) => stringgetExpected(const encoded: ASTencoded)
})
return var Array: ArrayConstructorArray.ArrayConstructor.from<string>(iterable: Iterable<string> | ArrayLike<string>): string[] (+3 overloads)Creates an array from an iterable object.
from(new var Set: SetConstructor
new <string>(iterable?: Iterable<string> | null | undefined) => Set<string> (+1 overload)
Set(const types: string[]types)).Array<string>.join(separator?: string): stringAdds all the elements of an array into a string, separated by the specified separator string.
join(" | ")
}
}