ArrayEnsure<S>Creates a schema that accepts either a value decoded by schema or an array
decoded by Schema.Array(schema), then returns an array.
When to use
Use to accept input that may be provided either as one item or as an array, while normalizing decoded values to a readonly array.
Details
During encoding, one-element arrays are encoded as the single element. Empty arrays and arrays with two or more elements are encoded as arrays.
Gotchas
The single-value branch is tried before the array branch. If schema itself
accepts arrays, an array input can be treated as one value and wrapped in a
one-element array.
export interface interface ArrayEnsure<S extends Constraint>Creates a schema that accepts either a value decoded by schema or an array
decoded by Schema.Array(schema), then returns an array.
When to use
Use to accept input that may be provided either as one item or as an array,
while normalizing decoded values to a readonly array.
Details
During encoding, one-element arrays are encoded as the single element. Empty
arrays and arrays with two or more elements are encoded as arrays.
Gotchas
The single-value branch is tried before the array branch. If schema itself
accepts arrays, an array input can be treated as one value and wrapped in a
one-element array.
Type-level representation returned by
ArrayEnsure
.
ArrayEnsure<function (type parameter) S in ArrayEnsure<S extends Constraint>S extends Constraint> extends interface decodeTo<To extends Constraint, From extends Constraint, RD = never, RE = never>Creates a schema that transforms from a source schema to a target schema.
When to use
Use when decoding should change the schema's decoded type or encoded shape,
with an optional custom bidirectional transformation.
Details
Call it with the target schema to and then pipe the source schema from
into the returned function. The resulting schema decodes from
From["Encoded"] to To["Type"] and encodes from To["Type"] back to
From["Encoded"].
When no transformation is provided, SchemaTransformation.passthrough() is
used, so From["Type"] must already be compatible with To["Encoded"].
The resulting schema combines decoding and encoding services from both
schemas and any custom transformation.
Gotchas
In a custom transformation, decode maps From["Type"] to To["Encoded"]
and is used on the encoding path, while encode maps To["Encoded"] to
From["Type"] and is used on the decoding path.
Example (Transforming strings to numbers with a schema transformation)
import { Schema, SchemaGetter } from "effect"
const NumberFromString = Schema.String.pipe(
Schema.decodeTo(
Schema.Number,
{
decode: SchemaGetter.transform((s) => Number(s)),
encode: SchemaGetter.transform((n) => String(n))
}
)
)
const result = Schema.decodeUnknownSync(NumberFromString)("123")
// result: 123
Type-level representation returned by
decodeTo
.
decodeTo<interface $Array<S extends Constraint>Type-level representation returned by
Array
.
$Array<interface toType<S extends Constraint>Type-level representation returned by
toType
.
Extracts the type-side schema: sets Encoded to equal the decoded Type,
discarding the encoding transformation path.
toType<function (type parameter) S in ArrayEnsure<S extends Constraint>S>>, interface Union<Members extends ReadonlyArray<Constraint>>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
Type-level representation returned by
Union
.
Union<readonly [function (type parameter) S in ArrayEnsure<S extends Constraint>S, interface $Array<S extends Constraint>Type-level representation returned by
Array
.
$Array<function (type parameter) S in ArrayEnsure<S extends Constraint>S>]>> {
readonly "Rebuild": interface ArrayEnsure<S extends Constraint>Creates a schema that accepts either a value decoded by schema or an array
decoded by Schema.Array(schema), then returns an array.
When to use
Use to accept input that may be provided either as one item or as an array,
while normalizing decoded values to a readonly array.
Details
During encoding, one-element arrays are encoded as the single element. Empty
arrays and arrays with two or more elements are encoded as arrays.
Gotchas
The single-value branch is tried before the array branch. If schema itself
accepts arrays, an array input can be treated as one value and wrapped in a
one-element array.
Type-level representation returned by
ArrayEnsure
.
ArrayEnsure<function (type parameter) S in ArrayEnsure<S extends Constraint>S>
}
/**
* Creates a schema that accepts either a value decoded by `schema` or an array
* decoded by `Schema.Array(schema)`, then returns an array.
*
* **When to use**
*
* Use to accept input that may be provided either as one item or as an array,
* while normalizing decoded values to a readonly array.
*
* **Details**
*
* During encoding, one-element arrays are encoded as the single element. Empty
* arrays and arrays with two or more elements are encoded as arrays.
*
* **Gotchas**
*
* The single-value branch is tried before the array branch. If `schema` itself
* accepts arrays, an array input can be treated as one value and wrapped in a
* one-element array.
*
* @see {@link Array} for accepting only array input
* @see {@link NonEmptyArray} for requiring at least one decoded element
*
* @category constructors
* @since 3.10.0
*/
export function function ArrayEnsure<
S extends Constraint
>(schema: S): ArrayEnsure<S>
Creates a schema that accepts either a value decoded by schema or an array
decoded by Schema.Array(schema), then returns an array.
When to use
Use to accept input that may be provided either as one item or as an array,
while normalizing decoded values to a readonly array.
Details
During encoding, one-element arrays are encoded as the single element. Empty
arrays and arrays with two or more elements are encoded as arrays.
Gotchas
The single-value branch is tried before the array branch. If schema itself
accepts arrays, an array input can be treated as one value and wrapped in a
one-element array.
ArrayEnsure<function (type parameter) S in ArrayEnsure<S extends Constraint>(schema: S): ArrayEnsure<S>S extends Constraint>(schema: S extends Constraintschema: function (type parameter) S in ArrayEnsure<S extends Constraint>(schema: S): ArrayEnsure<S>S): interface ArrayEnsure<S extends Constraint>Creates a schema that accepts either a value decoded by schema or an array
decoded by Schema.Array(schema), then returns an array.
When to use
Use to accept input that may be provided either as one item or as an array,
while normalizing decoded values to a readonly array.
Details
During encoding, one-element arrays are encoded as the single element. Empty
arrays and arrays with two or more elements are encoded as arrays.
Gotchas
The single-value branch is tried before the array branch. If schema itself
accepts arrays, an array input can be treated as one value and wrapped in a
one-element array.
Type-level representation returned by
ArrayEnsure
.
ArrayEnsure<function (type parameter) S in ArrayEnsure<S extends Constraint>(schema: S): ArrayEnsure<S>S> {
return 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([schema: S extends Constraintschema, const ArraySchema: ArrayLambda
;<S>(self: S) => $Array<S>
schema: S extends Constraintschema)]).pipe(function decodeTo<$Array<toType<S>>, Constraint, never, never>(to: $Array<toType<S>>, transformation: {
readonly decode: SchemaGetter.Getter<NoInfer<readonly S["Type"][]>, unknown, never>;
readonly encode: SchemaGetter.Getter<unknown, NoInfer<readonly S["Type"][]>, never>;
}): (from: Constraint) => decodeTo<$Array<toType<S>>, Constraint, never, never> (+1 overload)
Creates a schema that transforms from a source schema to a target schema.
When to use
Use when decoding should change the schema's decoded type or encoded shape,
with an optional custom bidirectional transformation.
Details
Call it with the target schema to and then pipe the source schema from
into the returned function. The resulting schema decodes from
From["Encoded"] to To["Type"] and encodes from To["Type"] back to
From["Encoded"].
When no transformation is provided, SchemaTransformation.passthrough() is
used, so From["Type"] must already be compatible with To["Encoded"].
The resulting schema combines decoding and encoding services from both
schemas and any custom transformation.
Gotchas
In a custom transformation, decode maps From["Type"] to To["Encoded"]
and is used on the encoding path, while encode maps To["Encoded"] to
From["Type"] and is used on the decoding path.
Example (Transforming strings to numbers with a schema transformation)
import { Schema, SchemaGetter } from "effect"
const NumberFromString = Schema.String.pipe(
Schema.decodeTo(
Schema.Number,
{
decode: SchemaGetter.transform((s) => Number(s)),
encode: SchemaGetter.transform((n) => String(n))
}
)
)
const result = Schema.decodeUnknownSync(NumberFromString)("123")
// result: 123
decodeTo(
const ArraySchema: ArrayLambda
<toType<S>>(self: toType<S>) => $Array<toType<S>>
const toType: toTypeLambda
;<S>(self: S) => toType<S>
Type-level representation returned by
toType
.
Extracts the type-side schema: sets Encoded to equal the decoded Type,
discarding the encoding transformation path.
toType(schema: S extends Constraintschema)),
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: S["Type"] | readonly S["Type"][]
) => NoInfer<readonly S["Type"][]>
import ArrArr.ensure,
encode: (
input: NoInfer<readonly S["Type"][]>
) => S["Type"] | readonly S["Type"][]
array: NoInfer<readonly S["Type"][]>array) => array: readonly S["Type"][]array.ReadonlyArray<T>.length: numberGets the length of the array. This is a number one higher than the highest element defined in an array.
length === 1 ? array: readonly S["Type"][]array[0] : array: readonly S["Type"][]array
})
))
}