withDecodingDefaultType<S, R>Wraps the Encoded side with optional (key absent or undefined)
and provides a default Type value when the field is missing or
undefined during decoding.
When to use
Use when the default is already in the decoded representation and should not pass through the field's decoding transformation.
Details
Unlike withDecodingDefault, the default value is specified in terms
of the Type (decoded) representation, so it does not need to go through
the decoding transformation.
Options:
encodingStrategy:"passthrough"(default): include the value in the encoded output."omit": omit the key from the encoded output.
export interface interface withDecodingDefaultType<S extends Constraint, R = never>Wraps the Encoded side with optional (key absent or undefined)
and provides a default Type value when the field is missing or
undefined during decoding.
When to use
Use when the default is already in the decoded representation and should not
pass through the field's decoding transformation.
Details
Unlike
withDecodingDefault
, the default value is specified in terms
of the Type (decoded) representation, so it does not need to go through
the decoding transformation.
Options:
encodingStrategy:
"passthrough" (default): include the value in the encoded output."omit": omit the key from the encoded output.
Type-level representation returned by
withDecodingDefaultType
.
withDecodingDefaultType<function (type parameter) S in withDecodingDefaultType<S extends Constraint, R = never>S extends Constraint, function (type parameter) R in withDecodingDefaultType<S extends Constraint, R = never>R = never>
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 withDecodingDefault<S extends Constraint, R = never>Wraps the Encoded side with optional (key absent or undefined)
and provides a default Encoded value when the field is missing or
undefined during decoding.
When to use
Use when the default is expressed in the encoded representation, before the
field's decoding transformation runs.
Details
The default value is specified in terms of the Encoded type (before any
decoding transformations).
Options:
encodingStrategy:
"passthrough" (default): include the value in the encoded output."omit": omit the key from the encoded output.
Example (Providing a default for an optional field value)
import { Effect, Schema } from "effect"
const MySchema = Schema.Struct({
name: Schema.String.pipe(Schema.optional, Schema.withDecodingDefault(Effect.succeed("anonymous")))
})
const result = Schema.decodeUnknownSync(MySchema)({ name: undefined })
// result: { name: "anonymous" }
Type-level representation returned by
withDecodingDefault
.
withDecodingDefault<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 withDecodingDefaultType<S extends Constraint, R = never>S>, function (type parameter) R in withDecodingDefaultType<S extends Constraint, R = never>R>, interface optional<S extends Constraint>Type-level representation returned by
optional
.
Marks a struct field as optional, allowing the key to be absent or
undefined.
Details
The resulting property may be absent or explicitly set to undefined.
Equivalent to optionalKey(UndefinedOr(S)).
Use
optionalKey
instead if you want exact optional semantics (absent
only, not undefined).
Example (Defining an optional field accepting undefined)
import { Schema } from "effect"
const schema = Schema.Struct({
name: Schema.String,
age: Schema.optional(Schema.Number)
})
// { readonly name: string; readonly age?: number | undefined }
type Person = typeof schema.Type
optional<function (type parameter) S in withDecodingDefaultType<S extends Constraint, R = never>S>>
{
readonly "Rebuild": interface withDecodingDefaultType<S extends Constraint, R = never>Wraps the Encoded side with optional (key absent or undefined)
and provides a default Type value when the field is missing or
undefined during decoding.
When to use
Use when the default is already in the decoded representation and should not
pass through the field's decoding transformation.
Details
Unlike
withDecodingDefault
, the default value is specified in terms
of the Type (decoded) representation, so it does not need to go through
the decoding transformation.
Options:
encodingStrategy:
"passthrough" (default): include the value in the encoded output."omit": omit the key from the encoded output.
Type-level representation returned by
withDecodingDefaultType
.
withDecodingDefaultType<function (type parameter) S in withDecodingDefaultType<S extends Constraint, R = never>S, function (type parameter) R in withDecodingDefaultType<S extends Constraint, R = never>R>
}
/**
* Wraps the `Encoded` side with `optional` (key absent **or** `undefined`)
* and provides a default `Type` value when the field is missing or
* `undefined` during decoding.
*
* **When to use**
*
* Use when the default is already in the decoded representation and should not
* pass through the field's decoding transformation.
*
* **Details**
*
* Unlike {@link withDecodingDefault}, the default value is specified in terms
* of the `Type` (decoded) representation, so it does not need to go through
* the decoding transformation.
*
* Options:
*
* - `encodingStrategy`:
* - `"passthrough"` (default): include the value in the encoded output.
* - `"omit"`: omit the key from the encoded output.
*
* @see {@link withDecodingDefault} for the variant where the default is an `Encoded` value
* @see {@link withDecodingDefaultTypeKey} for the key-level variant
* @category decoding
* @since 4.0.0
*/
export function function withDecodingDefaultType<
S extends Constraint,
R = never
>(
defaultValue: Effect.Effect<
S["Type"],
SchemaError,
R
>,
options?: DecodingDefaultOptions
): (self: S) => withDecodingDefaultType<S, R>
Wraps the Encoded side with optional (key absent or undefined)
and provides a default Type value when the field is missing or
undefined during decoding.
When to use
Use when the default is already in the decoded representation and should not
pass through the field's decoding transformation.
Details
Unlike
withDecodingDefault
, the default value is specified in terms
of the Type (decoded) representation, so it does not need to go through
the decoding transformation.
Options:
encodingStrategy:
"passthrough" (default): include the value in the encoded output."omit": omit the key from the encoded output.
withDecodingDefaultType<function (type parameter) S in withDecodingDefaultType<S extends Constraint, R = never>(defaultValue: Effect.Effect<S["Type"], SchemaError, R>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultType<S, R>S extends Constraint, function (type parameter) R in withDecodingDefaultType<S extends Constraint, R = never>(defaultValue: Effect.Effect<S["Type"], SchemaError, R>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultType<S, R>R = never>(
defaultValue: Effect.Effect<S["Type"], SchemaError, R>(parameter) defaultValue: {
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
import EffectEffect.type Effect.Effect = /*unresolved*/ anyEffect<function (type parameter) S in withDecodingDefaultType<S extends Constraint, R = never>(defaultValue: Effect.Effect<S["Type"], SchemaError, R>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultType<S, R>S["Type"], class SchemaErrorclass SchemaError {
message: string;
toString: () => string;
name: string;
stack: string;
cause: unknown;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toJSON: () => unknown;
_tag: Tag;
issue: SchemaIssue.Issue;
}
Error thrown (or returned as the error channel value) when schema decoding
or encoding fails.
Details
The issue field contains a structured
Issue
tree describing
every validation failure, including the path to the problematic value,
expected types, and actual values received. message renders the issue tree
as a human-readable string.
Use
isSchemaError
to narrow an unknown value to SchemaError.
Example (Catching a SchemaError)
import { Schema } from "effect"
try {
Schema.decodeUnknownSync(Schema.Number)("not a number")
} catch (err) {
if (Schema.isSchemaError(err)) {
console.log(err.message)
// Expected number, actual "not a number"
}
}
SchemaError, function (type parameter) R in withDecodingDefaultType<S extends Constraint, R = never>(defaultValue: Effect.Effect<S["Type"], SchemaError, R>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultType<S, R>R>,
options: DecodingDefaultOptionsoptions?: type DecodingDefaultOptions = {
readonly encodingStrategy?:
| "omit"
| "passthrough"
| undefined
}
Options for
withDecodingDefaultKey
and
withDecodingDefault
.
Details
encodingStrategy:
"passthrough" (default): pass the value through during encoding"omit": omit the key from the encoded output
DecodingDefaultOptions
) {
return (self: S extends Constraintself: function (type parameter) S in withDecodingDefaultType<S extends Constraint, R = never>(defaultValue: Effect.Effect<S["Type"], SchemaError, R>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultType<S, R>S): interface withDecodingDefaultType<S extends Constraint, R = never>Wraps the Encoded side with optional (key absent or undefined)
and provides a default Type value when the field is missing or
undefined during decoding.
When to use
Use when the default is already in the decoded representation and should not
pass through the field's decoding transformation.
Details
Unlike
withDecodingDefault
, the default value is specified in terms
of the Type (decoded) representation, so it does not need to go through
the decoding transformation.
Options:
encodingStrategy:
"passthrough" (default): include the value in the encoded output."omit": omit the key from the encoded output.
Type-level representation returned by
withDecodingDefaultType
.
withDecodingDefaultType<function (type parameter) S in withDecodingDefaultType<S extends Constraint, R = never>(defaultValue: Effect.Effect<S["Type"], SchemaError, R>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultType<S, R>S, function (type parameter) R in withDecodingDefaultType<S extends Constraint, R = never>(defaultValue: Effect.Effect<S["Type"], SchemaError, R>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultType<S, R>R> => {
return 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(self: S extends Constraintself).pipe(
function withDecodingDefault<
S extends Constraint,
R = never
>(
defaultValue: Effect.Effect<
S["Encoded"],
SchemaError,
R
>,
options?: DecodingDefaultOptions
): (self: S) => withDecodingDefault<S, R>
Wraps the Encoded side with optional (key absent or undefined)
and provides a default Encoded value when the field is missing or
undefined during decoding.
When to use
Use when the default is expressed in the encoded representation, before the
field's decoding transformation runs.
Details
The default value is specified in terms of the Encoded type (before any
decoding transformations).
Options:
encodingStrategy:
"passthrough" (default): include the value in the encoded output."omit": omit the key from the encoded output.
Example (Providing a default for an optional field value)
import { Effect, Schema } from "effect"
const MySchema = Schema.Struct({
name: Schema.String.pipe(Schema.optional, Schema.withDecodingDefault(Effect.succeed("anonymous")))
})
const result = Schema.decodeUnknownSync(MySchema)({ name: undefined })
// result: { name: "anonymous" }
withDecodingDefault<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 withDecodingDefaultType<S extends Constraint, R = never>(defaultValue: Effect.Effect<S["Type"], SchemaError, R>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultType<S, R>S>, function (type parameter) R in withDecodingDefaultType<S extends Constraint, R = never>(defaultValue: Effect.Effect<S["Type"], SchemaError, R>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultType<S, R>R>(defaultValue: Effect.Effect<S["Type"], SchemaError, R>(parameter) defaultValue: {
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
options: DecodingDefaultOptionsoptions),
function encodeTo<optional<S>>(to: optional<S>): <From>(from: From) => decodeTo<From, optional<S>, never, never> (+1 overload)Reverses a schema transformation so the encoded schema is supplied first.
When to use
Use to define a transformation by naming the encoded schema before the
decoded schema.
Details
encodeTo(to)(from) is equivalent to to.pipe(decodeTo(from)). The from
schema acts as the target decoded schema and to acts as the encoded source.
Example (Encoding a number back to a string)
import { Schema, SchemaGetter } from "effect"
const NumberFromString = Schema.Number.pipe(
Schema.encodeTo(Schema.String, {
decode: SchemaGetter.transform((s: string) => Number(s)),
encode: SchemaGetter.transform((n: number) => String(n))
})
)
encodeTo(const optional: optionalLambda
;<S>(self: S) => optional<S>
Type-level representation returned by
optional
.
Marks a struct field as optional, allowing the key to be absent or
undefined.
Details
The resulting property may be absent or explicitly set to undefined.
Equivalent to optionalKey(UndefinedOr(S)).
Use
optionalKey
instead if you want exact optional semantics (absent
only, not undefined).
Example (Defining an optional field accepting undefined)
import { Schema } from "effect"
const schema = Schema.Struct({
name: Schema.String,
age: Schema.optional(Schema.Number)
})
// { readonly name: string; readonly age?: number | undefined }
type Person = typeof schema.Type
optional(self: S extends Constraintself))
)
}
}