Effect Data Types

Effect provides schemas for its runtime data types, including Option, Result, Exit, hash collections, Duration, and Redacted.

These schemas expect the corresponding runtime value on both sides. Their inner schemas can still transform the contained values. When you need a JSON-compatible representation, derive it with Schema.toCodecJson.

Example (Runtime Values and Their JSON Representation)

1
import { Option, Schema } from "effect"
2

3
const RuntimeOption = Schema.Option(Schema.FiniteFromString)
4

5
Schema.decodeUnknownSync(RuntimeOption)(Option.some("1")) // => Option.some(1)
6
Schema.encodeSync(RuntimeOption)(Option.some(1)) // => Option.some("1")
7

8
const JsonOption = Schema.toCodecJson(RuntimeOption)
9

10
Schema.decodeUnknownSync(JsonOption)({ _tag: "Some", value: "1" }) // => Option.some(1)
11
Schema.encodeSync(JsonOption)(Option.some(1)) // => { _tag: "Some", value: "1" }

Config

Use Config.schema to read and decode configuration with a schema. The provider supplies the encoded representation, and the resulting Config produces the schema’s Type.

Example (Reading Structured Configuration)

1
import { Config, ConfigProvider, Effect, Schema } from "effect"
2

3
const DatabaseConfig = Config.schema(
4
  Schema.Struct({
5
    host: Schema.String,
6
    port: Schema.Finite,
7
  }),
8
  "database",
9
)
10

11
const provider = ConfigProvider.fromUnknown({
12
  database: {
13
    host: "localhost",
14
    port: 5432,
15
  },
16
})
17

18
Effect.runSync(DatabaseConfig.parse(provider)) // => { host: "localhost", port: 5432 }

See Configuration for configuration providers, nesting, defaults, and secrets.

Option

Schema.Option(value) describes Option values and applies value to the contents of Some.

Example (Transforming an Option’s Value)

1
import { Option, Schema } from "effect"
2

3
const schema = Schema.Option(Schema.FiniteFromString)
4

5
// Option<string> -> Option<number>
6
Schema.decodeUnknownSync(schema)(Option.some("1")) // => Option.some(1)
7

8
// Option<number> -> Option<string>
9
Schema.encodeSync(schema)(Option.some(1)) // => Option.some("1")
10

11
Schema.decodeUnknownSync(schema)(Option.none()) // => Option.none()

Options from Nullable and Optional Values

The following schemas transform common nullable and optional representations into Option values:

Schema	Values decoded as `None`	Default encoding of `None`
`OptionFromUndefinedOr`	`undefined`	`undefined`
`OptionFromNullOr`	`null`	`null`
`OptionFromNullishOr`	`null` or `undefined`	`undefined`
`OptionFromOptionalKey`	A missing property	A missing property
`OptionFromOptional`	A missing property or `undefined`	A missing property
`OptionFromOptionalNullOr`	A missing property, `null`, or `undefined`	A missing property

OptionFromNullishOr accepts an onNoneEncoding option of null or undefined. OptionFromOptionalNullOr accepts "omit", null, or undefined.

Example (Mapping an Optional Property to Option)

1
import { Option, Schema } from "effect"
2

3
const Profile = Schema.Struct({
4
  nickname: Schema.OptionFromOptionalKey(Schema.String),
5
})
6

7
Schema.decodeUnknownSync(Profile)({}) // => { nickname: Option.none() }
8
Schema.decodeUnknownSync(Profile)({ nickname: "Ada" }) // => { nickname: Option.some("Ada") }
9

10
Schema.encodeSync(Profile)({ nickname: Option.none() }) // => {}

Example (Mapping Nullish Values to Option)

1
import { Option, Schema } from "effect"
2

3
const schema = Schema.OptionFromNullishOr(Schema.FiniteFromString, {
4
  onNoneEncoding: null,
5
})
6

7
Schema.decodeUnknownSync(schema)(undefined) // => Option.none()
8
Schema.decodeUnknownSync(schema)(null) // => Option.none()
9
Schema.decodeUnknownSync(schema)("1") // => Option.some(1)
10

11
Schema.encodeSync(schema)(Option.none()) // => null

Result

Schema.Result(success, failure) describes Result values and transforms the success and failure channels independently.

Example (Transforming Result Values)

1
import { Result, Schema } from "effect"
2

3
const schema = Schema.Result(Schema.FiniteFromString, Schema.Trim)
4

5
Schema.decodeUnknownSync(schema)(Result.succeed("1")) // => Result.succeed(1)
6
Schema.decodeUnknownSync(schema)(Result.fail(" error ")) // => Result.fail("error")
7

8
Schema.encodeSync(schema)(Result.succeed(1)) // => Result.succeed("1")

Its default JSON representation uses { _tag: "Success", success } and { _tag: "Failure", failure }.

Example (Result as JSON)

1
import { Result, Schema } from "effect"
2

3
const schema = Schema.toCodecJson(
4
  Schema.Result(Schema.FiniteFromString, Schema.Trim),
5
)
6

7
Schema.decodeUnknownSync(schema)({ _tag: "Success", success: "1" }) // => Result.succeed(1)
8
Schema.encodeSync(schema)(Result.fail("error")) // => { _tag: "Failure", failure: "error" }

Exit

Schema.Exit(success, failure, defect) describes Exit values. It applies the supplied schemas to successful values, expected failures, and defects.

Example (Transforming Exit Values)

1
import { Exit, Schema } from "effect"
2

3
const schema = Schema.Exit(
4
  Schema.FiniteFromString,
5
  Schema.Trim,
6
  Schema.Defect(),
7
)
8

9
Schema.decodeUnknownSync(schema)(Exit.succeed("1")) // => Exit.succeed(1)
10
Schema.decodeUnknownSync(schema)(Exit.fail(" error ")) // => Exit.fail("error")
11

12
Schema.encodeSync(schema)(Exit.succeed(1)) // => Exit.succeed("1")

The JSON representation uses { _tag: "Success", value } for success and { _tag: "Failure", cause } for failure.

Example (Exit as JSON)

1
import { Exit, Schema } from "effect"
2

3
const schema = Schema.toCodecJson(
4
  Schema.Exit(Schema.FiniteFromString, Schema.String, Schema.Defect()),
5
)
6

7
Schema.decodeUnknownSync(schema)({ _tag: "Success", value: "1" }) // => Exit.succeed(1)
8
Schema.encodeSync(schema)(Exit.fail("not found")) // => { _tag: "Failure", cause: [{ _tag: "Fail", error: "not found" }] }

Schema.Defect() converts JSON-compatible defect data back into defects. Objects with name, message, and optionally stack are reconstructed as JavaScript errors.

Collections

Schemas for Effect collections expect collection values on both sides and apply the element schemas during decoding and encoding. Their JSON codecs use arrays of values or key-value entries.

ReadonlySet

Example (ReadonlySet Values and JSON)

1
import { Schema } from "effect"
2

3
const RuntimeSet = Schema.ReadonlySet(Schema.FiniteFromString)
4

5
Schema.decodeUnknownSync(RuntimeSet)(new Set(["1", "2"])) // => new Set([1, 2])
6
Schema.encodeSync(RuntimeSet)(new Set([1, 2])) // => new Set(["1", "2"])
7

8
const JsonSet = Schema.toCodecJson(RuntimeSet)
9

10
Schema.decodeUnknownSync(JsonSet)(["1", "2"]) // => new Set([1, 2])
11
Schema.encodeSync(JsonSet)(new Set([1, 2])) // => ["1", "2"]

ReadonlyMap

Example (ReadonlyMap Values and JSON)

1
import { Schema } from "effect"
2

3
const RuntimeMap = Schema.ReadonlyMap(Schema.String, Schema.FiniteFromString)
4

5
Schema.decodeUnknownSync(RuntimeMap)(new Map([["a", "1"]])) // => new Map([["a", 1]])
6
Schema.encodeSync(RuntimeMap)(new Map([["a", 1]])) // => new Map([["a", "1"]])
7

8
const JsonMap = Schema.toCodecJson(RuntimeMap)
9

10
Schema.decodeUnknownSync(JsonMap)([["a", "1"]]) // => new Map([["a", 1]])
11
Schema.encodeSync(JsonMap)(new Map([["a", 1]])) // => [["a", "1"]]

HashSet

Example (HashSet Values and JSON)

1
import { HashSet, Schema } from "effect"
2

3
const RuntimeSet = Schema.HashSet(Schema.FiniteFromString)
4

5
Schema.decodeUnknownSync(RuntimeSet)(HashSet.fromIterable(["1", "2"])) // => HashSet.fromIterable([1, 2])
6

7
const JsonSet = Schema.toCodecJson(RuntimeSet)
8

9
Schema.decodeUnknownSync(JsonSet)(["1", "2"]) // => HashSet.fromIterable([1, 2])
10
Schema.encodeSync(JsonSet)(HashSet.fromIterable([1, 2])) // => ["1", "2"]

HashMap

Example (HashMap Values and JSON)

1
import { HashMap, Schema } from "effect"
2

3
const RuntimeMap = Schema.HashMap(Schema.String, Schema.FiniteFromString)
4

5
Schema.decodeUnknownSync(RuntimeMap)(HashMap.make(["a", "1"])) // => HashMap.make(["a", 1])
6

7
const JsonMap = Schema.toCodecJson(RuntimeMap)
8

9
Schema.decodeUnknownSync(JsonMap)([["a", "1"]]) // => HashMap.make(["a", 1])
10
Schema.encodeSync(JsonMap)(HashMap.make(["a", 1])) // => [["a", "1"]]

Duration

Schema.Duration validates existing Duration values. Use a transformation schema when the encoded value is a string, a number of milliseconds, or a bigint number of nanoseconds.

Schema	Encoded	Type
`Schema.Duration`	`Duration`	`Duration`
`Schema.DurationFromString`	`string`	`Duration`
`Schema.DurationFromMillis`	`number`	`Duration`
`Schema.DurationFromNanos`	`bigint`	`Duration`

Example (Decoding Durations)

1
import { Duration, Schema } from "effect"
2

3
Schema.decodeUnknownSync(Schema.Duration)(Duration.seconds(2)) // => Duration.seconds(2)
4

5
Schema.decodeUnknownSync(Schema.DurationFromString)("2 seconds") // => Duration.seconds(2)
6
Schema.encodeSync(Schema.DurationFromString)(Duration.seconds(2)) // => "2000 millis"
7

8
Schema.decodeUnknownSync(Schema.DurationFromMillis)(2000) // => Duration.seconds(2)
9
Schema.encodeSync(Schema.DurationFromMillis)(Duration.seconds(2)) // => 2000
10

11
Schema.decodeUnknownSync(Schema.DurationFromNanos)(2_000_000_000n) // => Duration.nanos(2_000_000_000n)

The default JSON representation of Schema.Duration is a tagged object that preserves milliseconds, nanoseconds, and infinite durations.

Example (Duration as JSON)

1
import { Duration, Schema } from "effect"
2

3
const schema = Schema.toCodecJson(Schema.Duration)
4

5
Schema.encodeSync(schema)(Duration.seconds(2)) // => { _tag: "Millis", value: 2000 }
6
Schema.decodeUnknownSync(schema)({ _tag: "Millis", value: 2000 }) // => Duration.seconds(2)

Redacted

Schema.Redacted(value) validates existing Redacted values and applies value to their hidden contents. Use Schema.RedactedFromValue(value) to decode a raw value and wrap it in Redacted.

Example (Decoding Raw Values as Redacted)

1
import { Redacted, Schema } from "effect"
2

3
const schema = Schema.RedactedFromValue(Schema.Trim)
4

5
const secret = Schema.decodeUnknownSync(schema)(" secret ")
6

7
Redacted.value(secret) // => "secret"
8
Schema.encodeSync(schema)(secret) // => "secret"

The default JSON representation of Schema.Redacted(value) exposes the encoded inner value. If a redacted value must never be serialized, set disallowJsonEncode: true.

Example (Preventing JSON Encoding)

1
import { Redacted, Schema } from "effect"
2

3
const Secret = Schema.Redacted(Schema.String, {
4
  label: "Secret",
5
  disallowJsonEncode: true,
6
})
7

8
const JsonSecret = Schema.toCodecJson(Secret)
9

10
// Encoding fails instead of exposing "password"
11
Schema.encodeSync(JsonSecret)(Redacted.make("password", { label: "Secret" }))