Literals<L>Creates a union schema from an array of literal values.
Example (Defining status codes)
import { Schema } from "effect"
const schema = Schema.Literals(["active", "inactive", "pending"])
// accepts "active", "inactive", or "pending"export interface interface Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>Creates a union schema from an array of literal values.
Example (Defining status codes)
import { Schema } from "effect"
const schema = Schema.Literals(["active", "inactive", "pending"])
// accepts "active", "inactive", or "pending"
Type-level representation returned by
Literals
.
Literals<function (type parameter) L in Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>L extends interface ReadonlyArray<T>ReadonlyArray<import SchemaASTSchemaAST.type LiteralValue =
| string
| number
| bigint
| boolean
The set of primitive types that can appear as a
Literal
value.
LiteralValue>>
extends interface Bottom<out T, out E, out RD, out RE, out Ast extends SchemaAST.AST, out Rebuild extends Top, out TypeMakeIn = T, out Iso = T, in out TypeParameters extends ReadonlyArray<Constraint> = readonly [], out TypeMake = TypeMakeIn, out TypeMutability extends Mutability = "readonly", out TypeOptionality extends Optionality = "required", out TypeConstructorDefault extends ConstructorDefault = "no-default", out EncodedMutability extends Mutability = "readonly", out EncodedOptionality extends Optionality = "required">The fully-parameterized base interface for all schemas. Exposes all 14 type
parameters controlling type inference, mutability, optionality, services, and
transformation behavior.
When to use
Use when you are writing advanced generic schema utilities or performing
schema introspection.
Bottom<function (type parameter) L in Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>L[number], function (type parameter) L in Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>L[number], never, never, import SchemaASTSchemaAST.class Union<A extends SchemaAST.AST = SchemaAST.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<import SchemaASTSchemaAST.class Literalclass Literal {
_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;
}
AST node matching an exact primitive value (string, number, boolean, or
bigint).
Details
Parsing succeeds only when the input is strictly equal (===) to the
stored literal. Numeric literals must be finite — Infinity, -Infinity,
and NaN are rejected at construction time.
Example (Creating a literal AST)
import { SchemaAST } from "effect"
const ast = new SchemaAST.Literal("active")
console.log(ast.literal) // "active"
Literal>, interface Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>Creates a union schema from an array of literal values.
Example (Defining status codes)
import { Schema } from "effect"
const schema = Schema.Literals(["active", "inactive", "pending"])
// accepts "active", "inactive", or "pending"
Type-level representation returned by
Literals
.
Literals<function (type parameter) L in Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>L>>
{
readonly Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>.literals: L extends ReadonlyArray<SchemaAST.LiteralValue>literals: function (type parameter) L in Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>L
readonly Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>.members: { readonly [K in keyof L]: Literal<L[K]>; }members: { readonly [function (type parameter) KK in keyof function (type parameter) L in Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>L]: interface Literal<L extends SchemaAST.LiteralValue>Creates a schema for a single literal value (string, number, bigint, boolean, or null).
Example (Defining a string literal)
import { Schema } from "effect"
const schema = Schema.Literal("hello")
// Type: Schema.Literal<"hello">
Type-level representation returned by
Literal
.
Literal<function (type parameter) L in Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>L[function (type parameter) KK]> }
/**
* Map over the members of the union.
*/
Literals<To extends ReadonlyArray<Constraint>>(f: (members: this['members']) => To): Union<Simplify<Readonly<To>>>Map over the members of the union.
mapMembers<function (type parameter) To in Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>.mapMembers<To extends ReadonlyArray<Constraint>>(f: (members: this["members"]) => To): Union<Simplify<Readonly<To>>>To extends interface ReadonlyArray<T>ReadonlyArray<Constraint>>(f: (members: this["members"]) => Tof: (members: this["members"]members: this["members"]) => function (type parameter) To in Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>.mapMembers<To extends ReadonlyArray<Constraint>>(f: (members: this["members"]) => To): Union<Simplify<Readonly<To>>>To): interface Union<Members extends ReadonlyArray<Constraint>>Creates a union schema from an array of member schemas. Members are tested in
order; the first match is returned.
Details
Optionally, specify mode:
"anyOf" (default) — matches if any member matches.
"oneOf" — matches if exactly one member matches.
Example (Defining a string or number union)
import { Schema } from "effect"
const schema = Schema.Union([Schema.String, Schema.Number])
Schema.decodeUnknownSync(schema)("hello") // "hello"
Schema.decodeUnknownSync(schema)(42) // 42
Type-level representation returned by
Union
.
Union<type Simplify<T> = { [K in keyof T]: T[K]; }Flattens intersection types into a single object type for readability.
When to use
Use when hovering over a type shows A & B & C instead of the merged shape.
Details
This helper is purely cosmetic at the type level and has no runtime effect.
It preserves readonly modifiers; use
Mutable
to strip them.
Example (Flattening an intersection)
import type { Struct } from "effect"
type Original = { a: string } & { b: number }
// Without Simplify, the type displays as `{ a: string } & { b: number }`
type Simplified = Struct.Simplify<Original>
// { a: string; b: number }
Simplify<type Readonly<T> = {
readonly [P in keyof T]: T[P]
}
Make all properties in T readonly
Readonly<function (type parameter) To in Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>.mapMembers<To extends ReadonlyArray<Constraint>>(f: (members: this["members"]) => To): Union<Simplify<Readonly<To>>>To>>>
Literals<L2 extends ReadonlyArray<L[number]>>(literals: L2): Literals<L2>pick<const function (type parameter) L2 in Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>.pick<const L2 extends ReadonlyArray<L[number]>>(literals: L2): Literals<L2>L2 extends interface ReadonlyArray<T>ReadonlyArray<function (type parameter) L in Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>L[number]>>(literals: const L2 extends ReadonlyArray<L[number]>literals: function (type parameter) L2 in Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>.pick<const L2 extends ReadonlyArray<L[number]>>(literals: L2): Literals<L2>L2): interface Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>Creates a union schema from an array of literal values.
Example (Defining status codes)
import { Schema } from "effect"
const schema = Schema.Literals(["active", "inactive", "pending"])
// accepts "active", "inactive", or "pending"
Type-level representation returned by
Literals
.
Literals<function (type parameter) L2 in Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>.pick<const L2 extends ReadonlyArray<L[number]>>(literals: L2): Literals<L2>L2>
Literals<L2 extends { readonly [I in keyof L]: SchemaAST.LiteralValue; }>(to: L2): Union<{ [I in keyof L]: decodeTo<Literal<L2[I]>, Literal<L[I]>>; }>transform<const function (type parameter) L2 in Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>.transform<const L2 extends { readonly [I in keyof L]: SchemaAST.LiteralValue; }>(to: L2): Union<{ [I in keyof L]: decodeTo<Literal<L2[I]>, Literal<L[I]>>; }>L2 extends { readonly [function (type parameter) II in keyof function (type parameter) L in Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>L]: import SchemaASTSchemaAST.type LiteralValue =
| string
| number
| bigint
| boolean
The set of primitive types that can appear as a
Literal
value.
LiteralValue }>(
to: const L2 extends { readonly [I in keyof L]: SchemaAST.LiteralValue; }to: function (type parameter) L2 in Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>.transform<const L2 extends { readonly [I in keyof L]: SchemaAST.LiteralValue; }>(to: L2): Union<{ [I in keyof L]: decodeTo<Literal<L2[I]>, Literal<L[I]>>; }>L2
): interface Union<Members extends ReadonlyArray<Constraint>>Creates a union schema from an array of member schemas. Members are tested in
order; the first match is returned.
Details
Optionally, specify mode:
"anyOf" (default) — matches if any member matches.
"oneOf" — matches if exactly one member matches.
Example (Defining a string or number union)
import { Schema } from "effect"
const schema = Schema.Union([Schema.String, Schema.Number])
Schema.decodeUnknownSync(schema)("hello") // "hello"
Schema.decodeUnknownSync(schema)(42) // 42
Type-level representation returned by
Union
.
Union<{ [function (type parameter) II in keyof function (type parameter) L in Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>L]: interface decodeTo<To extends Constraint, From extends Constraint, RD = never, RE = never>Creates a schema that transforms from a source schema to a target schema.
When to use
Use when decoding should change the schema's decoded type or encoded shape,
with an optional custom bidirectional transformation.
Details
Call it with the target schema to and then pipe the source schema from
into the returned function. The resulting schema decodes from
From["Encoded"] to To["Type"] and encodes from To["Type"] back to
From["Encoded"].
When no transformation is provided, SchemaTransformation.passthrough() is
used, so From["Type"] must already be compatible with To["Encoded"].
The resulting schema combines decoding and encoding services from both
schemas and any custom transformation.
Gotchas
In a custom transformation, decode maps From["Type"] to To["Encoded"]
and is used on the encoding path, while encode maps To["Encoded"] to
From["Type"] and is used on the decoding path.
Example (Transforming strings to numbers with a schema transformation)
import { Schema, SchemaGetter } from "effect"
const NumberFromString = Schema.String.pipe(
Schema.decodeTo(
Schema.Number,
{
decode: SchemaGetter.transform((s) => Number(s)),
encode: SchemaGetter.transform((n) => String(n))
}
)
)
const result = Schema.decodeUnknownSync(NumberFromString)("123")
// result: 123
Type-level representation returned by
decodeTo
.
decodeTo<interface Literal<L extends SchemaAST.LiteralValue>Creates a schema for a single literal value (string, number, bigint, boolean, or null).
Example (Defining a string literal)
import { Schema } from "effect"
const schema = Schema.Literal("hello")
// Type: Schema.Literal<"hello">
Type-level representation returned by
Literal
.
Literal<function (type parameter) L2 in Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>.transform<const L2 extends { readonly [I in keyof L]: SchemaAST.LiteralValue; }>(to: L2): Union<{ [I in keyof L]: decodeTo<Literal<L2[I]>, Literal<L[I]>>; }>L2[function (type parameter) II]>, interface Literal<L extends SchemaAST.LiteralValue>Creates a schema for a single literal value (string, number, bigint, boolean, or null).
Example (Defining a string literal)
import { Schema } from "effect"
const schema = Schema.Literal("hello")
// Type: Schema.Literal<"hello">
Type-level representation returned by
Literal
.
Literal<function (type parameter) L in Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>L[function (type parameter) II]>> }>
}
/**
* Creates a union schema from an array of literal values.
*
* **Example** (Defining status codes)
*
* ```ts
* import { Schema } from "effect"
*
* const schema = Schema.Literals(["active", "inactive", "pending"])
* // accepts "active", "inactive", or "pending"
* ```
*
* @see {@link Literal} for a schema that represents a single literal.
* @category constructors
* @since 4.0.0
*/
export function function Literals<
L extends ReadonlyArray<SchemaAST.LiteralValue>
>(literals: L): Literals<L>
Creates a union schema from an array of literal values.
Example (Defining status codes)
import { Schema } from "effect"
const schema = Schema.Literals(["active", "inactive", "pending"])
// accepts "active", "inactive", or "pending"
Literals<const function (type parameter) L in Literals<const L extends ReadonlyArray<SchemaAST.LiteralValue>>(literals: L): Literals<L>L extends interface ReadonlyArray<T>ReadonlyArray<import SchemaASTSchemaAST.type LiteralValue =
| string
| number
| bigint
| boolean
The set of primitive types that can appear as a
Literal
value.
LiteralValue>>(literals: const L extends ReadonlyArray<SchemaAST.LiteralValue>literals: function (type parameter) L in Literals<const L extends ReadonlyArray<SchemaAST.LiteralValue>>(literals: L): Literals<L>L): interface Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>Creates a union schema from an array of literal values.
Example (Defining status codes)
import { Schema } from "effect"
const schema = Schema.Literals(["active", "inactive", "pending"])
// accepts "active", "inactive", or "pending"
Type-level representation returned by
Literals
.
Literals<function (type parameter) L in Literals<const L extends ReadonlyArray<SchemaAST.LiteralValue>>(literals: L): Literals<L>L> {
const const members: {
readonly [K in keyof L]: Literal<L[K]>
}
members = literals: const L extends ReadonlyArray<SchemaAST.LiteralValue>literals.ReadonlyArray<LiteralValue>.map<Literal<SchemaAST.LiteralValue>>(callbackfn: (value: SchemaAST.LiteralValue, index: number, array: readonly SchemaAST.LiteralValue[]) => Literal<SchemaAST.LiteralValue>, thisArg?: any): Literal<SchemaAST.LiteralValue>[]Calls a defined callback function on each element of an array, and returns an array that contains the results.
map(function Literal<
L extends SchemaAST.LiteralValue
>(literal: L): Literal<L>
Creates a schema for a single literal value (string, number, bigint, boolean, or null).
Example (Defining a string literal)
import { Schema } from "effect"
const schema = Schema.Literal("hello")
// Type: Schema.Literal<"hello">
Literal) as { readonly [function (type parameter) KK in keyof function (type parameter) L in Literals<const L extends ReadonlyArray<SchemaAST.LiteralValue>>(literals: L): Literals<L>L]: interface Literal<L extends SchemaAST.LiteralValue>Creates a schema for a single literal value (string, number, bigint, boolean, or null).
Example (Defining a string literal)
import { Schema } from "effect"
const schema = Schema.Literal("hello")
// Type: Schema.Literal<"hello">
Type-level representation returned by
Literal
.
Literal<function (type parameter) L in Literals<const L extends ReadonlyArray<SchemaAST.LiteralValue>>(literals: L): Literals<L>L[function (type parameter) KK]> }
return const make: <S extends Constraint>(
ast: S["ast"],
options?: object
) => S
Creates a schema from an AST (Abstract Syntax Tree) node.
Details
This is the fundamental constructor for all schemas in the Effect Schema
library. It takes an AST node and wraps it in a fully-typed schema that
preserves all type information and provides the complete schema API.
The make function is used internally to create all primitive schemas like
String, Number, Boolean, etc., as well as more complex schemas. It's
the bridge between the untyped AST representation and the strongly-typed
schema.
make(import SchemaASTSchemaAST.function union<
Members extends ReadonlyArray<{
readonly ast: AST
}>
>(
members: Members,
mode: "anyOf" | "oneOf",
checks: Checks | undefined
): Union<Members[number]["ast"]>
union(const members: {
readonly [K in keyof L]: Literal<L[K]>
}
members, "anyOf", var undefinedundefined), {
literals: const L extends ReadonlyArray<SchemaAST.LiteralValue>literals,
members: {
readonly [K in keyof L]: Literal<L[K]>
}
members,
mapMembers<To extends ReadonlyArray<Constraint>>(this: Literals<L>, f: (members: Literals<L>['members']) => To): Union<Simplify<Readonly<To>>>mapMembers<function (type parameter) To in mapMembers<To extends ReadonlyArray<Constraint>>(this: Literals<L>, f: (members: Literals<L>["members"]) => To): Union<Simplify<Readonly<To>>>To extends interface ReadonlyArray<T>ReadonlyArray<Constraint>>(
this: Literals<L>(parameter) this: {
literals: L;
members: { readonly [K in keyof L]: Literal<L[K]>; };
mapMembers: (f: (members: { readonly [K in keyof L]: Literal<L[K]>; }) => To) => Union<{ [K in keyof Readonly<To>]: Readonly<To>[K]; }>;
pick: (literals: L2) => Literals<L2>;
transform: (to: L2) => Union<{ [I in keyof L]: decodeTo<Literal<L2[I]>, Literal<L[I]>, never, never>; }>;
Rebuild: Rebuild;
Iso: Iso;
ast: Ast;
Type: T;
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
annotate: (annotations: Annotations.Bottom<L[number], readonly []>) => Literals<L>;
annotateKey: (annotations: Annotations.Key<L[number]>) => Literals<L>;
check: (checks_0: SchemaAST.Check<L[number]>, ...checks: Array<SchemaAST.Check<L[number]>>) => Literals<L>;
rebuild: (ast: SchemaAST.Union<SchemaAST.Literal>) => Literals<L>;
make: (input: L[number], options?: MakeOptions) => L[number];
makeOption: (input: L[number], options?: MakeOptions) => Option_.Option<L[number]>;
makeEffect: (input: L[number], options?: MakeOptions) => Effect.Effect<L[number], SchemaError, never>;
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; <…;
}
this: interface Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>Creates a union schema from an array of literal values.
Example (Defining status codes)
import { Schema } from "effect"
const schema = Schema.Literals(["active", "inactive", "pending"])
// accepts "active", "inactive", or "pending"
Type-level representation returned by
Literals
.
Literals<function (type parameter) L in Literals<const L extends ReadonlyArray<SchemaAST.LiteralValue>>(literals: L): Literals<L>L>,
f: (members: Literals<L>["members"]) => Tof: (members: Literals<L>["members"]members: interface Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>Creates a union schema from an array of literal values.
Example (Defining status codes)
import { Schema } from "effect"
const schema = Schema.Literals(["active", "inactive", "pending"])
// accepts "active", "inactive", or "pending"
Type-level representation returned by
Literals
.
Literals<function (type parameter) L in Literals<const L extends ReadonlyArray<SchemaAST.LiteralValue>>(literals: L): Literals<L>L>["members"]) => function (type parameter) To in mapMembers<To extends ReadonlyArray<Constraint>>(this: Literals<L>, f: (members: Literals<L>["members"]) => To): Union<Simplify<Readonly<To>>>To
): interface Union<Members extends ReadonlyArray<Constraint>>Creates a union schema from an array of member schemas. Members are tested in
order; the first match is returned.
Details
Optionally, specify mode:
"anyOf" (default) — matches if any member matches.
"oneOf" — matches if exactly one member matches.
Example (Defining a string or number union)
import { Schema } from "effect"
const schema = Schema.Union([Schema.String, Schema.Number])
Schema.decodeUnknownSync(schema)("hello") // "hello"
Schema.decodeUnknownSync(schema)(42) // 42
Type-level representation returned by
Union
.
Union<type Simplify<T> = { [K in keyof T]: T[K]; }Flattens intersection types into a single object type for readability.
When to use
Use when hovering over a type shows A & B & C instead of the merged shape.
Details
This helper is purely cosmetic at the type level and has no runtime effect.
It preserves readonly modifiers; use
Mutable
to strip them.
Example (Flattening an intersection)
import type { Struct } from "effect"
type Original = { a: string } & { b: number }
// Without Simplify, the type displays as `{ a: string } & { b: number }`
type Simplified = Struct.Simplify<Original>
// { a: string; b: number }
Simplify<type Readonly<T> = {
readonly [P in keyof T]: T[P]
}
Make all properties in T readonly
Readonly<function (type parameter) To in mapMembers<To extends ReadonlyArray<Constraint>>(this: Literals<L>, f: (members: Literals<L>["members"]) => To): Union<Simplify<Readonly<To>>>To>>> {
return function Union<
Members extends ReadonlyArray<Constraint>
>(
members: Members,
options?: { mode?: "anyOf" | "oneOf" }
): Union<Members>
Creates a union schema from an array of member schemas. Members are tested in
order; the first match is returned.
Details
Optionally, specify mode:
"anyOf" (default) — matches if any member matches.
"oneOf" — matches if exactly one member matches.
Example (Defining a string or number union)
import { Schema } from "effect"
const schema = Schema.Union([Schema.String, Schema.Number])
Schema.decodeUnknownSync(schema)("hello") // "hello"
Schema.decodeUnknownSync(schema)(42) // 42
Union(f: (members: Literals<L>["members"]) => Tof(this.Literals<L>.members: { readonly [K in keyof L]: Literal<L[K]>; }members))
},
pick<L2 extends ReadonlyArray<L[number]>>(literals: L2): Literals<L2>pick<const function (type parameter) L2 in pick<const L2 extends ReadonlyArray<L[number]>>(literals: L2): Literals<L2>L2 extends interface ReadonlyArray<T>ReadonlyArray<function (type parameter) L in Literals<const L extends ReadonlyArray<SchemaAST.LiteralValue>>(literals: L): Literals<L>L[number]>>(literals: const L2 extends ReadonlyArray<L[number]>literals: function (type parameter) L2 in pick<const L2 extends ReadonlyArray<L[number]>>(literals: L2): Literals<L2>L2): interface Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>>Creates a union schema from an array of literal values.
Example (Defining status codes)
import { Schema } from "effect"
const schema = Schema.Literals(["active", "inactive", "pending"])
// accepts "active", "inactive", or "pending"
Type-level representation returned by
Literals
.
Literals<function (type parameter) L2 in pick<const L2 extends ReadonlyArray<L[number]>>(literals: L2): Literals<L2>L2> {
return function Literals<
L extends ReadonlyArray<SchemaAST.LiteralValue>
>(literals: L): Literals<L>
Creates a union schema from an array of literal values.
Example (Defining status codes)
import { Schema } from "effect"
const schema = Schema.Literals(["active", "inactive", "pending"])
// accepts "active", "inactive", or "pending"
Literals(literals: const L2 extends ReadonlyArray<L[number]>literals)
},
transform<L2 extends { readonly [I in keyof L]: SchemaAST.LiteralValue; }>(to: L2): Union<{ [I in keyof L]: decodeTo<Literal<L2[I]>, Literal<L[I]>>; }>transform<const function (type parameter) L2 in transform<const L2 extends { readonly [I in keyof L]: SchemaAST.LiteralValue; }>(to: L2): Union<{ [I in keyof L]: decodeTo<Literal<L2[I]>, Literal<L[I]>>; }>L2 extends { readonly [function (type parameter) II in keyof function (type parameter) L in Literals<const L extends ReadonlyArray<SchemaAST.LiteralValue>>(literals: L): Literals<L>L]: import SchemaASTSchemaAST.type LiteralValue =
| string
| number
| bigint
| boolean
The set of primitive types that can appear as a
Literal
value.
LiteralValue }>(
to: const L2 extends { readonly [I in keyof L]: SchemaAST.LiteralValue; }to: function (type parameter) L2 in transform<const L2 extends { readonly [I in keyof L]: SchemaAST.LiteralValue; }>(to: L2): Union<{ [I in keyof L]: decodeTo<Literal<L2[I]>, Literal<L[I]>>; }>L2
): interface Union<Members extends ReadonlyArray<Constraint>>Creates a union schema from an array of member schemas. Members are tested in
order; the first match is returned.
Details
Optionally, specify mode:
"anyOf" (default) — matches if any member matches.
"oneOf" — matches if exactly one member matches.
Example (Defining a string or number union)
import { Schema } from "effect"
const schema = Schema.Union([Schema.String, Schema.Number])
Schema.decodeUnknownSync(schema)("hello") // "hello"
Schema.decodeUnknownSync(schema)(42) // 42
Type-level representation returned by
Union
.
Union<{ [function (type parameter) II in keyof function (type parameter) L in Literals<const L extends ReadonlyArray<SchemaAST.LiteralValue>>(literals: L): Literals<L>L]: interface decodeTo<To extends Constraint, From extends Constraint, RD = never, RE = never>Creates a schema that transforms from a source schema to a target schema.
When to use
Use when decoding should change the schema's decoded type or encoded shape,
with an optional custom bidirectional transformation.
Details
Call it with the target schema to and then pipe the source schema from
into the returned function. The resulting schema decodes from
From["Encoded"] to To["Type"] and encodes from To["Type"] back to
From["Encoded"].
When no transformation is provided, SchemaTransformation.passthrough() is
used, so From["Type"] must already be compatible with To["Encoded"].
The resulting schema combines decoding and encoding services from both
schemas and any custom transformation.
Gotchas
In a custom transformation, decode maps From["Type"] to To["Encoded"]
and is used on the encoding path, while encode maps To["Encoded"] to
From["Type"] and is used on the decoding path.
Example (Transforming strings to numbers with a schema transformation)
import { Schema, SchemaGetter } from "effect"
const NumberFromString = Schema.String.pipe(
Schema.decodeTo(
Schema.Number,
{
decode: SchemaGetter.transform((s) => Number(s)),
encode: SchemaGetter.transform((n) => String(n))
}
)
)
const result = Schema.decodeUnknownSync(NumberFromString)("123")
// result: 123
Type-level representation returned by
decodeTo
.
decodeTo<interface Literal<L extends SchemaAST.LiteralValue>Creates a schema for a single literal value (string, number, bigint, boolean, or null).
Example (Defining a string literal)
import { Schema } from "effect"
const schema = Schema.Literal("hello")
// Type: Schema.Literal<"hello">
Type-level representation returned by
Literal
.
Literal<function (type parameter) L2 in transform<const L2 extends { readonly [I in keyof L]: SchemaAST.LiteralValue; }>(to: L2): Union<{ [I in keyof L]: decodeTo<Literal<L2[I]>, Literal<L[I]>>; }>L2[function (type parameter) II]>, interface Literal<L extends SchemaAST.LiteralValue>Creates a schema for a single literal value (string, number, bigint, boolean, or null).
Example (Defining a string literal)
import { Schema } from "effect"
const schema = Schema.Literal("hello")
// Type: Schema.Literal<"hello">
Type-level representation returned by
Literal
.
Literal<function (type parameter) L in Literals<const L extends ReadonlyArray<SchemaAST.LiteralValue>>(literals: L): Literals<L>L[function (type parameter) II]>> }> {
return function Union<
Members extends ReadonlyArray<Constraint>
>(
members: Members,
options?: { mode?: "anyOf" | "oneOf" }
): Union<Members>
Creates a union schema from an array of member schemas. Members are tested in
order; the first match is returned.
Details
Optionally, specify mode:
"anyOf" (default) — matches if any member matches.
"oneOf" — matches if exactly one member matches.
Example (Defining a string or number union)
import { Schema } from "effect"
const schema = Schema.Union([Schema.String, Schema.Number])
Schema.decodeUnknownSync(schema)("hello") // "hello"
Schema.decodeUnknownSync(schema)(42) // 42
Union(const members: {
readonly [K in keyof L]: Literal<L[K]>
}
members.ReadonlyArray<Literal<LiteralValue>>.map<decodeTo<Literal<SchemaAST.LiteralValue>, Literal<SchemaAST.LiteralValue>, never, never>>(callbackfn: (value: Literal<SchemaAST.LiteralValue>, index: number, array: readonly Literal<SchemaAST.LiteralValue>[]) => decodeTo<Literal<SchemaAST.LiteralValue>, Literal<SchemaAST.LiteralValue>, never, never>, thisArg?: any): decodeTo<Literal<SchemaAST.LiteralValue>, Literal<SchemaAST.LiteralValue>, never, never>[]Calls a defined callback function on each element of an array, and returns an array that contains the results.
map((member: Literal<SchemaAST.LiteralValue>(parameter) member: {
literal: L;
transform: (to: L2) => decodeTo<Literal<L2>, Literal<SchemaAST.LiteralValue>, never, never>;
Rebuild: Rebuild;
Iso: Iso;
ast: Ast;
Type: T;
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
annotate: (annotations: Annotations.Bottom<SchemaAST.LiteralValue, readonly []>) => Literal<SchemaAST.LiteralValue>;
annotateKey: (annotations: Annotations.Key<SchemaAST.LiteralValue>) => Literal<SchemaAST.LiteralValue>;
check: (checks_0: SchemaAST.Check<SchemaAST.LiteralValue>, ...checks: Array<SchemaAST.Check<SchemaAST.LiteralValue>>) => Literal<SchemaAST.LiteralValue>;
rebuild: (ast: SchemaAST.Literal) => Literal<SchemaAST.LiteralValue>;
make: (input: SchemaAST.LiteralValue, options?: MakeOptions) => SchemaAST.LiteralValue;
makeOption: (input: SchemaAST.LiteralValue, options?: MakeOptions) => Option_.Option<SchemaAST.LiteralValue>;
makeEffect: (input: SchemaAST.LiteralValue, options?: MakeOptions) => Effect.Effect<SchemaAST.LiteralValue, SchemaError, never>;
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; <…;
}
member, index: numberindex) => member: Literal<SchemaAST.LiteralValue>(parameter) member: {
literal: L;
transform: (to: L2) => decodeTo<Literal<L2>, Literal<SchemaAST.LiteralValue>, never, never>;
Rebuild: Rebuild;
Iso: Iso;
ast: Ast;
Type: T;
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
annotate: (annotations: Annotations.Bottom<SchemaAST.LiteralValue, readonly []>) => Literal<SchemaAST.LiteralValue>;
annotateKey: (annotations: Annotations.Key<SchemaAST.LiteralValue>) => Literal<SchemaAST.LiteralValue>;
check: (checks_0: SchemaAST.Check<SchemaAST.LiteralValue>, ...checks: Array<SchemaAST.Check<SchemaAST.LiteralValue>>) => Literal<SchemaAST.LiteralValue>;
rebuild: (ast: SchemaAST.Literal) => Literal<SchemaAST.LiteralValue>;
make: (input: SchemaAST.LiteralValue, options?: MakeOptions) => SchemaAST.LiteralValue;
makeOption: (input: SchemaAST.LiteralValue, options?: MakeOptions) => Option_.Option<SchemaAST.LiteralValue>;
makeEffect: (input: SchemaAST.LiteralValue, options?: MakeOptions) => Effect.Effect<SchemaAST.LiteralValue, SchemaError, never>;
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; <…;
}
member.Literal<LiteralValue>.transform<SchemaAST.LiteralValue>(to: SchemaAST.LiteralValue): decodeTo<Literal<SchemaAST.LiteralValue>, Literal<SchemaAST.LiteralValue>, never, never>transform(to: const L2 extends { readonly [I in keyof L]: SchemaAST.LiteralValue; }to[index: numberindex]))) as any
}
})
}