<Self = never, Brand = {}>(identifier?: string): {
<Tag extends string, const Fields extends Struct.Fields>(
tag: Tag,
fields: Fields,
annotations?: Annotations.Declaration<
Self,
readonly [TaggedStruct<Tag, Fields>]
>
): [Self] extends [never]
? MissingSelfGeneric<"Schema.TaggedErrorClass">
: Class<
Self,
TaggedStruct<Tag, Fields>,
Cause_.YieldableError & Brand
>
<Tag extends string, S extends Struct<Struct.Fields>>(
tag: Tag,
schema: S,
annotations?: Annotations.Declaration<
Self,
readonly [
Struct<Simplify<{ readonly _tag: tag<Tag> } & S["fields"]>>
]
>
): [Self] extends [never]
? MissingSelfGeneric<"Schema.TaggedErrorClass">
: Class<
Self,
Struct<Simplify<{ readonly _tag: tag<Tag> } & S["fields"]>>,
Cause_.YieldableError & Brand
>
}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.
Example (Defining a tagged error class)
import { Effect, Schema } from "effect"
class NotFound extends Schema.TaggedErrorClass<NotFound>()("NotFound", {
id: Schema.Number
}) {}
const program = Effect.gen(function*() {
yield* new NotFound({ id: 42 })
})export const const TaggedErrorClass: {
<Self = never, Brand = {}>(
identifier?: string
): {
<
Tag extends string,
Fields extends Struct.Fields
>(
tag: Tag,
fields: Fields,
annotations?: Annotations.Declaration<
Self,
readonly [TaggedStruct<Tag, Fields>]
>
): [Self] extends [never]
? MissingSelfGeneric<"Schema.TaggedErrorClass">
: Class<
Self,
TaggedStruct<Tag, Fields>,
Cause_.YieldableError & Brand
>
<
Tag extends string,
S extends Struct<Struct.Fields>
>(
tag: Tag,
schema: S,
annotations?: Annotations.Declaration<
Self,
readonly [
Struct<
Simplify<
{
readonly _tag: tag<Tag>
} & S["fields"]
>
>
]
>
): [Self] extends [never]
? MissingSelfGeneric<"Schema.TaggedErrorClass">
: Class<
Self,
Struct<
Simplify<
{
readonly _tag: tag<Tag>
} & S["fields"]
>
>,
Cause_.YieldableError & Brand
>
}
}
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.
Example (Defining a tagged error class)
import { Effect, Schema } from "effect"
class NotFound extends Schema.TaggedErrorClass<NotFound>()("NotFound", {
id: Schema.Number
}) {}
const program = Effect.gen(function*() {
yield* new NotFound({ id: 42 })
})
TaggedErrorClass: {
<function (type parameter) Self in <Self = never, Brand = {}>(identifier?: string): {
<Tag extends string, const Fields extends Struct.Fields>(tag: Tag, fields: Fields, annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, TaggedStruct<Tag, Fields>, Cause_.YieldableError & Brand>;
<Tag extends string, S extends Struct<Struct.Fields>>(tag: Tag, schema: S, annotations?: Annotations.Declaration<Self, readonly [Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>, Cause_.YieldableError & Brand>;
}
function (type parameter) Brand in <Self = never, Brand = {}>(identifier?: string): {
<Tag extends string, const Fields extends Struct.Fields>(tag: Tag, fields: Fields, annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, TaggedStruct<Tag, Fields>, Cause_.YieldableError & Brand>;
<Tag extends string, S extends Struct<Struct.Fields>>(tag: Tag, schema: S, annotations?: Annotations.Declaration<Self, readonly [Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>, Cause_.YieldableError & Brand>;
}
identifier: string | undefinedidentifier?: string): {
<function (type parameter) Tag in <Tag extends string, const Fields extends Struct.Fields>(tag: Tag, fields: Fields, annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, TaggedStruct<Tag, Fields>, Cause_.YieldableError & Brand>Tag extends string, const function (type parameter) Fields in <Tag extends string, const Fields extends Struct.Fields>(tag: Tag, fields: Fields, annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, TaggedStruct<Tag, Fields>, Cause_.YieldableError & Brand>Fields extends Struct.type Struct<Fields extends Struct.Fields>.Fields = {
readonly [x: string]: Constraint;
readonly [x: number]: Constraint;
readonly [x: symbol]: Constraint;
}
Constraint for a struct field map: an object whose values are schemas.
Fields>(
tag: Tag extends stringtag: function (type parameter) Tag in <Tag extends string, const Fields extends Struct.Fields>(tag: Tag, fields: Fields, annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, TaggedStruct<Tag, Fields>, Cause_.YieldableError & Brand>Tag,
fields: const Fields extends Struct.Fieldsfields: function (type parameter) Fields in <Tag extends string, const Fields extends Struct.Fields>(tag: Tag, fields: Fields, annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, TaggedStruct<Tag, Fields>, Cause_.YieldableError & Brand>Fields,
annotations: Annotations.Declaration<
Self,
readonly [TaggedStruct<Tag, Fields>]
>
interface Annotations.Declaration<T, TypeParameters extends ReadonlyArray<Constraint> = readonly []>Full annotation set for Declaration schema nodes — used when defining
custom, opaque schema types via Schema.declare. Extends
Bottom
with optional codec, arbitrary, equivalence, and formatter hooks so that
derived capabilities (JSON encoding, property testing, etc.) can be
provided for the custom type.
Declaration<function (type parameter) Self in <Self = never, Brand = {}>(identifier?: string): {
<Tag extends string, const Fields extends Struct.Fields>(tag: Tag, fields: Fields, annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, TaggedStruct<Tag, Fields>, Cause_.YieldableError & Brand>;
<Tag extends string, S extends Struct<Struct.Fields>>(tag: Tag, schema: S, annotations?: Annotations.Declaration<Self, readonly [Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>, Cause_.YieldableError & Brand>;
}
type TaggedStruct<
Tag extends SchemaAST.LiteralValue,
Fields extends Struct.Fields
> = Struct<{
[K in keyof ({
readonly _tag: tag<Tag>
} & Fields)]: ({
readonly _tag: tag<Tag>
} & Fields)[K]
}>
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.
Example (Defining a tagged struct shorthand)
import { Schema } from "effect"
// Defines a struct with a fixed `_tag` field
const tagged = Schema.TaggedStruct("A", {
a: Schema.String
})
// This is the same as writing:
const equivalent = Schema.Struct({
_tag: Schema.tag("A"),
a: Schema.String
})
Example (Accessing the literal value of the tag)
import { Schema } from "effect"
const tagged = Schema.TaggedStruct("A", {
a: Schema.String
})
// literal: "A"
const literal = tagged.fields._tag.schema.literal
Type-level representation returned by
TaggedStruct
.
TaggedStruct<function (type parameter) Tag in <Tag extends string, const Fields extends Struct.Fields>(tag: Tag, fields: Fields, annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, TaggedStruct<Tag, Fields>, Cause_.YieldableError & Brand>Tag, function (type parameter) Fields in <Tag extends string, const Fields extends Struct.Fields>(tag: Tag, fields: Fields, annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, TaggedStruct<Tag, Fields>, Cause_.YieldableError & Brand>Fields>]>
): [function (type parameter) Self in <Self = never, Brand = {}>(identifier?: string): {
<Tag extends string, const Fields extends Struct.Fields>(tag: Tag, fields: Fields, annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, TaggedStruct<Tag, Fields>, Cause_.YieldableError & Brand>;
<Tag extends string, S extends Struct<Struct.Fields>>(tag: Tag, schema: S, annotations?: Annotations.Declaration<Self, readonly [Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>, Cause_.YieldableError & Brand>;
}
type MissingSelfGeneric<
Usage extends string
> =
`Missing \`Self\` generic - use \`class Self extends ${Usage}<Self>(...)\``
interface Class<Self, S extends Constraint & { readonly fields: Struct.Fields; }, Inherited>Type-level representation returned by
Class
.
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.
Gotchas
Passing disableChecks in the options skips constructor validation.
Example (Defining a basic class)
import { Schema } from "effect"
class Person extends Schema.Class<Person>("Person")({
name: Schema.String,
age: Schema.Number
}) {}
const alice = new Person({ name: "Alice", age: 30 })
console.log(alice.name) // "Alice"
console.log(`${alice}`) // "Person({ name: Alice, age: 30 })"
Example (Extending a class)
import { Schema } from "effect"
class Animal extends Schema.Class<Animal>("Animal")({
name: Schema.String
}) {}
class Dog extends Animal.extend<Dog>("Dog")({
breed: Schema.String
}) {}
const dog = new Dog({ name: "Rex", breed: "Labrador" })
console.log(dog.name) // "Rex"
console.log(dog.breed) // "Labrador"
Class<function (type parameter) Self in <Self = never, Brand = {}>(identifier?: string): {
<Tag extends string, const Fields extends Struct.Fields>(tag: Tag, fields: Fields, annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, TaggedStruct<Tag, Fields>, Cause_.YieldableError & Brand>;
<Tag extends string, S extends Struct<Struct.Fields>>(tag: Tag, schema: S, annotations?: Annotations.Declaration<Self, readonly [Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>, Cause_.YieldableError & Brand>;
}
type TaggedStruct<
Tag extends SchemaAST.LiteralValue,
Fields extends Struct.Fields
> = Struct<{
[K in keyof ({
readonly _tag: tag<Tag>
} & Fields)]: ({
readonly _tag: tag<Tag>
} & Fields)[K]
}>
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.
Example (Defining a tagged struct shorthand)
import { Schema } from "effect"
// Defines a struct with a fixed `_tag` field
const tagged = Schema.TaggedStruct("A", {
a: Schema.String
})
// This is the same as writing:
const equivalent = Schema.Struct({
_tag: Schema.tag("A"),
a: Schema.String
})
Example (Accessing the literal value of the tag)
import { Schema } from "effect"
const tagged = Schema.TaggedStruct("A", {
a: Schema.String
})
// literal: "A"
const literal = tagged.fields._tag.schema.literal
Type-level representation returned by
TaggedStruct
.
TaggedStruct<function (type parameter) Tag in <Tag extends string, const Fields extends Struct.Fields>(tag: Tag, fields: Fields, annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, TaggedStruct<Tag, Fields>, Cause_.YieldableError & Brand>Tag, function (type parameter) Fields in <Tag extends string, const Fields extends Struct.Fields>(tag: Tag, fields: Fields, annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, TaggedStruct<Tag, Fields>, Cause_.YieldableError & Brand>Fields>, import Cause_Cause_.type Cause_.YieldableError = /*unresolved*/ anyYieldableError & function (type parameter) Brand in <Self = never, Brand = {}>(identifier?: string): {
<Tag extends string, const Fields extends Struct.Fields>(tag: Tag, fields: Fields, annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, TaggedStruct<Tag, Fields>, Cause_.YieldableError & Brand>;
<Tag extends string, S extends Struct<Struct.Fields>>(tag: Tag, schema: S, annotations?: Annotations.Declaration<Self, readonly [Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>, Cause_.YieldableError & Brand>;
}
function (type parameter) Tag in <Tag extends string, S extends Struct<Struct.Fields>>(tag: Tag, schema: S, annotations?: Annotations.Declaration<Self, readonly [Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>, Cause_.YieldableError & Brand>
function (type parameter) S in <Tag extends string, S extends Struct<Struct.Fields>>(tag: Tag, schema: S, annotations?: Annotations.Declaration<Self, readonly [Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>, Cause_.YieldableError & Brand>
interface Struct<Fields extends Struct.Fields>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.
Example (Defining a basic struct)
import { Schema } from "effect"
const Person = Schema.Struct({
name: Schema.String,
age: Schema.Number,
email: Schema.optionalKey(Schema.String)
})
// { readonly name: string; readonly age: number; readonly email?: string }
type Person = typeof Person.Type
const alice = Schema.decodeUnknownSync(Person)({ name: "Alice", age: 30 })
console.log(alice)
// { name: 'Alice', age: 30 }
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 objectStruct.Type<F> — decoded type of the structStruct.Encoded<F> — encoded type of the structStruct.MakeIn<F> — constructor input (optional/defaulted fields may be omitted)Struct.DecodingServices<F> / Struct.EncodingServices<F> — required services
Type-level representation returned by
Struct
.
Struct<Struct.type Struct<Fields extends Struct.Fields>.Fields = {
readonly [x: string]: Constraint;
readonly [x: number]: Constraint;
readonly [x: symbol]: Constraint;
}
Constraint for a struct field map: an object whose values are schemas.
Fields>>(
tag: Tag extends stringtag: function (type parameter) Tag in <Tag extends string, S extends Struct<Struct.Fields>>(tag: Tag, schema: S, annotations?: Annotations.Declaration<Self, readonly [Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>, Cause_.YieldableError & Brand>
schema: S extends Struct<Struct.Fields>schema: function (type parameter) S in <Tag extends string, S extends Struct<Struct.Fields>>(tag: Tag, schema: S, annotations?: Annotations.Declaration<Self, readonly [Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>, Cause_.YieldableError & Brand>
annotations: Annotations.Declaration<
Self,
readonly [
Struct<
Simplify<
{ readonly _tag: tag<Tag> } & S["fields"]
>
>
]
>
interface Annotations.Declaration<T, TypeParameters extends ReadonlyArray<Constraint> = readonly []>Full annotation set for Declaration schema nodes — used when defining
custom, opaque schema types via Schema.declare. Extends
Bottom
with optional codec, arbitrary, equivalence, and formatter hooks so that
derived capabilities (JSON encoding, property testing, etc.) can be
provided for the custom type.
Declaration<
function (type parameter) Self in <Self = never, Brand = {}>(identifier?: string): {
<Tag extends string, const Fields extends Struct.Fields>(tag: Tag, fields: Fields, annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, TaggedStruct<Tag, Fields>, Cause_.YieldableError & Brand>;
<Tag extends string, S extends Struct<Struct.Fields>>(tag: Tag, schema: S, annotations?: Annotations.Declaration<Self, readonly [Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>, Cause_.YieldableError & Brand>;
}
interface Struct<Fields extends Struct.Fields>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.
Example (Defining a basic struct)
import { Schema } from "effect"
const Person = Schema.Struct({
name: Schema.String,
age: Schema.Number,
email: Schema.optionalKey(Schema.String)
})
// { readonly name: string; readonly age: number; readonly email?: string }
type Person = typeof Person.Type
const alice = Schema.decodeUnknownSync(Person)({ name: "Alice", age: 30 })
console.log(alice)
// { name: 'Alice', age: 30 }
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 objectStruct.Type<F> — decoded type of the structStruct.Encoded<F> — encoded type of the structStruct.MakeIn<F> — constructor input (optional/defaulted fields may be omitted)Struct.DecodingServices<F> / Struct.EncodingServices<F> — required services
Type-level representation returned by
Struct
.
Struct<type Simplify<T> = { [K in keyof T]: T[K]; }Flattens intersection types into a single object type for readability.
When to use
Use when hovering over a type shows A & B & C instead of the merged shape.
Details
This helper is purely cosmetic at the type level and has no runtime effect.
It preserves readonly modifiers; use
Mutable
to strip them.
Example (Flattening an intersection)
import type { Struct } from "effect"
type Original = { a: string } & { b: number }
// Without Simplify, the type displays as `{ a: string } & { b: number }`
type Simplified = Struct.Simplify<Original>
// { a: string; b: number }
Simplify<{ readonly _tag: tag<Tag>(property) _tag: {
Type: S["Type"];
Encoded: S["Encoded"];
DecodingServices: S["DecodingServices"];
EncodingServices: S["EncodingServices"];
Iso: S["Iso"];
schema: S;
Rebuild: Rebuild;
ast: Ast;
annotate: (annotations: Annotations.Bottom<Tag, readonly []>) => withConstructorDefault<Literal<Tag>>;
annotateKey: (annotations: Annotations.Key<Tag>) => withConstructorDefault<Literal<Tag>>;
check: (checks_0: SchemaAST.Check<Tag>, ...checks: Array<SchemaAST.Check<Tag>>) => withConstructorDefault<Literal<Tag>>;
rebuild: (ast: SchemaAST.Literal) => withConstructorDefault<Literal<Tag>>;
make: (input: Tag, options?: MakeOptions) => Tag;
makeOption: (input: Tag, options?: MakeOptions) => Option_.Option<Tag>;
makeEffect: (input: Tag, options?: MakeOptions) => Effect.Effect<Tag, SchemaError, never>;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
}
interface tag<Tag extends SchemaAST.LiteralValue>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.
Example (Defining a discriminated union tag)
import { Schema } from "effect"
const A = Schema.Struct({ _tag: Schema.tag("A"), value: Schema.Number })
// _tag is optional in make, auto-filled to "A"
const a = A.make({ value: 42 })
// a: { _tag: "A", value: 42 }
Type-level representation returned by
tag
.
tag<function (type parameter) Tag in <Tag extends string, S extends Struct<Struct.Fields>>(tag: Tag, schema: S, annotations?: Annotations.Declaration<Self, readonly [Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>, Cause_.YieldableError & Brand>
function (type parameter) S in <Tag extends string, S extends Struct<Struct.Fields>>(tag: Tag, schema: S, annotations?: Annotations.Declaration<Self, readonly [Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>, Cause_.YieldableError & Brand>
function (type parameter) Self in <Self = never, Brand = {}>(identifier?: string): {
<Tag extends string, const Fields extends Struct.Fields>(tag: Tag, fields: Fields, annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, TaggedStruct<Tag, Fields>, Cause_.YieldableError & Brand>;
<Tag extends string, S extends Struct<Struct.Fields>>(tag: Tag, schema: S, annotations?: Annotations.Declaration<Self, readonly [Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>, Cause_.YieldableError & Brand>;
}
type MissingSelfGeneric<
Usage extends string
> =
`Missing \`Self\` generic - use \`class Self extends ${Usage}<Self>(...)\``
interface Class<Self, S extends Constraint & { readonly fields: Struct.Fields; }, Inherited>Type-level representation returned by
Class
.
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.
Gotchas
Passing disableChecks in the options skips constructor validation.
Example (Defining a basic class)
import { Schema } from "effect"
class Person extends Schema.Class<Person>("Person")({
name: Schema.String,
age: Schema.Number
}) {}
const alice = new Person({ name: "Alice", age: 30 })
console.log(alice.name) // "Alice"
console.log(`${alice}`) // "Person({ name: Alice, age: 30 })"
Example (Extending a class)
import { Schema } from "effect"
class Animal extends Schema.Class<Animal>("Animal")({
name: Schema.String
}) {}
class Dog extends Animal.extend<Dog>("Dog")({
breed: Schema.String
}) {}
const dog = new Dog({ name: "Rex", breed: "Labrador" })
console.log(dog.name) // "Rex"
console.log(dog.breed) // "Labrador"
Class<function (type parameter) Self in <Self = never, Brand = {}>(identifier?: string): {
<Tag extends string, const Fields extends Struct.Fields>(tag: Tag, fields: Fields, annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, TaggedStruct<Tag, Fields>, Cause_.YieldableError & Brand>;
<Tag extends string, S extends Struct<Struct.Fields>>(tag: Tag, schema: S, annotations?: Annotations.Declaration<Self, readonly [Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>, Cause_.YieldableError & Brand>;
}
interface Struct<Fields extends Struct.Fields>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.
Example (Defining a basic struct)
import { Schema } from "effect"
const Person = Schema.Struct({
name: Schema.String,
age: Schema.Number,
email: Schema.optionalKey(Schema.String)
})
// { readonly name: string; readonly age: number; readonly email?: string }
type Person = typeof Person.Type
const alice = Schema.decodeUnknownSync(Person)({ name: "Alice", age: 30 })
console.log(alice)
// { name: 'Alice', age: 30 }
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 objectStruct.Type<F> — decoded type of the structStruct.Encoded<F> — encoded type of the structStruct.MakeIn<F> — constructor input (optional/defaulted fields may be omitted)Struct.DecodingServices<F> / Struct.EncodingServices<F> — required services
Type-level representation returned by
Struct
.
Struct<type Simplify<T> = { [K in keyof T]: T[K]; }Flattens intersection types into a single object type for readability.
When to use
Use when hovering over a type shows A & B & C instead of the merged shape.
Details
This helper is purely cosmetic at the type level and has no runtime effect.
It preserves readonly modifiers; use
Mutable
to strip them.
Example (Flattening an intersection)
import type { Struct } from "effect"
type Original = { a: string } & { b: number }
// Without Simplify, the type displays as `{ a: string } & { b: number }`
type Simplified = Struct.Simplify<Original>
// { a: string; b: number }
Simplify<{ readonly _tag: tag<Tag>(property) _tag: {
Type: S["Type"];
Encoded: S["Encoded"];
DecodingServices: S["DecodingServices"];
EncodingServices: S["EncodingServices"];
Iso: S["Iso"];
schema: S;
Rebuild: Rebuild;
ast: Ast;
annotate: (annotations: Annotations.Bottom<Tag, readonly []>) => withConstructorDefault<Literal<Tag>>;
annotateKey: (annotations: Annotations.Key<Tag>) => withConstructorDefault<Literal<Tag>>;
check: (checks_0: SchemaAST.Check<Tag>, ...checks: Array<SchemaAST.Check<Tag>>) => withConstructorDefault<Literal<Tag>>;
rebuild: (ast: SchemaAST.Literal) => withConstructorDefault<Literal<Tag>>;
make: (input: Tag, options?: MakeOptions) => Tag;
makeOption: (input: Tag, options?: MakeOptions) => Option_.Option<Tag>;
makeEffect: (input: Tag, options?: MakeOptions) => Effect.Effect<Tag, SchemaError, never>;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
}
interface tag<Tag extends SchemaAST.LiteralValue>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.
Example (Defining a discriminated union tag)
import { Schema } from "effect"
const A = Schema.Struct({ _tag: Schema.tag("A"), value: Schema.Number })
// _tag is optional in make, auto-filled to "A"
const a = A.make({ value: 42 })
// a: { _tag: "A", value: 42 }
Type-level representation returned by
tag
.
tag<function (type parameter) Tag in <Tag extends string, S extends Struct<Struct.Fields>>(tag: Tag, schema: S, annotations?: Annotations.Declaration<Self, readonly [Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>, Cause_.YieldableError & Brand>
function (type parameter) S in <Tag extends string, S extends Struct<Struct.Fields>>(tag: Tag, schema: S, annotations?: Annotations.Declaration<Self, readonly [Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>, Cause_.YieldableError & Brand>
import Cause_Cause_.type Cause_.YieldableError = /*unresolved*/ anyYieldableError & function (type parameter) Brand in <Self = never, Brand = {}>(identifier?: string): {
<Tag extends string, const Fields extends Struct.Fields>(tag: Tag, fields: Fields, annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, TaggedStruct<Tag, Fields>, Cause_.YieldableError & Brand>;
<Tag extends string, S extends Struct<Struct.Fields>>(tag: Tag, schema: S, annotations?: Annotations.Declaration<Self, readonly [Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, Struct<Simplify<{
readonly _tag: tag<Tag>;
} & S["fields"]>>, Cause_.YieldableError & Brand>;
}
identifier: string | undefinedidentifier?: string) => {
return (
tagValue: stringtagValue: string,
schema: Struct.Fields | Struct<Struct.Fields>schema: Struct.type Struct<Fields extends Struct.Fields>.Fields = {
readonly [x: string]: Constraint;
readonly [x: number]: Constraint;
readonly [x: symbol]: Constraint;
}
Constraint for a struct field map: an object whose values are schemas.
Fields | interface Struct<Fields extends Struct.Fields>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.
Example (Defining a basic struct)
import { Schema } from "effect"
const Person = Schema.Struct({
name: Schema.String,
age: Schema.Number,
email: Schema.optionalKey(Schema.String)
})
// { readonly name: string; readonly age: number; readonly email?: string }
type Person = typeof Person.Type
const alice = Schema.decodeUnknownSync(Person)({ name: "Alice", age: 30 })
console.log(alice)
// { name: 'Alice', age: 30 }
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 objectStruct.Type<F> — decoded type of the structStruct.Encoded<F> — encoded type of the structStruct.MakeIn<F> — constructor input (optional/defaulted fields may be omitted)Struct.DecodingServices<F> / Struct.EncodingServices<F> — required services
Type-level representation returned by
Struct
.
Struct<Struct.type Struct<Fields extends Struct.Fields>.Fields = {
readonly [x: string]: Constraint;
readonly [x: number]: Constraint;
readonly [x: symbol]: Constraint;
}
Constraint for a struct field map: an object whose values are schemas.
Fields>,
annotations: Annotations.Declaration<
any,
readonly [Struct<Struct.Fields>]
>
interface Annotations.Declaration<T, TypeParameters extends ReadonlyArray<Constraint> = readonly []>Full annotation set for Declaration schema nodes — used when defining
custom, opaque schema types via Schema.declare. Extends
Bottom
with optional codec, arbitrary, equivalence, and formatter hooks so that
derived capabilities (JSON encoding, property testing, etc.) can be
provided for the custom type.
Declaration<any, readonly [interface Struct<Fields extends Struct.Fields>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.
Example (Defining a basic struct)
import { Schema } from "effect"
const Person = Schema.Struct({
name: Schema.String,
age: Schema.Number,
email: Schema.optionalKey(Schema.String)
})
// { readonly name: string; readonly age: number; readonly email?: string }
type Person = typeof Person.Type
const alice = Schema.decodeUnknownSync(Person)({ name: "Alice", age: 30 })
console.log(alice)
// { name: 'Alice', age: 30 }
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 objectStruct.Type<F> — decoded type of the structStruct.Encoded<F> — encoded type of the structStruct.MakeIn<F> — constructor input (optional/defaulted fields may be omitted)Struct.DecodingServices<F> / Struct.EncodingServices<F> — required services
Type-level representation returned by
Struct
.
Struct<Struct.type Struct<Fields extends Struct.Fields>.Fields = {
readonly [x: string]: Constraint;
readonly [x: number]: Constraint;
readonly [x: symbol]: Constraint;
}
Constraint for a struct field map: an object whose values are schemas.
Fields>]>
): any => {
const const struct:
| TaggedStruct<string, Struct.Fields>
| Struct<{
readonly _tag: tag<string>
}>
function isStruct(
schema: Struct.Fields | Struct<Struct.Fields>
): schema is Struct<Struct.Fields>
schema: Struct.Fields | Struct<Struct.Fields>schema) ?
schema: Struct.Fields | Struct<Struct.Fields>(parameter) schema: {
Type: Struct.Type<Fields>;
Encoded: Struct.Encoded<Fields>;
DecodingServices: Struct.DecodingServices<Fields>;
EncodingServices: Struct.EncodingServices<Fields>;
Iso: Struct.Iso<Fields>;
fields: Fields;
mapFields: (f: (fields: Struct.Fields) => To, options?: { readonly unsafePreserveChecks?: boolean | undefined } | undefined) => Struct<{ [K in keyof Readonly<To>]: Readonly<To>[K]; }>;
Rebuild: Rebuild;
ast: Ast;
annotate: (annotations: Annotations.Bottom<Struct.ReadonlySide<Struct.Fields, 'Type'>, readonly []>) => Struct<Struct.Fields>;
annotateKey: (annotations: Annotations.Key<Struct.ReadonlySide<Struct.Fields, 'Type'>>) => Struct<Struct.Fields>;
check: (checks_0: SchemaAST.Check<Struct.ReadonlySide<Struct.Fields, 'Type'>>, ...checks: Array<SchemaAST.Check<Struct.ReadonlySide<Struct.Fields, 'Type'>>>) => Struct<Struct.Fields>;
rebuild: (ast: SchemaAST.Objects) => Struct<Struct.Fields>;
make: (input: Struct.ReadonlyMakeIn<Struct.Fields>, options?: MakeOptions) => Struct.ReadonlySide<Struct.Fields, 'Type'>;
makeOption: (input: Struct.ReadonlyMakeIn<Struct.Fields>, options?: MakeOptions) => Option_.Option<Struct.ReadonlySide<Struct.Fields, 'Type'>>;
makeEffect: (input: Struct.ReadonlyMakeIn<Struct.Fields>, options?: MakeOptions) => Effect.Effect<Struct.ReadonlySide<Struct.Fields, 'Type'>, SchemaError, never>;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
}
Struct<Struct.Fields>.mapFields<{
_tag: tag<string>;
}>(f: (fields: Struct<Fields extends Struct.Fields>.Fields) => {
_tag: tag<string>;
}, options?: {
readonly unsafePreserveChecks?: boolean | undefined;
} | undefined): Struct<{
readonly _tag: tag<string>;
}>
Returns a new struct with the fields modified by the provided function.
Details
Options:
-
unsafePreserveChecks - if true, keep any .check(...) constraints
that were attached to the original union. Defaults to false.
Warning: This is an unsafe operation. Since mapFields
transformations change the schema type, the original refinement functions
may no longer be valid or safe to apply to the transformed schema. Only
use this option if you have verified that your refinements remain correct
after the transformation.
mapFields((fields: Struct.Fieldsfields) => ({ _tag: tag<string>(property) _tag: {
Type: S["Type"];
Encoded: S["Encoded"];
DecodingServices: S["DecodingServices"];
EncodingServices: S["EncodingServices"];
Iso: S["Iso"];
schema: S;
Rebuild: Rebuild;
ast: Ast;
annotate: (annotations: Annotations.Bottom<string, readonly []>) => withConstructorDefault<Literal<string>>;
annotateKey: (annotations: Annotations.Key<string>) => withConstructorDefault<Literal<string>>;
check: (checks_0: SchemaAST.Check<string>, ...checks: Array<SchemaAST.Check<string>>) => withConstructorDefault<Literal<string>>;
rebuild: (ast: SchemaAST.Literal) => withConstructorDefault<Literal<string>>;
make: (input: string, options?: MakeOptions) => string;
makeOption: (input: string, options?: MakeOptions) => Option_.Option<string>;
makeEffect: (input: string, options?: MakeOptions) => Effect.Effect<string, SchemaError, never>;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
}
function tag<
Tag extends SchemaAST.LiteralValue
>(literal: Tag): tag<Tag>
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.
Example (Defining a discriminated union tag)
import { Schema } from "effect"
const A = Schema.Struct({ _tag: Schema.tag("A"), value: Schema.Number })
// _tag is optional in make, auto-filled to "A"
const a = A.make({ value: 42 })
// a: { _tag: "A", value: 42 }
tag(tagValue: stringtagValue), ...fields: Struct.Fieldsfields }), {
unsafePreserveChecks?: boolean | undefinedunsafePreserveChecks: true
}) :
function TaggedStruct<
Tag extends SchemaAST.LiteralValue,
Fields extends Struct.Fields
>(
value: Tag,
fields: Fields
): TaggedStruct<Tag, Fields>
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.
Example (Defining a tagged struct shorthand)
import { Schema } from "effect"
// Defines a struct with a fixed `_tag` field
const tagged = Schema.TaggedStruct("A", {
a: Schema.String
})
// This is the same as writing:
const equivalent = Schema.Struct({
_tag: Schema.tag("A"),
a: Schema.String
})
Example (Accessing the literal value of the tag)
import { Schema } from "effect"
const tagged = Schema.TaggedStruct("A", {
a: Schema.String
})
// literal: "A"
const literal = tagged.fields._tag.schema.literal
TaggedStruct(tagValue: stringtagValue, schema: Struct.Fields | Struct<Struct.Fields>schema)
return const ErrorClass: {
<Self = never, Brand = {}>(
identifier: string
): {
<Fields extends Struct.Fields>(
fields: Fields,
annotations?: Annotations.Declaration<
Self,
readonly [Struct<Fields>]
>
): [Self] extends [never]
? MissingSelfGeneric<"Schema.ErrorClass">
: Class<
Self,
Struct<Fields>,
Cause_.YieldableError & Brand
>
<S extends Struct<Struct.Fields>>(
schema: S,
annotations?: Annotations.Declaration<
Self,
readonly [S]
>
): [Self] extends [never]
? MissingSelfGeneric<"Schema.ErrorClass">
: Class<
Self,
S,
Cause_.YieldableError & Brand
>
}
}
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.
Example (Schema-backed error)
import { Effect, Schema } from "effect"
class NotFound extends Schema.ErrorClass<NotFound>("NotFound")({
id: Schema.Number
}) {}
const program = Effect.gen(function*() {
yield* new NotFound({ id: 1 })
})
ErrorClass<any, {}>(identifier: string | undefinedidentifier ?? tagValue: stringtagValue)(
const struct:
| TaggedStruct<string, Struct.Fields>
| Struct<{
readonly _tag: tag<string>
}>
annotations: Annotations.Declaration<
any,
readonly [Struct<Struct.Fields>]
>
interface Annotations.Declaration<T, TypeParameters extends ReadonlyArray<Constraint> = readonly []>Full annotation set for Declaration schema nodes — used when defining
custom, opaque schema types via Schema.declare. Extends
Bottom
with optional codec, arbitrary, equivalence, and formatter hooks so that
derived capabilities (JSON encoding, property testing, etc.) can be
provided for the custom type.
Declaration<any, readonly [typeof const struct:
| TaggedStruct<string, Struct.Fields>
| Struct<{
readonly _tag: tag<string>
}>