Schema.decodeTo<
Schema.$Record<Schema.String, Schema.Unknown>,
Schema.$Record<
Schema.String,
Schema.Codec<PrimitiveTree, PrimitiveTree, never, never>
>,
never,
never
>Schema for serializing public Schema.Annotations.Annotations values. It
filters out internal annotation keys and non-primitive values during
encoding.
When to use
Use to serialize schema annotations in representation schemas while retaining only primitive-tree metadata.
Details
Decoding is passthrough. Encoding removes internal annotation keys and values
that are not accepted by $PrimitiveTree.
export const const $Annotations: Schema.decodeTo<
Schema.$Record<Schema.String, Schema.Unknown>,
Schema.$Record<
Schema.String,
Schema.Codec<
PrimitiveTree,
PrimitiveTree,
never,
never
>
>,
never,
never
>
const $Annotations: {
Type: To["Type"];
Encoded: From["Encoded"];
DecodingServices: To["DecodingServices"] | From["DecodingServices"] | RD;
EncodingServices: To["EncodingServices"] | From["EncodingServices"] | RE;
Iso: To["Iso"];
from: From;
to: To;
Rebuild: Rebuild;
ast: Ast;
annotate: (annotations: Schema.Annotations.Bottom<{ readonly [x: string]: unknown; }, readonly []>) => Schema.decodeTo<Schema.$Record<Schema.String, Schema.Unknown>, Schema.$Record<Schema.String, Schema.Codec<PrimitiveTree, PrimitiveTree, never, nev…;
annotateKey: (annotations: Schema.Annotations.Key<{ readonly [x: string]: unknown }>) => Schema.decodeTo<Schema.$Record<Schema.String, Schema.Unknown>, Schema.$Record<Schema.String, Schema.Codec<PrimitiveTree, PrimitiveTree, never, never>>, never, neve…;
check: (checks_0: SchemaAST.Check<{ readonly [x: string]: unknown }>, ...checks: Array<SchemaAST.Check<{ readonly [x: string]: unknown }>>) => Schema.decodeTo<Schema.$Record<Schema.String, Schema.Unknown>, Schema.$Record<Schema.String, Schema.Cod…;
rebuild: (ast: SchemaAST.Objects) => Schema.decodeTo<Schema.$Record<Schema.String, Schema.Unknown>, Schema.$Record<Schema.String, Schema.Codec<PrimitiveTree, PrimitiveTree, never, never>>, never, never>;
make: (input: { readonly [x: string]: unknown }, options?: MakeOptions) => { readonly [x: string]: unknown };
makeOption: (input: { readonly [x: string]: unknown }, options?: MakeOptions) => Option_.Option<{ readonly [x: string]: unknown }>;
makeEffect: (input: { readonly [x: string]: unknown }, options?: MakeOptions) => Effect.Effect<{ readonly [x: string]: unknown }, SchemaError, never>;
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; <…;
}
Schema for serializing public Schema.Annotations.Annotations values. It
filters out internal annotation keys and non-primitive values during
encoding.
When to use
Use to serialize schema annotations in representation schemas while retaining
only primitive-tree metadata.
Details
Decoding is passthrough. Encoding removes internal annotation keys and values
that are not accepted by $PrimitiveTree.
$Annotations = import SchemaSchema.function Record<
Key extends Record.Key,
Value extends Constraint
>(
key: Key,
value: Value,
options?: {
readonly keyValueCombiner: {
readonly decode?:
| Combiner.Combiner<
readonly [Key["Type"], Value["Type"]]
>
| undefined
readonly encode?:
| Combiner.Combiner<
readonly [
Key["Encoded"],
Value["Encoded"]
]
>
| undefined
}
}
): $Record<Key, Value>
Defines a record schema whose dynamic properties are selected by a key schema
and decoded with a value schema.
Details
For dynamic keys, the key schema selects matching own properties and the
value schema decodes or encodes only those selected properties. Checks on
string, number, symbol, and template literal key schemas narrow which
properties are selected.
For transformed key schemas, property selection is based on encoded property
names before the selected key is decoded.
Example (Defining a string-keyed record of numbers)
import { Schema } from "effect"
const schema = Schema.Record(Schema.String, Schema.Number)
// { readonly [x: string]: number }
type R = typeof schema.Type
const result = Schema.decodeUnknownSync(schema)({ a: 1, b: 2 })
console.log(result)
// { a: 1, b: 2 }
Record(import SchemaSchema.const String: Stringconst String: {
Rebuild: Rebuild;
Iso: Iso;
ast: Ast;
Type: T;
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
annotate: (annotations: Schema.Annotations.Bottom<string, readonly []>) => Schema.String;
annotateKey: (annotations: Schema.Annotations.Key<string>) => Schema.String;
check: (checks_0: SchemaAST.Check<string>, ...checks: Array<SchemaAST.Check<string>>) => Schema.String;
rebuild: (ast: SchemaAST.String) => Schema.String;
make: (input: string, options?: MakeOptions) => string;
makeOption: (input: string, options?: MakeOptions) => Option_.Option<string>;
makeEffect: (input: string, options?: MakeOptions) => Effect.Effect<string, SchemaError, never>;
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; <…;
}
Type-level representation of
String
.
Schema for string values. Validates that the input is typeof "string".
String, import SchemaSchema.const Unknown: Unknownconst Unknown: {
Rebuild: Rebuild;
Iso: Iso;
ast: Ast;
Type: T;
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
annotate: (annotations: Schema.Annotations.Bottom<unknown, readonly []>) => Schema.Unknown;
annotateKey: (annotations: Schema.Annotations.Key<unknown>) => Schema.Unknown;
check: (checks_0: SchemaAST.Check<unknown>, ...checks: Array<SchemaAST.Check<unknown>>) => Schema.Unknown;
rebuild: (ast: SchemaAST.Unknown) => Schema.Unknown;
make: (input: unknown, options?: MakeOptions) => unknown;
makeOption: (input: unknown, options?: MakeOptions) => Option_.Option<unknown>;
makeEffect: (input: unknown, options?: MakeOptions) => Effect.Effect<unknown, SchemaError, never>;
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; <…;
}
Type-level representation of
Unknown
.
Schema for the unknown type. Accepts any value without validation.
When to use
Use as a top schema when you need to accept any input while preserving
TypeScript's unknown safety at use sites.
Unknown).Pipeable.pipe<Schema.$Record<Schema.String, Schema.Unknown>, Schema.decodeTo<Schema.$Record<Schema.String, Schema.Unknown>, Schema.$Record<Schema.String, Schema.Codec<PrimitiveTree, PrimitiveTree, never, never>>, never, never>>(this: Schema.$Record<...>, ab: (_: Schema.$Record<Schema.String, Schema.Unknown>) => Schema.decodeTo<Schema.$Record<Schema.String, Schema.Unknown>, Schema.$Record<Schema.String, Schema.Codec<PrimitiveTree, PrimitiveTree, never, never>>, never, never>): Schema.decodeTo<...> (+21 overloads)pipe(
import SchemaSchema.function encodeTo<Schema.$Record<Schema.String, Schema.Codec<PrimitiveTree, PrimitiveTree, never, never>>, Schema.$Record<Schema.String, Schema.Unknown>, never, never>(to: Schema.$Record<Schema.String, Schema.Codec<PrimitiveTree, PrimitiveTree, never, never>>, transformation: {
readonly decode: SchemaGetter.Getter<NoInfer<{
readonly [x: string]: unknown;
}>, NoInfer<{
...;
}>, never>;
readonly encode: SchemaGetter.Getter<...>;
}): (from: Schema.$Record<...>) => Schema.decodeTo<...> (+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(import SchemaSchema.function Record<
Key extends Record.Key,
Value extends Constraint
>(
key: Key,
value: Value,
options?: {
readonly keyValueCombiner: {
readonly decode?:
| Combiner.Combiner<
readonly [Key["Type"], Value["Type"]]
>
| undefined
readonly encode?:
| Combiner.Combiner<
readonly [
Key["Encoded"],
Value["Encoded"]
]
>
| undefined
}
}
): $Record<Key, Value>
Defines a record schema whose dynamic properties are selected by a key schema
and decoded with a value schema.
Details
For dynamic keys, the key schema selects matching own properties and the
value schema decodes or encodes only those selected properties. Checks on
string, number, symbol, and template literal key schemas narrow which
properties are selected.
For transformed key schemas, property selection is based on encoded property
names before the selected key is decoded.
Example (Defining a string-keyed record of numbers)
import { Schema } from "effect"
const schema = Schema.Record(Schema.String, Schema.Number)
// { readonly [x: string]: number }
type R = typeof schema.Type
const result = Schema.decodeUnknownSync(schema)({ a: 1, b: 2 })
console.log(result)
// { a: 1, b: 2 }
Record(import SchemaSchema.const String: Stringconst String: {
Rebuild: Rebuild;
Iso: Iso;
ast: Ast;
Type: T;
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
annotate: (annotations: Schema.Annotations.Bottom<string, readonly []>) => Schema.String;
annotateKey: (annotations: Schema.Annotations.Key<string>) => Schema.String;
check: (checks_0: SchemaAST.Check<string>, ...checks: Array<SchemaAST.Check<string>>) => Schema.String;
rebuild: (ast: SchemaAST.String) => Schema.String;
make: (input: string, options?: MakeOptions) => string;
makeOption: (input: string, options?: MakeOptions) => Option_.Option<string>;
makeEffect: (input: string, options?: MakeOptions) => Effect.Effect<string, SchemaError, never>;
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; <…;
}
Type-level representation of
String
.
Schema for string values. Validates that the input is typeof "string".
String, const $PrimitiveTree: Schema.Codec<PrimitiveTree>const $PrimitiveTree: {
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
Rebuild: Codec<T, E, RD, RE>;
Type: T;
Iso: Iso;
ast: Ast;
annotate: (annotations: Schema.Annotations.Bottom<PrimitiveTree, any>) => Schema.Codec<PrimitiveTree, PrimitiveTree, never, never>;
annotateKey: (annotations: Schema.Annotations.Key<PrimitiveTree>) => Schema.Codec<PrimitiveTree, PrimitiveTree, never, never>;
check: (checks_0: SchemaAST.Check<PrimitiveTree>, ...checks: Array<SchemaAST.Check<PrimitiveTree>>) => Schema.Codec<PrimitiveTree, PrimitiveTree, never, never>;
rebuild: (ast: SchemaAST.AST) => Schema.Codec<PrimitiveTree, PrimitiveTree, never, never>;
make: (input: unknown, options?: MakeOptions) => SchemaRepresentation.PrimitiveTree;
makeOption: (input: unknown, options?: MakeOptions) => Option_.Option<SchemaRepresentation.PrimitiveTree>;
makeEffect: (input: unknown, options?: MakeOptions) => Effect.Effect<SchemaRepresentation.PrimitiveTree, SchemaError, never>;
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; <…;
}
Schema for
PrimitiveTree
.
When to use
Use to validate recursive annotation metadata trees whose leaves are null,
number, boolean, bigint, symbol, or string.
$PrimitiveTree), {
decode: SchemaGetter.Getter<
NoInfer<{
readonly [x: string]: PrimitiveTree
}>,
NoInfer<{
readonly [x: string]: PrimitiveTree
}>,
never
>
(property) decode: {
run: (input: Option.Option<E>, options: SchemaAST.ParseOptions) => Effect.Effect<Option.Option<T>, SchemaIssue.Issue, R>;
map: (f: (t: NoInfer<{ readonly [x: string]: PrimitiveTree }>) => T2) => SchemaGetter.Getter<T2, NoInfer<{ readonly [x: string]: PrimitiveTree }>, never>;
compose: (other: SchemaGetter.Getter<T2, NoInfer<{ readonly [x: string]: PrimitiveTree }>, R2>) => SchemaGetter.Getter<T2, NoInfer<{ readonly [x: string]: PrimitiveTree }>, R2>;
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; <…;
}
import SchemaGetterSchemaGetter.function passthrough<NoInfer<{
readonly [x: string]: PrimitiveTree;
}>>(): SchemaGetter.Getter<NoInfer<{
readonly [x: string]: PrimitiveTree;
}>, NoInfer<{
readonly [x: string]: PrimitiveTree;
}>, never> (+1 overload)
Returns the identity getter — passes the value through unchanged.
When to use
Use when you need a schema getter for one side of a decodeTo pair, either
encode or decode, to pass values through unchanged.
Details
- Pure, no allocation (singleton instance).
- Optimized away during
.compose() — composing with a passthrough is free.
- The default overload requires
T === E. Pass { strict: false } to opt
out of the type constraint.
Example (Passing through identity transformations)
import { Schema, SchemaGetter } from "effect"
// No transformation needed — types already match
const StringToString = Schema.String.pipe(
Schema.decodeTo(Schema.String, {
decode: SchemaGetter.passthrough(),
encode: SchemaGetter.passthrough()
})
)
passthrough(),
encode: SchemaGetter.Getter<
NoInfer<{
readonly [x: string]: PrimitiveTree
}>,
NoInfer<{ readonly [x: string]: unknown }>,
never
>
(property) encode: {
run: (input: Option.Option<E>, options: SchemaAST.ParseOptions) => Effect.Effect<Option.Option<T>, SchemaIssue.Issue, R>;
map: (f: (t: NoInfer<{ readonly [x: string]: PrimitiveTree }>) => T2) => SchemaGetter.Getter<T2, NoInfer<{ readonly [x: string]: unknown }>, never>;
compose: (other: SchemaGetter.Getter<T2, NoInfer<{ readonly [x: string]: PrimitiveTree }>, R2>) => SchemaGetter.Getter<T2, NoInfer<{ readonly [x: string]: unknown }>, R2>;
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; <…;
}
import SchemaGetterSchemaGetter.function transformOptional<T, E>(
f: (oe: Option.Option<E>) => Option.Option<T>
): Getter<T, E>
Creates a getter that transforms the full Option — both present and absent values.
When to use
Use when you need a schema getter to handle both Some and None cases.
Details
The getter is pure and never fails. It receives the full Option<E> and
must return Option<T>, so it can turn a present value into absent or an
absent value into present.
Example (Filtering out empty strings)
import { Option, SchemaGetter } from "effect"
const skipEmpty = SchemaGetter.transformOptional<string, string>((o) =>
Option.filter(o, (s) => s.length > 0)
)
transformOptional(import OptionOption.const flatMap: {
<A, B>(f: (a: A) => Option<B>): (
self: Option<A>
) => Option<B>
<A, B>(
self: Option<A>,
f: (a: A) => Option<B>
): Option<B>
}
r: NoInfer<{
readonly [x: string]: unknown
}>
const out: Record<
string,
(typeof $PrimitiveTree)["Type"]
>
type Record<K extends keyof any, T> = {
[P in K]: T
}
Construct a type with a set of properties K of type T
Record<string, typeof const $PrimitiveTree: Schema.Codec<PrimitiveTree>const $PrimitiveTree: {
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
Rebuild: Codec<T, E, RD, RE>;
Type: T;
Iso: Iso;
ast: Ast;
annotate: (annotations: Schema.Annotations.Bottom<PrimitiveTree, any>) => Schema.Codec<PrimitiveTree, PrimitiveTree, never, never>;
annotateKey: (annotations: Schema.Annotations.Key<PrimitiveTree>) => Schema.Codec<PrimitiveTree, PrimitiveTree, never, never>;
check: (checks_0: SchemaAST.Check<PrimitiveTree>, ...checks: Array<SchemaAST.Check<PrimitiveTree>>) => Schema.Codec<PrimitiveTree, PrimitiveTree, never, never>;
rebuild: (ast: SchemaAST.AST) => Schema.Codec<PrimitiveTree, PrimitiveTree, never, never>;
make: (input: unknown, options?: MakeOptions) => SchemaRepresentation.PrimitiveTree;
makeOption: (input: unknown, options?: MakeOptions) => Option_.Option<SchemaRepresentation.PrimitiveTree>;
makeEffect: (input: unknown, options?: MakeOptions) => Effect.Effect<SchemaRepresentation.PrimitiveTree, SchemaError, never>;
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; <…;
}
Schema for
PrimitiveTree
.
When to use
Use to validate recursive annotation metadata trees whose leaves are null,
number, boolean, bigint, symbol, or string.
$PrimitiveTree["Type"]> = {}
for (const [const k: stringk, const v: unknownv] of var Object: ObjectConstructorProvides functionality common to all JavaScript objects.
Object.ObjectConstructor.entries<unknown>(o: {
[s: string]: unknown;
} | ArrayLike<unknown>): [string, unknown][] (+1 overload)
Returns an array of key/values of the enumerable own properties of an object
entries(r: {
readonly [x: string]: unknown
}
const toJsonAnnotationsBlacklist: Set<string>toJsonAnnotationsBlacklist.Set<string>.has(value: string): booleanhas(const k: stringk) && const isPrimitiveTree: <unknown>(
input: unknown
) => input is I & S["Type"]
const v: unknownv)) {
const out: Record<
string,
(typeof $PrimitiveTree)["Type"]
>
const k: stringk] = const v: PrimitiveTreev
}
}
return import RecRec.const isEmptyRecord: <
string,
PrimitiveTree
>(
self: Record<string, PrimitiveTree>
) => self is Record<string, never>
Determines if a mutable record is empty.
Example (Checking for an empty record)
import { Record } from "effect"
import * as assert from "node:assert"
assert.deepStrictEqual(Record.isEmptyRecord({}), true)
assert.deepStrictEqual(Record.isEmptyRecord({ a: 3 }), false)
isEmptyRecord(const out: Record<
string,
(typeof $PrimitiveTree)["Type"]
>
import OptionOption.const none: <A = never>() => Option<A>Creates an Option representing the absence of a value.
When to use
Use to represent a missing or uninitialized value, such as returning "no
result" from a function.
Details
- Returns
Option<never>, which is a subtype of Option<A> for any A
- Always returns the same singleton instance
Example (Creating an empty Option)
import { Option } from "effect"
// ┌─── Option<never>
// ▼
const noValue = Option.none()
console.log(noValue)
// Output: { _id: 'Option', _tag: 'None' }
none() : 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(const out: Record<
string,
(typeof $PrimitiveTree)["Type"]
>
Bottom<unknown, unknown, unknown, unknown, Objects, decodeTo<$Record<String, Unknown>, $Record<String, Codec<PrimitiveTree, PrimitiveTree, never, never>>, never, never>, ... 8 more ..., "required">.annotate(annotations: Schema.Annotations.Bottom<{
readonly [x: string]: unknown;
}, readonly []>): Schema.decodeTo<Schema.$Record<Schema.String, Schema.Unknown>, Schema.$Record<Schema.String, Schema.Codec<PrimitiveTree, PrimitiveTree, never, never>>, never, never>
Annotations.Bottom<T, TypeParameters extends ReadonlyArray<Constraint>>.identifier?: string | undefinedStable identifier for this schema node.
Details
Identifiers are used by schema tooling, including JSON Schema
generation, to name references. The default formatter also uses
identifier as the expected label for type-level failures, such as
Expected UserId, got null.
identifier does not name a failed filter or refinement. If the base
type matches and a filter fails, put expected or message on the
filter/refinement instead.
identifier: "Annotations" })