<T>(): Transformation<Option.Option<T>, T>Decodes an optional struct key into Option<T> and encodes Option<T>
back to an optional key.
When to use
Use when you need a schema transformation to convert optional struct keys
(declared with Schema.optionalKey) to Option values.
Details
Decoding maps an absent key (None) to Some(None) and a present key
(Some(v)) to Some(Some(v)). Encoding maps Some(None) to None to omit
the key, and maps Some(Some(v)) to Some(v). This uses
transformOptional under the hood.
Example (Converting an optional key to an Option)
import { Schema, SchemaTransformation } from "effect"
const schema = Schema.Struct({
name: Schema.optionalKey(Schema.String).pipe(
Schema.decodeTo(
Schema.Option(Schema.String),
SchemaTransformation.optionFromOptionalKey()
)
)
})export function function optionFromOptionalKey<
T
>(): Transformation<Option.Option<T>, T>
Decodes an optional struct key into Option<T> and encodes Option<T>
back to an optional key.
When to use
Use when you need a schema transformation to convert optional struct keys
(declared with Schema.optionalKey) to Option values.
Details
Decoding maps an absent key (None) to Some(None) and a present key
(Some(v)) to Some(Some(v)). Encoding maps Some(None) to None to omit
the key, and maps Some(Some(v)) to Some(v). This uses
transformOptional under the hood.
Example (Converting an optional key to an Option)
import { Schema, SchemaTransformation } from "effect"
const schema = Schema.Struct({
name: Schema.optionalKey(Schema.String).pipe(
Schema.decodeTo(
Schema.Option(Schema.String),
SchemaTransformation.optionFromOptionalKey()
)
)
})
optionFromOptionalKey<function (type parameter) T in optionFromOptionalKey<T>(): Transformation<Option.Option<T>, T>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 optionFromOptionalKey<T>(): Transformation<Option.Option<T>, T>T>, function (type parameter) T in optionFromOptionalKey<T>(): Transformation<Option.Option<T>, T>T> {
return function transformOptional<
T,
E
>(options: {
readonly decode: (
input: Option.Option<E>
) => Option.Option<T>
readonly encode: (
input: Option.Option<T>
) => Option.Option<E>
}): Transformation<T, E>
Creates a Transformation where decode and encode operate on Option
values, giving full control over missing-key handling.
When to use
Use when you need a schema transformation to produce or consume Option.None
for absent keys.
- You are working with optional struct fields.
Details
- Each function receives
Option<input> and returns Option<output>.
Option.None input means the key is absent; returning Option.None
omits the key from the output.- Pure and synchronous.
Example (Converting an optional key to Option)
import { Option, Schema, SchemaTransformation } from "effect"
const schema = Schema.Struct({
a: Schema.optionalKey(Schema.Number).pipe(
Schema.decodeTo(
Schema.Option(Schema.Number),
SchemaTransformation.transformOptional({
decode: Option.some,
encode: Option.flatten
})
)
)
})
transformOptional({
decode: <A>(value: A) => Option<A>decode: import OptionOption.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,
encode: <A>(
self: Option<Option<A>>
) => Option<A>
import OptionOption.const flatten: <A>(
self: Option<Option<A>>
) => Option<A>
Flattens a nested Option<Option<A>> into Option<A>.
When to use
Use when you need to remove one layer of nested Option.
Details
Some(Some(value)) → Some(value)Some(None) → NoneNone → None
Example (Flattening nested Options)
import { Option } from "effect"
console.log(Option.flatten(Option.some(Option.some("value"))))
// Output: { _id: 'Option', _tag: 'Some', value: 'value' }
console.log(Option.flatten(Option.some(Option.none())))
// Output: { _id: 'Option', _tag: 'None' }
flatten
})
}