Skip to content
Effect V4 Docs

Schema.ts

Schema.ts overview

Section titled “Schema.ts overview”

Exports Grouped by Category

Section titled “Exports Grouped by Category”

Arbitrary

Section titled “Arbitrary”

LazyArbitrary (type alias)

Section titled “LazyArbitrary (type alias)”

A thunk that, given the fast-check module, returns an Arbitrary<T>. Use this type when you need to defer instantiation of the arbitrary, for example to support recursive schemas.

Signature

type LazyArbitrary<T> = (fc: typeof FastCheck) => FastCheck.Arbitrary<T>

Source

Since v4.0.0

toArbitrary

Section titled “toArbitrary”

Derives a fast-check Arbitrary from a schema for property-based testing. The derived arbitrary generates values that satisfy the schema.

Details

Constraints refine base generators; candidates add weighted sources while filters still validate every value. { report: true } returns warnings such as OpaqueFilter, while derivation errors remain fail-fast. Recursive schemas use terminal branches and fail when no finite terminal path exists.

Example (Generating arbitrary values)

import { Schema } from "effect"
import * as FastCheck from "fast-check"


const PersonArb = Schema.toArbitrary(Schema.Struct({ name: Schema.String, age: Schema.Number }))


// Sample a random value
const sample = FastCheck.sample(PersonArb, 1)[0]
console.log(typeof sample.name) // "string"

Signature

declare const toArbitrary: {
  <S extends Constraint>(schema: S): FastCheck.Arbitrary<S["Type"]>
  <S extends Constraint>(
    schema: S,
    options: { readonly report: true }
  ): Annotations.ToArbitrary.WithReport<FastCheck.Arbitrary<S["Type"]>>
}

Source

Since v4.0.0

toArbitraryLazy

Section titled “toArbitraryLazy”

Derives a LazyArbitrary from a schema. The result is memoized so repeated calls with the same schema are cheap.

Details

Prefer toArbitrary when you need the arbitrary directly, or when you want derivation diagnostics via { report: true }. Unsupported schema nodes, impossible constraints, invalid candidates, and recursive schemas without a finite terminal path fail immediately.

Signature

declare const toArbitraryLazy: <S extends Constraint>(schema: S) => LazyArbitrary<S["Type"]>

Source

Since v4.0.0

Array checks

Section titled “Array checks”

isUnique

Section titled “isUnique”

Validates that all items in an array are unique according to Effect equality.

Details

JSON Schema: This check corresponds to the uniqueItems: true constraint in JSON Schema.

Arbitrary: When generating test data with fast-check, this applies a node-local unique: true constraint. Array generators translate it to fast-check uniqueArray using Effect equality.

Signature

declare const isUnique: <T>(annotations?: Annotations.Filter) => SchemaAST.Filter<ReadonlyArray<T>>

Source

Since v4.0.0

BigDecimal

Section titled “BigDecimal”

BigDecimal

Section titled “BigDecimal”

Schema for BigDecimal values.

When to use

Use when you already have Effect decimal instances and need schema validation, formatting, equivalence, and JSON string serialization.

Details

Default JSON serializer:

  • encodes BigDecimal as a string

See

  • BigDecimalFromString for parsing string input into a BigDecimal

Signature

declare const BigDecimal: BigDecimal

Source

Since v3.10.0

BigDecimal (interface)

Section titled “BigDecimal (interface)”

Type-level representation of BigDecimal.

Signature

export interface BigDecimal extends declare<BigDecimal_.BigDecimal> {
  readonly Rebuild: BigDecimal
}

Source

Since v3.10.0

BigDecimalFromString

Section titled “BigDecimalFromString”

Schema that parses a string into a BigDecimal.

When to use

Use to parse decimal or exponent-notation strings into arbitrary-precision BigDecimal values while encoding them back to strings.

Details

Decoding:

  • A string is decoded with BigDecimal.fromString.

Encoding:

  • A BigDecimal is encoded with BigDecimal.format.

Gotchas

An empty string decodes as zero.

See

  • BigDecimal for validating values that are already BigDecimal values
  • BigIntFromString for parsing base-10 integer strings into bigint values
  • NumberFromString for parsing JavaScript number strings

Signature

declare const BigDecimalFromString: BigDecimalFromString

Source

Since v4.0.0

BigDecimalFromString (interface)

Section titled “BigDecimalFromString (interface)”

Type-level representation of BigDecimalFromString.

Signature

export interface BigDecimalFromString extends decodeTo<BigDecimal, String> {
  readonly Rebuild: BigDecimalFromString
}

Source

Since v4.0.0

BigDecimal checks

Section titled “BigDecimal checks”

isBetweenBigDecimal

Section titled “isBetweenBigDecimal”

Validates that a BigDecimal is within a specified range.

Details

The minimum and maximum boundaries are inclusive by default. Pass exclusiveMinimum or exclusiveMaximum to exclude either boundary.

Signature

declare const isBetweenBigDecimal: (
  options: {
    readonly minimum: BigDecimal_.BigDecimal
    readonly maximum: BigDecimal_.BigDecimal
    readonly exclusiveMinimum?: boolean | undefined
    readonly exclusiveMaximum?: boolean | undefined
  },
  annotations?: Annotations.Filter
) => SchemaAST.Filter<BigDecimal_.BigDecimal>

Source

Since v4.0.0

isGreaterThanBigDecimal

Section titled “isGreaterThanBigDecimal”

Validates that a BigDecimal is greater than the specified value (exclusive).

Signature

declare const isGreaterThanBigDecimal: (
  exclusiveMinimum: BigDecimal_.BigDecimal,
  annotations?: Annotations.Filter
) => SchemaAST.Filter<BigDecimal_.BigDecimal>

Source

Since v4.0.0

isGreaterThanOrEqualToBigDecimal

Section titled “isGreaterThanOrEqualToBigDecimal”

Validates that a BigDecimal is greater than or equal to the specified value (inclusive).

Signature

declare const isGreaterThanOrEqualToBigDecimal: (
  minimum: BigDecimal_.BigDecimal,
  annotations?: Annotations.Filter
) => SchemaAST.Filter<BigDecimal_.BigDecimal>

Source

Since v4.0.0

isLessThanBigDecimal

Section titled “isLessThanBigDecimal”

Validates that a BigDecimal is less than the specified value (exclusive).

Signature

declare const isLessThanBigDecimal: (
  exclusiveMaximum: BigDecimal_.BigDecimal,
  annotations?: Annotations.Filter
) => SchemaAST.Filter<BigDecimal_.BigDecimal>

Source

Since v4.0.0

isLessThanOrEqualToBigDecimal

Section titled “isLessThanOrEqualToBigDecimal”

Validates that a BigDecimal is less than or equal to the specified value (inclusive).

Signature

declare const isLessThanOrEqualToBigDecimal: (
  maximum: BigDecimal_.BigDecimal,
  annotations?: Annotations.Filter
) => SchemaAST.Filter<BigDecimal_.BigDecimal>

Source

Since v4.0.0

BigInt

Section titled “BigInt”

BigIntFromString

Section titled “BigIntFromString”

Schema that parses a string into a bigint.

When to use

Use to parse signed base-10 integer strings into bigint values while encoding bigint values back to decimal strings.

Details

Decoding:

  • A string is decoded as a bigint.

Encoding:

  • A bigint is encoded as a string.

Gotchas

Decoding accepts only strings matching ^-?\d+$.

See

  • isStringBigInt for the string predicate used by this schema
  • BigInt for validating values that are already bigint values
  • NumberFromString for parsing JavaScript number strings, including non-finite values
  • BigDecimalFromString for parsing decimal number strings

Signature

declare const BigIntFromString: BigIntFromString

Source

Since v4.0.0

BigIntFromString (interface)

Section titled “BigIntFromString (interface)”

Type-level representation of BigIntFromString.

Signature

export interface BigIntFromString extends decodeTo<BigInt, String> {
  readonly Rebuild: BigIntFromString
}

Source

Since v4.0.0

BigInt checks

Section titled “BigInt checks”

isBetweenBigInt

Section titled “isBetweenBigInt”

Validates that a BigInt is within a specified range. The range boundaries can be inclusive or exclusive based on the provided options.

Details

Arbitrary:

When generating test data with fast-check, this applies min and max constraints to ensure generated BigInt values fall within the specified range.

Signature

declare const isBetweenBigInt: (
  options: {
    readonly minimum: bigint
    readonly maximum: bigint
    readonly exclusiveMinimum?: boolean | undefined
    readonly exclusiveMaximum?: boolean | undefined
  },
  annotations?: Annotations.Filter
) => SchemaAST.Filter<bigint>

Source

Since v4.0.0

isGreaterThanBigInt

Section titled “isGreaterThanBigInt”

Validates that a BigInt is greater than the specified value (exclusive).

Details

Arbitrary:

When generating test data with fast-check, this applies a min constraint of exclusiveMinimum + 1n to ensure generated BigInts are greater than the specified value.

Signature

declare const isGreaterThanBigInt: (
  exclusiveMinimum: bigint,
  annotations?: Annotations.Filter
) => SchemaAST.Filter<bigint>

Source

Since v4.0.0

isGreaterThanOrEqualToBigInt

Section titled “isGreaterThanOrEqualToBigInt”

Validates that a BigInt is greater than or equal to the specified value (inclusive).

Details

Arbitrary:

When generating test data with fast-check, this applies a min constraint to ensure generated BigInt values are greater than or equal to the specified value.

Signature

declare const isGreaterThanOrEqualToBigInt: (
  minimum: bigint,
  annotations?: Annotations.Filter
) => SchemaAST.Filter<bigint>

Source

Since v4.0.0

isLessThanBigInt

Section titled “isLessThanBigInt”

Validates that a BigInt is less than the specified value (exclusive).

Details

Arbitrary:

When generating test data with fast-check, this applies a max constraint of exclusiveMaximum - 1n to ensure generated BigInts are less than the specified value.

Signature

declare const isLessThanBigInt: (exclusiveMaximum: bigint, annotations?: Annotations.Filter) => SchemaAST.Filter<bigint>

Source

Since v4.0.0

isLessThanOrEqualToBigInt

Section titled “isLessThanOrEqualToBigInt”

Validates that a BigInt is less than or equal to the specified value (inclusive).

Details

Arbitrary:

When generating test data with fast-check, this applies a max constraint to ensure generated BigInt values are less than or equal to the specified value.

Signature

declare const isLessThanOrEqualToBigInt: (maximum: bigint, annotations?: Annotations.Filter) => SchemaAST.Filter<bigint>

Source

Since v4.0.0

Canonical Codecs

Section titled “Canonical Codecs”

StringTree (type alias)

Section titled “StringTree (type alias)”

A Tree of string | undefined nodes. Leaf values are either a string representation or undefined for opaque/declaration types.

Signature

type StringTree = Tree<string | undefined>

Source

Since v4.0.0

toCodecArrayFromSingle

Section titled “toCodecArrayFromSingle”

Allows array schemas to decode from either an array input or a single value input.

When to use

Use when you need to accept transport formats that may represent a single-item array as a bare value, such as query-string or form-data adapters.

Gotchas

This combinator is intentionally not part of toCodecStringTree; it adds a decoding convenience rather than a canonical StringTree representation. It does not parse comma-separated strings.

Signature

declare const toCodecArrayFromSingle: <S extends Constraint>(schema: S) => toCodecArrayFromSingle<S>

Source

Since v4.0.0

toCodecArrayFromSingle (interface)

Section titled “toCodecArrayFromSingle (interface)”

Type-level representation returned by toCodecArrayFromSingle.

Signature

export interface toCodecArrayFromSingle<S extends Constraint> extends BottomLazy<
  S["ast"],
  toCodecArrayFromSingle<S>,
  S["~type.parameters"],
  S["~type.mutability"],
  S["~type.optionality"],
  S["~type.constructor.default"],
  S["~encoded.mutability"],
  S["~encoded.optionality"]
> {
  readonly Type: S["Type"]
  readonly Encoded: S["Encoded"]
  readonly DecodingServices: S["DecodingServices"]
  readonly EncodingServices: S["EncodingServices"]
  readonly "~type.make.in": S["~type.make.in"]
  readonly "~type.make": S["~type.make"]
  readonly Iso: S["Iso"]
}

Source

Since v4.0.0

toCodecIso

Section titled “toCodecIso”

Derives an isomorphism codec from a schema. The encoded form is the schema’s Iso type — the intermediate representation used for round-tripping.

Signature

declare const toCodecIso: <S extends Constraint>(schema: S) => Codec<S["Type"], S["Iso"]>

Source

Since v4.0.0

toCodecJson

Section titled “toCodecJson”

Derives a canonical JSON codec from a schema. The encoded form is Json, and decoding produces the schema’s Type.

Signature

declare const toCodecJson: <S extends Constraint>(schema: S) => toCodecJson<S>

Source

Since v4.0.0

toCodecJson (interface)

Section titled “toCodecJson (interface)”

Type-level representation returned by toCodecJson.

Signature

export interface toCodecJson<S extends Constraint> extends BottomLazy<
  S["ast"],
  toCodecJson<S>,
  S["~type.parameters"],
  S["~type.mutability"],
  S["~type.optionality"],
  S["~type.constructor.default"],
  S["~encoded.mutability"],
  S["~encoded.optionality"]
> {
  readonly Type: S["Type"]
  readonly Encoded: Json
  readonly DecodingServices: S["DecodingServices"]
  readonly EncodingServices: S["EncodingServices"]
  readonly "~type.make.in": S["~type.make.in"]
  readonly "~type.make": S["~type.make"]
  readonly Iso: S["Iso"]
  readonly schema: S
}

Source

Since v4.0.0

toCodecStringTree

Section titled “toCodecStringTree”

Converts a schema to the StringTree canonical codec, where every leaf value becomes a string while preserving the original structure.

Details

Declarations are converted to undefined (unless they have a toCodecJson or toCodec annotation).

Signature

declare const toCodecStringTree: <S extends Constraint>(schema: S) => toCodecStringTree<S>

Source

Since v4.0.0

toCodecStringTree (interface)

Section titled “toCodecStringTree (interface)”

Type-level representation returned by toCodecStringTree.

Signature

export interface toCodecStringTree<S extends Constraint> extends BottomLazy<
  S["ast"],
  toCodecStringTree<S>,
  ReadonlyArray<Constraint>,
  S["~type.mutability"],
  S["~type.optionality"],
  S["~type.constructor.default"],
  S["~encoded.mutability"],
  S["~encoded.optionality"]
> {
  readonly Type: S["Type"]
  readonly Encoded: StringTree
  readonly DecodingServices: S["DecodingServices"]
  readonly EncodingServices: S["EncodingServices"]
  readonly "~type.make.in": S["~type.make.in"]
  readonly "~type.make": S["~type.make"]
  readonly Iso: S["Iso"]
  readonly schema: S
}

Source

Since v4.0.0

toEncoderXml

Section titled “toEncoderXml”

Derives an XML encoder from a codec.

Details

The returned function encodes a value through toCodecStringTree and returns an Effect that succeeds with the XML string or fails with SchemaError if codec encoding fails.

Signature

declare const toEncoderXml: <T, E, RD, RE>(
  codec: Codec<T, E, RD, RE>,
  options?: XmlEncoderOptions
) => (t: T) => Effect.Effect<string, SchemaError, RE>

Source

Since v4.0.0

Cause

Section titled “Cause”

Cause

Section titled “Cause”

Creates a schema for Cause values using separate schemas for typed failures and unexpected defects.

When to use

Use to validate, transform, or serialize Effect failure causes when typed failures and unexpected defects need separate schemas.

Details

The error schema is applied to Fail reasons and the defect schema is applied to Die reasons. Interrupt reasons do not use either schema and carry only an optional fiber id.

See

  • CauseReason for the schema used by each individual cause reason
  • CauseIso for the ordered array representation used by the schema ISO

Signature

declare const Cause: <E extends Constraint, D extends Constraint>(error: E, defect: D) => Cause<E, D>

Source

Since v3.10.0

Cause (interface)

Section titled “Cause (interface)”

Type-level representation returned by Cause.

Signature

export interface Cause<E extends Constraint, D extends Constraint> extends declareConstructor<
  Cause_.Cause<E["Type"]>,
  Cause_.Cause<E["Encoded"]>,
  readonly [E, D],
  CauseIso<E, D>
> {
  readonly Rebuild: Cause<E, D>
  readonly error: E
  readonly defect: D
}

Source

Since v3.10.0

CauseIso (type alias)

Section titled “CauseIso (type alias)”

Iso representation used for Cause schemas: an ordered array of CauseReasonIso values.

When to use

Use when working with the ISO shape of a Cause schema, such as toIso optics or codecs that expose a cause as its ordered array of encoded reasons.

See

  • Cause for constructing schemas for full Cause values
  • CauseReasonIso for the ISO shape of each array element

Signature

type CauseIso<E, D> = ReadonlyArray<CauseReasonIso<E, D>>

Source

Since v4.0.0

CauseReason

Section titled “CauseReason”

CauseReason

Section titled “CauseReason”

Creates a schema for Cause.Reason values using separate schemas for typed failures and unexpected defects.

When to use

Use when serializing or decoding individual cause reasons separately from a full failure cause, with distinct schemas for typed errors and defects.

Details

Fail reasons use the error schema, Die reasons use the defect schema, and Interrupt reasons carry only an optional fiber id.

See

  • Cause for constructing schemas for full Cause values
  • CauseReasonIso for the ISO shape of each cause reason

Signature

declare const CauseReason: <E extends Constraint, D extends Constraint>(error: E, defect: D) => CauseReason<E, D>

Source

Since v4.0.0

CauseReason (interface)

Section titled “CauseReason (interface)”

Type-level representation returned by CauseReason.

Signature

export interface CauseReason<E extends Constraint, D extends Constraint> extends declareConstructor<
  Cause_.Reason<E["Type"]>,
  Cause_.Reason<E["Encoded"]>,
  readonly [E, D],
  CauseReasonIso<E, D>
> {
  readonly Rebuild: CauseReason<E, D>
  readonly error: E
  readonly defect: D
}

Source

Since v4.0.0

CauseReasonIso (type alias)

Section titled “CauseReasonIso (type alias)”

Iso representation used for CauseReason schemas.

Details

Failures are represented with a Fail tag and encoded error, defects with a Die tag and encoded defect, and interrupts with an optional fiberId.

Signature

type CauseReasonIso<E, D> =
  | {
      readonly _tag: "Fail"
      readonly error: E["Iso"]
    }
  | {
      readonly _tag: "Die"
      readonly error: D["Iso"]
    }
  | {
      readonly _tag: "Interrupt"
      readonly fiberId: number | undefined
    }

Source

Since v4.0.0

Chunk

Section titled “Chunk”

Chunk

Section titled “Chunk”

Schema for chunks whose values conform to the provided element schema.

Signature

declare const Chunk: <Value extends Constraint>(value: Value) => Chunk<Value>

Source

Since v3.10.0

Chunk (interface)

Section titled “Chunk (interface)”

Type-level representation returned by Chunk.

Signature

export interface Chunk<Value extends Constraint> extends declareConstructor<
  Chunk_.Chunk<Value["Type"]>,
  Chunk_.Chunk<Value["Encoded"]>,
  readonly [Value],
  ChunkIso<Value>
> {
  readonly Rebuild: Chunk<Value>
  readonly value: Value
}

Source

Since v3.10.0

ChunkIso (type alias)

Section titled “ChunkIso (type alias)”

Iso representation used for Chunk schemas: an array of element values using the element schema’s Iso type.

When to use

Use when annotating type-level helpers that work with the readonly-array ISO shape of a Chunk schema.

See

  • Chunk for the schema interface and constructor that use this ISO representation

Signature

type ChunkIso<Value> = ReadonlyArray<Value["Iso"]>

Source

Since v4.0.0

Date

Section titled “Date”

Date

Section titled “Date”

Schema for JavaScript Date objects.

When to use

Use to validate in-memory values that must already be JavaScript date objects.

Details

This schema accepts any Date instance, including invalid dates. The default JSON serializer encodes valid dates as ISO 8601 strings; invalid dates encode as "Invalid Date".

Example (Defining a Date schema)

import { Schema } from "effect"


Schema.decodeUnknownSync(Schema.Date)(new Date("2024-01-01"))
// => Date { 2024-01-01T00:00:00.000Z }

See

  • DateValid for accepting only valid Date instances

Signature

declare const Date: Date

Source

Since v4.0.0

Date (interface)

Section titled “Date (interface)”

Type-level representation of Date.

Signature

export interface Date extends instanceOf<globalThis.Date> {
  readonly Rebuild: Date
}

Source

Since v4.0.0

DateFromString

Section titled “DateFromString”

Schema that decodes a string into a JavaScript Date.

When to use

Use to model string-encoded dates that decode to JavaScript Date objects and encode back to strings.

Details

Decoding: The string is passed to JavaScript Date construction.

Encoding: A valid Date is encoded as an ISO string; an invalid Date is encoded as "Invalid Date".

Gotchas

Invalid date strings can decode to invalid Date instances.

See

  • Date for accepting Date instances directly
  • DateValid for rejecting invalid Date instances

Signature

declare const DateFromString: DateFromString

Source

Since v3.10.0

DateFromString (interface)

Section titled “DateFromString (interface)”

Type-level representation of DateFromString.

Signature

export interface DateFromString extends decodeTo<Date, String> {
  readonly Rebuild: DateFromString
}

Source

Since v3.10.0

DateValid

Section titled “DateValid”

Schema for valid JavaScript Date objects.

Details

This schema accepts Date instances but rejects invalid dates (such as new Date("invalid")).

Signature

declare const DateValid: DateValid

Source

Since v4.0.0

DateValid (interface)

Section titled “DateValid (interface)”

Type-level representation of DateValid.

Signature

export interface DateValid extends Date {
  readonly Rebuild: DateValid
}

Source

Since v4.0.0

Date checks

Section titled “Date checks”

isBetweenDate

Section titled “isBetweenDate”

Validates that a Date is within a specified range. The range boundaries can be inclusive or exclusive based on the provided options.

Details

JSON Schema:

This check does not have a direct JSON Schema equivalent, as JSON Schema validates date strings, not Date objects.

Arbitrary:

When generating test data with fast-check, this applies min and max constraints to ensure generated Date objects fall within the specified range, shifting exclusive bounds by one millisecond.

Signature

declare const isBetweenDate: (
  options: {
    readonly minimum: globalThis.Date
    readonly maximum: globalThis.Date
    readonly exclusiveMinimum?: boolean | undefined
    readonly exclusiveMaximum?: boolean | undefined
  },
  annotations?: Annotations.Filter
) => SchemaAST.Filter<globalThis.Date>

Source

Since v4.0.0

isDateValid

Section titled “isDateValid”

Validates that a Date object represents a valid date (not an invalid date like new Date("invalid")).

Details

JSON Schema:

This check does not have a direct JSON Schema equivalent, as JSON Schema validates date strings, not Date objects.

Arbitrary:

When generating test data with fast-check, this applies a valid: true constraint to ensure generated Date objects are valid.

Signature

declare const isDateValid: (annotations?: Annotations.Filter) => SchemaAST.Filter<globalThis.Date>

Source

Since v4.0.0

isGreaterThanDate

Section titled “isGreaterThanDate”

Validates that a Date is greater than the specified value (exclusive).

Details

Arbitrary:

When generating test data with fast-check, this applies a min constraint of one millisecond after the specified value to ensure generated Date objects are greater than it.

Signature

declare const isGreaterThanDate: (
  exclusiveMinimum: globalThis.Date,
  annotations?: Annotations.Filter
) => SchemaAST.Filter<globalThis.Date>

Source

Since v4.0.0

isGreaterThanOrEqualToDate

Section titled “isGreaterThanOrEqualToDate”

Validates that a Date is greater than or equal to the specified date (inclusive).

Details

JSON Schema:

This check does not have a direct JSON Schema equivalent, as JSON Schema validates date strings, not Date objects.

Arbitrary:

When generating test data with fast-check, this applies a min constraint to ensure generated Date objects are greater than or equal to the specified date.

Signature

declare const isGreaterThanOrEqualToDate: (
  minimum: globalThis.Date,
  annotations?: Annotations.Filter
) => SchemaAST.Filter<globalThis.Date>

Source

Since v4.0.0

isLessThanDate

Section titled “isLessThanDate”

Validates that a Date is less than the specified value (exclusive).

Details

Arbitrary:

When generating test data with fast-check, this applies a max constraint of one millisecond before the specified value to ensure generated Date objects are less than it.

Signature

declare const isLessThanDate: (
  exclusiveMaximum: globalThis.Date,
  annotations?: Annotations.Filter
) => SchemaAST.Filter<globalThis.Date>

Source

Since v4.0.0

isLessThanOrEqualToDate

Section titled “isLessThanOrEqualToDate”

Validates that a Date is less than or equal to the specified date (inclusive).

Details

JSON Schema:

This check does not have a direct JSON Schema equivalent, as JSON Schema validates date strings, not Date objects.

Arbitrary:

When generating test data with fast-check, this applies a max constraint to ensure generated Date objects are less than or equal to the specified date.

Signature

declare const isLessThanOrEqualToDate: (
  maximum: globalThis.Date,
  annotations?: Annotations.Filter
) => SchemaAST.Filter<globalThis.Date>

Source

Since v4.0.0

DateTime

Section titled “DateTime”

DateTimeUtc

Section titled “DateTimeUtc”

Schema for DateTime.Utc values.

When to use

Use to validate existing DateTime.Utc schema values and use the default JSON codec that represents them as UTC ISO strings.

Details

The default JSON codec decodes UTC ISO strings into DateTime.Utc values and encodes DateTime.Utc values as UTC ISO strings.

See

  • DateTimeUtcFromString for decoding date-time strings into UTC values
  • DateTimeUtcFromDate for decoding JavaScript Date values into UTC values
  • DateTimeUtcFromMillis for decoding epoch milliseconds into UTC values
  • DateTimeZoned for preserving zoned DateTime values

Signature

declare const DateTimeUtc: DateTimeUtc

Source

Since v3.10.0

DateTimeUtc (interface)

Section titled “DateTimeUtc (interface)”

Type-level representation of DateTimeUtc.

Signature

export interface DateTimeUtc extends declare<DateTime.Utc> {
  readonly Rebuild: DateTimeUtc
}

Source

Since v3.10.0

DateTimeUtcFromDate

Section titled “DateTimeUtcFromDate”

Schema that decodes a Date into a DateTime.Utc.

When to use

Use when you need to decode valid JavaScript Date objects into DateTime.Utc values.

Details

Decoding:

  • A valid Date is decoded as a DateTime.Utc

Encoding:

  • A DateTime.Utc is encoded as a Date

See

  • DateTimeUtc for validating values that are already DateTime.Utc
  • DateTimeUtcFromString for decoding date-time strings into UTC values
  • DateTimeUtcFromMillis for decoding epoch milliseconds into UTC values
  • DateValid for validating Date instances without converting them

Signature

declare const DateTimeUtcFromDate: DateTimeUtcFromDate

Source

Since v3.12.0

DateTimeUtcFromDate (interface)

Section titled “DateTimeUtcFromDate (interface)”

Type-level representation of DateTimeUtcFromDate.

Signature

export interface DateTimeUtcFromDate extends decodeTo<DateTimeUtc, Date> {
  readonly Rebuild: DateTimeUtcFromDate
}

Source

Since v3.12.0

DateTimeUtcFromMillis

Section titled “DateTimeUtcFromMillis”

Schema that decodes a number into a DateTime.Utc.

Details

Decoding:

  • A number of milliseconds since the Unix epoch is decoded as a DateTime.Utc

Encoding:

  • A DateTime.Utc is encoded as a number of milliseconds since the Unix epoch.

Signature

declare const DateTimeUtcFromMillis: DateTimeUtcFromMillis

Source

Since v4.0.0

DateTimeUtcFromMillis (interface)

Section titled “DateTimeUtcFromMillis (interface)”

Type-level representation of DateTimeUtcFromMillis.

Signature

export interface DateTimeUtcFromMillis extends decodeTo<instanceOf<DateTime.Utc>, Number> {
  readonly Rebuild: DateTimeUtcFromMillis
}

Source

Since v4.0.0

DateTimeUtcFromString

Section titled “DateTimeUtcFromString”

Schema that decodes a date-time string into a DateTime.Utc.

Details

Decoding:

  • A string accepted by DateTime.make is parsed and normalized to UTC. Strings without an explicit zone are interpreted as UTC.

Encoding:

  • A DateTime.Utc is encoded as a UTC ISO 8601 string.

Signature

declare const DateTimeUtcFromString: DateTimeUtcFromString

Source

Since v4.0.0

DateTimeUtcFromString (interface)

Section titled “DateTimeUtcFromString (interface)”

Type-level representation of DateTimeUtcFromString.

Signature

export interface DateTimeUtcFromString extends decodeTo<DateTimeUtc, String> {
  readonly Rebuild: DateTimeUtcFromString
}

Source

Since v4.0.0

DateTimeZoned

Section titled “DateTimeZoned”

Schema for DateTime.Zoned values.

Details

Default JSON serializer:

  • encodes offset zones as an ISO date-time with a numeric offset, such as YYYY-MM-DDTHH:mm:ss.sss+HH:MM
  • encodes named zones by appending the IANA identifier in brackets, such as YYYY-MM-DDTHH:mm:ss.sss+HH:MM[Time/Zone]

Signature

declare const DateTimeZoned: DateTimeZoned

Source

Since v3.10.0

DateTimeZoned (interface)

Section titled “DateTimeZoned (interface)”

Type-level representation of DateTimeZoned.

Signature

export interface DateTimeZoned extends declare<DateTime.Zoned> {
  readonly Rebuild: DateTimeZoned
}

Source

Since v3.10.0

DateTimeZonedFromString

Section titled “DateTimeZonedFromString”

Schema that parses a zoned DateTime string into a DateTime.Zoned.

Details

Decoding:

  • A string (e.g. 2024-01-01T00:00:00.000+00:00[Europe/London]) is decoded as a DateTime.Zoned.

Encoding:

  • A DateTime.Zoned is encoded as a string.

Signature

declare const DateTimeZonedFromString: DateTimeZonedFromString

Source

Since v4.0.0

DateTimeZonedFromString (interface)

Section titled “DateTimeZonedFromString (interface)”

Type-level representation of DateTimeZonedFromString.

Signature

export interface DateTimeZonedFromString extends decodeTo<DateTimeZoned, String> {
  readonly Rebuild: DateTimeZonedFromString
}

Source

Since v4.0.0

TimeZone

Section titled “TimeZone”

Schema for DateTime.TimeZone values.

Details

Default JSON serializer:

  • encodes DateTime.TimeZone as a string (IANA identifier or offset like +03:00)

Signature

declare const TimeZone: TimeZone

Source

Since v3.10.0

TimeZone (interface)

Section titled “TimeZone (interface)”

Type-level representation of TimeZone.

Signature

export interface TimeZone extends declare<DateTime.TimeZone> {
  readonly Rebuild: TimeZone
}

Source

Since v3.10.0

TimeZoneFromString

Section titled “TimeZoneFromString”

Schema that parses a time zone string into a DateTime.TimeZone.

Details

Decoding:

  • A string (IANA identifier or offset like +03:00) is decoded as a DateTime.TimeZone.

Encoding:

  • A DateTime.TimeZone is encoded as a string.

Signature

declare const TimeZoneFromString: TimeZoneFromString

Source

Since v4.0.0

TimeZoneFromString (interface)

Section titled “TimeZoneFromString (interface)”

Type-level representation of TimeZoneFromString.

Signature

export interface TimeZoneFromString extends decodeTo<TimeZone, String> {
  readonly Rebuild: TimeZoneFromString
}

Source

Since v4.0.0

TimeZoneNamed

Section titled “TimeZoneNamed”

Schema for DateTime.TimeZone.Named values.

Details

Default JSON serializer:

  • encodes DateTime.TimeZone.Named as a string (IANA time zone identifier)

Signature

declare const TimeZoneNamed: TimeZoneNamed

Source

Since v3.10.0

TimeZoneNamed (interface)

Section titled “TimeZoneNamed (interface)”

Type-level representation of TimeZoneNamed.

Signature

export interface TimeZoneNamed extends declare<DateTime.TimeZone.Named> {
  readonly Rebuild: TimeZoneNamed
}

Source

Since v3.10.0

TimeZoneNamedFromString

Section titled “TimeZoneNamedFromString”

Schema that parses an IANA time zone identifier string into a DateTime.TimeZone.Named.

Details

Decoding:

  • A string is decoded as a DateTime.TimeZone.Named.

Encoding:

  • A DateTime.TimeZone.Named is encoded as a string.

Signature

declare const TimeZoneNamedFromString: TimeZoneNamedFromString

Source

Since v4.0.0

TimeZoneNamedFromString (interface)

Section titled “TimeZoneNamedFromString (interface)”

Type-level representation of TimeZoneNamedFromString.

Signature

export interface TimeZoneNamedFromString extends decodeTo<TimeZoneNamed, String> {
  readonly Rebuild: TimeZoneNamedFromString
}

Source

Since v4.0.0

TimeZoneOffset

Section titled “TimeZoneOffset”

Schema for DateTime.TimeZone.Offset values.

Details

Default JSON serializer:

  • encodes DateTime.TimeZone.Offset as a number (offset in milliseconds)

Signature

declare const TimeZoneOffset: TimeZoneOffset

Source

Since v3.10.0

TimeZoneOffset (interface)

Section titled “TimeZoneOffset (interface)”

Type-level representation of TimeZoneOffset.

Signature

export interface TimeZoneOffset extends declare<DateTime.TimeZone.Offset> {
  readonly Rebuild: TimeZoneOffset
}

Source

Since v3.10.0

Defect

Section titled “Defect”

Defect (interface)

Section titled “Defect (interface)”

Type-level representation of Defect.

Signature

export interface Defect extends decodeTo<Unknown, typeof Json> {
  readonly Rebuild: Defect
}

Source

Since v3.10.0

Duration

Section titled “Duration”

Duration

Section titled “Duration”

Schema for Duration values.

Details

The default JSON serializer encodes Duration as a tagged object with the duration type and value.

Example (Defining a Duration schema)

import { Duration, Schema } from "effect"


Schema.decodeUnknownSync(Schema.Duration)(Duration.seconds(5))
// => Duration(5s)

Signature

declare const Duration: Duration

Source

Since v3.10.0

Duration (interface)

Section titled “Duration (interface)”

Type-level representation of Duration.

Signature

export interface Duration extends declare<Duration_.Duration> {
  readonly Rebuild: Duration
}

Source

Since v3.10.0

DurationFromMillis

Section titled “DurationFromMillis”

Schema that decodes a non-negative (possibly infinite) integer into a Duration, treating the integer value as the duration in milliseconds.

Details

Decoding:

  • A non-negative (possibly infinite) integer representing milliseconds is decoded as a Duration

Encoding:

  • A Duration is encoded to a non-negative (possibly infinite) integer representing milliseconds

Signature

declare const DurationFromMillis: DurationFromMillis

Source

Since v3.10.0

DurationFromMillis (interface)

Section titled “DurationFromMillis (interface)”

Type-level representation of DurationFromMillis.

Signature

export interface DurationFromMillis extends decodeTo<Duration, Number> {
  readonly Rebuild: DurationFromMillis
}

Source

Since v3.10.0

DurationFromNanos

Section titled “DurationFromNanos”

Schema that decodes a non-negative bigint into a Duration, treating the bigint as nanoseconds.

Details

Decoding: A non-negative bigint representing nanoseconds is decoded as a Duration.

Encoding: Finite durations are encoded as a non-negative bigint number of nanoseconds. Encoding fails when the duration cannot be represented as nanoseconds, such as Duration.infinity.

Signature

declare const DurationFromNanos: DurationFromNanos

Source

Since v3.10.0

DurationFromNanos (interface)

Section titled “DurationFromNanos (interface)”

Type-level representation of DurationFromNanos.

Signature

export interface DurationFromNanos extends decodeTo<Duration, BigInt> {
  readonly Rebuild: DurationFromNanos
}

Source

Since v3.10.0

DurationFromString

Section titled “DurationFromString”

Schema that parses a string into a Duration.

Details

Decoding:

  • A string is decoded as a Duration, accepting any format that Duration.fromInput can parse.

Encoding:

  • A Duration is encoded as a parseable string.

Signature

declare const DurationFromString: DurationFromString

Source

Since v4.0.0

DurationFromString (interface)

Section titled “DurationFromString (interface)”

Type-level representation of DurationFromString.

Signature

export interface DurationFromString extends decodeTo<Duration, String> {
  readonly Rebuild: DurationFromString
}

Source

Since v4.0.0

Error

Section titled “Error”

Error (interface)

Section titled “Error (interface)”

Type-level representation of Error.

Signature

export interface Error extends instanceOf<globalThis.Error> {
  readonly Rebuild: Error
}

Source

Since v4.0.0

Exit

Section titled “Exit”

Exit

Section titled “Exit”

Creates a schema for Exit values using schemas for the success value, typed failure, and unexpected defect channels.

When to use

Use when serializing or validating an effect outcome where success, typed failure, and defects each need their own schema.

Signature

declare const Exit: <A extends Constraint, E extends Constraint, D extends Constraint>(
  value: A,
  error: E,
  defect: D
) => Exit<A, E, D>

Source

Since v3.10.0

Exit (interface)

Section titled “Exit (interface)”

Type-level representation returned by Exit.

Signature

export interface Exit<A extends Constraint, E extends Constraint, D extends Constraint> extends declareConstructor<
  Exit_.Exit<A["Type"], E["Type"]>,
  Exit_.Exit<A["Encoded"], E["Encoded"]>,
  readonly [A, E, D],
  ExitIso<A, E, D>
> {
  readonly Rebuild: Exit<A, E, D>
  readonly value: A
  readonly error: E
  readonly defect: D
}

Source

Since v3.10.0

ExitIso (type alias)

Section titled “ExitIso (type alias)”

Iso representation used for Exit schemas.

Details

Successful exits are represented as { _tag: "Success", value }, while failed exits are represented as { _tag: "Failure", cause }.

Signature

type ExitIso<A, E, D> =
  | {
      readonly _tag: "Success"
      readonly value: A["Iso"]
    }
  | {
      readonly _tag: "Failure"
      readonly cause: CauseIso<E, D>
    }

Source

Since v4.0.0

FormData

Section titled “FormData”

FormData

Section titled “FormData”

Schema for JavaScript FormData objects.

Details

The default JSON serializer encodes a FormData as an array of [key, entry] pairs where each entry is tagged as "String" or "File".

Signature

declare const FormData: FormData

Source

Since v4.0.0

FormData (interface)

Section titled “FormData (interface)”

Type-level representation of FormData.

Signature

export interface FormData extends instanceOf<globalThis.FormData> {
  readonly Rebuild: FormData
}

Source

Since v4.0.0

fromFormData (interface)

Section titled “fromFormData (interface)”

Type-level representation returned by fromFormData.

Signature

export interface fromFormData<S extends Constraint> extends decodeTo<S, FormData> {
  readonly Rebuild: fromFormData<S>
}

Source

Since v4.0.0

Formatter

Section titled “Formatter”

overrideToFormatter

Section titled “overrideToFormatter”

Attaches a custom formatter used by toFormatter.

Details

Use this when the formatter derived from the schema structure is not suitable. The annotation is applied through this helper because adding it directly to Annotations.Bottom would make schemas invariant.

Signature

declare const overrideToFormatter: <S extends Top>(toFormatter: () => Formatter<S["Type"]>) => (self: S) => S["Rebuild"]

Source

Since v4.0.0

toFormatter

Section titled “toFormatter”

Derives a string formatter function from a schema. The formatter converts a value to its human-readable string representation, recursing into structs, arrays, and unions.

Details

The optional onBefore hook lets you intercept specific AST nodes before the default formatting logic runs.

Signature

declare const toFormatter: <S extends Constraint>(
  schema: S,
  options?: {
    readonly onBefore?:
      | ((ast: SchemaAST.AST, recur: (ast: SchemaAST.AST) => Formatter<any>) => Formatter<any> | undefined)
      | undefined
  }
) => Formatter<S["Type"]>

Source

Since v4.0.0

HashMap

Section titled “HashMap”

HashMap

Section titled “HashMap”

Schema for hash maps whose keys and values conform to the provided schemas.

Signature

declare const HashMap: <Key extends Constraint, Value extends Constraint>(key: Key, value: Value) => HashMap<Key, Value>

Source

Since v3.10.0

HashMap (interface)

Section titled “HashMap (interface)”

Type-level representation returned by HashMap.

Signature

export interface HashMap<Key extends Constraint, Value extends Constraint> extends declareConstructor<
  HashMap_.HashMap<Key["Type"], Value["Type"]>,
  HashMap_.HashMap<Key["Encoded"], Value["Encoded"]>,
  readonly [Key, Value],
  HashMapIso<Key, Value>
> {
  readonly Rebuild: HashMap<Key, Value>
  readonly key: Key
  readonly value: Value
}

Source

Since v3.10.0

HashMapIso (type alias)

Section titled “HashMapIso (type alias)”

Iso representation used for HashMap schemas: an array of readonly [key, value] tuples using each entry schema’s Iso type.

Signature

type HashMapIso<Key, Value> = ReadonlyArray<readonly [Key["Iso"], Value["Iso"]]>

Source

Since v4.0.0

HashSet

Section titled “HashSet”

HashSet

Section titled “HashSet”

Schema for hash sets whose values conform to the provided element schema.

Signature

declare const HashSet: <Value extends Constraint>(value: Value) => HashSet<Value>

Source

Since v3.10.0

HashSet (interface)

Section titled “HashSet (interface)”

Type-level representation returned by HashSet.

Signature

export interface HashSet<Value extends Constraint> extends declareConstructor<
  HashSet_.HashSet<Value["Type"]>,
  HashSet_.HashSet<Value["Encoded"]>,
  readonly [Value],
  HashSetIso<Value>
> {
  readonly Rebuild: HashSet<Value>
  readonly value: Value
}

Source

Since v3.10.0

HashSetIso (type alias)

Section titled “HashSetIso (type alias)”

Iso representation used for HashSet schemas: an array of element values using the element schema’s Iso type.

Signature

type HashSetIso<Value> = ReadonlyArray<Value["Iso"]>

Source

Since v4.0.0

Integer checks

Section titled “Integer checks”

isInt

Section titled “isInt”

Validates that a number is a safe integer (within the safe integer range that can be exactly represented in JavaScript).

Details

JSON Schema:

This check corresponds to the type: "integer" constraint in JSON Schema.

Arbitrary:

When generating test data with fast-check, this applies an integer: true constraint to ensure generated numbers are integers.

Signature

declare const isInt: (annotations?: Annotations.Filter) => SchemaAST.Filter<number>

Source

Since v4.0.0

isInt32

Section titled “isInt32”

Validates that a number is a 32-bit signed integer (range: -2,147,483,648 to 2,147,483,647).

Details

JSON Schema:

This check corresponds to the format: "int32" constraint in OpenAPI 3.1, or minimum/maximum constraints in other JSON Schema targets.

Arbitrary:

When generating test data with fast-check, this applies integer and range constraints to ensure generated numbers are 32-bit signed integers.

Signature

declare const isInt32: (annotations?: Annotations.Filter) => SchemaAST.FilterGroup<number>

Source

Since v4.0.0

isUint32

Section titled “isUint32”

Validates that a number is a 32-bit unsigned integer (range: 0 to 4,294,967,295).

Details

JSON Schema:

This check corresponds to the format: "uint32" constraint in OpenAPI 3.1, or minimum/maximum constraints in other JSON Schema targets.

Arbitrary:

When generating test data with fast-check, this applies integer and range constraints to ensure generated numbers are 32-bit unsigned integers.

Signature

declare const isUint32: (annotations?: Annotations.Filter) => SchemaAST.FilterGroup<number>

Source

Since v4.0.0

Length checks

Section titled “Length checks”

isLengthBetween

Section titled “isLengthBetween”

Validates that a value’s length is within the specified range. Works with strings and arrays.

Details

JSON Schema:

This check corresponds to minLength/maxLength constraints for strings or minItems/maxItems constraints for arrays in JSON Schema.

Arbitrary:

When generating test data with fast-check, this applies minLength and maxLength constraints to ensure generated strings or arrays have a length within the specified range.

Signature

declare const isLengthBetween: (
  minimum: number,
  maximum: number,
  annotations?: Annotations.Filter
) => SchemaAST.Filter<{ readonly length: number }>

Source

Since v4.0.0

isMaxLength

Section titled “isMaxLength”

Validates that a value has at most the specified length. Works with strings and arrays.

Details

JSON Schema:

This check corresponds to the maxLength constraint for strings or the maxItems constraint for arrays in JSON Schema.

Arbitrary:

When generating test data with fast-check, this applies a maxLength constraint to ensure generated strings or arrays have at most the required length.

Signature

declare const isMaxLength: (
  maxLength: number,
  annotations?: Annotations.Filter
) => SchemaAST.Filter<{ readonly length: number }>

Source

Since v4.0.0

isMinLength

Section titled “isMinLength”

Validates that a value has at least the specified length. Works with strings and arrays.

Details

JSON Schema:

This check corresponds to the minLength constraint for strings or the minItems constraint for arrays in JSON Schema.

Arbitrary:

When generating test data with fast-check, this applies a minLength constraint to ensure generated strings or arrays have at least the required length.

Example (Checking minimum length)

import { Schema } from "effect"


const NonEmptyStringSchema = Schema.String.check(Schema.isMinLength(1))
const NonEmptyArraySchema = Schema.Array(Schema.Number).check(Schema.isMinLength(1))

Signature

declare const isMinLength: (
  minLength: number,
  annotations?: Annotations.Filter
) => SchemaAST.Filter<{ readonly length: number }>

Source

Since v4.0.0

isNonEmpty

Section titled “isNonEmpty”

Validates that a value has at least one element. Works with strings and arrays. This is equivalent to isMinLength(1).

Details

JSON Schema:

This check corresponds to the minLength: 1 constraint for strings or the minItems: 1 constraint for arrays in JSON Schema.

Arbitrary:

When generating test data with fast-check, this applies a minLength: 1 constraint to ensure generated strings or arrays are non-empty.

Signature

declare const isNonEmpty: (annotations?: Annotations.Filter) => SchemaAST.Filter<{ readonly length: number }>

Source

Since v4.0.0

Number

Section titled “Number”

Finite

Section titled “Finite”

Schema for finite numbers, rejecting NaN, Infinity, and -Infinity.

Signature

declare const Finite: Finite

Source

Since v3.10.0

Finite (interface)

Section titled “Finite (interface)”

Type-level representation of Finite.

Signature

export interface Finite extends Number {
  readonly Rebuild: Finite
}

Source

Since v3.10.0

FiniteFromString

Section titled “FiniteFromString”

Schema that parses a string into a finite number.

Details

Decoding:

  • A string is decoded as a finite number, rejecting NaN, Infinity, and -Infinity values.

Encoding:

  • A finite number is encoded as a string.

Signature

declare const FiniteFromString: FiniteFromString

Source

Since v4.0.0

FiniteFromString (interface)

Section titled “FiniteFromString (interface)”

Type-level representation of FiniteFromString.

Signature

export interface FiniteFromString extends decodeTo<Finite, String> {
  readonly Rebuild: FiniteFromString
}

Source

Since v4.0.0

Int

Section titled “Int”

Schema for integers, rejecting NaN, Infinity, and -Infinity.

Signature

declare const Int: Int

Source

Since v3.10.0

Int (interface)

Section titled “Int (interface)”

Type-level representation of Int.

Signature

export interface Int extends Number {
  readonly Rebuild: Int
}

Source

Since v3.10.0

NumberFromString

Section titled “NumberFromString”

Schema that parses a string into a number using JavaScript number coercion.

Details

Decoding: A string is decoded as a number, including possible non-finite values such as NaN, Infinity, and -Infinity. Use FiniteFromString to reject non-finite numbers.

Encoding: A number is encoded as a string.

Signature

declare const NumberFromString: NumberFromString

Source

Since v3.10.0

NumberFromString (interface)

Section titled “NumberFromString (interface)”

Type-level representation of NumberFromString.

Signature

export interface NumberFromString extends decodeTo<Finite, String> {
  readonly Rebuild: NumberFromString
}

Source

Since v3.10.0

Number checks

Section titled “Number checks”

isBetween

Section titled “isBetween”

Validates that a number is within a specified range. The range boundaries can be inclusive or exclusive based on the provided options.

Details

JSON Schema:

This check corresponds to minimum/maximum or exclusiveMinimum/exclusiveMaximum constraints in JSON Schema, depending on the options provided.

Arbitrary:

When generating test data with fast-check, this applies minimum and maximum constraints with optional exclusiveMinimum and exclusiveMaximum flags to ensure generated numbers fall within the specified range.

Signature

declare const isBetween: (
  options: {
    readonly minimum: number
    readonly maximum: number
    readonly exclusiveMinimum?: boolean | undefined
    readonly exclusiveMaximum?: boolean | undefined
  },
  annotations?: Annotations.Filter
) => SchemaAST.Filter<number>

Source

Since v4.0.0

isFinite

Section titled “isFinite”

Validates that a number is finite (not Infinity, -Infinity, or NaN).

Details

JSON Schema:

This check does not have a direct JSON Schema equivalent, but ensures the number is valid and finite.

Arbitrary:

When generating test data with fast-check, this applies noNaN: true and noInfinity: true constraints to ensure generated numbers are finite.

Signature

declare const isFinite: (annotations?: Annotations.Filter) => SchemaAST.Filter<number>

Source

Since v4.0.0

isGreaterThan

Section titled “isGreaterThan”

Validates that a number is greater than the specified value (exclusive).

Details

JSON Schema:

This check corresponds to the exclusiveMinimum constraint in JSON Schema.

Arbitrary:

When generating test data with fast-check, this applies an exclusiveMinimum constraint to ensure generated numbers are greater than the specified value.

Signature

declare const isGreaterThan: (exclusiveMinimum: number, annotations?: Annotations.Filter) => SchemaAST.Filter<number>

Source

Since v4.0.0

isGreaterThanOrEqualTo

Section titled “isGreaterThanOrEqualTo”

Validates that a number is greater than or equal to the specified value (inclusive).

Details

JSON Schema:

This check corresponds to the minimum constraint in JSON Schema.

Arbitrary:

When generating test data with fast-check, this applies a minimum constraint to ensure generated numbers are greater than or equal to the specified value.

Signature

declare const isGreaterThanOrEqualTo: (minimum: number, annotations?: Annotations.Filter) => SchemaAST.Filter<number>

Source

Since v4.0.0

isLessThan

Section titled “isLessThan”

Validates that a number is less than the specified value (exclusive).

Details

JSON Schema:

This check corresponds to the exclusiveMaximum constraint in JSON Schema.

Arbitrary:

When generating test data with fast-check, this applies an exclusiveMaximum constraint to ensure generated numbers are less than the specified value.

Signature

declare const isLessThan: (exclusiveMaximum: number, annotations?: Annotations.Filter) => SchemaAST.Filter<number>

Source

Since v4.0.0

isLessThanOrEqualTo

Section titled “isLessThanOrEqualTo”

Validates that a number is less than or equal to the specified value (inclusive).

Details

JSON Schema:

This check corresponds to the maximum constraint in JSON Schema.

Arbitrary:

When generating test data with fast-check, this applies a maximum constraint to ensure generated numbers are less than or equal to the specified value.

Signature

declare const isLessThanOrEqualTo: (maximum: number, annotations?: Annotations.Filter) => SchemaAST.Filter<number>

Source

Since v4.0.0

isMultipleOf

Section titled “isMultipleOf”

Validates that a number is a multiple of the specified divisor.

Details

JSON Schema:

This check corresponds to the multipleOf constraint in JSON Schema.

Arbitrary:

When generating test data with fast-check, this applies constraints to ensure generated numbers are multiples of the specified divisor.

Signature

declare const isMultipleOf: (divisor: number, annotations?: Annotations.Filter) => SchemaAST.Filter<number>

Source

Since v4.0.0

Numeric checks

Section titled “Numeric checks”

makeIsMultipleOf

Section titled “makeIsMultipleOf”

Creates a divisibility check for any numeric type from a remainder function and a zero value.

Signature

declare const makeIsMultipleOf: <T>(options: {
  readonly remainder: (input: T, divisor: T) => T
  readonly zero: NoInfer<T>
  readonly annotate?: ((divisor: T) => Annotations.Filter) | undefined
  readonly formatter?: Formatter<T> | undefined
}) => (divisor: T, annotations?: Annotations.Filter) => SchemaAST.Filter<T>

Source

Since v4.0.0

Object checks

Section titled “Object checks”

isMaxProperties

Section titled “isMaxProperties”

Validates that an object contains at most the specified number of properties. This includes both string and symbol keys when counting properties.

Details

JSON Schema:

This check corresponds to the maxProperties constraint in JSON Schema.

Arbitrary:

When generating test data with fast-check, this applies a node-local maxLength constraint. Object generators interpret it as the final number of own properties.

Signature

declare const isMaxProperties: (maxProperties: number, annotations?: Annotations.Filter) => SchemaAST.Filter<object>

Source

Since v4.0.0

isMinProperties

Section titled “isMinProperties”

Validates that an object contains at least the specified number of properties. This includes both string and symbol keys when counting properties.

Details

JSON Schema:

This check corresponds to the minProperties constraint in JSON Schema.

Arbitrary:

When generating test data with fast-check, this applies a node-local minLength constraint. Object generators interpret it as the final number of own properties.

Signature

declare const isMinProperties: (minProperties: number, annotations?: Annotations.Filter) => SchemaAST.Filter<object>

Source

Since v4.0.0

isPropertiesLengthBetween

Section titled “isPropertiesLengthBetween”

Validates that an object contains between minimum and maximum properties (inclusive). This includes both string and symbol keys when counting properties.

Details

JSON Schema:

This check corresponds to minProperties and maxProperties constraints in JSON Schema.

Arbitrary:

When generating test data with fast-check, this applies node-local minLength and maxLength constraints. Object generators interpret them as the final number of own properties.

Signature

declare const isPropertiesLengthBetween: (
  minimum: number,
  maximum: number,
  annotations?: Annotations.Filter
) => SchemaAST.Filter<object>

Source

Since v4.0.0

isPropertyNames

Section titled “isPropertyNames”

Validates that every own property key of an object satisfies the encoded side of the provided key schema.

Details

This check uses Reflect.ownKeys, so symbol keys are validated in addition to string property names.

JSON Schema: For string property names, this corresponds to the propertyNames constraint in JSON Schema.

Signature

declare const isPropertyNames: (keySchema: Constraint, annotations?: Annotations.Filter) => SchemaAST.Filter<object>

Source

Since v4.0.0

Optic

Section titled “Optic”

overrideToCodecIso

Section titled “overrideToCodecIso”

Overrides a schema’s derived ISO codec with an explicit target codec.

When to use

Use to provide a custom ISO transformation when the default derivation is not appropriate.

Details

The resulting schema carries a custom Iso type parameter and uses the provided decode and encode getters to transform between the schema type and the target codec.

Signature

declare const overrideToCodecIso: <S extends Constraint, Iso>(
  to: Codec<Iso>,
  transformation: {
    readonly decode: SchemaGetter.Getter<S["Type"], Iso>
    readonly encode: SchemaGetter.Getter<Iso, S["Type"]>
  }
) => (schema: S) => overrideToCodecIso<S, Iso>

Source

Since v4.0.0

overrideToCodecIso (interface)

Section titled “overrideToCodecIso (interface)”

Type-level representation returned by overrideToCodecIso.

Signature

export interface overrideToCodecIso<S extends Constraint, Iso> extends BottomLazy<
  S["ast"],
  overrideToCodecIso<S, Iso>,
  S["~type.parameters"],
  S["~type.mutability"],
  S["~type.optionality"],
  S["~type.constructor.default"],
  S["~encoded.mutability"],
  S["~encoded.optionality"]
> {
  readonly Type: S["Type"]
  readonly Encoded: S["Encoded"]
  readonly DecodingServices: S["DecodingServices"]
  readonly EncodingServices: S["EncodingServices"]
  readonly "~type.make.in": S["~type.make.in"]
  readonly "~type.make": S["~type.make"]
  readonly Iso: Iso
  readonly schema: S
}

Source

Since v4.0.0

toIso

Section titled “toIso”

Derives an Iso optic from a schema that isomorphically converts between the schema’s Type and its Iso (intermediate / serialized form).

Signature

declare const toIso: <S extends Constraint>(schema: S) => Optic_.Iso<S["Type"], S["Iso"]>

Source

Since v4.0.0

toIsoFocus

Section titled “toIsoFocus”

Returns an identity Iso over the schema’s focus (Iso) side.

Signature

declare const toIsoFocus: <S extends Constraint>(_: S) => Optic_.Iso<S["Iso"], S["Iso"]>

Source

Since v4.0.0

toIsoSource

Section titled “toIsoSource”

Returns an identity Iso over the schema’s source (Type) side.

Signature

declare const toIsoSource: <S extends Constraint>(_: S) => Optic_.Iso<S["Type"], S["Type"]>

Source

Since v4.0.0

Option

Section titled “Option”

Option

Section titled “Option”

Schema for Option<A> values.

Signature

declare const Option: <A extends Constraint>(value: A) => Option<A>

Source

Since v3.10.0

Option (interface)

Section titled “Option (interface)”

Type-level representation returned by Option.

Signature

export interface Option<A extends Constraint> extends declareConstructor<
  Option_.Option<A["Type"]>,
  Option_.Option<A["Encoded"]>,
  readonly [A],
  OptionIso<A>
> {
  readonly Rebuild: Option<A>
  readonly value: A
}

Source

Since v3.10.0

OptionFromNullOr

Section titled “OptionFromNullOr”

Decodes a nullable, required value T to a required Option<T> value.

Details

Decoding maps null to None and all other values to Some. Encoding maps None to null and maps Some to its value.

Signature

declare const OptionFromNullOr: <S extends Constraint>(schema: S) => OptionFromNullOr<S>

Source

Since v3.10.0

OptionFromNullOr (interface)

Section titled “OptionFromNullOr (interface)”

Type-level representation returned by OptionFromNullOr.

Signature

export interface OptionFromNullOr<S extends Constraint> extends decodeTo<Option<toType<S>>, NullOr<S>> {
  readonly Rebuild: OptionFromNullOr<S>
}

Source

Since v3.10.0

OptionFromNullishOr

Section titled “OptionFromNullishOr”

Decodes a nullish value T to a required Option<T> value.

Details

Decoding maps null and undefined to None and all other values to Some. Encoding maps None to null or undefined depending on options.onNoneEncoding, which defaults to undefined, and maps Some to its value.

Signature

declare const OptionFromNullishOr: <S extends Constraint>(
  schema: S,
  options?: { onNoneEncoding: null | undefined }
) => OptionFromNullishOr<S>

Source

Since v3.10.0

OptionFromNullishOr (interface)

Section titled “OptionFromNullishOr (interface)”

Type-level representation returned by OptionFromNullishOr.

Signature

export interface OptionFromNullishOr<S extends Constraint> extends decodeTo<Option<toType<S>>, NullishOr<S>> {
  readonly Rebuild: OptionFromNullishOr<S>
}

Source

Since v3.10.0

OptionFromOptional

Section titled “OptionFromOptional”

Decodes an optional or undefined value A to a required Option<A> value.

Details

Decoding maps a missing key or a present undefined value to None, and maps all other values to Some. Encoding maps None to a missing key and maps Some to its value.

Signature

declare const OptionFromOptional: <S extends Constraint>(schema: S) => OptionFromOptional<S>

Source

Since v4.0.0

OptionFromOptional (interface)

Section titled “OptionFromOptional (interface)”

Type-level representation returned by OptionFromOptional.

Signature

export interface OptionFromOptional<S extends Constraint> extends decodeTo<Option<toType<S>>, optional<S>> {
  readonly Rebuild: OptionFromOptional<S>
}

Source

Since v4.0.0

OptionFromOptionalKey

Section titled “OptionFromOptionalKey”

Decodes an optional value A to a required Option<A> value.

Details

Decoding maps a missing key to None and a present value to Some. Encoding maps None to a missing key and maps Some to its value.

Signature

declare const OptionFromOptionalKey: <S extends Constraint>(schema: S) => OptionFromOptionalKey<S>

Source

Since v4.0.0

OptionFromOptionalKey (interface)

Section titled “OptionFromOptionalKey (interface)”

Type-level representation returned by OptionFromOptionalKey.

Signature

export interface OptionFromOptionalKey<S extends Constraint> extends decodeTo<Option<toType<S>>, optionalKey<S>> {
  readonly Rebuild: OptionFromOptionalKey<S>
}

Source

Since v4.0.0

OptionFromOptionalNullOr

Section titled “OptionFromOptionalNullOr”

Decodes an optional or null or undefined value A to a required Option<A> value.

Details

Decoding maps a missing key, undefined, or null to None, and maps all other values to Some. Encoding maps Some to its value. None is encoded according to options.onNoneEncoding: "omit" encodes a missing key, null encodes null, and undefined encodes undefined.

Signature

declare const OptionFromOptionalNullOr: <S extends Constraint>(
  schema: S,
  options?: { readonly onNoneEncoding: "omit" | null | undefined }
) => OptionFromOptionalNullOr<S>

Source

Since v4.0.0

OptionFromOptionalNullOr (interface)

Section titled “OptionFromOptionalNullOr (interface)”

Type-level representation returned by OptionFromOptionalNullOr.

Signature

export interface OptionFromOptionalNullOr<S extends Constraint> extends decodeTo<
  Option<toType<S>>,
  optional<NullOr<S>>
> {
  readonly Rebuild: OptionFromOptionalNullOr<S>
}

Source

Since v4.0.0

OptionFromUndefinedOr

Section titled “OptionFromUndefinedOr”

Decodes a required value that may be undefined to a required Option<T> value.

Details

Decoding maps undefined to None and all other values to Some. Encoding maps None to undefined and maps Some to its value.

Signature

declare const OptionFromUndefinedOr: <S extends Constraint>(schema: S) => OptionFromUndefinedOr<S>

Source

Since v3.10.0

OptionFromUndefinedOr (interface)

Section titled “OptionFromUndefinedOr (interface)”

Type-level representation returned by OptionFromUndefinedOr.

Signature

export interface OptionFromUndefinedOr<S extends Constraint> extends decodeTo<Option<toType<S>>, UndefinedOr<S>> {
  readonly Rebuild: OptionFromUndefinedOr<S>
}

Source

Since v3.10.0

OptionIso (type alias)

Section titled “OptionIso (type alias)”

Iso representation used for Option schemas.

Details

None is represented as { _tag: "None" }, while Some is represented as { _tag: "Some", value } using the wrapped schema’s Iso type.

Signature

type OptionIso<A> = { readonly _tag: "None" } | { readonly _tag: "Some"; readonly value: A["Iso"] }

Source

Since v4.0.0

Order checks

Section titled “Order checks”

makeIsBetween

Section titled “makeIsBetween”

Creates an inclusive or exclusive range check for any ordered type from an Order.Order instance.

Signature

declare const makeIsBetween: <T>(deriveOptions: {
  readonly order: Order.Order<T>
  readonly annotate?:
    | ((options: {
        readonly minimum: T
        readonly maximum: T
        readonly exclusiveMinimum?: boolean | undefined
        readonly exclusiveMaximum?: boolean | undefined
      }) => Annotations.Filter)
    | undefined
  readonly formatter?: Formatter<T> | undefined
}) => (
  options: {
    readonly minimum: T
    readonly maximum: T
    readonly exclusiveMinimum?: boolean | undefined
    readonly exclusiveMaximum?: boolean | undefined
  },
  annotations?: Annotations.Filter
) => SchemaAST.Filter<T>

Source

Since v4.0.0

makeIsGreaterThan

Section titled “makeIsGreaterThan”

Creates a greater-than (>) check for any ordered type from an Order.Order instance.

Signature

declare const makeIsGreaterThan: <T>(options: {
  readonly order: Order.Order<T>
  readonly annotate?: ((exclusiveMinimum: T) => Annotations.Filter) | undefined
  readonly formatter?: Formatter<T> | undefined
}) => (exclusiveMinimum: T, annotations?: Annotations.Filter) => SchemaAST.Filter<T>

Source

Since v4.0.0

makeIsGreaterThanOrEqualTo

Section titled “makeIsGreaterThanOrEqualTo”

Creates a greater-than-or-equal-to (>=) check for any ordered type from an Order.Order instance.

Signature

declare const makeIsGreaterThanOrEqualTo: <T>(options: {
  readonly order: Order.Order<T>
  readonly annotate?: ((exclusiveMinimum: T) => Annotations.Filter) | undefined
  readonly formatter?: Formatter<T> | undefined
}) => (minimum: T, annotations?: Annotations.Filter) => SchemaAST.Filter<T>

Source

Since v4.0.0

makeIsLessThan

Section titled “makeIsLessThan”

Creates a less-than (<) check for any ordered type from an Order.Order instance.

Signature

declare const makeIsLessThan: <T>(options: {
  readonly order: Order.Order<T>
  readonly annotate?: ((exclusiveMaximum: T) => Annotations.Filter) | undefined
  readonly formatter?: Formatter<T> | undefined
}) => (exclusiveMaximum: T, annotations?: Annotations.Filter) => SchemaAST.Filter<T>

Source

Since v4.0.0

makeIsLessThanOrEqualTo

Section titled “makeIsLessThanOrEqualTo”

Creates a less-than-or-equal-to (<=) check for any ordered type from an Order.Order instance.

Signature

declare const makeIsLessThanOrEqualTo: <T>(options: {
  readonly order: Order.Order<T>
  readonly annotate?: ((exclusiveMaximum: T) => Annotations.Filter) | undefined
  readonly formatter?: Formatter<T> | undefined
}) => (maximum: T, annotations?: Annotations.Filter) => SchemaAST.Filter<T>

Source

Since v4.0.0

PropertyKey

Section titled “PropertyKey”

PropertyKey

Section titled “PropertyKey”

Schema for property keys accepted by Effect schemas: finite number, symbol, or string.

Signature

declare const PropertyKey: Union<readonly [Finite, Symbol, String]>

Source

Since v4.0.0

ReadonlyMap

Section titled “ReadonlyMap”

$ReadonlyMap (interface)

Section titled “$ReadonlyMap (interface)”

Type-level representation returned by ReadonlyMap.

Signature

export interface $ReadonlyMap<Key extends Constraint, Value extends Constraint> extends declareConstructor<
  globalThis.ReadonlyMap<Key["Type"], Value["Type"]>,
  globalThis.ReadonlyMap<Key["Encoded"], Value["Encoded"]>,
  readonly [Key, Value],
  ReadonlyMapIso<Key, Value>
> {
  readonly Rebuild: $ReadonlyMap<Key, Value>
  readonly key: Key
  readonly value: Value
}

Source

Since v4.0.0

ReadonlyMap

Section titled “ReadonlyMap”

Schema for readonly maps whose keys and values conform to the provided schemas.

Signature

declare const ReadonlyMap: <Key extends Constraint, Value extends Constraint>(
  key: Key,
  value: Value
) => $ReadonlyMap<Key, Value>

Source

Since v3.10.0

ReadonlyMapIso (type alias)

Section titled “ReadonlyMapIso (type alias)”

Iso representation used for ReadonlyMap schemas: an array of readonly [key, value] tuples using each entry schema’s Iso type.

Signature

type ReadonlyMapIso<Key, Value> = ReadonlyArray<readonly [Key["Iso"], Value["Iso"]]>

Source

Since v4.0.0

ReadonlySet

Section titled “ReadonlySet”

$ReadonlySet (interface)

Section titled “$ReadonlySet (interface)”

Type-level representation returned by ReadonlySet.

Signature

export interface $ReadonlySet<Value extends Constraint> extends declareConstructor<
  globalThis.ReadonlySet<Value["Type"]>,
  globalThis.ReadonlySet<Value["Encoded"]>,
  readonly [Value],
  ReadonlySetIso<Value>
> {
  readonly Rebuild: $ReadonlySet<Value>
  readonly value: Value
}

Source

Since v4.0.0

ReadonlySet

Section titled “ReadonlySet”

Schema for readonly sets whose values conform to the provided element schema.

Signature

declare const ReadonlySet: <Value extends Constraint>(value: Value) => $ReadonlySet<Value>

Source

Since v3.10.0

ReadonlySetIso (type alias)

Section titled “ReadonlySetIso (type alias)”

Iso representation used for ReadonlySet schemas: an array of element values using the element schema’s Iso type.

Signature

type ReadonlySetIso<Value> = ReadonlyArray<Value["Iso"]>

Source

Since v4.0.0

Redacted

Section titled “Redacted”

Redacted

Section titled “Redacted”

Schema for values that hide sensitive information from error output and inspection.

Details

If the wrapped schema fails, the issue will be redacted to prevent both the actual value and the schema details from being exposed.

Options:

  • label: When provided, the schema will behave as follows:
    • Values will be validated against the label in addition to the wrapped schema
    • The default JSON serializer will deserialize into a Redacted instance with the label
    • The arbitrary generator will produce a Redacted instance with the label
    • The formatter will return the label
  • disallowJsonEncode: When set to true, when attempting to encode a Redacted instance into JSON, it will fail with an error. This is useful when the wrapped schema is sensitive and should not be exposed in JSON.

See

  • RedactedFromValue for decoding raw values and wrapping them in Redacted.

Signature

declare const Redacted: <S extends Constraint>(
  value: S,
  options?: { readonly label?: string | undefined; readonly disallowJsonEncode?: boolean | undefined }
) => Redacted<S>

Source

Since v3.10.0

Redacted (interface)

Section titled “Redacted (interface)”

Type-level representation returned by Redacted.

Signature

export interface Redacted<S extends Constraint> extends declareConstructor<
  Redacted_.Redacted<S["Type"]>,
  Redacted_.Redacted<S["Encoded"]>,
  readonly [S]
> {
  readonly Rebuild: Redacted<S>
  readonly value: S
}

Source

Since v3.10.0

RedactedFromValue

Section titled “RedactedFromValue”

Decodes a value and wraps it in Redacted<A>. Unlike Redacted which expects the input to already be a Redacted instance, this schema decodes the raw value and wraps it.

See

  • Redacted for schemas whose input is already a Redacted value.

Signature

declare const RedactedFromValue: <S extends Constraint>(
  value: S,
  options?: { readonly label?: string | undefined; readonly disallowEncode?: boolean | undefined }
) => RedactedFromValue<S>

Source

Since v4.0.0

RedactedFromValue (interface)

Section titled “RedactedFromValue (interface)”

Type-level representation returned by RedactedFromValue.

Signature

export interface RedactedFromValue<S extends Constraint> extends decodeTo<
  Redacted<toType<S>>,
  middlewareDecoding<S, S["DecodingServices"]>
> {
  readonly Rebuild: RedactedFromValue<S>
}

Source

Since v4.0.0

redact

Section titled “redact”

Middleware that wraps decoded errors in Redacted, preventing sensitive schema details from leaking in error messages.

Signature

declare const redact: <S extends Constraint>(schema: S) => middlewareDecoding<S, S["DecodingServices"]>

Source

Since v4.0.0

RegExp

Section titled “RegExp”

RegExp

Section titled “RegExp”

Schema for JavaScript RegExp objects.

Details

The default JSON serializer encodes a RegExp as { source, flags }.

Signature

declare const RegExp: RegExp

Source

Since v4.0.0

RegExp (interface)

Section titled “RegExp (interface)”

Type-level representation of RegExp.

Signature

export interface RegExp extends instanceOf<globalThis.RegExp> {
  readonly Rebuild: RegExp
}

Source

Since v4.0.0

Representation

Section titled “Representation”

toRepresentation

Section titled “toRepresentation”

Derives an intermediate SchemaRepresentation.Document from a schema. This document is used internally by toJsonSchemaDocument and related functions to produce JSON Schema output.

Signature

declare const toRepresentation: (schema: Constraint) => SchemaRepresentation.Document

Source

Since v4.0.0

Schema Resolvers

Section titled “Schema Resolvers”

resolveAnnotations

Section titled “resolveAnnotations”

Resolves the typed annotations from a schema. The term “resolve” (rather than “get”) reflects the lookup strategy: if the schema has checks, the annotations are taken from the last check; otherwise they are taken from the base schema instance.

Signature

declare const resolveAnnotations: <S extends Constraint>(
  schema: S
) => Annotations.Bottom<S["Type"], S["~type.parameters"]> | undefined

Source

Since v4.0.0

resolveAnnotationsKey

Section titled “resolveAnnotationsKey”

Resolves the context (key-level) annotations from a schema. Context annotations are those attached via annotateKey and live on the AST’s context rather than on the schema node itself.

Signature

declare const resolveAnnotationsKey: <S extends Constraint>(schema: S) => Annotations.Key<S["Type"]> | undefined

Source

Since v4.0.0

Size checks

Section titled “Size checks”

isMaxSize

Section titled “isMaxSize”

Validates that a value has at most the specified size. Works with values that have a size property, such as Set or Map.

Details

JSON Schema:

This check does not have a direct JSON Schema equivalent, as it applies to values with a size property rather than standard JSON Schema types.

Arbitrary:

When generating test data with fast-check, this applies a node-local maxLength constraint. Generators for values with a final .size, such as sets and maps, interpret it as final cardinality.

Signature

declare const isMaxSize: (
  maxSize: number,
  annotations?: Annotations.Filter
) => SchemaAST.Filter<{ readonly size: number }>

Source

Since v4.0.0

isMinSize

Section titled “isMinSize”

Validates that a value has at least the specified size. Works with values that have a size property, such as Set or Map.

Details

JSON Schema:

This check does not have a direct JSON Schema equivalent, as it applies to values with a size property rather than standard JSON Schema types.

Arbitrary:

When generating test data with fast-check, this applies a node-local minLength constraint. Generators for values with a final .size, such as sets and maps, interpret it as final cardinality.

Signature

declare const isMinSize: (
  minSize: number,
  annotations?: Annotations.Filter
) => SchemaAST.Filter<{ readonly size: number }>

Source

Since v4.0.0

isSizeBetween

Section titled “isSizeBetween”

Validates that a value’s size is within the specified range. Works with values that have a size property, such as Set or Map.

Details

JSON Schema:

This check does not have a direct JSON Schema equivalent, as it applies to values with a size property rather than standard JSON Schema types.

Arbitrary:

When generating test data with fast-check, this applies node-local minLength and maxLength constraints. Generators for values with a final .size, such as sets and maps, interpret them as final cardinality.

Signature

declare const isSizeBetween: (
  minimum: number,
  maximum: number,
  annotations?: Annotations.Filter
) => SchemaAST.Filter<{ readonly size: number }>

Source

Since v4.0.0

Standard Schema

Section titled “Standard Schema”

StandardSchemaV1FailureResult

Section titled “StandardSchemaV1FailureResult”

Schema for a Standard Schema v1 failure result.

Details

The result contains an issues array where each issue has a message and an optional path made of property keys or keyed path segments.

Signature

declare const StandardSchemaV1FailureResult: Struct<{
  readonly issues: $Array<
    Struct<{
      readonly message: String
      readonly path: optional<
        $Array<
          Union<
            readonly [
              Union<readonly [Finite, Symbol, String]>,
              Struct<{ readonly key: Union<readonly [Finite, Symbol, String]> }>
            ]
          >
        >
      >
    }>
  >
}>

Source

Since v4.0.0

toStandardJSONSchemaV1

Section titled “toStandardJSONSchemaV1”

Converts a schema to an experimental Standard JSON Schema V1 representation.

Details

https://github.com/standard-schema/standard-schema/pull/134

Signature

declare const toStandardJSONSchemaV1: <S extends Constraint>(
  self: S
) => StandardJSONSchemaV1<S["Encoded"], S["Type"]> & S

Source

Since v4.0.0

toStandardSchemaV1

Section titled “toStandardSchemaV1”

Returns a “Standard Schema” object conforming to the Standard Schema v1 specification.

Details

This function creates a schema whose validate method attempts to decode and validate the provided input synchronously. If the underlying Schema includes any asynchronous components (e.g., asynchronous message resolutions or checks), then validation will necessarily return a Promise instead.

Example (Creating a standard schema from a regular schema)

import { Schema } from "effect"


// Define custom hook functions for error formatting
const leafHook = (issue: any) => {
  switch (issue._tag) {
    case "InvalidType":
      return "Expected different type"
    case "InvalidValue":
      return "Invalid value provided"
    case "MissingKey":
      return "Required property missing"
    case "UnexpectedKey":
      return "Unexpected property found"
    case "Forbidden":
      return "Operation not allowed"
    case "OneOf":
      return "Multiple valid options available"
    default:
      return "Validation error"
  }
}


// Create a standard schema from a regular schema
const PersonSchema = Schema.Struct({
  name: Schema.NonEmptyString,
  age: Schema.Number.check(Schema.isBetween({ minimum: 0, maximum: 150 }))
})


const standardSchema = Schema.toStandardSchemaV1(PersonSchema, {
  leafHook
})


// The standard schema can be used with any Standard Schema v1 compatible library
const validResult = standardSchema["~standard"].validate({
  name: "Alice",
  age: 30
})
console.log(validResult) // { value: { name: "Alice", age: 30 } }


const invalidResult = standardSchema["~standard"].validate({
  name: "",
  age: 200
})
console.log(invalidResult) // { issues: [{ path: ["name"], message: "..." }, { path: ["age"], message: "..." }] }

Signature

declare const toStandardSchemaV1: <S extends ConstraintDecoder<unknown>>(
  self: S,
  options?: {
    readonly leafHook?: SchemaIssue.LeafHook | undefined
    readonly checkHook?: SchemaIssue.CheckHook | undefined
    readonly parseOptions?: SchemaAST.ParseOptions | undefined
  }
) => StandardSchemaV1<S["Encoded"], S["Type"]> & S

Source

Since v4.0.0

String checks

Section titled “String checks”

isBase64

Section titled “isBase64”

Validates that a string is valid Base64 encoded data.

Details

JSON Schema:

This check corresponds to a pattern constraint in JSON Schema that matches Base64 format.

Arbitrary:

When generating test data with fast-check, this applies a patterns constraint to ensure generated strings match the Base64 pattern.

Signature

declare const isBase64: (annotations?: Annotations.Filter) => SchemaAST.Filter<string>

Source

Since v4.0.0

isBase64Url

Section titled “isBase64Url”

Validates that a string is valid Base64URL encoded data (Base64 with URL-safe characters).

Details

JSON Schema:

This check corresponds to a pattern constraint in JSON Schema that matches Base64URL format.

Arbitrary:

When generating test data with fast-check, this applies a patterns constraint to ensure generated strings match the Base64URL pattern.

Signature

declare const isBase64Url: (annotations?: Annotations.Filter) => SchemaAST.Filter<string>

Source

Since v4.0.0

isCapitalized

Section titled “isCapitalized”

Validates that the first character of a string is unchanged by toUpperCase().

Details

Empty strings pass. Strings whose first character has no lowercase form, such as a digit, punctuation mark, or whitespace, also pass.

Signature

declare const isCapitalized: (annotations?: Annotations.Filter) => SchemaAST.Filter<string>

Source

Since v4.0.0

isEndsWith

Section titled “isEndsWith”

Validates at runtime that a string ends with the specified literal suffix.

Details

Notes: The JSON Schema and arbitrary metadata are built from ${endsWith}$ without escaping regexp metacharacters. If the suffix contains regexp syntax, generated patterns may not be equivalent to the runtime endsWith check.

Signature

declare const isEndsWith: (endsWith: string, annotations?: Annotations.Filter) => SchemaAST.Filter<string>

Source

Since v4.0.0

isGUID

Section titled “isGUID”

Validates that a string has the GUID / UUID textual shape.

When to use

Use when you need to accept dashed hexadecimal identifiers without enforcing UUID version or variant bits.

Details

This check accepts strings in the 8-4-4-4-12 hexadecimal form. JSON Schema output includes the corresponding pattern constraint and intentionally does not include format: "uuid" because GUID validation is looser than UUID validation.

Arbitrary:

When generating test data with fast-check, this applies a patterns constraint to ensure generated strings match the GUID pattern.

See

  • isUUID for strict UUID validation.

Signature

declare const isGUID: (annotations?: Annotations.Filter) => SchemaAST.Filter<string>

Source

Since v4.0.0

isIncludes

Section titled “isIncludes”

Validates at runtime that a string contains the specified literal substring.

Details

Notes: The JSON Schema and arbitrary metadata use the substring as a raw regexp pattern. If the substring contains regexp syntax, generated patterns may not be equivalent to the runtime includes check.

Signature

declare const isIncludes: (includes: string, annotations?: Annotations.Filter) => SchemaAST.Filter<string>

Source

Since v4.0.0

isLowercased

Section titled “isLowercased”

Validates that a string is unchanged by JavaScript’s toLowerCase().

Details

This accepts empty strings and characters that do not have uppercase forms, such as digits, punctuation, and whitespace. It rejects strings that would change when lowercased.

Signature

declare const isLowercased: (annotations?: Annotations.Filter) => SchemaAST.Filter<string>

Source

Since v4.0.0

isPattern

Section titled “isPattern”

Validates that a string matches the specified regular expression pattern.

Details

JSON Schema:

This check corresponds to the pattern constraint in JSON Schema.

Arbitrary:

When generating test data with fast-check, this applies a patterns constraint to ensure generated strings match the specified RegExp pattern.

Signature

declare const isPattern: (regExp: globalThis.RegExp, annotations?: Annotations.Filter) => SchemaAST.Filter<string>

Source

Since v4.0.0

isStartsWith

Section titled “isStartsWith”

Validates at runtime that a string starts with the specified literal prefix.

Details

Notes: The JSON Schema and arbitrary metadata are built from ^${startsWith} without escaping regexp metacharacters. If the prefix contains regexp syntax, generated patterns may not be equivalent to the runtime startsWith check.

Signature

declare const isStartsWith: (startsWith: string, annotations?: Annotations.Filter) => SchemaAST.Filter<string>

Source

Since v4.0.0

isStringBigInt

Section titled “isStringBigInt”

Validates that a string is a signed base-10 integer literal for Effect’s BigInt string encoding.

Details

The check uses the pattern ^-?\d+$. It does not accept leading +, decimal points, exponent notation, separators, or non-decimal inputs such as hexadecimal strings.

JSON Schema: This check corresponds to a pattern constraint with the same signed base-10 integer pattern.

Signature

declare const isStringBigInt: (annotations?: Annotations.Filter) => SchemaAST.Filter<string>

Source

Since v4.0.0

isStringFinite

Section titled “isStringFinite”

Validates that a string represents a finite number.

Details

JSON Schema:

This check corresponds to a pattern constraint in JSON Schema that matches strings representing finite numbers.

Arbitrary:

When generating test data with fast-check, this applies a patterns constraint to ensure generated strings match the number string pattern.

Signature

declare const isStringFinite: (annotations?: Annotations.Filter) => SchemaAST.Filter<string>

Source

Since v4.0.0

isStringSymbol

Section titled “isStringSymbol”

Validates that a string has the Symbol(description) format used by Effect’s symbol string encoding.

Details

The check uses the pattern ^Symbol\((.*)\)$. It is not a general test for whether a string can be passed to JavaScript’s Symbol() function.

Signature

declare const isStringSymbol: (annotations?: Annotations.Filter) => SchemaAST.Filter<string>

Source

Since v4.0.0

isTrimmed

Section titled “isTrimmed”

Validates that a string has no leading or trailing whitespace.

Details

JSON Schema:

This check corresponds to a pattern constraint in JSON Schema that matches strings without leading or trailing whitespace.

Arbitrary:

When generating test data with fast-check, this applies a patterns constraint to ensure generated strings match the trimmed pattern.

Signature

declare const isTrimmed: (annotations?: Annotations.Filter) => SchemaAST.Filter<string>

Source

Since v4.0.0

isULID

Section titled “isULID”

Validates that a string is a valid ULID (Universally Unique Lexicographically Sortable Identifier).

Details

JSON Schema:

This check corresponds to a pattern constraint in JSON Schema that matches the ULID format.

Arbitrary:

When generating test data with fast-check, this applies a patterns constraint to ensure generated strings match the ULID pattern.

Signature

declare const isULID: (annotations?: Annotations.Filter) => SchemaAST.Filter<string>

Source

Since v4.0.0

isUUID

Section titled “isUUID”

Validates that a string is a strict Universally Unique Identifier (UUID).

When to use

Use when you need UUID semantics, including version and RFC variant bits, rather than only the dashed hexadecimal shape.

Details

Without a version argument, this accepts UUID versions 1 through 8, the nil UUID (00000000-0000-0000-0000-000000000000), and the max UUID (ffffffff-ffff-ffff-ffff-ffffffffffff). With a version argument, this accepts only UUIDs with that version and RFC variant bits; nil and max UUIDs are not versioned UUIDs and do not match version-specific checks.

JSON Schema:

This check corresponds to a pattern constraint in JSON Schema that matches UUID format, and includes a format: "uuid" annotation.

Arbitrary:

When generating test data with fast-check, this applies a patterns constraint to ensure generated strings match the UUID pattern.

See

  • isGUID for shape-only GUID validation.

Signature

declare const isUUID: (
  version?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8,
  annotations?: Annotations.Filter
) => SchemaAST.Filter<string>

Source

Since v4.0.0

isUncapitalized

Section titled “isUncapitalized”

Validates that the first character of a string is unchanged by toLowerCase().

Details

Empty strings pass. Strings whose first character has no uppercase form, such as a digit, punctuation mark, or whitespace, also pass.

Signature

declare const isUncapitalized: (annotations?: Annotations.Filter) => SchemaAST.Filter<string>

Source

Since v4.0.0

isUppercased

Section titled “isUppercased”

Validates that a string is unchanged by JavaScript’s toUpperCase().

Details

This accepts empty strings and characters that do not have lowercase forms, such as digits, punctuation, and whitespace. It rejects strings that would change when uppercased.

Signature

declare const isUppercased: (annotations?: Annotations.Filter) => SchemaAST.Filter<string>

Source

Since v4.0.0

Tree

Section titled “Tree”

Tree

Section titled “Tree”

Creates a recursive schema for a Tree of values described by node. The resulting schema accepts a single node value, an array of trees, or an object whose values are trees.

Signature

declare const Tree: <S extends Constraint>(
  node: S
) => Union<
  readonly [
    S,
    $Array<suspend<Codec<Tree<S["Type"]>, Tree<S["Encoded"]>, S["DecodingServices"], S["EncodingServices"]>>>,
    $Record<String, suspend<Codec<Tree<S["Type"]>, Tree<S["Encoded"]>, S["DecodingServices"], S["EncodingServices"]>>>
  ]
>

Source

Since v4.0.0

Tree (type alias)

Section titled “Tree (type alias)”

Recursive tree type whose leaves are Node values and whose branches are readonly arrays or string-keyed records of child trees.

Signature

type Tree<Node> = Node | TreeRecord<Node> | ReadonlyArray<Tree<Node>>

Source

Since v4.0.0

TreeRecord (interface)

Section titled “TreeRecord (interface)”

A record node in a Tree: an object mapping string keys to child Tree nodes.

Signature

export interface TreeRecord<A> {
  readonly [x: string]: Tree<A>
}

Source

Since v4.0.0

URL

Section titled “URL”

URL

Section titled “URL”

Schema for JavaScript URL objects.

Details

Default JSON serializer:

  • encodes URL as a string

Signature

declare const URL: URL

Source

Since v4.0.0

URL (interface)

Section titled “URL (interface)”

Type-level representation of URL.

Signature

export interface URL extends instanceOf<globalThis.URL> {
  readonly Rebuild: URL
}

Source

Since v4.0.0

URLFromString

Section titled “URLFromString”

Schema that decodes a string into a URL.

Details

Decoding:

  • A valid URL string is decoded as a URL

Encoding:

  • A URL is encoded as a string

Signature

declare const URLFromString: URLFromString

Source

Since v4.0.0

URLFromString (interface)

Section titled “URLFromString (interface)”

Type-level representation of URLFromString.

Signature

export interface URLFromString extends decodeTo<URL, String> {
  readonly Rebuild: URLFromString
}

Source

Since v4.0.0

Uint8Array

Section titled “Uint8Array”

Uint8Array

Section titled “Uint8Array”

Schema for JavaScript Uint8Array objects.

Details

Default JSON serializer:

The default JSON serializer encodes Uint8Array as a Base64 encoded string.

Signature

declare const Uint8Array: Uint8Array

Source

Since v4.0.0

Uint8Array (interface)

Section titled “Uint8Array (interface)”

Type-level representation of Uint8Array.

Signature

export interface Uint8Array extends instanceOf<globalThis.Uint8Array<ArrayBufferLike>> {
  readonly Rebuild: Uint8Array
}

Source

Since v4.0.0

Uint8ArrayFromBase64

Section titled “Uint8ArrayFromBase64”

Schema that decodes a base64 encoded string into a Uint8Array.

Details

Decoding:

  • A valid base64 encoded string is decoded as a Uint8Array.

Encoding:

  • A Uint8Array is encoded as a base64-encoded string.

Signature

declare const Uint8ArrayFromBase64: Uint8ArrayFromBase64

Source

Since v3.10.0

Uint8ArrayFromBase64 (interface)

Section titled “Uint8ArrayFromBase64 (interface)”

Type-level representation of Uint8ArrayFromBase64.

Signature

export interface Uint8ArrayFromBase64 extends decodeTo<Uint8Array, String> {
  readonly Rebuild: Uint8ArrayFromBase64
}

Source

Since v3.10.0

Uint8ArrayFromBase64Url

Section titled “Uint8ArrayFromBase64Url”

Schema that decodes a base64 (URL) encoded string into a Uint8Array.

Details

Decoding:

  • A valid base64 (URL) encoded string is decoded as a Uint8Array.

Encoding:

  • A Uint8Array is encoded as a base64 (URL) encoded string.

Signature

declare const Uint8ArrayFromBase64Url: Uint8ArrayFromBase64Url

Source

Since v3.10.0

Uint8ArrayFromBase64Url (interface)

Section titled “Uint8ArrayFromBase64Url (interface)”

Type-level representation of Uint8ArrayFromBase64Url.

Signature

export interface Uint8ArrayFromBase64Url extends decodeTo<Uint8Array, String> {
  readonly Rebuild: Uint8ArrayFromBase64Url
}

Source

Since v3.10.0

Uint8ArrayFromHex

Section titled “Uint8ArrayFromHex”

Schema that decodes a hex encoded string into a Uint8Array.

Details

Decoding:

  • A valid hex encoded string is decoded as a Uint8Array.

Encoding:

  • A Uint8Array is encoded as a hex encoded string.

Signature

declare const Uint8ArrayFromHex: Uint8ArrayFromHex

Source

Since v3.10.0

Uint8ArrayFromHex (interface)

Section titled “Uint8ArrayFromHex (interface)”

Type-level representation of Uint8ArrayFromHex.

Signature

export interface Uint8ArrayFromHex extends decodeTo<Uint8Array, String> {
  readonly Rebuild: Uint8ArrayFromHex
}

Source

Since v3.10.0

annotations

Section titled “annotations”

annotate

Section titled “annotate”

Adds metadata annotations to a schema without changing its runtime behavior. This is the pipeable (curried) counterpart of the .annotate method.

Details

Annotations provide extra context used by documentation generators, JSON Schema converters, error formatters, and other tooling. Common keys include title, description, examples, message, and identifier.

Example (Adding a title and description)

import { Schema } from "effect"


const Age = Schema.Number.pipe(
  Schema.annotate({
    title: "Age",
    description: "A non-negative integer representing age in years"
  })
)

See

  • annotateEncoded to annotate the encoded side instead.

Signature

declare const annotate: <S extends Top>(
  annotations: Annotations.Bottom<S["Type"], S["~type.parameters"]>
) => (self: S) => S["Rebuild"]

Source

Since v4.0.0

annotateEncoded

Section titled “annotateEncoded”

Adds metadata annotations to the encoded side of a schema without changing its runtime behavior. This is the encoded-side counterpart of annotate, which targets the decoded (Type) side.

Details

Internally the schema is flipped so that Encoded becomes Type, annotated, and then flipped back.

Example (Adding a title to the encoded representation)

import { Schema } from "effect"


const schema = Schema.NumberFromString.pipe(
  Schema.annotateEncoded({
    title: "my title"
  })
)


console.log(Schema.toEncoded(schema).ast.annotations?.title)
// "my title"

See

  • annotate to annotate the type side instead.

Signature

declare const annotateEncoded: <S extends Top>(
  annotations: Annotations.Bottom<S["Encoded"], readonly []>
) => (self: S) => S["Rebuild"]

Source

Since v4.0.0

annotateKey

Section titled “annotateKey”

Adds key-level annotations to a schema field. This is the pipeable (curried) counterpart of the .annotateKey method.

Details

Key annotations apply to a field’s position inside a Struct or Tuple rather than to the field’s value type. They can carry a messageMissingKey to customise the error shown when the field is absent, as well as standard documentation fields such as title, description, and examples.

Example (Customizing the missing-key message for a required field)

import { Schema } from "effect"


const schema = Schema.Struct({
  username: Schema.String.pipe(
    Schema.annotateKey({
      description: "The username used to log in",
      messageMissingKey: "Username is required"
    })
  )
})

Signature

declare const annotateKey: <S extends Top>(annotations: Annotations.Key<S["Type"]>) => (self: S) => S["Rebuild"]

Source

Since v4.0.0

boolean

Section titled “boolean”

Boolean

Section titled “Boolean”

Schema for boolean values. Validates that the input is typeof "boolean".

When to use

Use to validate values that are already JavaScript booleans.

See

  • BooleanFromBit for a schema that decodes bit literals 0 or 1 into a boolean

Signature

declare const Boolean: Boolean

Source

Since v4.0.0

BooleanFromBit

Section titled “BooleanFromBit”

Schema for a boolean parsed from 0 or 1.

When to use

Use when decoding data sources that represent booleans as 0 | 1 while keeping boolean values in the decoded model.

Details

Decoding accepts only 0 | 1, maps 1 to true, and maps 0 to false. Encoding maps true to 1 and false to 0.

See

  • Boolean for validating values that are already booleans
  • Literals for keeping bit literals instead of decoding them

Signature

declare const BooleanFromBit: BooleanFromBit

Source

Since v4.0.0

BooleanFromBit (interface)

Section titled “BooleanFromBit (interface)”

Type-level representation of BooleanFromBit.

Signature

export interface BooleanFromBit extends decodeTo<Boolean, Literals<readonly [0, 1]>> {
  readonly Rebuild: BooleanFromBit
}

Source

Since v4.0.0

branding

Section titled “branding”

brand

Section titled “brand”

Adds a nominal brand to a schema, intersecting the output type with Brand.Brand<B> to prevent accidental mixing of structurally identical types.

When to use

Use to make values decoded by an existing schema nominally distinct when the schema already carries the runtime validation you need.

Gotchas

brand adds brand metadata and narrows the TypeScript output type, but it does not add runtime checks.

See

  • fromBrand for applying a Brand constructor’s checks along with the brand tag

Signature

declare const brand: <B extends string>(
  identifier: B
) => <S extends ConstraintRebuildable>(schema: S) => brand<S["Rebuild"], B>

Source

Since v3.10.0

brand (interface)

Section titled “brand (interface)”

Type-level representation returned by brand.

Signature

export interface brand<S extends Constraint, B> extends BottomLazy<
  S["ast"],
  brand<S, B>,
  S["~type.parameters"],
  S["~type.mutability"],
  S["~type.optionality"],
  S["~type.constructor.default"],
  S["~encoded.mutability"],
  S["~encoded.optionality"]
> {
  readonly Type: S["Type"] & DistributeBrands<B>
  readonly Encoded: S["Encoded"]
  readonly DecodingServices: S["DecodingServices"]
  readonly EncodingServices: S["EncodingServices"]
  readonly "~type.make.in": S["~type.make.in"]
  readonly "~type.make": S["Type"] & DistributeBrands<B>
  readonly Iso: S["Type"] & DistributeBrands<B>
  readonly schema: S
  readonly identifier: string
}

Source

Since v3.10.0

fromBrand

Section titled “fromBrand”

Creates a branded schema from a Brand.Constructor, applying the constructor’s checks and brand tag to the underlying schema.

Signature

declare const fromBrand: <A extends Brand.Brand<any>>(
  identifier: string,
  ctor: Brand.Constructor<A>
) => <S extends Top & { readonly Type: Brand.Brand.Unbranded<A> }>(self: S) => brand<S["Rebuild"], Brand.Brand.Keys<A>>

Source

Since v3.10.0

combinators

Section titled “combinators”

fieldsAssign

Section titled “fieldsAssign”

Adds fields to a struct schema through a struct-mapping lambda.

When to use

Use to add the same fields to an existing struct or every struct member of a union.

Details

This is a shortcut for MyStruct.mapFields(Struct.assign(fields)).

Example (Adding fields to a union of structs)

import { Schema, Tuple } from "effect"


// Add a new field to all members of a union of structs
const schema = Schema.Union([Schema.Struct({ a: Schema.String }), Schema.Struct({ b: Schema.Number })]).mapMembers(
  Tuple.map(Schema.fieldsAssign({ c: Schema.Number }))
)

Signature

declare const fieldsAssign: <const NewFields extends Struct.Fields>(fields: NewFields) => fieldsAssign<NewFields>

Source

Since v4.0.0

mutableKey

Section titled “mutableKey”

Makes a struct field mutable (removes the readonly modifier on the property). Use readonlyKey to reverse.

Signature

declare const mutableKey: mutableKeyLambda

Source

Since v4.0.0

optional

Section titled “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

Signature

declare const optional: optionalLambda

Source

Since v3.10.0

optionalKey

Section titled “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"]

Signature

declare const optionalKey: optionalKeyLambda

Source

Since v4.0.0

readonlyKey

Section titled “readonlyKey”

Reverses mutableKey and returns the inner readonly schema.

When to use

Use to remove mutable-key wrapping from a schema field that was previously wrapped with mutableKey.

Signature

declare const readonlyKey: readonlyKeyLambda

Source

Since v4.0.0

required

Section titled “required”

Reverses optional and returns the inner schema.

When to use

Use to remove optional wrapping from a schema field that was previously wrapped with optional.

Details

This also unwraps the UndefinedOr member added by optional.

Signature

declare const required: requiredLambda

Source

Since v3.10.0

requiredKey

Section titled “requiredKey”

Reverses optionalKey and returns the inner required schema.

When to use

Use to remove optional-key wrapping from a schema field that was previously wrapped with optionalKey.

Signature

declare const requiredKey: requiredKeyLambda

Source

Since v4.0.0

toTaggedUnion

Section titled “toTaggedUnion”

Augments an existing Union of tagged structs with utility methods keyed by the discriminant field.

Example (Adding tagged-union utilities to an existing union)

import { Schema } from "effect"


const A = Schema.TaggedStruct("A", { value: Schema.Number })
const B = Schema.TaggedStruct("B", { name: Schema.String })


const MyUnion = Schema.Union([A, B]).pipe(Schema.toTaggedUnion("_tag"))


// Pattern-match on the union
const result = MyUnion.match(
  { _tag: "A", value: 1 },
  {
    A: (a) => `number: ${a.value}`,
    B: (b) => `name: ${b.name}`
  }
)

See

  • TaggedUnion for a shorthand that builds the union from scratch

Signature

declare const toTaggedUnion: <const Tag extends PropertyKey>(
  tag: Tag
) => <const Members extends ReadonlyArray<Constraint & { readonly Type: { readonly [K in Tag]: PropertyKey } }>>(
  self: Union<Members>
) => toTaggedUnion<Tag, Members>

Source

Since v4.0.0

toTaggedUnion (type alias)

Section titled “toTaggedUnion (type alias)”

Type-level representation returned by toTaggedUnion.

Signature

type toTaggedUnion<Tag, Members> = Union<Members> & TaggedUnionUtils<Tag, Members>

Source

Since v4.0.0

constructors

Section titled “constructors”

Array

Section titled “Array”

Defines a ReadonlyArray schema for a given element schema.

Example (Defining an array of strings)

import { Schema } from "effect"


const schema = Schema.Array(Schema.String)


const result = Schema.decodeUnknownSync(schema)(["a", "b", "c"])
console.log(result)
// [ 'a', 'b', 'c' ]

Signature

declare const Array: ArrayLambda

Source

Since v4.0.0

ArrayEnsure

Section titled “ArrayEnsure”

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

  • Array for accepting only array input
  • NonEmptyArray for requiring at least one decoded element

Signature

declare const ArrayEnsure: <S extends Constraint>(schema: S) => ArrayEnsure<S>

Source

Since v3.10.0

ArrayEnsure (interface)

Section titled “ArrayEnsure (interface)”

Type-level representation returned by ArrayEnsure.

Signature

export interface ArrayEnsure<S extends Constraint> extends decodeTo<$Array<toType<S>>, Union<readonly [S, $Array<S>]>> {
  readonly Rebuild: ArrayEnsure<S>
}

Source

Since v3.10.0

Class

Section titled “Class”

Creates a schema-backed class whose constructor validates input against a Struct schema. Construction throws a SchemaError on invalid input.

When to use

Use when you need a schema-backed data class with validated construction, schema-derived decoding/encoding, and class-style methods or inheritance.

Details

Pass the desired class type as the first type parameter. The second optional type parameter can be used to add nominal brands.

Gotchas

Passing disableChecks in the options skips constructor validation.

Example (Defining a basic class)

import { Schema } from "effect"


class Person extends Schema.Class<Person>("Person")({
  name: Schema.String,
  age: Schema.Number
}) {}


const alice = new Person({ name: "Alice", age: 30 })
console.log(alice.name) // "Alice"
console.log(`${alice}`) // "Person({ name: Alice, age: 30 })"

Example (Extending a class)

import { Schema } from "effect"


class Animal extends Schema.Class<Animal>("Animal")({
  name: Schema.String
}) {}


class Dog extends Animal.extend<Dog>("Dog")({
  breed: Schema.String
}) {}


const dog = new Dog({ name: "Rex", breed: "Labrador" })
console.log(dog.name) // "Rex"
console.log(dog.breed) // "Labrador"

See

  • TaggedClass for adding a _tag literal field to the class schema
  • ErrorClass for defining schema-backed error classes
  • TaggedErrorClass for defining tagged schema-backed error classes

Signature

declare const Class: <Self = never, Brand = {}>(
  identifier: string
) => {
  <const Fields extends Struct.Fields>(
    fields: Fields,
    annotations?: Annotations.Declaration<Self, readonly [Struct<Fields>]>
  ): [Self] extends [never] ? MissingSelfGeneric<"Schema.Class"> : Class<Self, Struct<Fields>, Brand>
  <S extends Struct<Struct.Fields>>(
    schema: S,
    annotations?: Annotations.Declaration<Self, readonly [S]>
  ): [Self] extends [never] ? MissingSelfGeneric<"Schema.Class"> : Class<Self, S, Brand>
}

Source

Since v3.10.0

Defect

Section titled “Defect”

Schema for unexpected defect values represented as unknown with a JSON encoded form.

When to use

Use when you need a schema for Cause defects or other unexpected failures whose runtime value may be any value.

Details

The encoded side is Json. During decoding, JSON objects with a string message property are decoded into JavaScript Error values, preserving a non-default name and any string stack. Other JSON values decode unchanged.

During encoding, JavaScript Error values encode to JSON objects with name, message, and optional cause properties. Pass { includeStack: true } to include string stack traces in encoded Error defects, or { excludeCause: true } to omit causes. Other values are serialized through Effect’s JSON formatter and then parsed back into JSON when possible.

Gotchas

This schema is for carrying defects across JSON boundaries, not for preserving every JavaScript value exactly. Some values cannot round-trip unchanged:

  • A non-Error object such as { message: "boom" } encodes as an error-shaped JSON object and decodes back as an Error.
  • JSON serialization normalizes unsupported values. For example, undefined array elements encode as null, unsupported object properties are omitted, and circular references are dropped.
  • Values that cannot be represented as JSON fall back to Effect’s formatted string representation.

See

  • Error for a schema that only accepts JavaScript Error values.

Signature

declare const Defect: (options?: ErrorOptions) => Defect

Source

Since v4.0.0

Enum

Section titled “Enum”

Creates a schema from a TypeScript enum object. Validates that the input is one of the enum’s values.

Example (Defining a direction enum)

import { Schema } from "effect"


enum Direction {
  Up = "Up",
  Down = "Down"
}


const schema = Schema.Enum(Direction)
// accepts "Up" or "Down"

Signature

declare const Enum: <A extends { [x: string]: string | number }>(enums: A) => Enum<A>

Source

Since v4.0.0

Error

Section titled “Error”

Schema for JavaScript Error objects.

Details

Default JSON serializer:

Encodes an Error as an object with message, optional name, and optional cause properties, and decodes that object back into an Error. Stack traces are omitted by default for security. Pass { includeStack: true } to include stack traces, or { excludeCause: true } to omit causes.

Signature

declare const Error: (options?: ErrorOptions) => Error

Source

Since v4.0.0

ErrorClass

Section titled “ErrorClass”

Creates a schema-backed error class that can be used as a typed, yieldable error in Effect programs. Combines Class validation with the YieldableError interface so instances can be yielded directly inside Effect.gen.

Example (Schema-backed error)

import { Effect, Schema } from "effect"


class NotFound extends Schema.ErrorClass<NotFound>("NotFound")({
  id: Schema.Number
}) {}


const program = Effect.gen(function* () {
  yield* new NotFound({ id: 1 })
})

Signature

declare const ErrorClass: <Self = never, Brand = {}>(
  identifier: string
) => {
  <const Fields extends Struct.Fields>(
    fields: Fields,
    annotations?: Annotations.Declaration<Self, readonly [Struct<Fields>]>
  ): [Self] extends [never]
    ? MissingSelfGeneric<"Schema.ErrorClass">
    : Class<Self, Struct<Fields>, Cause_.YieldableError & Brand>
  <S extends Struct<Struct.Fields>>(
    schema: S,
    annotations?: Annotations.Declaration<Self, readonly [S]>
  ): [Self] extends [never] ? MissingSelfGeneric<"Schema.ErrorClass"> : Class<Self, S, Cause_.YieldableError & Brand>
}

Source

Since v4.0.0

Literal

Section titled “Literal”

Creates a schema for a single literal value (string, number, bigint, boolean, or null).

Example (Defining a string literal)

import { Schema } from "effect"


const schema = Schema.Literal("hello")
// Type: Schema.Literal<"hello">

See

  • Literals for a schema that represents a union of literals.
  • tag for a schema that represents a literal value that can be used as a discriminator field in tagged unions and has a constructor default.

Signature

declare const Literal: <L extends SchemaAST.LiteralValue>(literal: L) => Literal<L>

Source

Since v3.10.0

Literals

Section titled “Literals”

Creates a union schema from an array of literal values.

Example (Defining status codes)

import { Schema } from "effect"


const schema = Schema.Literals(["active", "inactive", "pending"])
// accepts "active", "inactive", or "pending"

See

  • Literal for a schema that represents a single literal.

Signature

declare const Literals: <const L extends ReadonlyArray<SchemaAST.LiteralValue>>(literals: L) => Literals<L>

Source

Since v4.0.0

NonEmptyArray

Section titled “NonEmptyArray”

Defines a non-empty ReadonlyArray schema — at least one element required. Type is readonly [T, ...T[]].

Example (Defining a non-empty array of numbers)

import { Schema } from "effect"


const schema = Schema.NonEmptyArray(Schema.Number)


Schema.decodeUnknownSync(schema)([1, 2, 3]) // ok
Schema.decodeUnknownSync(schema)([]) // throws

Signature

declare const NonEmptyArray: NonEmptyArrayLambda

Source

Since v3.10.0

NullOr

Section titled “NullOr”

Creates a union schema of S | null.

Signature

declare const NullOr: NullOrLambda

Source

Since v3.10.0

NullishOr

Section titled “NullishOr”

Creates a union schema of S | null | undefined.

Signature

declare const NullishOr: NullishOrLambda

Source

Since v3.10.0

Opaque

Section titled “Opaque”

Wraps a struct schema so that its decoded Type becomes a nominally distinct type Self. Useful for creating opaque types that are structurally identical to a base struct but type-incompatible with it.

Example (Defining opaque structs)

import { Schema } from "effect"


class Person extends Schema.Opaque<Person>()(
  Schema.Struct({
    name: Schema.String
  })
) {}


// Decoded value is Person, not { name: string }
const person = Schema.decodeUnknownSync(Person)({ name: "Alice" })
// person: Person

Signature

declare const Opaque: <Self, Brand = {}>() => <S extends Top>(schema: S) => Opaque<Self, S, Brand> & Omit<S, keyof Top>

Source

Since v4.0.0

Record

Section titled “Record”

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 }

Signature

declare const 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>

Source

Since v3.10.0

Struct

Section titled “Struct”

Defines a struct schema from a map of field schemas.

Details

Each field value is a schema. Use optionalKey or optional to mark fields as optional, and mutableKey to mark them as mutable.

The resulting schema’s Type is a readonly object type with the fields’ decoded types. The Encoded form mirrors the field schemas’ encoded types.

Example (Defining a basic struct)

import { Schema } from "effect"


const Person = Schema.Struct({
  name: Schema.String,
  age: Schema.Number,
  email: Schema.optionalKey(Schema.String)
})


// { readonly name: string; readonly age: number; readonly email?: string }
type Person = typeof Person.Type


const alice = Schema.decodeUnknownSync(Person)({ name: "Alice", age: 30 })
console.log(alice)
// { name: 'Alice', age: 30 }

Signature

declare const Struct: <const Fields extends Struct.Fields>(fields: Fields) => Struct<Fields>

Source

Since v3.10.0

StructWithRest

Section titled “StructWithRest”

Extends a struct schema with one or more record (index-signature) schemas, producing a schema whose decoded type intersects the struct and all records.

Gotchas

TypeScript index signatures also apply to fixed keys. StructWithRest does not reject incompatible fixed fields at the call site; use StructWithRest.ValidateRecords when you want an explicit type-level compatibility check.

Example (Defining structs with string-indexed extra keys)

import { Schema } from "effect"


const schema = Schema.StructWithRest(Schema.Struct({ id: Schema.Number }), [
  Schema.Record(Schema.String, Schema.Number)
])


// { readonly id: number, readonly [x: string]: number }
type T = typeof schema.Type

Signature

declare const StructWithRest: <const S extends StructWithRest.Objects, const Records extends StructWithRest.Records>(
  schema: S,
  records: Records
) => StructWithRest<S, Records>

Source

Since v4.0.0

TaggedClass

Section titled “TaggedClass”

Defines a schema-backed class with an automatically populated _tag field.

When to use

Use to define class instances that are validated by a schema and participate in tagged union matching.

Details

The optional identifier parameter overrides the schema identifier; it defaults to the tag value.

Example (Defining a tagged class)

import { Schema } from "effect"


class Circle extends Schema.TaggedClass<Circle>()("Circle", {
  radius: Schema.Number
}) {}


const c = new Circle({ radius: 5 })
console.log(c._tag) // "Circle"
console.log(c.radius) // 5

Signature

declare const TaggedClass: <Self = never, Brand = {}>(
  identifier?: string
) => {
  <Tag extends string, const Fields extends Struct.Fields>(
    tag: Tag,
    fields: Fields,
    annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>
  ): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedClass"> : Class<Self, TaggedStruct<Tag, Fields>, Brand>
  <Tag extends string, S extends Struct<Struct.Fields>>(
    tag: Tag,
    schema: S,
    annotations?: Annotations.Declaration<Self, readonly [Struct<Simplify<{ readonly _tag: tag<Tag> } & S["fields"]>>]>
  ): [Self] extends [never]
    ? MissingSelfGeneric<"Schema.TaggedClass">
    : Class<Self, Struct<Simplify<{ readonly _tag: tag<Tag> } & S["fields"]>>, Brand>
}

Source

Since v3.10.0

TaggedErrorClass

Section titled “TaggedErrorClass”

Defines a schema-backed yieldable error class with an automatically populated _tag field.

When to use

Use to define typed errors that are schema validated, yielded in Effect.gen, and matched as tagged union members.

Example (Defining a tagged error class)

import { Effect, Schema } from "effect"


class NotFound extends Schema.TaggedErrorClass<NotFound>()("NotFound", {
  id: Schema.Number
}) {}


const program = Effect.gen(function* () {
  yield* new NotFound({ id: 42 })
})

Signature

declare const TaggedErrorClass: <Self = never, Brand = {}>(
  identifier?: string
) => {
  <Tag extends string, const Fields extends Struct.Fields>(
    tag: Tag,
    fields: Fields,
    annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>
  ): [Self] extends [never]
    ? MissingSelfGeneric<"Schema.TaggedErrorClass">
    : Class<Self, TaggedStruct<Tag, Fields>, Cause_.YieldableError & Brand>
  <Tag extends string, S extends Struct<Struct.Fields>>(
    tag: Tag,
    schema: S,
    annotations?: Annotations.Declaration<Self, readonly [Struct<Simplify<{ readonly _tag: tag<Tag> } & S["fields"]>>]>
  ): [Self] extends [never]
    ? MissingSelfGeneric<"Schema.TaggedErrorClass">
    : Class<Self, Struct<Simplify<{ readonly _tag: tag<Tag> } & S["fields"]>>, Cause_.YieldableError & Brand>
}

Source

Since v3.10.0

TaggedStruct

Section titled “TaggedStruct”

Creates a struct schema with an automatically populated _tag field.

When to use

Use to define a tagged union case from a literal tag and a set of fields.

Details

When using the make method, the _tag field is optional and will be added automatically. However, when decoding or encoding, the _tag field must be present in the input.

Example (Defining a tagged struct shorthand)

import { Schema } from "effect"


// Defines a struct with a fixed `_tag` field
const tagged = Schema.TaggedStruct("A", {
  a: Schema.String
})


// This is the same as writing:
const equivalent = Schema.Struct({
  _tag: Schema.tag("A"),
  a: Schema.String
})

Example (Accessing the literal value of the tag)

import { Schema } from "effect"


const tagged = Schema.TaggedStruct("A", {
  a: Schema.String
})


// literal: "A"
const literal = tagged.fields._tag.schema.literal

Signature

declare const TaggedStruct: <const Tag extends SchemaAST.LiteralValue, const Fields extends Struct.Fields>(
  value: Tag,
  fields: Fields
) => TaggedStruct<Tag, Fields>

Source

Since v3.10.0

TaggedUnion

Section titled “TaggedUnion”

Builds a discriminated union from a record of field sets, one per variant. Each key becomes the _tag literal and the value is passed to TaggedStruct. The result includes cases, guards, isAnyOf, and match utilities.

Example (Pattern matching a discriminated union)

import { Schema } from "effect"


const Shape = Schema.TaggedUnion({
  Circle: { radius: Schema.Number },
  Rectangle: { width: Schema.Number, height: Schema.Number }
})


// Pattern-match on a decoded value
const area = Shape.match(
  { _tag: "Circle", radius: 5 },
  {
    Circle: (c) => Math.PI * c.radius ** 2,
    Rectangle: (r) => r.width * r.height
  }
)

See

  • toTaggedUnion to augment an existing union instead

Signature

declare const TaggedUnion: <const CasesByTag extends Record<string, Struct.Fields>>(
  casesByTag: CasesByTag
) => TaggedUnion<{ readonly [K in keyof CasesByTag & string]: TaggedStruct<K, CasesByTag[K]> }>

Source

Since v4.0.0

TemplateLiteral

Section titled “TemplateLiteral”

Creates a schema that validates strings by matching ordered template literal parts.

When to use

Use when the decoded value should remain the matched string and you do not need the individual template parts parsed into a tuple.

Details

Each part can be a literal string, number, or bigint, or a schema whose encoded type is string, number, or bigint. Checks on string, number, and bigint schema parts are applied while matching each segment.

Example (Defining a URL path pattern)

import { Schema } from "effect"


const schema = Schema.TemplateLiteral(["/user/", Schema.Number])
// matches strings like "/user/123", "/user/42", etc.

See

  • TemplateLiteralParser for a schema that also parses matched parts into a tuple.

Signature

declare const TemplateLiteral: <const Parts extends TemplateLiteral.Parts>(parts: Parts) => TemplateLiteral<Parts>

Source

Since v3.10.0

TemplateLiteralParser

Section titled “TemplateLiteralParser”

Schema for parsing matched template literal strings into typed tuple parts.

When to use

Use to validate a template literal string and decode the matched parts into typed values.

Details

Unlike TemplateLiteral, this schema decodes the matched string into a readonly tuple with one element per schema part. Checks on string, number, and bigint schema parts are applied while matching each segment.

Example (Parsing path parameters)

import { Schema } from "effect"


const schema = Schema.TemplateLiteralParser(["/user/", Schema.NumberFromString])
// decodes "/user/42" => readonly ["/user/", 42]

See

  • TemplateLiteral for a validation-only version that keeps the string encoded.

Signature

declare const TemplateLiteralParser: <const Parts extends TemplateLiteral.Parts>(
  parts: Parts
) => TemplateLiteralParser<Parts>

Source

Since v3.10.0

Tuple

Section titled “Tuple”

Defines a fixed-length tuple schema from an array of element schemas.

Example (Defining a pair of string and number)

import { Schema } from "effect"


const schema = Schema.Tuple([Schema.String, Schema.Number])


const pair = Schema.decodeUnknownSync(schema)(["hello", 42])
console.log(pair)
// [ 'hello', 42 ]

Signature

declare const Tuple: <const Elements extends ReadonlyArray<Constraint>>(elements: Elements) => Tuple<Elements>

Source

Since v3.10.0

TupleWithRest

Section titled “TupleWithRest”

Extends a fixed-length tuple schema with a variadic rest segment.

Details

The resulting tuple starts with the fixed elements from schema. The first schema in rest is the repeatable element schema, and any additional schemas in rest are required trailing tuple elements after the variadic segment. For example, [Schema.Boolean, Schema.String] represents zero or more booleans followed by a final string.

Example (Defining tuples with rest elements)

import { Schema } from "effect"


// [string, number, ...boolean[]]
const schema = Schema.TupleWithRest(Schema.Tuple([Schema.String, Schema.Number]), [Schema.Boolean])


const result = Schema.decodeUnknownSync(schema)(["hello", 1, true, false])
console.log(result)
// [ 'hello', 1, true, false ]

Signature

declare const TupleWithRest: <S extends Tuple<Tuple.Elements>, const Rest extends TupleWithRest.Rest>(
  schema: S,
  rest: Rest
) => TupleWithRest<S, Rest>

Source

Since v4.0.0

UndefinedOr

Section titled “UndefinedOr”

Creates a union schema of S | undefined.

Signature

declare const UndefinedOr: UndefinedOrLambda

Source

Since v3.10.0

Union

Section titled “Union”

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

Signature

declare const Union: <const Members extends ReadonlyArray<Constraint>>(
  members: Members,
  options?: { mode?: "anyOf" | "oneOf" }
) => Union<Members>

Source

Since v3.10.0

UniqueArray

Section titled “UniqueArray”

Returns a new array schema that ensures all elements are unique.

Details

The equivalence used to determine uniqueness is the one provided by Schema.toEquivalence(item).

Signature

declare const UniqueArray: <S extends Constraint>(item: S) => UniqueArray<S>

Source

Since v4.0.0

UniqueSymbol

Section titled “UniqueSymbol”

Creates a schema for a specific symbol. Only that exact symbol satisfies the schema.

Example (Defining a specific symbol)

import { Schema } from "effect"


const mySymbol = Symbol.for("mySymbol")
const schema = Schema.UniqueSymbol(mySymbol)

See

  • Symbol for a schema that accepts any symbol.

Signature

declare const UniqueSymbol: <const sym extends symbol>(symbol: sym) => UniqueSymbol<sym>

Source

Since v4.0.0

asClass

Section titled “asClass”

Transforms a schema into a class that can be extended with extends. The resulting class inherits the full schema API (e.g. annotate) and can define static methods that reference this.

Example (Wrapping a primitive schema)

import { Schema } from "effect"


class MyString extends Schema.asClass(Schema.String) {
  static readonly decodeUnknownSync = Schema.decodeUnknownSync(this)
}


console.log(MyString.decodeUnknownSync("a"))
// "a"

Signature

declare const asClass: <S extends Top>(schema: S) => S & { new (_: never): {} }

Source

Since v4.0.0

declare

Section titled “declare”

Creates a schema for a non-parametric opaque type using a type-guard function. The schema accepts any unknown value and succeeds when is returns true, failing with an InvalidType issue otherwise.

When to use

Use when you are defining a schema for an opaque type with no type parameters and validation can be expressed as a type guard.

Example (Defining a schema for a custom UserId branded type)

import { Schema } from "effect"


type UserId = string & { readonly _tag: "UserId" }


const isUserId = (u: unknown): u is UserId => typeof u === "string" && u.startsWith("user_")


const UserId = Schema.declare<UserId>(isUserId, {
  title: "UserId",
  description: "A user identifier starting with 'user_'"
})

See

  • declareConstructor for creating schemas for parametric types.

Signature

declare const declare: <T, Iso = T>(
  is: (u: unknown) => u is T,
  annotations?: Annotations.Declaration<T> | undefined
) => declare<T, Iso>

Source

Since v3.10.0

declare (interface)

Section titled “declare (interface)”

Type-level representation returned by declare.

Signature

export interface declare<T, Iso = T> extends declareConstructor<T, T, readonly [], Iso> {
  readonly Rebuild: declare<T, Iso>
}

Source

Since v3.13.3

declareConstructor

Section titled “declareConstructor”

Creates a schema for a parametric type (a generic container such as Array<A>, Option<A>, etc.) by accepting a list of type-parameter schemas and a decoder factory.

When to use

Use when you are defining a schema for a generic container whose validation depends on one or more type-parameter schemas.

Details

The outer call declareConstructor<T, E, Iso>() fixes the decoded type T, the encoded type E, and the optional iso type. The inner call receives:

  • typeParameters — the concrete schemas for each type variable
  • run — a factory that, given resolved codecs for each type parameter, returns a parsing function (u, ast, options) => Effect<T, Issue>
  • annotations — optional metadata

See

  • declare for creating schemas for non-parametric types.

Example (Schema for a parametric Box<A> type)

import { Effect, Option, Schema, SchemaIssue as Issue, SchemaParser } from "effect"


interface Box<A> {
  readonly value: A
}


const isBox = (u: unknown): u is Box<unknown> => typeof u === "object" && u !== null && "value" in u


const Box = <A extends Schema.Constraint>(item: A) =>
  Schema.declareConstructor<Box<A["Type"]>, Box<A["Encoded"]>>()([item], ([itemCodec]) => (u, ast, options) => {
    if (!isBox(u)) {
      return Effect.fail(new SchemaIssue.InvalidType(ast, Option.some(u)))
    }
    return Effect.map(SchemaParser.decodeUnknownEffect(itemCodec)(u.value, options), (value) => ({ value }))
  })


const schema = Box(Schema.Number)

Signature

declare const declareConstructor: <T, E = T, Iso = T>() => <const TypeParameters extends ReadonlyArray<Constraint>>(
  typeParameters: TypeParameters,
  run: (typeParameters: {
    readonly [K in keyof TypeParameters]: Codec<TypeParameters[K]["Type"], TypeParameters[K]["Encoded"]>
  }) => (
    u: unknown,
    self: SchemaAST.Declaration,
    options: SchemaAST.ParseOptions
  ) => Effect.Effect<T, SchemaIssue.Issue>,
  annotations?: Annotations.Declaration<T, TypeParameters>
) => declareConstructor<T, E, TypeParameters, Iso>

Source

Since v4.0.0

declareConstructor (interface)

Section titled “declareConstructor (interface)”

Type-level representation returned by declareConstructor.

Signature

export interface declareConstructor<T, E, TypeParameters extends ReadonlyArray<Constraint>, Iso = T> extends Bottom<
  T,
  E,
  TypeParameters[number]["DecodingServices"],
  TypeParameters[number]["EncodingServices"],
  SchemaAST.Declaration,
  declareConstructor<T, E, TypeParameters, Iso>,
  T,
  Iso,
  TypeParameters
> {}

Source

Since v4.0.0

fromJsonString

Section titled “fromJsonString”

Returns a schema that decodes a JSON string and then decodes the parsed value using the given schema.

Details

This is useful when working with JSON-encoded strings where the actual structure of the value is known and described by an existing schema.

The resulting schema first parses the input string as JSON, and then runs the provided schema on the parsed result.

JSON Schema generation:

When using fromJsonString with draft-2020-12 or openApi3.1, the resulting schema will be a JSON Schema with a contentSchema property that contains the JSON Schema for the given schema.

Example (Decoding JSON strings with a schema)

import { Schema } from "effect"


const schema = Schema.Struct({ a: Schema.Number })
const schemaFromJsonString = Schema.fromJsonString(schema)


Schema.decodeUnknownSync(schemaFromJsonString)(`{"a":1,"b":2}`)
// => { a: 1 }

Example (Emitting JSON Schema for a JSON string decoder)

import { Schema } from "effect"


const original = Schema.Struct({ a: Schema.String })
const schema = Schema.fromJsonString(original)


const document = Schema.toJsonSchemaDocument(schema)


console.log(JSON.stringify(document, null, 2))
// {
//   "source": "draft-2020-12",
//   "schema": {
//     "type": "string",
//     "contentMediaType": "application/json",
//     "contentSchema": {
//       "type": "object",
//       "properties": {
//         "a": {
//           "type": "string"
//         }
//       },
//       "required": [
//         "a"
//       ],
//       "additionalProperties": false
//     }
//   },
//   "definitions": {}
// }

Signature

declare const fromJsonString: <S extends Constraint>(schema: S) => fromJsonString<S>

Source

Since v4.0.0

instanceOf

Section titled “instanceOf”

Creates a schema that validates values using instanceof. Decoding and encoding pass the value through unchanged.

Example (Defining a schema for a built-in class)

import { Schema } from "effect"


const DateSchema = Schema.instanceOf(Date)


const decoded = Schema.decodeUnknownSync(DateSchema)(new Date("2024-01-01"))
// decoded: Date

Signature

declare const instanceOf: <C extends abstract new (...args: any) => any, Iso = InstanceType<C>>(
  constructor: C,
  annotations?: Annotations.Declaration<InstanceType<C>> | undefined
) => instanceOf<InstanceType<C>, Iso>

Source

Since v3.10.0

make

Section titled “make”

Creates a schema from an AST (Abstract Syntax Tree) node.

Details

This is the fundamental constructor for all schemas in the Effect Schema library. It takes an AST node and wraps it in a fully-typed schema that preserves all type information and provides the complete schema API.

The make function is used internally to create all primitive schemas like String, Number, Boolean, etc., as well as more complex schemas. It’s the bridge between the untyped AST representation and the strongly-typed schema.

Signature

declare const make: <S extends Constraint>(ast: S["ast"], options?: object) => S

Source

Since v3.10.0

makeFilter

Section titled “makeFilter”

Creates a custom validation filter from a predicate function.

Details

The predicate receives the decoded input value, the schema AST, and parse options, and returns a FilterOutput. Non-success outputs are normalized into schema issues. The annotations parameter annotates the filter itself; with the default formatter, failures use message first, expected second, and <filter> when neither is provided.

When abort is true, parsing stops after this filter fails instead of collecting later check failures.

Example (Reporting failure at a nested path)

import { Schema } from "effect"


const schema = Schema.Struct({ password: Schema.String, confirmPassword: Schema.String }).check(
  Schema.makeFilter((o) =>
    o.password === o.confirmPassword
      ? undefined
      : { path: ["password"], issue: "password and confirmPassword must match" }
  )
)


console.log(String(Schema.decodeUnknownExit(schema)({ password: "123456", confirmPassword: "1234567" })))
// Failure(Cause([Fail(SchemaError: password and confirmPassword must match
//   at ["password"])]))

Example (Reporting multiple failures at once)

import { Schema } from "effect"


const schema = Schema.Struct({ a: Schema.Finite, b: Schema.Finite, c: Schema.Finite }).check(
  Schema.makeFilter((o) => {
    const issues: Array<Schema.FilterIssue> = []
    if (o.a > 0) {
      if (o.b <= 0) issues.push({ path: ["b"], issue: "b must be greater than 0" })
      if (o.c <= 0) issues.push({ path: ["c"], issue: "c must be greater than 0" })
    }
    return issues
  })
)


console.log(String(Schema.decodeUnknownExit(schema)({ a: 1, b: 0, c: 0 })))
// Failure(Cause([Fail(SchemaError: b must be greater than 0
//   at ["b"]
// c must be greater than 0
//   at ["c"])]))

Signature

declare const makeFilter: <T>(
  filter: (input: T, ast: SchemaAST.AST, options: SchemaAST.ParseOptions) => FilterOutput,
  annotations?: Annotations.Filter | undefined,
  abort?: boolean
) => SchemaAST.Filter<T>

Source

Since v4.0.0

makeFilterGroup

Section titled “makeFilterGroup”

Groups multiple checks into a single SchemaAST.FilterGroup, applying optional shared annotations to the group as a whole.

Signature

declare const makeFilterGroup: <T>(
  checks: readonly [SchemaAST.Check<T>, ...Array<SchemaAST.Check<T>>],
  annotations?: Annotations.Filter | undefined
) => SchemaAST.FilterGroup<T>

Source

Since v4.0.0

suspend

Section titled “suspend”

Creates a suspended schema that defers evaluation until needed. This is essential for creating recursive schemas where a schema references itself, preventing infinite recursion during schema definition.

Example (Defining recursive tree schemas)

import { Schema } from "effect"


interface Tree {
  readonly value: number
  readonly children: ReadonlyArray<Tree>
}


const Tree = Schema.Struct({
  value: Schema.Number,
  children: Schema.Array(Schema.suspend((): Schema.Codec<Tree> => Tree))
})

Signature

declare const suspend: <S extends Constraint>(f: () => S) => suspend<S>

Source

Since v3.10.0

tag

Section titled “tag”

Combines a Literal schema with withConstructorDefault, making it ideal for discriminator fields in tagged unions. When constructing via make, the _tag field can be omitted and will be filled automatically.

Example (Defining a discriminated union tag)

import { Schema } from "effect"


const A = Schema.Struct({ _tag: Schema.tag("A"), value: Schema.Number })


// _tag is optional in make, auto-filled to "A"
const a = A.make({ value: 42 })
// a: { _tag: "A", value: 42 }

See

  • tagDefaultOmit to also omit the tag during encoding
  • TaggedStruct for a shorthand that adds _tag automatically

Signature

declare const tag: <Tag extends SchemaAST.LiteralValue>(literal: Tag) => tag<Tag>

Source

Since v3.10.0

tag (interface)

Section titled “tag (interface)”

Type-level representation returned by tag.

Signature

export interface tag<Tag extends SchemaAST.LiteralValue> extends withConstructorDefault<Literal<Tag>> {}

Source

Since v3.10.0

tagDefaultOmit

Section titled “tagDefaultOmit”

Creates a literal _tag schema that is omitted from encoded output.

When to use

Use to decode data that omits the discriminator field while still constructing values with a _tag for tagged union matching.

Details

The tag is filled during decoding and construction, like tag, but is omitted when encoding.

Example (Omitting tags during encoding)

import { Schema } from "effect"


const A = Schema.Struct({
  _tag: Schema.tagDefaultOmit("A"),
  value: Schema.Number
})


// Encode strips the _tag field
const encoded = Schema.encodeUnknownSync(A)({ _tag: "A", value: 1 })
// encoded: { value: 1 }

See

  • tag for the variant that keeps the tag during encoding

Signature

declare const tagDefaultOmit: <Tag extends SchemaAST.LiteralValue>(
  literal: Tag
) => withDecodingDefaultKey<tag<Tag>, never>

Source

Since v4.0.0

withConstructorDefault

Section titled “withConstructorDefault”

Attaches a constructor default value to a schema field.

Details

Constructor defaults are applied only during make*, not during decoding or encoding.

Example (Defining an optional field with a static default)

import { Effect, Schema } from "effect"


const MySchema = Schema.Struct({
  name: Schema.String.pipe(Schema.optionalKey, Schema.withConstructorDefault(Effect.succeed("anonymous")))
})


const value = MySchema.make({})
// value: { name: "anonymous" }

Signature

declare const withConstructorDefault: <S extends Constraint & WithoutConstructorDefault>(
  defaultValue: Effect.Effect<S["~type.make.in"], SchemaError>
) => (schema: S) => withConstructorDefault<S>

Source

Since v3.10.0

withConstructorDefault (interface)

Section titled “withConstructorDefault (interface)”

Type-level representation returned by withConstructorDefault.

Signature

export interface withConstructorDefault<S extends Constraint & WithoutConstructorDefault> extends BottomLazy<
  S["ast"],
  withConstructorDefault<S>,
  S["~type.parameters"],
  S["~type.mutability"],
  S["~type.optionality"],
  "with-default",
  S["~encoded.mutability"],
  S["~encoded.optionality"]
> {
  readonly Type: S["Type"]
  readonly Encoded: S["Encoded"]
  readonly DecodingServices: S["DecodingServices"]
  readonly EncodingServices: S["EncodingServices"]
  readonly "~type.make.in": S["~type.make.in"]
  readonly "~type.make": S["~type.make"]
  readonly Iso: S["Iso"]
  readonly schema: S
}

Source

Since v3.10.0

converting

Section titled “converting”

toDifferJsonPatch

Section titled “toDifferJsonPatch”

Derives a JSON Patch differ from a codec. Serializes values to JSON (via toCodecJson), computes RFC 6902 JSON Patch operations between old and new values, and can apply patches back to the typed value.

Signature

declare const toDifferJsonPatch: <T, E>(schema: Codec<T, E>) => Differ<T, JsonPatch.JsonPatch>

Source

Since v4.0.0

toJsonSchemaDocument

Section titled “toJsonSchemaDocument”

Returns a JSON Schema document using draft 2020-12.

Details

The options parameter controls generation details such as additional properties and synthesized check descriptions; it does not change the draft target.

Gotchas

JSON Schema generation is best-effort. Some Effect schema semantics cannot be represented exactly in JSON Schema, and importing an emitted JSON Schema may produce an equivalent approximation rather than the original schema shape.

Signature

declare const toJsonSchemaDocument: (
  schema: Constraint,
  options?: ToJsonSchemaOptions
) => JsonSchema.Document<"draft-2020-12">

Source

Since v4.0.0

decoding

Section titled “decoding”

decodeEffect

Section titled “decodeEffect”

Decodes a typed input (the schema’s Encoded type) against a schema, returning an Effect that succeeds with the decoded value or fails with a SchemaError.

When to use

Use when you need to decode input already typed as the schema’s Encoded type in an Effect whose failure channel is SchemaError.

Details

For unknown input use decodeUnknownEffect. Options may be provided either when creating the decoder or when applying it; application options override creation options.

See

  • SchemaParser.decodeEffect for the adapter that fails with SchemaIssue.Issue directly

Signature

declare const decodeEffect: <S extends Constraint>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (
  input: S["Encoded"],
  options?: SchemaAST.ParseOptions
) => Effect.Effect<S["Type"], SchemaError, S["DecodingServices"]>

Source

Since v4.0.0

decodeExit

Section titled “decodeExit”

Decodes a typed input (the schema’s Encoded type) against a schema synchronously, returning an Exit that is either a Success with the decoded value or a Failure.

When to use

Use when you need to decode already typed Encoded input into an Exit and capture schema mismatches as SchemaError.

Details

Only usable with schemas that have no DecodingServices requirement. For unknown input use decodeUnknownExit. Options may be provided either when creating the decoder or when applying it; application options override creation options. Schema mismatches are represented by a Failure cause containing SchemaError.

Gotchas

Schema issue fail reasons are wrapped as SchemaError. Defects, interruptions, and other non-schema reasons remain in the returned Cause, including when they are mixed with schema issues.

See

  • SchemaParser.decodeExit for the adapter whose failure contains SchemaIssue.Issue directly

Signature

declare const decodeExit: <S extends ConstraintDecoder<unknown>>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (input: S["Encoded"], options?: SchemaAST.ParseOptions) => Exit_.Exit<S["Type"], SchemaError>

Source

Since v4.0.0

decodeOption

Section titled “decodeOption”

Decodes a typed input (the schema’s Encoded type) against a schema, returning an Option that is Some with the decoded value on success or None for schema mismatches.

When to use

Use when you already have input typed as the schema’s Encoded type and only need to know whether decoding succeeded.

Details

For unknown input use decodeUnknownOption. Options may be provided either when creating the decoder or when applying it; application options override creation options.

Gotchas

Only causes made entirely of schema issues are converted to None. Causes that contain defects, interruptions, or other non-schema reasons throw instead.

Signature

declare const decodeOption: <S extends ConstraintDecoder<unknown>>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (input: S["Encoded"], options?: SchemaAST.ParseOptions) => Option_.Option<S["Type"]>

Source

Since v3.10.0

decodePromise

Section titled “decodePromise”

Decodes a typed input (the schema’s Encoded type) against a schema, returning a Promise that resolves with the decoded value or rejects with a SchemaError for schema mismatches.

When to use

Use when you already have input typed as the schema’s Encoded type and need decoding to return a JavaScript Promise that rejects with SchemaError for schema mismatches.

Details

For unknown input use decodeUnknownPromise. Options may be provided either when creating the decoder or when applying it; application options override creation options.

Gotchas

Non-schema failures may reject with a runtime failure instead of SchemaError.

See

  • SchemaParser.decodePromise for the adapter that rejects with an Error whose cause is SchemaIssue.Issue

Signature

declare const decodePromise: <S extends ConstraintDecoder<unknown>>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (input: S["Encoded"], options?: SchemaAST.ParseOptions) => Promise<S["Type"]>

Source

Since v3.10.0

decodeResult

Section titled “decodeResult”

Decodes a typed input (the schema’s Encoded type) against a schema, returning a Result that succeeds with the decoded value or fails with a SchemaError for schema mismatches.

When to use

Use when you already have input typed as the schema’s Encoded type and want schema mismatches returned as Result.fail with SchemaError.

Details

For unknown input use decodeUnknownResult. Options may be provided either when creating the decoder or when applying it; application options override creation options. Schema mismatches are returned as Result.fail with SchemaError.

Gotchas

Only causes made entirely of schema issues are returned as Result.fail. Causes that contain defects, interruptions, or other non-schema reasons throw instead.

See

  • SchemaParser.decodeResult for the adapter that fails with SchemaIssue.Issue directly

Signature

declare const decodeResult: <S extends ConstraintDecoder<unknown>>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (input: S["Encoded"], options?: SchemaAST.ParseOptions) => Result_.Result<S["Type"], SchemaError>

Source

Since v4.0.0

decodeSync

Section titled “decodeSync”

Decodes a typed input (the schema’s Encoded type) against a schema synchronously, returning the decoded value or throwing a SchemaError for schema mismatches.

When to use

Use when you already have input typed as the schema’s Encoded type and want schema mismatches to throw SchemaError synchronously.

Details

For unknown input use decodeUnknownSync. Only service-free schemas can be decoded synchronously. Options may be provided either when creating the decoder or when applying it; application options override creation options.

Gotchas

Non-schema failures may throw a runtime failure instead of SchemaError.

See

  • SchemaParser.decodeSync for the adapter that throws an Error whose cause is SchemaIssue.Issue

Signature

declare const decodeSync: <S extends ConstraintDecoder<unknown>>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (input: S["Encoded"], options?: SchemaAST.ParseOptions) => S["Type"]

Source

Since v4.0.0

decodeUnknownEffect

Section titled “decodeUnknownEffect”

Decodes an unknown input against a schema, returning an Effect that succeeds with the decoded value or fails with a SchemaError.

When to use

Use when you need to decode unknown input in an Effect whose failure channel is SchemaError.

Details

Prefer decodeEffect when the input is already typed as the schema’s Encoded type. Options may be provided either when creating the decoder or when applying it; application options override creation options.

See

  • SchemaParser.decodeUnknownEffect for the adapter that fails with SchemaIssue.Issue directly

Signature

declare const decodeUnknownEffect: <S extends Constraint>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (input: unknown, options?: SchemaAST.ParseOptions) => Effect.Effect<S["Type"], SchemaError, S["DecodingServices"]>

Source

Since v4.0.0

decodeUnknownExit

Section titled “decodeUnknownExit”

Decodes an unknown input against a schema synchronously, returning an Exit that is either a Success with the decoded value or a Failure.

When to use

Use when you need to decode unknown input into an Exit and capture schema mismatches as SchemaError.

Details

Only usable with schemas that have no DecodingServices requirement. Prefer decodeExit when the input is already typed as the schema’s Encoded type. Options may be provided either when creating the decoder or when applying it; application options override creation options. Schema mismatches are represented by a Failure cause containing SchemaError.

Gotchas

Schema issue fail reasons are wrapped as SchemaError. Defects, interruptions, and other non-schema reasons remain in the returned Cause, including when they are mixed with schema issues.

See

  • SchemaParser.decodeUnknownExit for the adapter whose failure contains SchemaIssue.Issue directly

Signature

declare const decodeUnknownExit: <S extends ConstraintDecoder<unknown>>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (input: unknown, options?: SchemaAST.ParseOptions) => Exit_.Exit<S["Type"], SchemaError>

Source

Since v4.0.0

decodeUnknownOption

Section titled “decodeUnknownOption”

Decodes an unknown input against a schema, returning an Option that is Some with the decoded value on success or None for schema mismatches.

When to use

Use when you do not know the input type statically and only need to know whether decoding succeeded.

Details

Prefer this over decodeUnknownExit or decodeUnknownEffect when you don’t need error details. For input already typed as the schema’s Encoded type use decodeOption. Options may be provided either when creating the decoder or when applying it; application options override creation options.

Gotchas

Only causes made entirely of schema issues are converted to None. Causes that contain defects, interruptions, or other non-schema reasons throw instead.

Signature

declare const decodeUnknownOption: <S extends ConstraintDecoder<unknown>>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (input: unknown, options?: SchemaAST.ParseOptions) => Option_.Option<S["Type"]>

Source

Since v3.10.0

decodeUnknownPromise

Section titled “decodeUnknownPromise”

Decodes an unknown input against a schema, returning a Promise that resolves with the decoded value or rejects with a SchemaError for schema mismatches.

When to use

Use when you need decoding of unknown input to return a JavaScript Promise that rejects with SchemaError for schema mismatches.

Details

For input already typed as the schema’s Encoded type use decodePromise. Options may be provided either when creating the decoder or when applying it; application options override creation options.

Gotchas

Non-schema failures may reject with a runtime failure instead of SchemaError.

See

  • SchemaParser.decodeUnknownPromise for the adapter that rejects with an Error whose cause is SchemaIssue.Issue

Signature

declare const decodeUnknownPromise: <S extends ConstraintDecoder<unknown>>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (input: unknown, options?: SchemaAST.ParseOptions) => Promise<S["Type"]>

Source

Since v3.10.0

decodeUnknownResult

Section titled “decodeUnknownResult”

Decodes an unknown input against a schema, returning a Result that succeeds with the decoded value or fails with a SchemaError for schema mismatches.

When to use

Use when you do not know the input type statically and want schema mismatches returned as Result.fail with SchemaError.

Details

For input already typed as the schema’s Encoded type use decodeResult. Options may be provided either when creating the decoder or when applying it; application options override creation options. Schema mismatches are returned as Result.fail with SchemaError.

Gotchas

Only causes made entirely of schema issues are returned as Result.fail. Causes that contain defects, interruptions, or other non-schema reasons throw instead.

See

  • SchemaParser.decodeUnknownResult for the adapter that fails with SchemaIssue.Issue directly

Signature

declare const decodeUnknownResult: <S extends ConstraintDecoder<unknown>>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (input: unknown, options?: SchemaAST.ParseOptions) => Result_.Result<S["Type"], SchemaError>

Source

Since v4.0.0

decodeUnknownSync

Section titled “decodeUnknownSync”

Decodes an unknown input against a schema synchronously, returning the decoded value or throwing a SchemaError for schema mismatches.

When to use

Use when you need to validate unknown data at a synchronous boundary and want schema mismatches to throw SchemaError.

Details

For input already typed as the schema’s Encoded type use decodeSync. Only service-free schemas can be decoded synchronously. For alternatives that do not throw on schema mismatches, see decodeUnknownOption, decodeUnknownExit, or decodeUnknownEffect. Options may be provided either when creating the decoder or when applying it; application options override creation options.

Gotchas

Non-schema failures may throw a runtime failure instead of SchemaError.

Example (Decoding with a transformation schema)

import { Schema } from "effect"


const NumberFromString = Schema.NumberFromString


console.log(Schema.decodeUnknownSync(NumberFromString)("42"))
// Output: 42


Schema.decodeUnknownSync(NumberFromString)("not a number")
// throws SchemaError: NumberFromString
//   └─ Encoded side transformation failure
//      └─ NumberFromString
//         └─ Expected a numeric string, actual "not a number"

See

  • SchemaParser.decodeUnknownSync for the adapter that throws an Error whose cause is SchemaIssue.Issue

Signature

declare const decodeUnknownSync: <S extends ConstraintDecoder<unknown>>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (input: unknown, options?: SchemaAST.ParseOptions) => S["Type"]

Source

Since v4.0.0

fromFormData

Section titled “fromFormData”

Schema for decoding FormData through a bracket-notation tree.

When to use

Use to decode browser or multipart form data into a structured schema value.

Details

The decoding process has two steps:

  1. Parse FormData into a nested tree record.
  2. Decode the parsed value with the given schema.

You can express nested values using bracket notation.

If you want to decode string fields into non-string primitive values, use Schema.toCodecStringTree.

Example (Decoding a flat structure)

import { Schema } from "effect"


const schema = Schema.fromFormData(
  Schema.Struct({
    a: Schema.String
  })
)


const formData = new FormData()
formData.append("a", "1")
formData.append("b", "2")


console.log(String(Schema.decodeUnknownExit(schema)(formData)))
// Success({"a":"1"})

Example (Decoding nested fields)

import { Schema } from "effect"


const schema = Schema.fromFormData(
  Schema.Struct({
    a: Schema.String,
    b: Schema.Struct({
      c: Schema.String,
      d: Schema.String
    })
  })
)


const formData = new FormData()
formData.append("a", "1")
formData.append("b[c]", "2")
formData.append("b[d]", "3")


console.log(String(Schema.decodeUnknownExit(schema)(formData)))
// Success({"a":"1","b":{"c":"2","d":"3"}})

Example (Parsing non-string values)

import { Schema } from "effect"


const schema = Schema.fromFormData(
  Schema.toCodecStringTree(
    Schema.Struct({
      a: Schema.Int
    })
  )
)


const formData = new FormData()
formData.append("a", "1")


console.log(String(Schema.decodeUnknownExit(schema)(formData)))
// Success({"a":1}) // Note: the value is a number

Signature

declare const fromFormData: <S extends Constraint>(schema: S) => fromFormData<S>

Source

Since v4.0.0

fromURLSearchParams

Section titled “fromURLSearchParams”

Schema for decoding URLSearchParams through a bracket-notation tree.

When to use

Use to decode query parameters into a structured schema value.

Details

The decoding process has two steps:

  1. Parse URLSearchParams into a nested tree record.
  2. Decode the parsed value with the given schema.

You can express nested values using bracket notation.

If you want to decode values that are not strings, use Schema.toCodecStringTree. This serializer preserves values such as numbers when compatible with the schema.

Example (Decoding a flat structure)

import { Schema } from "effect"


const schema = Schema.fromURLSearchParams(
  Schema.Struct({
    a: Schema.String
  })
)


const urlSearchParams = new URLSearchParams("a=1&b=2")


console.log(String(Schema.decodeUnknownExit(schema)(urlSearchParams)))
// Success({"a":"1"})

Example (Decoding nested fields)

import { Schema } from "effect"


const schema = Schema.fromURLSearchParams(
  Schema.Struct({
    a: Schema.String,
    b: Schema.Struct({
      c: Schema.String,
      d: Schema.String
    })
  })
)


const urlSearchParams = new URLSearchParams("a=1&b[c]=2&b[d]=3")


console.log(String(Schema.decodeUnknownExit(schema)(urlSearchParams)))
// Success({"a":"1","b":{"c":"2","d":"3"}})

Example (Parsing non-string values)

import { Schema } from "effect"


const schema = Schema.fromURLSearchParams(
  Schema.toCodecStringTree(
    Schema.Struct({
      a: Schema.Int
    })
  )
)


const urlSearchParams = new URLSearchParams("a=1&b=2")


console.log(String(Schema.decodeUnknownExit(schema)(urlSearchParams)))
// Success({"a":1}) // Note: the value is a number

Signature

declare const fromURLSearchParams: <S extends Constraint>(schema: S) => fromURLSearchParams<S>

Source

Since v4.0.0

middlewareDecoding

Section titled “middlewareDecoding”

Intercepts the decoding pipeline of a schema.

Details

The provided function receives the current decoding Effect and ParseOptions, and returns a new Effect — potentially adding service requirements (RD), recovering from errors, or augmenting the result.

Example (Logging decode failures)

import { Effect, Schema } from "effect"


const Logged = Schema.String.pipe(
  Schema.middlewareDecoding((effect) => Effect.tapError(effect, (issue) => Effect.log("decode failed", issue)))
)

See

  • catchDecoding for a simpler error-recovery variant

Signature

declare const middlewareDecoding: <S extends Constraint, RD>(
  decode: (
    effect: Effect.Effect<Option_.Option<S["Type"]>, SchemaIssue.Issue, S["DecodingServices"]>,
    options: SchemaAST.ParseOptions
  ) => Effect.Effect<Option_.Option<S["Type"]>, SchemaIssue.Issue, RD>
) => (schema: S) => middlewareDecoding<S, RD>

Source

Since v4.0.0

middlewareDecoding (interface)

Section titled “middlewareDecoding (interface)”

Type-level representation returned by middlewareDecoding.

Signature

export interface middlewareDecoding<S extends Constraint, RD> extends BottomLazy<
  S["ast"],
  middlewareDecoding<S, RD>,
  S["~type.parameters"],
  S["~type.mutability"],
  S["~type.optionality"],
  S["~type.constructor.default"],
  S["~encoded.mutability"],
  S["~encoded.optionality"]
> {
  readonly Type: S["Type"]
  readonly Encoded: S["Encoded"]
  readonly DecodingServices: RD
  readonly EncodingServices: S["EncodingServices"]
  readonly "~type.make.in": S["~type.make.in"]
  readonly "~type.make": S["~type.make"]
  readonly Iso: S["Iso"]
  readonly schema: S
}

Source

Since v4.0.0

withDecodingDefault

Section titled “withDecodingDefault”

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" }

See

  • withDecodingDefaultKey for the key-level variant (key absent only, not undefined)
  • withDecodingDefaultType for the variant where the default is a Type value

Signature

declare const withDecodingDefault: <S extends Constraint, R = never>(
  defaultValue: Effect.Effect<S["Encoded"], SchemaError, R>,
  options?: DecodingDefaultOptions
) => (self: S) => withDecodingDefault<S, R>

Source

Since v3.10.0

withDecodingDefault (interface)

Section titled “withDecodingDefault (interface)”

Type-level representation returned by withDecodingDefault.

Signature

export interface withDecodingDefault<S extends Constraint, R = never> extends decodeTo<S, optional<toEncoded<S>>, R> {
  readonly Rebuild: withDecodingDefault<S, R>
}

Source

Since v3.10.0

withDecodingDefaultKey

Section titled “withDecodingDefaultKey”

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" }

See

  • withDecodingDefault for the value-level variant (key absent or undefined)
  • withDecodingDefaultTypeKey for the variant where the default is a Type value

Signature

declare const withDecodingDefaultKey: <S extends Constraint, R = never>(
  defaultValue: Effect.Effect<S["Encoded"], SchemaError, R>,
  options?: DecodingDefaultOptions
) => (self: S) => withDecodingDefaultKey<S, R>

Source

Since v4.0.0

withDecodingDefaultKey (interface)

Section titled “withDecodingDefaultKey (interface)”

Type-level representation returned by withDecodingDefaultKey.

Signature

export interface withDecodingDefaultKey<S extends Constraint, R = never> extends decodeTo<
  S,
  optionalKey<toEncoded<S>>,
  R
> {
  readonly Rebuild: withDecodingDefaultKey<S, R>
}

Source

Since v4.0.0

withDecodingDefaultType

Section titled “withDecodingDefaultType”

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.

See

  • withDecodingDefault for the variant where the default is an Encoded value
  • withDecodingDefaultTypeKey for the key-level variant

Signature

declare const withDecodingDefaultType: <S extends Constraint, R = never>(
  defaultValue: Effect.Effect<S["Type"], SchemaError, R>,
  options?: DecodingDefaultOptions
) => (self: S) => withDecodingDefaultType<S, R>

Source

Since v4.0.0

withDecodingDefaultType (interface)

Section titled “withDecodingDefaultType (interface)”

Type-level representation returned by withDecodingDefaultType.

Signature

export interface withDecodingDefaultType<S extends Constraint, R = never> extends decodeTo<
  withDecodingDefault<toType<S>, R>,
  optional<S>
> {
  readonly Rebuild: withDecodingDefaultType<S, R>
}

Source

Since v4.0.0

withDecodingDefaultTypeKey

Section titled “withDecodingDefaultTypeKey”

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.

See

  • withDecodingDefaultKey for the variant where the default is an Encoded value
  • withDecodingDefaultType for the value-level variant

Signature

declare const withDecodingDefaultTypeKey: <S extends Constraint, R = never>(
  defaultValue: Effect.Effect<S["Type"], SchemaError, R>,
  options?: DecodingDefaultOptions
) => (self: S) => withDecodingDefaultTypeKey<S, R>

Source

Since v4.0.0

withDecodingDefaultTypeKey (interface)

Section titled “withDecodingDefaultTypeKey (interface)”

Type-level representation returned by withDecodingDefaultTypeKey.

Signature

export interface withDecodingDefaultTypeKey<S extends Constraint, R = never> extends decodeTo<
  withDecodingDefaultKey<toType<S>, R>,
  optionalKey<S>
> {
  readonly Rebuild: withDecodingDefaultTypeKey<S, R>
}

Source

Since v4.0.0

encoding

Section titled “encoding”

encodeEffect

Section titled “encodeEffect”

Encodes a typed input (the schema’s Type) against a schema, returning an Effect that succeeds with the encoded value or fails with a SchemaError.

When to use

Use when you need to encode input already typed as the schema’s Type in an Effect whose failure channel is SchemaError.

Details

For unknown input use encodeUnknownEffect. Options may be provided either when creating the encoder or when applying it; application options override creation options.

See

  • SchemaParser.encodeEffect for the adapter that fails with SchemaIssue.Issue directly

Signature

declare const encodeEffect: <S extends Constraint>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (
  input: S["Type"],
  options?: SchemaAST.ParseOptions
) => Effect.Effect<S["Encoded"], SchemaError, S["EncodingServices"]>

Source

Since v4.0.0

encodeExit

Section titled “encodeExit”

Encodes a typed input (the schema’s Type) against a schema synchronously, returning an Exit that is either a Success with the encoded value or a Failure.

When to use

Use when you need to encode already typed schema values into an Exit and capture schema mismatches as SchemaError.

Details

Only usable with schemas that have no EncodingServices requirement. For unknown input use encodeUnknownExit. Options may be provided either when creating the encoder or when applying it; application options override creation options. Schema mismatches are represented by a Failure cause containing SchemaError.

Gotchas

Schema issue fail reasons are wrapped as SchemaError. Defects, interruptions, and other non-schema reasons remain in the returned Cause, including when they are mixed with schema issues.

See

  • SchemaParser.encodeExit for the adapter whose failure contains SchemaIssue.Issue directly

Signature

declare const encodeExit: <S extends ConstraintEncoder<unknown>>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (input: S["Type"], options?: SchemaAST.ParseOptions) => Exit_.Exit<S["Encoded"], SchemaError>

Source

Since v4.0.0

encodeOption

Section titled “encodeOption”

Encodes a typed input (the schema’s Type) against a schema, returning an Option that is Some with the encoded value on success or None for schema mismatches.

When to use

Use when you already have a value typed as the schema’s Type and only need to know whether encoding succeeded.

Details

For unknown input use encodeUnknownOption. Options may be provided either when creating the encoder or when applying it; application options override creation options.

Gotchas

Only causes made entirely of schema issues are converted to None. Causes that contain defects, interruptions, or other non-schema reasons throw instead.

Signature

declare const encodeOption: <S extends ConstraintEncoder<unknown>>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (input: S["Type"], options?: SchemaAST.ParseOptions) => Option_.Option<S["Encoded"]>

Source

Since v3.10.0

encodePromise

Section titled “encodePromise”

Encodes a typed input (the schema’s Type) against a schema, returning a Promise that resolves with the encoded value or rejects with a SchemaError for schema mismatches.

When to use

Use when you already have a value typed as the schema’s Type and need encoding to return a JavaScript Promise that rejects with SchemaError for schema mismatches.

Details

For unknown input use encodeUnknownPromise. Options may be provided either when creating the encoder or when applying it; application options override creation options.

Gotchas

Non-schema failures may reject with a runtime failure instead of SchemaError.

See

  • SchemaParser.encodePromise for the adapter that rejects with an Error whose cause is SchemaIssue.Issue

Signature

declare const encodePromise: <S extends ConstraintEncoder<unknown>>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (input: S["Type"], options?: SchemaAST.ParseOptions) => Promise<S["Encoded"]>

Source

Since v3.10.0

encodeResult

Section titled “encodeResult”

Encodes a typed input (the schema’s Type) against a schema, returning a Result that succeeds with the encoded value or fails with a SchemaError for schema mismatches.

When to use

Use when you already have a value typed as the schema’s Type and want schema mismatches returned as Result.fail with SchemaError.

Details

For unknown input use encodeUnknownResult. Options may be provided either when creating the encoder or when applying it; application options override creation options. Schema mismatches are returned as Result.fail with SchemaError.

Gotchas

Only causes made entirely of schema issues are returned as Result.fail. Causes that contain defects, interruptions, or other non-schema reasons throw instead.

See

  • SchemaParser.encodeResult for the adapter that fails with SchemaIssue.Issue directly

Signature

declare const encodeResult: <S extends ConstraintEncoder<unknown>>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (input: S["Type"], options?: SchemaAST.ParseOptions) => Result_.Result<S["Encoded"], SchemaError>

Source

Since v4.0.0

encodeSync

Section titled “encodeSync”

Encodes a typed input (the schema’s Type) against a schema synchronously, throwing a SchemaError for schema mismatches.

When to use

Use when you already have a value typed as the schema’s Type and want schema mismatches to throw SchemaError synchronously.

Details

For unknown input use encodeUnknownSync. Options may be provided either when creating the encoder or when applying it; application options override creation options.

Gotchas

Non-schema failures may throw a runtime failure instead of SchemaError.

See

  • SchemaParser.encodeSync for the adapter that throws an Error whose cause is SchemaIssue.Issue

Signature

declare const encodeSync: <S extends ConstraintEncoder<unknown>>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (input: S["Type"], options?: SchemaAST.ParseOptions) => S["Encoded"]

Source

Since v4.0.0

encodeUnknownEffect

Section titled “encodeUnknownEffect”

Encodes an unknown input against a schema, returning an Effect that succeeds with the encoded value or fails with a SchemaError.

When to use

Use when you need to encode unknown input in an Effect whose failure channel is SchemaError.

Details

Prefer encodeEffect when the value is already typed as the schema’s Type. Options may be provided either when creating the encoder or when applying it; application options override creation options.

Example (Encoding a value to a string)

import { Effect, Schema } from "effect"


const NumberFromString = Schema.NumberFromString


Effect.runPromise(Schema.encodeUnknownEffect(NumberFromString)(42)).then(console.log)
// Output: "42"

See

  • SchemaParser.encodeUnknownEffect for the adapter that fails with SchemaIssue.Issue directly

Signature

declare const encodeUnknownEffect: <S extends Constraint>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (
  input: unknown,
  options?: SchemaAST.ParseOptions
) => Effect.Effect<S["Encoded"], SchemaError, S["EncodingServices"]>

Source

Since v4.0.0

encodeUnknownExit

Section titled “encodeUnknownExit”

Encodes an unknown input against a schema synchronously, returning an Exit that is either a Success with the encoded value or a Failure.

When to use

Use when you need to encode unknown input into an Exit and capture schema mismatches as SchemaError.

Details

Only usable with schemas that have no EncodingServices requirement. Prefer encodeExit when the value is already typed as the schema’s Type. Options may be provided either when creating the encoder or when applying it; application options override creation options. Schema mismatches are represented by a Failure cause containing SchemaError.

Gotchas

Schema issue fail reasons are wrapped as SchemaError. Defects, interruptions, and other non-schema reasons remain in the returned Cause, including when they are mixed with schema issues.

See

  • SchemaParser.encodeUnknownExit for the adapter whose failure contains SchemaIssue.Issue directly

Signature

declare const encodeUnknownExit: <S extends ConstraintEncoder<unknown>>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (input: unknown, options?: SchemaAST.ParseOptions) => Exit_.Exit<S["Encoded"], SchemaError>

Source

Since v4.0.0

encodeUnknownOption

Section titled “encodeUnknownOption”

Encodes an unknown input against a schema, returning an Option that is Some with the encoded value on success or None for schema mismatches.

When to use

Use when you do not know the input type statically and only need to know whether encoding succeeded.

Details

Prefer this over encodeUnknownExit or encodeUnknownEffect when you don’t need error details. For values already typed as the schema’s Type use encodeOption. Options may be provided either when creating the encoder or when applying it; application options override creation options.

Gotchas

Only causes made entirely of schema issues are converted to None. Causes that contain defects, interruptions, or other non-schema reasons throw instead.

Signature

declare const encodeUnknownOption: <S extends ConstraintEncoder<unknown>>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (input: unknown, options?: SchemaAST.ParseOptions) => Option_.Option<S["Encoded"]>

Source

Since v3.10.0

encodeUnknownPromise

Section titled “encodeUnknownPromise”

Encodes an unknown input against a schema, returning a Promise that resolves with the encoded value or rejects with a SchemaError for schema mismatches.

When to use

Use when you need encoding of unknown input to return a JavaScript Promise that rejects with SchemaError for schema mismatches.

Details

For values already typed as the schema’s Type use encodePromise. Options may be provided either when creating the encoder or when applying it; application options override creation options.

Gotchas

Non-schema failures may reject with a runtime failure instead of SchemaError.

See

  • SchemaParser.encodeUnknownPromise for the adapter that rejects with an Error whose cause is SchemaIssue.Issue

Signature

declare const encodeUnknownPromise: <S extends ConstraintEncoder<unknown>>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (input: unknown, options?: SchemaAST.ParseOptions) => Promise<S["Encoded"]>

Source

Since v3.10.0

encodeUnknownResult

Section titled “encodeUnknownResult”

Encodes an unknown input against a schema, returning a Result that succeeds with the encoded value or fails with a SchemaError for schema mismatches.

When to use

Use when you do not know the input type statically and want schema mismatches returned as Result.fail with SchemaError.

Details

For values already typed as the schema’s Type use encodeResult. Options may be provided either when creating the encoder or when applying it; application options override creation options. Schema mismatches are returned as Result.fail with SchemaError.

Gotchas

Only causes made entirely of schema issues are returned as Result.fail. Causes that contain defects, interruptions, or other non-schema reasons throw instead.

See

  • SchemaParser.encodeUnknownResult for the adapter that fails with SchemaIssue.Issue directly

Signature

declare const encodeUnknownResult: <S extends ConstraintEncoder<unknown>>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (input: unknown, options?: SchemaAST.ParseOptions) => Result_.Result<S["Encoded"], SchemaError>

Source

Since v4.0.0

encodeUnknownSync

Section titled “encodeUnknownSync”

Encodes an unknown input against a schema synchronously, throwing a SchemaError for schema mismatches.

When to use

Use when you need to serialize unknown data at a synchronous boundary and want schema mismatches to throw SchemaError.

Details

For alternatives that do not throw on schema mismatches, see encodeUnknownOption, encodeUnknownExit, or encodeUnknownEffect. For values already typed as the schema’s Type use encodeSync. Options may be provided either when creating the encoder or when applying it; application options override creation options.

Gotchas

Non-schema failures may throw a runtime failure instead of SchemaError.

See

  • SchemaParser.encodeUnknownSync for the adapter that throws an Error whose cause is SchemaIssue.Issue

Signature

declare const encodeUnknownSync: <S extends ConstraintEncoder<unknown>>(
  schema: S,
  options?: SchemaAST.ParseOptions
) => (input: unknown, options?: SchemaAST.ParseOptions) => S["Encoded"]

Source

Since v4.0.0

middlewareEncoding

Section titled “middlewareEncoding”

Intercepts the encoding pipeline of a schema.

Details

The provided function receives the current encoding Effect and ParseOptions, and returns a new Effect — potentially adding service requirements (RE), recovering from errors, or augmenting the result.

Example (Logging encode failures)

import { Effect, Schema } from "effect"


const Logged = Schema.String.pipe(
  Schema.middlewareEncoding((effect) => Effect.tapError(effect, (issue) => Effect.log("encode failed", issue)))
)

See

  • catchEncoding for a simpler error-recovery variant

Signature

declare const middlewareEncoding: <S extends Constraint, RE>(
  encode: (
    effect: Effect.Effect<Option_.Option<S["Encoded"]>, SchemaIssue.Issue, S["EncodingServices"]>,
    options: SchemaAST.ParseOptions
  ) => Effect.Effect<Option_.Option<S["Encoded"]>, SchemaIssue.Issue, RE>
) => (schema: S) => middlewareEncoding<S, RE>

Source

Since v4.0.0

middlewareEncoding (interface)

Section titled “middlewareEncoding (interface)”

Type-level representation returned by middlewareEncoding.

Signature

export interface middlewareEncoding<S extends Constraint, RE> extends BottomLazy<
  S["ast"],
  middlewareEncoding<S, RE>,
  S["~type.parameters"],
  S["~type.mutability"],
  S["~type.optionality"],
  S["~type.constructor.default"],
  S["~encoded.mutability"],
  S["~encoded.optionality"]
> {
  readonly Type: S["Type"]
  readonly Encoded: S["Encoded"]
  readonly DecodingServices: S["DecodingServices"]
  readonly EncodingServices: RE
  readonly "~type.make.in": S["~type.make.in"]
  readonly "~type.make": S["~type.make"]
  readonly Iso: S["Iso"]
  readonly schema: S
}

Source

Since v4.0.0

error handling

Section titled “error handling”

catchDecoding

Section titled “catchDecoding”

Recovers from a decoding error by providing a fallback value.

Details

The handler receives the Issue and returns an Effect that either succeeds with a fallback value or re-fails with a (possibly different) issue.

Example (Returning a default on decode failure)

import { Effect, Option, Schema } from "effect"


const schema = Schema.Number.pipe(Schema.catchDecoding((_issue) => Effect.succeed(Option.some(0))))

See

  • catchDecodingWithContext to add service requirements to the handler

Signature

declare const catchDecoding: <S extends Constraint>(
  f: (issue: SchemaIssue.Issue) => Effect.Effect<Option_.Option<S["Type"]>, SchemaIssue.Issue>
) => (self: S) => middlewareDecoding<S, S["DecodingServices"]>

Source

Since v4.0.0

catchDecodingWithContext

Section titled “catchDecodingWithContext”

Recovers from a decoding error with a handler that may require Effect services.

When to use

Use when you need decoding fallback logic to require services from the Effect context.

Details

The handler receives the Issue and returns an Effect that either succeeds with a fallback value or re-fails with a (possibly different) issue. The handler’s services are added to the schema’s decoding services.

See

  • catchDecoding for recovery handlers that do not require services
  • middlewareDecoding for intercepting or replacing the full decoding pipeline

Signature

declare const catchDecodingWithContext: <S extends Constraint, R = never>(
  f: (issue: SchemaIssue.Issue) => Effect.Effect<Option_.Option<S["Type"]>, SchemaIssue.Issue, R>
) => (self: S) => middlewareDecoding<S, S["DecodingServices"] | R>

Source

Since v4.0.0

catchEncoding

Section titled “catchEncoding”

Recovers from an encoding error by providing a fallback value.

Details

The handler receives the Issue and returns an Effect that either succeeds with a fallback value or re-fails with a (possibly different) issue.

See

  • catchEncodingWithContext to add service requirements to the handler

Signature

declare const catchEncoding: <S extends Constraint>(
  f: (issue: SchemaIssue.Issue) => Effect.Effect<Option_.Option<S["Encoded"]>, SchemaIssue.Issue>
) => (self: S) => middlewareEncoding<S, S["EncodingServices"]>

Source

Since v4.0.0

catchEncodingWithContext

Section titled “catchEncodingWithContext”

Recovers from an encoding error with a handler that may require Effect services.

When to use

Use when you need encoding fallback logic to require services from the Effect context.

Details

The handler receives the Issue and returns an Effect that either succeeds with a fallback encoded value or re-fails with a (possibly different) issue. The handler’s services are added to the schema’s encoding services.

See

  • catchEncoding for recovery handlers that do not require services
  • middlewareEncoding for intercepting or replacing the full encoding pipeline

Signature

declare const catchEncodingWithContext: <S extends Constraint, R = never>(
  f: (issue: SchemaIssue.Issue) => Effect.Effect<Option_.Option<S["Encoded"]>, SchemaIssue.Issue, R>
) => (self: S) => middlewareEncoding<S, S["EncodingServices"] | R>

Source

Since v4.0.0

errors

Section titled “errors”

SchemaError

Section titled “SchemaError”

Error thrown (or returned as the error channel value) when schema decoding or encoding fails.

Details

The issue field contains a structured SchemaIssue.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"
  }
}

Signature

declare const SchemaError: typeof InternalSchema.SchemaError

Source

Since v4.0.0

file

Section titled “file”

File

Section titled “File”

Schema for JavaScript File objects.

Details

The default JSON serializer encodes a File as { data, type, name, lastModified } where data is base64-encoded.

Signature

declare const File: File

Source

Since v4.0.0

File (interface)

Section titled “File (interface)”

Type-level representation of File.

Signature

export interface File extends instanceOf<globalThis.File> {
  readonly Rebuild: File
}

Source

Since v4.0.0

filtering

Section titled “filtering”

check

Section titled “check”

Attaches one or more filter checks to a schema without changing the TypeScript type.

Example (Adding checks to a schema)

import { Schema } from "effect"


const AgeSchema = Schema.Number.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(120)))

Signature

declare const check: <S extends Top>(
  checks_0: SchemaAST.Check<S["Type"]>,
  ...checks: Array<SchemaAST.Check<S["Type"]>>
) => (self: S) => S["Rebuild"]

Source

Since v4.0.0

refine

Section titled “refine”

Narrows the TypeScript type of a schema’s output via a type guard predicate, attaching the guard as a runtime filter check.

Details

The annotations parameter annotates the filter created by the refinement. With the default formatter, failed refinements use message first, expected second, and <filter> when neither is provided. identifier names type-level failures before the refinement runs; it does not name the failed refinement itself.

Signature

declare const refine: <S extends Constraint, T extends S["Type"]>(
  refinement: (value: S["Type"]) => value is T,
  annotations?: Annotations.Filter
) => (schema: S) => refine<T, S>

Source

Since v3.10.0

refine (interface)

Section titled “refine (interface)”

Type-level representation returned by refine.

Signature

export interface refine<T extends S["Type"], S extends Constraint> extends BottomLazy<
  S["ast"],
  refine<T, S>,
  S["~type.parameters"],
  S["~type.mutability"],
  S["~type.optionality"],
  S["~type.constructor.default"],
  S["~encoded.mutability"],
  S["~encoded.optionality"]
> {
  readonly Type: T
  readonly Encoded: S["Encoded"]
  readonly DecodingServices: S["DecodingServices"]
  readonly EncodingServices: S["EncodingServices"]
  readonly "~type.make.in": S["~type.make.in"]
  readonly "~type.make": T
  readonly Iso: T
  readonly schema: S
}

Source

Since v3.10.0

guards

Section titled “guards”

asserts

Section titled “asserts”

Creates an assertion function that throws an error if the input does not match the schema.

When to use

Use to validate unknown input at runtime while narrowing the value with a TypeScript assertion signature.

Details

The input is narrowed if the assertion succeeds. If schema validation fails, the assertion throws an Error whose cause is SchemaIssue.Issue.

Gotchas

Causes that contain defects, interruptions, or other non-schema reasons throw with the underlying Cause attached instead of being converted to schema validation errors.

Example (Asserting and narrowing an input)

import { Schema } from "effect"


const input: unknown = "hello"


// This will pass silently (no return value) and narrow input to string
Schema.asserts(Schema.String, input)
console.log(input.toUpperCase())


// This will throw an error
try {
  const invalid: unknown = 123
  Schema.asserts(Schema.String, invalid)
} catch (error) {
  console.log("Non-string assertion failed as expected")
}

Signature

declare const asserts: <S extends Constraint, I>(schema: S, input: I) => asserts input is I & S["Type"]

Source

Since v4.0.0

is

Section titled “is”

Creates a type guard function that checks if a value conforms to a given schema.

Details

This function returns a predicate that performs a type-safe check, narrowing the type of the input value if the check passes. The predicate returns false for schema mismatches.

Gotchas

Only causes made entirely of schema issues are converted to false. Causes that contain defects, interruptions, or other non-schema reasons throw instead.

Example (Defining a basic type guard)

import { Schema } from "effect"


const isString = Schema.is(Schema.String)


console.log(isString("hello")) // true
console.log(isString(42)) // false


// Type narrowing in action
const value: unknown = "hello"
if (isString(value)) {
  // value is now typed as string
  console.log(value.toUpperCase()) // "HELLO"
}

Signature

declare const is: <T>(schema: Schema<T>) => <I>(input: I) => input is I & T

Source

Since v3.10.0

isSchema

Section titled “isSchema”

Checks whether a value is a Schema.

Signature

declare const isSchema: (u: unknown) => u is Top

Source

Since v3.10.0

isSchemaError

Section titled “isSchemaError”

Returns true if u is a SchemaError.

Example (Narrowing Schema errors in a catch block)

import { Schema } from "effect"


try {
  Schema.decodeUnknownSync(Schema.Number)("oops")
} catch (err) {
  if (Schema.isSchemaError(err)) {
    console.log(err._tag) // "SchemaError"
  }
}

Signature

declare const isSchemaError: (u: unknown) => u is SchemaError

Source

Since v4.0.0

instances

Section titled “instances”

overrideToEquivalence

Section titled “overrideToEquivalence”

Overrides the equivalence derivation for a schema by supplying a custom Equivalence.

When to use

Use when you need a custom equivalence instead of the default structural equivalence derived by toEquivalence.

Signature

declare const overrideToEquivalence: <S extends Top>(
  toEquivalence: () => Equivalence.Equivalence<S["Type"]>
) => (self: S) => S["Rebuild"]

Source

Since v4.0.0

toEquivalence

Section titled “toEquivalence”

Derives an Equivalence from a schema. Two values are considered equal when every field (and nested field) compares equal according to the schema structure.

Example (Comparing structs)

import { Schema } from "effect"


const eq = Schema.toEquivalence(Schema.Struct({ id: Schema.Number, name: Schema.String }))


console.log(eq({ id: 1, name: "Alice" }, { id: 1, name: "Alice" })) // true
console.log(eq({ id: 1, name: "Alice" }, { id: 2, name: "Alice" })) // false

Signature

declare const toEquivalence: <T>(schema: Schema<T>) => Equivalence.Equivalence<T>

Source

Since v4.0.0

models

Section titled “models”

$Array (interface)

Section titled “$Array (interface)”

Type-level representation returned by Array.

Signature

export interface $Array<S extends Constraint> extends BottomLazy<SchemaAST.Arrays, $Array<S>> {
  readonly Type: ReadonlyArray<S["Type"]>
  readonly Encoded: ReadonlyArray<S["Encoded"]>
  readonly DecodingServices: S["DecodingServices"]
  readonly EncodingServices: S["EncodingServices"]
  readonly "~type.make.in": ReadonlyArray<S["~type.make"]>
  readonly "~type.make": ReadonlyArray<S["~type.make"]>
  readonly Iso: ReadonlyArray<S["Iso"]>
  readonly value: S
}

Source

Since v4.0.0

$Record (interface)

Section titled “$Record (interface)”

Type-level representation returned by Record.

Signature

export interface $Record<Key extends Record.Key, Value extends Constraint> extends BottomLazy<
  SchemaAST.Objects,
  $Record<Key, Value>
> {
  readonly Type: Record.Type<Key, Value>
  readonly Encoded: Record.Encoded<Key, Value>
  readonly DecodingServices: Record.DecodingServices<Key, Value>
  readonly EncodingServices: Record.EncodingServices<Key, Value>
  readonly "~type.make.in": Simplify<Record.MakeIn<Key, Value>>
  readonly "~type.make": Simplify<Record.MakeIn<Key, Value>>
  readonly Iso: Record.Iso<Key, Value>
  readonly key: Key
  readonly value: Value
}

Source

Since v4.0.0

Any (interface)

Section titled “Any (interface)”

Type-level representation of Any.

Signature

export interface Any extends Bottom<any, any, never, never, SchemaAST.Any, Any> {}

Source

Since v3.10.0

BigInt (interface)

Section titled “BigInt (interface)”

Type-level representation of BigInt.

Signature

export interface BigInt extends Bottom<bigint, bigint, never, never, SchemaAST.BigInt, BigInt> {}

Source

Since v4.0.0

Boolean (interface)

Section titled “Boolean (interface)”

Type-level representation of Boolean.

Signature

export interface Boolean extends Bottom<boolean, boolean, never, never, SchemaAST.Boolean, Boolean> {}

Source

Since v4.0.0

Bottom (interface)

Section titled “Bottom (interface)”

The fully-parameterized base interface for all schemas. Exposes all 14 type parameters controlling type inference, mutability, optionality, services, and transformation behavior.

When to use

Use when you are writing advanced generic schema utilities or performing schema introspection.

Signature

export interface Bottom<
  out T,
  out E,
  out RD,
  out RE,
  out Ast extends SchemaAST.AST,
  out Rebuild extends Top,
  out TypeMakeIn = T,
  out Iso = T,
  in out TypeParameters extends ReadonlyArray<Constraint> = readonly [],
  out TypeMake = TypeMakeIn,
  out TypeMutability extends Mutability = "readonly",
  out TypeOptionality extends Optionality = "required",
  out TypeConstructorDefault extends ConstructorDefault = "no-default",
  out EncodedMutability extends Mutability = "readonly",
  out EncodedOptionality extends Optionality = "required"
>
  extends Pipeable.Pipeable {
  readonly [TypeId]: typeof TypeId


  readonly ast: Ast
  readonly Rebuild: Rebuild
  readonly "~type.parameters": TypeParameters


  readonly Type: T
  readonly Encoded: E
  readonly DecodingServices: RD
  readonly EncodingServices: RE


  readonly "~type.make.in": TypeMakeIn
  readonly "~type.make": TypeMake // useful to type the `refine` interface
  readonly "~type.constructor.default": TypeConstructorDefault
  readonly Iso: Iso


  readonly "~type.mutability": TypeMutability
  readonly "~type.optionality": TypeOptionality
  readonly "~encoded.mutability": EncodedMutability
  readonly "~encoded.optionality": EncodedOptionality


  annotate(annotations: Annotations.Bottom<this["Type"], this["~type.parameters"]>): this["Rebuild"]
  annotateKey(annotations: Annotations.Key<this["Type"]>): this["Rebuild"]
  check(...checks: readonly [SchemaAST.Check<this["Type"]>, ...Array<SchemaAST.Check<this["Type"]>>]): this["Rebuild"]
  rebuild(ast: this["ast"]): this["Rebuild"]
  /**
   * Constructs a value from the make input representation synchronously.
   *
   * **When to use**
   *
   * Use when constructor input is trusted or when validation failure
   * should abort with a thrown `Error`.
   *
   * **Details**
   *
   * Applies constructor defaults and type-side validation according to
   * `MakeOptions`.
   *
   * **Gotchas**
   *
   * Throws an `Error` with the schema issue in its `cause` when validation
   * fails.
   * Causes that contain defects, interruptions, or other non-schema reasons
   * throw with the underlying `Cause` attached instead.
   *
   * @see {@link Bottom.makeOption} — construct synchronously and discard validation details
   * @see {@link Bottom.makeEffect} — construct through `Effect` when validation failure should stay in the error channel
   */
  make(input: this["~type.make.in"], options?: MakeOptions): this["Type"]
  /**
   * Constructs a value from the make input representation, returning `Option.none`
   * when validation fails.
   *
   * **When to use**
   *
   * Use when you only need to know whether construction succeeds
   * and do not need validation details.
   *
   * **Details**
   *
   * Applies constructor defaults and type-side validation according to
   * `MakeOptions`.
   *
   * **Gotchas**
   *
   * Only causes made entirely of schema issues are converted to `None`. Causes
   * that contain defects, interruptions, or other non-schema reasons throw
   * instead.
   *
   * @see {@link Bottom.make} — construct synchronously when validation failure should throw
   * @see {@link Bottom.makeEffect} — construct through `Effect` when validation details should stay in the error channel
   */
  makeOption(input: this["~type.make.in"], options?: MakeOptions): Option_.Option<this["Type"]>
  /**
   * Constructs a value from the make input representation, returning validation
   * failures in the `Effect` error channel.
   *
   * **When to use**
   *
   * Use when constructor input may fail validation and you want to
   * compose that failure with other `Effect` operations instead of throwing.
   *
   * @see {@link Bottom.make} — construct synchronously when validation failure should throw
   * @see {@link Bottom.makeOption} — construct synchronously and discard validation details
   */
  makeEffect(input: this["~type.make.in"], options?: MakeOptions): Effect.Effect<this["Type"], SchemaError>
}

Source

Since v4.0.0

Class (interface)

Section titled “Class (interface)”

Type-level representation returned by Class.

Signature

export interface Class<Self, S extends Constraint & { readonly fields: Struct.Fields }, Inherited> extends BottomLazy<
  SchemaAST.Declaration,
  decodeTo<declareConstructor<Self, S["Encoded"], readonly [S], S["Iso"]>, S>,
  readonly [S],
  S["~type.mutability"],
  S["~type.optionality"],
  S["~type.constructor.default"],
  S["~encoded.mutability"],
  S["~encoded.optionality"]
> {
  readonly Type: Self
  readonly Encoded: S["Encoded"]
  readonly DecodingServices: S["DecodingServices"]
  readonly EncodingServices: S["EncodingServices"]
  readonly "~type.make.in": RequiredKeys<S["~type.make.in"]> extends never
    ? void | S["~type.make.in"]
    : S["~type.make.in"]
  readonly "~type.make": Self
  readonly Iso: S["Iso"]
  new (
    ...args: {} extends S["~type.make.in"]
      ? [props?: S["~type.make.in"], options?: MakeOptions]
      : [props: S["~type.make.in"], options?: MakeOptions]
  ): S["Type"] & Inherited
  readonly identifier: string
  readonly fields: S["fields"]


  /**
   * Returns a new struct with the fields modified by the provided function.
   *
   * **Details**
   *
   * Options:
   *
   * - `unsafePreserveChecks` - if `true`, keep any `.check(...)` constraints
   *   that were attached to the original struct. Defaults to `false`.
   *
   *   **Warning**: This is an unsafe operation. Since `mapFields`
   *   transformations change the schema type, the original refinement functions
   *   may no longer be valid or safe to apply to the transformed schema. Only
   *   use this option if you have verified that your refinements remain correct
   *   after the transformation.
   */
  mapFields<To extends Struct.Fields>(
    f: (fields: S["fields"]) => To,
    options?:
      | {
          readonly unsafePreserveChecks?: boolean | undefined
        }
      | undefined
  ): Struct<Simplify<Readonly<To>>>


  /**
   * Returns a function that creates a schema-backed subclass with this class's
   * fields plus additional fields.
   *
   * **When to use**
   *
   * Use when you need a subclass whose constructor validates both inherited
   * fields and newly added fields.
   *
   * **Details**
   *
   * The returned function accepts either a field map or a `Struct`. When you
   * pass a `Struct`, checks attached to that extension schema are preserved and
   * combined with checks from the base class schema.
   *
   * **Gotchas**
   *
   * Checks from a `Struct` argument are evaluated against the full subclass
   * value after inherited and extension fields are merged. Object-wide checks
   * such as `isMaxProperties` count inherited fields too.
   */
  extend<Extended = never, Static = {}, Brand = {}>(
    identifier: string
  ): {
    <NewFields extends Struct.Fields>(
      fields: NewFields,
      annotations?: Annotations.Declaration<Extended, readonly [Struct<Simplify<Assign<S["fields"], NewFields>>>]>
    ): [Extended] extends [never]
      ? MissingSelfGeneric<"Base.extend">
      : InheritStaticMembers<Class<Extended, Struct<Simplify<Assign<S["fields"], NewFields>>>, Self & Brand>, Static>
    <Extension extends Struct<Struct.Fields>>(
      schema: Extension,
      annotations?: Annotations.Declaration<
        Extended,
        readonly [Struct<Simplify<Assign<S["fields"], Extension["fields"]>>>]
      >
    ): [Extended] extends [never]
      ? MissingSelfGeneric<"Base.extend">
      : InheritStaticMembers<
          Class<Extended, Struct<Simplify<Assign<S["fields"], Extension["fields"]>>>, Self & Brand>,
          Static
        >
  }
}

Source

Since v3.10.0

Codec (interface)

Section titled “Codec (interface)”

A schema that tracks the decoded type T, the encoded type E, and the Effect services required during decoding (RD) and encoding (RE).

Details

Use Codec<T, E, RD, RE> when you need to preserve full type information about a schema — both what it decodes to and what it serializes from/to. Most concrete schemas produced by this module implement Codec.

For APIs that only need one direction, prefer the narrower views:

  • ConstraintDecoder``<T, RD> — decode-only
  • ConstraintEncoder``<E, RE> — encode-only
  • Schema``<T> — type-only (no encoded representation)

Example (Accepting a codec that decodes to number from string)

import { Schema } from "effect"


declare function serialize<T>(codec: Schema.Codec<T, string>): string


serialize(Schema.NumberFromString) // ok — decodes number, encoded as string

See

  • Codec.Encoded — extract the encoded type
  • Codec.DecodingServices — extract required decoding services
  • Codec.EncodingServices — extract required encoding services
  • revealCodec — helper to make TypeScript infer the full Codec type

Signature

export interface Codec<out T, out E = T, out RD = never, out RE = never> extends Schema<T> {
  readonly Encoded: E
  readonly DecodingServices: RD
  readonly EncodingServices: RE
  readonly Rebuild: Codec<T, E, RD, RE>
}

Source

Since v4.0.0

Constraint (interface)

Section titled “Constraint (interface)”

Lightweight structural constraint for APIs that accept schema values but only read their data and type-level views.

When to use

Use when you need to constrain a generic value to be a schema, but the API only reads properties such as ast, Type, Encoded, service requirements, constructor input views, or modifier flags.

Details

Constraint keeps the schema type identifier and the property surface needed by schema constructors, while avoiding the full Bottom protocol. Use Top when an API calls schema methods such as annotate, check, rebuild, make, or makeEffect.

See

  • Top for the complete schema protocol.

Signature

export interface Constraint {
  readonly [TypeId]: typeof TypeId
  readonly ast: SchemaAST.AST


  readonly Type: unknown
  readonly Encoded: unknown
  readonly DecodingServices: unknown
  readonly EncodingServices: unknown


  readonly "~type.parameters": any
  readonly "~type.make.in": unknown
  readonly "~type.make": unknown
  readonly Iso: unknown


  readonly "~type.optionality": Optionality
  readonly "~type.mutability": Mutability
  readonly "~type.constructor.default": ConstructorDefault
  readonly "~encoded.optionality": Optionality
  readonly "~encoded.mutability": Mutability
}

Source

Since v4.0.0

ConstraintCodec (interface)

Section titled “ConstraintCodec (interface)”

Lightweight structural constraint for APIs that need codec type views but do not need the full schema protocol.

When to use

Use when you need to preserve decoded type, encoded type, and service requirements for a schema value, but the API does not call schema methods such as annotate, check, rebuild, make, or makeEffect.

See

  • Constraint for the generic lightweight schema constraint.
  • Codec for the full schema protocol with codec type views.

Signature

export interface ConstraintCodec<out T, out E = T, out RD = never, out RE = never> extends Constraint {
  readonly Type: T
  readonly Encoded: E
  readonly DecodingServices: RD
  readonly EncodingServices: RE
}

Source

Since v4.0.0

ConstraintDecoder (interface)

Section titled “ConstraintDecoder (interface)”

Lightweight structural constraint for APIs that need decoder type views but do not need the full schema protocol.

When to use

Use when you need to preserve a schema’s decoded type and decoding services, but the API does not constrain the encoded type, encoding services, or call schema methods such as annotate, check, rebuild, make, or makeEffect.

See

  • ConstraintCodec for APIs that need both decoded and encoded codec views.
  • Codec for the full schema protocol with codec type views.

Signature

export interface ConstraintDecoder<out T, out RD = never> extends ConstraintCodec<T, unknown, RD, unknown> {}

Source

Since v4.0.0

ConstraintEncoder (interface)

Section titled “ConstraintEncoder (interface)”

Lightweight structural constraint for APIs that need encoder type views but do not need the full schema protocol.

When to use

Use when you need to preserve a schema’s encoded type and encoding services, but the API does not constrain the decoded type, decoding services, or call schema methods such as annotate, check, rebuild, make, or makeEffect.

See

  • ConstraintCodec for APIs that need both decoded and encoded codec views.
  • Codec for the full schema protocol with codec type views.

Signature

export interface ConstraintEncoder<out E, out RE = never> extends ConstraintCodec<unknown, E, unknown, RE> {}

Source

Since v4.0.0

ConstraintRebuildable (interface)

Section titled “ConstraintRebuildable (interface)”

Lightweight structural constraint for APIs that need schema views and the rebuilt schema type, but do not call the full schema protocol.

When to use

Use when an API needs to read Rebuild in addition to the schema views exposed by Constraint, but does not call methods such as annotate, check, rebuild, make, or makeEffect.

Signature

export interface ConstraintRebuildable extends Constraint {
  readonly Rebuild: Constraint
}

Source

Since v4.0.0

ConstructorDefault (type alias)

Section titled “ConstructorDefault (type alias)”

Whether a schema field has a constructor default value.

See

  • withConstructorDefault — add a default to a schema field
  • tag — creates a literal field with a constructor default

Signature

type ConstructorDefault = "no-default" | "with-default"

Source

Since v4.0.0

Enum (interface)

Section titled “Enum (interface)”

Type-level representation returned by Enum.

Signature

export interface Enum<A extends { [x: string]: string | number }> extends Bottom<
  A[keyof A],
  A[keyof A],
  never,
  never,
  SchemaAST.Enum,
  Enum<A>
> {
  readonly enums: A
}

Source

Since v4.0.0

FilterIssue (type alias)

Section titled “FilterIssue (type alias)”

A single failure reported by a filter predicate. Used as the element type of the array arm of FilterOutput, and also accepted on its own.

Details

  • string: failure with that string as the message. Produces an SchemaIssue.InvalidValue wrapping the input, with the string used as the issue’s message annotation.
  • SchemaIssue.Issue: a fully-formed issue, returned as-is.
  • { path, issue }: failure attached to a nested path. issue is either a string (wrapped in an SchemaIssue.InvalidValue) or a full SchemaIssue.Issue; the result is wrapped in an SchemaIssue.Pointer at the given path.

Signature

type FilterIssue =
  | string
  | SchemaIssue.Issue
  | {
      readonly path: ReadonlyArray<PropertyKey>
      readonly issue: string | SchemaIssue.Issue
    }

Source

Since v3.10.0

FilterOutput (type alias)

Section titled “FilterOutput (type alias)”

The value a filter predicate (see makeFilter) may return.

Details

Each shape is normalized into an SchemaIssue.Issue (or undefined for success) before being attached to the parse result:

  • undefined: success. The input satisfies the filter.
  • true: success. Equivalent to undefined, useful when the predicate is a plain boolean expression.
  • false: generic failure. Produces an SchemaIssue.InvalidValue wrapping the input, with no custom message.
  • FilterIssue: a single failure. See FilterIssue for the shapes (string, SchemaIssue.Issue, or { path, issue }).
  • ReadonlyArray<FilterIssue>: several failures reported together. An empty array is treated as success; a single-element array is equivalent to returning that element directly; otherwise the entries are grouped into an SchemaIssue.Composite.

Signature

type FilterOutput = undefined | boolean | FilterIssue | ReadonlyArray<FilterIssue>

Source

Since v3.10.0

Json (type alias)

Section titled “Json (type alias)”

Recursive TypeScript type for any valid immutable JSON value: null, number, boolean, string, a readonly array of Json values, or a readonly record of string → Json. For the corresponding schema, see the Json const.

Signature

type Json = null | number | boolean | string | JsonArray | JsonObject

Source

Since v4.0.0

JsonArray (interface)

Section titled “JsonArray (interface)”

A readonly array of Json values.

Signature

export interface JsonArray extends ReadonlyArray<Json> {}

Source

Since v4.0.0

JsonObject (interface)

Section titled “JsonObject (interface)”

A readonly record whose values are Json values.

Signature

export interface JsonObject {
  readonly [x: string]: Json
}

Source

Since v4.0.0

Literal (interface)

Section titled “Literal (interface)”

Type-level representation returned by Literal.

Signature

export interface Literal<L extends SchemaAST.LiteralValue> extends Bottom<
  L,
  L,
  never,
  never,
  SchemaAST.Literal,
  Literal<L>
> {
  readonly literal: L
  transform<L2 extends SchemaAST.LiteralValue>(to: L2): decodeTo<Literal<L2>, Literal<L>>
}

Source

Since v3.10.0

Literals (interface)

Section titled “Literals (interface)”

Type-level representation returned by Literals.

Signature

export interface Literals<L extends ReadonlyArray<SchemaAST.LiteralValue>> extends Bottom<
  L[number],
  L[number],
  never,
  never,
  SchemaAST.Union<SchemaAST.Literal>,
  Literals<L>
> {
  readonly literals: L
  readonly members: { readonly [K in keyof L]: Literal<L[K]> }
  /**
   * Map over the members of the union.
   */
  mapMembers<To extends ReadonlyArray<Constraint>>(f: (members: this["members"]) => To): Union<Simplify<Readonly<To>>>


  pick<const L2 extends ReadonlyArray<L[number]>>(literals: L2): Literals<L2>


  transform<const L2 extends { readonly [I in keyof L]: SchemaAST.LiteralValue }>(
    to: L2
  ): Union<{ [I in keyof L]: decodeTo<Literal<L2[I]>, Literal<L[I]>> }>
}

Source

Since v4.0.0

Mutability (type alias)

Section titled “Mutability (type alias)”

Whether a schema field is readonly or mutable within a struct.

See

  • mutableKey — mark a struct field as mutable

Signature

type Mutability = "readonly" | "mutable"

Source

Since v4.0.0

MutableJson (type alias)

Section titled “MutableJson (type alias)”

Recursive TypeScript type for mutable JSON values: null, number, boolean, string, mutable arrays, or mutable string-keyed records.

Signature

type MutableJson = null | number | boolean | string | MutableJsonArray | MutableJsonObject

Source

Since v4.0.0

MutableJsonArray (interface)

Section titled “MutableJsonArray (interface)”

A mutable array of MutableJson values.

Signature

export interface MutableJsonArray extends Array<MutableJson> {}

Source

Since v4.0.0

MutableJsonObject (interface)

Section titled “MutableJsonObject (interface)”

A mutable record whose values are MutableJson values.

Signature

export interface MutableJsonObject {
  [x: string]: MutableJson
}

Source

Since v4.0.0

Never (interface)

Section titled “Never (interface)”

Type-level representation of Never.

Signature

export interface Never extends Bottom<never, never, never, never, SchemaAST.Never, Never> {}

Source

Since v3.10.0

NonEmptyArray (interface)

Section titled “NonEmptyArray (interface)”

Type-level representation returned by NonEmptyArray.

Signature

export interface NonEmptyArray<S extends Constraint> extends BottomLazy<SchemaAST.Arrays, NonEmptyArray<S>> {
  readonly Type: readonly [S["Type"], ...Array<S["Type"]>]
  readonly Encoded: readonly [S["Encoded"], ...Array<S["Encoded"]>]
  readonly DecodingServices: S["DecodingServices"]
  readonly EncodingServices: S["EncodingServices"]
  readonly "~type.make.in": readonly [S["~type.make"], ...Array<S["~type.make"]>]
  readonly "~type.make": readonly [S["~type.make"], ...Array<S["~type.make"]>]
  readonly Iso: readonly [S["Iso"], ...Array<S["Iso"]>]
  readonly value: S
}

Source

Since v3.10.0

Null (interface)

Section titled “Null (interface)”

Type-level representation of Null.

Signature

export interface Null extends Bottom<null, null, never, never, SchemaAST.Null, Null> {}

Source

Since v3.10.0

NullOr (interface)

Section titled “NullOr (interface)”

Type-level representation returned by NullOr.

Signature

export interface NullOr<S extends Constraint> extends Union<readonly [S, Null]> {
  readonly Rebuild: NullOr<S>
}

Source

Since v3.10.0

NullishOr (interface)

Section titled “NullishOr (interface)”

Type-level representation returned by NullishOr.

Signature

export interface NullishOr<S extends Constraint> extends Union<readonly [S, Null, Undefined]> {
  readonly Rebuild: NullishOr<S>
}

Source

Since v3.10.0

Number (interface)

Section titled “Number (interface)”

Type-level representation of Number.

Signature

export interface Number extends Bottom<number, number, never, never, SchemaAST.Number, Number> {}

Source

Since v4.0.0

ObjectKeyword (interface)

Section titled “ObjectKeyword (interface)”

Type-level representation of ObjectKeyword.

Signature

export interface ObjectKeyword extends Bottom<object, object, never, never, SchemaAST.ObjectKeyword, ObjectKeyword> {}

Source

Since v4.0.0

Opaque (interface)

Section titled “Opaque (interface)”

Type-level representation returned by Opaque.

Signature

export interface Opaque<Self, S extends Top, Brand> extends BottomLazy<
  S["ast"],
  S["Rebuild"],
  S["~type.parameters"],
  S["~type.mutability"],
  S["~type.optionality"],
  S["~type.constructor.default"],
  S["~encoded.mutability"],
  S["~encoded.optionality"]
> {
  readonly Type: Self
  readonly Encoded: S["Encoded"]
  readonly DecodingServices: S["DecodingServices"]
  readonly EncodingServices: S["EncodingServices"]
  readonly "~type.make.in": S["~type.make.in"]
  readonly "~type.make": S["~type.make"]
  readonly Iso: S["Iso"]
  new (_: never): S["Type"] & Brand
}

Source

Since v4.0.0

Optic (interface)

Section titled “Optic (interface)”

A schema that additionally supports optic (lens/prism) operations.

Details

Optic<T, Iso> extends Schema``<T> with an Iso type that describes the isomorphic counterpart used by the optic layer. Crucially, decoding and encoding require no Effect services (DecodingServices and EncodingServices are both never), which means the optic can operate purely without an Effect runtime.

Most primitive schemas (e.g. Schema.String, Schema.Number) implement Optic automatically. You normally interact with this interface through Optic_ utilities rather than constructing it directly.

Signature

export interface Optic<out T, out Iso> extends Schema<T> {
  readonly Iso: Iso
  readonly DecodingServices: never
  readonly EncodingServices: never
  readonly Rebuild: Optic<T, Iso>
}

Source

Since v4.0.0

Optionality (type alias)

Section titled “Optionality (type alias)”

Whether a schema field is required or optional within a struct.

See

  • optionalKey — mark a struct field as optional
  • optional — mark a struct field as optional with | undefined

Signature

type Optionality = "required" | "optional"

Source

Since v4.0.0

Schema (interface)

Section titled “Schema (interface)”

A typed view of a schema that tracks only the decoded (output) type T.

Details

Use Schema<T> as a constraint when you want to accept “any schema that decodes to T” and do not need to know or constrain the encoded representation, required services, or any other type parameters.

This is a structural interface — concrete schema values are produced by the constructors in this module (e.g. Struct, String, Number). When you also need the encoded type or service requirements, use Codec.

Example (Accepting any schema decoding to string)

import { Schema } from "effect"


declare function print(schema: Schema.Schema<string>): void


print(Schema.String) // ok
print(Schema.NonEmptyString) // ok

See

  • Codec — also tracks Encoded, DecodingServices, EncodingServices
  • Schema.Type — extract the decoded type at the type level

Signature

export interface Schema<out T> extends Top {
  readonly Type: T
  readonly Rebuild: Schema<T>
}

Source

Since v3.10.0

String (interface)

Section titled “String (interface)”

Type-level representation of String.

Signature

export interface String extends Bottom<string, string, never, never, SchemaAST.String, String> {}

Source

Since v4.0.0

Struct (interface)

Section titled “Struct (interface)”

Type-level representation returned by Struct.

Signature

export interface Struct<Fields extends Struct.Fields> extends BottomLazy<SchemaAST.Objects, Struct<Fields>> {
  readonly Type: Struct.Type<Fields>
  readonly Encoded: Struct.Encoded<Fields>
  readonly DecodingServices: Struct.DecodingServices<Fields>
  readonly EncodingServices: Struct.EncodingServices<Fields>
  readonly "~type.make.in": Struct.MakeIn<Fields>
  readonly "~type.make": Struct.MakeIn<Fields>
  readonly Iso: Struct.Iso<Fields>
  /**
   * The field definitions of this struct. Spread them into a new struct to
   * reuse fields across schemas.
   *
   * **Example** (Reusing fields across structs)
   *
   * ```ts
   * import { Schema } from "effect"
   *
   * const Timestamped = Schema.Struct({
   *   createdAt: Schema.Date,
   *   updatedAt: Schema.Date
   * })
   *
   * const User = Schema.Struct({
   *   ...Timestamped.fields,
   *   name: Schema.String,
   *   email: Schema.String
   * })
   * ```
   */
  readonly fields: Fields
  /**
   * Returns a new struct with the fields modified by the provided function.
   *
   * **Details**
   *
   * Options:
   *
   * - `unsafePreserveChecks` - if `true`, keep any `.check(...)` constraints
   *   that were attached to the original union. Defaults to `false`.
   *
   *   **Warning**: This is an unsafe operation. Since `mapFields`
   *   transformations change the schema type, the original refinement functions
   *   may no longer be valid or safe to apply to the transformed schema. Only
   *   use this option if you have verified that your refinements remain correct
   *   after the transformation.
   */
  mapFields<To extends Struct.Fields>(
    f: (fields: Fields) => To,
    options?:
      | {
          readonly unsafePreserveChecks?: boolean | undefined
        }
      | undefined
  ): Struct<Simplify<Readonly<To>>>
}

Source

Since v3.10.0

StructWithRest (interface)

Section titled “StructWithRest (interface)”

Type-level representation returned by StructWithRest.

Signature

export interface StructWithRest<
  S extends StructWithRest.Objects,
  Records extends StructWithRest.Records
> extends BottomLazy<SchemaAST.Objects, StructWithRest<S, Records>> {
  readonly Type: Simplify<StructWithRest.Type<S, Records>>
  readonly Encoded: Simplify<StructWithRest.Encoded<S, Records>>
  readonly DecodingServices: StructWithRest.DecodingServices<S, Records>
  readonly EncodingServices: StructWithRest.EncodingServices<S, Records>
  readonly "~type.make.in": Simplify<StructWithRest.MakeIn<S, Records>>
  readonly "~type.make": Simplify<StructWithRest.MakeIn<S, Records>>
  readonly Iso: Simplify<StructWithRest.Iso<S, Records>>
  readonly schema: S
  readonly records: Records
}

Source

Since v4.0.0

Symbol (interface)

Section titled “Symbol (interface)”

Type-level representation of Symbol.

Signature

export interface Symbol extends Bottom<symbol, symbol, never, never, SchemaAST.Symbol, Symbol> {}

Source

Since v4.0.0

TaggedStruct (type alias)

Section titled “TaggedStruct (type alias)”

Type-level representation returned by TaggedStruct.

Signature

type TaggedStruct<Tag, Fields> = Struct<Simplify<{ readonly _tag: tag<Tag> } & Fields>>

Source

Since v3.10.0

TaggedUnion (interface)

Section titled “TaggedUnion (interface)”

Type-level representation returned by TaggedUnion.

Signature

export interface TaggedUnion<Cases extends Record<string, Constraint>> extends BottomLazy<
  SchemaAST.Union<SchemaAST.Objects>,
  TaggedUnion<Cases>
> {
  readonly Type: { [K in keyof Cases]: Cases[K]["Type"] }[keyof Cases]
  readonly Encoded: { [K in keyof Cases]: Cases[K]["Encoded"] }[keyof Cases]
  readonly DecodingServices: { [K in keyof Cases]: Cases[K]["DecodingServices"] }[keyof Cases]
  readonly EncodingServices: { [K in keyof Cases]: Cases[K]["EncodingServices"] }[keyof Cases]
  readonly "~type.make.in": { [K in keyof Cases]: Cases[K]["~type.make"] }[keyof Cases]
  readonly "~type.make": { [K in keyof Cases]: Cases[K]["~type.make"] }[keyof Cases]
  readonly Iso: { [K in keyof Cases]: Cases[K]["Type"] }[keyof Cases]
  readonly cases: Cases
  readonly isAnyOf: <const Keys>(
    keys: ReadonlyArray<Keys>
  ) => (value: Cases[keyof Cases]["Type"]) => value is Extract<Cases[keyof Cases]["Type"], { _tag: Keys }>
  readonly guards: { [K in keyof Cases]: (u: unknown) => u is Cases[K]["Type"] }
  readonly match: {
    <Output>(cases: { [K in keyof Cases]: (value: Cases[K]["Type"]) => Output }): (
      value: Cases[keyof Cases]["Type"]
    ) => Output
    <Output>(
      value: Cases[keyof Cases]["Type"],
      cases: { [K in keyof Cases]: (value: Cases[K]["Type"]) => Output }
    ): Output
  }
}

Source

Since v4.0.0

TemplateLiteral (interface)

Section titled “TemplateLiteral (interface)”

Type-level representation returned by TemplateLiteral.

Signature

export interface TemplateLiteral<Parts extends TemplateLiteral.Parts> extends Bottom<
  TemplateLiteral.Encoded<Parts>,
  TemplateLiteral.Encoded<Parts>,
  never,
  never,
  SchemaAST.TemplateLiteral,
  TemplateLiteral<Parts>
> {
  readonly parts: Parts
}

Source

Since v3.10.0

TemplateLiteralParser (interface)

Section titled “TemplateLiteralParser (interface)”

Type-level representation returned by TemplateLiteralParser.

Signature

export interface TemplateLiteralParser<Parts extends TemplateLiteral.Parts> extends BottomLazy<
  SchemaAST.Arrays,
  TemplateLiteralParser<Parts>
> {
  readonly Type: TemplateLiteralParser.Type<Parts>
  readonly Encoded: TemplateLiteral.Encoded<Parts>
  readonly DecodingServices: never
  readonly EncodingServices: never
  readonly "~type.make.in": TemplateLiteralParser.Type<Parts>
  readonly "~type.make": TemplateLiteralParser.Type<Parts>
  readonly Iso: TemplateLiteralParser.Type<Parts>
  readonly parts: Parts
}

Source

Since v3.10.0

Top (interface)

Section titled “Top (interface)”

The existential “any schema” type — all type parameters are erased to unknown.

Details

Use Top as a constraint when writing generic utilities that must accept any schema regardless of its Type, Encoded, or service requirements. It is the widest possible schema type and therefore gives you the least static information.

In user code prefer the narrower interfaces:

  • Schema``<T> — when you only care about the decoded type
  • Codec``<T, E, RD, RE> — when you need the encoded type and service requirements
  • ConstraintDecoder``<T, RD> — for decode-only APIs
  • ConstraintEncoder``<E, RE> — for encode-only APIs

Signature

export interface Top extends Bottom<
  unknown,
  unknown,
  unknown,
  unknown,
  SchemaAST.AST,
  Top,
  unknown,
  unknown,
  any, // this is because TypeParameters is invariant
  unknown,
  Mutability,
  Optionality,
  ConstructorDefault,
  Mutability,
  Optionality
> {}

Source

Since v4.0.0

Tuple (interface)

Section titled “Tuple (interface)”

Type-level representation returned by Tuple.

Signature

export interface Tuple<Elements extends Tuple.Elements> extends BottomLazy<SchemaAST.Arrays, Tuple<Elements>> {
  readonly Type: Tuple.Type<Elements>
  readonly Encoded: Tuple.Encoded<Elements>
  readonly DecodingServices: Tuple.DecodingServices<Elements>
  readonly EncodingServices: Tuple.EncodingServices<Elements>
  readonly "~type.make.in": Tuple.MakeIn<Elements>
  readonly "~type.make": Tuple.MakeIn<Elements>
  readonly Iso: Tuple.Iso<Elements>
  readonly elements: Elements
  /**
   * Returns a new tuple with the elements modified by the provided function.
   *
   * **Details**
   *
   * Options:
   *
   * - `unsafePreserveChecks` - if `true`, keep any `.check(...)` constraints
   *   that were attached to the original union. Defaults to `false`.
   *
   *   **Warning**: This is an unsafe operation. Since `mapFields`
   *   transformations change the schema type, the original refinement functions
   *   may no longer be valid or safe to apply to the transformed schema. Only
   *   use this option if you have verified that your refinements remain correct
   *   after the transformation.
   */
  mapElements<To extends Tuple.Elements>(
    f: (elements: Elements) => To,
    options?:
      | {
          readonly unsafePreserveChecks?: boolean | undefined
        }
      | undefined
  ): Tuple<Simplify<Readonly<To>>>
}

Source

Since v3.10.0

TupleWithRest (interface)

Section titled “TupleWithRest (interface)”

Type-level representation returned by TupleWithRest.

Signature

export interface TupleWithRest<S extends TupleWithRest.TupleType, Rest extends TupleWithRest.Rest> extends BottomLazy<
  SchemaAST.Arrays,
  TupleWithRest<S, Rest>
> {
  readonly Type: TupleWithRest.Type<S["Type"], Rest>
  readonly Encoded: TupleWithRest.Encoded<S["Encoded"], Rest>
  readonly DecodingServices: S["DecodingServices"] | Rest[number]["DecodingServices"]
  readonly EncodingServices: S["EncodingServices"] | Rest[number]["EncodingServices"]
  readonly "~type.make.in": TupleWithRest.MakeIn<S["~type.make"], Rest>
  readonly "~type.make": TupleWithRest.MakeIn<S["~type.make"], Rest>
  readonly Iso: TupleWithRest.Iso<S["Iso"], Rest>
  readonly schema: S
  readonly rest: Rest
}

Source

Since v4.0.0

Undefined (interface)

Section titled “Undefined (interface)”

Type-level representation of Undefined.

Signature

export interface Undefined extends Bottom<undefined, undefined, never, never, SchemaAST.Undefined, Undefined> {}

Source

Since v3.10.0

UndefinedOr (interface)

Section titled “UndefinedOr (interface)”

Type-level representation returned by UndefinedOr.

Signature

export interface UndefinedOr<S extends Constraint> extends Union<readonly [S, Undefined]> {
  readonly Rebuild: UndefinedOr<S>
}

Source

Since v3.10.0

Union (interface)

Section titled “Union (interface)”

Type-level representation returned by Union.

Signature

export interface Union<Members extends ReadonlyArray<Constraint>> extends BottomLazy<
  SchemaAST.Union<{ [K in keyof Members]: Members[K]["ast"] }[number]>,
  Union<Members>
> {
  readonly Type: { [K in keyof Members]: Members[K]["Type"] }[number]
  readonly Encoded: { [K in keyof Members]: Members[K]["Encoded"] }[number]
  readonly DecodingServices: { [K in keyof Members]: Members[K]["DecodingServices"] }[number]
  readonly EncodingServices: { [K in keyof Members]: Members[K]["EncodingServices"] }[number]
  readonly "~type.make.in": { [K in keyof Members]: Members[K]["~type.make"] }[number]
  readonly "~type.make": { [K in keyof Members]: Members[K]["~type.make"] }[number]
  readonly Iso: { [K in keyof Members]: Members[K]["Iso"] }[number]
  readonly members: Members
  /**
   * Returns a new union with the members modified by the provided function.
   *
   * **Details**
   *
   * Options:
   *
   * - `unsafePreserveChecks` - if `true`, keep any `.check(...)` constraints
   *   that were attached to the original union. Defaults to `false`.
   *
   *   **Warning**: This is an unsafe operation. Since `mapFields`
   *   transformations change the schema type, the original refinement functions
   *   may no longer be valid or safe to apply to the transformed schema. Only
   *   use this option if you have verified that your refinements remain correct
   *   after the transformation.
   */
  mapMembers<To extends ReadonlyArray<Constraint>>(
    f: (members: Members) => To,
    options?:
      | {
          readonly unsafePreserveChecks?: boolean | undefined
        }
      | undefined
  ): Union<Simplify<Readonly<To>>>
}

Source

Since v3.10.0

UniqueArray (interface)

Section titled “UniqueArray (interface)”

Type-level representation returned by UniqueArray.

Signature

export interface UniqueArray<S extends Constraint> extends $Array<S> {
  readonly Rebuild: UniqueArray<S>
}

Source

Since v4.0.0

UniqueSymbol (interface)

Section titled “UniqueSymbol (interface)”

Type-level representation returned by UniqueSymbol.

Signature

export interface UniqueSymbol<sym extends symbol> extends Bottom<
  sym,
  sym,
  never,
  never,
  SchemaAST.UniqueSymbol,
  UniqueSymbol<sym>
> {}

Source

Since v4.0.0

Unknown (interface)

Section titled “Unknown (interface)”

Type-level representation of Unknown.

Signature

export interface Unknown extends Bottom<unknown, unknown, never, never, SchemaAST.Unknown, Unknown> {}

Source

Since v3.10.0

UnknownFromJsonString (interface)

Section titled “UnknownFromJsonString (interface)”

Type-level representation of UnknownFromJsonString.

Signature

export interface UnknownFromJsonString extends fromJsonString<Unknown> {
  readonly Rebuild: UnknownFromJsonString
}

Source

Since v4.0.0

Void (interface)

Section titled “Void (interface)”

Type-level representation of Void.

Signature

export interface Void extends Bottom<void, void, never, never, SchemaAST.Void, Void> {}

Source

Since v3.10.0

WithoutConstructorDefault (interface)

Section titled “WithoutConstructorDefault (interface)”

Constraint used to ensure a schema field does not already have a constructor default.

Details

Only schemas that satisfy this constraint can be passed to withConstructorDefault.

Signature

export interface WithoutConstructorDefault {
  readonly "~type.constructor.default": "no-default"
}

Source

Since v4.0.0

fromJsonString (interface)

Section titled “fromJsonString (interface)”

Type-level representation returned by fromJsonString.

Signature

export interface fromJsonString<S extends Constraint> extends decodeTo<S, String> {
  readonly Rebuild: fromJsonString<S>
}

Source

Since v4.0.0

instanceOf (interface)

Section titled “instanceOf (interface)”

Type-level representation returned by instanceOf.

Signature

export interface instanceOf<T, Iso = T> extends declare<T, Iso> {
  readonly Rebuild: instanceOf<T, Iso>
}

Source

Since v3.10.0

mutableKey (interface)

Section titled “mutableKey (interface)”

Type-level representation returned by mutableKey.

Signature

export interface mutableKey<S extends Constraint> extends BottomLazy<
  S["ast"],
  mutableKey<S>,
  S["~type.parameters"],
  "mutable",
  S["~type.optionality"],
  S["~type.constructor.default"],
  "mutable",
  S["~encoded.optionality"]
> {
  readonly Type: S["Type"]
  readonly Encoded: S["Encoded"]
  readonly DecodingServices: S["DecodingServices"]
  readonly EncodingServices: S["EncodingServices"]
  readonly "~type.make.in": S["~type.make.in"]
  readonly "~type.make": S["~type.make"]
  readonly Iso: S["Iso"]
  readonly schema: S
}

Source

Since v4.0.0

optional (interface)

Section titled “optional (interface)”

Type-level representation returned by optional.

Signature

export interface optional<S extends Constraint> extends optionalKey<UndefinedOr<S>> {
  readonly Rebuild: optional<S>
}

Source

Since v3.10.0

optionalKey (interface)

Section titled “optionalKey (interface)”

Type-level representation returned by optionalKey.

Signature

export interface optionalKey<S extends Constraint> extends BottomLazy<
  S["ast"],
  optionalKey<S>,
  S["~type.parameters"],
  S["~type.mutability"],
  "optional",
  S["~type.constructor.default"],
  S["~encoded.mutability"],
  "optional"
> {
  readonly Type: S["Type"]
  readonly Encoded: S["Encoded"]
  readonly DecodingServices: S["DecodingServices"]
  readonly EncodingServices: S["EncodingServices"]
  readonly "~type.make.in": S["~type.make.in"]
  readonly "~type.make": S["~type.make"]
  readonly Iso: S["Iso"]
  readonly schema: S
}

Source

Since v4.0.0

suspend (interface)

Section titled “suspend (interface)”

Type-level representation returned by suspend.

Signature

export interface suspend<S extends Constraint> extends BottomLazy<
  SchemaAST.Suspend,
  suspend<S>,
  S["~type.parameters"],
  S["~type.mutability"],
  S["~type.optionality"],
  S["~type.constructor.default"],
  S["~encoded.mutability"],
  S["~encoded.optionality"]
> {
  readonly Type: S["Type"]
  readonly Encoded: S["Encoded"]
  readonly DecodingServices: S["DecodingServices"]
  readonly EncodingServices: S["EncodingServices"]
  readonly "~type.make.in": S["~type.make.in"]
  readonly "~type.make": S["~type.make"]
  readonly Iso: S["Iso"]
}

Source

Since v3.10.0

options

Section titled “options”

DecodingDefaultOptions (type alias)

Section titled “DecodingDefaultOptions (type alias)”

Options for withDecodingDefaultKey and withDecodingDefault.

Details

  • encodingStrategy:
    • "passthrough" (default): pass the value through during encoding
    • "omit": omit the key from the encoded output

Signature

type DecodingDefaultOptions = {
  readonly encodingStrategy?: "omit" | "passthrough" | undefined
}

Source

Since v4.0.0

ErrorOptions (interface)

Section titled “ErrorOptions (interface)”

Options for Error and Defect.

Signature

export interface ErrorOptions {
  /**
   * Includes string stack traces in encoded `Error` values when set to `true`.
   *
   * @default false
   */
  readonly includeStack?: boolean | undefined
  /**
   * Excludes `Error.cause` values from encoded `Error` values when set to
   * `true`.
   *
   * @default false
   */
  readonly excludeCause?: boolean | undefined
}

Source

Since v4.0.0

MakeOptions (interface)

Section titled “MakeOptions (interface)”

Options for makeEffect, make, and Class constructors.

When to use

Use when passing disableChecks: true to skip validation when you trust the data.

  • Pass parseOptions to control error reporting behavior.

See

  • Bottom.makeEffect
  • Bottom.make

Signature

export interface MakeOptions {
  /**
   * The parse options to use for the schema.
   */
  readonly parseOptions?: SchemaAST.ParseOptions | undefined
  /**
   * Whether to disable validation for the schema.
   */
  readonly disableChecks?: boolean | undefined
}

Source

Since v3.13.4

ToJsonSchemaOptions (interface)

Section titled “ToJsonSchemaOptions (interface)”

Options for toJsonSchemaDocument.

Signature

export interface ToJsonSchemaOptions {
  /**
   * Controls how additional properties are handled while resolving the JSON
   * schema.
   *
   * **Details**
   *
   * Possible values include:
   * - `false`: Disallow additional properties (default)
   * - `true`: Allow additional properties
   * - `JsonSchema`: Use the provided JSON Schema for additional properties
   */
  readonly additionalProperties?: boolean | JsonSchema.JsonSchema | undefined
  /**
   * Controls whether to generate descriptions for checks (if the user has not
   * provided them) based on the `expected` annotation of the check.
   */
  readonly generateDescriptions?: boolean | undefined
  /**
   * A predicate that controls which additional annotation keys (beyond the
   * standard JSON Schema keys) are included in the generated output.
   *
   * **When to use**
   *
   * Use when you need to include non-standard annotation keys in the generated
   * JSON Schema, such as Monaco Editor properties (`markdownDescription`,
   * `defaultSnippets`) or vendor extensions (`x-*`).
   *
   * **Details**
   *
   * Standard JSON Schema keys (`title`, `description`, `default`, `examples`,
   * `readOnly`, `writeOnly`, `format`, `contentEncoding`, `contentMediaType`,
   * `contentSchema`) are always included. This predicate is checked for any
   * *other* annotation key.
   *
   * **Gotchas**
   *
   * Prefer whitelisting the custom annotation keys you want to emit instead of
   * using a broad predicate such as `() => true`, because broad predicates can
   * include Effect-specific annotations that are preserved for internal schema
   * generation.
   *
   * **Example** (Including custom annotations)
   *
   * ```ts
   * import { Schema } from "effect"
   *
   * const schema = Schema.String.annotate({
   *   description: "A name",
   *   markdownDescription: "The **name** field"
   * })
   *
   * const doc = Schema.toJsonSchemaDocument(schema, {
   *   includeAnnotationKey: (key) =>
   *     key === "markdownDescription" || key.startsWith("x-")
   * })
   *
   * console.log(doc.schema)
   * // {
   * //   type: "string",
   * //   description: "A name",
   * //   markdownDescription: "The **name** field"
   * // }
   * ```
   */
  readonly includeAnnotationKey?: ((key: string) => boolean) | undefined
}

Source

Since v4.0.0

schemas

Section titled “schemas”

Any

Section titled “Any”

Schema for the any type. Accepts any value without validation.

See

  • Unknown for a safer alternative that uses unknown.

Signature

declare const Any: Any

Source

Since v3.10.0

BigInt

Section titled “BigInt”

Schema for bigint values. Validates that the input is typeof "bigint".

When to use

Use when the input is already a bigint and the schema should validate and preserve bigint values without parsing from another representation.

See

  • BigIntFromString for parsing string input into a bigint

Signature

declare const BigInt: BigInt

Source

Since v4.0.0

Json

Section titled “Json”

Schema that accepts and validates any immutable JSON-compatible value.

Example (Validating a JSON value)

import { Schema } from "effect"


const result = Schema.decodeUnknownOption(Schema.Json)({ key: [1, true, null] })
console.log(result._tag) // "Some"

Signature

declare const Json: Codec<Json, Json, never, never>

Source

Since v4.0.0

MutableJson

Section titled “MutableJson”

Schema that accepts any mutable JSON-compatible value. See Json for the immutable variant.

Signature

declare const MutableJson: Codec<MutableJson, MutableJson, never, never>

Source

Since v4.0.0

Never

Section titled “Never”

Schema for the never type. Always fails validation — no value satisfies it.

Signature

declare const Never: Never

Source

Since v3.10.0

Null

Section titled “Null”

Schema for the null literal. Validates that the input is strictly null.

See

  • NullOr for a union with another schema.

Signature

declare const Null: Null

Source

Since v3.10.0

Number

Section titled “Number”

Schema for number values, including NaN, Infinity, and -Infinity.

Details

Default JSON serializer:

  • Finite numbers are serialized as numbers.
  • Non-finite values are serialized as strings ("NaN", "Infinity", "-Infinity").

See

  • Finite for a schema that excludes non-finite values.

Signature

declare const Number: Number

Source

Since v4.0.0

ObjectKeyword

Section titled “ObjectKeyword”

Schema for the object type. Validates that the input is a non-null object or function (i.e. typeof value === "object" && value !== null || typeof value === "function").

Signature

declare const ObjectKeyword: ObjectKeyword

Source

Since v4.0.0

Result

Section titled “Result”

Schema for Result<A, E> values.

Signature

declare const Result: <A extends Constraint, E extends Constraint>(success: A, failure: E) => Result<A, E>

Source

Since v4.0.0

Result (interface)

Section titled “Result (interface)”

Type-level representation returned by Result.

Signature

export interface Result<A extends Constraint, E extends Constraint> extends declareConstructor<
  Result_.Result<A["Type"], E["Type"]>,
  Result_.Result<A["Encoded"], E["Encoded"]>,
  readonly [A, E],
  ResultIso<A, E>
> {
  readonly Rebuild: Result<A, E>
  readonly success: A
  readonly failure: E
}

Source

Since v4.0.0

ResultIso (type alias)

Section titled “ResultIso (type alias)”

Iso representation used for Result schemas.

Details

Successful results are represented as { _tag: "Success", success }, while failed results are represented as { _tag: "Failure", failure }.

Signature

type ResultIso<A, E> =
  | { readonly _tag: "Success"; readonly success: A["Iso"] }
  | { readonly _tag: "Failure"; readonly failure: E["Iso"] }

Source

Since v4.0.0

String

Section titled “String”

Schema for string values. Validates that the input is typeof "string".

Signature

declare const String: String

Source

Since v4.0.0

Symbol

Section titled “Symbol”

Schema for symbol values. Validates that the input is typeof "symbol".

See

  • UniqueSymbol for a schema that matches a specific symbol.

Signature

declare const Symbol: Symbol

Source

Since v4.0.0

Undefined

Section titled “Undefined”

Schema for the undefined literal. Validates that the input is strictly undefined.

See

  • UndefinedOr for a union with another schema.

Signature

declare const Undefined: Undefined

Source

Since v3.10.0

Unknown

Section titled “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.

See

  • Any for the any variant.

Signature

declare const Unknown: Unknown

Source

Since v3.10.0

UnknownFromJsonString

Section titled “UnknownFromJsonString”

Schema that decodes a JSON-encoded string into an unknown value.

Details

Decoding:

  • A string is decoded as an unknown value.
  • If the string is not valid JSON, decoding fails.

Encoding:

  • Any value is encoded as a JSON string using JSON.stringify.
  • If the value is not a valid JSON value, encoding fails.

Example (Decoding unknown JSON strings)

import { Schema } from "effect"


Schema.decodeUnknownSync(Schema.UnknownFromJsonString)(`{"a":1,"b":2}`)
// => { a: 1, b: 2 }

Signature

declare const UnknownFromJsonString: UnknownFromJsonString

Source

Since v4.0.0

Void

Section titled “Void”

Schema for a TypeScript void return value.

When to use

Use when you need to model the return value of a function, RPC, or endpoint whose result is intentionally ignored.

Details

Runtime parsing accepts any present value and discards it, producing undefined. The public decoded and encoded TypeScript representation remains void, so typed construction, decoding, and encoding APIs are still modeled as void.

See

  • Undefined for a schema that matches only the exact undefined value.

Signature

declare const Void: Void

Source

Since v3.10.0

search params

Section titled “search params”

URLSearchParams

Section titled “URLSearchParams”

Schema for JavaScript URLSearchParams objects.

Details

The default JSON serializer encodes a URLSearchParams as a query string.

Signature

declare const URLSearchParams: URLSearchParams

Source

Since v4.0.0

URLSearchParams (interface)

Section titled “URLSearchParams (interface)”

Type-level representation of URLSearchParams.

Signature

export interface URLSearchParams extends instanceOf<globalThis.URLSearchParams> {
  readonly Rebuild: URLSearchParams
}

Source

Since v4.0.0

fromURLSearchParams (interface)

Section titled “fromURLSearchParams (interface)”

Type-level representation returned by fromURLSearchParams.

Signature

export interface fromURLSearchParams<S extends Constraint> extends decodeTo<S, URLSearchParams> {
  readonly Rebuild: fromURLSearchParams<S>
}

Source

Since v4.0.0

string

Section titled “string”

Char

Section titled “Char”

Schema for strings whose JavaScript length is exactly 1.

When to use

Use to validate string values that must have length === 1.

Gotchas

This schema uses JavaScript String.length, so visible characters made from multiple UTF-16 code units do not satisfy length === 1.

See

  • String for unconstrained string values
  • NonEmptyString for strings with length greater than zero
  • isLengthBetween for the underlying length check

Signature

declare const Char: Char

Source

Since v3.10.0

Char (interface)

Section titled “Char (interface)”

Type-level representation of Char.

Signature

export interface Char extends String {
  readonly Rebuild: Char
}

Source

Since v3.10.0

NonEmptyString

Section titled “NonEmptyString”

Schema for non-empty strings. Validates that a string has at least one character.

Signature

declare const NonEmptyString: NonEmptyString

Source

Since v3.10.0

NonEmptyString (interface)

Section titled “NonEmptyString (interface)”

Type-level representation of NonEmptyString.

Signature

export interface NonEmptyString extends String {
  readonly Rebuild: NonEmptyString
}

Source

Since v3.10.0

StringFromBase64

Section titled “StringFromBase64”

Decodes a base64 (RFC4648) encoded string into a UTF-8 string.

Details

Decoding:

  • A valid base64 encoded string is decoded as a UTF-8 string.

Encoding:

  • A string is encoded as a base64-encoded string.

Signature

declare const StringFromBase64: StringFromBase64

Source

Since v3.10.0

StringFromBase64 (interface)

Section titled “StringFromBase64 (interface)”

Type-level representation of StringFromBase64.

Signature

export interface StringFromBase64 extends decodeTo<String, String> {
  readonly Rebuild: StringFromBase64
}

Source

Since v3.10.0

StringFromBase64Url

Section titled “StringFromBase64Url”

Decodes a base64 (URL) encoded string into a UTF-8 string.

Details

Decoding:

  • A valid base64 (URL) encoded string is decoded as a UTF-8 string.

Encoding:

  • A string is encoded as a base64 (URL) encoded string.

Signature

declare const StringFromBase64Url: StringFromBase64Url

Source

Since v3.10.0

StringFromBase64Url (interface)

Section titled “StringFromBase64Url (interface)”

Type-level representation of StringFromBase64Url.

Signature

export interface StringFromBase64Url extends decodeTo<String, String> {
  readonly Rebuild: StringFromBase64Url
}

Source

Since v3.10.0

StringFromHex

Section titled “StringFromHex”

Decodes a hex encoded string into a UTF-8 string.

Details

Decoding:

  • A valid hex encoded string is decoded as a UTF-8 string.

Encoding:

  • A string is encoded as a hex string.

Signature

declare const StringFromHex: StringFromHex

Source

Since v3.10.0

StringFromHex (interface)

Section titled “StringFromHex (interface)”

Type-level representation of StringFromHex.

Signature

export interface StringFromHex extends decodeTo<String, String> {
  readonly Rebuild: StringFromHex
}

Source

Since v3.10.0

StringFromUriComponent

Section titled “StringFromUriComponent”

Decodes a URI component encoded string into a UTF-8 string. Can be used to store data in a URL.

Details

Decoding:

  • A valid URI component encoded string is decoded as a UTF-8 string.

Encoding:

  • A string is encoded as a URI component encoded string.

Example (Decoding URI component strings)

import { Schema } from "effect"


const PaginationSchema = Schema.Struct({
  maxItemPerPage: Schema.Number,
  page: Schema.Number
})


const UrlSchema = Schema.StringFromUriComponent.pipe(Schema.decodeTo(Schema.fromJsonString(PaginationSchema)))


console.log(Schema.encodeSync(UrlSchema)({ maxItemPerPage: 10, page: 1 }))
// %7B%22maxItemPerPage%22%3A10%2C%22page%22%3A1%7D

Signature

declare const StringFromUriComponent: StringFromUriComponent

Source

Since v3.12.0

StringFromUriComponent (interface)

Section titled “StringFromUriComponent (interface)”

Type-level representation of StringFromUriComponent.

Signature

export interface StringFromUriComponent extends decodeTo<String, String> {
  readonly Rebuild: StringFromUriComponent
}

Source

Since v3.12.0

Trim

Section titled “Trim”

Schema that trims whitespace from a string.

Details

Decoding:

  • A string is decoded as a string with no leading or trailing whitespaces.

Encoding:

  • The trimmed string is encoded as is.

Signature

declare const Trim: Trim

Source

Since v3.10.0

Trim (interface)

Section titled “Trim (interface)”

Type-level representation of Trim.

Signature

export interface Trim extends decodeTo<Trimmed, String> {
  readonly Rebuild: Trim
}

Source

Since v3.10.0

Trimmed

Section titled “Trimmed”

Schema for strings that contains no leading or trailing whitespaces.

Signature

declare const Trimmed: Trimmed

Source

Since v3.10.0

Trimmed (interface)

Section titled “Trimmed (interface)”

Type-level representation of Trimmed.

Signature

export interface Trimmed extends String {
  readonly Rebuild: Trimmed
}

Source

Since v3.10.0

transforming

Section titled “transforming”

compose (interface)

Section titled “compose (interface)”

Type-level representation returned by decodeTo without a custom transformation.

Signature

export interface compose<To extends Constraint, From extends Constraint> extends decodeTo<To, From> {}

Source

Since v3.10.0

decode

Section titled “decode”

Applies a transformation to a schema, creating a new schema with the same type but transformed encoding/decoding.

When to use

Use when the decoded type stays the same and the transformation only normalizes values during encoding and decoding.

Details

Call it with a transformation object and then pipe a schema into the returned function. The resulting schema keeps the same Type and Encoded types as the source schema, while applying the transformation during both decoding and encoding.

Internally this uses toType(self) as the target schema and combines service requirements from the source schema and the transformation.

Gotchas

Use decodeTo instead when the transformation should change the decoded type. For this helper, both transformation getters operate on S["Type"] values.

Example (Trimming string values during encoding/decoding)

import { Schema, SchemaGetter } from "effect"


const Trimmed = Schema.String.pipe(
  Schema.decode({
    decode: SchemaGetter.transform((s) => s.trim()),
    encode: SchemaGetter.transform((s) => s.trim())
  })
)


const result = Schema.decodeUnknownSync(Trimmed)("  hello  ")
// result: "hello"

Signature

declare const decode: <S extends Constraint, RD = never, RE = never>(transformation: {
  readonly decode: SchemaGetter.Getter<S["Type"], S["Type"], RD>
  readonly encode: SchemaGetter.Getter<S["Type"], S["Type"], RE>
}) => (self: S) => decodeTo<toType<S>, S, RD, RE>

Source

Since v3.10.0

decodeTo

Section titled “decodeTo”

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

Signature

declare const decodeTo: {
  <To extends Constraint>(to: To): <From extends Constraint>(from: From) => compose<To, From>
  <To extends Constraint, From extends Constraint, RD = never, RE = never>(
    to: To,
    transformation: {
      readonly decode: SchemaGetter.Getter<NoInfer<To["Encoded"]>, NoInfer<From["Type"]>, RD>
      readonly encode: SchemaGetter.Getter<NoInfer<From["Type"]>, NoInfer<To["Encoded"]>, RE>
    }
  ): (from: From) => decodeTo<To, From, RD, RE>
}

Source

Since v4.0.0

decodeTo (interface)

Section titled “decodeTo (interface)”

Type-level representation returned by decodeTo.

Signature

export interface decodeTo<To extends Constraint, From extends Constraint, RD = never, RE = never> extends BottomLazy<
  To["ast"],
  decodeTo<To, From, RD, RE>,
  To["~type.parameters"],
  To["~type.mutability"],
  To["~type.optionality"],
  To["~type.constructor.default"],
  From["~encoded.mutability"],
  From["~encoded.optionality"]
> {
  readonly Type: To["Type"]
  readonly Encoded: From["Encoded"]
  readonly DecodingServices: To["DecodingServices"] | From["DecodingServices"] | RD
  readonly EncodingServices: To["EncodingServices"] | From["EncodingServices"] | RE
  readonly "~type.make.in": To["~type.make.in"]
  readonly "~type.make": To["~type.make"]
  readonly Iso: To["Iso"]
  readonly from: From
  readonly to: To
}

Source

Since v4.0.0

encode

Section titled “encode”

Applies a transformation to a schema’s encoded type, creating a new schema where encoding/decoding operate on S["Encoded"] rather than S["Type"].

Details

The decode getter maps S["Encoded"] → S["Encoded"] (applied during decoding), and the encode getter maps S["Encoded"] → S["Encoded"] (applied during encoding).

Example (Upper-casing encoded strings)

import { Schema, SchemaGetter } from "effect"


const UpperFromLower = Schema.String.pipe(
  Schema.encode({
    decode: SchemaGetter.transform((s: string) => s.toLowerCase()),
    encode: SchemaGetter.transform((s: string) => s.toUpperCase())
  })
)

Signature

declare const encode: <S extends Constraint, RD = never, RE = never>(transformation: {
  readonly decode: SchemaGetter.Getter<S["Encoded"], S["Encoded"], RD>
  readonly encode: SchemaGetter.Getter<S["Encoded"], S["Encoded"], RE>
}) => (self: S) => decodeTo<S, toEncoded<S>, RD, RE>

Source

Since v3.10.0

encodeKeys

Section titled “encodeKeys”

Renames struct keys in the encoded form without changing the decoded type.

Details

Takes a partial mapping { decodedKey: encodedKey } and produces a transformation schema that decodes from the renamed keys and encodes back to the renamed keys. Keys not present in the mapping are left unchanged. If two existing fields would produce the same encoded key, construction fails.

Example (Renaming name to full_name in the encoded form)

import { Schema } from "effect"


const Person = Schema.Struct({ name: Schema.String, age: Schema.Number })
const Encoded = Person.pipe(Schema.encodeKeys({ name: "full_name" }))


// Decodes { full_name: "Alice", age: 30 } → { name: "Alice", age: 30 }
const alice = Schema.decodeUnknownSync(Encoded)({ full_name: "Alice", age: 30 })
console.log(alice)
// { name: 'Alice', age: 30 }

Signature

declare const encodeKeys: <
  S extends Constraint & { readonly fields: Struct.Fields },
  const M extends { readonly [K in keyof S["fields"]]?: PropertyKey }
>(
  mapping: M
) => (self: S) => encodeKeys<S, M>

Source

Since v4.0.0

encodeKeys (interface)

Section titled “encodeKeys (interface)”

Type-level representation returned by encodeKeys.

Signature

export interface encodeKeys<
  S extends Constraint & { readonly fields: Struct.Fields },
  M extends { readonly [K in keyof S["fields"]]?: PropertyKey }
> extends decodeTo<
  S,
  Struct<{
    [K in keyof S["fields"] as K extends keyof M ? (M[K] extends PropertyKey ? M[K] : K) : K]: toEncoded<S["fields"][K]>
  }>
> {}

Source

Since v4.0.0

encodeTo

Section titled “encodeTo”

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))
  })
)

Signature

declare const encodeTo: {
  <To extends Constraint>(to: To): <From extends Constraint>(from: From) => decodeTo<From, To>
  <To extends Constraint, From extends Constraint, RD = never, RE = never>(
    to: To,
    transformation: {
      readonly decode: SchemaGetter.Getter<NoInfer<From["Encoded"]>, NoInfer<To["Type"]>, RD>
      readonly encode: SchemaGetter.Getter<NoInfer<To["Type"]>, NoInfer<From["Encoded"]>, RE>
    }
  ): (from: From) => decodeTo<From, To, RD, RE>
}

Source

Since v4.0.0

extendTo

Section titled “extendTo”

Adds derived fields to a struct schema during decoding.

Details

Each new field is derived from the decoded struct value via a function that returns Option. On encoding the derived fields are stripped. This allows computed or enriched fields to live in the decoded type without appearing in the encoded form.

Example (Adding a computed fullName field)

import { Option, Schema } from "effect"


const Person = Schema.Struct({ first: Schema.String, last: Schema.String })
const Extended = Person.pipe(
  Schema.extendTo({ fullName: Schema.String }, { fullName: (p) => Option.some(`${p.first} ${p.last}`) })
)


const alice = Schema.decodeUnknownSync(Extended)({ first: "Alice", last: "Smith" })
console.log(alice.fullName)
// Alice Smith

Signature

declare const extendTo: <S extends Struct<Struct.Fields>, const Fields extends Struct.Fields>(
  fields: Fields,
  derive: { readonly [K in keyof Fields]: (s: S["Type"]) => Option_.Option<Fields[K]["Type"]> }
) => (self: S) => decodeTo<Struct<Simplify<{ [K in keyof S["fields"]]: toType<S["fields"][K]> } & Fields>>, S>

Source

Since v4.0.0

flip

Section titled “flip”

Swaps the decoded and encoded sides of a schema.

When to use

Use to invert a schema transformation direction.

Details

Calling flip twice returns the original schema.

Example (Flipping a number-from-string schema)

import { Schema } from "effect"


// NumberFromString: decodes string → number
const flipped = Schema.flip(Schema.NumberFromString)
// flipped: decodes number → string

Signature

declare const flip: <S extends Top>(schema: S) => S extends flip<infer F> ? F["Rebuild"] : flip<S>

Source

Since v4.0.0

flip (interface)

Section titled “flip (interface)”

Type-level representation returned by flip.

Signature

export interface flip<S extends Top> extends BottomLazy<
  SchemaAST.AST,
  flip<S>,
  ReadonlyArray<Constraint>,
  S["~encoded.mutability"],
  S["~encoded.optionality"],
  ConstructorDefault,
  S["~type.mutability"],
  S["~type.optionality"]
> {
  readonly Type: S["Encoded"]
  readonly Encoded: S["Type"]
  readonly DecodingServices: S["EncodingServices"]
  readonly EncodingServices: S["DecodingServices"]
  readonly "~type.make.in": S["Encoded"]
  readonly "~type.make": S["Encoded"]
  readonly Iso: S["Encoded"]
  readonly [FlipTypeId]: typeof FlipTypeId
  readonly schema: S
}

Source

Since v4.0.0

Section titled “link”

Constructs an SchemaAST.Link that describes how a value of type T encodes to and decodes from a To schema. Used when building low-level AST transformations that bridge two schema types.

Signature

declare const link: <T>() => <To extends Constraint>(
  encodeTo: To,
  transformation: {
    readonly decode: SchemaGetter.Getter<T, NoInfer<To["Type"]>>
    readonly encode: SchemaGetter.Getter<NoInfer<To["Type"]>, T>
  }
) => SchemaAST.Link

Source

Since v4.0.0

mutable

Section titled “mutable”

Makes an array or tuple schema mutable, removing the readonly modifier.

Example (Defining mutable arrays)

import { Schema } from "effect"


const schema = Schema.mutable(Schema.Array(Schema.Number))


// number[]   (mutable)
type T = typeof schema.Type

Signature

declare const mutable: mutableLambda

Source

Since v3.10.0

mutable (interface)

Section titled “mutable (interface)”

Type-level representation returned by mutable.

Signature

export interface mutable<S extends Constraint & { readonly ast: SchemaAST.Arrays }> extends BottomLazy<
  S["ast"],
  mutable<S>,
  S["~type.parameters"],
  S["~type.mutability"],
  S["~type.optionality"],
  S["~type.constructor.default"],
  S["~encoded.mutability"],
  S["~encoded.optionality"]
> {
  readonly Type: Mutable<S["Type"]>
  readonly Encoded: Mutable<S["Encoded"]>
  readonly DecodingServices: S["DecodingServices"]
  readonly EncodingServices: S["EncodingServices"]
  // "~type.make" and "~type.make.in" as they are because they are contravariant
  readonly "~type.make.in": S["~type.make.in"]
  readonly "~type.make": S["~type.make"]
  readonly Iso: S["Iso"]
  readonly schema: S
}

Source

Since v3.10.0

toEncoded

Section titled “toEncoded”

Extracts the encoded-side schema: sets Type to equal the Encoded, discarding the decoding transformation path.

Signature

declare const toEncoded: toEncodedLambda

Source

Since v4.0.0

toEncoded (interface)

Section titled “toEncoded (interface)”

Type-level representation returned by toEncoded.

Signature

export interface toEncoded<S extends Constraint> extends BottomLazy<
  SchemaAST.AST,
  toEncoded<S>,
  ReadonlyArray<Constraint>,
  S["~type.mutability"],
  S["~type.optionality"],
  S["~type.constructor.default"],
  S["~encoded.mutability"],
  S["~encoded.optionality"]
> {
  readonly Type: S["Encoded"]
  readonly Encoded: S["Encoded"]
  readonly DecodingServices: never
  readonly EncodingServices: never
  readonly "~type.make.in": S["Encoded"]
  readonly "~type.make": S["Encoded"]
  readonly Iso: S["Encoded"]
  readonly schema: S
}

Source

Since v4.0.0

toType

Section titled “toType”

Extracts the type-side schema: sets Encoded to equal the decoded Type, discarding the encoding transformation path.

Signature

declare const toType: toTypeLambda

Source

Since v4.0.0

toType (interface)

Section titled “toType (interface)”

Type-level representation returned by toType.

Signature

export interface toType<S extends Constraint> extends BottomLazy<
  S["ast"],
  toType<S>,
  S["~type.parameters"],
  S["~type.mutability"],
  S["~type.optionality"],
  S["~type.constructor.default"],
  S["~encoded.mutability"],
  S["~encoded.optionality"]
> {
  readonly Type: S["Type"]
  readonly Encoded: S["Type"]
  readonly DecodingServices: never
  readonly EncodingServices: never
  readonly "~type.make.in": S["~type.make.in"]
  readonly "~type.make": S["~type.make"]
  readonly Iso: S["Iso"]
  readonly schema: S
}

Source

Since v4.0.0

utility types

Section titled “utility types”

BottomLazy (interface)

Section titled “BottomLazy (interface)”

Lazy Bottom variant for schema implementations that compute their public views on demand.

When to use

Use as an implementation base for schema interfaces that must expose Bottom behavior without forcing TypeScript to eagerly evaluate expensive Type, Encoded, or service views.

Details

The laziness is purely type-level; runtime behavior is unchanged. BottomLazy keeps the structural operations inherited from Bottom, but erases the expensive schema views to unknown. Concrete schema interfaces can then redeclare the precise views they expose. This keeps wide schemas such as Struct and Union cheaper when generic code reads a single view, while preserving their exact public types.

See

  • Bottom for the fully parameterized schema interface when every view must be supplied directly.

Signature

export interface BottomLazy<
  out Ast extends SchemaAST.AST,
  out Rebuild extends Top,
  in out TypeParameters extends ReadonlyArray<Constraint> = readonly [],
  out TypeMutability extends Mutability = "readonly",
  out TypeOptionality extends Optionality = "required",
  out TypeConstructorDefault extends ConstructorDefault = "no-default",
  out EncodedMutability extends Mutability = "readonly",
  out EncodedOptionality extends Optionality = "required"
> extends Bottom<
  unknown,
  unknown,
  unknown,
  unknown,
  Ast,
  Rebuild,
  unknown,
  unknown,
  TypeParameters,
  unknown,
  TypeMutability,
  TypeOptionality,
  TypeConstructorDefault,
  EncodedMutability,
  EncodedOptionality
> {}

Source

Since v4.0.0

revealBottom

Section titled “revealBottom”

Returns a schema widened to the fully-parameterized Bottom interface, making all 14 type parameters visible to TypeScript.

Details

Normally, concrete schema interfaces (e.g. Schema<string>) hide most type parameters. revealBottom is useful when writing generic utilities that need to inspect or propagate the complete set of type parameters.

Example (Inspecting all type parameters of a schema)

import { Schema } from "effect"


const schema = Schema.String


// Widen to Bottom to access all 14 type parameters
const bottom = Schema.revealBottom(schema)


// `bottom` now exposes Type, Encoded, DecodingServices, EncodingServices,
// ast, Rebuild, ~type.make.in, Iso, ~type.parameters, etc.
type T = (typeof bottom)["Type"] // string
type E = (typeof bottom)["Encoded"] // string

Signature

declare const revealBottom: <S extends Top>(
  bottom: S
) => Bottom<
  S["Type"],
  S["Encoded"],
  S["DecodingServices"],
  S["EncodingServices"],
  S["ast"],
  S["Rebuild"],
  S["~type.make.in"],
  S["Iso"],
  S["~type.parameters"],
  S["~type.make"],
  S["~type.mutability"],
  S["~type.optionality"],
  S["~type.constructor.default"],
  S["~encoded.mutability"],
  S["~encoded.optionality"]
>

Source

Since v4.0.0

revealCodec

Section titled “revealCodec”

Returns a codec widened to the full Codec interface, prompting TypeScript to infer all four type parameters (T, E, RD, RE).

Details

When a schema is stored in a variable typed as Schema<T> or Top, the encoded type and service requirements are erased. Passing the value through revealCodec recovers those parameters without any runtime cost.

Example (Recovering encoded type from a schema variable)

import { Schema } from "effect"


const schema: Schema.Schema<number> = Schema.NumberFromString


// Without revealCodec, Encoded is unknown
const codec = Schema.revealCodec(schema)
type Enc = (typeof codec)["Encoded"] // string

Signature

declare const revealCodec: <T, E, RD, RE>(codec: Codec<T, E, RD, RE>) => Codec<T, E, RD, RE>

Source

Since v4.0.0

utils

Section titled “utils”

Annotations (namespace)

Section titled “Annotations (namespace)”

The Annotations namespace groups all annotation interfaces used to attach metadata to schemas. Annotations control documentation, validation messages, JSON Schema generation, equivalence, arbitrary generation, and more.

Details

Use resolveAnnotations to read the annotations attached to a schema at runtime.

Source

Since v4.0.0

Annotations (interface)

Section titled “Annotations (interface)”

This interface is used to define the annotations that can be attached to a schema. You can extend this interface to define your own annotations.

Details

Note that both a missing key or undefined is used to indicate that the annotation is not present.

This means that can remove any annotation by setting it to undefined.

Example (Defining your own annotations)

import { Schema } from "effect"


// Extend the Annotations interface with a custom `version` annotation
declare module "effect/Schema" {
  namespace Annotations {
    interface Annotations {
      readonly version?: readonly [major: number, minor: number, patch: number] | undefined
    }
  }
}


// The `version` annotation is now recognized by the TypeScript compiler
const schema = Schema.String.annotate({ version: [1, 2, 0] })


// const version: readonly [major: number, minor: number, patch: number] | undefined
const version = Schema.resolveAnnotations(schema)?.["version"]


if (version) {
  // Access individual parts of the version
  console.log(version[1])
  // Output: 2
}

Signature

export interface Annotations {
  readonly [x: string]: unknown
}

Source

Since v4.0.0

Augment (interface)

Section titled “Augment (interface)”

Annotations shared by all schema nodes. These map to common JSON Schema / OpenAPI fields: title, description, format, etc.

Signature

export interface Augment extends Annotations {
  /**
   * Human-readable description of what a value is expected to satisfy.
   *
   * **Details**
   *
   * For filter and refinement failures, the default formatter uses
   * `message` first, then `expected`, and finally falls back to `<filter>`.
   *
   * Use this to name a failed filter in the default message:
   * `Expected <expected>, got <actual>`.
   */
  readonly expected?: string | undefined
  readonly title?: string | undefined
  readonly description?: string | undefined
  readonly documentation?: string | undefined
  readonly readOnly?: boolean | undefined
  readonly writeOnly?: boolean | undefined
  readonly format?: string | undefined
  readonly contentEncoding?: string | undefined
  readonly contentMediaType?: string | undefined
}

Source

Since v4.0.0

Documentation (interface)

Section titled “Documentation (interface)”

Extends Augment with type-parametric default and examples fields.

Signature

export interface Documentation<T> extends Augment {
  readonly default?: T | undefined
  readonly examples?: ReadonlyArray<T> | undefined
}

Source

Since v4.0.0

Key (interface)

Section titled “Key (interface)”

Annotations for struct property schemas. Extends Documentation with an optional messageMissingKey to override the error message when the property key is absent during decoding.

Signature

export interface Key<T> extends Documentation<T> {
  /**
   * The message to use when a key is missing.
   */
  readonly messageMissingKey?: string | undefined
}

Source

Since v4.0.0

Bottom (interface)

Section titled “Bottom (interface)”

Base annotations shared by all composite schema nodes. Extends Documentation with error messages, branding, parse options, and arbitrary generation hooks. Declaration and other annotation interfaces build on top of this.

Signature

export interface Bottom<T, TypeParameters extends ReadonlyArray<Constraint>> extends Documentation<T> {
  /**
   * Complete message to use when this schema node reports an issue.
   *
   * **Details**
   *
   * This replaces the default message for matching issue types instead of
   * only changing the expected label. For a filter or refinement failure,
   * annotate the filter with `message` to replace the whole filter failure
   * message, or `expected` to keep the default
   * `Expected <expected>, got <actual>` shape.
   */
  readonly message?: string | undefined
  /**
   * The message to use when a key is unexpected.
   */
  readonly messageUnexpectedKey?: string | undefined
  /**
   * Stable 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.
   */
  readonly identifier?: string | undefined
  readonly parseOptions?: SchemaAST.ParseOptions | undefined
  /**
   * Optional metadata used to identify or extend the filter with custom data.
   */
  readonly meta?: Meta | undefined
  /**
   * Accumulated brands when multiple brands are added with `Schema.brand`.
   */
  readonly brands?: ReadonlyArray<string> | undefined
  readonly toArbitrary?: ToArbitrary.Declaration<T, TypeParameters> | undefined
}

Source

Since v4.0.0

Declaration (interface)

Section titled “Declaration (interface)”

Full annotation set for Declaration schema nodes — used when defining custom, opaque schema types via Schema.declare. Extends Bottom with optional codec, arbitrary, equivalence, and formatter hooks so that derived capabilities (JSON encoding, property testing, etc.) can be provided for the custom type.

Signature

export interface Declaration<T, TypeParameters extends ReadonlyArray<Constraint> = readonly []> extends Bottom<
  T,
  TypeParameters
> {
  readonly toCodec?: ((typeParameters: TypeParameters.Encoded<TypeParameters>) => SchemaAST.Link) | undefined
  readonly toCodecJson?: ((typeParameters: TypeParameters.Encoded<TypeParameters>) => SchemaAST.Link) | undefined
  readonly toCodecIso?: ((typeParameters: TypeParameters.Type<TypeParameters>) => SchemaAST.Link) | undefined
  readonly toArbitrary?: ToArbitrary.Declaration<T, TypeParameters> | undefined
  readonly toEquivalence?: ToEquivalence.Declaration<T, TypeParameters> | undefined
  readonly toFormatter?: ToFormatter.Declaration<T, TypeParameters> | undefined
  readonly typeConstructor?:
    | {
        readonly _tag: string
        readonly [key: string]: unknown
      }
    | undefined
  readonly generation?:
    | {
        readonly runtime: string
        readonly Type: string
        readonly Encoded?: string | undefined
        readonly importDeclaration?: string | undefined
      }
    | undefined
  /**
   * Used to collect sentinels from a Declaration SchemaAST.
   *
   * @internal
   */
  readonly "~sentinels"?: ReadonlyArray<SchemaAST.Sentinel> | undefined
}

Source

Since v4.0.0

Filter (interface)

Section titled “Filter (interface)”

Annotations for filter schema nodes (created via Schema.filter). Extends Augment with an optional error message, identifier, and metadata. Filters are intentionally non-parametric to keep them covariant.

Signature

export interface Filter extends Augment {
  /**
   * Complete message to use when this filter or refinement fails.
   *
   * **Details**
   *
   * The default formatter checks filter annotations in this order:
   * `message`, then `expected`, then `<filter>`.
   */
  readonly message?: string | undefined
  /**
   * Stable identifier for the schema after this filter is attached.
   *
   * **Details**
   *
   * This can affect schema tooling such as JSON Schema generation and
   * type-level failures before the filter runs, but it does not name the
   * failed filter itself. For filter failure messages, use `expected` or
   * `message`.
   */
  readonly identifier?: string | undefined
  /**
   * Optional metadata used to identify or extend the filter with custom data.
   */
  readonly meta?: Meta | undefined
  /**
   * Optional hints used by arbitrary derivation for this filter.
   *
   * **Details**
   *
   * The same annotation can be attached to a single filter or a
   * `FilterGroup`. Group hints apply to the same schema node while child
   * filters are still collected and checked normally.
   */
  readonly arbitrary?: ToArbitrary.Filter | undefined
  /**
   * Marks the filter as *structural*, meaning it applies to the shape or
   * structure of the container (e.g., array length, object keys) rather than
   * the contents.
   *
   * **Details**
   *
   * Example: `minLength` on an array is a structural filter.
   */
  readonly "~structural"?: boolean | undefined
}

Source

Since v4.0.0

Issue (interface)

Section titled “Issue (interface)”

Annotations that can be attached to schema issues.

Details

The optional message field overrides the default issue message.

Signature

export interface Issue extends Annotations {
  readonly message?: string | undefined
}

Source

Since v4.0.0

BuiltInMetaDefinitions (interface)

Section titled “BuiltInMetaDefinitions (interface)”

Registry of metadata payloads emitted by built-in schema filters and checks.

Details

Do not augment this interface with custom metadata; extend MetaDefinitions instead.

Signature

export interface BuiltInMetaDefinitions {
  // String Meta
  readonly isStringFinite: {
    readonly _tag: "isStringFinite"
    readonly regExp: globalThis.RegExp
  }
  readonly isStringBigInt: {
    readonly _tag: "isStringBigInt"
    readonly regExp: globalThis.RegExp
  }
  readonly isStringSymbol: {
    readonly _tag: "isStringSymbol"
    readonly regExp: globalThis.RegExp
  }
  readonly isMinLength: {
    readonly _tag: "isMinLength"
    readonly minLength: number
  }
  readonly isMaxLength: {
    readonly _tag: "isMaxLength"
    readonly maxLength: number
  }
  readonly isLengthBetween: {
    readonly _tag: "isLengthBetween"
    readonly minimum: number
    readonly maximum: number
  }
  readonly isPattern: {
    readonly _tag: "isPattern"
    readonly regExp: globalThis.RegExp
  }
  readonly isTrimmed: {
    readonly _tag: "isTrimmed"
    readonly regExp: globalThis.RegExp
  }
  readonly isUUID: {
    readonly _tag: "isUUID"
    readonly regExp: globalThis.RegExp
    readonly version: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | undefined
  }
  readonly isGUID: {
    readonly _tag: "isGUID"
    readonly regExp: globalThis.RegExp
  }
  readonly isULID: {
    readonly _tag: "isULID"
    readonly regExp: globalThis.RegExp
  }
  readonly isBase64: {
    readonly _tag: "isBase64"
    readonly regExp: globalThis.RegExp
  }
  readonly isBase64Url: {
    readonly _tag: "isBase64Url"
    readonly regExp: globalThis.RegExp
  }
  readonly isStartsWith: {
    readonly _tag: "isStartsWith"
    readonly startsWith: string
    readonly regExp: globalThis.RegExp
  }
  readonly isEndsWith: {
    readonly _tag: "isEndsWith"
    readonly endsWith: string
    readonly regExp: globalThis.RegExp
  }
  readonly isIncludes: {
    readonly _tag: "isIncludes"
    readonly includes: string
    readonly regExp: globalThis.RegExp
  }
  readonly isUppercased: {
    readonly _tag: "isUppercased"
    readonly regExp: globalThis.RegExp
  }
  readonly isLowercased: {
    readonly _tag: "isLowercased"
    readonly regExp: globalThis.RegExp
  }
  readonly isCapitalized: {
    readonly _tag: "isCapitalized"
    readonly regExp: globalThis.RegExp
  }
  readonly isUncapitalized: {
    readonly _tag: "isUncapitalized"
    readonly regExp: globalThis.RegExp
  }
  // Number Meta
  readonly isFinite: {
    readonly _tag: "isFinite"
  }
  readonly isInt: {
    readonly _tag: "isInt"
  }
  readonly isMultipleOf: {
    readonly _tag: "isMultipleOf"
    readonly divisor: number
  }
  readonly isGreaterThan: {
    readonly _tag: "isGreaterThan"
    readonly exclusiveMinimum: number
  }
  readonly isGreaterThanOrEqualTo: {
    readonly _tag: "isGreaterThanOrEqualTo"
    readonly minimum: number
  }
  readonly isLessThan: {
    readonly _tag: "isLessThan"
    readonly exclusiveMaximum: number
  }
  readonly isLessThanOrEqualTo: {
    readonly _tag: "isLessThanOrEqualTo"
    readonly maximum: number
  }
  readonly isBetween: {
    readonly _tag: "isBetween"
    readonly minimum: number
    readonly maximum: number
    readonly exclusiveMinimum?: boolean | undefined
    readonly exclusiveMaximum?: boolean | undefined
  }
  // BigInt Meta
  readonly isGreaterThanBigInt: {
    readonly _tag: "isGreaterThanBigInt"
    readonly exclusiveMinimum: bigint
  }
  readonly isGreaterThanOrEqualToBigInt: {
    readonly _tag: "isGreaterThanOrEqualToBigInt"
    readonly minimum: bigint
  }
  readonly isLessThanBigInt: {
    readonly _tag: "isLessThanBigInt"
    readonly exclusiveMaximum: bigint
  }
  readonly isLessThanOrEqualToBigInt: {
    readonly _tag: "isLessThanOrEqualToBigInt"
    readonly maximum: bigint
  }
  readonly isBetweenBigInt: {
    readonly _tag: "isBetweenBigInt"
    readonly minimum: bigint
    readonly maximum: bigint
    readonly exclusiveMinimum?: boolean | undefined
    readonly exclusiveMaximum?: boolean | undefined
  }
  // Date Meta
  readonly isDateValid: {
    readonly _tag: "isDateValid"
  }
  readonly isGreaterThanDate: {
    readonly _tag: "isGreaterThanDate"
    readonly exclusiveMinimum: globalThis.Date
  }
  readonly isGreaterThanOrEqualToDate: {
    readonly _tag: "isGreaterThanOrEqualToDate"
    readonly minimum: globalThis.Date
  }
  readonly isLessThanDate: {
    readonly _tag: "isLessThanDate"
    readonly exclusiveMaximum: globalThis.Date
  }
  readonly isLessThanOrEqualToDate: {
    readonly _tag: "isLessThanOrEqualToDate"
    readonly maximum: globalThis.Date
  }
  readonly isBetweenDate: {
    readonly _tag: "isBetweenDate"
    readonly minimum: globalThis.Date
    readonly maximum: globalThis.Date
    readonly exclusiveMinimum?: boolean | undefined
    readonly exclusiveMaximum?: boolean | undefined
  }
  // Objects Meta
  readonly isMinProperties: {
    readonly _tag: "isMinProperties"
    readonly minProperties: number
  }
  readonly isMaxProperties: {
    readonly _tag: "isMaxProperties"
    readonly maxProperties: number
  }
  readonly isPropertiesLengthBetween: {
    readonly _tag: "isPropertiesLengthBetween"
    readonly minimum: number
    readonly maximum: number
  }
  readonly isPropertyNames: {
    readonly _tag: "isPropertyNames"
    readonly propertyNames: SchemaAST.AST
  }
  // Arrays Meta
  readonly isUnique: {
    readonly _tag: "isUnique"
  }
  // Declaration Meta
  readonly isMinSize: {
    readonly _tag: "isMinSize"
    readonly minSize: number
  }
  readonly isMaxSize: {
    readonly _tag: "isMaxSize"
    readonly maxSize: number
  }
  readonly isSizeBetween: {
    readonly _tag: "isSizeBetween"
    readonly minimum: number
    readonly maximum: number
  }
}

Source

Since v4.0.0

MetaDefinitions (interface)

Section titled “MetaDefinitions (interface)”

Augmentable registry of schema filter metadata payloads.

Details

Extend this interface to add custom values accepted by annotation meta fields.

Signature

export interface MetaDefinitions extends BuiltInMetaDefinitions {}

Source

Since v4.0.0

BuiltInMeta (type alias)

Section titled “BuiltInMeta (type alias)”

Union of all metadata payloads defined by BuiltInMetaDefinitions.

Signature

type BuiltInMeta = BuiltInMetaDefinitions[keyof BuiltInMetaDefinitions]

Source

Since v4.0.0

Meta (type alias)

Section titled “Meta (type alias)”

Union of built-in and user-augmented schema filter metadata payloads.

Signature

type Meta = MetaDefinitions[keyof MetaDefinitions]

Source

Since v4.0.0

TypeParameters (namespace)

Section titled “TypeParameters (namespace)”

Helpers for projecting declaration type-parameter schemas into decoded or encoded codec arrays used by annotation hooks.

Source

Since v4.0.0

Type (type alias)

Section titled “Type (type alias)”

Maps declaration type-parameter schemas to codecs for their decoded Type values.

Signature

type Type<TypeParameters> = {
  readonly [K in keyof TypeParameters]: Codec<TypeParameters[K]["Type"]>
}

Source

Since v4.0.0

Encoded (type alias)

Section titled “Encoded (type alias)”

Maps declaration type-parameter schemas to codecs for their Encoded values.

Signature

type Encoded<TypeParameters> = {
  readonly [K in keyof TypeParameters]: Codec<TypeParameters[K]["Encoded"]>
}

Source

Since v4.0.0

ToArbitrary (namespace)

Section titled “ToArbitrary (namespace)”

Types used by arbitrary-derivation annotations to configure toArbitrary hooks, filter hints, candidate sources, diagnostics, and merged generation constraints.

Source

Since v4.0.0

Filter (interface)

Section titled “Filter (interface)”

Arbitrary-generation hints attached to a filter or filter group.

Details

constraint refines the schema node’s base generator. candidate adds a weighted source before all filters run. If neither hint is provided, the filter does not guide generation; generated values are still checked by the filter predicate. With { report: true }, this is reported as OpaqueFilter.

Signature

export interface Filter {
  readonly constraint?: GenerationConstraint | undefined
  readonly candidate?: Candidate | undefined
}

Source

Since v4.0.0

Candidate (interface)

Section titled “Candidate (interface)”

Additional arbitrary source used before final filter checks run.

Details

The base generator keeps weight 1; candidates default to weight 1 and must use a positive integer weight. make receives the merged constraint for the current node and may return undefined to opt out, including for recursive terminal branches. Candidate values are still checked by every schema filter, so invalid candidates affect efficiency but not validity.

Signature

export interface Candidate {
  readonly weight?: number | undefined
  readonly make: (fc: typeof FastCheck, context: Context) => FastCheck.Arbitrary<unknown> | undefined
}

Source

Since v4.0.0

OrderedConstraint (interface)

Section titled “OrderedConstraint (interface)”

Ordered constraint accumulated from range checks.

Details

Generators consume these constraints only when they recognize order, such as Order.Number, Order.BigInt, DateTime, or BigDecimal. Merging constraints with different Order instances fails fast.

Signature

export interface OrderedConstraint<T> {
  readonly order: Order.Order<T>
  readonly minimum?: T | undefined
  readonly exclusiveMinimum?: boolean | undefined
  readonly maximum?: T | undefined
  readonly exclusiveMaximum?: boolean | undefined
}

Source

Since v4.0.0

GenerationConstraint (interface)

Section titled “GenerationConstraint (interface)”

Node-local arbitrary-generation constraint accumulated from schema checks.

Details

GenerationConstraint is a generation hint for the current schema AST node, not a self-describing validation contract. Each generator consumes the fields it understands for the current node and ignores the rest; final schema filters still validate every generated value.

minLength and maxLength represent node-local cardinality: string length for strings, array length for arrays, final own-property count for objects, and final size/cardinality for sets, maps, hash collections, and chunks. patterns are concatenated and used by string generators. integer, noNaN, noInfinity, valid, and unique are true when any contributing filter sets them. Range bounds live in ordered so ordered values can share the same representation.

Signature

export interface GenerationConstraint {
  readonly minLength?: number | undefined
  readonly maxLength?: number | undefined
  readonly patterns?: readonly [string, ...Array<string>]
  readonly integer?: boolean | undefined
  readonly noInfinity?: boolean | undefined
  readonly noNaN?: boolean | undefined
  readonly valid?: boolean | undefined
  readonly unique?: boolean | undefined
  readonly ordered?: OrderedConstraint<any> | undefined
}

Source

Since v4.0.0

Recursion (interface)

Section titled “Recursion (interface)”

Recursion budget passed to arbitrary-derivation hooks.

Details

Pass this object to fc.oneof when combining terminal and recursive branches. Put the terminal branch first because fast-check uses only the first branch once maxDepth is reached for depthIdentifier.

Signature

export interface Recursion {
  readonly maxDepth: number
  readonly depthIdentifier: FastCheck.DepthIdentifier | string
}

Source

Since v4.0.0

Context (interface)

Section titled “Context (interface)”

Context passed to arbitrary-derivation hooks and candidate factories.

Details

constraint contains the merged constraint for the current schema node. recursion is present while deriving through a suspended schema; hooks that build recursive alternatives should pass it to fc.oneof with the finite branch first.

Signature

export interface Context {
  readonly constraint?: ToArbitrary.GenerationConstraint | undefined
  readonly recursion?: ToArbitrary.Recursion | undefined
}

Source

Since v4.0.0

TypeParameter (interface)

Section titled “TypeParameter (interface)”

Arbitrary generators derived for a declaration type parameter.

Details

arbitrary is the normal generator. terminal is the finite generator used while building recursive terminal branches and is undefined when no finite path is known. Optional containers can ignore it; non-empty containers need it for their terminal branch.

Signature

export interface TypeParameter<T> {
  readonly arbitrary: FastCheck.Arbitrary<T>
  readonly terminal: FastCheck.Arbitrary<T> | undefined
}

Source

Since v4.0.0

Derivation (interface)

Section titled “Derivation (interface)”

Arbitrary derivation returned by declaration hooks.

Details

arbitrary is the normal generator. terminal is an optional finite branch for recursive schemas. If omitted, it defaults to arbitrary only for declarations without type parameters.

Signature

export interface Derivation<T> {
  readonly arbitrary: FastCheck.Arbitrary<T>
  readonly terminal?: FastCheck.Arbitrary<T> | undefined
}

Source

Since v4.0.0

Declaration (interface)

Section titled “Declaration (interface)”

Hook signature for declaration schema arbitrary annotations.

Details

Type parameters expose normal and terminal generators. A declaration with no type parameters can return a bare arbitrary; a generic declaration must return terminal explicitly when it has a finite branch depending on parameters.

Signature

export interface Declaration<T, TypeParameters extends ReadonlyArray<Constraint>> {
  (
    /* Arbitrary derivations for any type parameters of the schema (if present) */
    typeParameters: { readonly [K in keyof TypeParameters]: TypeParameter<TypeParameters[K]["Type"]> }
  ): (fc: typeof FastCheck, context: Context) => Output<T>
}

Source

Since v4.0.0

WithReport (interface)

Section titled “WithReport (interface)”

Wraps a derived value together with arbitrary-derivation diagnostics.

Signature

export interface WithReport<A> {
  readonly value: A
  readonly report: Report
}

Source

Since v4.0.0

Report (interface)

Section titled “Report (interface)”

Diagnostics collected while deriving an arbitrary.

Details

Reports contain warnings only. Unsupported schema nodes, impossible constraints, invalid candidate weights, and throwing candidate factories fail immediately.

Signature

export interface Report {
  readonly warnings: ReadonlyArray<Warning>
}

Source

Since v4.0.0

OpaqueFilterWarning (interface)

Section titled “OpaqueFilterWarning (interface)”

Warning emitted when a filter is handled only by the final .filter.

Details

The filter is still enforced. The warning means it did not contribute a constraint or candidate, so generation may rely on fast-check discards.

Signature

export interface OpaqueFilterWarning {
  readonly _tag: "OpaqueFilter"
  readonly path: ReadonlyArray<PropertyKey>
  readonly description?: string | undefined
}

Source

Since v4.0.0

Output (type alias)

Section titled “Output (type alias)”

Output accepted from declaration arbitrary hooks.

Details

A bare fast-check arbitrary is shorthand for { arbitrary }, useful for atomic declarations such as URLs. Generic declarations that need precise recursive behavior should return a Derivation with terminal.

Signature

type Output<T> = FastCheck.Arbitrary<T> | Derivation<T>

Source

Since v4.0.0

Warning (type alias)

Section titled “Warning (type alias)”

Non-fatal arbitrary-derivation warning.

Signature

type Warning = OpaqueFilterWarning

Source

Since v4.0.0

ToFormatter (namespace)

Section titled “ToFormatter (namespace)”

Types used by formatter annotations to customize formatter derivation for declaration schemas.

Source

Since v4.0.0

Declaration (interface)

Section titled “Declaration (interface)”

Hook signature for declaration schema formatter annotations.

Details

Given formatters for any type parameters, returns a formatter for T.

Signature

export interface Declaration<T, TypeParameters extends ReadonlyArray<Constraint>> {
  (
    /* Formatters for any type parameters of the schema (if present) */
    typeParameters: { readonly [K in keyof TypeParameters]: Formatter<TypeParameters[K]["Type"]> }
  ): Formatter<T>
}

Source

Since v4.0.0

ToEquivalence (namespace)

Section titled “ToEquivalence (namespace)”

Types used by equivalence annotations to customize equivalence derivation for declaration schemas.

Source

Since v4.0.0

Declaration (interface)

Section titled “Declaration (interface)”

Hook signature for declaration schema equivalence annotations.

Details

Given equivalences for any type parameters, returns an Equivalence for T.

Signature

export interface Declaration<T, TypeParameters extends ReadonlyArray<Constraint>> {
  (
    /* Equivalences for any type parameters of the schema (if present) */
    typeParameters: { readonly [K in keyof TypeParameters]: Equivalence.Equivalence<TypeParameters[K]["Type"]> }
  ): Equivalence.Equivalence<T>
}

Source

Since v4.0.0

Codec (namespace)

Section titled “Codec (namespace)”

Namespace of type-level helpers for Codec.

Source

Since v4.0.0

Encoded (type alias)

Section titled “Encoded (type alias)”

Extracts the encoded (Encoded) type from a schema.

Example (Extracting the encoded type)

import { Schema } from "effect"


const schema = Schema.NumberFromString
type Enc = Schema.Codec.Encoded<typeof schema>
// string

Signature

type Encoded<S> = S extends { readonly Encoded: infer E } ? E : never

Source

Since v3.10.0

DecodingServices (type alias)

Section titled “DecodingServices (type alias)”

Extracts the Effect services required during decoding from a schema.

Example (Checking decoding service requirements)

import { Schema } from "effect"


const schema = Schema.String
type RD = Schema.Codec.DecodingServices<typeof schema>
// never

Signature

type DecodingServices<S> = S extends { readonly DecodingServices: infer R } ? R : never

Source

Since v4.0.0

EncodingServices (type alias)

Section titled “EncodingServices (type alias)”

Extracts the Effect services required during encoding from a schema.

Example (Checking encoding service requirements)

import { Schema } from "effect"


const schema = Schema.String
type RE = Schema.Codec.EncodingServices<typeof schema>
// never

Signature

type EncodingServices<S> = S extends { readonly EncodingServices: infer R } ? R : never

Source

Since v4.0.0

Record (namespace)

Section titled “Record (namespace)”

Namespace for Record type utilities.

Details

  • Record.Key — constraint for the key schema (must encode to PropertyKey)
  • Record.Type<K, V> — decoded type of the record
  • Record.Encoded<K, V> — encoded type of the record

Source

Since v3.10.0

Key (interface)

Section titled “Key (interface)”

Constraint for schemas that can be used as record keys.

Details

The key schema must decode and encode property keys (string, number, or symbol) so it can describe object property names.

Signature

export interface Key extends Codec<PropertyKey, PropertyKey, unknown, unknown> {
  readonly "~type.make": PropertyKey
  readonly Iso: PropertyKey
}

Source

Since v4.0.0

Type (type alias)

Section titled “Type (type alias)”

Computes the decoded object type for a record schema from its key and value schemas.

Details

The key schema supplies the property keys and the value schema supplies each property’s decoded Type. Optional and mutable value schemas affect the resulting property optionality and writability.

Signature

type Type<Key, Value> = Value extends { readonly "~type.optionality": "optional" }
  ? Value extends { readonly "~type.mutability": "mutable" }
    ? { [P in Key["Type"]]?: Value["Type"] }
    : { readonly [P in Key["Type"]]?: Value["Type"] }
  : Value extends { readonly "~type.mutability": "mutable" }
    ? { [P in Key["Type"]]: Value["Type"] }
    : { readonly [P in Key["Type"]]: Value["Type"] }

Source

Since v3.10.0

Iso (type alias)

Section titled “Iso (type alias)”

Computes the iso object type for a record schema from the key schema’s Iso keys and the value schema’s Iso values.

Signature

type Iso<Key, Value> = Value extends { readonly "~type.optionality": "optional" }
  ? Value extends { readonly "~type.mutability": "mutable" }
    ? { [P in Key["Iso"]]?: Value["Iso"] }
    : { readonly [P in Key["Iso"]]?: Value["Iso"] }
  : Value extends { readonly "~type.mutability": "mutable" }
    ? { [P in Key["Iso"]]: Value["Iso"] }
    : { readonly [P in Key["Iso"]]: Value["Iso"] }

Source

Since v4.0.0

Encoded (type alias)

Section titled “Encoded (type alias)”

Computes the encoded object type for a record schema from the key and value schemas’ encoded types.

Details

Encoded-side optionality and mutability on the value schema determine whether the encoded record properties are optional or writable.

Signature

type Encoded<Key, Value> = Value extends { readonly "~encoded.optionality": "optional" }
  ? Value extends { readonly "~encoded.mutability": "mutable" }
    ? { [P in Key["Encoded"]]?: Value["Encoded"] }
    : { readonly [P in Key["Encoded"]]?: Value["Encoded"] }
  : Value extends { readonly "~encoded.mutability": "mutable" }
    ? { [P in Key["Encoded"]]: Value["Encoded"] }
    : { readonly [P in Key["Encoded"]]: Value["Encoded"] }

Source

Since v3.10.0

DecodingServices (type alias)

Section titled “DecodingServices (type alias)”

Union of the decoding service requirements of a record’s key schema and value schema.

Signature

type DecodingServices<Key, Value> = Key["DecodingServices"] | Value["DecodingServices"]

Source

Since v4.0.0

EncodingServices (type alias)

Section titled “EncodingServices (type alias)”

Union of the encoding service requirements of a record’s key schema and value schema.

Signature

type EncodingServices<Key, Value> = Key["EncodingServices"] | Value["EncodingServices"]

Source

Since v4.0.0

MakeIn (type alias)

Section titled “MakeIn (type alias)”

Computes the input object type accepted when constructing a record value.

Details

Keys use the key schema’s ~type.make type and values use the value schema’s ~type.make type. Value optionality and mutability determine whether properties are optional or writable.

Signature

type MakeIn<Key, Value> = Value extends { readonly "~encoded.optionality": "optional" }
  ? Value extends { readonly "~encoded.mutability": "mutable" }
    ? { [P in Key["~type.make"]]?: Value["~type.make"] }
    : { readonly [P in Key["~type.make"]]?: Value["~type.make"] }
  : Value extends { readonly "~encoded.mutability": "mutable" }
    ? { [P in Key["~type.make"]]: Value["~type.make"] }
    : { readonly [P in Key["~type.make"]]: Value["~type.make"] }

Source

Since v4.0.0

Schema (namespace)

Section titled “Schema (namespace)”

Namespace of type-level helpers for Schema.

Source

Since v3.10.0

Type (type alias)

Section titled “Type (type alias)”

Extracts the decoded Type from a schema.

Example (Extracting the decoded type)

import { Schema } from "effect"


const Person = Schema.Struct({ name: Schema.String, age: Schema.Number })
type Person = Schema.Schema.Type<typeof Person>
// { readonly name: string; readonly age: number }

Signature

type Type<S> = S extends { readonly Type: infer T } ? T : never

Source

Since v3.10.0

Struct (namespace)

Section titled “Struct (namespace)”

Namespace for struct field type utilities.

Details

These types compute the decoded Type, encoded Encoded, and constructor input MakeIn of a Struct from its field map, handling optional, mutable, and other field modifiers automatically.

  • Struct.Fields — constraint for the field map object
  • Struct.Type<F> — decoded type of the struct
  • Struct.Encoded<F> — encoded type of the struct
  • Struct.MakeIn<F> — constructor input (optional/defaulted fields may be omitted)
  • Struct.DecodingServices<F> / Struct.EncodingServices<F> — required services

Source

Since v3.10.0

Fields (type alias)

Section titled “Fields (type alias)”

Constraint for a struct field map: an object whose values are schemas.

Signature

type Fields = { readonly [x: PropertyKey]: Constraint }

Source

Since v3.10.0

Type (type alias)

Section titled “Type (type alias)”

Computes the decoded object type for a struct field map.

Details

Field schemas contribute their decoded Type. optionalKey and optional produce optional properties, while mutableKey produces writable properties.

Signature

type Type<F> = View<F, "Type">

Source

Since v3.10.0

Iso (type alias)

Section titled “Iso (type alias)”

Computes the iso object type for a struct field map from each field schema’s Iso type.

Details

The resulting property optionality and mutability follow the same field modifiers used by Struct.Type.

Signature

type Iso<F> = View<F, "Iso">

Source

Since v4.0.0

Encoded (type alias)

Section titled “Encoded (type alias)”

Computes the encoded object type for a struct field map.

Details

Field schemas contribute their Encoded type. Encoded-side optionality and mutability modifiers determine whether properties are optional or writable in the encoded shape.

Signature

type Encoded<F> = View<F, "Encoded">

Source

Since v3.10.0

DecodingServices (type alias)

Section titled “DecodingServices (type alias)”

Union of all decoding service requirements needed by the schemas in a struct field map.

Signature

type DecodingServices<F> = { readonly [K in keyof F]: F[K]["DecodingServices"] }[keyof F]

Source

Since v4.0.0

EncodingServices (type alias)

Section titled “EncodingServices (type alias)”

Union of all encoding service requirements needed by the schemas in a struct field map.

Signature

type EncodingServices<F> = { readonly [K in keyof F]: F[K]["EncodingServices"] }[keyof F]

Source

Since v4.0.0

MakeIn (type alias)

Section titled “MakeIn (type alias)”

Computes the input object type accepted when constructing a struct value.

Details

Required fields use each field schema’s ~type.make input. Fields marked optional or with a constructor default may be omitted.

Signature

type MakeIn<F> = MakeInView<F>

Source

Since v4.0.0

StructWithRest (namespace)

Section titled “StructWithRest (namespace)”

Namespace for StructWithRest type utilities.

Details

  • StructWithRest.Type<S, R> — decoded type (struct type intersected with record types)
  • StructWithRest.Encoded<S, R> — encoded type

Source

Since v4.0.0

Objects (type alias)

Section titled “Objects (type alias)”

Constraint for object-like schemas that can be used as the fixed portion of a StructWithRest schema.

Signature

type Objects = Constraint & { readonly ast: SchemaAST.Objects }

Source

Since v4.0.0

Records (type alias)

Section titled “Records (type alias)”

Readonly list of record schemas that provide the additional index signatures for a StructWithRest schema.

Signature

type Records = ReadonlyArray<$Record<Record.Key, Constraint>>

Source

Since v3.10.0

Type (type alias)

Section titled “Type (type alias)”

Computes the decoded type for StructWithRest by intersecting the base object schema’s decoded Type with the decoded types of all rest record schemas.

Signature

type Type<S, Records> = Intersect<S, Records, "Type">

Source

Since v3.10.0

Iso (type alias)

Section titled “Iso (type alias)”

Computes the iso type for StructWithRest by intersecting the base object schema’s Iso type with the Iso types of all rest record schemas.

Signature

type Iso<S, Records> = Intersect<S, Records, "Iso">

Source

Since v4.0.0

Encoded (type alias)

Section titled “Encoded (type alias)”

Computes the encoded type for StructWithRest by intersecting the base object schema’s encoded type with the encoded types of all rest record schemas.

Signature

type Encoded<S, Records> = Intersect<S, Records, "Encoded">

Source

Since v3.10.0

MakeIn (type alias)

Section titled “MakeIn (type alias)”

Computes the input type accepted when constructing a StructWithRest value by intersecting the base object’s make input with the make inputs of all rest record schemas.

Signature

type MakeIn<S, Records> = Intersect<S, Records, "~type.make">

Source

Since v4.0.0

DecodingServices (type alias)

Section titled “DecodingServices (type alias)”

Union of the decoding service requirements of the base object schema and all rest record schemas.

Signature

type DecodingServices<S, Records> = Services<S, Records, "DecodingServices">

Source

Since v4.0.0

EncodingServices (type alias)

Section titled “EncodingServices (type alias)”

Union of the encoding service requirements of the base object schema and all rest record schemas.

Signature

type EncodingServices<S, Records> = Services<S, Records, "EncodingServices">

Source

Since v4.0.0

ValidateRecords (type alias)

Section titled “ValidateRecords (type alias)”

Checks whether fixed fields are compatible with the rest record schemas.

Details

Returns true when all fixed fields can also satisfy the matching rest index signatures. Returns a diagnostic object when TypeScript would make the resulting intersection too narrow for one or more fixed keys.

Example (Checking record compatibility)

import { Schema } from "effect"


const user = Schema.Struct({ id: Schema.String })
const stringExtras = [Schema.Record(Schema.String, Schema.String)] as const


type UserCheck = Schema.StructWithRest.ValidateRecords<typeof user, typeof stringExtras>


const userCheck: UserCheck = true
void userCheck


const counter = Schema.Struct({ count: Schema.NumberFromString })


type CounterCheck = Schema.StructWithRest.ValidateRecords<typeof counter, typeof stringExtras>
//    ^? { "incompatible index signatures": "count" }


const counterCheck = null as unknown as CounterCheck
void counterCheck

Signature

type ValidateRecords<S, Records> = [IncompatibleRecords<S, Records>] extends [never]
  ? true
  : {
      "incompatible index signatures": IncompatibleRecords<S, Records>
    }

Source

Since v4.0.0

TemplateLiteral (namespace)

Section titled “TemplateLiteral (namespace)”

Namespace for TemplateLiteral helper types.

Source

Since v3.10.0

SchemaPart (interface)

Section titled “SchemaPart (interface)”

Constraint for schema parts that can appear inside a TemplateLiteral.

Details

The schema’s encoded value must be a string, number, or bigint so it can be converted into a template literal string segment.

Signature

export interface SchemaPart extends Constraint {
  readonly Encoded: string | number | bigint
}

Source

Since v4.0.0

LiteralPart (type alias)

Section titled “LiteralPart (type alias)”

Literal value that can be used directly as a part of a TemplateLiteral.

Signature

type LiteralPart = string | number | bigint

Source

Since v4.0.0

Part (type alias)

Section titled “Part (type alias)”

A single part of a TemplateLiteral, either an interpolated schema part or a literal string, number, or bigint.

Signature

type Part = SchemaPart | LiteralPart

Source

Since v4.0.0

Parts (type alias)

Section titled “Parts (type alias)”

Ordered list of parts used to construct a TemplateLiteral schema.

Signature

type Parts = ReadonlyArray<Part>

Source

Since v4.0.0

Encoded (type alias)

Section titled “Encoded (type alias)”

Computes the encoded string literal type produced by concatenating the encoded forms of all template literal parts.

Signature

type Encoded<Parts> = Parts extends readonly [...infer Init, infer Last] ? AppendType<Encoded<Init>, Last> : ``

Source

Since v3.10.0

TemplateLiteralParser (namespace)

Section titled “TemplateLiteralParser (namespace)”

Namespace for TemplateLiteralParser helper types.

Source

Since v3.10.0

Type (type alias)

Section titled “Type (type alias)”

Computes the decoded tuple type produced by TemplateLiteralParser.

Details

Literal parts contribute their literal value to the tuple. Schema parts contribute their decoded Type.

Signature

type Type<Parts> = Parts extends readonly [infer Head, ...infer Tail]
  ? readonly [
      Head extends TemplateLiteral.LiteralPart
        ? Head
        : Head extends Codec<infer T, unknown, unknown, unknown>
          ? T
          : never,
      ...Type<Tail>
    ]
  : []

Source

Since v3.10.0

Tuple (namespace)

Section titled “Tuple (namespace)”

Namespace for Tuple type utilities.

Details

  • Tuple.Elements — constraint for the element schema array
  • Tuple.Type<E> — decoded tuple type
  • Tuple.Encoded<E> — encoded tuple type
  • Tuple.MakeIn<E> — constructor input tuple

Source

Since v3.10.0

Elements (type alias)

Section titled “Elements (type alias)”

Constraint for the readonly array of element schemas used to define a fixed-length Tuple schema.

Signature

type Elements = ReadonlyArray<Constraint>

Source

Since v3.10.0

Type (type alias)

Section titled “Type (type alias)”

Computes the decoded tuple type for a tuple element schema array.

Details

Each element contributes its decoded Type; optional element schemas produce optional tuple positions.

Signature

type Type<E> = Type_<E>

Source

Since v3.10.0

Iso (type alias)

Section titled “Iso (type alias)”

Computes the iso tuple type for a tuple element schema array from each element schema’s Iso type.

Signature

type Iso<E> = Iso_<E>

Source

Since v4.0.0

Encoded (type alias)

Section titled “Encoded (type alias)”

Computes the encoded tuple type for a tuple element schema array.

Details

Each element contributes its Encoded type; encoded-side optional element schemas produce optional tuple positions.

Signature

type Encoded<E> = Encoded_<E>

Source

Since v3.10.0

DecodingServices (type alias)

Section titled “DecodingServices (type alias)”

Union of all decoding service requirements needed by the tuple element schemas.

Signature

type DecodingServices<E> = E[number]["DecodingServices"]

Source

Since v4.0.0

EncodingServices (type alias)

Section titled “EncodingServices (type alias)”

Union of all encoding service requirements needed by the tuple element schemas.

Signature

type EncodingServices<E> = E[number]["EncodingServices"]

Source

Since v4.0.0

MakeIn (type alias)

Section titled “MakeIn (type alias)”

Computes the input tuple type accepted when constructing a tuple value.

Details

Each element uses its ~type.make input type. Optional elements and elements with constructor defaults produce optional tuple positions.

Signature

type MakeIn<E> = MakeIn_<E>

Source

Since v4.0.0

TupleWithRest (namespace)

Section titled “TupleWithRest (namespace)”

Namespace for TupleWithRest type utilities.

Details

  • TupleWithRest.TupleType — constraint for the leading tuple schema
  • TupleWithRest.Rest — the rest element schema(s)
  • TupleWithRest.Type<T, R> — decoded type (fixed elements + rest)
  • TupleWithRest.Encoded<T, R> — encoded type

Source

Since v4.0.0

TupleType (type alias)

Section titled “TupleType (type alias)”

Constraint for tuple-like schemas that can be used as the fixed leading portion of a TupleWithRest schema.

Signature

type TupleType = Constraint & {
  readonly Type: ReadonlyArray<unknown>
  readonly Encoded: ReadonlyArray<unknown>
  readonly ast: SchemaAST.Arrays
  readonly "~type.make": ReadonlyArray<unknown>
  readonly Iso: ReadonlyArray<unknown>
}

Source

Since v3.10.0

Rest (type alias)

Section titled “Rest (type alias)”

Non-empty list of schemas used for the rest portion of a TupleWithRest.

Details

The first schema describes the repeated rest element. Additional schemas, when present, describe trailing tuple elements after the repeated rest segment.

Signature

type Rest = readonly [Constraint, ...Array<Constraint>]

Source

Since v3.10.0

Type (type alias)

Section titled “Type (type alias)”

Computes the decoded tuple type for a TupleWithRest.

Details

The output starts with the fixed tuple elements, continues with zero or more values decoded by the first rest schema, and includes any trailing rest schemas as fixed tuple positions.

Signature

type Type<T, Rest> = Rest extends readonly [
  infer Head extends Constraint,
  ...infer Tail extends ReadonlyArray<Constraint>
]
  ? Readonly<[...T, ...Array<Head["Type"]>, ...{ readonly [K in keyof Tail]: Tail[K]["Type"] }]>
  : T

Source

Since v3.10.0

Iso (type alias)

Section titled “Iso (type alias)”

Computes the iso tuple type for a TupleWithRest.

Details

The output starts with the fixed tuple’s Iso elements, continues with zero or more values using the first rest schema’s Iso, and includes any trailing rest schemas as fixed tuple positions.

Signature

type Iso<T, Rest> = Rest extends readonly [
  infer Head extends Constraint,
  ...infer Tail extends ReadonlyArray<Constraint>
]
  ? Readonly<[...T, ...Array<Head["Iso"]>, ...{ readonly [K in keyof Tail]: Tail[K]["Iso"] }]>
  : T

Source

Since v4.0.0

Encoded (type alias)

Section titled “Encoded (type alias)”

Computes the encoded tuple type for TupleWithRest.

Details

The leading tuple’s encoded elements are kept first. The encoded type of the first rest schema may repeat zero or more times, and the encoded types of any additional rest schemas become required trailing tuple elements.

Signature

type Encoded<E, Rest> = Rest extends readonly [
  infer Head extends Constraint,
  ...infer Tail extends ReadonlyArray<Constraint>
]
  ? readonly [...E, ...Array<Head["Encoded"]>, ...{ readonly [K in keyof Tail]: Tail[K]["Encoded"] }]
  : E

Source

Since v3.10.0

MakeIn (type alias)

Section titled “MakeIn (type alias)”

Computes the constructor input tuple type for TupleWithRest.

Details

The leading tuple’s make input elements are kept first. The make input type of the first rest schema may repeat zero or more times, and the make input types of any additional rest schemas become required trailing tuple elements.

Signature

type MakeIn<M, Rest> = Rest extends readonly [
  infer Head extends Constraint,
  ...infer Tail extends ReadonlyArray<Constraint>
]
  ? readonly [...M, ...Array<Head["~type.make"]>, ...{ readonly [K in keyof Tail]: Tail[K]["~type.make"] }]
  : M

Source

Since v4.0.0