withDecodingDefaultTypeKey<S, R>Makes a struct key optional on the Encoded side (optionalKey, so the
key may be absent but not undefined) and provides a default Type
value when the key is missing during decoding.
Details
Unlike withDecodingDefaultKey, 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 withDecodingDefaultTypeKey<S extends Constraint, R = never>Makes a struct key optional on the Encoded side (optionalKey, so the
key may be absent but not undefined) and provides a default Type
value when the key is missing during decoding.
Details
Unlike
withDecodingDefaultKey
, 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
withDecodingDefaultTypeKey
.
withDecodingDefaultTypeKey<function (type parameter) S in withDecodingDefaultTypeKey<S extends Constraint, R = never>S extends Constraint, function (type parameter) R in withDecodingDefaultTypeKey<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 withDecodingDefaultKey<S extends Constraint, R = never>Makes a struct key optional on the Encoded side and provides a default
Encoded value when the key is missing during decoding.
Details
The key uses optionalKey on the encoded side, so it may be absent from the
input object but not undefined. 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 a missing struct key)
import { Effect, Schema } from "effect"
const MySchema = Schema.Struct({
name: Schema.String.pipe(Schema.withDecodingDefaultKey(Effect.succeed("anonymous")))
})
const result = Schema.decodeUnknownSync(MySchema)({})
// result: { name: "anonymous" }
Type-level representation returned by
withDecodingDefaultKey
.
withDecodingDefaultKey<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 withDecodingDefaultTypeKey<S extends Constraint, R = never>S>, function (type parameter) R in withDecodingDefaultTypeKey<S extends Constraint, R = never>R>, interface optionalKey<S extends Constraint>Type-level representation returned by
optionalKey
.
Creates an exact optional key schema for struct fields. Unlike optional,
this creates exact optional properties (not | undefined) that can be
completely omitted from the object.
Example (Creating a struct with optional key)
import { Schema } from "effect"
const schema = Schema.Struct({
name: Schema.String,
age: Schema.optionalKey(Schema.Number)
})
// Type: { readonly name: string; readonly age?: number }
type Person = typeof schema["Type"]
optionalKey<function (type parameter) S in withDecodingDefaultTypeKey<S extends Constraint, R = never>S>>
{
readonly "Rebuild": interface withDecodingDefaultTypeKey<S extends Constraint, R = never>Makes a struct key optional on the Encoded side (optionalKey, so the
key may be absent but not undefined) and provides a default Type
value when the key is missing during decoding.
Details
Unlike
withDecodingDefaultKey
, 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
withDecodingDefaultTypeKey
.
withDecodingDefaultTypeKey<function (type parameter) S in withDecodingDefaultTypeKey<S extends Constraint, R = never>S, function (type parameter) R in withDecodingDefaultTypeKey<S extends Constraint, R = never>R>
}
/**
* Makes a struct key optional on the `Encoded` side (`optionalKey`, so the
* key may be absent but **not** `undefined`) and provides a default `Type`
* value when the key is missing during decoding.
*
* **Details**
*
* Unlike {@link withDecodingDefaultKey}, 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 withDecodingDefaultKey} for the variant where the default is an `Encoded` value
* @see {@link withDecodingDefaultType} for the value-level variant
* @category decoding
* @since 4.0.0
*/
export function function withDecodingDefaultTypeKey<
S extends Constraint,
R = never
>(
defaultValue: Effect.Effect<
S["Type"],
SchemaError,
R
>,
options?: DecodingDefaultOptions
): (self: S) => withDecodingDefaultTypeKey<S, R>
Makes a struct key optional on the Encoded side (optionalKey, so the
key may be absent but not undefined) and provides a default Type
value when the key is missing during decoding.
Details
Unlike
withDecodingDefaultKey
, 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.
withDecodingDefaultTypeKey<function (type parameter) S in withDecodingDefaultTypeKey<S extends Constraint, R = never>(defaultValue: Effect.Effect<S["Type"], SchemaError, R>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultTypeKey<S, R>S extends Constraint, function (type parameter) R in withDecodingDefaultTypeKey<S extends Constraint, R = never>(defaultValue: Effect.Effect<S["Type"], SchemaError, R>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultTypeKey<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 withDecodingDefaultTypeKey<S extends Constraint, R = never>(defaultValue: Effect.Effect<S["Type"], SchemaError, R>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultTypeKey<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 withDecodingDefaultTypeKey<S extends Constraint, R = never>(defaultValue: Effect.Effect<S["Type"], SchemaError, R>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultTypeKey<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 withDecodingDefaultTypeKey<S extends Constraint, R = never>(defaultValue: Effect.Effect<S["Type"], SchemaError, R>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultTypeKey<S, R>S): interface withDecodingDefaultTypeKey<S extends Constraint, R = never>Makes a struct key optional on the Encoded side (optionalKey, so the
key may be absent but not undefined) and provides a default Type
value when the key is missing during decoding.
Details
Unlike
withDecodingDefaultKey
, 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
withDecodingDefaultTypeKey
.
withDecodingDefaultTypeKey<function (type parameter) S in withDecodingDefaultTypeKey<S extends Constraint, R = never>(defaultValue: Effect.Effect<S["Type"], SchemaError, R>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultTypeKey<S, R>S, function (type parameter) R in withDecodingDefaultTypeKey<S extends Constraint, R = never>(defaultValue: Effect.Effect<S["Type"], SchemaError, R>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultTypeKey<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 withDecodingDefaultKey<
S extends Constraint,
R = never
>(
defaultValue: Effect.Effect<
S["Encoded"],
SchemaError,
R
>,
options?: DecodingDefaultOptions
): (self: S) => withDecodingDefaultKey<S, R>
Makes a struct key optional on the Encoded side and provides a default
Encoded value when the key is missing during decoding.
Details
The key uses optionalKey on the encoded side, so it may be absent from the
input object but not undefined. 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 a missing struct key)
import { Effect, Schema } from "effect"
const MySchema = Schema.Struct({
name: Schema.String.pipe(Schema.withDecodingDefaultKey(Effect.succeed("anonymous")))
})
const result = Schema.decodeUnknownSync(MySchema)({})
// result: { name: "anonymous" }
withDecodingDefaultKey<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 withDecodingDefaultTypeKey<S extends Constraint, R = never>(defaultValue: Effect.Effect<S["Type"], SchemaError, R>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultTypeKey<S, R>S>, function (type parameter) R in withDecodingDefaultTypeKey<S extends Constraint, R = never>(defaultValue: Effect.Effect<S["Type"], SchemaError, R>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultTypeKey<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<optionalKey<S>>(to: optionalKey<S>): <From>(from: From) => decodeTo<From, optionalKey<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 optionalKey: optionalKeyLambda
;<S>(self: S) => optionalKey<S>
Type-level representation returned by
optionalKey
.
Creates an exact optional key schema for struct fields. Unlike optional,
this creates exact optional properties (not | undefined) that can be
completely omitted from the object.
Example (Creating a struct with optional key)
import { Schema } from "effect"
const schema = Schema.Struct({
name: Schema.String,
age: Schema.optionalKey(Schema.Number)
})
// Type: { readonly name: string; readonly age?: number }
type Person = typeof schema["Type"]
optionalKey(self: S extends Constraintself))
)
}
}