<T>(options?: { onNoneEncoding: null | undefined }): Transformation<
Option.Option<T>,
T | null | undefined
>Decodes T | null | undefined into Option<T> and encodes Option<T>
back to T | null or T | undefined depending on the provided
options.onNoneEncoding (defaults to undefined).
When to use
Use when you need a schema transformation to convert nullish API fields to
Option when both null and undefined represent absence.
Details
Decoding maps null and undefined to Option.none() and all other values
to Option.some(value). Encoding maps Option.none() to null or
undefined according to options.onNoneEncoding, and maps
Option.some(value) to value. The transformation is pure and synchronous.
Example (Converting nullish values to an Option and encoding None as null)
import { Schema, SchemaTransformation } from "effect"
const schema = Schema.NullishOr(Schema.String).pipe(
Schema.decodeTo(
Schema.Option(Schema.String),
SchemaTransformation.optionFromNullishOr({ onNoneEncoding: null })
)
)export function function optionFromNullishOr<
T
>(options?: {
onNoneEncoding: null | undefined
}): Transformation<
Option.Option<T>,
T | null | undefined
>
Decodes T | null | undefined into Option<T> and encodes Option<T>
back to T | null or T | undefined depending on the provided
options.onNoneEncoding (defaults to undefined).
When to use
Use when you need a schema transformation to convert nullish API fields to
Option when both null and undefined represent absence.
Details
Decoding maps null and undefined to Option.none() and all other values
to Option.some(value). Encoding maps Option.none() to null or
undefined according to options.onNoneEncoding, and maps
Option.some(value) to value. The transformation is pure and synchronous.
Example (Converting nullish values to an Option and encoding None as null)
import { Schema, SchemaTransformation } from "effect"
const schema = Schema.NullishOr(Schema.String).pipe(
Schema.decodeTo(
Schema.Option(Schema.String),
SchemaTransformation.optionFromNullishOr({ onNoneEncoding: null })
)
)
optionFromNullishOr<function (type parameter) T in optionFromNullishOr<T>(options?: {
onNoneEncoding: null | undefined;
}): Transformation<Option.Option<T>, T | null | undefined>
options: | {
onNoneEncoding: null | undefined
}
| undefined
onNoneEncoding: null | undefinedonNoneEncoding: null | undefined
}
): 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 optionFromNullishOr<T>(options?: {
onNoneEncoding: null | undefined;
}): Transformation<Option.Option<T>, T | null | undefined>
function (type parameter) T in optionFromNullishOr<T>(options?: {
onNoneEncoding: null | undefined;
}): Transformation<Option.Option<T>, T | null | undefined>
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<NonNullable<A>>decode: import OptionOption.const fromNullishOr: <A>(
a: A
) => Option<NonNullable<A>>
Converts a nullable value (null or undefined) into an Option.
When to use
Use when you need JavaScript nullish values to become absence at an API
boundary while all other values, including falsy ones, remain present.
Details
null or undefined → None- Any other value →
Some (typed as NonNullable<A>)
Example (Converting nullable values to an Option)
import { Option } from "effect"
console.log(Option.fromNullishOr(undefined))
// Output: { _id: 'Option', _tag: 'None' }
console.log(Option.fromNullishOr(null))
// Output: { _id: 'Option', _tag: 'None' }
console.log(Option.fromNullishOr(1))
// Output: { _id: 'Option', _tag: 'Some', value: 1 }
fromNullishOr,
encode: (
input: Option.Option<T>
) => T | null | undefined
options: | {
onNoneEncoding: null | undefined
}
| undefined
onNoneEncoding: null | undefinedonNoneEncoding === null ? import OptionOption.const getOrNull: <A>(
self: Option<A>
) => A | null
Extracts the value from a Some, or returns null for None.
When to use
Use when you need to pass absent Option values to APIs that expect null.
Details
Some → the inner valueNone → null
Example (Unwrapping to null)
import { Option } from "effect"
console.log(Option.getOrNull(Option.some(1)))
// Output: 1
console.log(Option.getOrNull(Option.none()))
// Output: null
getOrNull : 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
})
}