Schema
Describes data shapes and how unknown input becomes trusted values.
A schema can validate input, decode it into an application type, and encode that value back to another representation. This module contains the main schema, codec, decoder, and encoder APIs, together with schemas for common JavaScript values and Effect data types. It also supports refinements, transformations, defaults, classes, JSON Schema generation, test data generation, formatting, equivalence, optics, and differs derived from schema definitions.
Annotations
Signature
declare function annotate<S extends Top>(
annotations: Bottom<S["Type"], S["~type.parameters"]>,
): (self: S) => S["Rebuild"];annotateEncoded
Adds metadata annotations to the encoded side of a schema without changing its runtime behavior. This is the encoded-side counterpart of annotate, which targets the decoded (Type) side.
Details
Internally the schema is flipped so that Encoded becomes Type, annotated, and then flipped back.
See
annotateto annotate the type side instead.
Signature
declare function annotateEncoded<S extends Top>(
annotations: Bottom<S["Encoded"], readonly []>,
): (self: S) => S["Rebuild"];annotateKey
Adds key-level annotations to a schema field. This is the pipeable (curried) counterpart of the .annotateKey method.
Details
Key annotations apply to a field's position inside a Struct or Tuple rather than to the field's value type. They can carry a messageMissingKey to customise the error shown when the field is absent, as well as standard documentation fields such as title, description, and examples.
Signature
declare function annotateKey<S extends Top>(annotations: Key<S["Type"]>): (self: S) => S["Rebuild"];Branding
Adds a nominal brand to a schema, intersecting the output type with Brand.Brand<B> to prevent accidental mixing of structurally identical types.
When to use
Use to make values decoded by an existing schema nominally distinct when the schema already carries the runtime validation you need.
Gotchas
brand adds brand metadata and narrows the TypeScript output type, but it does not add runtime checks.
See
fromBrandfor applying a Brand constructor's checks along with the brand tag
Signature
declare function brand<B extends string>(
identifier: B,
): <S extends ConstraintRebuildable>(schema: S) => brand<S["Rebuild"], B>;Type-level representation returned by brand.
Signature
interface brand<S extends Constraint, B> extends BottomLazy<
S["ast"],
brand<S, B>,
S["~type.parameters"],
S["~type.mutability"],
S["~type.optionality"],
S["~type.constructor.default"],
S["~encoded.mutability"],
S["~encoded.optionality"]
> {
constructor(_: never);
readonly "~type.make": S["Type"] & UnionToIntersection<B extends U ? Brand<U> : never>;
readonly "~type.make.in": S["~type.make.in"];
readonly DecodingServices: S["DecodingServices"];
readonly Encoded: S["Encoded"];
readonly EncodingServices: S["EncodingServices"];
readonly identifier: string;
readonly Iso: S["Type"] & UnionToIntersection<B extends U ? Brand<U> : never>;
readonly schema: S;
readonly Type: S["Type"] & UnionToIntersection<B extends U ? Brand<U> : never>;
}Creates a branded schema from a Brand.Constructor, applying the constructor's checks and brand tag to the underlying schema.
Signature
declare function fromBrand<A extends Brand<any>>(
identifier: string,
ctor: Constructor<A>,
): <
S extends Top & {
readonly Type: Unbranded<A>;
},
>(
self: S,
) => brand<S["Rebuild"], keyof A["~effect/Brand"]>;Combinators
fieldsAssign
Adds fields to a struct schema through a struct-mapping lambda.
When to use
Use to add the same fields to an existing struct or every struct member of a union.
Details
This is a shortcut for MyStruct.mapFields(Struct.assign(fields)).
Signature
declare function fieldsAssign<NewFields extends Fields>(fields: NewFields): fieldsAssign<NewFields>;mutableKey
Makes a struct field mutable (removes the readonly modifier on the property). Use readonlyKey to reverse.
Signature
declare const mutableKey: mutableKeyLambda;Marks a struct field as optional, allowing the key to be absent or undefined.
Details
The resulting property may be absent or explicitly set to undefined. Equivalent to optionalKey(UndefinedOr(S)).
Use optionalKey instead if you want exact optional semantics (absent only, not undefined).
Signature
declare const optional: optionalLambda;optionalKey
Creates an exact optional key schema for struct fields. Unlike optional, this creates exact optional properties (not | undefined) that can be completely omitted from the object.
Signature
declare const optionalKey: optionalKeyLambda;readonlyKey
Reverses mutableKey and returns the inner readonly schema.
When to use
Use to remove mutable-key wrapping from a schema field that was previously wrapped with mutableKey.
Signature
declare const readonlyKey: readonlyKeyLambda;Reverses optional and returns the inner schema.
When to use
Use to remove optional wrapping from a schema field that was previously wrapped with optional.
Details
This also unwraps the UndefinedOr member added by optional.
Signature
declare const required: requiredLambda;requiredKey
Reverses optionalKey and returns the inner required schema.
When to use
Use to remove optional-key wrapping from a schema field that was previously wrapped with optionalKey.
Signature
declare const requiredKey: requiredKeyLambda;toTaggedUnion
Augments an existing Union of tagged structs with utility methods and an ordered tuple of discriminant values.
Gotchas
Throws if multiple members use the same discriminant property key.
See
TaggedUnionfor a shorthand that builds the union from scratch
Signature
declare function toTaggedUnion<Tag extends PropertyKey>(tag: Tag): <Members extends readonly Array<Constraint & {
readonly Type: { [K in PropertyKey]: PropertyKey };
}>>(self: Union<Members>) => toTaggedUnion<Tag, Members>toTaggedUnion type
Type-level representation returned by toTaggedUnion.
Signature
type toTaggedUnion<
Tag extends PropertyKey,
Members extends ReadonlyArray<
Constraint & {
readonly Type: { [K in Tag]: PropertyKey };
}
>,
> = Union<Members> & TaggedUnionUtils<Tag, Members>;Constructors
Signature
declare const Array: ArrayLambda;ArrayEnsure
Creates a schema that accepts either a value decoded by schema or an array decoded by Schema.Array(schema), then returns an array.
When to use
Use to accept input that may be provided either as one item or as an array, while normalizing decoded values to a readonly array.
Details
During encoding, one-element arrays are encoded as the single element. Empty arrays and arrays with two or more elements are encoded as arrays.
Gotchas
The single-value branch is tried before the array branch. If schema itself accepts arrays, an array input can be treated as one value and wrapped in a one-element array.
See
Arrayfor accepting only array inputNonEmptyArrayfor requiring at least one decoded element
Signature
declare function ArrayEnsure<S extends Constraint>(schema: S): ArrayEnsure<S>;ArrayEnsure interface
Type-level representation returned by ArrayEnsure.
Signature
interface ArrayEnsure<S extends Constraint> extends decodeTo<
$Array<toType<S>>,
Union<readonly [S, $Array<S>]>
> {
constructor(_: never);
readonly Rebuild: ArrayEnsure<S>;
}Creates a schema-backed class whose constructor validates input against a Struct schema. Construction throws a SchemaError on invalid input.
When to use
Use when you need a schema-backed data class with validated construction, schema-derived decoding/encoding, and class-style methods or inheritance.
Details
Pass the desired class type as the first type parameter. The second optional type parameter can be used to add nominal brands.
The identifier is the schema's stable runtime name. It is exposed on the class, stored in the schema AST, and used to label diagnostics and generated references as well as to format class instances.
It also derives a runtime marker that recognizes instances across hot module reloads, where instanceof can fail because the constructor has been replaced. The identifier is explicit because the outer JavaScript class name is not available while the extends expression is evaluated and may change through renaming or minification.
Gotchas
Passing disableChecks in the options skips constructor validation.
See
TaggedClassfor adding a_tagliteral field to the class schemaErrorfor defining schema-backed error classesTaggedErrorfor defining tagged schema-backed error classes
Signature
declare const Class: <Self = never, Brand = {}>(
identifier: string,
) => {
<Fields extends Fields>(
fields: Fields,
annotations?: Declaration<Self, readonly [Struct<Fields>]>,
): [Self] extends [never]
? "Missing `Self` generic - use `class Self extends Schema.Class<Self>(...)`"
: Class<Self, Struct<Fields>, Brand>;
<S extends Struct<Fields>>(
schema: S,
annotations?: Declaration<Self, readonly [S]>,
): [Self] extends [never]
? "Missing `Self` generic - use `class Self extends Schema.Class<Self>(...)`"
: Class<Self, S, Brand>;
};Creates a schema for a non-parametric opaque type using a type-guard function. The schema accepts any unknown value and succeeds when is returns true, failing with an InvalidType issue otherwise.
When to use
Use when you are defining a schema for an opaque type with no type parameters and validation can be expressed as a type guard.
See
declareConstructorfor creating schemas for parametric types.
Signature
declare function declare<T, Iso = T>(
is: (u: unknown) => u is T,
annotations?: Declaration<T, readonly []>,
): declare<T, Iso>;Type-level representation returned by declare.
Signature
interface declare<T, Iso = T> extends declareConstructor<T, T, readonly [], Iso> {
constructor(_: never);
readonly Rebuild: declare<T, Iso>;
}declareConstructor
Creates a schema for a parametric type (a generic container such as Array<A>, Option<A>, etc.) by accepting a list of type-parameter schemas and a decoder factory.
When to use
Use when you are defining a schema for a generic container whose validation depends on one or more type-parameter schemas.
Details
The outer call declareConstructor<T, E, Iso>() fixes the decoded type T, the encoded type E, and the optional iso type. The inner call receives: - typeParameters — the concrete schemas for each type variable - run — a factory that, given resolved codecs for each type parameter, returns a parsing function (u, ast, options) => Effect<T, Issue> - annotations — optional metadata
See
declarefor creating schemas for non-parametric types. Example (Schema for a parametricBox<A>type) ``ts import.meta.vitest import { Effect, Schema, SchemaIssue as Issue, SchemaParser } from "effect" interface Box<A> { readonly value: A } const isBox = (u: unknown): u is Box<unknown> => typeof u === "object" && u !== null && "value" in u const Box = <A extends Schema.Constraint>(item: A) => Schema.declareConstructor<Box<A["Type"]>, Box<A["Encoded"]>>()( [item], ([itemCodec]) => (u, ast, options) => { if (!isBox(u)) { return Effect.fail(new SchemaIssue.InvalidType(ast)) } return Effect.map( SchemaParser.decodeUnknownEffect(itemCodec)(u.value, options), (value) => ({ value }) ) } ) const schema = Box(Schema.Number) Effect.runSync(Schema.decodeUnknownEffect(schema)({ value: 1 })) // => { value: 1 }``
Signature
declare function declareConstructor<T, E = T, Iso = T>(): <TypeParameters extends readonly Array<Constraint>>(typeParameters: TypeParameters, run: (typeParameters: { [K in string | number | symbol]: Codec<TypeParameters[K]["Type"], TypeParameters[K]["Encoded"], never, never> }) => (u: unknown, self: Declaration, options: ParseOptions) => Effect<T, Issue>, annotations?: Declaration<T, TypeParameters>) => declareConstructor<T, E, TypeParameters, Iso>declareConstructor interface
Type-level representation returned by declareConstructor.
Signature
interface declareConstructor<
T,
E,
TypeParameters extends ReadonlyArray<Constraint>,
Iso = T,
> extends Bottom<
T,
E,
TypeParameters[number]["DecodingServices"],
TypeParameters[number]["EncodingServices"],
SchemaAST.Declaration,
declareConstructor<T, E, TypeParameters, Iso>,
T,
Iso,
TypeParameters
> {
constructor(_: never);
}Creates a schema from a TypeScript enum object. Validates that the input is one of the enum's values.
Signature
declare function Enum<
A extends {
[x: string]: string | number;
},
>(enums: A): Enum<A>;Creates a schema-backed error class that can be used as a typed, yieldable error in Effect programs. Combines Class validation with the YieldableError interface so instances can be yielded directly inside Effect.gen.
Signature
declare const Error: <Self = never, Brand = {}>(
identifier: string,
) => {
<Fields extends Fields>(
fields: Fields,
annotations?: Declaration<Self, readonly [Struct<Fields>]>,
): [Self] extends [never]
? "Missing `Self` generic - use `class Self extends Schema.Error<Self>(...)`"
: Class<Self, Struct<Fields>, YieldableError & Brand>;
<S extends Struct<Fields>>(
schema: S,
annotations?: Declaration<Self, readonly [S]>,
): [Self] extends [never]
? "Missing `Self` generic - use `class Self extends Schema.Error<Self>(...)`"
: Class<Self, S, YieldableError & Brand>;
};instanceOf
Creates a schema that validates values using instanceof. Decoding and encoding pass the value through unchanged.
Signature
declare function instanceOf<C extends (...args: any) => any, Iso = InstanceType<C>>(
constructor: C,
annotations?: Declaration<InstanceType<C>, readonly []>,
): instanceOf<InstanceType<C>, Iso>;Creates a schema for a single literal value (string, number, bigint, boolean, or null).
See
Signature
declare function Literal<L extends LiteralValue>(literal: L): Literal<L>;Creates a union schema from an array of literal values.
See
Literalfor a schema that represents a single literal.
Signature
declare function Literals<L extends readonly Array<LiteralValue>>(literals: L): Literals<L>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.
Signature
declare const make: <S extends Constraint>(ast: S["ast"], options?: object) => S;makeFilter
Creates a custom validation filter from a predicate function.
Details
The predicate receives the decoded input value, the schema AST, and parse options, and returns a FilterOutput. Non-success outputs are normalized into schema issues. The annotations parameter annotates the filter itself; with the default formatter, failures use message first, expected second, and <filter> when neither is provided.
When abort is true, parsing stops after this filter fails instead of collecting later check failures.
Signature
declare const makeFilter: <T>(
filter: (input: T, ast: SchemaAST.AST, options: SchemaAST.ParseOptions) => FilterOutput,
annotations?: Annotations.Filter,
abort?: boolean,
) => SchemaAST.Filter<T>;makeFilterGroup
Groups multiple checks into a single SchemaAST.FilterGroup, applying optional shared annotations to the group as a whole.
Signature
declare function makeFilterGroup<T>(
checks: readonly [Check<T>, Check<T>],
annotations: Filter | undefined,
): FilterGroup<T>;NonEmptyArray
Defines a non-empty ReadonlyArray schema — at least one element required. Type is readonly [T, ...T[]].
Signature
declare const NonEmptyArray: NonEmptyArrayLambda;Creates a union schema of S | null | undefined.
Signature
declare const NullishOr: NullishOrLambda;Creates a union schema of S | null.
Signature
declare const NullOr: NullOrLambda;Wraps a struct schema so that its decoded Type becomes a nominally distinct type Self. Useful for creating opaque types that are structurally identical to a base struct but type-incompatible with it.
Signature
declare function Opaque<Self, Brand = {}>(): <S extends Top>(
schema: S,
) => Opaque<Self, S, Brand> & Omit<S, keyof Top>;Defines a record schema whose dynamic properties are selected by a key schema and decoded with a value schema.
Details
For dynamic keys, the key schema selects matching own properties and the value schema decodes or encodes only those selected properties. Checks on string, number, symbol, and template literal key schemas narrow which properties are selected.
For transformed key schemas, property selection is based on encoded property names before the selected key is decoded.
Gotchas
When decoded or encoded key transformations produce the same property key, sequential parsing applies selected own properties in selection order, so the later selected property overwrites the earlier value. With concurrency greater than 1, completion order determines which value is retained.
Signature
declare function Record<Key extends Key, Value extends Constraint>(
key: Key,
value: Value,
): $Record<Key, Value>;Defines a struct schema from a map of field schemas.
Details
Each field value is a schema. Use optionalKey or optional to mark fields as optional, and mutableKey to mark them as mutable.
The resulting schema's Type is a readonly object type with the fields' decoded types. The Encoded form mirrors the field schemas' encoded types.
Signature
declare function Struct<Fields extends Fields>(fields: Fields): Struct<Fields>;StructWithRest
Extends a struct schema with one or more record (index-signature) schemas, producing a schema whose decoded type intersects the struct and all records.
Gotchas
TypeScript index signatures also apply to fixed keys. StructWithRest does not reject incompatible fixed fields at the call site; use StructWithRest.ValidateRecords when you want an explicit type-level compatibility check.
Signature
declare function StructWithRest<S extends Objects, Records extends Records>(
schema: S,
records: Records,
): StructWithRest<S, Records>;Creates a suspended schema that defers evaluation until needed. This is essential for creating recursive schemas where a schema references itself, preventing infinite recursion during schema definition.
Signature
declare function suspend<S extends Constraint>(f: () => S): suspend<S>;Combines a Literal schema with withConstructorDefault, making it ideal for discriminator fields in tagged unions. When constructing via make, the _tag field can be omitted and will be filled automatically.
See
tagDefaultOmitto also omit the tag during encodingTaggedStructfor a shorthand that adds_tagautomatically
Signature
declare function tag<Tag extends LiteralValue>(literal: Tag): tag<Tag>;Type-level representation returned by tag.
Signature
interface tag<Tag extends SchemaAST.LiteralValue> extends withConstructorDefault<Literal<Tag>> {
constructor(_: never);
}tagDefaultOmit
Creates a literal _tag schema that is omitted from encoded output.
When to use
Use to decode data that omits the discriminator field while still constructing values with a _tag for tagged union matching.
Details
The tag is filled during decoding and construction, like tag, but is omitted when encoding.
See
tagfor the variant that keeps the tag during encoding
Signature
declare function tagDefaultOmit<Tag extends LiteralValue>(
literal: Tag,
): withDecodingDefaultKey<tag<Tag>, never>;TaggedClass
Defines a schema-backed class with an automatically populated _tag field.
When to use
Use to define class instances that are validated by a schema and participate in tagged union matching.
Details
The optional identifier parameter overrides the schema identifier; it defaults to the tag value.
Signature
declare const TaggedClass: <Self = never, Brand = {}>(identifier?: string) => {
<Tag extends string, Fields extends Fields>(tag: Tag, fields: Fields, annotations?: Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): [Self] extends [never] ? "Missing `Self` generic - use `class Self extends Schema.TaggedClass<Self>(...)`" : Class<Self, TaggedStruct<Tag, Fields>, Brand>;
<Tag extends string, S extends Struct<Fields>>(tag: Tag, schema: S, annotations?: Declaration<Self, readonly [Struct<{ [K in string | number | symbol]: {
readonly _tag: tag<...>;
} & S["fields"][K] }>]>): [Self] extends [never] ? "Missing `Self` generic - use `class Self extends Schema.TaggedClass<Self>(...)`" : Class<Self, Struct<{ [K in string | number | symbol]: {
readonly _tag: tag<Tag>;
} & S["fields"][K] }>, Brand>;
}TaggedError
Defines a schema-backed yieldable error class with an automatically populated _tag field.
When to use
Use to define typed errors that are schema validated, yielded in Effect.gen, and matched as tagged union members.
Signature
declare const TaggedError: <Self = never, Brand = {}>(identifier?: string) => {
<Tag extends string, Fields extends Fields>(tag: Tag, fields: Fields, annotations?: Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): [Self] extends [never] ? "Missing `Self` generic - use `class Self extends Schema.TaggedError<Self>(...)`" : Class<Self, TaggedStruct<Tag, Fields>, YieldableError & Brand>;
<Tag extends string, S extends Struct<Fields>>(tag: Tag, schema: S, annotations?: Declaration<Self, readonly [Struct<{ [K in string | number | symbol]: {
readonly _tag: tag<...>;
} & S["fields"][K] }>]>): [Self] extends [never] ? "Missing `Self` generic - use `class Self extends Schema.TaggedError<Self>(...)`" : Class<Self, Struct<{ [K in string | number | symbol]: {
readonly _tag: tag<Tag>;
} & S["fields"][K] }>, YieldableError & Brand>;
}TaggedStruct
Creates a struct schema with an automatically populated _tag field.
When to use
Use to define a tagged union case from a literal tag and a set of fields.
Details
When using the make method, the _tag field is optional and will be added automatically. However, when decoding or encoding, the _tag field must be present in the input.
Signature
declare function TaggedStruct<Tag extends LiteralValue, Fields extends Fields>(
value: Tag,
fields: Fields,
): TaggedStruct<Tag, Fields>;TaggedUnion
Builds a discriminated union from a record of field sets, one per variant. Each key becomes the _tag literal and the value is passed to TaggedStruct. The result includes cases, guards, isAnyOf, and match utilities.
See
toTaggedUnionto augment an existing union instead
Signature
declare function TaggedUnion<CasesByTag extends Record<string, Fields>>(
casesByTag: CasesByTag,
): TaggedUnion<{ [K in string]: TaggedStruct<K, CasesByTag[K]> }>;TemplateLiteral
Creates a schema that validates strings by matching ordered template literal parts.
When to use
Use when the decoded value should remain the matched string and you do not need the individual template parts parsed into a tuple.
Details
Each part can be a literal string, number, or bigint, or a schema whose encoded type is string, number, or bigint. Checks on string, number, and bigint schema parts are applied while matching each segment.
See
TemplateLiteralParserfor a schema that also parses matched parts into a tuple.
Signature
declare function TemplateLiteral<Parts extends Parts>(parts: Parts): TemplateLiteral<Parts>;TemplateLiteralParser
Schema for parsing matched template literal strings into typed tuple parts.
When to use
Use to validate a template literal string and decode the matched parts into typed values.
Details
Unlike TemplateLiteral, this schema decodes the matched string into a readonly tuple with one element per schema part. Checks on string, number, and bigint schema parts are applied while matching each segment.
See
TemplateLiteralfor a validation-only version that keeps the string encoded.
Signature
declare function TemplateLiteralParser<Parts extends Parts>(
parts: Parts,
): TemplateLiteralParser<Parts>;toIsoFocus
Returns an identity Iso over the schema's focus (Iso) side.
Signature
declare function toIsoFocus<S extends Constraint>(_: S): Iso<S["Iso"], S["Iso"]>;toIsoSource
Returns an identity Iso over the schema's source (Type) side.
Signature
declare function toIsoSource<S extends Constraint>(_: S): Iso<S["Type"], S["Type"]>;Defines a fixed-length tuple schema from an array of element schemas.
Signature
declare function Tuple<Elements extends readonly Array<Constraint>>(elements: Elements): Tuple<Elements>TupleWithRest
Extends a fixed-length tuple schema with a variadic rest segment.
Details
The resulting tuple starts with the fixed elements from schema. The first schema in rest is the repeatable element schema, and any additional schemas in rest are required trailing tuple elements after the variadic segment. For example, [Schema.Boolean, Schema.String] represents zero or more booleans followed by a final string.
Signature
declare function TupleWithRest<
S extends Tuple<Elements>,
Rest extends readonly [Constraint, Constraint],
>(schema: S, rest: Rest): TupleWithRest<S, Rest>;UndefinedOr
Creates a union schema of S | undefined.
Signature
declare const UndefinedOr: UndefinedOrLambda;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.
Signature
declare function Union<Members extends readonly Array<Constraint>>(members: Members, options?: {
mode?: "anyOf" | "oneOf";
}): Union<Members>UniqueArray
Returns a new array schema that ensures all elements are unique.
Details
The equivalence used to determine uniqueness is the one provided by Schema.toEquivalence(item).
Signature
declare function UniqueArray<S extends Constraint>(item: S): UniqueArray<S>;UniqueSymbol
Creates a schema for a specific symbol. Only that exact symbol satisfies the schema.
See
Symbolfor a schema that accepts any symbol.
Signature
declare function UniqueSymbol<sym extends symbol>(symbol: sym): UniqueSymbol<sym>;withConstructorDefault
Attaches a constructor default value to a schema field.
Details
Constructor defaults are applied only during make*, not during decoding or encoding.
Signature
declare function withConstructorDefault<S extends Constraint & WithoutConstructorDefault>(
defaultValue: Effect<S["~type.make.in"], SchemaError>,
): (schema: S) => withConstructorDefault<S>;withConstructorDefault interface
Type-level representation returned by withConstructorDefault.
Signature
interface withConstructorDefault<
S extends Constraint & WithoutConstructorDefault,
> extends BottomLazy<
S["ast"],
withConstructorDefault<S>,
S["~type.parameters"],
S["~type.mutability"],
S["~type.optionality"],
"with-default",
S["~encoded.mutability"],
S["~encoded.optionality"]
> {
constructor(_: never);
readonly "~type.make": S["~type.make"];
readonly "~type.make.in": S["~type.make.in"];
readonly DecodingServices: S["DecodingServices"];
readonly Encoded: S["Encoded"];
readonly EncodingServices: S["EncodingServices"];
readonly Iso: S["Iso"];
readonly schema: S;
readonly Type: S["Type"];
}Converting
toCodecArrayFromSingle
Allows array schemas to decode from either an array input or a single value input.
When to use
Use when you need to accept transport formats that may represent a single-item array as a bare value, such as query-string or form-data adapters.
Gotchas
This combinator is intentionally not part of toCodecStringTree; it adds a decoding convenience rather than a canonical StringTree representation. It does not parse comma-separated strings.
Signature
declare function toCodecArrayFromSingle<S extends Constraint>(schema: S): toCodecArrayFromSingle<S>;toCodecArrayFromSingle interface
Type-level representation returned by toCodecArrayFromSingle.
Signature
interface toCodecArrayFromSingle<S extends Constraint> extends BottomLazy<
S["ast"],
toCodecArrayFromSingle<S>,
S["~type.parameters"],
S["~type.mutability"],
S["~type.optionality"],
S["~type.constructor.default"],
S["~encoded.mutability"],
S["~encoded.optionality"]
> {
constructor(_: never);
readonly "~type.make": S["~type.make"];
readonly "~type.make.in": S["~type.make.in"];
readonly DecodingServices: S["DecodingServices"];
readonly Encoded: S["Encoded"];
readonly EncodingServices: S["EncodingServices"];
readonly Iso: S["Iso"];
readonly Type: S["Type"];
}toCodecIso
Derives an isomorphism codec from a schema. The encoded form is the schema's Iso type — the intermediate representation used for round-tripping.
Signature
declare function toCodecIso<S extends Constraint>(schema: S): Codec<S["Type"], S["Iso"]>;toCodecJson
Derives a canonical JSON codec from a schema. The encoded form is Json, and decoding produces the schema's Type.
Gotchas
Declarations without a toCodecJson or toCodec annotation use Json as their encoded schema. This keeps codec construction total, but encoding or decoding can still fail when declaration values are not JSON values. A toCodecJson callback can return undefined when the declaration is already in canonical JSON form.
Signature
declare function toCodecJson<S extends Constraint>(schema: S): toCodecJson<S>;toCodecJson interface
Type-level representation returned by toCodecJson.
Signature
interface toCodecJson<S extends Constraint> extends BottomLazy<
S["ast"],
toCodecJson<S>,
S["~type.parameters"],
S["~type.mutability"],
S["~type.optionality"],
S["~type.constructor.default"],
S["~encoded.mutability"],
S["~encoded.optionality"]
> {
constructor(_: never);
readonly "~type.make": S["~type.make"];
readonly "~type.make.in": S["~type.make.in"];
readonly DecodingServices: S["DecodingServices"];
readonly Encoded: Json;
readonly EncodingServices: S["EncodingServices"];
readonly Iso: S["Iso"];
readonly schema: S;
readonly Type: S["Type"];
}toCodecStringTree
Converts a schema to the StringTree canonical codec, where every leaf value becomes a string while preserving the original structure.
Gotchas
Declarations must provide a structural toCodecStringTree, toCodecJson, or toCodec encoding. A callback can return undefined when the declaration is already in canonical StringTree form.
Signature
declare function toCodecStringTree<S extends Constraint>(schema: S): toCodecStringTree<S>;toCodecStringTree interface
Type-level representation returned by toCodecStringTree.
Signature
interface toCodecStringTree<S extends Constraint> extends BottomLazy<
S["ast"],
toCodecStringTree<S>,
ReadonlyArray<Constraint>,
S["~type.mutability"],
S["~type.optionality"],
S["~type.constructor.default"],
S["~encoded.mutability"],
S["~encoded.optionality"]
> {
constructor(_: never);
readonly "~type.make": S["~type.make"];
readonly "~type.make.in": S["~type.make.in"];
readonly DecodingServices: S["DecodingServices"];
readonly Encoded: StringTree;
readonly EncodingServices: S["EncodingServices"];
readonly Iso: S["Iso"];
readonly schema: S;
readonly Type: S["Type"];
}toDifferJsonPatch
Derives a JSON Patch differ from a codec. Serializes values to JSON (via toCodecJson), computes RFC 6902 JSON Patch operations between old and new values, and can apply patches back to the typed value.
Signature
declare function toDifferJsonPatch<T>(schema: ConstraintCodec<T, unknown>): Differ<T, JsonPatch>;Derives an Iso optic from a schema that isomorphically converts between the schema's Type and its Iso (intermediate / serialized form).
Signature
declare function toIso<S extends Constraint>(schema: S): Iso<S["Type"], S["Iso"]>;toJsonSchemaDocument
Returns a JSON Schema document using draft 2020-12.
Details
The options parameter controls generation details such as additional properties and synthesized check descriptions; it does not change the draft target. Declarations are lowered through their toCodecJson or toCodec annotation when available before the representation document is compiled.
Gotchas
JSON Schema generation is best-effort. Some Effect schema semantics cannot be represented exactly in JSON Schema, and importing an emitted JSON Schema may produce an equivalent approximation rather than the original schema shape. Opaque declarations without a structural codec are represented by an unconstrained JSON Schema.
Signature
declare function toJsonSchemaDocument(
schema: Constraint,
options?: ToJsonSchemaOptions,
): Document<"draft-2020-12">;toRepresentation
Derives an intermediate SchemaRepresentation.Document from the encoded side of a schema.
Details
Use toType before this function to represent the type side instead.
Signature
declare function toRepresentation(schema: Constraint): Document;toStandardJSONSchemaV1
Converts a schema to an experimental Standard JSON Schema V1 representation.
Details
https://github.com/standard-schema/standard-schema/pull/134
Signature
declare function toStandardJSONSchemaV1<S extends Constraint>(self: S): any;toStandardSchemaV1
Returns a "Standard Schema" object conforming to the [Standard Schema v1](https://standardschema.dev/) specification.
Details
This function creates a schema whose validate method attempts to decode and validate the provided input synchronously. If the underlying Schema includes any asynchronous components (e.g., asynchronous message resolutions or checks), then validation will necessarily return a Promise instead.
Signature
declare function toStandardSchemaV1<S extends ConstraintDecoder<unknown, never>>(
self: S,
options?: {
readonly checkHook?: CheckHook;
readonly leafHook?: LeafHook;
readonly parseOptions?: ParseOptions;
},
): any;Decoding
decodeEffect
Decodes a typed input (the schema's Encoded type) against a schema, returning an Effect that succeeds with the decoded value or fails with a SchemaError.
When to use
Use when you need to decode input already typed as the schema's Encoded type in an Effect whose failure channel is SchemaError.
Details
For unknown input use decodeUnknownEffect. Options may be provided either when creating the decoder or when applying it; application options override creation options.
See
SchemaParser.decodeEffect for the adapter that fails withSchemaIssue.Issuedirectly
Signature
declare const decodeEffect: <S extends Constraint>(
schema: S,
options?: SchemaAST.ParseOptions,
) => (
input: S["Encoded"],
options?: SchemaAST.ParseOptions,
) => Effect.Effect<S["Type"], SchemaError, S["DecodingServices"]>;decodeExit
Decodes a typed input (the schema's Encoded type) against a schema synchronously, returning an Exit that is either a Success with the decoded value or a Failure.
When to use
Use when you need to decode already typed Encoded input into an Exit and capture schema mismatches as SchemaError.
Details
Only usable with schemas that have no DecodingServices requirement. For unknown input use decodeUnknownExit. Options may be provided either when creating the decoder or when applying it; application options override creation options. Schema mismatches are represented by a Failure cause containing SchemaError.
Gotchas
Schema issue fail reasons are wrapped as SchemaError. Defects, interruptions, and other non-schema reasons remain in the returned Cause, including when they are mixed with schema issues.
See
SchemaParser.decodeExit for the adapter whose failure containsSchemaIssue.Issuedirectly
Signature
declare const decodeExit: <S extends ConstraintDecoder<unknown>>(
schema: S,
options?: SchemaAST.ParseOptions,
) => (input: S["Encoded"], options?: SchemaAST.ParseOptions) => Exit_.Exit<S["Type"], SchemaError>;decodeOption
Decodes a typed input (the schema's Encoded type) against a schema, returning an Option that is Some with the decoded value on success or None for schema mismatches.
When to use
Use when you already have input typed as the schema's Encoded type and only need to know whether decoding succeeded.
Details
For unknown input use decodeUnknownOption. Options may be provided either when creating the decoder or when applying it; application options override creation options.
Gotchas
Only causes made entirely of schema issues are converted to None. Causes that contain defects, interruptions, or other non-schema reasons throw instead.
Signature
declare const decodeOption: <S extends ConstraintDecoder<unknown>>(
schema: S,
options?: SchemaAST.ParseOptions,
) => (input: S["Encoded"], options?: SchemaAST.ParseOptions) => Option_.Option<S["Type"]>;decodePromise
Decodes a typed input (the schema's Encoded type) against a schema, returning a Promise that resolves with the decoded value or rejects with a SchemaError for schema mismatches.
When to use
Use when you already have input typed as the schema's Encoded type and need decoding to return a JavaScript Promise that rejects with SchemaError for schema mismatches.
Details
For unknown input use decodeUnknownPromise. Options may be provided either when creating the decoder or when applying it; application options override creation options.
Gotchas
Non-schema failures may reject with a runtime failure instead of SchemaError.
See
SchemaParser.decodePromise for the adapter that rejects with anErrorwhose cause isSchemaIssue.Issue
Signature
declare const decodePromise: <S extends ConstraintDecoder<unknown>>(
schema: S,
options?: SchemaAST.ParseOptions,
) => (input: S["Encoded"], options?: SchemaAST.ParseOptions) => Promise<S["Type"]>;decodeResult
Decodes a typed input (the schema's Encoded type) against a schema, returning a Result that succeeds with the decoded value or fails with a SchemaError for schema mismatches.
When to use
Use when you already have input typed as the schema's Encoded type and want schema mismatches returned as Result.fail with SchemaError.
Details
For unknown input use decodeUnknownResult. Options may be provided either when creating the decoder or when applying it; application options override creation options. Schema mismatches are returned as Result.fail with SchemaError.
Gotchas
Only causes made entirely of schema issues are returned as Result.fail. Causes that contain defects, interruptions, or other non-schema reasons throw instead.
See
SchemaParser.decodeResult for the adapter that fails withSchemaIssue.Issuedirectly
Signature
declare const decodeResult: <S extends ConstraintDecoder<unknown>>(
schema: S,
options?: SchemaAST.ParseOptions,
) => (
input: S["Encoded"],
options?: SchemaAST.ParseOptions,
) => Result_.Result<S["Type"], SchemaError>;decodeSync
Decodes a typed input (the schema's Encoded type) against a schema synchronously, returning the decoded value or throwing a SchemaError for schema mismatches.
When to use
Use when you already have input typed as the schema's Encoded type and want schema mismatches to throw SchemaError synchronously.
Details
For unknown input use decodeUnknownSync. Only service-free schemas can be decoded synchronously. Options may be provided either when creating the decoder or when applying it; application options override creation options.
Gotchas
Non-schema failures may throw a runtime failure instead of SchemaError.
See
SchemaParser.decodeSync for the adapter that throws anErrorwhose cause isSchemaIssue.Issue
Signature
declare const decodeSync: <S extends ConstraintDecoder<unknown>>(
schema: S,
options?: SchemaAST.ParseOptions,
) => (input: S["Encoded"], options?: SchemaAST.ParseOptions) => S["Type"];decodeUnknownEffect
Decodes an unknown input against a schema, returning an Effect that succeeds with the decoded value or fails with a SchemaError.
When to use
Use when you need to decode unknown input in an Effect whose failure channel is SchemaError.
Details
Prefer decodeEffect when the input is already typed as the schema's Encoded type. Options may be provided either when creating the decoder or when applying it; application options override creation options.
See
SchemaParser.decodeUnknownEffect for the adapter that fails withSchemaIssue.Issuedirectly
Signature
declare function decodeUnknownEffect<S extends Constraint>(
schema: S,
options?: ParseOptions,
): (
input: unknown,
options?: ParseOptions,
) => Effect<S["Type"], SchemaError, S["DecodingServices"]>;decodeUnknownExit
Decodes an unknown input against a schema synchronously, returning an Exit that is either a Success with the decoded value or a Failure.
When to use
Use when you need to decode unknown input into an Exit and capture schema mismatches as SchemaError.
Details
Only usable with schemas that have no DecodingServices requirement. Prefer decodeExit when the input is already typed as the schema's Encoded type. Options may be provided either when creating the decoder or when applying it; application options override creation options. Schema mismatches are represented by a Failure cause containing SchemaError.
Gotchas
Schema issue fail reasons are wrapped as SchemaError. Defects, interruptions, and other non-schema reasons remain in the returned Cause, including when they are mixed with schema issues.
See
SchemaParser.decodeUnknownExit for the adapter whose failure containsSchemaIssue.Issuedirectly
Signature
declare function decodeUnknownExit<S extends ConstraintDecoder<unknown, never>>(
schema: S,
options?: ParseOptions,
): (input: unknown, options?: ParseOptions) => Exit<S["Type"], SchemaError>;decodeUnknownOption
Decodes an unknown input against a schema, returning an Option that is Some with the decoded value on success or None for schema mismatches.
When to use
Use when you do not know the input type statically and only need to know whether decoding succeeded.
Details
Prefer this over decodeUnknownExit or decodeUnknownEffect when you don't need error details. For input already typed as the schema's Encoded type use decodeOption. Options may be provided either when creating the decoder or when applying it; application options override creation options.
Gotchas
Only causes made entirely of schema issues are converted to None. Causes that contain defects, interruptions, or other non-schema reasons throw instead.
Signature
declare const decodeUnknownOption: <S extends ConstraintDecoder<unknown>>(
schema: S,
options?: SchemaAST.ParseOptions,
) => (input: unknown, options?: SchemaAST.ParseOptions) => Option_.Option<S["Type"]>;decodeUnknownPromise
Decodes an unknown input against a schema, returning a Promise that resolves with the decoded value or rejects with a SchemaError for schema mismatches.
When to use
Use when you need decoding of unknown input to return a JavaScript Promise that rejects with SchemaError for schema mismatches.
Details
For input already typed as the schema's Encoded type use decodePromise. Options may be provided either when creating the decoder or when applying it; application options override creation options.
Gotchas
Non-schema failures may reject with a runtime failure instead of SchemaError.
See
SchemaParser.decodeUnknownPromise for the adapter that rejects with anErrorwhose cause isSchemaIssue.Issue
Signature
declare function decodeUnknownPromise<S extends ConstraintDecoder<unknown, never>>(
schema: S,
options?: ParseOptions,
): (input: unknown, options?: ParseOptions) => Promise<S["Type"]>;decodeUnknownResult
Decodes an unknown input against a schema, returning a Result that succeeds with the decoded value or fails with a SchemaError for schema mismatches.
When to use
Use when you do not know the input type statically and want schema mismatches returned as Result.fail with SchemaError.
Details
For input already typed as the schema's Encoded type use decodeResult. Options may be provided either when creating the decoder or when applying it; application options override creation options. Schema mismatches are returned as Result.fail with SchemaError.
Gotchas
Only causes made entirely of schema issues are returned as Result.fail. Causes that contain defects, interruptions, or other non-schema reasons throw instead.
See
SchemaParser.decodeUnknownResult for the adapter that fails withSchemaIssue.Issuedirectly
Signature
declare function decodeUnknownResult<S extends ConstraintDecoder<unknown, never>>(
schema: S,
options?: ParseOptions,
): (input: unknown, options?: ParseOptions) => Result<S["Type"], SchemaError>;decodeUnknownSync
Decodes an unknown input against a schema synchronously, returning the decoded value or throwing a SchemaError for schema mismatches.
When to use
Use when you need to validate unknown data at a synchronous boundary and want schema mismatches to throw SchemaError.
Details
For input already typed as the schema's Encoded type use decodeSync. Only service-free schemas can be decoded synchronously. For alternatives that do not throw on schema mismatches, see decodeUnknownOption, decodeUnknownExit, or decodeUnknownEffect. Options may be provided either when creating the decoder or when applying it; application options override creation options.
Gotchas
Non-schema failures may throw a runtime failure instead of SchemaError.
See
SchemaParser.decodeUnknownSync for the adapter that throws anErrorwhose cause isSchemaIssue.Issue
Signature
declare function decodeUnknownSync<S extends ConstraintDecoder<unknown, never>>(
schema: S,
options?: ParseOptions,
): (input: unknown, options?: ParseOptions) => S["Type"];fromFormData
Schema for decoding FormData through a bracket-notation tree.
When to use
Use to decode browser or multipart form data into a structured schema value.
Details
The decoding process has two steps:
1. Parse FormData into a nested tree record. 2. Decode the parsed value with the given schema.
You can express nested values using bracket notation.
If you want to decode string fields into non-string primitive values, use Schema.toCodecStringTree.
Signature
declare function fromFormData<S extends Constraint>(schema: S): fromFormData<S>;fromURLSearchParams
Schema for decoding URLSearchParams through a bracket-notation tree.
When to use
Use to decode query parameters into a structured schema value.
Details
The decoding process has two steps:
1. Parse URLSearchParams into a nested tree record. 2. Decode the parsed value with the given schema.
You can express nested values using bracket notation.
If you want to decode values that are not strings, use Schema.toCodecStringTree. This serializer preserves values such as numbers when compatible with the schema.
Signature
declare function fromURLSearchParams<S extends Constraint>(schema: S): fromURLSearchParams<S>;middlewareDecoding
Intercepts the decoding pipeline of a schema.
Details
The provided function receives the current decoding Effect and ParseOptions, and returns a new Effect — potentially adding service requirements (RD), recovering from errors, or augmenting the result.
See
catchDecodingfor a simpler error-recovery variant
Signature
declare function middlewareDecoding<S extends Constraint, RD>(
decode: (
effect: Effect<Option<S["Type"]>, Issue, S["DecodingServices"]>,
options: ParseOptions,
) => Effect<Option<S["Type"]>, Issue, RD>,
): (schema: S) => middlewareDecoding<S, RD>;middlewareDecoding interface
Type-level representation returned by middlewareDecoding.
Signature
interface middlewareDecoding<S extends Constraint, RD> extends BottomLazy<
S["ast"],
middlewareDecoding<S, RD>,
S["~type.parameters"],
S["~type.mutability"],
S["~type.optionality"],
S["~type.constructor.default"],
S["~encoded.mutability"],
S["~encoded.optionality"]
> {
constructor(_: never);
readonly "~type.make": S["~type.make"];
readonly "~type.make.in": S["~type.make.in"];
readonly DecodingServices: RD;
readonly Encoded: S["Encoded"];
readonly EncodingServices: S["EncodingServices"];
readonly Iso: S["Iso"];
readonly schema: S;
readonly Type: S["Type"];
}withDecodingDefault
Wraps the Encoded side with optional (key absent or undefined) and provides a default Encoded value when the field is missing or undefined during decoding.
When to use
Use when the default is expressed in the encoded representation, before the field's decoding transformation runs.
Details
The default value is specified in terms of the Encoded type (before any decoding transformations).
Options:
- encodingStrategy: - "passthrough" (default): include the value in the encoded output. - "omit": omit the key from the encoded output.
See
withDecodingDefaultKeyfor the key-level variant (key absent only, notundefined)withDecodingDefaultTypefor the variant where the default is aTypevalue
Signature
declare function withDecodingDefault<S extends Constraint, R = never>(
defaultValue: Effect<S["Encoded"], SchemaError, R>,
options?: DecodingDefaultOptions,
): (self: S) => withDecodingDefault<S, R>;withDecodingDefault interface
Type-level representation returned by withDecodingDefault.
Signature
interface withDecodingDefault<S extends Constraint, R = never> extends decodeTo<
S,
optional<toEncoded<S>>,
R
> {
constructor(_: never);
readonly Rebuild: withDecodingDefault<S, R>;
}withDecodingDefaultKey
Makes a struct key optional on the Encoded side and provides a default Encoded value when the key is missing during decoding.
Details
The key uses optionalKey on the encoded side, so it may be absent from the input object but not undefined. The default value is specified in terms of the Encoded type (before any decoding transformations).
Options:
- encodingStrategy: - "passthrough" (default): include the value in the encoded output. - "omit": omit the key from the encoded output.
See
withDecodingDefaultfor the value-level variant (key absent orundefined)withDecodingDefaultTypeKeyfor the variant where the default is aTypevalue
Signature
declare function withDecodingDefaultKey<S extends Constraint, R = never>(
defaultValue: Effect<S["Encoded"], SchemaError, R>,
options?: DecodingDefaultOptions,
): (self: S) => withDecodingDefaultKey<S, R>;withDecodingDefaultKey interface
Type-level representation returned by withDecodingDefaultKey.
Signature
interface withDecodingDefaultKey<S extends Constraint, R = never> extends decodeTo<
S,
optionalKey<toEncoded<S>>,
R
> {
constructor(_: never);
readonly Rebuild: withDecodingDefaultKey<S, R>;
}withDecodingDefaultType
Wraps the Encoded side with optional (key absent or undefined) and provides a default Type value when the field is missing or undefined during decoding.
When to use
Use when the default is already in the decoded representation and should not pass through the field's decoding transformation.
Details
Unlike withDecodingDefault, the default value is specified in terms of the Type (decoded) representation, so it does not need to go through the decoding transformation.
Options:
- encodingStrategy: - "passthrough" (default): include the value in the encoded output. - "omit": omit the key from the encoded output.
See
withDecodingDefaultfor the variant where the default is anEncodedvaluewithDecodingDefaultTypeKeyfor the key-level variant
Signature
declare function withDecodingDefaultType<S extends Constraint, R = never>(
defaultValue: Effect<S["Type"], SchemaError, R>,
options?: DecodingDefaultOptions,
): (self: S) => withDecodingDefaultType<S, R>;withDecodingDefaultType interface
Type-level representation returned by withDecodingDefaultType.
Signature
interface withDecodingDefaultType<S extends Constraint, R = never> extends decodeTo<
withDecodingDefault<toType<S>, R>,
optional<S>
> {
constructor(_: never);
readonly Rebuild: withDecodingDefaultType<S, R>;
}withDecodingDefaultTypeKey
Makes a struct key optional on the Encoded side (optionalKey, so the key may be absent but not undefined) and provides a default Type value when the key is missing during decoding.
Details
Unlike withDecodingDefaultKey, the default value is specified in terms of the Type (decoded) representation, so it does not need to go through the decoding transformation.
Options:
- encodingStrategy: - "passthrough" (default): include the value in the encoded output. - "omit": omit the key from the encoded output.
See
withDecodingDefaultKeyfor the variant where the default is anEncodedvaluewithDecodingDefaultTypefor the value-level variant
Signature
declare function withDecodingDefaultTypeKey<S extends Constraint, R = never>(
defaultValue: Effect<S["Type"], SchemaError, R>,
options?: DecodingDefaultOptions,
): (self: S) => withDecodingDefaultTypeKey<S, R>;withDecodingDefaultTypeKey interface
Type-level representation returned by withDecodingDefaultTypeKey.
Signature
interface withDecodingDefaultTypeKey<S extends Constraint, R = never> extends decodeTo<
withDecodingDefaultKey<toType<S>, R>,
optionalKey<S>
> {
constructor(_: never);
readonly Rebuild: withDecodingDefaultTypeKey<S, R>;
}Encoding
encodeEffect
Encodes a typed input (the schema's Type) against a schema, returning an Effect that succeeds with the encoded value or fails with a SchemaError.
When to use
Use when you need to encode input already typed as the schema's Type in an Effect whose failure channel is SchemaError.
Details
For unknown input use encodeUnknownEffect. Options may be provided either when creating the encoder or when applying it; application options override creation options.
See
SchemaParser.encodeEffect for the adapter that fails withSchemaIssue.Issuedirectly
Signature
declare const encodeEffect: <S extends Constraint>(
schema: S,
options?: SchemaAST.ParseOptions,
) => (
input: S["Type"],
options?: SchemaAST.ParseOptions,
) => Effect.Effect<S["Encoded"], SchemaError, S["EncodingServices"]>;encodeExit
Encodes a typed input (the schema's Type) against a schema synchronously, returning an Exit that is either a Success with the encoded value or a Failure.
When to use
Use when you need to encode already typed schema values into an Exit and capture schema mismatches as SchemaError.
Details
Only usable with schemas that have no EncodingServices requirement. For unknown input use encodeUnknownExit. Options may be provided either when creating the encoder or when applying it; application options override creation options. Schema mismatches are represented by a Failure cause containing SchemaError.
Gotchas
Schema issue fail reasons are wrapped as SchemaError. Defects, interruptions, and other non-schema reasons remain in the returned Cause, including when they are mixed with schema issues.
See
SchemaParser.encodeExit for the adapter whose failure containsSchemaIssue.Issuedirectly
Signature
declare const encodeExit: <S extends ConstraintEncoder<unknown>>(
schema: S,
options?: SchemaAST.ParseOptions,
) => (input: S["Type"], options?: SchemaAST.ParseOptions) => Exit_.Exit<S["Encoded"], SchemaError>;encodeOption
Encodes a typed input (the schema's Type) against a schema, returning an Option that is Some with the encoded value on success or None for schema mismatches.
When to use
Use when you already have a value typed as the schema's Type and only need to know whether encoding succeeded.
Details
For unknown input use encodeUnknownOption. Options may be provided either when creating the encoder or when applying it; application options override creation options.
Gotchas
Only causes made entirely of schema issues are converted to None. Causes that contain defects, interruptions, or other non-schema reasons throw instead.
Signature
declare const encodeOption: <S extends ConstraintEncoder<unknown>>(
schema: S,
options?: SchemaAST.ParseOptions,
) => (input: S["Type"], options?: SchemaAST.ParseOptions) => Option_.Option<S["Encoded"]>;encodePromise
Encodes a typed input (the schema's Type) against a schema, returning a Promise that resolves with the encoded value or rejects with a SchemaError for schema mismatches.
When to use
Use when you already have a value typed as the schema's Type and need encoding to return a JavaScript Promise that rejects with SchemaError for schema mismatches.
Details
For unknown input use encodeUnknownPromise. Options may be provided either when creating the encoder or when applying it; application options override creation options.
Gotchas
Non-schema failures may reject with a runtime failure instead of SchemaError.
See
SchemaParser.encodePromise for the adapter that rejects with anErrorwhose cause isSchemaIssue.Issue
Signature
declare const encodePromise: <S extends ConstraintEncoder<unknown>>(
schema: S,
options?: SchemaAST.ParseOptions,
) => (input: S["Type"], options?: SchemaAST.ParseOptions) => Promise<S["Encoded"]>;encodeResult
Encodes a typed input (the schema's Type) against a schema, returning a Result that succeeds with the encoded value or fails with a SchemaError for schema mismatches.
When to use
Use when you already have a value typed as the schema's Type and want schema mismatches returned as Result.fail with SchemaError.
Details
For unknown input use encodeUnknownResult. Options may be provided either when creating the encoder or when applying it; application options override creation options. Schema mismatches are returned as Result.fail with SchemaError.
Gotchas
Only causes made entirely of schema issues are returned as Result.fail. Causes that contain defects, interruptions, or other non-schema reasons throw instead.
See
SchemaParser.encodeResult for the adapter that fails withSchemaIssue.Issuedirectly
Signature
declare const encodeResult: <S extends ConstraintEncoder<unknown>>(
schema: S,
options?: SchemaAST.ParseOptions,
) => (
input: S["Type"],
options?: SchemaAST.ParseOptions,
) => Result_.Result<S["Encoded"], SchemaError>;encodeSync
Encodes a typed input (the schema's Type) against a schema synchronously, throwing a SchemaError for schema mismatches.
When to use
Use when you already have a value typed as the schema's Type and want schema mismatches to throw SchemaError synchronously.
Details
For unknown input use encodeUnknownSync. Options may be provided either when creating the encoder or when applying it; application options override creation options.
Gotchas
Non-schema failures may throw a runtime failure instead of SchemaError.
See
SchemaParser.encodeSync for the adapter that throws anErrorwhose cause isSchemaIssue.Issue
Signature
declare const encodeSync: <S extends ConstraintEncoder<unknown>>(
schema: S,
options?: SchemaAST.ParseOptions,
) => (input: S["Type"], options?: SchemaAST.ParseOptions) => S["Encoded"];encodeUnknownEffect
Encodes an unknown input against a schema, returning an Effect that succeeds with the encoded value or fails with a SchemaError.
When to use
Use when you need to encode unknown input in an Effect whose failure channel is SchemaError.
Details
Prefer encodeEffect when the value is already typed as the schema's Type. Options may be provided either when creating the encoder or when applying it; application options override creation options.
See
SchemaParser.encodeUnknownEffect for the adapter that fails withSchemaIssue.Issuedirectly
Signature
declare function encodeUnknownEffect<S extends Constraint>(
schema: S,
options?: ParseOptions,
): (
input: unknown,
options?: ParseOptions,
) => Effect<S["Encoded"], SchemaError, S["EncodingServices"]>;encodeUnknownExit
Encodes an unknown input against a schema synchronously, returning an Exit that is either a Success with the encoded value or a Failure.
When to use
Use when you need to encode unknown input into an Exit and capture schema mismatches as SchemaError.
Details
Only usable with schemas that have no EncodingServices requirement. Prefer encodeExit when the value is already typed as the schema's Type. Options may be provided either when creating the encoder or when applying it; application options override creation options. Schema mismatches are represented by a Failure cause containing SchemaError.
Gotchas
Schema issue fail reasons are wrapped as SchemaError. Defects, interruptions, and other non-schema reasons remain in the returned Cause, including when they are mixed with schema issues.
See
SchemaParser.encodeUnknownExit for the adapter whose failure containsSchemaIssue.Issuedirectly
Signature
declare function encodeUnknownExit<S extends ConstraintEncoder<unknown, never>>(
schema: S,
options?: ParseOptions,
): (input: unknown, options?: ParseOptions) => Exit<S["Encoded"], SchemaError>;encodeUnknownOption
Encodes an unknown input against a schema, returning an Option that is Some with the encoded value on success or None for schema mismatches.
When to use
Use when you do not know the input type statically and only need to know whether encoding succeeded.
Details
Prefer this over encodeUnknownExit or encodeUnknownEffect when you don't need error details. For values already typed as the schema's Type use encodeOption. Options may be provided either when creating the encoder or when applying it; application options override creation options.
Gotchas
Only causes made entirely of schema issues are converted to None. Causes that contain defects, interruptions, or other non-schema reasons throw instead.
Signature
declare const encodeUnknownOption: <S extends ConstraintEncoder<unknown>>(
schema: S,
options?: SchemaAST.ParseOptions,
) => (input: unknown, options?: SchemaAST.ParseOptions) => Option_.Option<S["Encoded"]>;encodeUnknownPromise
Encodes an unknown input against a schema, returning a Promise that resolves with the encoded value or rejects with a SchemaError for schema mismatches.
When to use
Use when you need encoding of unknown input to return a JavaScript Promise that rejects with SchemaError for schema mismatches.
Details
For values already typed as the schema's Type use encodePromise. Options may be provided either when creating the encoder or when applying it; application options override creation options.
Gotchas
Non-schema failures may reject with a runtime failure instead of SchemaError.
See
SchemaParser.encodeUnknownPromise for the adapter that rejects with anErrorwhose cause isSchemaIssue.Issue
Signature
declare function encodeUnknownPromise<S extends ConstraintEncoder<unknown, never>>(
schema: S,
options?: ParseOptions,
): (input: unknown, options?: ParseOptions) => Promise<S["Encoded"]>;encodeUnknownResult
Encodes an unknown input against a schema, returning a Result that succeeds with the encoded value or fails with a SchemaError for schema mismatches.
When to use
Use when you do not know the input type statically and want schema mismatches returned as Result.fail with SchemaError.
Details
For values already typed as the schema's Type use encodeResult. Options may be provided either when creating the encoder or when applying it; application options override creation options. Schema mismatches are returned as Result.fail with SchemaError.
Gotchas
Only causes made entirely of schema issues are returned as Result.fail. Causes that contain defects, interruptions, or other non-schema reasons throw instead.
See
SchemaParser.encodeUnknownResult for the adapter that fails withSchemaIssue.Issuedirectly
Signature
declare function encodeUnknownResult<S extends ConstraintEncoder<unknown, never>>(
schema: S,
options?: ParseOptions,
): (input: unknown, options?: ParseOptions) => Result<S["Encoded"], SchemaError>;encodeUnknownSync
Encodes an unknown input against a schema synchronously, throwing a SchemaError for schema mismatches.
When to use
Use when you need to serialize unknown data at a synchronous boundary and want schema mismatches to throw SchemaError.
Details
For alternatives that do not throw on schema mismatches, see encodeUnknownOption, encodeUnknownExit, or encodeUnknownEffect. For values already typed as the schema's Type use encodeSync. Options may be provided either when creating the encoder or when applying it; application options override creation options.
Gotchas
Non-schema failures may throw a runtime failure instead of SchemaError.
See
SchemaParser.encodeUnknownSync for the adapter that throws anErrorwhose cause isSchemaIssue.Issue
Signature
declare function encodeUnknownSync<S extends ConstraintEncoder<unknown, never>>(
schema: S,
options?: ParseOptions,
): (input: unknown, options?: ParseOptions) => S["Encoded"];middlewareEncoding
Intercepts the encoding pipeline of a schema.
Details
The provided function receives the current encoding Effect and ParseOptions, and returns a new Effect — potentially adding service requirements (RE), recovering from errors, or augmenting the result.
See
catchEncodingfor a simpler error-recovery variant
Signature
declare function middlewareEncoding<S extends Constraint, RE>(
encode: (
effect: Effect<Option<S["Encoded"]>, Issue, S["EncodingServices"]>,
options: ParseOptions,
) => Effect<Option<S["Encoded"]>, Issue, RE>,
): (schema: S) => middlewareEncoding<S, RE>;middlewareEncoding interface
Type-level representation returned by middlewareEncoding.
Signature
interface middlewareEncoding<S extends Constraint, RE> extends BottomLazy<
S["ast"],
middlewareEncoding<S, RE>,
S["~type.parameters"],
S["~type.mutability"],
S["~type.optionality"],
S["~type.constructor.default"],
S["~encoded.mutability"],
S["~encoded.optionality"]
> {
constructor(_: never);
readonly "~type.make": S["~type.make"];
readonly "~type.make.in": S["~type.make.in"];
readonly DecodingServices: S["DecodingServices"];
readonly Encoded: S["Encoded"];
readonly EncodingServices: RE;
readonly Iso: S["Iso"];
readonly schema: S;
readonly Type: S["Type"];
}toEncoderXml
Derives an XML encoder from a codec.
Details
The returned function encodes a value through toCodecStringTree and returns an Effect that succeeds with the XML string or fails with SchemaError if codec encoding fails.
Signature
declare function toEncoderXml<T, RE>(
codec: ConstraintCodec<T, unknown, unknown, RE>,
options?: XmlEncoderOptions,
): (t: T) => Effect<string, SchemaError, RE>;Error Handling
catchDecoding
Recovers from a decoding error by providing a fallback value.
Details
The handler receives the Issue and returns an Effect that either succeeds with a fallback value or re-fails with a (possibly different) issue.
See
catchDecodingWithContextto add service requirements to the handler
Signature
declare function catchDecoding<S extends Constraint>(
f: (issue: Issue) => Effect<Option<S["Type"]>, Issue>,
): (self: S) => middlewareDecoding<S, S["DecodingServices"]>;catchDecodingWithContext
Recovers from a decoding error with a handler that may require Effect services.
When to use
Use when you need decoding fallback logic to require services from the Effect context.
Details
The handler receives the Issue and returns an Effect that either succeeds with a fallback value or re-fails with a (possibly different) issue. The handler's services are added to the schema's decoding services.
See
catchDecodingfor recovery handlers that do not require servicesmiddlewareDecodingfor intercepting or replacing the full decoding pipeline
Signature
declare function catchDecodingWithContext<S extends Constraint, R = never>(
f: (issue: Issue) => Effect<Option<S["Type"]>, Issue, R>,
): (self: S) => middlewareDecoding<S, R | S["DecodingServices"]>;catchEncoding
Recovers from an encoding error by providing a fallback value.
Details
The handler receives the Issue and returns an Effect that either succeeds with a fallback value or re-fails with a (possibly different) issue.
See
catchEncodingWithContextto add service requirements to the handler
Signature
declare function catchEncoding<S extends Constraint>(
f: (issue: Issue) => Effect<Option<S["Encoded"]>, Issue>,
): (self: S) => middlewareEncoding<S, S["EncodingServices"]>;catchEncodingWithContext
Recovers from an encoding error with a handler that may require Effect services.
When to use
Use when you need encoding fallback logic to require services from the Effect context.
Details
The handler receives the Issue and returns an Effect that either succeeds with a fallback encoded value or re-fails with a (possibly different) issue. The handler's services are added to the schema's encoding services.
See
catchEncodingfor recovery handlers that do not require servicesmiddlewareEncodingfor intercepting or replacing the full encoding pipeline
Signature
declare function catchEncodingWithContext<S extends Constraint, R = never>(
f: (issue: Issue) => Effect<Option<S["Encoded"]>, Issue, R>,
): (self: S) => middlewareEncoding<S, R | S["EncodingServices"]>;Errors
SchemaError
Error thrown (or returned as the error channel value) when schema decoding or encoding fails.
Details
The issue field contains a structured Issue tree describing every validation failure, including the path to the problematic value and the expected type or constraint. Built-in issues have no actual field, and built-in messages do not include the rejected value. Other Issue fields and custom annotations or messages are not sanitized. message renders the issue tree as a human-readable string.
Use isSchemaError to narrow an unknown value to SchemaError.
Signature
declare class SchemaError extends YieldableError<this> & {
readonly _tag: "SchemaError";
} & Readonly<{
readonly issue: Issue;
}> {
constructor(issue: Issue);
readonly "~effect/SchemaError/SchemaError": "~effect/SchemaError/SchemaError";
message: string;
toString(): string;
}Filtering
Attaches one or more filter checks to a schema without changing the TypeScript type.
Signature
declare function check<S extends Top>(
...checks: readonly [Check<S["Type"]>, Check<S["Type"]>]
): (self: S) => S["Rebuild"];Narrows the TypeScript type of a schema's output via a type guard predicate, attaching the guard as a runtime filter check.
Details
The annotations parameter annotates the filter created by the refinement. With the default formatter, failed refinements use message first, expected second, and <filter> when neither is provided. identifier names type-level failures before the refinement runs; it does not name the failed refinement itself.
Signature
declare function refine<S extends Constraint, T extends unknown>(
refinement: (value: S["Type"]) => value is T,
annotations?: Filter,
): (schema: S) => refine<T, S>;Type-level representation returned by refine.
Signature
interface refine<T extends S["Type"], S extends Constraint> extends BottomLazy<
S["ast"],
refine<T, S>,
S["~type.parameters"],
S["~type.mutability"],
S["~type.optionality"],
S["~type.constructor.default"],
S["~encoded.mutability"],
S["~encoded.optionality"]
> {
constructor(_: never);
readonly "~type.make": T;
readonly "~type.make.in": S["~type.make.in"];
readonly DecodingServices: S["DecodingServices"];
readonly Encoded: S["Encoded"];
readonly EncodingServices: S["EncodingServices"];
readonly Iso: T;
readonly schema: S;
readonly Type: T;
}Formatting
overrideToFormatter
Attaches a custom formatter used by toFormatter.
Details
Use this when the formatter derived from the schema structure is not suitable. The annotation is applied through this helper because adding it directly to Annotations.Bottom would make schemas invariant.
Signature
declare function overrideToFormatter<S extends Top>(
toFormatter: () => Formatter<S["Type"]>,
): (self: S) => S["Rebuild"];toFormatter
Derives a string formatter function from a schema. The formatter converts a value to its human-readable string representation, recursing into structs, arrays, and unions.
Details
The optional onBefore hook lets you intercept specific AST nodes before the default formatting logic runs.
Signature
declare function toFormatter<S extends Constraint>(
schema: S,
options?: {
readonly onBefore?: (
ast: AST,
recur: (ast: AST) => Formatter<any>,
) => Formatter<any, string> | undefined;
},
): Formatter<S["Type"]>;Generators
toArbitrary
Derives a fast-check Arbitrary from a schema for property-based testing. The derived arbitrary generates values that satisfy the schema.
Details
Constraints refine base generators; candidates add weighted sources while filters still validate every value. { report: true } returns warnings such as OpaqueFilter, while derivation errors remain fail-fast. Recursive schemas use terminal branches and fail when no finite terminal path exists.
Signature
declare function toArbitrary<S extends Constraint>(schema: S): Arbitrary<S["Type"]>;
declare function toArbitrary<S extends Constraint>(
schema: S,
options: {
readonly report: true;
},
): WithReport<Arbitrary<S["Type"]>>;toArbitraryLazy
Derives a LazyArbitrary from a schema. The result is memoized so repeated calls with the same schema are cheap.
Details
Prefer toArbitrary when you need the arbitrary directly, or when you want derivation diagnostics via { report: true }. Unsupported schema nodes, impossible constraints, invalid candidates, and recursive schemas without a finite terminal path fail immediately.
Signature
declare function toArbitraryLazy<S extends Constraint>(schema: S): LazyArbitrary<S["Type"]>;Getters
resolveAnnotations
Resolves the typed annotations from a schema. The term "resolve" (rather than "get") reflects the lookup strategy: if the schema has checks, the annotations are taken from the last check; otherwise they are taken from the base schema instance.
Signature
declare function resolveAnnotations<S extends Constraint>(
schema: S,
): Bottom<S["Type"], S["~type.parameters"]> | undefined;resolveAnnotationsKey
Resolves the context (key-level) annotations from a schema. Context annotations are those attached via annotateKey and live on the AST's context rather than on the schema node itself.
Signature
declare function resolveAnnotationsKey<S extends Constraint>(schema: S): Key<S["Type"]> | undefined;Guards
Creates an assertion function that throws an error if the input does not match the schema.
When to use
Use to validate unknown input at runtime while narrowing the value with a TypeScript assertion signature.
Details
The input is narrowed if the assertion succeeds. If schema validation fails, the assertion throws an Error whose cause is SchemaIssue.Issue.
Gotchas
Causes that contain defects, interruptions, or other non-schema reasons throw with the underlying Cause attached instead of being converted to schema validation errors.
Signature
declare const asserts: <S extends Constraint, I>(
schema: S,
input: I,
) => asserts input is I & S["Type"];Creates a type guard function that checks if a value conforms to a given schema.
Details
This function returns a predicate that performs a type-safe check, narrowing the type of the input value if the check passes. The predicate returns false for schema mismatches.
Gotchas
Only causes made entirely of schema issues are converted to false. Causes that contain defects, interruptions, or other non-schema reasons throw instead.
Signature
declare const is: <S extends Constraint>(schema: S) => <I>(input: I) => input is I & S["Type"];Checks whether a value is a Schema.
Signature
declare function isSchema(u: unknown): u is Top;isSchemaError
Returns true if u is a SchemaError.
Signature
declare function isSchemaError(u: unknown): u is SchemaError;Instances
overrideToEquivalence
Overrides the equivalence derivation for a schema by supplying a custom Equivalence.
When to use
Use when you need a custom equivalence instead of the default structural equivalence derived by toEquivalence.
Signature
declare function overrideToEquivalence<S extends Top>(
toEquivalence: () => Equivalence<S["Type"]>,
): (self: S) => S["Rebuild"];toEquivalence
Derives an Equivalence from a schema. Two values are considered equal when every field (and nested field) compares equal according to the schema structure.
Signature
declare function toEquivalence<T>(schema: Schema<T>): Equivalence<T>;Models
Type-level representation returned by Array.
Signature
interface $Array<S extends Constraint> extends BottomLazy<SchemaAST.Arrays, $Array<S>> {
constructor(_: never);
readonly "~type.make": readonly Array<S["~type.make"]>;
readonly "~type.make.in": readonly Array<S["~type.make"]>;
readonly DecodingServices: S["DecodingServices"];
readonly Encoded: readonly Array<S["Encoded"]>;
readonly EncodingServices: S["EncodingServices"];
readonly Iso: readonly Array<S["Iso"]>;
readonly Type: readonly Array<S["Type"]>;
readonly value: S;
}$ReadonlyMap interface
Type-level representation returned by ReadonlyMap.
Signature
interface $ReadonlyMap<Key extends Constraint, Value extends Constraint> extends declareConstructor<
globalThis.ReadonlyMap<Key["Type"], Value["Type"]>,
globalThis.ReadonlyMap<Key["Encoded"], Value["Encoded"]>,
readonly [Key, Value],
ReadonlyMapIso<Key, Value>
> {
constructor(_: never);
readonly key: Key;
readonly Rebuild: $ReadonlyMap<Key, Value>;
readonly value: Value;
}$ReadonlySet interface
Type-level representation returned by ReadonlySet.
Signature
interface $ReadonlySet<Value extends Constraint> extends declareConstructor<
globalThis.ReadonlySet<Value["Type"]>,
globalThis.ReadonlySet<Value["Encoded"]>,
readonly [Value],
ReadonlySetIso<Value>
> {
constructor(_: never);
readonly Rebuild: $ReadonlySet<Value>;
readonly value: Value;
}Type-level representation returned by Record.
Signature
interface $Record<Key extends Record.Key, Value extends Constraint> extends BottomLazy<
SchemaAST.Objects,
$Record<Key, Value>
> {
constructor(_: never);
readonly "~type.make": { [K in string | number | symbol]: MakeIn<Key, Value>[K] };
readonly "~type.make.in": { [K in string | number | symbol]: MakeIn<Key, Value>[K] };
readonly DecodingServices: DecodingServices<Key, Value>;
readonly Encoded: Encoded<Key, Value>;
readonly EncodingServices: EncodingServices<Key, Value>;
readonly Iso: Iso<Key, Value>;
readonly key: Key;
readonly Type: Type<Key, Value>;
readonly value: Value;
}Type-level representation of Any.
Signature
interface Any extends Bottom<any, any, never, never, SchemaAST.Any, Any> {
constructor(_: never);
}BigDecimal interface
Type-level representation of BigDecimal.
Signature
interface BigDecimal extends declare<BigDecimal_.BigDecimal> {
constructor(_: never);
readonly Rebuild: BigDecimal;
}BigDecimalFromString interface
Type-level representation of BigDecimalFromString.
Signature
interface BigDecimalFromString extends decodeTo<BigDecimal, String> {
constructor(_: never);
readonly Rebuild: BigDecimalFromString;
}Type-level representation of BigInt.
Signature
interface BigInt extends Bottom<bigint, bigint, never, never, SchemaAST.BigInt, BigInt> {
constructor(_: never);
}BigIntFromString interface
Type-level representation of BigIntFromString.
Signature
interface BigIntFromString extends decodeTo<BigInt, String> {
constructor(_: never);
readonly Rebuild: BigIntFromString;
}Type-level representation of Boolean.
Signature
interface Boolean extends Bottom<boolean, boolean, never, never, SchemaAST.Boolean, Boolean> {
constructor(_: never);
}BooleanFromBit interface
Type-level representation of BooleanFromBit.
Signature
interface BooleanFromBit extends decodeTo<Boolean, Literals<readonly [0, 1]>> {
constructor(_: never);
readonly Rebuild: BooleanFromBit;
}BottomWithoutNew interface
The fully-parameterized schema interface without a construct signature. Exposes all 14 type parameters controlling type inference, mutability, optionality, services, and transformation behavior.
When to use
Use as the base for schema interfaces that provide a specialized construct signature.
Signature
interface BottomWithoutNew<
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",
> extends Pipeable {
readonly "~effect/Schema/Schema": "~effect/Schema/Schema";
readonly "~encoded.mutability": EncodedMutability;
readonly "~encoded.optionality": EncodedOptionality;
readonly "~type.constructor.default": TypeConstructorDefault;
readonly "~type.make": TypeMake;
readonly "~type.make.in": TypeMakeIn;
readonly "~type.mutability": TypeMutability;
readonly "~type.optionality": TypeOptionality;
readonly "~type.parameters": TypeParameters;
readonly ast: Ast;
readonly DecodingServices: RD;
readonly Encoded: E;
readonly EncodingServices: RE;
Iso: Iso;
Rebuild: Rebuild;
readonly Type: T;
annotate(annotations: Bottom<T, TypeParameters>): Rebuild;
annotateKey(annotations: Key<T>): Rebuild;
check(...checks: readonly [Check<T>, Check<T>]): Rebuild;
make(input: TypeMakeIn, options?: MakeOptions): T;
makeEffect(input: TypeMakeIn, options?: MakeOptions): Effect<T, SchemaError>;
makeOption(input: TypeMakeIn, options?: MakeOptions): Option<T>;
rebuild(ast: Ast): Rebuild;
}Type-level representation returned by Cause.
Signature
interface Cause<E extends Constraint, D extends Constraint> extends declareConstructor<
Cause_.Cause<E["Type"]>,
Cause_.Cause<E["Encoded"]>,
readonly [E, D],
CauseIso<E, D>
> {
constructor(_: never);
readonly defect: D;
readonly error: E;
readonly Rebuild: Cause<E, D>;
}CauseReason interface
Type-level representation returned by CauseReason.
Signature
interface CauseReason<E extends Constraint, D extends Constraint> extends declareConstructor<
Cause_.Reason<E["Type"]>,
Cause_.Reason<E["Encoded"]>,
readonly [E, D],
CauseReasonIso<E, D>
> {
constructor(_: never);
readonly defect: D;
readonly error: E;
readonly Rebuild: CauseReason<E, D>;
}Type-level representation of Char.
Signature
interface Char extends String {
constructor(_: never);
readonly Rebuild: Char;
}Type-level representation returned by Chunk.
Signature
interface Chunk<Value extends Constraint> extends declareConstructor<
Chunk_.Chunk<Value["Type"]>,
Chunk_.Chunk<Value["Encoded"]>,
readonly [Value],
ChunkIso<Value>
> {
constructor(_: never);
readonly Rebuild: Chunk<Value>;
readonly value: Value;
}Type-level representation returned by Class.
Signature
interface Class<Self, S extends Constraint & {
readonly fields: Struct.Fields;
}, Inherited> extends BottomLazyWithoutNew<SchemaAST.Declaration, decodeTo<declareConstructor<Self, S["Encoded"], readonly [S], S["Iso"]>, S>, readonly [S], S["~type.mutability"], S["~type.optionality"], S["~type.constructor.default"], S["~encoded.mutability"], S["~encoded.optionality"]> {
constructor(...args: {} extends S["~type.make.in"] ? [props?: S["~type.make.in"], options?: MakeOptions] : [props: S["~type.make.in"], options?: MakeOptions]);
readonly "~type.make": Self;
readonly "~type.make.in": RequiredKeys<S["~type.make.in"]> extends never ? void | S["~type.make.in"] : S["~type.make.in"];
readonly DecodingServices: S["DecodingServices"];
readonly Encoded: S["Encoded"];
readonly EncodingServices: S["EncodingServices"];
readonly fields: S["fields"];
readonly identifier: string;
readonly Iso: S["Iso"];
readonly Type: Self;
extend<Extended = never, Static = {}, Brand = {}>(identifier: string): {
<NewFields extends Fields>(fields: NewFields, annotations?: Declaration<Extended, readonly [Struct<{ [K in string | number | symbol]: { [K in string | number | symbol]: ... & ... extends never ? ... & ... : ... & ...[K] }[K] }>]>): [Extended] extends [never] ? "Missing `Self` generic - use `class Self extends Base.extend<Self>(...)`" : InheritStaticMembers<Class<Extended, Struct<{ [K in string | number | symbol]: { [K in string | number | symbol]: ... & ... extends never ? ... & ... : ... & ...[K] }[K] }>, Self & Brand>, Static>;
<Extension extends Struct<Fields>>(schema: Extension, annotations?: Declaration<Extended, readonly [Struct<{ [K in string | number | symbol]: { [K in string | number | symbol]: ... & ... extends never ? ... & ... : ... & ...[K] }[K] }>]>): [Extended] extends [never] ? "Missing `Self` generic - use `class Self extends Base.extend<Self>(...)`" : InheritStaticMembers<Class<Extended, Struct<{ [K in string | number | symbol]: { [K in string | number | symbol]: ... & ... extends never ? ... & ... : ... & ...[K] }[K] }>, Self & Brand>, Static>;
};
mapFields<To extends Fields>(f: (fields: S["fields"]) => To, options?: {
readonly unsafePreserveChecks?: boolean;
}): Struct<{ [K in string | number | symbol]: Readonly<To>[K] }>;
}A schema that tracks the decoded type T, the encoded type E, and the Effect services required during decoding (RD) and encoding (RE).
Details
Use Codec<T, E, RD, RE> when you need to preserve full type information about a schema — both what it decodes to and what it serializes from/to. Most concrete schemas produced by this module implement Codec.
For APIs that only need one direction, prefer the narrower views: - Decoder<T, RD> — decode-only - Encoder<E, RE> — encode-only - Schema<T> — type-only (no encoded representation)
See
Codec.Encoded — extract the encoded typeCodec.DecodingServices — extract required decoding servicesCodec.EncodingServices — extract required encoding servicesrevealCodec— helper to make TypeScript infer the full Codec type
Signature
interface Codec<out T, out E = T, out RD = never, out RE = never> extends Schema<T> {
constructor(_: never);
readonly DecodingServices: RD;
readonly Encoded: E;
readonly EncodingServices: RE;
readonly Rebuild: Codec<T, E, RD, RE>;
}Constraint interface
Lightweight structural constraint for APIs that accept schema values but only read their data and type-level views.
When to use
Use when you need to constrain a generic value to be a schema, but the API only reads properties such as ast, Type, Encoded, service requirements, constructor input views, or modifier flags.
Details
Constraint keeps the schema type identifier and the property surface needed by schema constructors, while avoiding the full Bottom protocol. Use Top when an API calls schema methods such as annotate, check, rebuild, make, or makeEffect.
See
Topfor the complete schema protocol.
Signature
interface Constraint {
readonly "~effect/Schema/Schema": "~effect/Schema/Schema";
readonly "~encoded.mutability": Mutability;
readonly "~encoded.optionality": Optionality;
readonly "~type.constructor.default": ConstructorDefault;
readonly "~type.make": unknown;
readonly "~type.make.in": unknown;
readonly "~type.mutability": Mutability;
readonly "~type.optionality": Optionality;
readonly "~type.parameters": any;
readonly ast: AST;
readonly DecodingServices: unknown;
readonly Encoded: unknown;
readonly EncodingServices: unknown;
readonly Iso: unknown;
readonly Type: unknown;
}ConstraintCodec interface
Lightweight structural constraint for APIs that need codec type views but do not need the full schema protocol.
When to use
Use when you need to preserve decoded type, encoded type, and service requirements for a schema value, but the API does not call schema methods such as annotate, check, rebuild, make, or makeEffect.
See
Constraintfor the generic lightweight schema constraint.Codecfor the full schema protocol with codec type views.
Signature
interface ConstraintCodec<out T, out E = T, out RD = never, out RE = never> extends Constraint {
readonly DecodingServices: RD;
readonly Encoded: E;
readonly EncodingServices: RE;
readonly Type: T;
}ConstraintDecoder interface
Lightweight structural constraint for APIs that need decoder type views but do not need the full schema protocol.
When to use
Use when you need to preserve a schema's decoded type and decoding services, but the API does not constrain the encoded type, encoding services, or call schema methods such as annotate, check, rebuild, make, or makeEffect.
See
ConstraintCodecfor APIs that need both decoded and encoded codec views.Codecfor the full schema protocol with codec type views.
Signature
interface ConstraintDecoder<out T, out RD = never> extends ConstraintCodec<
T,
unknown,
RD,
unknown
> {}ConstraintEncoder interface
Lightweight structural constraint for APIs that need encoder type views but do not need the full schema protocol.
When to use
Use when you need to preserve a schema's encoded type and encoding services, but the API does not constrain the decoded type, decoding services, or call schema methods such as annotate, check, rebuild, make, or makeEffect.
See
ConstraintCodecfor APIs that need both decoded and encoded codec views.Codecfor the full schema protocol with codec type views.
Signature
interface ConstraintEncoder<out E, out RE = never> extends ConstraintCodec<
unknown,
E,
unknown,
RE
> {}ConstraintRebuildable interface
Lightweight structural constraint for APIs that need schema views and the rebuilt schema type, but do not call the full schema protocol.
When to use
Use when an API needs to read Rebuild in addition to the schema views exposed by Constraint, but does not call methods such as annotate, check, rebuild, make, or makeEffect.
Signature
interface ConstraintRebuildable extends Constraint {
readonly Rebuild: Constraint;
}ConstructorDefault type
Whether a schema field has a constructor default value.
See
withConstructorDefault— add a default to a schema fieldtag— creates a literal field with a constructor default
Signature
type ConstructorDefault = "no-default" | "with-default";Type-level representation of Date.
Signature
interface Date extends declare<globalThis.Date> {
constructor(_: never);
readonly Rebuild: Date;
}DateFromMillis interface
Type-level representation of DateFromMillis.
Signature
interface DateFromMillis extends decodeTo<Date, Int> {
constructor(_: never);
readonly Rebuild: DateFromMillis;
}DateFromString interface
Type-level representation of DateFromString.
Signature
interface DateFromString extends decodeTo<Date, String> {
constructor(_: never);
readonly Rebuild: DateFromString;
}DateTimeUtc interface
Type-level representation of DateTimeUtc.
Signature
interface DateTimeUtc extends declare<DateTime.Utc> {
constructor(_: never);
readonly Rebuild: DateTimeUtc;
}DateTimeUtcFromDate interface
Type-level representation of DateTimeUtcFromDate.
Signature
interface DateTimeUtcFromDate extends decodeTo<DateTimeUtc, Date> {
constructor(_: never);
readonly Rebuild: DateTimeUtcFromDate;
}DateTimeUtcFromMillis interface
Type-level representation of DateTimeUtcFromMillis.
Signature
interface DateTimeUtcFromMillis extends decodeTo<instanceOf<DateTime.Utc>, Int> {
constructor(_: never);
readonly Rebuild: DateTimeUtcFromMillis;
}DateTimeUtcFromString interface
Type-level representation of DateTimeUtcFromString.
Signature
interface DateTimeUtcFromString extends decodeTo<DateTimeUtc, String> {
constructor(_: never);
readonly Rebuild: DateTimeUtcFromString;
}DateTimeZoned interface
Type-level representation of DateTimeZoned.
Signature
interface DateTimeZoned extends declare<DateTime.Zoned> {
constructor(_: never);
readonly Rebuild: DateTimeZoned;
}DateTimeZonedFromString interface
Type-level representation of DateTimeZonedFromString.
Signature
interface DateTimeZonedFromString extends decodeTo<DateTimeZoned, String> {
constructor(_: never);
readonly Rebuild: DateTimeZonedFromString;
}A schema that tracks the decoded type T and the Effect services required during decoding (RD).
When to use
Use when you need to preserve a schema's decoded type and decoding service requirements, but do not need to constrain its encoded representation or encoding services.
See
Signature
interface Decoder<out T, out RD = never> extends Schema<T> {
constructor(_: never);
readonly DecodingServices: RD;
readonly Encoded: unknown;
readonly EncodingServices: unknown;
readonly Rebuild: Decoder<T, RD>;
}Type-level representation of Defect.
Signature
interface Defect extends decodeTo<Unknown, typeof Json> {
constructor(_: never);
readonly Rebuild: Defect;
}Type-level representation of Duration.
Signature
interface Duration extends declare<Duration_.Duration> {
constructor(_: never);
readonly Rebuild: Duration;
}DurationFromMillis interface
Type-level representation of DurationFromMillis.
Signature
interface DurationFromMillis extends decodeTo<Duration, Number> {
constructor(_: never);
readonly Rebuild: DurationFromMillis;
}DurationFromNanos interface
Type-level representation of DurationFromNanos.
Signature
interface DurationFromNanos extends decodeTo<Duration, BigInt> {
constructor(_: never);
readonly Rebuild: DurationFromNanos;
}DurationFromString interface
Type-level representation of DurationFromString.
Signature
interface DurationFromString extends decodeTo<Duration, String> {
constructor(_: never);
readonly Rebuild: DurationFromString;
}A schema that tracks the encoded type E and the Effect services required during encoding (RE).
When to use
Use when you need to preserve a schema's encoded type and encoding service requirements, but do not need to constrain its decoded representation or decoding services.
See
Signature
interface Encoder<out E, out RE = never> extends Schema<unknown> {
constructor(_: never);
readonly DecodingServices: unknown;
readonly Encoded: E;
readonly EncodingServices: RE;
readonly Rebuild: Encoder<E, RE>;
}Type-level representation returned by Enum.
Signature
interface Enum<
A extends {
[x: string]: string | number;
},
> extends Bottom<A[keyof A], A[keyof A], never, never, SchemaAST.Enum, Enum<A>> {
constructor(_: never);
readonly enums: A;
}ErrorInstance interface
Type-level representation of ErrorInstance.
Signature
interface ErrorInstance extends instanceOf<globalThis.Error> {
constructor(_: never);
readonly Rebuild: ErrorInstance;
}Type-level representation returned by Exit.
Signature
interface Exit<
A extends Constraint,
E extends Constraint,
D extends Constraint,
> extends declareConstructor<
Exit_.Exit<A["Type"], E["Type"]>,
Exit_.Exit<A["Encoded"], E["Encoded"]>,
readonly [A, E, D],
ExitIso<A, E, D>
> {
constructor(_: never);
readonly defect: D;
readonly error: E;
readonly Rebuild: Exit<A, E, D>;
readonly value: A;
}Type-level representation of File.
Signature
interface File extends instanceOf<globalThis.File> {
constructor(_: never);
readonly Rebuild: File;
}FilterIssue type
A single failure reported by a filter predicate. Used as the element type of the array arm of FilterOutput, and also accepted on its own.
Details
- string: failure with that string as the message. Produces an SchemaIssue.InvalidValue with the string used as the issue's message annotation. - SchemaIssue.Issue: a fully-formed issue, returned as-is. - { path, issue }: failure attached to a nested path. issue is either a string (wrapped in an SchemaIssue.InvalidValue) or a full SchemaIssue.Issue; the result is wrapped in an SchemaIssue.Pointer at the given path.
Signature
type FilterIssue =
| string
| SchemaIssue.Issue
| {
readonly issue: string | SchemaIssue.Issue;
readonly path: ReadonlyArray<PropertyKey>;
};FilterOutput type
The value a filter predicate (see makeFilter) may return.
Details
Each shape is normalized into an SchemaIssue.Issue (or undefined for success) before being attached to the parse result:
- undefined: success. The input satisfies the filter. - true: success. Equivalent to undefined, useful when the predicate is a plain boolean expression. - false: generic failure. Produces an SchemaIssue.InvalidValue with no custom message. - FilterIssue: a single failure. See FilterIssue for the shapes (string, SchemaIssue.Issue, or { path, issue }). - ReadonlyArray<FilterIssue>: several failures reported together. An empty array is treated as success; a single-element array is equivalent to returning that element directly; otherwise the entries are grouped into an SchemaIssue.Composite.
Signature
type FilterOutput = undefined | boolean | FilterIssue | ReadonlyArray<FilterIssue>;Type-level representation of Finite.
Signature
interface Finite extends Number {
constructor(_: never);
readonly Rebuild: Finite;
}FiniteFromString interface
Type-level representation of FiniteFromString.
Signature
interface FiniteFromString extends decodeTo<Finite, String> {
constructor(_: never);
readonly Rebuild: FiniteFromString;
}Type-level representation of FormData.
Signature
interface FormData extends instanceOf<globalThis.FormData> {
constructor(_: never);
readonly Rebuild: FormData;
}fromFormData interface
Type-level representation returned by fromFormData.
Signature
interface fromFormData<S extends Constraint> extends decodeTo<S, FormData> {
constructor(_: never);
readonly Rebuild: fromFormData<S>;
}fromJsonString interface
Type-level representation returned by fromJsonString.
Signature
interface fromJsonString<S extends Constraint> extends decodeTo<S, String> {
constructor(_: never);
readonly Rebuild: fromJsonString<S>;
}fromURLSearchParams interface
Type-level representation returned by fromURLSearchParams.
Signature
interface fromURLSearchParams<S extends Constraint> extends decodeTo<S, URLSearchParams> {
constructor(_: never);
readonly Rebuild: fromURLSearchParams<S>;
}Type-level representation returned by HashMap.
Signature
interface HashMap<Key extends Constraint, Value extends Constraint> extends declareConstructor<
HashMap_.HashMap<Key["Type"], Value["Type"]>,
HashMap_.HashMap<Key["Encoded"], Value["Encoded"]>,
readonly [Key, Value],
HashMapIso<Key, Value>
> {
constructor(_: never);
readonly key: Key;
readonly Rebuild: HashMap<Key, Value>;
readonly value: Value;
}Type-level representation returned by HashSet.
Signature
interface HashSet<Value extends Constraint> extends declareConstructor<
HashSet_.HashSet<Value["Type"]>,
HashSet_.HashSet<Value["Encoded"]>,
readonly [Value],
HashSetIso<Value>
> {
constructor(_: never);
readonly Rebuild: HashSet<Value>;
readonly value: Value;
}instanceOf interface
Type-level representation returned by instanceOf.
Signature
interface instanceOf<T, Iso = T> extends declare<T, Iso> {
constructor(_: never);
readonly Rebuild: instanceOf<T, Iso>;
}Type-level representation of Int.
Signature
interface Int extends Number {
constructor(_: never);
readonly Rebuild: Int;
}Recursive TypeScript type for any valid immutable JSON value: null, number, boolean, string, a readonly array of Json values, or a readonly record of string → Json. For the corresponding schema, see the Json const.
Signature
type Json = null | number | boolean | string | JsonArray | JsonObject;A readonly array of Json values.
Signature
interface JsonArray extends ReadonlyArray<Json> {
[n: number]: Json;
}JsonObject interface
A readonly record whose values are Json values.
Signature
interface JsonObject {
[x: string]: Json;
}Type-level representation returned by Literal.
Signature
interface Literal<L extends SchemaAST.LiteralValue> extends Bottom<
L,
L,
never,
never,
SchemaAST.Literal,
Literal<L>
> {
constructor(_: never);
readonly literal: L;
transform<L2 extends LiteralValue>(to: L2): decodeTo<Literal<L2>, Literal<L>>;
}Type-level representation returned by Literals.
Signature
interface Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>> extends Bottom<L[number], L[number], never, never, SchemaAST.Union<SchemaAST.Literal>, Literals<L>> {
constructor(_: never);
readonly literals: L;
readonly members: { [K in string | number | symbol]: Literal<L[K]> };
mapMembers<To extends readonly Array<Constraint>>(f: (members: { [K in string | number | symbol]: Literal<L[K]> }) => To): Union<{ [K in string | number | symbol]: Readonly<To>[K] }>;
pick<L2 extends readonly Array<L[number]>>(literals: L2): Literals<L2>;
transform<L2 extends { [I in string | number | symbol]: LiteralValue }>(to: L2): Union<{ [I in string | number | symbol]: decodeTo<Literal<L2[I]>, Literal<L[I]>, never, never> }>;
}Mutability type
Whether a schema field is readonly or mutable within a struct.
See
mutableKey— mark a struct field as mutable
Signature
type Mutability = "readonly" | "mutable";MutableJson type
Recursive TypeScript type for mutable JSON values: null, number, boolean, string, mutable arrays, or mutable string-keyed records.
Signature
type MutableJson = null | number | boolean | string | MutableJsonArray | MutableJsonObject;MutableJsonArray interface
A mutable array of MutableJson values.
Signature
interface MutableJsonArray extends Array<MutableJson> {
[n: number]: MutableJson;
}MutableJsonObject interface
A mutable record whose values are MutableJson values.
Signature
interface MutableJsonObject {
[x: string]: MutableJson;
}mutableKey interface
Type-level representation returned by mutableKey.
Signature
interface mutableKey<S extends Constraint> extends BottomLazy<
S["ast"],
mutableKey<S>,
S["~type.parameters"],
"mutable",
S["~type.optionality"],
S["~type.constructor.default"],
"mutable",
S["~encoded.optionality"]
> {
constructor(_: never);
readonly "~type.make": S["~type.make"];
readonly "~type.make.in": S["~type.make.in"];
readonly DecodingServices: S["DecodingServices"];
readonly Encoded: S["Encoded"];
readonly EncodingServices: S["EncodingServices"];
readonly Iso: S["Iso"];
readonly schema: S;
readonly Type: S["Type"];
}Type-level representation of Natural.
Signature
interface Natural extends Int {
constructor(_: never);
readonly Rebuild: Natural;
}Type-level representation of Never.
Signature
interface Never extends Bottom<never, never, never, never, SchemaAST.Never, Never> {
constructor(_: never);
}NonEmptyArray interface
Type-level representation returned by NonEmptyArray.
Signature
interface NonEmptyArray<S extends Constraint> extends BottomLazy<
SchemaAST.Arrays,
NonEmptyArray<S>
> {
constructor(_: never);
readonly "~type.make": readonly [S["~type.make"], S["~type.make"]];
readonly "~type.make.in": readonly [S["~type.make"], S["~type.make"]];
readonly DecodingServices: S["DecodingServices"];
readonly Encoded: readonly [S["Encoded"], S["Encoded"]];
readonly EncodingServices: S["EncodingServices"];
readonly Iso: readonly [S["Iso"], S["Iso"]];
readonly Type: readonly [S["Type"], S["Type"]];
readonly value: S;
}NonEmptyString interface
Type-level representation of NonEmptyString.
Signature
interface NonEmptyString extends String {
constructor(_: never);
readonly Rebuild: NonEmptyString;
}Type-level representation of Null.
Signature
interface Null extends Bottom<null, null, never, never, SchemaAST.Null, Null> {
constructor(_: never);
}Type-level representation returned by NullishOr.
Signature
interface NullishOr<S extends Constraint> extends Union<readonly [S, Null, Undefined]> {
constructor(_: never);
readonly Rebuild: NullishOr<S>;
}Type-level representation returned by NullOr.
Signature
interface NullOr<S extends Constraint> extends Union<readonly [S, Null]> {
constructor(_: never);
readonly Rebuild: NullOr<S>;
}Type-level representation of Number.
Signature
interface Number extends Bottom<number, number, never, never, SchemaAST.Number, Number> {
constructor(_: never);
}NumberFromString interface
Type-level representation of NumberFromString.
Signature
interface NumberFromString extends decodeTo<Number, String> {
constructor(_: never);
readonly Rebuild: NumberFromString;
}ObjectKeyword interface
Type-level representation of ObjectKeyword.
Signature
interface ObjectKeyword extends Bottom<
object,
object,
never,
never,
SchemaAST.ObjectKeyword,
ObjectKeyword
> {
constructor(_: never);
}Type-level representation returned by Opaque.
Signature
interface Opaque<Self, S extends Top, Brand> extends BottomLazyWithoutNew<
S["ast"],
S["Rebuild"],
S["~type.parameters"],
S["~type.mutability"],
S["~type.optionality"],
S["~type.constructor.default"],
S["~encoded.mutability"],
S["~encoded.optionality"]
> {
constructor(_: never);
readonly "~type.make": S["~type.make"];
readonly "~type.make.in": S["~type.make.in"];
readonly DecodingServices: S["DecodingServices"];
readonly Encoded: S["Encoded"];
readonly EncodingServices: S["EncodingServices"];
readonly Iso: S["Iso"];
readonly Type: Self;
}A schema that additionally supports optic (lens/prism) operations.
Details
Optic<T, Iso> extends Schema<T> with an Iso type that describes the isomorphic counterpart used by the optic layer. Crucially, decoding and encoding require *no* Effect services (DecodingServices and EncodingServices are both never), which means the optic can operate purely without an Effect runtime.
Most primitive schemas (e.g. Schema.String, Schema.Number) implement Optic automatically. You normally interact with this interface through Optic_ utilities rather than constructing it directly.
Signature
interface Optic<out T, out Iso> extends Schema<T> {
constructor(_: never);
readonly DecodingServices: never;
readonly EncodingServices: never;
Iso: Iso;
readonly Rebuild: Optic<T, Iso>;
}Type-level representation returned by Option.
Signature
interface Option<A extends Constraint> extends declareConstructor<
Option_.Option<A["Type"]>,
Option_.Option<A["Encoded"]>,
readonly [A],
OptionIso<A>
> {
constructor(_: never);
readonly Rebuild: Option<A>;
readonly value: A;
}Type-level representation returned by optional.
Signature
interface optional<S extends Constraint> extends optionalKey<UndefinedOr<S>> {
constructor(_: never);
readonly Rebuild: optional<S>;
}Optionality type
Whether a schema field is required or optional within a struct.
See
optionalKey— mark a struct field as optionaloptional— mark a struct field as optional with| undefined
Signature
type Optionality = "required" | "optional";optionalKey interface
Type-level representation returned by optionalKey.
Signature
interface optionalKey<S extends Constraint> extends BottomLazy<
S["ast"],
optionalKey<S>,
S["~type.parameters"],
S["~type.mutability"],
"optional",
S["~type.constructor.default"],
S["~encoded.mutability"],
"optional"
> {
constructor(_: never);
readonly "~type.make": S["~type.make"];
readonly "~type.make.in": S["~type.make.in"];
readonly DecodingServices: S["DecodingServices"];
readonly Encoded: S["Encoded"];
readonly EncodingServices: S["EncodingServices"];
readonly Iso: S["Iso"];
readonly schema: S;
readonly Type: S["Type"];
}OptionFromNullishOr interface
Type-level representation returned by OptionFromNullishOr.
Signature
interface OptionFromNullishOr<S extends Constraint> extends decodeTo<
Option<toType<S>>,
NullishOr<S>
> {
constructor(_: never);
readonly Rebuild: OptionFromNullishOr<S>;
}OptionFromNullOr interface
Type-level representation returned by OptionFromNullOr.
Signature
interface OptionFromNullOr<S extends Constraint> extends decodeTo<Option<toType<S>>, NullOr<S>> {
constructor(_: never);
readonly Rebuild: OptionFromNullOr<S>;
}OptionFromOptional interface
Type-level representation returned by OptionFromOptional.
Signature
interface OptionFromOptional<S extends Constraint> extends decodeTo<
Option<toType<S>>,
optional<S>
> {
constructor(_: never);
readonly Rebuild: OptionFromOptional<S>;
}OptionFromOptionalKey interface
Type-level representation returned by OptionFromOptionalKey.
Signature
interface OptionFromOptionalKey<S extends Constraint> extends decodeTo<
Option<toType<S>>,
optionalKey<S>
> {
constructor(_: never);
readonly Rebuild: OptionFromOptionalKey<S>;
}OptionFromOptionalNullOr interface
Type-level representation returned by OptionFromOptionalNullOr.
Signature
interface OptionFromOptionalNullOr<S extends Constraint> extends decodeTo<
Option<toType<S>>,
optional<NullOr<S>>
> {
constructor(_: never);
readonly Rebuild: OptionFromOptionalNullOr<S>;
}OptionFromUndefinedOr interface
Type-level representation returned by OptionFromUndefinedOr.
Signature
interface OptionFromUndefinedOr<S extends Constraint> extends decodeTo<
Option<toType<S>>,
UndefinedOr<S>
> {
constructor(_: never);
readonly Rebuild: OptionFromUndefinedOr<S>;
}Type-level representation returned by Redacted.
Signature
interface Redacted<S extends Constraint> extends declareConstructor<
Redacted_.Redacted<S["Type"]>,
Redacted_.Redacted<S["Encoded"]>,
readonly [S]
> {
constructor(_: never);
readonly Rebuild: Redacted<S>;
readonly value: S;
}RedactedFromValue interface
Type-level representation returned by RedactedFromValue.
Signature
interface RedactedFromValue<S extends Constraint> extends decodeTo<Redacted<toType<S>>, S> {
constructor(_: never);
readonly Rebuild: RedactedFromValue<S>;
}Type-level representation of RegExp.
Signature
interface RegExp extends instanceOf<globalThis.RegExp> {
constructor(_: never);
readonly Rebuild: RegExp;
}Type-level representation returned by Result.
Signature
interface Result<A extends Constraint, E extends Constraint> extends declareConstructor<
Result_.Result<A["Type"], E["Type"]>,
Result_.Result<A["Encoded"], E["Encoded"]>,
readonly [A, E],
ResultIso<A, E>
> {
constructor(_: never);
readonly failure: E;
readonly Rebuild: Result<A, E>;
readonly success: A;
}A typed view of a schema that tracks only the decoded (output) type T.
Details
Use Schema<T> as a constraint when you want to accept "any schema that decodes to T" and do not need to know or constrain the encoded representation, required services, or any other type parameters.
This is a structural interface — concrete schema values are produced by the constructors in this module (e.g. Struct, String, Number). When you also need the encoded type or service requirements, use Codec.
See
Signature
interface Schema<out T> extends Top {
constructor(_: never);
readonly Rebuild: Schema<T>;
readonly Type: T;
}Type-level representation of String.
Signature
interface String extends Bottom<string, string, never, never, SchemaAST.String, String> {
constructor(_: never);
}StringFromBase64 interface
Type-level representation of StringFromBase64.
Signature
interface StringFromBase64 extends decodeTo<String, String> {
constructor(_: never);
readonly Rebuild: StringFromBase64;
}StringFromBase64Url interface
Type-level representation of StringFromBase64Url.
Signature
interface StringFromBase64Url extends decodeTo<String, String> {
constructor(_: never);
readonly Rebuild: StringFromBase64Url;
}StringFromHex interface
Type-level representation of StringFromHex.
Signature
interface StringFromHex extends decodeTo<String, String> {
constructor(_: never);
readonly Rebuild: StringFromHex;
}StringFromUriComponent interface
Type-level representation of StringFromUriComponent.
Signature
interface StringFromUriComponent extends decodeTo<String, String> {
constructor(_: never);
readonly Rebuild: StringFromUriComponent;
}StringTree type
A Tree of string | undefined nodes. Leaf values are either a string representation or undefined for opaque/declaration types.
Signature
type StringTree = Tree<string | undefined>;Type-level representation returned by Struct.
Signature
interface Struct<Fields extends Struct.Fields> extends BottomLazy<
SchemaAST.Objects,
Struct<Fields>
> {
constructor(_: never);
readonly "~type.make": MakeInView<Fields>;
readonly "~type.make.in": MakeInView<Fields>;
readonly DecodingServices: DecodingServices<Fields>;
readonly Encoded: View<Fields>;
readonly EncodingServices: EncodingServices<Fields>;
readonly fields: Fields;
readonly Iso: View<Fields>;
readonly Type: View<Fields>;
mapFields<To extends Fields>(
f: (fields: Fields) => To,
options?: {
readonly unsafePreserveChecks?: boolean;
},
): Struct<{ [K in string | number | symbol]: Readonly<To>[K] }>;
}StructWithRest interface
Type-level representation returned by StructWithRest.
Signature
interface StructWithRest<
S extends StructWithRest.Objects,
Records extends StructWithRest.Records,
> extends BottomLazy<SchemaAST.Objects, StructWithRest<S, Records>> {
constructor(_: never);
readonly "~type.make": { [K in string | number | symbol]: MakeIn<S, Records>[K] };
readonly "~type.make.in": { [K in string | number | symbol]: MakeIn<S, Records>[K] };
readonly DecodingServices: DecodingServices<S, Records>;
readonly Encoded: { [K in string | number | symbol]: Encoded<S, Records>[K] };
readonly EncodingServices: EncodingServices<S, Records>;
readonly Iso: { [K in string | number | symbol]: Iso<S, Records>[K] };
readonly records: Records;
readonly schema: S;
readonly Type: { [K in string | number | symbol]: Type<S, Records>[K] };
}Type-level representation returned by suspend.
Signature
interface suspend<S extends Constraint> extends BottomLazy<
SchemaAST.Suspend,
suspend<S>,
S["~type.parameters"],
S["~type.mutability"],
S["~type.optionality"],
S["~type.constructor.default"],
S["~encoded.mutability"],
S["~encoded.optionality"]
> {
constructor(_: never);
readonly "~type.make": S["~type.make"];
readonly "~type.make.in": S["~type.make.in"];
readonly DecodingServices: S["DecodingServices"];
readonly Encoded: S["Encoded"];
readonly EncodingServices: S["EncodingServices"];
readonly Iso: S["Iso"];
readonly Type: S["Type"];
}Type-level representation of Symbol.
Signature
interface Symbol extends Bottom<symbol, symbol, never, never, SchemaAST.Symbol, Symbol> {
constructor(_: never);
}TaggedStruct type
Type-level representation returned by TaggedStruct.
Signature
type TaggedStruct<Tag extends SchemaAST.LiteralValue, Fields extends Struct.Fields> = Struct<
Simplify<
{
readonly _tag: tag<Tag>;
} & Fields
>
>;TaggedUnion interface
Type-level representation returned by TaggedUnion.
Signature
interface TaggedUnion<Cases extends Record<string, Constraint>> extends BottomLazy<SchemaAST.Union<SchemaAST.Objects>, TaggedUnion<Cases>> {
constructor(_: never);
readonly "~type.make": { [K in string | number | symbol]: Cases[K]["~type.make"] }[keyof Cases];
readonly "~type.make.in": { [K in string | number | symbol]: Cases[K]["~type.make"] }[keyof Cases];
readonly cases: Cases;
readonly DecodingServices: { [K in string | number | symbol]: Cases[K]["DecodingServices"] }[keyof Cases];
readonly Encoded: { [K in string | number | symbol]: Cases[K]["Encoded"] }[keyof Cases];
readonly EncodingServices: { [K in string | number | symbol]: Cases[K]["EncodingServices"] }[keyof Cases];
readonly guards: { [K in string | number | symbol]: (u: unknown) => u is Cases[K]["Type"] };
readonly isAnyOf: <Keys>(keys: readonly Array<Keys>) => (value: Cases[keyof Cases]["Type"]) => value is Extract<Cases[keyof Cases]["Type"], {
_tag: Keys;
}>;
readonly Iso: { [K in string | number | symbol]: Cases[K]["Type"] }[keyof Cases];
readonly match: {
<Output>(cases: { [K in string | number | symbol]: (value: Cases[K]["Type"]) => Output }): (value: Cases[keyof Cases]["Type"]) => Output;
<Output>(value: Cases[keyof Cases]["Type"], cases: { [K in string | number | symbol]: (value: Cases[K]["Type"]) => Output }): Output;
};
readonly Type: { [K in string | number | symbol]: Cases[K]["Type"] }[keyof Cases];
}TemplateLiteral interface
Type-level representation returned by TemplateLiteral.
Signature
interface TemplateLiteral<Parts extends TemplateLiteral.Parts> extends Bottom<
TemplateLiteral.Encoded<Parts>,
TemplateLiteral.Encoded<Parts>,
never,
never,
SchemaAST.TemplateLiteral,
TemplateLiteral<Parts>
> {
constructor(_: never);
readonly parts: Parts;
}TemplateLiteralParser interface
Type-level representation returned by TemplateLiteralParser.
Signature
interface TemplateLiteralParser<Parts extends TemplateLiteral.Parts> extends BottomLazy<
SchemaAST.Arrays,
TemplateLiteralParser<Parts>
> {
constructor(_: never);
readonly "~type.make": Type<Parts>;
readonly "~type.make.in": Type<Parts>;
readonly DecodingServices: never;
readonly Encoded: Encoded<Parts>;
readonly EncodingServices: never;
readonly Iso: Type<Parts>;
readonly parts: Parts;
readonly Type: Type<Parts>;
}Type-level representation of TimeZone.
Signature
interface TimeZone extends declare<DateTime.TimeZone> {
constructor(_: never);
readonly Rebuild: TimeZone;
}TimeZoneFromString interface
Type-level representation of TimeZoneFromString.
Signature
interface TimeZoneFromString extends decodeTo<TimeZone, String> {
constructor(_: never);
readonly Rebuild: TimeZoneFromString;
}TimeZoneNamed interface
Type-level representation of TimeZoneNamed.
Signature
interface TimeZoneNamed extends declare<DateTime.TimeZone.Named> {
constructor(_: never);
readonly Rebuild: TimeZoneNamed;
}TimeZoneNamedFromString interface
Type-level representation of TimeZoneNamedFromString.
Signature
interface TimeZoneNamedFromString extends decodeTo<TimeZoneNamed, String> {
constructor(_: never);
readonly Rebuild: TimeZoneNamedFromString;
}TimeZoneOffset interface
Type-level representation of TimeZoneOffset.
Signature
interface TimeZoneOffset extends declare<DateTime.TimeZone.Offset> {
constructor(_: never);
readonly Rebuild: TimeZoneOffset;
}The existential "any schema" type — all type parameters are erased to unknown.
Details
Use Top as a constraint when writing generic utilities that must accept *any* schema regardless of its Type, Encoded, or service requirements. It is the widest possible schema type and therefore gives you the least static information.
In user code prefer the narrower interfaces: - Schema<T> — when you only care about the decoded type - Codec<T, E, RD, RE> — when you need the encoded type and service requirements - ConstraintDecoder<T, RD> — for decode-only APIs - ConstraintEncoder<E, RE> — for encode-only APIs
Signature
interface Top extends Bottom<
unknown,
unknown,
unknown,
unknown,
SchemaAST.AST,
Top,
unknown,
unknown,
any,
unknown,
Mutability,
Optionality,
ConstructorDefault,
Mutability,
Optionality
> {
constructor(_: never);
}Recursive tree type whose leaves are Node values and whose branches are readonly arrays or string-keyed records of child trees.
Signature
type Tree<Node> = Node | TreeRecord<Node> | ReadonlyArray<Tree<Node>>;TreeRecord interface
A record node in a Tree: an object mapping string keys to child Tree nodes.
Signature
interface TreeRecord<A> {
[x: string]: Tree<A>;
}Type-level representation of Trim.
Signature
interface Trim extends decodeTo<Trimmed, String> {
constructor(_: never);
readonly Rebuild: Trim;
}Type-level representation of Trimmed.
Signature
interface Trimmed extends String {
constructor(_: never);
readonly Rebuild: Trimmed;
}Type-level representation returned by Tuple.
Signature
interface Tuple<Elements extends Tuple.Elements> extends BottomLazy<
SchemaAST.Arrays,
Tuple<Elements>
> {
constructor(_: never);
readonly "~type.make": MakeIn_<Elements>;
readonly "~type.make.in": MakeIn_<Elements>;
readonly DecodingServices: DecodingServices<Elements>;
readonly elements: Elements;
readonly Encoded: Encoded_<Elements>;
readonly EncodingServices: EncodingServices<Elements>;
readonly Iso: Iso_<Elements>;
readonly Type: Type_<Elements>;
mapElements<To extends Elements>(
f: (elements: Elements) => To,
options?: {
readonly unsafePreserveChecks?: boolean;
},
): Tuple<{ [K in string | number | symbol]: Readonly<To>[K] }>;
}TupleWithRest interface
Type-level representation returned by TupleWithRest.
Signature
interface TupleWithRest<
S extends TupleWithRest.TupleType,
Rest extends TupleWithRest.Rest,
> extends BottomLazy<SchemaAST.Arrays, TupleWithRest<S, Rest>> {
constructor(_: never);
readonly "~type.make": MakeIn<S["~type.make"], Rest>;
readonly "~type.make.in": MakeIn<S["~type.make"], Rest>;
readonly DecodingServices: S["DecodingServices"] | Rest[number]["DecodingServices"];
readonly Encoded: Encoded<S["Encoded"], Rest>;
readonly EncodingServices: S["EncodingServices"] | Rest[number]["EncodingServices"];
readonly Iso: Iso<S["Iso"], Rest>;
readonly rest: Rest;
readonly schema: S;
readonly Type: Type<S["Type"], Rest>;
}Uint8Array interface
Type-level representation of Uint8Array.
Signature
interface Uint8Array extends instanceOf<globalThis.Uint8Array<ArrayBufferLike>> {
constructor(_: never);
readonly Rebuild: Uint8Array;
}Uint8ArrayFromBase64 interface
Type-level representation of Uint8ArrayFromBase64.
Signature
interface Uint8ArrayFromBase64 extends decodeTo<Uint8Array, String> {
constructor(_: never);
readonly Rebuild: Uint8ArrayFromBase64;
}Uint8ArrayFromBase64Url interface
Type-level representation of Uint8ArrayFromBase64Url.
Signature
interface Uint8ArrayFromBase64Url extends decodeTo<Uint8Array, String> {
constructor(_: never);
readonly Rebuild: Uint8ArrayFromBase64Url;
}Uint8ArrayFromHex interface
Type-level representation of Uint8ArrayFromHex.
Signature
interface Uint8ArrayFromHex extends decodeTo<Uint8Array, String> {
constructor(_: never);
readonly Rebuild: Uint8ArrayFromHex;
}Type-level representation of Undefined.
Signature
interface Undefined extends Bottom<
undefined,
undefined,
never,
never,
SchemaAST.Undefined,
Undefined
> {
constructor(_: never);
}UndefinedOr interface
Type-level representation returned by UndefinedOr.
Signature
interface UndefinedOr<S extends Constraint> extends Union<readonly [S, Undefined]> {
constructor(_: never);
readonly Rebuild: UndefinedOr<S>;
}Type-level representation returned by Union.
Signature
interface Union<Members extends ReadonlyArray<Constraint>> extends BottomLazy<SchemaAST.Union<{ [K in keyof Members]: Members[K]["ast"] }[number]>, Union<Members>> {
constructor(_: never);
readonly "~type.make": { [K in string | number | symbol]: Members[K]["~type.make"] }[number];
readonly "~type.make.in": { [K in string | number | symbol]: Members[K]["~type.make"] }[number];
readonly DecodingServices: { [K in string | number | symbol]: Members[K]["DecodingServices"] }[number];
readonly Encoded: { [K in string | number | symbol]: Members[K]["Encoded"] }[number];
readonly EncodingServices: { [K in string | number | symbol]: Members[K]["EncodingServices"] }[number];
readonly Iso: { [K in string | number | symbol]: Members[K]["Iso"] }[number];
readonly members: Members;
readonly Type: { [K in string | number | symbol]: Members[K]["Type"] }[number];
mapMembers<To extends readonly Array<Constraint>>(f: (members: Members) => To, options?: {
readonly unsafePreserveChecks?: boolean;
}): Union<{ [K in string | number | symbol]: Readonly<To>[K] }>;
}UniqueArray interface
Type-level representation returned by UniqueArray.
Signature
interface UniqueArray<S extends Constraint> extends $Array<S> {
constructor(_: never);
readonly Rebuild: UniqueArray<S>;
}UniqueSymbol interface
Type-level representation returned by UniqueSymbol.
Signature
interface UniqueSymbol<sym extends symbol> extends Bottom<
sym,
sym,
never,
never,
SchemaAST.UniqueSymbol,
UniqueSymbol<sym>
> {
constructor(_: never);
}Type-level representation of Unknown.
Signature
interface Unknown extends Bottom<unknown, unknown, never, never, SchemaAST.Unknown, Unknown> {
constructor(_: never);
}Type-level representation of URL.
Signature
interface URL extends instanceOf<globalThis.URL> {
constructor(_: never);
readonly Rebuild: URL;
}URLFromString interface
Type-level representation of URLFromString.
Signature
interface URLFromString extends decodeTo<URL, String> {
constructor(_: never);
readonly Rebuild: URLFromString;
}URLSearchParams interface
Type-level representation of URLSearchParams.
Signature
interface URLSearchParams extends instanceOf<globalThis.URLSearchParams> {
constructor(_: never);
readonly Rebuild: URLSearchParams;
}Type-level representation of Void.
Signature
interface Void extends Bottom<void, void, never, never, SchemaAST.Void, Void> {
constructor(_: never);
}WithoutConstructorDefault interface
Constraint used to ensure a schema field does not already have a constructor default.
Details
Only schemas that satisfy this constraint can be passed to withConstructorDefault.
Signature
interface WithoutConstructorDefault {
readonly "~type.constructor.default": "no-default";
}Options
DecodingDefaultOptions type
Options for withDecodingDefaultKey and withDecodingDefault.
Details
- encodingStrategy: - "passthrough" (default): pass the value through during encoding - "omit": omit the key from the encoded output
Signature
type DecodingDefaultOptions = {
readonly encodingStrategy?: "omit" | "passthrough";
};ErrorOptions interface
Options for ErrorInstance and Defect.
Signature
interface ErrorOptions {
readonly excludeCause?: boolean;
readonly includeStack?: boolean;
}MakeOptions interface
Options for makeEffect, make, and Class constructors.
When to use
Use when passing disableChecks: true to skip validation when you trust the data. - Pass parseOptions to control error reporting behavior.
See
BottomWithoutNew.makeEffectBottomWithoutNew.make
Signature
interface MakeOptions {
readonly disableChecks?: boolean;
readonly parseOptions?: ParseOptions;
}ToJsonSchemaOptions interface
Options for toJsonSchemaDocument.
Signature
interface ToJsonSchemaOptions {
readonly additionalProperties?: boolean | JsonSchema;
readonly generateDescriptions?: boolean;
readonly includeAnnotationKey?: (key: string) => boolean;
}Other
Annotations
The Annotations namespace groups all annotation interfaces used to attach metadata to schemas. Annotations control documentation, validation messages, JSON Schema generation, equivalence, arbitrary generation, and more.
Details
Use resolveAnnotations to read the annotations attached to a schema at runtime.
Namespace of type-level helpers for Codec.
Namespace for Record type utilities.
Details
- Record.Key — constraint for the key schema (must encode to PropertyKey) - Record.Type<K, V> — decoded type of the record - Record.Encoded<K, V> — encoded type of the record
Namespace of type-level helpers for Schema.
Namespace for struct field type utilities.
Details
These types compute the decoded Type, encoded Encoded, and constructor input MakeIn of a Struct from its field map, handling optional, mutable, and other field modifiers automatically.
- Struct.Fields — constraint for the field map object - Struct.Type<F> — decoded type of the struct - Struct.Encoded<F> — encoded type of the struct - Struct.MakeIn<F> — constructor input (optional/defaulted fields may be omitted) - Struct.DecodingServices<F> / Struct.EncodingServices<F> — required services
StructWithRest
Namespace for StructWithRest type utilities.
Details
- StructWithRest.Type<S, R> — decoded type (struct type intersected with record types) - StructWithRest.Encoded<S, R> — encoded type
TemplateLiteral
Namespace for TemplateLiteral helper types.
TemplateLiteralParser
Namespace for TemplateLiteralParser helper types.
Namespace for Tuple type utilities.
Details
- Tuple.Elements — constraint for the element schema array - Tuple.Type<E> — decoded tuple type - Tuple.Encoded<E> — encoded tuple type - Tuple.MakeIn<E> — constructor input tuple
TupleWithRest
Namespace for TupleWithRest type utilities.
Details
- TupleWithRest.TupleType — constraint for the leading tuple schema - TupleWithRest.Rest — the rest element schema(s) - TupleWithRest.Type<T, R> — decoded type (fixed elements + rest) - TupleWithRest.Encoded<T, R> — encoded type
Schemas
Schema for the any type. Accepts any value without validation.
See
Unknownfor a safer alternative that usesunknown.
Signature
declare const Any: Any;BigDecimal
Schema for BigDecimal values.
When to use
Use when you already have Effect decimal instances and need schema validation, formatting, equivalence, and JSON string serialization.
Details
Default JSON serializer:
- encodes BigDecimal as a string
See
BigDecimalFromStringfor parsing string input into a BigDecimal
Signature
declare const BigDecimal: BigDecimal;BigDecimalFromString
Schema that parses a string into a BigDecimal.
When to use
Use to parse decimal or exponent-notation strings into arbitrary-precision BigDecimal values while encoding them back to strings.
Details
Decoding: - A string is decoded with BigDecimal.fromString.
Encoding: - A BigDecimal is encoded with BigDecimal.format.
Gotchas
An empty string decodes as zero.
See
BigDecimalfor validating values that are already BigDecimal valuesBigIntFromStringfor parsing base-10 integer strings into bigint valuesNumberFromStringfor parsing JavaScript number strings
Signature
declare const BigDecimalFromString: BigDecimalFromString;BigDecimalReviver
Reviver for persisted BigDecimal declarations.
When to use
Use when reconstructing documents that may contain the BigDecimal schema.
See
BigDecimalfor the corresponding schema
Signature
declare const BigDecimalReviver: DeclarationReviver<null>;Schema for bigint values. Validates that the input is typeof "bigint".
When to use
Use when the input is already a bigint and the schema should validate and preserve bigint values without parsing from another representation.
See
BigIntFromStringfor parsing string input into a bigint
Signature
declare const BigInt: BigInt;BigIntFromString
Schema that parses a string into a bigint.
When to use
Use to parse signed base-10 integer strings into bigint values while encoding bigint values back to decimal strings.
Details
Decoding: - A string is decoded as a bigint.
Encoding: - A bigint is encoded as a string.
Gotchas
Decoding accepts only strings matching ^-?\d+$.
See
isStringBigIntfor the string predicate used by this schemaBigIntfor validating values that are already bigint valuesNumberFromStringfor parsing JavaScript number strings, including non-finite valuesBigDecimalFromStringfor parsing decimal number strings
Signature
declare const BigIntFromString: BigIntFromString;Schema for boolean values. Validates that the input is typeof "boolean".
When to use
Use to validate values that are already JavaScript booleans.
See
BooleanFromBitfor a schema that decodes bit literals0or1into a boolean
Signature
declare const Boolean: Boolean;BooleanFromBit
Schema for a boolean parsed from 0 or 1.
When to use
Use when decoding data sources that represent booleans as 0 | 1 while keeping boolean values in the decoded model.
Details
Decoding accepts only 0 | 1, maps 1 to true, and maps 0 to false. Encoding maps true to 1 and false to 0.
See
Signature
declare const BooleanFromBit: BooleanFromBit;Creates a schema for Cause values using separate schemas for typed failures and unexpected defects.
When to use
Use to validate, transform, or serialize Effect failure causes when typed failures and unexpected defects need separate schemas.
Details
The error schema is applied to Fail reasons and the defect schema is applied to Die reasons. Interrupt reasons do not use either schema and carry only an optional fiber id.
See
CauseReasonfor the schema used by each individual cause reasonCauseIsofor the ordered array representation used by the schema ISO
Signature
declare function Cause<E extends Constraint, D extends Constraint>(
error: E,
defect: D,
): Cause<E, D>;CauseReason
Creates a schema for Cause.Reason values using separate schemas for typed failures and unexpected defects.
When to use
Use when serializing or decoding individual cause reasons separately from a full failure cause, with distinct schemas for typed errors and defects.
Details
Fail reasons use the error schema, Die reasons use the defect schema, and Interrupt reasons carry only an optional fiber id.
See
Causefor constructing schemas for full Cause valuesCauseReasonIsofor the ISO shape of each cause reason
Signature
declare function CauseReason<E extends Constraint, D extends Constraint>(
error: E,
defect: D,
): CauseReason<E, D>;CauseReasonReviver
Reviver for persisted CauseReason declarations.
When to use
Use when reconstructing documents that may contain schemas created by CauseReason.
See
CauseReasonfor creating the corresponding schema
Signature
declare const CauseReasonReviver: DeclarationReviver<null>;CauseReviver
Reviver for persisted Cause declarations.
When to use
Use when reconstructing documents that may contain schemas created by Cause.
See
Causefor creating the corresponding schema
Signature
declare const CauseReviver: DeclarationReviver<null>;Schema for strings whose JavaScript length is exactly 1.
When to use
Use to validate string values that must have length === 1.
Gotchas
This schema uses JavaScript String.length, so visible characters made from multiple UTF-16 code units do not satisfy length === 1.
See
Stringfor unconstrained string valuesNonEmptyStringfor strings with length greater than zeroisLengthBetweenfor the underlying length check
Signature
declare const Char: Char;Schema for chunks whose values conform to the provided element schema.
Signature
declare function Chunk<Value extends Constraint>(value: Value): Chunk<Value>;ChunkReviver
Reviver for persisted Chunk declarations.
When to use
Use when reconstructing documents that may contain schemas created by Chunk.
See
Chunkfor creating the corresponding schema
Signature
declare const ChunkReviver: DeclarationReviver<null>;Schema for valid JavaScript Date objects.
When to use
Use to validate in-memory values that must already be valid JavaScript date objects.
Details
This schema accepts Date instances whose timestamp is not NaN. The default JSON serializer encodes dates as ISO 8601 strings.
See
DateFromStringfor decoding strings into Date instancesDateFromMillisfor decoding epoch milliseconds into Date instances
Signature
declare const Date: Date;DateFromMillis
Schema that decodes epoch milliseconds into a JavaScript Date.
When to use
Use to model numeric millisecond timestamps that decode to JavaScript Date objects and encode back to numbers.
Details
Decoding: A safe integer number of milliseconds since the Unix epoch is decoded as a Date.
Encoding: A Date is encoded as its millisecond timestamp.
Gotchas
JavaScript Date supports a narrower range than safe integers, so integers outside the supported Date range fail decoding.
See
DateFromStringfor decoding string-encoded datesDateTimeUtcFromMillisfor decoding epoch milliseconds into UTC values
Signature
declare const DateFromMillis: DateFromMillis;DateFromString
Schema that decodes a string into a JavaScript Date.
When to use
Use to model string-encoded dates that decode to JavaScript Date objects and encode back to strings.
Details
Decoding: The string is passed to JavaScript Date construction.
Encoding: A Date is encoded as an ISO string.
Invalid date strings fail decoding.
See
DateFromMillisfor decoding epoch milliseconds into Date instancesDateTimeUtcFromStringfor decoding date-time strings into UTC valuesDatefor accepting Date instances directly
Signature
declare const DateFromString: DateFromString;DateReviver
Reviver for persisted Date declarations.
When to use
Use when reconstructing documents that may contain the Date schema.
See
Datefor the corresponding schema
Signature
declare const DateReviver: DeclarationReviver<null>;DateTimeUtc
Schema for DateTime.Utc values.
When to use
Use to validate existing DateTime.Utc schema values and use the default JSON codec that represents them as UTC ISO strings.
Details
The default JSON codec decodes UTC ISO strings into DateTime.Utc values and encodes DateTime.Utc values as UTC ISO strings.
See
DateTimeUtcFromStringfor decoding date-time strings into UTC valuesDateTimeUtcFromDatefor decoding JavaScript Date values into UTC valuesDateTimeUtcFromMillisfor decoding epoch milliseconds into UTC valuesDateTimeZonedfor preserving zoned DateTime values
Signature
declare const DateTimeUtc: DateTimeUtc;DateTimeUtcFromDate
Schema that decodes a Date into a DateTime.Utc.
When to use
Use when you need to decode valid JavaScript Date objects into DateTime.Utc values.
Details
Decoding: - A valid Date is decoded as a DateTime.Utc
Encoding: - A DateTime.Utc is encoded as a Date
See
DateTimeUtcfor validating values that are alreadyDateTime.UtcDateTimeUtcFromStringfor decoding date-time strings into UTC valuesDateTimeUtcFromMillisfor decoding epoch milliseconds into UTC valuesDatefor validating Date instances without converting them
Signature
declare const DateTimeUtcFromDate: DateTimeUtcFromDate;DateTimeUtcFromMillis
Schema that decodes a number into a DateTime.Utc.
Details
Decoding: - A number of milliseconds since the Unix epoch is decoded as a DateTime.Utc
Encoding: - A DateTime.Utc is encoded as a number of milliseconds since the Unix epoch.
See
DateTimeUtcFromDatefor decoding JavaScript Date values into UTC valuesDateTimeUtcFromStringfor decoding date-time strings into UTC valuesDateFromMillisfor decoding epoch milliseconds into JavaScript Date instances
Signature
declare const DateTimeUtcFromMillis: DateTimeUtcFromMillis;DateTimeUtcFromString
Schema that decodes a date-time string into a DateTime.Utc.
Details
Decoding:
- A string accepted by DateTime.make is parsed and normalized to UTC. Strings without an explicit zone are interpreted as UTC.
Encoding:
- A DateTime.Utc is encoded as a UTC ISO 8601 string.
See
DateTimeUtcFromDatefor decoding JavaScript Date values into UTC valuesDateTimeUtcFromMillisfor decoding epoch milliseconds into UTC valuesDateFromStringfor decoding strings into JavaScript Date instances
Signature
declare const DateTimeUtcFromString: DateTimeUtcFromString;DateTimeUtcReviver
Reviver for persisted DateTimeUtc declarations.
When to use
Use when reconstructing documents that may contain the DateTimeUtc schema.
See
DateTimeUtcfor the corresponding schema
Signature
declare const DateTimeUtcReviver: DeclarationReviver<null>;DateTimeZoned
Schema for DateTime.Zoned values.
Details
Default JSON serializer:
- encodes offset zones as an ISO date-time with a numeric offset, such as YYYY-MM-DDTHH:mm:ss.sss+HH:MM - encodes named zones by appending the IANA identifier in brackets, such as YYYY-MM-DDTHH:mm:ss.sss+HH:MM[Time/Zone]
Signature
declare const DateTimeZoned: DateTimeZoned;DateTimeZonedFromString
Schema that parses a zoned DateTime string into a DateTime.Zoned.
Details
Decoding: - A string (e.g. 2024-01-01T00:00:00.000+00:00[Europe/London]) is decoded as a DateTime.Zoned.
Encoding: - A DateTime.Zoned is encoded as a string.
Signature
declare const DateTimeZonedFromString: DateTimeZonedFromString;DateTimeZonedReviver
Reviver for persisted DateTimeZoned declarations.
When to use
Use when reconstructing documents that may contain the DateTimeZoned schema.
See
DateTimeZonedfor the corresponding schema
Signature
declare const DateTimeZonedReviver: DeclarationReviver<null>;Schema for unexpected defect values represented as unknown with a JSON encoded form.
When to use
Use when you need a schema for Cause defects or other unexpected failures whose runtime value may be any value.
Details
The encoded side is Json. During decoding, JSON objects with a string message property are decoded into JavaScript Error values, preserving a non-default name and any string stack. Other JSON values decode unchanged.
During encoding, JavaScript Error values encode to JSON objects with name, message, and optional cause properties. Pass { includeStack: true } to include string stack traces in encoded Error defects, or { excludeCause: true } to omit causes. Other values are serialized through Effect's JSON formatter and then parsed back into JSON when possible.
Gotchas
This schema is for carrying defects across JSON boundaries, not for preserving every JavaScript value exactly. Some values cannot round-trip unchanged:
- A non-Error object such as { message: "boom" } encodes as an error-shaped JSON object and decodes back as an Error. - JSON serialization normalizes unsupported values. For example, undefined array elements encode as null, unsupported object properties are omitted, and circular references are dropped. - Values that cannot be represented as JSON fall back to Effect's formatted string representation.
See
ErrorInstancefor a schema that only accepts JavaScriptErrorvalues.
Signature
declare function Defect(options?: ErrorOptions): Defect;Schema for Duration values.
Details
The default JSON serializer encodes Duration as a tagged object with the duration type and value.
Signature
declare const Duration: Duration;DurationFromMillis
Schema that decodes a number into a Duration, treating the number as milliseconds.
Details
Decoding: - A finite or infinite number is decoded as a Duration
Encoding: - A Duration is encoded to a finite or infinite number of milliseconds
Gotchas
NaN is decoded as Duration.zero, matching Duration.millis.
Signature
declare const DurationFromMillis: DurationFromMillis;DurationFromNanos
Schema that decodes a bigint into a Duration, treating the bigint as nanoseconds.
Details
Decoding: A bigint representing nanoseconds is decoded as a Duration.
Encoding: Finite durations are encoded as a bigint number of nanoseconds. Encoding fails when the duration cannot be represented as nanoseconds, such as Duration.infinity or Duration.negativeInfinity.
Signature
declare const DurationFromNanos: DurationFromNanos;DurationFromString
Schema that parses a string into a Duration.
Details
Decoding: - A string is decoded as a Duration, accepting any format that Duration.fromInput can parse.
Encoding: - A Duration is encoded as a parseable string.
Signature
declare const DurationFromString: DurationFromString;DurationReviver
Reviver for persisted Duration declarations.
When to use
Use when reconstructing documents that may contain the Duration schema.
See
Durationfor the corresponding schema
Signature
declare const DurationReviver: DeclarationReviver<null>;ErrorInstance
Schema for JavaScript Error objects.
Details
Default JSON serializer:
Encodes an Error as an object with message, optional name, and optional cause properties, and decodes that object back into an Error. Stack traces are omitted by default for security. Pass { includeStack: true } to include stack traces, or { excludeCause: true } to omit causes.
Signature
declare function ErrorInstance(options?: ErrorOptions): ErrorInstance;ErrorInstanceReviver
Reviver for persisted ErrorInstance declarations.
When to use
Use when reconstructing documents that may contain schemas created by ErrorInstance.
See
ErrorInstancefor creating the corresponding schema
Signature
declare const ErrorInstanceReviver: DeclarationReviver<ErrorRepresentationPayload>;Creates a schema for Exit values using schemas for the success value, typed failure, and unexpected defect channels.
When to use
Use when serializing or validating an effect outcome where success, typed failure, and defects each need their own schema.
Signature
declare function Exit<A extends Constraint, E extends Constraint, D extends Constraint>(
value: A,
error: E,
defect: D,
): Exit<A, E, D>;ExitReviver
Reviver for persisted Exit declarations.
When to use
Use when reconstructing documents that may contain schemas created by Exit.
See
Exitfor creating the corresponding schema
Signature
declare const ExitReviver: DeclarationReviver<null>;Schema for JavaScript File objects.
Details
The default JSON serializer encodes a File as { data, type, name, lastModified } where data is base64-encoded.
Signature
declare const File: File;FileReviver
Reviver for persisted File declarations.
When to use
Use when reconstructing documents that may contain the File schema.
See
Filefor the corresponding schema
Signature
declare const FileReviver: DeclarationReviver<null>;Schema for finite numbers, rejecting NaN, Infinity, and -Infinity.
Signature
declare const Finite: Finite;FiniteFromString
Schema that parses a string into a finite number.
Details
Decoding: - A string is decoded as a finite number, rejecting NaN, Infinity, and -Infinity values.
Encoding: - A finite number is encoded as a string.
Signature
declare const FiniteFromString: FiniteFromString;Schema for JavaScript FormData objects.
Details
The default JSON serializer encodes a FormData as an array of [key, entry] pairs where each entry is tagged as "String" or "File".
Signature
declare const FormData: FormData;FormDataReviver
Reviver for persisted FormData declarations.
When to use
Use when reconstructing documents that may contain the FormData schema.
See
FormDatafor the corresponding schema
Signature
declare const FormDataReviver: DeclarationReviver<null>;fromJsonString
Returns a schema that decodes a JSON string and then decodes the parsed value using the given schema.
Details
This is useful when working with JSON-encoded strings where the actual structure of the value is known and described by an existing schema.
During decoding, the resulting schema first parses the input string as JSON, using reviver when provided, and then runs the provided schema on the parsed result. During encoding, it first encodes with the provided schema and then passes the result to JSON.stringify with the optional replacer and space.
Signature
declare function fromJsonString<S extends Constraint>(
schema: S,
options?: {
readonly replacer?: JsonReplacer;
readonly reviver?: (this: any, key: string, value: any) => any;
readonly space?: string | number;
},
): fromJsonString<S>;Schema for hash maps whose keys and values conform to the provided schemas.
Signature
declare function HashMap<Key extends Constraint, Value extends Constraint>(
key: Key,
value: Value,
): HashMap<Key, Value>;HashMapReviver
Reviver for persisted HashMap declarations.
When to use
Use when reconstructing documents that may contain schemas created by HashMap.
See
HashMapfor creating the corresponding schema
Signature
declare const HashMapReviver: DeclarationReviver<null>;Schema for hash sets whose values conform to the provided element schema.
Signature
declare function HashSet<Value extends Constraint>(value: Value): HashSet<Value>;HashSetReviver
Reviver for persisted HashSet declarations.
When to use
Use when reconstructing documents that may contain schemas created by HashSet.
See
HashSetfor creating the corresponding schema
Signature
declare const HashSetReviver: DeclarationReviver<null>;Schema for integers, rejecting NaN, Infinity, and -Infinity.
Signature
declare const Int: Int;Schema that accepts and validates any immutable JSON-compatible value.
Signature
declare const Json: Codec<Json, Json, never, never>;JsonReviver
Reviver for persisted Json declarations.
When to use
Use when reconstructing documents that may contain the Json schema.
See
Jsonfor the corresponding immutable JSON schema
Signature
declare const JsonReviver: DeclarationReviver<null>;MutableJson
Schema that accepts any mutable JSON-compatible value. See Json for the immutable variant.
Signature
declare const MutableJson: Codec<MutableJson, MutableJson, never, never>;MutableJsonReviver
Reviver for persisted MutableJson declarations.
When to use
Use when reconstructing documents that may contain the MutableJson schema.
See
MutableJsonfor the corresponding mutable JSON schema
Signature
declare const MutableJsonReviver: DeclarationReviver<null>;Schema for non-negative safe integers, including zero.
When to use
Use when you need a count, index, or size that cannot be negative.
See
Intfor safe integers that may be negative
Signature
declare const Natural: Natural;Schema for the never type. Always fails validation — no value satisfies it.
Signature
declare const Never: Never;NonEmptyString
Schema for non-empty strings. Validates that a string has at least one character.
Signature
declare const NonEmptyString: NonEmptyString;Schema for the null literal. Validates that the input is strictly null.
See
NullOrfor a union with another schema.
Signature
declare const Null: Null;Schema for number values, including NaN, Infinity, and -Infinity.
Details
Default JSON serializer:
- Finite numbers are serialized as numbers. - Non-finite values are serialized as strings ("NaN", "Infinity", "-Infinity").
See
Finitefor a schema that excludes non-finite values.
Signature
declare const Number: Number;NumberFromString
Schema that parses a string into a number using JavaScript number coercion.
Details
Decoding: A string is decoded as a number, including possible non-finite values such as NaN, Infinity, and -Infinity. Use FiniteFromString to reject non-finite numbers.
Encoding: A number is encoded as a string.
Signature
declare const NumberFromString: NumberFromString;ObjectKeyword
Schema for the object type. Validates that the input is a non-null object or function (i.e. typeof value === "object" && value !== null || typeof value === "function").
Signature
declare const ObjectKeyword: ObjectKeyword;Schema for Option<A> values.
Signature
declare function Option<A extends Constraint>(value: A): Option<A>;OptionFromNullishOr
Decodes a nullish value T to a required Option<T> value.
Details
Decoding maps null and undefined to None and all other values to Some. Encoding maps None to null or undefined depending on options.onNoneEncoding, which defaults to undefined, and maps Some to its value.
Signature
declare function OptionFromNullishOr<S extends Constraint>(
schema: S,
options?: {
onNoneEncoding: null | undefined;
},
): OptionFromNullishOr<S>;OptionFromNullOr
Decodes a nullable, required value T to a required Option<T> value.
Details
Decoding maps null to None and all other values to Some. Encoding maps None to null and maps Some to its value.
Signature
declare function OptionFromNullOr<S extends Constraint>(schema: S): OptionFromNullOr<S>;OptionFromOptional
Decodes an optional or undefined value A to a required Option<A> value.
Details
Decoding maps a missing key or a present undefined value to None, and maps all other values to Some. Encoding maps None to a missing key and maps Some to its value.
Signature
declare function OptionFromOptional<S extends Constraint>(schema: S): OptionFromOptional<S>;OptionFromOptionalKey
Decodes an optional value A to a required Option<A> value.
Details
Decoding maps a missing key to None and a present value to Some. Encoding maps None to a missing key and maps Some to its value.
Signature
declare function OptionFromOptionalKey<S extends Constraint>(schema: S): OptionFromOptionalKey<S>;OptionFromOptionalNullOr
Decodes an optional or null or undefined value A to a required Option<A> value.
Details
Decoding maps a missing key, undefined, or null to None, and maps all other values to Some. Encoding maps Some to its value. None is encoded according to options.onNoneEncoding: "omit" encodes a missing key, null encodes null, and undefined encodes undefined.
Signature
declare function OptionFromOptionalNullOr<S extends Constraint>(
schema: S,
options?: {
readonly onNoneEncoding: "omit" | null | undefined;
},
): OptionFromOptionalNullOr<S>;OptionFromUndefinedOr
Decodes a required value that may be undefined to a required Option<T> value.
Details
Decoding maps undefined to None and all other values to Some. Encoding maps None to undefined and maps Some to its value.
Signature
declare function OptionFromUndefinedOr<S extends Constraint>(schema: S): OptionFromUndefinedOr<S>;OptionReviver
Reviver for persisted Option declarations.
When to use
Use when reconstructing documents that may contain schemas created by Option.
See
Optionfor creating the corresponding schema
Signature
declare const OptionReviver: DeclarationReviver<null>;PropertyKey
Schema for property keys accepted by Effect schemas: finite number, symbol, or string.
Signature
declare const PropertyKey: Union<readonly [Finite, Symbol, String]>;ReadonlyMap
Schema for readonly maps whose keys and values conform to the provided schemas.
Signature
declare function ReadonlyMap<Key extends Constraint, Value extends Constraint>(
key: Key,
value: Value,
): $ReadonlyMap<Key, Value>;ReadonlyMapReviver
Reviver for persisted ReadonlyMap declarations.
When to use
Use when reconstructing documents that may contain schemas created by ReadonlyMap.
See
ReadonlyMapfor creating the corresponding schema
Signature
declare const ReadonlyMapReviver: DeclarationReviver<null>;ReadonlySet
Schema for readonly sets whose values conform to the provided element schema.
Signature
declare function ReadonlySet<Value extends Constraint>(value: Value): $ReadonlySet<Value>;ReadonlySetReviver
Reviver for persisted ReadonlySet declarations.
When to use
Use when reconstructing documents that may contain schemas created by ReadonlySet.
See
ReadonlySetfor creating the corresponding schema
Signature
declare const ReadonlySetReviver: DeclarationReviver<null>;Schema for Redacted values, which hide their contents from inspection.
Options:
- label: When provided, the schema will behave as follows: - Values will be validated against the label in addition to the wrapped schema - The default JSON serializer will deserialize into a Redacted instance with the label - The arbitrary generator will produce a Redacted instance with the label - The formatter will return the label - disallowJsonEncode: When set to true, when attempting to encode a Redacted instance into JSON, it will fail with an error. This is useful when the wrapped schema is sensitive and should not be exposed in JSON.
See
RedactedFromValuefor decoding raw values and wrapping them inRedacted.
Signature
declare function Redacted<S extends Constraint>(
value: S,
options?: {
readonly disallowJsonEncode?: boolean;
readonly label?: string;
},
): Redacted<S>;RedactedFromValue
Decodes a value and wraps it in Redacted<A>. Unlike Redacted which expects the input to already be a Redacted instance, this schema decodes the raw value and wraps it.
See
Redactedfor schemas whose input is already aRedactedvalue.
Signature
declare function RedactedFromValue<S extends Constraint>(
value: S,
options?: {
readonly disallowEncode?: boolean;
readonly label?: string;
},
): RedactedFromValue<S>;RedactedReviver
Reviver for persisted Redacted declarations.
When to use
Use when reconstructing documents that may contain schemas created by Redacted.
See
Redactedfor creating the corresponding schema
Signature
declare const RedactedReviver: DeclarationReviver<RedactedRepresentationPayload>;Schema for JavaScript RegExp objects.
Details
The default JSON serializer encodes a RegExp as { source, flags }.
Signature
declare const RegExp: RegExp;RegExpReviver
Reviver for persisted RegExp declarations.
When to use
Use when reconstructing documents that may contain the RegExp schema.
See
RegExpfor the corresponding schema
Signature
declare const RegExpReviver: DeclarationReviver<null>;Schema for Result<A, E> values.
Signature
declare function Result<A extends Constraint, E extends Constraint>(
success: A,
failure: E,
): Result<A, E>;ResultReviver
Reviver for persisted Result declarations.
When to use
Use when reconstructing documents that may contain schemas created by Result.
See
Resultfor creating the corresponding schema
Signature
declare const ResultReviver: DeclarationReviver<null>;StandardSchemaV1FailureResult
Schema for a Standard Schema v1 failure result.
Details
The result contains an issues array where each issue has a message and an optional path made of property keys or keyed path segments.
Signature
declare const StandardSchemaV1FailureResult: Struct<{
readonly issues: $Array<Struct<{
readonly message: String;
readonly path: optional<$Array<Union<readonly [Union<readonly [..., ..., ...]>, Struct<{
readonly key: ...;
}>]>>>;
}>>;
}>Schema for string values. Validates that the input is typeof "string".
Signature
declare const String: String;StringFromBase64
Decodes a base64 (RFC4648) encoded string into a UTF-8 string.
Details
Decoding: - A valid base64 encoded string is decoded as a UTF-8 string.
Encoding: - A string is encoded as a base64-encoded string.
Signature
declare const StringFromBase64: StringFromBase64;StringFromBase64Url
Decodes a base64 (URL) encoded string into a UTF-8 string.
Details
Decoding: - A valid base64 (URL) encoded string is decoded as a UTF-8 string.
Encoding: - A string is encoded as a base64 (URL) encoded string.
Signature
declare const StringFromBase64Url: StringFromBase64Url;StringFromHex
Decodes a hex encoded string into a UTF-8 string.
Details
Decoding: - A valid hex encoded string is decoded as a UTF-8 string.
Encoding: - A string is encoded as a hex string.
Signature
declare const StringFromHex: StringFromHex;StringFromUriComponent
Decodes a URI component encoded string into a UTF-8 string. Can be used to store data in a URL.
Details
Decoding: - A valid URI component encoded string is decoded as a UTF-8 string.
Encoding: - A string is encoded as a URI component encoded string.
Signature
declare const StringFromUriComponent: StringFromUriComponent;Schema for symbol values. Validates that the input is typeof "symbol".
See
UniqueSymbolfor a schema that matches a specific symbol.
Signature
declare const Symbol: Symbol;Schema for DateTime.TimeZone values.
Details
Default JSON serializer:
- encodes DateTime.TimeZone as a string (IANA identifier or offset like +03:00)
Signature
declare const TimeZone: TimeZone;TimeZoneFromString
Schema that parses a time zone string into a DateTime.TimeZone.
Details
Decoding: - A string (IANA identifier or offset like +03:00) is decoded as a DateTime.TimeZone.
Encoding: - A DateTime.TimeZone is encoded as a string.
Signature
declare const TimeZoneFromString: TimeZoneFromString;TimeZoneNamed
Schema for DateTime.TimeZone.Named values.
Details
Default JSON serializer:
- encodes DateTime.TimeZone.Named as a string (IANA time zone identifier)
Signature
declare const TimeZoneNamed: TimeZoneNamed;TimeZoneNamedFromString
Schema that parses an IANA time zone identifier string into a DateTime.TimeZone.Named.
Details
Decoding: - A string is decoded as a DateTime.TimeZone.Named.
Encoding: - A DateTime.TimeZone.Named is encoded as a string.
Signature
declare const TimeZoneNamedFromString: TimeZoneNamedFromString;TimeZoneNamedReviver
Reviver for persisted TimeZoneNamed declarations.
When to use
Use when reconstructing documents that may contain the TimeZoneNamed schema.
See
TimeZoneNamedfor the corresponding schema
Signature
declare const TimeZoneNamedReviver: DeclarationReviver<null>;TimeZoneOffset
Schema for DateTime.TimeZone.Offset values.
Details
Default JSON serializer:
- encodes DateTime.TimeZone.Offset as a number (offset in milliseconds)
Signature
declare const TimeZoneOffset: TimeZoneOffset;TimeZoneOffsetReviver
Reviver for persisted TimeZoneOffset declarations.
When to use
Use when reconstructing documents that may contain the TimeZoneOffset schema.
See
TimeZoneOffsetfor the corresponding schema
Signature
declare const TimeZoneOffsetReviver: DeclarationReviver<null>;TimeZoneReviver
Reviver for persisted TimeZone declarations.
When to use
Use when reconstructing documents that may contain the TimeZone schema.
See
TimeZonefor the corresponding schema
Signature
declare const TimeZoneReviver: DeclarationReviver<null>;Creates a recursive schema for a Tree of values described by node. The resulting schema accepts a single node value, an array of trees, or an object whose values are trees.
Signature
declare function Tree<S extends Constraint>(
node: S,
): Union<
readonly [
S,
$Array<
suspend<
Codec<Tree<S["Type"]>, Tree<S["Encoded"]>, S["DecodingServices"], S["EncodingServices"]>
>
>,
$Record<
String,
suspend<
Codec<Tree<S["Type"]>, Tree<S["Encoded"]>, S["DecodingServices"], S["EncodingServices"]>
>
>,
]
>;Schema that trims whitespace from a string.
Details
Decoding: - A string is decoded as a string with no leading or trailing whitespaces.
Encoding: - The trimmed string is encoded as is.
Signature
declare const Trim: Trim;Schema for strings that contains no leading or trailing whitespaces.
Signature
declare const Trimmed: Trimmed;Uint8Array
Schema for JavaScript Uint8Array objects.
Details
Default JSON serializer:
The default JSON serializer encodes Uint8Array as a Base64 encoded string.
Signature
declare const Uint8Array: Uint8Array;Uint8ArrayFromBase64
Schema that decodes a base64 encoded string into a Uint8Array.
Details
Decoding: - A valid base64 encoded string is decoded as a Uint8Array.
Encoding: - A Uint8Array is encoded as a base64-encoded string.
Signature
declare const Uint8ArrayFromBase64: Uint8ArrayFromBase64;Uint8ArrayFromBase64Url
Schema that decodes a base64 (URL) encoded string into a Uint8Array.
Details
Decoding: - A valid base64 (URL) encoded string is decoded as a Uint8Array.
Encoding: - A Uint8Array is encoded as a base64 (URL) encoded string.
Signature
declare const Uint8ArrayFromBase64Url: Uint8ArrayFromBase64Url;Uint8ArrayFromHex
Schema that decodes a hex encoded string into a Uint8Array.
Details
Decoding: - A valid hex encoded string is decoded as a Uint8Array.
Encoding: - A Uint8Array is encoded as a hex encoded string.
Signature
declare const Uint8ArrayFromHex: Uint8ArrayFromHex;Uint8ArrayReviver
Reviver for persisted Uint8Array declarations.
When to use
Use when reconstructing documents that may contain the Uint8Array schema.
See
Uint8Arrayfor the corresponding schema
Signature
declare const Uint8ArrayReviver: DeclarationReviver<null>;Schema for the undefined literal. Validates that the input is strictly undefined.
See
UndefinedOrfor a union with another schema.
Signature
declare const Undefined: Undefined;Schema for the unknown type. Accepts any value without validation.
When to use
Use as a top schema when you need to accept any input while preserving TypeScript's unknown safety at use sites.
See
Anyfor theanyvariant.
Signature
declare const Unknown: Unknown;Schema for JavaScript URL objects.
Details
Default JSON serializer:
- encodes URL as a string
Signature
declare const URL: URL;URLFromString
Schema that decodes a string into a URL.
Details
Decoding: - A valid URL string is decoded as a URL
Encoding: - A URL is encoded as a string
Signature
declare const URLFromString: URLFromString;URLReviver
Reviver for persisted URL declarations.
When to use
Use when reconstructing documents that may contain the URL schema.
See
URLfor the corresponding schema
Signature
declare const URLReviver: DeclarationReviver<null>;URLSearchParams
Schema for JavaScript URLSearchParams objects.
Details
The default JSON serializer encodes a URLSearchParams as a query string.
Signature
declare const URLSearchParams: URLSearchParams;URLSearchParamsReviver
Reviver for persisted URLSearchParams declarations.
When to use
Use when reconstructing documents that may contain the URLSearchParams schema.
See
URLSearchParamsfor the corresponding schema
Signature
declare const URLSearchParamsReviver: DeclarationReviver<null>;Schema for a TypeScript void return value.
When to use
Use when you need to model the return value of a function, RPC, or endpoint whose result is intentionally ignored.
Details
Runtime parsing accepts any present value and discards it, producing undefined. The public decoded and encoded TypeScript representation remains void, so typed construction, decoding, and encoding APIs are still modeled as void.
See
Undefinedfor a schema that matches only the exactundefinedvalue.
Signature
declare const Void: Void;Transforming
Type-level representation returned by decodeTo without a custom transformation.
Signature
interface compose<To extends Constraint, From extends Constraint> extends decodeTo<To, From> {
constructor(_: never);
}Applies a transformation to a schema, creating a new schema with the same type but transformed encoding/decoding.
When to use
Use when the decoded type stays the same and the transformation only normalizes values during encoding and decoding.
Details
Call it with a transformation object and then pipe a schema into the returned function. The resulting schema keeps the same Type and Encoded types as the source schema, while applying the transformation during both decoding and encoding.
Internally this uses toType(self) as the target schema and combines service requirements from the source schema and the transformation.
Gotchas
Use decodeTo instead when the transformation should change the decoded type. For this helper, both transformation getters operate on S["Type"] values.
Signature
declare function decode<S extends Constraint, RD = never, RE = never>(transformation: {
readonly decode: Getter<S["Type"], S["Type"], RD>;
readonly encode: Getter<S["Type"], S["Type"], RE>;
}): (self: S) => decodeTo<toType<S>, S, RD, RE>;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.
Signature
declare function decodeTo<To extends Constraint>(
to: To,
): <From extends Constraint>(from: From) => compose<To, From>;
declare function decodeTo<To extends Constraint, From extends Constraint, RD = never, RE = never>(
to: To,
transformation: {
readonly decode: Getter<NoInfer<To["Encoded"]>, NoInfer<From["Type"]>, RD>;
readonly encode: Getter<NoInfer<From["Type"]>, NoInfer<To["Encoded"]>, RE>;
},
): (from: From) => decodeTo<To, From, RD, RE>;Type-level representation returned by decodeTo.
Signature
interface decodeTo<
To extends Constraint,
From extends Constraint,
RD = never,
RE = never,
> extends BottomLazy<
To["ast"],
decodeTo<To, From, RD, RE>,
To["~type.parameters"],
To["~type.mutability"],
To["~type.optionality"],
To["~type.constructor.default"],
From["~encoded.mutability"],
From["~encoded.optionality"]
> {
constructor(_: never);
readonly "~type.make": To["~type.make"];
readonly "~type.make.in": To["~type.make.in"];
readonly DecodingServices: RD | To["DecodingServices"] | From["DecodingServices"];
readonly Encoded: From["Encoded"];
readonly EncodingServices: RE | To["EncodingServices"] | From["EncodingServices"];
readonly from: From;
readonly Iso: To["Iso"];
readonly to: To;
readonly Type: To["Type"];
}Applies a transformation to a schema's encoded type, creating a new schema where encoding/decoding operate on S["Encoded"] rather than S["Type"].
Details
The decode getter maps S["Encoded"] → S["Encoded"] (applied during decoding), and the encode getter maps S["Encoded"] → S["Encoded"] (applied during encoding).
Signature
declare function encode<S extends Constraint, RD = never, RE = never>(transformation: {
readonly decode: Getter<S["Encoded"], S["Encoded"], RD>;
readonly encode: Getter<S["Encoded"], S["Encoded"], RE>;
}): (self: S) => decodeTo<S, toEncoded<S>, RD, RE>;encodeKeys
Renames struct keys in the encoded form without changing the decoded type.
Details
Takes a partial mapping { decodedKey: encodedKey } and produces a transformation schema that decodes from the renamed keys and encodes back to the renamed keys. Keys not present in the mapping are left unchanged. If two existing fields would produce the same encoded key, construction fails.
Signature
declare function encodeKeys<
S extends Constraint & {
readonly fields: Fields;
},
M extends { [K in string | number | symbol]: PropertyKey },
>(mapping: M): (self: S) => encodeKeys<S, M>;encodeKeys interface
Type-level representation returned by encodeKeys.
Signature
interface encodeKeys<
S extends Constraint & {
readonly fields: Struct.Fields;
},
M extends { [K in keyof S["fields"]]: PropertyKey },
> extends decodeTo<S, Struct<{ [K in keyof S["fields"]]: toEncoded<S["fields"][K]> }>> {
constructor(_: never);
}Reverses a schema transformation so the encoded schema is supplied first.
When to use
Use to define a transformation by naming the encoded schema before the decoded schema.
Details
encodeTo(to)(from) is equivalent to to.pipe(decodeTo(from)). The from schema acts as the target decoded schema and to acts as the encoded source.
Signature
declare function encodeTo<To extends Constraint>(
to: To,
): <From extends Constraint>(from: From) => decodeTo<From, To>;
declare function encodeTo<To extends Constraint, From extends Constraint, RD = never, RE = never>(
to: To,
transformation: {
readonly decode: Getter<NoInfer<From["Encoded"]>, NoInfer<To["Type"]>, RD>;
readonly encode: Getter<NoInfer<To["Type"]>, NoInfer<From["Encoded"]>, RE>;
},
): (from: From) => decodeTo<From, To, RD, RE>;Adds derived fields to a struct schema during decoding.
Details
Each new field is derived from the decoded struct value via a function that returns Option. On encoding the derived fields are stripped. This allows computed or enriched fields to live in the decoded type without appearing in the encoded form.
Signature
declare function extendTo<S extends Struct<Fields>, Fields extends Fields>(
fields: Fields,
derive: { [K in string | number | symbol]: (s: S["Type"]) => Option<Fields[K]["Type"]> },
): (
self: S,
) => decodeTo<
Struct<{
[K in string | number | symbol]: {
[K in string | number | symbol]: toType<S["fields"][K]>;
} & Fields[K];
}>,
S
>;Swaps the decoded and encoded sides of a schema.
When to use
Use to invert a schema transformation direction.
Details
Calling flip twice returns the original schema.
Signature
declare function flip<S extends Top>(schema: S): S extends flip<F> ? F["Rebuild"] : flip<S>;Type-level representation returned by flip.
Signature
interface flip<S extends Top> extends BottomLazy<
SchemaAST.AST,
flip<S>,
ReadonlyArray<Constraint>,
S["~encoded.mutability"],
S["~encoded.optionality"],
ConstructorDefault,
S["~type.mutability"],
S["~type.optionality"]
> {
constructor(_: never);
readonly "~effect/Schema/flip": "~effect/Schema/flip";
readonly "~type.make": S["Encoded"];
readonly "~type.make.in": S["Encoded"];
readonly DecodingServices: S["EncodingServices"];
readonly Encoded: S["Type"];
readonly EncodingServices: S["DecodingServices"];
readonly Iso: S["Encoded"];
readonly schema: S;
readonly Type: S["Encoded"];
}Constructs an SchemaAST.Link that describes how a value of type T encodes to and decodes from a To schema. Used when building low-level AST transformations that bridge two schema types.
Signature
declare function link<T>(): <To extends Constraint>(
encodeTo: To,
transformation: {
readonly decode: Getter<T, NoInfer<To["Type"]>>;
readonly encode: Getter<NoInfer<To["Type"]>, T>;
},
) => Link;Makes an array or tuple schema mutable, removing the readonly modifier.
Signature
declare const mutable: mutableLambda;Type-level representation returned by mutable.
Signature
interface mutable<
S extends Constraint & {
readonly ast: SchemaAST.Arrays;
},
> extends BottomLazy<
S["ast"],
mutable<S>,
S["~type.parameters"],
S["~type.mutability"],
S["~type.optionality"],
S["~type.constructor.default"],
S["~encoded.mutability"],
S["~encoded.optionality"]
> {
constructor(_: never);
readonly "~type.make": S["~type.make"];
readonly "~type.make.in": S["~type.make.in"];
readonly DecodingServices: S["DecodingServices"];
readonly Encoded: { [K in string | number | symbol]: S["Encoded"][K] };
readonly EncodingServices: S["EncodingServices"];
readonly Iso: S["Iso"];
readonly schema: S;
readonly Type: { [K in string | number | symbol]: S["Type"][K] };
}overrideToCodecIso
Overrides a schema's derived ISO codec with an explicit target codec.
When to use
Use to provide a custom ISO transformation when the default derivation is not appropriate.
Details
The resulting schema carries a custom Iso type parameter and uses the provided decode and encode getters to transform between the schema type and the target codec.
Signature
declare function overrideToCodecIso<S extends Constraint, Iso>(
to: ConstraintCodec<Iso>,
transformation: {
readonly decode: Getter<S["Type"], Iso>;
readonly encode: Getter<Iso, S["Type"]>;
},
): (schema: S) => overrideToCodecIso<S, Iso>;overrideToCodecIso interface
Type-level representation returned by overrideToCodecIso.
Signature
interface overrideToCodecIso<S extends Constraint, Iso> extends BottomLazy<
S["ast"],
overrideToCodecIso<S, Iso>,
S["~type.parameters"],
S["~type.mutability"],
S["~type.optionality"],
S["~type.constructor.default"],
S["~encoded.mutability"],
S["~encoded.optionality"]
> {
constructor(_: never);
readonly "~type.make": S["~type.make"];
readonly "~type.make.in": S["~type.make.in"];
readonly DecodingServices: S["DecodingServices"];
readonly Encoded: S["Encoded"];
readonly EncodingServices: S["EncodingServices"];
Iso: Iso;
readonly schema: S;
readonly Type: S["Type"];
}Extracts the encoded-side schema: sets Type to equal the Encoded, discarding the decoding transformation path.
Signature
declare const toEncoded: toEncodedLambda;Type-level representation returned by toEncoded.
Signature
interface toEncoded<S extends Constraint> extends BottomLazy<
SchemaAST.AST,
toEncoded<S>,
ReadonlyArray<Constraint>,
S["~type.mutability"],
S["~type.optionality"],
S["~type.constructor.default"],
S["~encoded.mutability"],
S["~encoded.optionality"]
> {
constructor(_: never);
readonly "~type.make": S["Encoded"];
readonly "~type.make.in": S["Encoded"];
readonly DecodingServices: never;
readonly Encoded: S["Encoded"];
readonly EncodingServices: never;
readonly Iso: S["Encoded"];
readonly schema: S;
readonly Type: S["Encoded"];
}Extracts the type-side schema: sets Encoded to equal the decoded Type, discarding the encoding transformation path.
Signature
declare const toType: toTypeLambda;Type-level representation returned by toType.
Signature
interface toType<S extends Constraint> extends BottomLazy<
S["ast"],
toType<S>,
S["~type.parameters"],
S["~type.mutability"],
S["~type.optionality"],
S["~type.constructor.default"],
S["~encoded.mutability"],
S["~encoded.optionality"]
> {
constructor(_: never);
readonly "~type.make": S["~type.make"];
readonly "~type.make.in": S["~type.make.in"];
readonly DecodingServices: never;
readonly Encoded: S["Type"];
readonly EncodingServices: never;
readonly Iso: S["Iso"];
readonly schema: S;
readonly Type: S["Type"];
}Utility Types
Fully-parameterized base interface for schemas that can be extended directly by TypeScript classes.
When to use
Use as the base for concrete schema interfaces whose runtime values support class ... extends schema.
Details
Extends BottomWithoutNew with a construct signature that accepts never. The signature enables class extension without making ordinary schemas directly constructible.
See
BottomWithoutNewfor the schema protocol without a construct signature
Signature
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",
> extends BottomWithoutNew<
T,
E,
RD,
RE,
Ast,
Rebuild,
TypeMakeIn,
Iso,
TypeParameters,
TypeMake,
TypeMutability,
TypeOptionality,
TypeConstructorDefault,
EncodedMutability,
EncodedOptionality
> {
constructor(_: never);
}BottomLazy interface
Lazy Bottom variant for schemas that can be extended directly by TypeScript classes.
When to use
Use as the base for concrete lazy schema interfaces whose runtime values support class ... extends schema.
Details
Extends BottomLazyWithoutNew with a construct signature that accepts never. The signature enables class extension without making ordinary schemas directly constructible.
See
BottomLazyWithoutNewfor the lazy schema protocol without a construct signature
Signature
interface BottomLazy<
out Ast extends SchemaAST.AST,
out Rebuild extends Top,
in out TypeParameters extends ReadonlyArray<Constraint> = readonly [],
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",
> extends BottomLazyWithoutNew<
Ast,
Rebuild,
TypeParameters,
TypeMutability,
TypeOptionality,
TypeConstructorDefault,
EncodedMutability,
EncodedOptionality
> {
constructor(_: never);
}BottomLazyWithoutNew interface
Lazy BottomWithoutNew variant for schema implementations that compute their public views on demand.
When to use
Use as the base for lazy schema interfaces that provide a specialized construct signature.
Details
The laziness is purely type-level; runtime behavior is unchanged. BottomLazyWithoutNew keeps the structural operations inherited from BottomWithoutNew, but erases the expensive schema views to unknown. Concrete schema interfaces can then redeclare the precise views they expose. This keeps wide schemas such as Struct and Union cheaper when generic code reads a single view, while preserving their exact public types.
See
BottomWithoutNewfor the fully parameterized schema interface when every view must be supplied directly.
Signature
interface BottomLazyWithoutNew<
out Ast extends SchemaAST.AST,
out Rebuild extends Top,
in out TypeParameters extends ReadonlyArray<Constraint> = readonly [],
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",
> extends BottomWithoutNew<
unknown,
unknown,
unknown,
unknown,
Ast,
Rebuild,
unknown,
unknown,
TypeParameters,
unknown,
TypeMutability,
TypeOptionality,
TypeConstructorDefault,
EncodedMutability,
EncodedOptionality
> {}Iso representation used for Cause schemas: an ordered array of CauseReasonIso values.
When to use
Use when working with the ISO shape of a Cause schema, such as toIso optics or codecs that expose a cause as its ordered array of encoded reasons.
See
Causefor constructing schemas for full Cause valuesCauseReasonIsofor the ISO shape of each array element
Signature
type CauseIso<E extends Constraint, D extends Constraint> = ReadonlyArray<CauseReasonIso<E, D>>;CauseReasonIso type
Iso representation used for CauseReason schemas.
Details
Failures are represented with a Fail tag and encoded error, defects with a Die tag and encoded defect, and interrupts with an optional fiberId.
Signature
type CauseReasonIso<E extends Constraint, D extends Constraint> =
| {
readonly _tag: "Fail";
readonly error: E["Iso"];
}
| {
readonly _tag: "Die";
readonly error: D["Iso"];
}
| {
readonly _tag: "Interrupt";
readonly fiberId: number | undefined;
};Iso representation used for Chunk schemas: an array of element values using the element schema's Iso type.
When to use
Use when annotating type-level helpers that work with the readonly-array ISO shape of a Chunk schema.
See
Chunkfor the schema interface and constructor that use this ISO representation
Signature
type ChunkIso<Value extends Constraint> = ReadonlyArray<Value["Iso"]>;Iso representation used for Exit schemas.
Details
Successful exits are represented as { _tag: "Success", value }, while failed exits are represented as { _tag: "Failure", cause }.
Signature
type ExitIso<A extends Constraint, E extends Constraint, D extends Constraint> =
| {
readonly _tag: "Success";
readonly value: A["Iso"];
}
| {
readonly _tag: "Failure";
readonly cause: CauseIso<E, D>;
};HashMapIso type
Iso representation used for HashMap schemas: an array of readonly [key, value] tuples using each entry schema's Iso type.
Signature
type HashMapIso<Key extends Constraint, Value extends Constraint> = ReadonlyArray<
readonly [Key["Iso"], Value["Iso"]]
>;HashSetIso type
Iso representation used for HashSet schemas: an array of element values using the element schema's Iso type.
Signature
type HashSetIso<Value extends Constraint> = ReadonlyArray<Value["Iso"]>;LazyArbitrary type
A thunk that, given the fast-check module, returns an Arbitrary<T>. Use this type when you need to defer instantiation of the arbitrary, for example to support recursive schemas.
Signature
type LazyArbitrary<T> = (fc: typeof FastCheck) => FastCheck.Arbitrary<T>;Iso representation used for Option schemas.
Details
None is represented as { _tag: "None" }, while Some is represented as { _tag: "Some", value } using the wrapped schema's Iso type.
Signature
type OptionIso<A extends Constraint> =
| {
readonly _tag: "None";
}
| {
readonly _tag: "Some";
readonly value: A["Iso"];
};ReadonlyMapIso type
Iso representation used for ReadonlyMap schemas: an array of readonly [key, value] tuples using each entry schema's Iso type.
Signature
type ReadonlyMapIso<Key extends Constraint, Value extends Constraint> = ReadonlyArray<
readonly [Key["Iso"], Value["Iso"]]
>;ReadonlySetIso type
Iso representation used for ReadonlySet schemas: an array of element values using the element schema's Iso type.
Signature
type ReadonlySetIso<Value extends Constraint> = ReadonlyArray<Value["Iso"]>;Iso representation used for Result schemas.
Details
Successful results are represented as { _tag: "Success", success }, while failed results are represented as { _tag: "Failure", failure }.
Signature
type ResultIso<A extends Constraint, E extends Constraint> =
| {
readonly _tag: "Success";
readonly success: A["Iso"];
}
| {
readonly _tag: "Failure";
readonly failure: E["Iso"];
};revealBottom
Returns a schema widened to the fully-parameterized Bottom interface, making all 14 type parameters visible to TypeScript.
Details
Normally, concrete schema interfaces (e.g. Schema<string>) hide most type parameters. revealBottom is useful when writing generic utilities that need to inspect or propagate the complete set of type parameters.
Signature
declare function revealBottom<S extends Top>(
bottom: S,
): Bottom<
S["Type"],
S["Encoded"],
S["DecodingServices"],
S["EncodingServices"],
S["ast"],
S["Rebuild"],
S["~type.make.in"],
S["Iso"],
S["~type.parameters"],
S["~type.make"],
S["~type.mutability"],
S["~type.optionality"],
S["~type.constructor.default"],
S["~encoded.mutability"],
S["~encoded.optionality"]
>;revealCodec
Returns a codec widened to the full Codec interface, prompting TypeScript to infer all four type parameters (T, E, RD, RE).
Details
When a schema is stored in a variable typed as Schema<T> or Top, the encoded type and service requirements are erased. Passing the value through revealCodec recovers those parameters without any runtime cost.
Signature
declare function revealCodec<T, E, RD, RE>(codec: Codec<T, E, RD, RE>): Codec<T, E, RD, RE>;Validation
Validates that a string is valid Base64 encoded data.
Details
JSON Schema:
This check corresponds to a pattern constraint in JSON Schema that matches Base64 format.
Arbitrary:
When generating test data with fast-check, this applies a patterns constraint to ensure generated strings match the Base64 pattern.
Signature
declare function isBase64(annotations?: Filter): Filter<string>;isBase64Reviver
Reviver for persisted isBase64 checks.
When to use
Use when reconstructing documents that may contain checks created by isBase64.
See
isBase64for creating the corresponding check
Signature
declare const isBase64Reviver: SchemaRepresentation.FilterReviver<null>;isBase64Url
Validates that a string is valid Base64URL encoded data (Base64 with URL-safe characters).
Details
JSON Schema:
This check corresponds to a pattern constraint in JSON Schema that matches Base64URL format.
Arbitrary:
When generating test data with fast-check, this applies a patterns constraint to ensure generated strings match the Base64URL pattern.
Signature
declare function isBase64Url(annotations?: Filter): Filter<string>;isBase64UrlReviver
Reviver for persisted isBase64Url checks.
When to use
Use when reconstructing documents that may contain checks created by isBase64Url.
See
isBase64Urlfor creating the corresponding check
Signature
declare const isBase64UrlReviver: SchemaRepresentation.FilterReviver<null>;Validates that a number is within a specified range. The range boundaries can be inclusive or exclusive based on the provided options.
Details
JSON Schema:
This check corresponds to minimum/maximum or exclusiveMinimum/exclusiveMaximum constraints in JSON Schema, depending on the options provided.
Arbitrary:
When generating test data with fast-check, this applies minimum and maximum constraints with optional exclusiveMinimum and exclusiveMaximum flags to ensure generated numbers fall within the specified range.
Signature
declare const isBetween: (
options: {
readonly exclusiveMaximum?: boolean;
readonly exclusiveMinimum?: boolean;
readonly maximum: number;
readonly minimum: number;
},
annotations?: Filter,
) => Filter<number>;isBetweenBigDecimal
Validates that a BigDecimal is within a specified range.
Details
The minimum and maximum boundaries are inclusive by default. Pass exclusiveMinimum or exclusiveMaximum to exclude either boundary.
Signature
declare const isBetweenBigDecimal: (
options: {
readonly exclusiveMaximum?: boolean;
readonly exclusiveMinimum?: boolean;
readonly maximum: BigDecimal;
readonly minimum: BigDecimal;
},
annotations?: Filter,
) => Filter<BigDecimal>;isBetweenBigInt
Validates that a BigInt is within a specified range. The range boundaries can be inclusive or exclusive based on the provided options.
Details
Arbitrary:
When generating test data with fast-check, this applies min and max constraints to ensure generated BigInt values fall within the specified range.
Signature
declare const isBetweenBigInt: (
options: {
readonly exclusiveMaximum?: boolean;
readonly exclusiveMinimum?: boolean;
readonly maximum: bigint;
readonly minimum: bigint;
},
annotations?: Filter,
) => Filter<bigint>;isBetweenBigIntReviver
Reviver for persisted isBetweenBigInt checks.
When to use
Use when reconstructing documents that may contain checks created by isBetweenBigInt.
See
isBetweenBigIntfor creating the corresponding check
Signature
declare const isBetweenBigIntReviver: SchemaRepresentation.FilterReviver<{
readonly exclusiveMaximum?: true;
readonly exclusiveMinimum?: true;
readonly maximum: bigint;
readonly minimum: bigint;
}>;isBetweenDate
Validates that a Date is within a specified range. The range boundaries can be inclusive or exclusive based on the provided options.
Details
JSON Schema:
This check does not have a direct JSON Schema equivalent, as JSON Schema validates date strings, not Date objects.
Arbitrary:
When generating test data with fast-check, this applies min and max constraints to ensure generated Date objects fall within the specified range, shifting exclusive bounds by one millisecond.
Signature
declare const isBetweenDate: (
options: {
readonly exclusiveMaximum?: boolean;
readonly exclusiveMinimum?: boolean;
readonly maximum: Date;
readonly minimum: Date;
},
annotations?: Filter,
) => Filter<Date>;isBetweenDateReviver
Reviver for persisted isBetweenDate checks.
When to use
Use when reconstructing documents that may contain checks created by isBetweenDate.
See
isBetweenDatefor creating the corresponding check
Signature
declare const isBetweenDateReviver: SchemaRepresentation.FilterReviver<{
readonly exclusiveMaximum?: true;
readonly exclusiveMinimum?: true;
readonly maximum: globalThis.Date;
readonly minimum: globalThis.Date;
}>;isBetweenReviver
Reviver for persisted isBetween checks.
When to use
Use when reconstructing documents that may contain checks created by isBetween.
See
isBetweenfor creating the corresponding check
Signature
declare const isBetweenReviver: SchemaRepresentation.FilterReviver<{
readonly exclusiveMaximum?: true;
readonly exclusiveMinimum?: true;
readonly maximum: number;
readonly minimum: number;
}>;isCapitalized
Validates that the first character of a string is unchanged by toUpperCase().
Details
Empty strings pass. Strings whose first character has no lowercase form, such as a digit, punctuation mark, or whitespace, also pass.
Signature
declare function isCapitalized(annotations?: Filter): Filter<string>;isCapitalizedReviver
Reviver for persisted isCapitalized checks.
When to use
Use when reconstructing documents that may contain checks created by isCapitalized.
See
isCapitalizedfor creating the corresponding check
Signature
declare const isCapitalizedReviver: SchemaRepresentation.FilterReviver<null>;isEndsWith
Validates at runtime that a string ends with the specified literal suffix.
Details
RegExp metacharacters in the suffix are escaped in JSON Schema and arbitrary metadata so that the generated patterns retain literal endsWith semantics.
Signature
declare function isEndsWith(endsWith: string, annotations?: Filter): Filter<string>;isEndsWithReviver
Reviver for persisted isEndsWith checks.
When to use
Use when reconstructing documents that may contain checks created by isEndsWith.
See
isEndsWithfor creating the corresponding check
Signature
declare const isEndsWithReviver: SchemaRepresentation.FilterReviver<{
readonly endsWith: string;
}>;Validates that a number is finite (not Infinity, -Infinity, or NaN).
Details
JSON Schema:
This check does not have a direct JSON Schema equivalent, but ensures the number is valid and finite.
Arbitrary:
When generating test data with fast-check, this applies noNaN: true and noInfinity: true constraints to ensure generated numbers are finite.
Signature
declare const isFinite: (annotations?: Annotations.Filter) => SchemaAST.Filter<number>;isFiniteReviver
Reviver for persisted isFinite checks.
When to use
Use when reconstructing documents that may contain checks created by isFinite.
See
isFinitefor creating the corresponding check
Signature
declare const isFiniteReviver: SchemaRepresentation.FilterReviver<null>;isGreaterThan
Validates that a number is greater than the specified value (exclusive).
Details
JSON Schema:
This check corresponds to the exclusiveMinimum constraint in JSON Schema.
Arbitrary:
When generating test data with fast-check, this applies an exclusiveMinimum constraint to ensure generated numbers are greater than the specified value.
Signature
declare const isGreaterThan: (exclusiveMinimum: number, annotations?: Filter) => Filter<number>;isGreaterThanBigDecimal
Validates that a BigDecimal is greater than the specified value (exclusive).
Signature
declare const isGreaterThanBigDecimal: (
exclusiveMinimum: BigDecimal,
annotations?: Filter,
) => Filter<BigDecimal>;isGreaterThanBigInt
Validates that a BigInt is greater than the specified value (exclusive).
Details
Arbitrary:
When generating test data with fast-check, this applies a min constraint of exclusiveMinimum + 1n to ensure generated BigInts are greater than the specified value.
Signature
declare const isGreaterThanBigInt: (
exclusiveMinimum: bigint,
annotations?: Filter,
) => Filter<bigint>;isGreaterThanBigIntReviver
Reviver for persisted isGreaterThanBigInt checks.
When to use
Use when reconstructing documents that may contain checks created by isGreaterThanBigInt.
See
isGreaterThanBigIntfor creating the corresponding check
Signature
declare const isGreaterThanBigIntReviver: SchemaRepresentation.FilterReviver<{
readonly exclusiveMinimum: bigint;
}>;isGreaterThanDate
Validates that a Date is greater than the specified value (exclusive).
Details
Arbitrary:
When generating test data with fast-check, this applies a min constraint of one millisecond after the specified value to ensure generated Date objects are greater than it.
Signature
declare const isGreaterThanDate: (exclusiveMinimum: Date, annotations?: Filter) => Filter<Date>;isGreaterThanDateReviver
Reviver for persisted isGreaterThanDate checks.
When to use
Use when reconstructing documents that may contain checks created by isGreaterThanDate.
See
isGreaterThanDatefor creating the corresponding check
Signature
declare const isGreaterThanDateReviver: SchemaRepresentation.FilterReviver<{
readonly exclusiveMinimum: globalThis.Date;
}>;isGreaterThanOrEqualTo
Validates that a number is greater than or equal to the specified value (inclusive).
Details
JSON Schema:
This check corresponds to the minimum constraint in JSON Schema.
Arbitrary:
When generating test data with fast-check, this applies a minimum constraint to ensure generated numbers are greater than or equal to the specified value.
Signature
declare const isGreaterThanOrEqualTo: (minimum: number, annotations?: Filter) => Filter<number>;isGreaterThanOrEqualToBigDecimal
Validates that a BigDecimal is greater than or equal to the specified value (inclusive).
Signature
declare const isGreaterThanOrEqualToBigDecimal: (
minimum: BigDecimal,
annotations?: Filter,
) => Filter<BigDecimal>;isGreaterThanOrEqualToBigInt
Validates that a BigInt is greater than or equal to the specified value (inclusive).
Details
Arbitrary:
When generating test data with fast-check, this applies a min constraint to ensure generated BigInt values are greater than or equal to the specified value.
Signature
declare const isGreaterThanOrEqualToBigInt: (
minimum: bigint,
annotations?: Filter,
) => Filter<bigint>;isGreaterThanOrEqualToBigIntReviver
Reviver for persisted isGreaterThanOrEqualToBigInt checks.
When to use
Use when reconstructing documents that may contain checks created by isGreaterThanOrEqualToBigInt.
See
isGreaterThanOrEqualToBigIntfor creating the corresponding check
Signature
declare const isGreaterThanOrEqualToBigIntReviver: SchemaRepresentation.FilterReviver<{
readonly minimum: bigint;
}>;isGreaterThanOrEqualToDate
Validates that a Date is greater than or equal to the specified date (inclusive).
Details
JSON Schema:
This check does not have a direct JSON Schema equivalent, as JSON Schema validates date strings, not Date objects.
Arbitrary:
When generating test data with fast-check, this applies a min constraint to ensure generated Date objects are greater than or equal to the specified date.
Signature
declare const isGreaterThanOrEqualToDate: (minimum: Date, annotations?: Filter) => Filter<Date>;isGreaterThanOrEqualToDateReviver
Reviver for persisted isGreaterThanOrEqualToDate checks.
When to use
Use when reconstructing documents that may contain checks created by isGreaterThanOrEqualToDate.
See
isGreaterThanOrEqualToDatefor creating the corresponding check
Signature
declare const isGreaterThanOrEqualToDateReviver: SchemaRepresentation.FilterReviver<{
readonly minimum: globalThis.Date;
}>;isGreaterThanOrEqualToReviver
Reviver for persisted isGreaterThanOrEqualTo checks.
When to use
Use when reconstructing documents that may contain checks created by isGreaterThanOrEqualTo.
See
isGreaterThanOrEqualTofor creating the corresponding check
Signature
declare const isGreaterThanOrEqualToReviver: SchemaRepresentation.FilterReviver<{
readonly minimum: number;
}>;isGreaterThanReviver
Reviver for persisted isGreaterThan checks.
When to use
Use when reconstructing documents that may contain checks created by isGreaterThan.
See
isGreaterThanfor creating the corresponding check
Signature
declare const isGreaterThanReviver: SchemaRepresentation.FilterReviver<{
readonly exclusiveMinimum: number;
}>;Validates that a string has the GUID / UUID textual shape.
When to use
Use when you need to accept dashed hexadecimal identifiers without enforcing UUID version or variant bits.
Details
This check accepts strings in the 8-4-4-4-12 hexadecimal form. JSON Schema output includes the corresponding pattern constraint and intentionally does not include format: "uuid" because GUID validation is looser than UUID validation.
Arbitrary:
When generating test data with fast-check, this applies a patterns constraint to ensure generated strings match the GUID pattern.
See
isUUIDfor strict UUID validation.
Signature
declare function isGUID(annotations?: Filter): Filter<string>;isGUIDReviver
Reviver for persisted isGUID checks.
When to use
Use when reconstructing documents that may contain checks created by isGUID.
See
isGUIDfor creating the corresponding check
Signature
declare const isGUIDReviver: SchemaRepresentation.FilterReviver<null>;isIncludes
Validates at runtime that a string contains the specified literal substring.
Details
RegExp metacharacters in the substring are escaped in JSON Schema and arbitrary metadata so that the generated patterns retain literal includes semantics.
Signature
declare function isIncludes(includes: string, annotations?: Filter): Filter<string>;isIncludesReviver
Reviver for persisted isIncludes checks.
When to use
Use when reconstructing documents that may contain checks created by isIncludes.
See
isIncludesfor creating the corresponding check
Signature
declare const isIncludesReviver: SchemaRepresentation.FilterReviver<{
readonly includes: string;
}>;Validates that a number is a safe integer (within the safe integer range that can be exactly represented in JavaScript).
Details
JSON Schema:
This check corresponds to the type: "integer" constraint in JSON Schema.
Arbitrary:
When generating test data with fast-check, this applies an integer: true constraint to ensure generated numbers are integers.
Signature
declare function isInt(annotations?: Filter): Filter<number>;Validates that a number is a 32-bit signed integer (range: -2,147,483,648 to 2,147,483,647).
Details
JSON Schema:
This check corresponds to the format: "int32" constraint in OpenAPI 3.1, or minimum/maximum constraints in other JSON Schema targets.
Arbitrary:
When generating test data with fast-check, this applies integer and range constraints to ensure generated numbers are 32-bit signed integers.
Signature
declare function isInt32(annotations?: Filter): FilterGroup<number>;isIntReviver
Reviver for persisted isInt checks.
When to use
Use when reconstructing documents that may contain checks created by isInt.
See
isIntfor creating the corresponding check
Signature
declare const isIntReviver: SchemaRepresentation.FilterReviver<null>;isLengthBetween
Validates that a value's length is within the specified range. Works with strings and arrays.
Details
JSON Schema:
This check corresponds to minLength/maxLength constraints for strings or minItems/maxItems constraints for arrays in JSON Schema.
Arbitrary:
When generating test data with fast-check, this applies minLength and maxLength constraints to ensure generated strings or arrays have a length within the specified range.
Signature
declare function isLengthBetween(
minimum: number,
maximum: number,
annotations?: Filter,
): Filter<{
readonly length: number;
}>;isLengthBetweenReviver
Reviver for persisted isLengthBetween checks.
When to use
Use when reconstructing documents that may contain checks created by isLengthBetween.
See
isLengthBetweenfor creating the corresponding check
Signature
declare const isLengthBetweenReviver: SchemaRepresentation.FilterReviver<{
readonly maximum: number;
readonly minimum: number;
}>;isLessThan
Validates that a number is less than the specified value (exclusive).
Details
JSON Schema:
This check corresponds to the exclusiveMaximum constraint in JSON Schema.
Arbitrary:
When generating test data with fast-check, this applies an exclusiveMaximum constraint to ensure generated numbers are less than the specified value.
Signature
declare const isLessThan: (exclusiveMaximum: number, annotations?: Filter) => Filter<number>;isLessThanBigDecimal
Validates that a BigDecimal is less than the specified value (exclusive).
Signature
declare const isLessThanBigDecimal: (
exclusiveMaximum: BigDecimal,
annotations?: Filter,
) => Filter<BigDecimal>;isLessThanBigInt
Validates that a BigInt is less than the specified value (exclusive).
Details
Arbitrary:
When generating test data with fast-check, this applies a max constraint of exclusiveMaximum - 1n to ensure generated BigInts are less than the specified value.
Signature
declare const isLessThanBigInt: (exclusiveMaximum: bigint, annotations?: Filter) => Filter<bigint>;isLessThanBigIntReviver
Reviver for persisted isLessThanBigInt checks.
When to use
Use when reconstructing documents that may contain checks created by isLessThanBigInt.
See
isLessThanBigIntfor creating the corresponding check
Signature
declare const isLessThanBigIntReviver: SchemaRepresentation.FilterReviver<{
readonly exclusiveMaximum: bigint;
}>;isLessThanDate
Validates that a Date is less than the specified value (exclusive).
Details
Arbitrary:
When generating test data with fast-check, this applies a max constraint of one millisecond before the specified value to ensure generated Date objects are less than it.
Signature
declare const isLessThanDate: (exclusiveMaximum: Date, annotations?: Filter) => Filter<Date>;isLessThanDateReviver
Reviver for persisted isLessThanDate checks.
When to use
Use when reconstructing documents that may contain checks created by isLessThanDate.
See
isLessThanDatefor creating the corresponding check
Signature
declare const isLessThanDateReviver: SchemaRepresentation.FilterReviver<{
readonly exclusiveMaximum: globalThis.Date;
}>;isLessThanOrEqualTo
Validates that a number is less than or equal to the specified value (inclusive).
Details
JSON Schema:
This check corresponds to the maximum constraint in JSON Schema.
Arbitrary:
When generating test data with fast-check, this applies a maximum constraint to ensure generated numbers are less than or equal to the specified value.
Signature
declare const isLessThanOrEqualTo: (maximum: number, annotations?: Filter) => Filter<number>;isLessThanOrEqualToBigDecimal
Validates that a BigDecimal is less than or equal to the specified value (inclusive).
Signature
declare const isLessThanOrEqualToBigDecimal: (
maximum: BigDecimal,
annotations?: Filter,
) => Filter<BigDecimal>;isLessThanOrEqualToBigInt
Validates that a BigInt is less than or equal to the specified value (inclusive).
Details
Arbitrary:
When generating test data with fast-check, this applies a max constraint to ensure generated BigInt values are less than or equal to the specified value.
Signature
declare const isLessThanOrEqualToBigInt: (maximum: bigint, annotations?: Filter) => Filter<bigint>;isLessThanOrEqualToBigIntReviver
Reviver for persisted isLessThanOrEqualToBigInt checks.
When to use
Use when reconstructing documents that may contain checks created by isLessThanOrEqualToBigInt.
See
isLessThanOrEqualToBigIntfor creating the corresponding check
Signature
declare const isLessThanOrEqualToBigIntReviver: SchemaRepresentation.FilterReviver<{
readonly maximum: bigint;
}>;isLessThanOrEqualToDate
Validates that a Date is less than or equal to the specified date (inclusive).
Details
JSON Schema:
This check does not have a direct JSON Schema equivalent, as JSON Schema validates date strings, not Date objects.
Arbitrary:
When generating test data with fast-check, this applies a max constraint to ensure generated Date objects are less than or equal to the specified date.
Signature
declare const isLessThanOrEqualToDate: (maximum: Date, annotations?: Filter) => Filter<Date>;isLessThanOrEqualToDateReviver
Reviver for persisted isLessThanOrEqualToDate checks.
When to use
Use when reconstructing documents that may contain checks created by isLessThanOrEqualToDate.
See
isLessThanOrEqualToDatefor creating the corresponding check
Signature
declare const isLessThanOrEqualToDateReviver: SchemaRepresentation.FilterReviver<{
readonly maximum: globalThis.Date;
}>;isLessThanOrEqualToReviver
Reviver for persisted isLessThanOrEqualTo checks.
When to use
Use when reconstructing documents that may contain checks created by isLessThanOrEqualTo.
See
isLessThanOrEqualTofor creating the corresponding check
Signature
declare const isLessThanOrEqualToReviver: SchemaRepresentation.FilterReviver<{
readonly maximum: number;
}>;isLessThanReviver
Reviver for persisted isLessThan checks.
When to use
Use when reconstructing documents that may contain checks created by isLessThan.
See
isLessThanfor creating the corresponding check
Signature
declare const isLessThanReviver: SchemaRepresentation.FilterReviver<{
readonly exclusiveMaximum: number;
}>;isLowercased
Validates that a string is unchanged by JavaScript's toLowerCase().
Details
This accepts empty strings and characters that do not have uppercase forms, such as digits, punctuation, and whitespace. It rejects strings that would change when lowercased.
Signature
declare function isLowercased(annotations?: Filter): Filter<string>;isLowercasedReviver
Reviver for persisted isLowercased checks.
When to use
Use when reconstructing documents that may contain checks created by isLowercased.
See
isLowercasedfor creating the corresponding check
Signature
declare const isLowercasedReviver: SchemaRepresentation.FilterReviver<null>;isMaxLength
Validates that a value has at most the specified length. Works with strings and arrays.
Details
JSON Schema:
This check corresponds to the maxLength constraint for strings or the maxItems constraint for arrays in JSON Schema.
Arbitrary:
When generating test data with fast-check, this applies a maxLength constraint to ensure generated strings or arrays have at most the required length.
Signature
declare function isMaxLength(
maxLength: number,
annotations?: Filter,
): Filter<{
readonly length: number;
}>;isMaxLengthReviver
Reviver for persisted isMaxLength checks.
When to use
Use when reconstructing documents that may contain checks created by isMaxLength.
See
isMaxLengthfor creating the corresponding check
Signature
declare const isMaxLengthReviver: SchemaRepresentation.FilterReviver<{
readonly maxLength: number;
}>;isMaxProperties
Validates that an object contains at most the specified number of properties. This includes both string and symbol keys when counting properties.
Details
JSON Schema:
This check corresponds to the maxProperties constraint in JSON Schema.
Arbitrary:
When generating test data with fast-check, this applies a node-local maxLength constraint. Object generators interpret it as the final number of own properties.
Signature
declare function isMaxProperties(maxProperties: number, annotations?: Filter): Filter<object>;isMaxPropertiesReviver
Reviver for persisted isMaxProperties checks.
When to use
Use when reconstructing documents that may contain checks created by isMaxProperties.
See
isMaxPropertiesfor creating the corresponding check
Signature
declare const isMaxPropertiesReviver: SchemaRepresentation.FilterReviver<{
readonly maxProperties: number;
}>;Validates that a value has at most the specified size. Works with values that have a size property, such as Set or Map.
Details
JSON Schema:
This check does not have a direct JSON Schema equivalent, as it applies to values with a size property rather than standard JSON Schema types.
Arbitrary:
When generating test data with fast-check, this applies a node-local maxLength constraint. Generators for values with a final .size, such as sets and maps, interpret it as final cardinality.
Signature
declare function isMaxSize(
maxSize: number,
annotations?: Filter,
): Filter<{
readonly size: number;
}>;isMaxSizeReviver
Reviver for persisted isMaxSize checks.
When to use
Use when reconstructing documents that may contain checks created by isMaxSize.
See
isMaxSizefor creating the corresponding check
Signature
declare const isMaxSizeReviver: SchemaRepresentation.FilterReviver<{
readonly maxSize: number;
}>;isMinLength
Validates that a value has at least the specified length. Works with strings and arrays.
Details
JSON Schema:
This check corresponds to the minLength constraint for strings or the minItems constraint for arrays in JSON Schema.
Arbitrary:
When generating test data with fast-check, this applies a minLength constraint to ensure generated strings or arrays have at least the required length.
Signature
declare function isMinLength(
minLength: number,
annotations?: Filter,
): Filter<{
readonly length: number;
}>;isMinLengthReviver
Reviver for persisted isMinLength checks.
When to use
Use when reconstructing documents that may contain checks created by isMinLength.
See
isMinLengthfor creating the corresponding check
Signature
declare const isMinLengthReviver: SchemaRepresentation.FilterReviver<{
readonly minLength: number;
}>;isMinProperties
Validates that an object contains at least the specified number of properties. This includes both string and symbol keys when counting properties.
Details
JSON Schema:
This check corresponds to the minProperties constraint in JSON Schema.
Arbitrary:
When generating test data with fast-check, this applies a node-local minLength constraint. Object generators interpret it as the final number of own properties.
Signature
declare function isMinProperties(minProperties: number, annotations?: Filter): Filter<object>;isMinPropertiesReviver
Reviver for persisted isMinProperties checks.
When to use
Use when reconstructing documents that may contain checks created by isMinProperties.
See
isMinPropertiesfor creating the corresponding check
Signature
declare const isMinPropertiesReviver: SchemaRepresentation.FilterReviver<{
readonly minProperties: number;
}>;Validates that a value has at least the specified size. Works with values that have a size property, such as Set or Map.
Details
JSON Schema:
This check does not have a direct JSON Schema equivalent, as it applies to values with a size property rather than standard JSON Schema types.
Arbitrary:
When generating test data with fast-check, this applies a node-local minLength constraint. Generators for values with a final .size, such as sets and maps, interpret it as final cardinality.
Signature
declare function isMinSize(
minSize: number,
annotations?: Filter,
): Filter<{
readonly size: number;
}>;isMinSizeReviver
Reviver for persisted isMinSize checks.
When to use
Use when reconstructing documents that may contain checks created by isMinSize.
See
isMinSizefor creating the corresponding check
Signature
declare const isMinSizeReviver: SchemaRepresentation.FilterReviver<{
readonly minSize: number;
}>;isMultipleOf
Validates that a number is a multiple of the specified divisor.
Details
JSON Schema:
This check corresponds to the multipleOf constraint in JSON Schema.
Arbitrary:
When generating test data with fast-check, this applies constraints to ensure generated numbers are multiples of the specified divisor.
Signature
declare const isMultipleOf: (divisor: number, annotations?: Filter) => Filter<number>;isMultipleOfReviver
Reviver for persisted isMultipleOf checks.
When to use
Use when reconstructing documents that may contain checks created by isMultipleOf.
See
isMultipleOffor creating the corresponding check
Signature
declare const isMultipleOfReviver: SchemaRepresentation.FilterReviver<{
readonly divisor: number;
}>;isNonEmpty
Validates that a value has at least one element. Works with strings and arrays. This is equivalent to isMinLength(1).
Details
JSON Schema:
This check corresponds to the minLength: 1 constraint for strings or the minItems: 1 constraint for arrays in JSON Schema.
Arbitrary:
When generating test data with fast-check, this applies a minLength: 1 constraint to ensure generated strings or arrays are non-empty.
Signature
declare function isNonEmpty(annotations?: Filter): Filter<{
readonly length: number;
}>;Validates that a string matches the specified regular expression pattern.
Details
JSON Schema:
This check corresponds to the pattern constraint in JSON Schema.
Arbitrary:
When generating test data with fast-check, this applies a patterns constraint to ensure generated strings match the specified RegExp pattern.
Signature
declare function isPattern(regExp: RegExp, annotations?: Filter): Filter<string>;isPatternReviver
Reviver for persisted isPattern checks.
When to use
Use when reconstructing documents that may contain checks created by isPattern.
See
isPatternfor creating the corresponding check
Signature
declare const isPatternReviver: SchemaRepresentation.FilterReviver<{
readonly flags: string;
readonly source: string;
}>;isPropertiesLengthBetween
Validates that an object contains between minimum and maximum properties (inclusive). This includes both string and symbol keys when counting properties.
Details
JSON Schema:
This check corresponds to minProperties and maxProperties constraints in JSON Schema.
Arbitrary:
When generating test data with fast-check, this applies node-local minLength and maxLength constraints. Object generators interpret them as the final number of own properties.
Signature
declare function isPropertiesLengthBetween(
minimum: number,
maximum: number,
annotations?: Filter,
): Filter<object>;isPropertiesLengthBetweenReviver
Reviver for persisted isPropertiesLengthBetween checks.
When to use
Use when reconstructing documents that may contain checks created by isPropertiesLengthBetween.
See
isPropertiesLengthBetweenfor creating the corresponding check
Signature
declare const isPropertiesLengthBetweenReviver: SchemaRepresentation.FilterReviver<{
readonly maximum: number;
readonly minimum: number;
}>;isPropertyNames
Validates that every own property key of an object satisfies the encoded side of the provided key schema.
Details
This check uses Reflect.ownKeys, so symbol keys are validated in addition to string property names.
JSON Schema: For string property names, this corresponds to the propertyNames constraint in JSON Schema.
Signature
declare function isPropertyNames(keySchema: Constraint, annotations?: Filter): Filter<object>;isPropertyNamesReviver
Reviver for persisted isPropertyNames checks.
When to use
Use when reconstructing documents that may contain checks created by isPropertyNames.
See
isPropertyNamesfor creating the corresponding check
Signature
declare const isPropertyNamesReviver: SchemaRepresentation.FilterReviver<null>;isSizeBetween
Validates that a value's size is within the specified range. Works with values that have a size property, such as Set or Map.
Details
JSON Schema:
This check does not have a direct JSON Schema equivalent, as it applies to values with a size property rather than standard JSON Schema types.
Arbitrary:
When generating test data with fast-check, this applies node-local minLength and maxLength constraints. Generators for values with a final .size, such as sets and maps, interpret them as final cardinality.
Signature
declare function isSizeBetween(
minimum: number,
maximum: number,
annotations?: Filter,
): Filter<{
readonly size: number;
}>;isSizeBetweenReviver
Reviver for persisted isSizeBetween checks.
When to use
Use when reconstructing documents that may contain checks created by isSizeBetween.
See
isSizeBetweenfor creating the corresponding check
Signature
declare const isSizeBetweenReviver: SchemaRepresentation.FilterReviver<{
readonly maximum: number;
readonly minimum: number;
}>;isStartsWith
Validates at runtime that a string starts with the specified literal prefix.
Details
RegExp metacharacters in the prefix are escaped in JSON Schema and arbitrary metadata so that the generated patterns retain literal startsWith semantics.
Signature
declare function isStartsWith(startsWith: string, annotations?: Filter): Filter<string>;isStartsWithReviver
Reviver for persisted isStartsWith checks.
When to use
Use when reconstructing documents that may contain checks created by isStartsWith.
See
isStartsWithfor creating the corresponding check
Signature
declare const isStartsWithReviver: SchemaRepresentation.FilterReviver<{
readonly startsWith: string;
}>;isStringBigInt
Validates that a string is a signed base-10 integer literal for Effect's BigInt string encoding.
Details
The check uses the pattern ^-?\d+$. It does not accept leading +, decimal points, exponent notation, separators, or non-decimal inputs such as hexadecimal strings.
JSON Schema: This check corresponds to a pattern constraint with the same signed base-10 integer pattern.
Signature
declare function isStringBigInt(annotations?: Filter): Filter<string>;isStringBigIntReviver
Reviver for persisted isStringBigInt checks.
When to use
Use when reconstructing documents that may contain checks created by isStringBigInt.
See
isStringBigIntfor creating the corresponding check
Signature
declare const isStringBigIntReviver: SchemaRepresentation.FilterReviver<null>;isStringFinite
Validates that a string represents a finite number.
Details
JSON Schema:
This check corresponds to a pattern constraint in JSON Schema that matches strings representing finite numbers.
Arbitrary:
When generating test data with fast-check, this applies a patterns constraint to ensure generated strings match the number string pattern.
Signature
declare function isStringFinite(annotations?: Filter): Filter<string>;isStringFiniteReviver
Reviver for persisted isStringFinite checks.
When to use
Use when reconstructing documents that may contain checks created by isStringFinite.
See
isStringFinitefor creating the corresponding check
Signature
declare const isStringFiniteReviver: SchemaRepresentation.FilterReviver<null>;isStringSymbol
Validates that a string has the Symbol(description) format used by Effect's symbol string encoding.
Details
The check uses the pattern ^Symbol\((.*)\)$. It is not a general test for whether a string can be passed to JavaScript's Symbol() function.
Signature
declare function isStringSymbol(annotations?: Filter): Filter<string>;isStringSymbolReviver
Reviver for persisted isStringSymbol checks.
When to use
Use when reconstructing documents that may contain checks created by isStringSymbol.
See
isStringSymbolfor creating the corresponding check
Signature
declare const isStringSymbolReviver: SchemaRepresentation.FilterReviver<null>;Validates that a string has no leading or trailing whitespace.
Details
JSON Schema:
This check corresponds to a pattern constraint in JSON Schema that matches strings without leading or trailing whitespace.
Arbitrary:
When generating test data with fast-check, this applies a patterns constraint to ensure generated strings match the trimmed pattern.
Signature
declare function isTrimmed(annotations?: Filter): Filter<string>;isTrimmedReviver
Reviver for persisted isTrimmed checks.
When to use
Use when reconstructing documents that may contain checks created by isTrimmed.
See
isTrimmedfor creating the corresponding check
Signature
declare const isTrimmedReviver: SchemaRepresentation.FilterReviver<null>;Validates that a number is a 32-bit unsigned integer (range: 0 to 4,294,967,295).
Details
JSON Schema:
This check corresponds to the format: "uint32" constraint in OpenAPI 3.1, or minimum/maximum constraints in other JSON Schema targets.
Arbitrary:
When generating test data with fast-check, this applies integer and range constraints to ensure generated numbers are 32-bit unsigned integers.
Signature
declare function isUint32(annotations?: Filter): FilterGroup<number>;Validates that a string is a valid ULID (Universally Unique Lexicographically Sortable Identifier).
Details
JSON Schema:
This check corresponds to a pattern constraint in JSON Schema that matches the ULID format.
Arbitrary:
When generating test data with fast-check, this applies a patterns constraint to ensure generated strings match the ULID pattern.
Signature
declare function isULID(annotations?: Filter): Filter<string>;isULIDReviver
Reviver for persisted isULID checks.
When to use
Use when reconstructing documents that may contain checks created by isULID.
See
isULIDfor creating the corresponding check
Signature
declare const isULIDReviver: SchemaRepresentation.FilterReviver<null>;isUncapitalized
Validates that the first character of a string is unchanged by toLowerCase().
Details
Empty strings pass. Strings whose first character has no uppercase form, such as a digit, punctuation mark, or whitespace, also pass.
Signature
declare function isUncapitalized(annotations?: Filter): Filter<string>;isUncapitalizedReviver
Reviver for persisted isUncapitalized checks.
When to use
Use when reconstructing documents that may contain checks created by isUncapitalized.
See
isUncapitalizedfor creating the corresponding check
Signature
declare const isUncapitalizedReviver: SchemaRepresentation.FilterReviver<null>;Validates that all items in an array are unique according to Effect equality.
Details
JSON Schema: This check corresponds to the uniqueItems: true constraint in JSON Schema.
Arbitrary: When generating test data with fast-check, this applies a node-local unique: true constraint. Array generators translate it to fast-check uniqueArray using Effect equality.
Signature
declare function isUnique<T>(annotations?: Filter): Filter<readonly Array<T>>isUniqueReviver
Reviver for persisted isUnique checks.
When to use
Use when reconstructing documents that may contain checks created by isUnique.
See
isUniquefor creating the corresponding check
Signature
declare const isUniqueReviver: SchemaRepresentation.FilterReviver<null>;isUppercased
Validates that a string is unchanged by JavaScript's toUpperCase().
Details
This accepts empty strings and characters that do not have lowercase forms, such as digits, punctuation, and whitespace. It rejects strings that would change when uppercased.
Signature
declare function isUppercased(annotations?: Filter): Filter<string>;isUppercasedReviver
Reviver for persisted isUppercased checks.
When to use
Use when reconstructing documents that may contain checks created by isUppercased.
See
isUppercasedfor creating the corresponding check
Signature
declare const isUppercasedReviver: SchemaRepresentation.FilterReviver<null>;Validates that a string is a strict Universally Unique Identifier (UUID).
When to use
Use when you need UUID semantics, including version and RFC variant bits, rather than only the dashed hexadecimal shape.
Details
Without a version argument, this accepts UUID versions 1 through 8, the nil UUID (00000000-0000-0000-0000-000000000000), and the max UUID (ffffffff-ffff-ffff-ffff-ffffffffffff). With a version argument, this accepts only UUIDs with that version and RFC variant bits; nil and max UUIDs are not versioned UUIDs and do not match version-specific checks.
JSON Schema:
This check corresponds to a pattern constraint in JSON Schema that matches UUID format, and includes a format: "uuid" annotation.
Arbitrary:
When generating test data with fast-check, this applies a patterns constraint to ensure generated strings match the UUID pattern.
See
isGUIDfor shape-only GUID validation.
Signature
declare function isUUID(
version?: 2 | 1 | 5 | 3 | 4 | 6 | 7 | 8,
annotations?: Filter,
): Filter<string>;isUUIDReviver
Reviver for persisted isUUID checks.
When to use
Use when reconstructing documents that may contain checks created by isUUID.
See
isUUIDfor creating the corresponding check
Signature
declare const isUUIDReviver: SchemaRepresentation.FilterReviver<{
readonly version: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | null;
}>;makeIsBetween
Creates an inclusive or exclusive range check for any ordered type from an Order.Order instance.
Signature
declare function makeIsBetween<T>(deriveOptions: {
readonly annotate?: (options: {
readonly exclusiveMaximum?: boolean;
readonly exclusiveMinimum?: boolean;
readonly maximum: T;
readonly minimum: T;
}) => Filter;
readonly formatter?: Formatter<T, string>;
readonly order: Order<T>;
}): (
options: {
readonly exclusiveMaximum?: boolean;
readonly exclusiveMinimum?: boolean;
readonly maximum: T;
readonly minimum: T;
},
annotations?: Filter,
) => Filter<T>;makeIsGreaterThan
Creates a greater-than (>) check for any ordered type from an Order.Order instance.
Signature
declare function makeIsGreaterThan<T>(options: {
readonly annotate?: (exclusiveMinimum: T) => Filter;
readonly formatter?: Formatter<T, string>;
readonly order: Order<T>;
}): (exclusiveMinimum: T, annotations?: Filter) => Filter<T>;makeIsGreaterThanOrEqualTo
Creates a greater-than-or-equal-to (>=) check for any ordered type from an Order.Order instance.
Signature
declare function makeIsGreaterThanOrEqualTo<T>(options: {
readonly annotate?: (exclusiveMinimum: T) => Filter;
readonly formatter?: Formatter<T, string>;
readonly order: Order<T>;
}): (minimum: T, annotations?: Filter) => Filter<T>;makeIsLessThan
Creates a less-than (<) check for any ordered type from an Order.Order instance.
Signature
declare function makeIsLessThan<T>(options: {
readonly annotate?: (exclusiveMaximum: T) => Filter;
readonly formatter?: Formatter<T, string>;
readonly order: Order<T>;
}): (exclusiveMaximum: T, annotations?: Filter) => Filter<T>;makeIsLessThanOrEqualTo
Creates a less-than-or-equal-to (<=) check for any ordered type from an Order.Order instance.
Signature
declare function makeIsLessThanOrEqualTo<T>(options: {
readonly annotate?: (exclusiveMaximum: T) => Filter;
readonly formatter?: Formatter<T, string>;
readonly order: Order<T>;
}): (maximum: T, annotations?: Filter) => Filter<T>;makeIsMultipleOf
Creates a divisibility check for any numeric type from a remainder function and a zero value.
Signature
declare function makeIsMultipleOf<T>(options: {
readonly annotate?: (divisor: T) => Filter;
readonly formatter?: Formatter<T, string>;
readonly remainder: (input: T, divisor: T) => T;
readonly zero: NoInfer<T>;
}): (divisor: T, annotations?: Filter) => Filter<T>;
Adds metadata annotations to a schema without changing its runtime behavior. This is the pipeable (curried) counterpart of the
.annotatemethod.Details
Annotations provide extra context used by documentation generators, JSON Schema converters, error formatters, and other tooling. Common keys include
title,description,examples,message, andidentifier.See
annotateEncodedto annotate the encoded side instead.