<T, E, RD = never, RE = never>(options: {
readonly decode: (
e: E,
options: SchemaAST.ParseOptions
) => Effect.Effect<T, SchemaIssue.Issue, RD>
readonly encode: (
t: T,
options: SchemaAST.ParseOptions
) => Effect.Effect<E, SchemaIssue.Issue, RE>
}): Transformation<T, E, RD, RE>Creates a Transformation from effectful decode and encode functions that
can fail with Issue.
When to use
Use when you need a schema transformation that may fail or require Effect services.
Details
- Each function receives the input value and
ParseOptions. - Must return an
Effectthat succeeds with the output or fails withIssue. - Skips
Noneinputs (missing keys) — functions are only called on present values.
Example (Parsing a date string that can fail)
import { Effect, Option, Schema, SchemaIssue, SchemaTransformation } from "effect"
const DateFromString = Schema.String.pipe(
Schema.decodeTo(
Schema.Date,
SchemaTransformation.transformOrFail({
decode: (s) => {
const d = new Date(s)
return isNaN(d.getTime())
? Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), { message: "Invalid date" }))
: Effect.succeed(d)
},
encode: (d) => Effect.succeed(d.toISOString())
})
)
)export function function transformOrFail<
T,
E,
RD = never,
RE = never
>(options: {
readonly decode: (
e: E,
options: SchemaAST.ParseOptions
) => Effect.Effect<T, SchemaIssue.Issue, RD>
readonly encode: (
t: T,
options: SchemaAST.ParseOptions
) => Effect.Effect<E, SchemaIssue.Issue, RE>
}): Transformation<T, E, RD, RE>
Creates a Transformation from effectful decode and encode functions that
can fail with Issue.
When to use
Use when you need a schema transformation that may fail or require Effect
services.
Details
- Each function receives the input value and
ParseOptions.
- Must return an
Effect that succeeds with the output or fails with Issue.
- Skips
None inputs (missing keys) — functions are only called on present values.
Example (Parsing a date string that can fail)
import { Effect, Option, Schema, SchemaIssue, SchemaTransformation } from "effect"
const DateFromString = Schema.String.pipe(
Schema.decodeTo(
Schema.Date,
SchemaTransformation.transformOrFail({
decode: (s) => {
const d = new Date(s)
return isNaN(d.getTime())
? Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), { message: "Invalid date" }))
: Effect.succeed(d)
},
encode: (d) => Effect.succeed(d.toISOString())
})
)
)
transformOrFail<function (type parameter) T in transformOrFail<T, E, RD = never, RE = never>(options: {
readonly decode: (e: E, options: SchemaAST.ParseOptions) => Effect.Effect<T, SchemaIssue.Issue, RD>;
readonly encode: (t: T, options: SchemaAST.ParseOptions) => Effect.Effect<E, SchemaIssue.Issue, RE>;
}): Transformation<T, E, RD, RE>
function (type parameter) E in transformOrFail<T, E, RD = never, RE = never>(options: {
readonly decode: (e: E, options: SchemaAST.ParseOptions) => Effect.Effect<T, SchemaIssue.Issue, RD>;
readonly encode: (t: T, options: SchemaAST.ParseOptions) => Effect.Effect<E, SchemaIssue.Issue, RE>;
}): Transformation<T, E, RD, RE>
function (type parameter) RD in transformOrFail<T, E, RD = never, RE = never>(options: {
readonly decode: (e: E, options: SchemaAST.ParseOptions) => Effect.Effect<T, SchemaIssue.Issue, RD>;
readonly encode: (t: T, options: SchemaAST.ParseOptions) => Effect.Effect<E, SchemaIssue.Issue, RE>;
}): Transformation<T, E, RD, RE>
function (type parameter) RE in transformOrFail<T, E, RD = never, RE = never>(options: {
readonly decode: (e: E, options: SchemaAST.ParseOptions) => Effect.Effect<T, SchemaIssue.Issue, RD>;
readonly encode: (t: T, options: SchemaAST.ParseOptions) => Effect.Effect<E, SchemaIssue.Issue, RE>;
}): Transformation<T, E, RD, RE>
options: {
readonly decode: (
e: E,
options: SchemaAST.ParseOptions
) => Effect.Effect<T, SchemaIssue.Issue, RD>
readonly encode: (
t: T,
options: SchemaAST.ParseOptions
) => Effect.Effect<E, SchemaIssue.Issue, RE>
}
decode: (
e: E,
options: SchemaAST.ParseOptions
) => Effect.Effect<T, SchemaIssue.Issue, RD>
e: Ee: function (type parameter) E in transformOrFail<T, E, RD = never, RE = never>(options: {
readonly decode: (e: E, options: SchemaAST.ParseOptions) => Effect.Effect<T, SchemaIssue.Issue, RD>;
readonly encode: (t: T, options: SchemaAST.ParseOptions) => Effect.Effect<E, SchemaIssue.Issue, RE>;
}): Transformation<T, E, RD, RE>
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;
}
import SchemaASTSchemaAST.ParseOptions) => import EffectEffect.interface Effect<out A, out E = never, out R = never>The Effect interface defines a value that lazily describes a workflow or
job. The workflow requires some context R, and may fail with an error of
type E, or succeed with a value of type A.
When to use
Use when you need to represent a lazy, composable workflow that can require
services, fail with a typed error, or succeed with a typed value.
Details
Effect values model resourceful interaction with the outside world,
including synchronous, asynchronous, concurrent, and parallel interaction.
They use a fiber-based concurrency model, with built-in support for
scheduling, fine-grained interruption, structured concurrency, and high
scalability.
To run an Effect value, you need a Runtime, which is a type that is
capable of executing Effect values.
Effect<function (type parameter) T in transformOrFail<T, E, RD = never, RE = never>(options: {
readonly decode: (e: E, options: SchemaAST.ParseOptions) => Effect.Effect<T, SchemaIssue.Issue, RD>;
readonly encode: (t: T, options: SchemaAST.ParseOptions) => Effect.Effect<E, SchemaIssue.Issue, RE>;
}): Transformation<T, E, RD, RE>
import SchemaIssueSchemaIssue.type Issue =
| SchemaIssue.Leaf
| SchemaIssue.Filter
| SchemaIssue.Encoding
| SchemaIssue.Pointer
| SchemaIssue.Composite
| SchemaIssue.AnyOf
The root discriminated union of all validation error nodes.
When to use
Use when typing the error channel in Effect<A, Issue, R> results from
schema parsing, or when writing custom formatters or issue-tree walkers.
Details
Every node has a _tag field for pattern-matching. The union includes both
terminal
Leaf
types and composite types that wrap inner issues:
Filter
,
Encoding
,
Pointer
,
Composite
,
AnyOf
. All Issue instances have a toString() that delegates to
the default formatter, so String(issue) produces a human-readable message.
Issue, function (type parameter) RD in transformOrFail<T, E, RD = never, RE = never>(options: {
readonly decode: (e: E, options: SchemaAST.ParseOptions) => Effect.Effect<T, SchemaIssue.Issue, RD>;
readonly encode: (t: T, options: SchemaAST.ParseOptions) => Effect.Effect<E, SchemaIssue.Issue, RE>;
}): Transformation<T, E, RD, RE>
encode: (
t: T,
options: SchemaAST.ParseOptions
) => Effect.Effect<E, SchemaIssue.Issue, RE>
t: Tt: function (type parameter) T in transformOrFail<T, E, RD = never, RE = never>(options: {
readonly decode: (e: E, options: SchemaAST.ParseOptions) => Effect.Effect<T, SchemaIssue.Issue, RD>;
readonly encode: (t: T, options: SchemaAST.ParseOptions) => Effect.Effect<E, SchemaIssue.Issue, RE>;
}): Transformation<T, E, RD, RE>
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;
}
import SchemaASTSchemaAST.ParseOptions) => import EffectEffect.interface Effect<out A, out E = never, out R = never>The Effect interface defines a value that lazily describes a workflow or
job. The workflow requires some context R, and may fail with an error of
type E, or succeed with a value of type A.
When to use
Use when you need to represent a lazy, composable workflow that can require
services, fail with a typed error, or succeed with a typed value.
Details
Effect values model resourceful interaction with the outside world,
including synchronous, asynchronous, concurrent, and parallel interaction.
They use a fiber-based concurrency model, with built-in support for
scheduling, fine-grained interruption, structured concurrency, and high
scalability.
To run an Effect value, you need a Runtime, which is a type that is
capable of executing Effect values.
Effect<function (type parameter) E in transformOrFail<T, E, RD = never, RE = never>(options: {
readonly decode: (e: E, options: SchemaAST.ParseOptions) => Effect.Effect<T, SchemaIssue.Issue, RD>;
readonly encode: (t: T, options: SchemaAST.ParseOptions) => Effect.Effect<E, SchemaIssue.Issue, RE>;
}): Transformation<T, E, RD, RE>
import SchemaIssueSchemaIssue.type Issue =
| SchemaIssue.Leaf
| SchemaIssue.Filter
| SchemaIssue.Encoding
| SchemaIssue.Pointer
| SchemaIssue.Composite
| SchemaIssue.AnyOf
The root discriminated union of all validation error nodes.
When to use
Use when typing the error channel in Effect<A, Issue, R> results from
schema parsing, or when writing custom formatters or issue-tree walkers.
Details
Every node has a _tag field for pattern-matching. The union includes both
terminal
Leaf
types and composite types that wrap inner issues:
Filter
,
Encoding
,
Pointer
,
Composite
,
AnyOf
. All Issue instances have a toString() that delegates to
the default formatter, so String(issue) produces a human-readable message.
Issue, function (type parameter) RE in transformOrFail<T, E, RD = never, RE = never>(options: {
readonly decode: (e: E, options: SchemaAST.ParseOptions) => Effect.Effect<T, SchemaIssue.Issue, RD>;
readonly encode: (t: T, options: SchemaAST.ParseOptions) => Effect.Effect<E, SchemaIssue.Issue, RE>;
}): Transformation<T, E, RD, RE>
class Transformation<in out T, in out E, RD = never, RE = never>class Transformation {
_tag: 'Transformation';
decode: SchemaGetter.Getter<T, E, RD>;
encode: SchemaGetter.Getter<E, T, RE>;
flip: () => Transformation<E, T, RE, RD>;
compose: <T2, RD2, RE2>(other: Transformation<T2, T, RD2, RE2>) => Transformation<T2, E, RD | RD2, RE | RE2>;
}
Represents a bidirectional transformation between a decoded type T and an encoded
type E, built from a pair of Getters.
When to use
Use when you need a schema transformation that defines how a schema converts
between two representations.
- You want to compose multiple transformations into a pipeline.
- You want to flip a transformation to swap decode/encode.
Details
This is the primary building block for Schema.decodeTo, Schema.encodeTo,
Schema.decode, Schema.encode, and Schema.link. Each direction is a
SchemaGetter.Getter that handles optionality, failure, and Effect services.
- Immutable —
flip() and compose() return new instances.
flip() swaps the decode and encode getters.compose(other) chains: this.decode then other.decode for decoding,
other.encode then this.encode for encoding.
Example (Composing two transformations)
import { SchemaTransformation } from "effect"
const trimAndLower = SchemaTransformation.trim().compose(
SchemaTransformation.toLowerCase()
)
// decode: trim then lowercase
// encode: passthrough (both directions)
Transformation<function (type parameter) T in transformOrFail<T, E, RD = never, RE = never>(options: {
readonly decode: (e: E, options: SchemaAST.ParseOptions) => Effect.Effect<T, SchemaIssue.Issue, RD>;
readonly encode: (t: T, options: SchemaAST.ParseOptions) => Effect.Effect<E, SchemaIssue.Issue, RE>;
}): Transformation<T, E, RD, RE>
function (type parameter) E in transformOrFail<T, E, RD = never, RE = never>(options: {
readonly decode: (e: E, options: SchemaAST.ParseOptions) => Effect.Effect<T, SchemaIssue.Issue, RD>;
readonly encode: (t: T, options: SchemaAST.ParseOptions) => Effect.Effect<E, SchemaIssue.Issue, RE>;
}): Transformation<T, E, RD, RE>
function (type parameter) RD in transformOrFail<T, E, RD = never, RE = never>(options: {
readonly decode: (e: E, options: SchemaAST.ParseOptions) => Effect.Effect<T, SchemaIssue.Issue, RD>;
readonly encode: (t: T, options: SchemaAST.ParseOptions) => Effect.Effect<E, SchemaIssue.Issue, RE>;
}): Transformation<T, E, RD, RE>
function (type parameter) RE in transformOrFail<T, E, RD = never, RE = never>(options: {
readonly decode: (e: E, options: SchemaAST.ParseOptions) => Effect.Effect<T, SchemaIssue.Issue, RD>;
readonly encode: (t: T, options: SchemaAST.ParseOptions) => Effect.Effect<E, SchemaIssue.Issue, RE>;
}): Transformation<T, E, RD, RE>
constructor Transformation<T, E, RD, RE>(decode: SchemaGetter.Getter<T, E, RD>, encode: SchemaGetter.Getter<E, T, RE>): Transformation<T, E, RD, RE>Represents a bidirectional transformation between a decoded type T and an encoded
type E, built from a pair of Getters.
When to use
Use when you need a schema transformation that defines how a schema converts
between two representations.
- You want to compose multiple transformations into a pipeline.
- You want to flip a transformation to swap decode/encode.
Details
This is the primary building block for Schema.decodeTo, Schema.encodeTo,
Schema.decode, Schema.encode, and Schema.link. Each direction is a
SchemaGetter.Getter that handles optionality, failure, and Effect services.
- Immutable —
flip() and compose() return new instances.
flip() swaps the decode and encode getters.compose(other) chains: this.decode then other.decode for decoding,
other.encode then this.encode for encoding.
Example (Composing two transformations)
import { SchemaTransformation } from "effect"
const trimAndLower = SchemaTransformation.trim().compose(
SchemaTransformation.toLowerCase()
)
// decode: trim then lowercase
// encode: passthrough (both directions)
Transformation(
import SchemaGetterSchemaGetter.function transformOrFail<T, E, R = never>(
f: (
e: E,
options: SchemaAST.ParseOptions
) => Effect.Effect<T, SchemaIssue.Issue, R>
): Getter<T, E, R>
Creates a getter that applies a fallible, effectful transformation to present values.
When to use
Use when you need a schema getter for a transformation that may fail, require
Effect services, or run asynchronously.
Details
- Skips
None inputs — only called when a value is present.
- On success, wraps the result in
Some.
- On failure, propagates the
Issue.
Example (Parsing with failure)
import { Effect, Option, SchemaGetter, SchemaIssue } from "effect"
const safeParseInt = SchemaGetter.transformOrFail<number, string>(
(s) => {
const n = parseInt(s, 10)
return isNaN(n)
? Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), { message: "not an integer" }))
: Effect.succeed(n)
}
)
transformOrFail(options: {
readonly decode: (
e: E,
options: SchemaAST.ParseOptions
) => Effect.Effect<T, SchemaIssue.Issue, RD>
readonly encode: (
t: T,
options: SchemaAST.ParseOptions
) => Effect.Effect<E, SchemaIssue.Issue, RE>
}
decode: (
e: E,
options: SchemaAST.ParseOptions
) => Effect.Effect<T, SchemaIssue.Issue, RD>
import SchemaGetterSchemaGetter.function transformOrFail<T, E, R = never>(
f: (
e: E,
options: SchemaAST.ParseOptions
) => Effect.Effect<T, SchemaIssue.Issue, R>
): Getter<T, E, R>
Creates a getter that applies a fallible, effectful transformation to present values.
When to use
Use when you need a schema getter for a transformation that may fail, require
Effect services, or run asynchronously.
Details
- Skips
None inputs — only called when a value is present.
- On success, wraps the result in
Some.
- On failure, propagates the
Issue.
Example (Parsing with failure)
import { Effect, Option, SchemaGetter, SchemaIssue } from "effect"
const safeParseInt = SchemaGetter.transformOrFail<number, string>(
(s) => {
const n = parseInt(s, 10)
return isNaN(n)
? Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), { message: "not an integer" }))
: Effect.succeed(n)
}
)
transformOrFail(options: {
readonly decode: (
e: E,
options: SchemaAST.ParseOptions
) => Effect.Effect<T, SchemaIssue.Issue, RD>
readonly encode: (
t: T,
options: SchemaAST.ParseOptions
) => Effect.Effect<E, SchemaIssue.Issue, RE>
}
encode: (
t: T,
options: SchemaAST.ParseOptions
) => Effect.Effect<E, SchemaIssue.Issue, RE>