CauseReason<E, D>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.
export interface interface CauseReason<E extends Constraint, D extends Constraint>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.
Type-level representation returned by
CauseReason
.
CauseReason<function (type parameter) E in CauseReason<E extends Constraint, D extends Constraint>E extends Constraint, function (type parameter) D in CauseReason<E extends Constraint, D extends Constraint>D extends Constraint> extends
interface declareConstructor<T, E, TypeParameters extends ReadonlyArray<Constraint>, Iso = T>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
Type-level representation returned by
declareConstructor
.
declareConstructor<
import Cause_Cause_.type Reason<E> = Cause_.Fail<E> | Cause_.Die | Cause_.InterruptA single entry inside a Cause's reasons array.
Details
Narrow to a concrete type with
isFailReason
,
isDieReason
,
or
isInterruptReason
.
Fail<E> — typed error, access via .error
Die — untyped defect, access via .defect
Interrupt — fiber interruption, access via .fiberId
Every reason carries an annotations map and an annotate method for
attaching tracing metadata.
Example (Narrowing a reason)
import { Cause } from "effect"
const reason = Cause.fail("error").reasons[0]
if (Cause.isFailReason(reason)) {
console.log(reason.error) // "error"
}
Companion namespace for the Reason type.
Reason<function (type parameter) E in CauseReason<E extends Constraint, D extends Constraint>E["Type"]>,
import Cause_Cause_.type Reason<E> = Cause_.Fail<E> | Cause_.Die | Cause_.InterruptA single entry inside a Cause's reasons array.
Details
Narrow to a concrete type with
isFailReason
,
isDieReason
,
or
isInterruptReason
.
Fail<E> — typed error, access via .error
Die — untyped defect, access via .defect
Interrupt — fiber interruption, access via .fiberId
Every reason carries an annotations map and an annotate method for
attaching tracing metadata.
Example (Narrowing a reason)
import { Cause } from "effect"
const reason = Cause.fail("error").reasons[0]
if (Cause.isFailReason(reason)) {
console.log(reason.error) // "error"
}
Companion namespace for the Reason type.
Reason<function (type parameter) E in CauseReason<E extends Constraint, D extends Constraint>E["Encoded"]>,
readonly [function (type parameter) E in CauseReason<E extends Constraint, D extends Constraint>E, function (type parameter) D in CauseReason<E extends Constraint, D extends Constraint>D],
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 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.
CauseReasonIso<function (type parameter) E in CauseReason<E extends Constraint, D extends Constraint>E, function (type parameter) D in CauseReason<E extends Constraint, D extends Constraint>D>
>
{
readonly "Rebuild": interface CauseReason<E extends Constraint, D extends Constraint>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.
Type-level representation returned by
CauseReason
.
CauseReason<function (type parameter) E in CauseReason<E extends Constraint, D extends Constraint>E, function (type parameter) D in CauseReason<E extends Constraint, D extends Constraint>D>
readonly CauseReason<E extends Constraint, D extends Constraint>.error: E extends Constrainterror: function (type parameter) E in CauseReason<E extends Constraint, D extends Constraint>E
readonly CauseReason<E extends Constraint, D extends Constraint>.defect: D extends Constraintdefect: function (type parameter) D in CauseReason<E extends Constraint, D extends Constraint>D
}
/**
* 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`.
*
* @category CauseReason
* @since 4.0.0
*/
export type 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 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.
CauseReasonIso<function (type parameter) E in type CauseReasonIso<E extends Constraint, D extends Constraint>E extends Constraint, function (type parameter) D in type CauseReasonIso<E extends Constraint, D extends Constraint>D extends Constraint> = {
readonly _tag: "Fail"_tag: "Fail"
readonly error: E["Iso"]error: function (type parameter) E in type CauseReasonIso<E extends Constraint, D extends Constraint>E["Iso"]
} | {
readonly _tag: "Die"_tag: "Die"
readonly error: D["Iso"]error: function (type parameter) D in type CauseReasonIso<E extends Constraint, D extends Constraint>D["Iso"]
} | {
readonly _tag: "Interrupt"_tag: "Interrupt"
readonly fiberId: number | undefinedfiberId: number | undefined
}
/**
* 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 {@link Cause} for constructing schemas for full Cause values
* @see {@link CauseReasonIso} for the ISO shape of each cause reason
*
* @category CauseReason
* @since 4.0.0
*/
export function function CauseReason<
E extends Constraint,
D extends Constraint
>(error: E, defect: D): CauseReason<E, D>
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.
CauseReason<function (type parameter) E in CauseReason<E extends Constraint, D extends Constraint>(error: E, defect: D): CauseReason<E, D>E extends Constraint, function (type parameter) D in CauseReason<E extends Constraint, D extends Constraint>(error: E, defect: D): CauseReason<E, D>D extends Constraint>(error: E extends Constrainterror: function (type parameter) E in CauseReason<E extends Constraint, D extends Constraint>(error: E, defect: D): CauseReason<E, D>E, defect: D extends Constraintdefect: function (type parameter) D in CauseReason<E extends Constraint, D extends Constraint>(error: E, defect: D): CauseReason<E, D>D): interface CauseReason<E extends Constraint, D extends Constraint>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.
Type-level representation returned by
CauseReason
.
CauseReason<function (type parameter) E in CauseReason<E extends Constraint, D extends Constraint>(error: E, defect: D): CauseReason<E, D>E, function (type parameter) D in CauseReason<E extends Constraint, D extends Constraint>(error: E, defect: D): CauseReason<E, D>D> {
const const schema: declareConstructor<
Cause_.Reason<E["Type"]>,
Cause_.Reason<E["Encoded"]>,
readonly [E, D],
CauseReasonIso<E, D>
>
const schema: {
Rebuild: Rebuild;
Iso: Iso;
ast: Ast;
Type: T;
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
annotate: (annotations: Annotations.Bottom<Cause_.Reason<E['Type']>, readonly [E, D]>) => declareConstructor<Cause_.Reason<E['Type']>, Cause_.Reason<E['Encoded']>, readonly [E, D], CauseReasonIso<E, D>>;
annotateKey: (annotations: Annotations.Key<Cause_.Reason<E['Type']>>) => declareConstructor<Cause_.Reason<E['Type']>, Cause_.Reason<E['Encoded']>, readonly [E, D], CauseReasonIso<E, D>>;
check: (checks_0: SchemaAST.Check<Cause_.Reason<E['Type']>>, ...checks: Array<SchemaAST.Check<Cause_.Reason<E['Type']>>>) => declareConstructor<Cause_.Reason<E['Type']>, Cause_.Reason<E['Encoded']>, readonly [E, D], CauseReasonIso<E, D>>;
rebuild: (ast: SchemaAST.Declaration) => declareConstructor<Cause_.Reason<E['Type']>, Cause_.Reason<E['Encoded']>, readonly [E, D], CauseReasonIso<E, D>>;
make: (input: Cause_.Reason<E['Type']>, options?: MakeOptions) => Cause_.Reason<E['Type']>;
makeOption: (input: Cause_.Reason<E['Type']>, options?: MakeOptions) => Option_.Option<Cause_.Reason<E['Type']>>;
makeEffect: (input: Cause_.Reason<E['Type']>, options?: MakeOptions) => Effect.Effect<Cause_.Reason<E['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; <…;
}
schema = function declareConstructor<
T,
E = T,
Iso = T
>(): <
TypeParameters extends ReadonlyArray<Constraint>
>(
typeParameters: TypeParameters,
run: (typeParameters: {
readonly [K in keyof TypeParameters]: Codec<
TypeParameters[K]["Type"],
TypeParameters[K]["Encoded"]
>
}) => (
u: unknown,
self: SchemaAST.Declaration,
options: SchemaAST.ParseOptions
) => Effect.Effect<T, SchemaIssue.Issue>,
annotations?: Annotations.Declaration<
T,
TypeParameters
>
) => declareConstructor<T, E, TypeParameters, Iso>
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
declareConstructor<import Cause_Cause_.type Reason<E> = Cause_.Fail<E> | Cause_.Die | Cause_.InterruptA single entry inside a Cause's reasons array.
Details
Narrow to a concrete type with
isFailReason
,
isDieReason
,
or
isInterruptReason
.
Fail<E> — typed error, access via .error
Die — untyped defect, access via .defect
Interrupt — fiber interruption, access via .fiberId
Every reason carries an annotations map and an annotate method for
attaching tracing metadata.
Example (Narrowing a reason)
import { Cause } from "effect"
const reason = Cause.fail("error").reasons[0]
if (Cause.isFailReason(reason)) {
console.log(reason.error) // "error"
}
Companion namespace for the Reason type.
Reason<function (type parameter) E in CauseReason<E extends Constraint, D extends Constraint>(error: E, defect: D): CauseReason<E, D>E["Type"]>, import Cause_Cause_.type Reason<E> = Cause_.Fail<E> | Cause_.Die | Cause_.InterruptA single entry inside a Cause's reasons array.
Details
Narrow to a concrete type with
isFailReason
,
isDieReason
,
or
isInterruptReason
.
Fail<E> — typed error, access via .error
Die — untyped defect, access via .defect
Interrupt — fiber interruption, access via .fiberId
Every reason carries an annotations map and an annotate method for
attaching tracing metadata.
Example (Narrowing a reason)
import { Cause } from "effect"
const reason = Cause.fail("error").reasons[0]
if (Cause.isFailReason(reason)) {
console.log(reason.error) // "error"
}
Companion namespace for the Reason type.
Reason<function (type parameter) E in CauseReason<E extends Constraint, D extends Constraint>(error: E, defect: D): CauseReason<E, D>E["Encoded"]>, 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 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.
CauseReasonIso<function (type parameter) E in CauseReason<E extends Constraint, D extends Constraint>(error: E, defect: D): CauseReason<E, D>E, function (type parameter) D in CauseReason<E extends Constraint, D extends Constraint>(error: E, defect: D): CauseReason<E, D>D>>()(
[error: E extends Constrainterror, defect: D extends Constraintdefect],
([error: Codec<
E["Type"],
E["Encoded"],
never,
never
>
(parameter) error: {
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
Rebuild: Codec<T, E, RD, RE>;
Type: T;
Iso: Iso;
ast: Ast;
annotate: (annotations: Annotations.Bottom<E['Type'], any>) => Codec<E['Type'], E['Encoded'], never, never>;
annotateKey: (annotations: Annotations.Key<E['Type']>) => Codec<E['Type'], E['Encoded'], never, never>;
check: (checks_0: SchemaAST.Check<E['Type']>, ...checks: Array<SchemaAST.Check<E['Type']>>) => Codec<E['Type'], E['Encoded'], never, never>;
rebuild: (ast: SchemaAST.AST) => Codec<E['Type'], E['Encoded'], never, never>;
make: (input: unknown, options?: MakeOptions) => E['Type'];
makeOption: (input: unknown, options?: MakeOptions) => Option_.Option<E['Type']>;
makeEffect: (input: unknown, options?: MakeOptions) => Effect.Effect<E['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; <…;
}
error, defect: Codec<
D["Type"],
D["Encoded"],
never,
never
>
(parameter) defect: {
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
Rebuild: Codec<T, E, RD, RE>;
Type: T;
Iso: Iso;
ast: Ast;
annotate: (annotations: Annotations.Bottom<D['Type'], any>) => Codec<D['Type'], D['Encoded'], never, never>;
annotateKey: (annotations: Annotations.Key<D['Type']>) => Codec<D['Type'], D['Encoded'], never, never>;
check: (checks_0: SchemaAST.Check<D['Type']>, ...checks: Array<SchemaAST.Check<D['Type']>>) => Codec<D['Type'], D['Encoded'], never, never>;
rebuild: (ast: SchemaAST.AST) => Codec<D['Type'], D['Encoded'], never, never>;
make: (input: unknown, options?: MakeOptions) => D['Type'];
makeOption: (input: unknown, options?: MakeOptions) => Option_.Option<D['Type']>;
makeEffect: (input: unknown, options?: MakeOptions) => Effect.Effect<D['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; <…;
}
defect]) => (input: unknowninput, ast: SchemaAST.Declaration(parameter) ast: {
_tag: 'Declaration';
typeParameters: ReadonlyArray<AST>;
run: (typeParameters: ReadonlyArray<AST>) => (input: unknown, self: Declaration, options: ParseOptions) => Effect.Effect<any, SchemaIssue.Issue, any>;
encodingChecks: Checks | undefined;
getParser: () => SchemaParser.Parser;
_rebuild: (recur: (ast: AST) => AST, checks: Checks | undefined, encodingChecks: Checks | undefined) => Declaration;
recur: (recur: (ast: AST) => AST) => Declaration;
flip: (recur: (ast: AST) => AST) => Declaration;
getExpected: () => string;
annotations: Schema.Annotations.Annotations | undefined;
checks: Checks | undefined;
encoding: Encoding | undefined;
context: Context | undefined;
toString: () => string;
}
ast, options: SchemaAST.ParseOptions(parameter) options: {
errors: "first" | "all" | undefined;
onExcessProperty: "ignore" | "error" | "preserve" | undefined;
propertyOrder: "none" | "original" | undefined;
disableChecks: boolean | undefined;
concurrency: number | "unbounded" | undefined;
}
options) => {
if (!import Cause_Cause_.const isReason: (
self: unknown
) => self is Reason<unknown>
Checks whether an arbitrary value is a Reason (Fail, Die, or Interrupt).
Example (Checking the runtime type)
import { Cause } from "effect"
const reason = Cause.fail("error").reasons[0]
console.log(Cause.isReason(reason)) // true
console.log(Cause.isReason("not a reason")) // false
isReason(input: unknowninput)) {
return import EffectEffect.const fail: <E>(
error: E
) => Effect<never, E>
Creates an Effect that represents a recoverable error.
When to use
Use to explicitly signal a recoverable error in an Effect.
Details
The error keeps propagating unless it is handled. You can handle tagged
errors with functions like
catchTag
or
catchTags
.
Example (Creating a failed effect)
import { Data, Effect } from "effect"
class OperationFailedError extends Data.TaggedError("OperationFailedError")<{}> {}
// ┌─── Effect<never, OperationFailedError, never>
// ▼
const failure = Effect.fail(
new OperationFailedError()
)
fail(new import SchemaIssueSchemaIssue.constructor InvalidType(ast: SchemaAST.AST, actual: Option_.Option<unknown>): SchemaIssue.InvalidTypeRepresents a schema issue produced when the runtime type of the input does not match the type
expected by the schema (e.g. got null when string was expected).
When to use
Use when you need to detect basic type mismatches, such as a wrong primitive
or null where an object was expected.
Details
ast is the schema node that expected a different type.
actual is Option.some(value) when the input was present, or
Option.none() when no value was provided.
- The default formatter renders this as
"Expected <type>, got <actual>".
Example (Formatting output)
import { Schema } from "effect"
try {
Schema.decodeUnknownSync(Schema.String)(42)
} catch (e) {
if (Schema.isSchemaError(e)) {
console.log(String(e.issue))
// "Expected string, got 42"
}
}
InvalidType(ast: SchemaAST.Declaration(parameter) ast: {
_tag: 'Declaration';
typeParameters: ReadonlyArray<AST>;
run: (typeParameters: ReadonlyArray<AST>) => (input: unknown, self: Declaration, options: ParseOptions) => Effect.Effect<any, SchemaIssue.Issue, any>;
encodingChecks: Checks | undefined;
getParser: () => SchemaParser.Parser;
_rebuild: (recur: (ast: AST) => AST, checks: Checks | undefined, encodingChecks: Checks | undefined) => Declaration;
recur: (recur: (ast: AST) => AST) => Declaration;
flip: (recur: (ast: AST) => AST) => Declaration;
getExpected: () => string;
annotations: Schema.Annotations.Annotations | undefined;
checks: Checks | undefined;
encoding: Encoding | undefined;
context: Context | undefined;
toString: () => string;
}
ast, import Option_Option_.const some: <A>(value: A) => Option<A>Wraps the given value into an Option to represent its presence.
When to use
Use to wrap a known present value as Option
- Returning a successful result from a partial function
Details
- Always returns
Some<A>
- Does not filter
null or undefined; use
fromNullishOr
for that
Example (Wrapping a value)
import { Option } from "effect"
// ┌─── Option<number>
// ▼
const value = Option.some(1)
console.log(value)
// Output: { _id: 'Option', _tag: 'Some', value: 1 }
some(input: unknowninput)))
}
switch (input: Cause_.Reason<unknown>input.Cause<out E>.ReasonProto<Tag extends string>._tag: "Fail" | "Die" | "Interrupt"_tag) {
case "Fail":
return import EffectEffect.const mapBothEager: {
<E, E2, A, A2>(options: {
readonly onFailure: (e: E) => E2
readonly onSuccess: (a: A) => A2
}): <R>(
self: Effect<A, E, R>
) => Effect<A2, E2, R>
<A, E, R, E2, A2>(
self: Effect<A, E, R>,
options: {
readonly onFailure: (e: E) => E2
readonly onSuccess: (a: A) => A2
}
): Effect<A2, E2, R>
}
mapBothEager(
import SchemaParserSchemaParser.function decodeUnknownEffect<
S extends Schema.Constraint
>(
schema: S,
options?: SchemaAST.ParseOptions
): (
input: unknown,
options?: SchemaAST.ParseOptions
) => Effect.Effect<
S["Type"],
SchemaIssue.Issue,
S["DecodingServices"]
>
Creates an effectful decoder for unknown input.
When to use
Use when you need to decode untyped boundary input in an Effect whose
failure channel is SchemaIssue.Issue, while preserving transformations
and service requirements.
Details
The returned function succeeds with the schema's decoded Type or fails with a
SchemaIssue.Issue. Decoding service requirements are preserved in the returned
Effect. Parse options may be provided when creating the decoder and overridden
when applying it.
decodeUnknownEffect(error: Codec<
E["Type"],
E["Encoded"],
never,
never
>
(parameter) error: {
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
Rebuild: Codec<T, E, RD, RE>;
Type: T;
Iso: Iso;
ast: Ast;
annotate: (annotations: Annotations.Bottom<E['Type'], any>) => Codec<E['Type'], E['Encoded'], never, never>;
annotateKey: (annotations: Annotations.Key<E['Type']>) => Codec<E['Type'], E['Encoded'], never, never>;
check: (checks_0: SchemaAST.Check<E['Type']>, ...checks: Array<SchemaAST.Check<E['Type']>>) => Codec<E['Type'], E['Encoded'], never, never>;
rebuild: (ast: SchemaAST.AST) => Codec<E['Type'], E['Encoded'], never, never>;
make: (input: unknown, options?: MakeOptions) => E['Type'];
makeOption: (input: unknown, options?: MakeOptions) => Option_.Option<E['Type']>;
makeEffect: (input: unknown, options?: MakeOptions) => Effect.Effect<E['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; <…;
}
error)(input: Cause_.Fail<unknown>(parameter) input: {
error: E;
_tag: Tag;
annotations: ReadonlyMap<string, unknown>;
annotate: (annotations: Context.Context<never> | ReadonlyMap<string, unknown>, options?: { readonly overwrite?: boolean | undefined }) => Fail<unknown>;
toString: () => string;
toJSON: () => unknown;
}
input.Fail<unknown>.error: unknownerror, options: SchemaAST.ParseOptions(parameter) options: {
errors: "first" | "all" | undefined;
onExcessProperty: "ignore" | "error" | "preserve" | undefined;
propertyOrder: "none" | "original" | undefined;
disableChecks: boolean | undefined;
concurrency: number | "unbounded" | undefined;
}
options),
{
onSuccess: <E>(error: E) => Fail<E>onSuccess: import Cause_Cause_.const makeFailReason: <E>(
error: E
) => Fail<E>
Creates a standalone Fail reason (not wrapped in a Cause).
When to use
Use when constructing a standalone typed failure reason for
fromReasons
or direct comparison.
Example (Creating a Fail reason)
import { Cause } from "effect"
const reason = Cause.makeFailReason("error")
console.log(reason._tag) // "Fail"
console.log(reason.error) // "error"
makeFailReason,
onFailure: (
e: SchemaIssue.Issue
) => SchemaIssue.Composite
onFailure: (issue: SchemaIssue.Issueissue) =>
new import SchemaIssueSchemaIssue.constructor Composite(ast: SchemaAST.AST, actual: Option_.Option<unknown>, issues: readonly [SchemaIssue.Issue, ...Array<SchemaIssue.Issue>]): SchemaIssue.CompositeRepresents a schema issue that groups multiple child issues under a single schema node.
When to use
Use when you need to walk the issue tree for struct/tuple schemas that collect
all field errors rather than failing on the first.
Details
issues is a non-empty readonly array (at least one child).
actual is Option.some(value) when the input was present, or
Option.none() when absent.
- Formatters flatten
Composite by recursing into each child.
Composite(ast: SchemaAST.Declaration(parameter) ast: {
_tag: 'Declaration';
typeParameters: ReadonlyArray<AST>;
run: (typeParameters: ReadonlyArray<AST>) => (input: unknown, self: Declaration, options: ParseOptions) => Effect.Effect<any, SchemaIssue.Issue, any>;
encodingChecks: Checks | undefined;
getParser: () => SchemaParser.Parser;
_rebuild: (recur: (ast: AST) => AST, checks: Checks | undefined, encodingChecks: Checks | undefined) => Declaration;
recur: (recur: (ast: AST) => AST) => Declaration;
flip: (recur: (ast: AST) => AST) => Declaration;
getExpected: () => string;
annotations: Schema.Annotations.Annotations | undefined;
checks: Checks | undefined;
encoding: Encoding | undefined;
context: Context | undefined;
toString: () => string;
}
ast, import Option_Option_.const some: <A>(value: A) => Option<A>Wraps the given value into an Option to represent its presence.
When to use
Use to wrap a known present value as Option
- Returning a successful result from a partial function
Details
- Always returns
Some<A>
- Does not filter
null or undefined; use
fromNullishOr
for that
Example (Wrapping a value)
import { Option } from "effect"
// ┌─── Option<number>
// ▼
const value = Option.some(1)
console.log(value)
// Output: { _id: 'Option', _tag: 'Some', value: 1 }
some(input: Cause_.Fail<unknown>(parameter) input: {
error: E;
_tag: Tag;
annotations: ReadonlyMap<string, unknown>;
annotate: (annotations: Context.Context<never> | ReadonlyMap<string, unknown>, options?: { readonly overwrite?: boolean | undefined }) => Fail<unknown>;
toString: () => string;
toJSON: () => unknown;
}
input), [new import SchemaIssueSchemaIssue.constructor Pointer(path: ReadonlyArray<PropertyKey>, issue: SchemaIssue.Issue): SchemaIssue.PointerWraps an inner
Issue
with a property-key path, indicating where in
a nested structure the error occurred.
When to use
Use when you need to walk the issue tree to accumulate path segments for error
reporting.
Details
path is an array of property keys (strings, numbers, or symbols).
- Has no
actual value —
getActual
returns Option.none().
- Formatters concatenate nested
Pointer paths into a single path like
["a"]["b"][0].
Pointer(["error"], issue: SchemaIssue.Issueissue)])
}
)
case "Die":
return import EffectEffect.const mapBothEager: {
<E, E2, A, A2>(options: {
readonly onFailure: (e: E) => E2
readonly onSuccess: (a: A) => A2
}): <R>(
self: Effect<A, E, R>
) => Effect<A2, E2, R>
<A, E, R, E2, A2>(
self: Effect<A, E, R>,
options: {
readonly onFailure: (e: E) => E2
readonly onSuccess: (a: A) => A2
}
): Effect<A2, E2, R>
}
mapBothEager(
import SchemaParserSchemaParser.function decodeUnknownEffect<
S extends Schema.Constraint
>(
schema: S,
options?: SchemaAST.ParseOptions
): (
input: unknown,
options?: SchemaAST.ParseOptions
) => Effect.Effect<
S["Type"],
SchemaIssue.Issue,
S["DecodingServices"]
>
Creates an effectful decoder for unknown input.
When to use
Use when you need to decode untyped boundary input in an Effect whose
failure channel is SchemaIssue.Issue, while preserving transformations
and service requirements.
Details
The returned function succeeds with the schema's decoded Type or fails with a
SchemaIssue.Issue. Decoding service requirements are preserved in the returned
Effect. Parse options may be provided when creating the decoder and overridden
when applying it.
decodeUnknownEffect(defect: Codec<
D["Type"],
D["Encoded"],
never,
never
>
(parameter) defect: {
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
Rebuild: Codec<T, E, RD, RE>;
Type: T;
Iso: Iso;
ast: Ast;
annotate: (annotations: Annotations.Bottom<D['Type'], any>) => Codec<D['Type'], D['Encoded'], never, never>;
annotateKey: (annotations: Annotations.Key<D['Type']>) => Codec<D['Type'], D['Encoded'], never, never>;
check: (checks_0: SchemaAST.Check<D['Type']>, ...checks: Array<SchemaAST.Check<D['Type']>>) => Codec<D['Type'], D['Encoded'], never, never>;
rebuild: (ast: SchemaAST.AST) => Codec<D['Type'], D['Encoded'], never, never>;
make: (input: unknown, options?: MakeOptions) => D['Type'];
makeOption: (input: unknown, options?: MakeOptions) => Option_.Option<D['Type']>;
makeEffect: (input: unknown, options?: MakeOptions) => Effect.Effect<D['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; <…;
}
defect)(input: Cause_.Die(parameter) input: {
defect: unknown;
_tag: Tag;
annotations: ReadonlyMap<string, unknown>;
annotate: (annotations: Context.Context<never> | ReadonlyMap<string, unknown>, options?: { readonly overwrite?: boolean | undefined }) => Die;
toString: () => string;
toJSON: () => unknown;
}
input.Die.defect: unknowndefect, options: SchemaAST.ParseOptions(parameter) options: {
errors: "first" | "all" | undefined;
onExcessProperty: "ignore" | "error" | "preserve" | undefined;
propertyOrder: "none" | "original" | undefined;
disableChecks: boolean | undefined;
concurrency: number | "unbounded" | undefined;
}
options),
{
onSuccess: (defect: unknown) => DieonSuccess: import Cause_Cause_.const makeDieReason: (
defect: unknown
) => Die
Creates a standalone Die reason (not wrapped in a Cause).
When to use
Use when constructing a standalone defect reason for
fromReasons
or
direct comparison.
Example (Creating a Die reason)
import { Cause } from "effect"
const reason = Cause.makeDieReason("bug")
console.log(reason._tag) // "Die"
console.log(reason.defect) // "bug"
makeDieReason,
onFailure: (
e: SchemaIssue.Issue
) => SchemaIssue.Composite
onFailure: (issue: SchemaIssue.Issueissue) =>
new import SchemaIssueSchemaIssue.constructor Composite(ast: SchemaAST.AST, actual: Option_.Option<unknown>, issues: readonly [SchemaIssue.Issue, ...Array<SchemaIssue.Issue>]): SchemaIssue.CompositeRepresents a schema issue that groups multiple child issues under a single schema node.
When to use
Use when you need to walk the issue tree for struct/tuple schemas that collect
all field errors rather than failing on the first.
Details
issues is a non-empty readonly array (at least one child).
actual is Option.some(value) when the input was present, or
Option.none() when absent.
- Formatters flatten
Composite by recursing into each child.
Composite(ast: SchemaAST.Declaration(parameter) ast: {
_tag: 'Declaration';
typeParameters: ReadonlyArray<AST>;
run: (typeParameters: ReadonlyArray<AST>) => (input: unknown, self: Declaration, options: ParseOptions) => Effect.Effect<any, SchemaIssue.Issue, any>;
encodingChecks: Checks | undefined;
getParser: () => SchemaParser.Parser;
_rebuild: (recur: (ast: AST) => AST, checks: Checks | undefined, encodingChecks: Checks | undefined) => Declaration;
recur: (recur: (ast: AST) => AST) => Declaration;
flip: (recur: (ast: AST) => AST) => Declaration;
getExpected: () => string;
annotations: Schema.Annotations.Annotations | undefined;
checks: Checks | undefined;
encoding: Encoding | undefined;
context: Context | undefined;
toString: () => string;
}
ast, import Option_Option_.const some: <A>(value: A) => Option<A>Wraps the given value into an Option to represent its presence.
When to use
Use to wrap a known present value as Option
- Returning a successful result from a partial function
Details
- Always returns
Some<A>
- Does not filter
null or undefined; use
fromNullishOr
for that
Example (Wrapping a value)
import { Option } from "effect"
// ┌─── Option<number>
// ▼
const value = Option.some(1)
console.log(value)
// Output: { _id: 'Option', _tag: 'Some', value: 1 }
some(input: Cause_.Die(parameter) input: {
defect: unknown;
_tag: Tag;
annotations: ReadonlyMap<string, unknown>;
annotate: (annotations: Context.Context<never> | ReadonlyMap<string, unknown>, options?: { readonly overwrite?: boolean | undefined }) => Die;
toString: () => string;
toJSON: () => unknown;
}
input), [new import SchemaIssueSchemaIssue.constructor Pointer(path: ReadonlyArray<PropertyKey>, issue: SchemaIssue.Issue): SchemaIssue.PointerWraps an inner
Issue
with a property-key path, indicating where in
a nested structure the error occurred.
When to use
Use when you need to walk the issue tree to accumulate path segments for error
reporting.
Details
path is an array of property keys (strings, numbers, or symbols).
- Has no
actual value —
getActual
returns Option.none().
- Formatters concatenate nested
Pointer paths into a single path like
["a"]["b"][0].
Pointer(["defect"], issue: SchemaIssue.Issueissue)])
}
)
case "Interrupt":
return import EffectEffect.const succeed: <A>(value: A) => Effect<A>Creates an Effect that always succeeds with a given value.
When to use
Use when an effect should complete successfully with a specific value without any errors
or external dependencies.
Example (Creating a successful effect)
import { Effect } from "effect"
// Creating an effect that represents a successful scenario
//
// ┌─── Effect<number, never, never>
// ▼
const success = Effect.succeed(42)
succeed(input: Cause_.Interrupt(parameter) input: {
fiberId: number | undefined;
_tag: Tag;
annotations: ReadonlyMap<string, unknown>;
annotate: (annotations: Context.Context<never> | ReadonlyMap<string, unknown>, options?: { readonly overwrite?: boolean | undefined }) => Interrupt;
toString: () => string;
toJSON: () => unknown;
}
input)
}
},
{
Annotations.Declaration<Reason<E["Type"]>, readonly [E, D]>.typeConstructor?: {
readonly [key: string]: unknown;
readonly _tag: string;
} | undefined
typeConstructor: {
_tag: string_tag: "effect/Cause/Failure"
},
Annotations.Declaration<Reason<E["Type"]>, readonly [E, D]>.generation?: {
readonly runtime: string;
readonly Type: string;
readonly Encoded?: string | undefined;
readonly importDeclaration?: string | undefined;
} | undefined
generation: {
runtime: stringruntime: `Schema.CauseReason(?, ?)`,
type Type: stringType: `Cause.Failure<?, ?>`,
importDeclaration?: string | undefinedimportDeclaration: `import * as Cause from "effect/Cause"`
},
Annotations.Augment.expected?: string | undefinedHuman-readable description of what a value is expected to satisfy.
Details
For filter and refinement failures, the default formatter uses
message first, then expected, and finally falls back to <filter>.
Use this to name a failed filter in the default message:
Expected <expected>, got <actual>.
expected: "Cause.Failure",
Annotations.Declaration<Reason<E["Type"]>, readonly [E, D]>.toCodec?: ((typeParameters: readonly [Codec<E["Encoded"], E["Encoded"], never, never>, Codec<D["Encoded"], D["Encoded"], never, never>]) => SchemaAST.Link) | undefinedtoCodec: ([error: Codec<
E["Encoded"],
E["Encoded"],
never,
never
>
(parameter) error: {
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
Rebuild: Codec<T, E, RD, RE>;
Type: T;
Iso: Iso;
ast: Ast;
annotate: (annotations: Annotations.Bottom<E['Encoded'], any>) => Codec<E['Encoded'], E['Encoded'], never, never>;
annotateKey: (annotations: Annotations.Key<E['Encoded']>) => Codec<E['Encoded'], E['Encoded'], never, never>;
check: (checks_0: SchemaAST.Check<E['Encoded']>, ...checks: Array<SchemaAST.Check<E['Encoded']>>) => Codec<E['Encoded'], E['Encoded'], never, never>;
rebuild: (ast: SchemaAST.AST) => Codec<E['Encoded'], E['Encoded'], never, never>;
make: (input: unknown, options?: MakeOptions) => E['Encoded'];
makeOption: (input: unknown, options?: MakeOptions) => Option_.Option<E['Encoded']>;
makeEffect: (input: unknown, options?: MakeOptions) => Effect.Effect<E['Encoded'], 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; <…;
}
error, defect: Codec<
D["Encoded"],
D["Encoded"],
never,
never
>
(parameter) defect: {
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
Rebuild: Codec<T, E, RD, RE>;
Type: T;
Iso: Iso;
ast: Ast;
annotate: (annotations: Annotations.Bottom<D['Encoded'], any>) => Codec<D['Encoded'], D['Encoded'], never, never>;
annotateKey: (annotations: Annotations.Key<D['Encoded']>) => Codec<D['Encoded'], D['Encoded'], never, never>;
check: (checks_0: SchemaAST.Check<D['Encoded']>, ...checks: Array<SchemaAST.Check<D['Encoded']>>) => Codec<D['Encoded'], D['Encoded'], never, never>;
rebuild: (ast: SchemaAST.AST) => Codec<D['Encoded'], D['Encoded'], never, never>;
make: (input: unknown, options?: MakeOptions) => D['Encoded'];
makeOption: (input: unknown, options?: MakeOptions) => Option_.Option<D['Encoded']>;
makeEffect: (input: unknown, options?: MakeOptions) => Effect.Effect<D['Encoded'], 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; <…;
}
defect]) =>
function link<T>(): <
To extends Constraint
>(
encodeTo: To,
transformation: {
readonly decode: SchemaGetter.Getter<
T,
NoInfer<To["Type"]>
>
readonly encode: SchemaGetter.Getter<
NoInfer<To["Type"]>,
T
>
}
) => SchemaAST.Link
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.
link<import Cause_Cause_.type Reason<E> = Cause_.Fail<E> | Cause_.Die | Cause_.InterruptA single entry inside a Cause's reasons array.
Details
Narrow to a concrete type with
isFailReason
,
isDieReason
,
or
isInterruptReason
.
Fail<E> — typed error, access via .error
Die — untyped defect, access via .defect
Interrupt — fiber interruption, access via .fiberId
Every reason carries an annotations map and an annotate method for
attaching tracing metadata.
Example (Narrowing a reason)
import { Cause } from "effect"
const reason = Cause.fail("error").reasons[0]
if (Cause.isFailReason(reason)) {
console.log(reason.error) // "error"
}
Companion namespace for the Reason type.
Reason<function (type parameter) E in CauseReason<E extends Constraint, D extends Constraint>(error: E, defect: D): CauseReason<E, D>E["Encoded"]>>()(
function Union<
Members extends ReadonlyArray<Constraint>
>(
members: Members,
options?: { mode?: "anyOf" | "oneOf" }
): Union<Members>
Creates a union schema from an array of member schemas. Members are tested in
order; the first match is returned.
Details
Optionally, specify mode:
"anyOf" (default) — matches if any member matches.
"oneOf" — matches if exactly one member matches.
Example (Defining a string or number union)
import { Schema } from "effect"
const schema = Schema.Union([Schema.String, Schema.Number])
Schema.decodeUnknownSync(schema)("hello") // "hello"
Schema.decodeUnknownSync(schema)(42) // 42
Union([
function Struct<
Fields extends Struct.Fields
>(fields: Fields): 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 }
Struct({ _tag: Literal<"Fail">(property) _tag: {
literal: L;
transform: (to: L2) => decodeTo<Literal<L2>, Literal<'Fail'>, never, never>;
Rebuild: Rebuild;
Iso: Iso;
ast: Ast;
Type: T;
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
annotate: (annotations: Annotations.Bottom<'Fail', readonly []>) => Literal<'Fail'>;
annotateKey: (annotations: Annotations.Key<'Fail'>) => Literal<'Fail'>;
check: (checks_0: SchemaAST.Check<'Fail'>, ...checks: Array<SchemaAST.Check<'Fail'>>) => Literal<'Fail'>;
rebuild: (ast: SchemaAST.Literal) => Literal<'Fail'>;
make: (input: 'Fail', options?: MakeOptions) => 'Fail';
makeOption: (input: 'Fail', options?: MakeOptions) => Option_.Option<'Fail'>;
makeEffect: (input: 'Fail', options?: MakeOptions) => Effect.Effect<'Fail', 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; <…;
}
_tag: function Literal<
L extends SchemaAST.LiteralValue
>(literal: L): Literal<L>
Creates a schema for a single literal value (string, number, bigint, boolean, or null).
Example (Defining a string literal)
import { Schema } from "effect"
const schema = Schema.Literal("hello")
// Type: Schema.Literal<"hello">
Literal("Fail"), error: Codec<
E["Encoded"],
E["Encoded"],
never,
never
>
(property) error: {
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
Rebuild: Codec<T, E, RD, RE>;
Type: T;
Iso: Iso;
ast: Ast;
annotate: (annotations: Annotations.Bottom<E['Encoded'], any>) => Codec<E['Encoded'], E['Encoded'], never, never>;
annotateKey: (annotations: Annotations.Key<E['Encoded']>) => Codec<E['Encoded'], E['Encoded'], never, never>;
check: (checks_0: SchemaAST.Check<E['Encoded']>, ...checks: Array<SchemaAST.Check<E['Encoded']>>) => Codec<E['Encoded'], E['Encoded'], never, never>;
rebuild: (ast: SchemaAST.AST) => Codec<E['Encoded'], E['Encoded'], never, never>;
make: (input: unknown, options?: MakeOptions) => E['Encoded'];
makeOption: (input: unknown, options?: MakeOptions) => Option_.Option<E['Encoded']>;
makeEffect: (input: unknown, options?: MakeOptions) => Effect.Effect<E['Encoded'], 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; <…;
}
error }),
function Struct<
Fields extends Struct.Fields
>(fields: Fields): 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 }
Struct({ _tag: Literal<"Die">(property) _tag: {
literal: L;
transform: (to: L2) => decodeTo<Literal<L2>, Literal<'Die'>, never, never>;
Rebuild: Rebuild;
Iso: Iso;
ast: Ast;
Type: T;
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
annotate: (annotations: Annotations.Bottom<'Die', readonly []>) => Literal<'Die'>;
annotateKey: (annotations: Annotations.Key<'Die'>) => Literal<'Die'>;
check: (checks_0: SchemaAST.Check<'Die'>, ...checks: Array<SchemaAST.Check<'Die'>>) => Literal<'Die'>;
rebuild: (ast: SchemaAST.Literal) => Literal<'Die'>;
make: (input: 'Die', options?: MakeOptions) => 'Die';
makeOption: (input: 'Die', options?: MakeOptions) => Option_.Option<'Die'>;
makeEffect: (input: 'Die', options?: MakeOptions) => Effect.Effect<'Die', 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; <…;
}
_tag: function Literal<
L extends SchemaAST.LiteralValue
>(literal: L): Literal<L>
Creates a schema for a single literal value (string, number, bigint, boolean, or null).
Example (Defining a string literal)
import { Schema } from "effect"
const schema = Schema.Literal("hello")
// Type: Schema.Literal<"hello">
Literal("Die"), defect: Codec<
D["Encoded"],
D["Encoded"],
never,
never
>
(property) defect: {
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
Rebuild: Codec<T, E, RD, RE>;
Type: T;
Iso: Iso;
ast: Ast;
annotate: (annotations: Annotations.Bottom<D['Encoded'], any>) => Codec<D['Encoded'], D['Encoded'], never, never>;
annotateKey: (annotations: Annotations.Key<D['Encoded']>) => Codec<D['Encoded'], D['Encoded'], never, never>;
check: (checks_0: SchemaAST.Check<D['Encoded']>, ...checks: Array<SchemaAST.Check<D['Encoded']>>) => Codec<D['Encoded'], D['Encoded'], never, never>;
rebuild: (ast: SchemaAST.AST) => Codec<D['Encoded'], D['Encoded'], never, never>;
make: (input: unknown, options?: MakeOptions) => D['Encoded'];
makeOption: (input: unknown, options?: MakeOptions) => Option_.Option<D['Encoded']>;
makeEffect: (input: unknown, options?: MakeOptions) => Effect.Effect<D['Encoded'], 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; <…;
}
defect }),
function Struct<
Fields extends Struct.Fields
>(fields: Fields): 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 }
Struct({ _tag: Literal<"Interrupt">(property) _tag: {
literal: L;
transform: (to: L2) => decodeTo<Literal<L2>, Literal<'Interrupt'>, never, never>;
Rebuild: Rebuild;
Iso: Iso;
ast: Ast;
Type: T;
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
annotate: (annotations: Annotations.Bottom<'Interrupt', readonly []>) => Literal<'Interrupt'>;
annotateKey: (annotations: Annotations.Key<'Interrupt'>) => Literal<'Interrupt'>;
check: (checks_0: SchemaAST.Check<'Interrupt'>, ...checks: Array<SchemaAST.Check<'Interrupt'>>) => Literal<'Interrupt'>;
rebuild: (ast: SchemaAST.Literal) => Literal<'Interrupt'>;
make: (input: 'Interrupt', options?: MakeOptions) => 'Interrupt';
makeOption: (input: 'Interrupt', options?: MakeOptions) => Option_.Option<'Interrupt'>;
makeEffect: (input: 'Interrupt', options?: MakeOptions) => Effect.Effect<'Interrupt', 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; <…;
}
_tag: function Literal<
L extends SchemaAST.LiteralValue
>(literal: L): Literal<L>
Creates a schema for a single literal value (string, number, bigint, boolean, or null).
Example (Defining a string literal)
import { Schema } from "effect"
const schema = Schema.Literal("hello")
// Type: Schema.Literal<"hello">
Literal("Interrupt"), fiberId: UndefinedOr<Finite>(property) fiberId: {
Rebuild: UndefinedOr<S>;
Type: { [K in keyof Members]: Members[K]["Type"]; }[number];
Encoded: { [K in keyof Members]: Members[K]["Encoded"]; }[number];
DecodingServices: { [K in keyof Members]: Members[K]["DecodingServices"]; }[number];
EncodingServices: { [K in keyof Members]: Members[K]["EncodingServices"]; }[number];
Iso: { [K in keyof Members]: Members[K]["Iso"]; }[number];
members: Members;
mapMembers: (f: (members: readonly [Finite, Undefined]) => To, options?: { readonly unsafePreserveChecks?: boolean | undefined } | undefined) => Union<{ [K in keyof Readonly<To>]: Readonly<To>[K]; }>;
ast: Ast;
annotate: (annotations: Annotations.Bottom<number | undefined, readonly []>) => UndefinedOr<Finite>;
annotateKey: (annotations: Annotations.Key<number | undefined>) => UndefinedOr<Finite>;
check: (checks_0: SchemaAST.Check<number | undefined>, ...checks: Array<SchemaAST.Check<number | undefined>>) => UndefinedOr<Finite>;
rebuild: (ast: SchemaAST.Union<SchemaAST.Undefined | SchemaAST.Number>) => UndefinedOr<Finite>;
make: (input: number | undefined, options?: MakeOptions) => number | undefined;
makeOption: (input: number | undefined, options?: MakeOptions) => Option_.Option<number | undefined>;
makeEffect: (input: number | undefined, options?: MakeOptions) => Effect.Effect<number | undefined, 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; <…;
}
fiberId: const UndefinedOr: UndefinedOrLambda
;<Finite>(self: Finite) => UndefinedOr<Finite>
Type-level representation returned by
UndefinedOr
.
Creates a union schema of S | undefined.
UndefinedOr(const Finite: Finiteconst Finite: {
Rebuild: Finite;
Iso: Iso;
ast: Ast;
Type: T;
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
annotate: (annotations: Annotations.Bottom<number, readonly []>) => Finite;
annotateKey: (annotations: Annotations.Key<number>) => Finite;
check: (checks_0: SchemaAST.Check<number>, ...checks: Array<SchemaAST.Check<number>>) => Finite;
rebuild: (ast: SchemaAST.Number) => Finite;
make: (input: number, options?: MakeOptions) => number;
makeOption: (input: number, options?: MakeOptions) => Option_.Option<number>;
makeEffect: (input: number, options?: MakeOptions) => Effect.Effect<number, SchemaError, never>;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
}
Type-level representation of
Finite
.
Schema for finite numbers, rejecting NaN, Infinity, and -Infinity.
Finite) })
]),
import SchemaTransformationSchemaTransformation.function transform<T, E>(options: {
readonly decode: (input: E) => T
readonly encode: (input: T) => E
}): Transformation<T, E>
Creates a Transformation from pure (sync, infallible) decode and encode
functions.
When to use
Use when you need an infallible schema transformation that does not require
Effect services.
Details
- Each function receives the input and returns the output directly.
- Skips
None inputs (missing keys) — functions are only called on present values.
- Does not allocate Effects internally; uses optimized sync path.
Example (Converting between cents and dollars)
import { Schema, SchemaTransformation } from "effect"
const CentsFromDollars = Schema.Number.pipe(
Schema.decodeTo(
Schema.Number,
SchemaTransformation.transform({
decode: (dollars) => dollars * 100,
encode: (cents) => cents / 100
})
)
)
transform({
decode: (input: NoInfer<Struct.ReadonlySide<{
readonly _tag: Literal<"Fail">;
readonly error: Codec<E["Encoded"], E["Encoded"], never, never>;
}, "Type"> | Struct.ReadonlySide<{
readonly _tag: Literal<"Die">;
readonly defect: Codec<D["Encoded"], D["Encoded"], never, never>;
}, "Type"> | Struct.ReadonlySide<{
readonly _tag: Literal<"Interrupt">;
readonly fiberId: UndefinedOr<Finite>;
}, "Type">>) => Cause_.Die | Cause_.Interrupt | Cause_.Fail<...>
decode: (e: NoInfer<
| Struct.ReadonlySide<
{
readonly _tag: Literal<"Fail">
readonly error: Codec<
E["Encoded"],
E["Encoded"],
never,
never
>
},
"Type"
>
| Struct.ReadonlySide<
{
readonly _tag: Literal<"Die">
readonly defect: Codec<
D["Encoded"],
D["Encoded"],
never,
never
>
},
"Type"
>
| Struct.ReadonlySide<
{
readonly _tag: Literal<"Interrupt">
readonly fiberId: UndefinedOr<Finite>
},
"Type"
>
>
e) => {
switch (e: | Struct.ReadonlySide<
{
readonly _tag: Literal<"Fail">
readonly error: Codec<
E["Encoded"],
E["Encoded"],
never,
never
>
},
"Type"
>
| Struct.ReadonlySide<
{
readonly _tag: Literal<"Die">
readonly defect: Codec<
D["Encoded"],
D["Encoded"],
never,
never
>
},
"Type"
>
| Struct.ReadonlySide<
{
readonly _tag: Literal<"Interrupt">
readonly fiberId: UndefinedOr<Finite>
},
"Type"
>
e._tag: "Fail" | "Die" | "Interrupt"_tag) {
case "Fail":
return import Cause_Cause_.const makeFailReason: <E>(
error: E
) => Fail<E>
Creates a standalone Fail reason (not wrapped in a Cause).
When to use
Use when constructing a standalone typed failure reason for
fromReasons
or direct comparison.
Example (Creating a Fail reason)
import { Cause } from "effect"
const reason = Cause.makeFailReason("error")
console.log(reason._tag) // "Fail"
console.log(reason.error) // "error"
makeFailReason(e: Struct.ReadonlySide<
{
readonly _tag: Literal<"Fail">
readonly error: Codec<
E["Encoded"],
E["Encoded"],
never,
never
>
},
"Type"
>
(parameter) e: {
_tag: 'Fail';
error: E['Encoded'];
}
e.error: E["Encoded"]error)
case "Die":
return import Cause_Cause_.const makeDieReason: (
defect: unknown
) => Die
Creates a standalone Die reason (not wrapped in a Cause).
When to use
Use when constructing a standalone defect reason for
fromReasons
or
direct comparison.
Example (Creating a Die reason)
import { Cause } from "effect"
const reason = Cause.makeDieReason("bug")
console.log(reason._tag) // "Die"
console.log(reason.defect) // "bug"
makeDieReason(e: Struct.ReadonlySide<
{
readonly _tag: Literal<"Die">
readonly defect: Codec<
D["Encoded"],
D["Encoded"],
never,
never
>
},
"Type"
>
(parameter) e: {
_tag: 'Die';
defect: D['Encoded'];
}
e.defect: D["Encoded"]defect)
case "Interrupt":
return import Cause_Cause_.const makeInterruptReason: (
fiberId?: number | undefined
) => Interrupt
Creates a standalone Interrupt reason (not wrapped in a Cause),
optionally carrying the interrupting fiber's ID.
When to use
Use when constructing a standalone interrupt reason for
fromReasons
or direct comparison.
Example (Creating an Interrupt reason)
import { Cause } from "effect"
const reason = Cause.makeInterruptReason(42)
console.log(reason._tag) // "Interrupt"
console.log(reason.fiberId) // 42
makeInterruptReason(e: Struct.ReadonlySide<
{
readonly _tag: Literal<"Interrupt">
readonly fiberId: UndefinedOr<Finite>
},
"Type"
>
(parameter) e: {
_tag: 'Interrupt';
fiberId: number | undefined;
}
e.fiberId: number | undefinedfiberId)
}
},
encode: (
input:
| Cause_.Die
| Cause_.Interrupt
| Cause_.Fail<E["Encoded"]>
) => NoInfer<
| Struct.ReadonlySide<
{
readonly _tag: Literal<"Fail">
readonly error: Codec<
E["Encoded"],
E["Encoded"],
never,
never
>
},
"Type"
>
| Struct.ReadonlySide<
{
readonly _tag: Literal<"Die">
readonly defect: Codec<
D["Encoded"],
D["Encoded"],
never,
never
>
},
"Type"
>
| Struct.ReadonlySide<
{
readonly _tag: Literal<"Interrupt">
readonly fiberId: UndefinedOr<Finite>
},
"Type"
>
>
encode: const identity: <A>(a: A) => AReturns its input argument unchanged.
When to use
Use to return a value unchanged where a function is required.
Example (Returning the same value)
import { identity } from "effect"
import * as assert from "node:assert"
assert.deepStrictEqual(identity(5), 5)
identity
})
),
Annotations.Declaration<Reason<E["Type"]>, readonly [E, D]>.toArbitrary?: Annotations.ToArbitrary.Declaration<Cause_.Reason<E["Type"]>, readonly [E, D]> | undefinedtoArbitrary: ([error: Annotations.ToArbitrary.TypeParameter<
E["Type"]
>
(parameter) error: {
arbitrary: FastCheck.Arbitrary<T>;
terminal: FastCheck.Arbitrary<T> | undefined;
}
error, defect: Annotations.ToArbitrary.TypeParameter<
D["Type"]
>
(parameter) defect: {
arbitrary: FastCheck.Arbitrary<T>;
terminal: FastCheck.Arbitrary<T> | undefined;
}
defect]) => function causeReasonToArbitrary<E["Type"], D["Type"]>(error: Annotations.ToArbitrary.TypeParameter<E["Type"]>, defect: Annotations.ToArbitrary.TypeParameter<D["Type"]>): (fc: typeof FastCheck, ctx: Annotations.ToArbitrary.Context) => {
arbitrary: any;
terminal: any;
}
causeReasonToArbitrary(error: Annotations.ToArbitrary.TypeParameter<
E["Type"]
>
(parameter) error: {
arbitrary: FastCheck.Arbitrary<T>;
terminal: FastCheck.Arbitrary<T> | undefined;
}
error, defect: Annotations.ToArbitrary.TypeParameter<
D["Type"]
>
(parameter) defect: {
arbitrary: FastCheck.Arbitrary<T>;
terminal: FastCheck.Arbitrary<T> | undefined;
}
defect),
Annotations.Declaration<Reason<E["Type"]>, readonly [E, D]>.toEquivalence?: Annotations.ToEquivalence.Declaration<Cause_.Reason<E["Type"]>, readonly [E, D]> | undefinedtoEquivalence: ([error: Equivalence.Equivalence<E["Type"]>error, defect: Equivalence.Equivalence<D["Type"]>defect]) => function causeReasonToEquivalence<E>(
error: Equivalence.Equivalence<E>,
defect: Equivalence.Equivalence<unknown>
): (
a: Cause_.Reason<E>,
b: Cause_.Reason<E>
) => boolean
causeReasonToEquivalence(error: Equivalence.Equivalence<E["Type"]>error, defect: Equivalence.Equivalence<D["Type"]>defect),
Annotations.Declaration<Reason<E["Type"]>, readonly [E, D]>.toFormatter?: Annotations.ToFormatter.Declaration<Cause_.Reason<E["Type"]>, readonly [E, D]> | undefinedtoFormatter: ([error: Formatter<E["Type"], string>error, defect: Formatter<D["Type"], string>defect]) => function causeReasonToFormatter<E>(
error: Formatter<E>,
defect: Formatter<unknown>
): (t: Cause_.Reason<E>) => string
causeReasonToFormatter(error: Formatter<E["Type"], string>error, defect: Formatter<D["Type"], string>defect)
}
)
return const make: <S extends Constraint>(
ast: S["ast"],
options?: object
) => S
Creates a schema from an AST (Abstract Syntax Tree) node.
Details
This is the fundamental constructor for all schemas in the Effect Schema
library. It takes an AST node and wraps it in a fully-typed schema that
preserves all type information and provides the complete schema API.
The make function is used internally to create all primitive schemas like
String, Number, Boolean, etc., as well as more complex schemas. It's
the bridge between the untyped AST representation and the strongly-typed
schema.
make(const schema: declareConstructor<
Cause_.Reason<E["Type"]>,
Cause_.Reason<E["Encoded"]>,
readonly [E, D],
CauseReasonIso<E, D>
>
const schema: {
Rebuild: Rebuild;
Iso: Iso;
ast: Ast;
Type: T;
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
annotate: (annotations: Annotations.Bottom<Cause_.Reason<E['Type']>, readonly [E, D]>) => declareConstructor<Cause_.Reason<E['Type']>, Cause_.Reason<E['Encoded']>, readonly [E, D], CauseReasonIso<E, D>>;
annotateKey: (annotations: Annotations.Key<Cause_.Reason<E['Type']>>) => declareConstructor<Cause_.Reason<E['Type']>, Cause_.Reason<E['Encoded']>, readonly [E, D], CauseReasonIso<E, D>>;
check: (checks_0: SchemaAST.Check<Cause_.Reason<E['Type']>>, ...checks: Array<SchemaAST.Check<Cause_.Reason<E['Type']>>>) => declareConstructor<Cause_.Reason<E['Type']>, Cause_.Reason<E['Encoded']>, readonly [E, D], CauseReasonIso<E, D>>;
rebuild: (ast: SchemaAST.Declaration) => declareConstructor<Cause_.Reason<E['Type']>, Cause_.Reason<E['Encoded']>, readonly [E, D], CauseReasonIso<E, D>>;
make: (input: Cause_.Reason<E['Type']>, options?: MakeOptions) => Cause_.Reason<E['Type']>;
makeOption: (input: Cause_.Reason<E['Type']>, options?: MakeOptions) => Option_.Option<Cause_.Reason<E['Type']>>;
makeEffect: (input: Cause_.Reason<E['Type']>, options?: MakeOptions) => Effect.Effect<Cause_.Reason<E['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; <…;
}
schema.Bottom<Reason<E["Type"]>, Reason<E["Encoded"]>, (E | D)["DecodingServices"], (E | D)["EncodingServices"], Declaration, ... 9 more ..., "required">["ast"]: SchemaAST.Declaration(property) Bottom<Reason<E["Type"]>, Reason<E["Encoded"]>, (E | D)["DecodingServices"], (E | D)["EncodingServices"], Declaration, ... 9 more ..., "required">["ast"]: {
_tag: 'Declaration';
typeParameters: ReadonlyArray<AST>;
run: (typeParameters: ReadonlyArray<AST>) => (input: unknown, self: Declaration, options: ParseOptions) => Effect.Effect<any, SchemaIssue.Issue, any>;
encodingChecks: Checks | undefined;
getParser: () => SchemaParser.Parser;
_rebuild: (recur: (ast: AST) => AST, checks: Checks | undefined, encodingChecks: Checks | undefined) => Declaration;
recur: (recur: (ast: AST) => AST) => Declaration;
flip: (recur: (ast: AST) => AST) => Declaration;
getExpected: () => string;
annotations: Schema.Annotations.Annotations | undefined;
checks: Checks | undefined;
encoding: Encoding | undefined;
context: Context | undefined;
toString: () => string;
}
ast, { error: E extends Constrainterror, defect: D extends Constraintdefect })
}