<T>(): Transformation<Option.Option<T>, T | undefined>Decodes T | undefined into Option<T> and encodes Option.none() back to
undefined.
When to use
Use when you need a schema transformation to convert API fields that use
undefined for absence to Option.
Details
Decoding maps undefined to Option.none() and non-undefined values to
Option.some(value). Encoding maps Option.none() to undefined and
Option.some(value) to value. The transformation is pure and synchronous.
Example (Converting undefined-or values to an Option)
import { Schema, SchemaTransformation } from "effect"
const schema = Schema.UndefinedOr(Schema.String).pipe(
Schema.decodeTo(
Schema.Option(Schema.String),
SchemaTransformation.optionFromUndefinedOr()
)
)export function function optionFromUndefinedOr<
T
>(): Transformation<
Option.Option<T>,
T | undefined
>
Decodes T | undefined into Option<T> and encodes Option.none() back to
undefined.
When to use
Use when you need a schema transformation to convert API fields that use
undefined for absence to Option.
Details
Decoding maps undefined to Option.none() and non-undefined values to
Option.some(value). Encoding maps Option.none() to undefined and
Option.some(value) to value. The transformation is pure and synchronous.
Example (Converting undefined-or values to an Option)
import { Schema, SchemaTransformation } from "effect"
const schema = Schema.UndefinedOr(Schema.String).pipe(
Schema.decodeTo(
Schema.Option(Schema.String),
SchemaTransformation.optionFromUndefinedOr()
)
)
optionFromUndefinedOr<function (type parameter) T in optionFromUndefinedOr<T>(): Transformation<Option.Option<T>, T | undefined>T>(): 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<import OptionOption.type Option<A> = Option.None<A> | Option.Some<A>The Option data type represents optional values. An Option<A> is either
Some<A>, containing a value of type A, or None, representing absence.
When to use
Use to represent initial values that may not yet exist
- Returning from partial functions (not defined for all inputs)
- Managing optional fields in data structures
Namespace containing utility types for Option.
When to use
Use to access type-level helpers associated with Option.
Option<function (type parameter) T in optionFromUndefinedOr<T>(): Transformation<Option.Option<T>, T | undefined>T>, function (type parameter) T in optionFromUndefinedOr<T>(): Transformation<Option.Option<T>, T | undefined>T | undefined> {
return 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: <A>(
a: A
) => Option<Exclude<A, undefined>>
import OptionOption.const fromUndefinedOr: <A>(
a: A
) => Option<Exclude<A, undefined>>
Converts a possibly undefined value into an Option, leaving null
as a valid Some.
When to use
Use when you want to treat only undefined as absent while preserving null
as a meaningful value.
Details
undefined → None- Any other value (including
null) → Some
Example (Converting possibly undefined values to an Option)
import { Option } from "effect"
console.log(Option.fromUndefinedOr(undefined))
// Output: { _id: 'Option', _tag: 'None' }
console.log(Option.fromUndefinedOr(null))
// Output: { _id: 'Option', _tag: 'Some', value: null }
console.log(Option.fromUndefinedOr(42))
// Output: { _id: 'Option', _tag: 'Some', value: 42 }
fromUndefinedOr,
encode: <A>(self: Option<A>) => A | undefinedencode: import OptionOption.const getOrUndefined: <A>(
self: Option<A>
) => A | undefined
Extracts the value from a Some, or returns undefined for None.
When to use
Use when you need to pass absent Option values to APIs that expect
undefined.
Details
Some → the inner valueNone → undefined
Example (Unwrapping to undefined)
import { Option } from "effect"
console.log(Option.getOrUndefined(Option.some(1)))
// Output: 1
console.log(Option.getOrUndefined(Option.none()))
// Output: undefined
getOrUndefined
})
}