Skip to content

SchemaGetter

Builds one-way conversions used by schemas.

A Getter<T, E, R> receives an optional encoded value and returns an optional decoded value. It can also report a schema issue or require Effect services. Schema transformations use getters to describe one direction of a conversion, for example decoding a field from input data. This module includes basic getters, validation helpers, pure and effectful conversions, and ready-made conversions for common string, number, binary, date, form, and URL-related values.

52 exports Added in v4.0.0 Source

Combining

joinKeyValue

Added in v4.0.0 Source

Joins a record of key-value pairs into a delimited string.

When to use

Use when you need a schema getter to serialize a present decoded record as a delimited key-value string.

Details

The getter is pure and never fails. It joins entries with separator (default ,) and joins each key and value with keyValueSeparator (default =).

See

Signature

declare function joinKeyValue<E extends Record<PropertyKey, string>>(options?: {
  readonly keyValueSeparator?: string;
  readonly separator?: string;
}): Getter<string, E>;

Constructors

fail

Added in v4.0.0 Source

Creates a getter that always fails with the given issue.

When to use

Use when you need a schema getter that unconditionally rejects input. - Building custom validation getters that produce specific error types.

Details

- Always fails with the Issue returned by f. - The failure function receives the original Option<E> input for error context.

See

  • forbidden for a convenience helper for Forbidden issues
  • checkEffect to fail conditionally based on input value

Signature

declare function fail<T, E>(f: (oe: Option<E>) => Issue): Getter<T, E>;

forbidden

Added in v4.0.0 Source

Creates a getter that always fails with a Forbidden issue.

When to use

Use when you need a schema getter to disallow a field or direction (encode/decode) entirely. - You want a clear "forbidden" error message in schema validation output.

Details

- Always fails with SchemaIssue.Forbidden. - The message function receives the Option<E> input for context.

See

  • fail to fail with a custom issue type

Signature

declare function forbidden<T, E>(message: (oe: Option<E>) => string): Getter<T, E>;

makeTreeRecord

Added in v4.0.0 Source

Builds a nested tree object from a list of bracket-path entries.

When to use

Use when you need a schema getter to parse FormData or URLSearchParams entries into structured objects. - You have flat key-value pairs with bracket-path keys that need nesting.

Details

- A bracket path is a string like "user[address][city]" that describes nested object/array structure. - Interprets bracket paths and constructs the corresponding nested object. - Builds and returns a nested object from the input entries. - Supported syntax: - "foo" → object key "foo" - "foo[bar]" → nested { foo: { bar: ... } } - "foo[0]" → array index { foo: [value] } - "foo[]" → append to array foo - "" → real empty key - Duplicate keys for the same path are merged into arrays. - If a structural path conflicts with a previous leaf or a different container type, the later structural path replaces the conflicting value. - The notation has no escaping for ., [ or ], so keys containing these delimiters cannot be round-tripped without changing their structure.

See

Signature

declare function makeTreeRecord<A>(bracketPathEntries: readonly Array<readonly [string, A]>): TreeRecord<A>

passthrough

Added in v4.0.0 Source

Returns the identity getter — passes the value through unchanged.

When to use

Use when you need a schema getter for one side of a decodeTo pair, either encode or decode, to pass values through unchanged.

Details

- Pure, no allocation (singleton instance). - Optimized away during .compose() — composing with a passthrough is free. - The default overload requires T === E. Pass { strict: false } to opt out of the type constraint.

See

Signature

declare function passthrough<T, E>(options: { readonly strict: false }): Getter<T, E>;
declare function passthrough<T>(): Getter<T, T>;

passthroughSubtype

Added in v4.0.0 Source

Returns the identity getter, typed for when the encoded type E is a subtype of T.

When to use

Use when you need a schema getter that passes values through without { strict: false } for an encoded type that narrows the decoded type.

Details

- Same singleton as passthrough — no allocation, optimized in composition.

See

Signature

declare function passthroughSubtype<T, E>(): Getter<T, E>;

passthroughSupertype

Added in v4.0.0 Source

Returns the identity getter typed for the relationship T extends E.

When to use

Use when you need a schema getter that passes values through when the decoded/output type is narrower than the encoded/input type.

Details

- Same singleton as passthrough — no allocation, optimized in composition.

See

Signature

declare function passthroughSupertype<T, E>(): Getter<T, E>;

succeed

Added in v4.0.0 Source

Creates a getter that always produces the given constant value, ignoring the input.

When to use

Use when you need a schema getter that always decodes a field to a fixed value.

Details

The getter is pure and always returns Option.some(t) regardless of whether the input is Some or None.

See

Signature

declare function succeed<T, E>(t: T): Getter<T, E>;

Converting

BigInt

Added in v4.0.0 Source

Coerces a value to bigint using the global BigInt() constructor.

When to use

Use when you need a schema getter to convert a present string, number, or boolean value to bigint.

Details

- Delegates to globalThis.BigInt. - Throws at runtime if the input cannot be converted (e.g. non-numeric string).

Signature

declare function BigInt<E extends string | number | bigint | boolean>(): Getter<bigint, E>;

Boolean

Added in v4.0.0 Source

Coerces any value to a boolean using the global Boolean() constructor.

When to use

Use when you need a schema getter to coerce a present encoded value to a boolean with Boolean().

Details

The getter is pure, never fails, and delegates to globalThis.Boolean.

Signature

declare function Boolean<E>(): Getter<boolean, E>;

collectBracketPathEntries

Added in v4.0.0 Source

Flattens a nested object into bracket-path entries, filtering leaf values by a type guard.

When to use

Use when you need a schema getter to serialize structured objects to flat key-value entries. - Building custom FormData or URLSearchParams encoders.

Details

- Takes a nested object and produces flat [bracketPath, value] pairs suitable for FormData or URLSearchParams. - Returns a curried function: first call provides the leaf type guard, second call provides the object. - Recursively traverses objects and arrays. - If all elements of an array are leaves, encodes them as multiple entries with the same key (e.g. tags=a&tags=b). Otherwise uses indexed bracket paths (e.g. items[0], items[1]). - Non-leaf values that aren't objects or arrays are silently skipped. - Empty arrays and objects produce no entries, and path delimiters in property names are not escaped. The resulting format is therefore lossy.

See

Signature

declare function collectBracketPathEntries<A>(
  isLeaf: (value: unknown) => value is A,
): (input: object) => Array<[bracketPath: string, value: A]>;

Date

Added in v4.0.0 Source

Coerces a value to a Date using new Date(input).

When to use

Use when you need a schema getter to coerce a present string, number, or existing date object into a new date object.

Details

- Delegates to new globalThis.Date(input). - Does not validate the result — may produce an invalid Date.

See

Signature

declare function Date<E extends string | number | Date>(): Getter<Date, E>;

dateTimeUtcFromInput

Added in v4.0.0 Source

Parses a DateTime.Input value into a DateTime.Utc.

When to use

Use when you need a schema getter to decode a present encoded date/time value to a DateTime.Utc.

Details

- Accepted input includes existing DateTime values, partial date/time parts, instant objects, zoned instant objects, JavaScript Date instances, epoch milliseconds, and date strings. - Converts successfully parsed values to UTC. - Fails with SchemaIssue.InvalidValue if the input cannot be parsed as a valid DateTime.

See

  • Date for a simpler coercion to Date (no validation)

Signature

declare function dateTimeUtcFromInput<E extends Input>(): Getter<Utc, E>;

Number

Added in v4.0.0 Source

Coerces any value to a number using the global Number() constructor.

When to use

Use when you need a schema getter to coerce a present encoded value to a number with Number().

Details

The getter is pure, never fails, and delegates to globalThis.Number. It may produce NaN for non-numeric inputs.

See

Signature

declare function Number<E>(): Getter<number, E>;

String

Added in v4.0.0 Source

Coerces any value to a string using the global String() constructor.

When to use

Use when you need a schema getter to coerce a present encoded value to a string with String().

Details

The getter is pure, never fails, and delegates to globalThis.String.

See

Signature

declare function String<E>(): Getter<string, E>;

Decoding

decodeBase64

Added in v4.0.0 Source

Decodes a Base64 string to a Uint8Array.

Details

- Fails with SchemaIssue.InvalidValue if the input is not valid Base64.

See

Signature

declare function decodeBase64<E extends string>(): Getter<Uint8Array<ArrayBufferLike>, E>;

decodeBase64String

Added in v4.0.0 Source

Decodes a Base64 string to a UTF-8 string.

Details

- Fails with SchemaIssue.InvalidValue if the input is not valid Base64.

See

Signature

declare function decodeBase64String<E extends string>(): Getter<string, E>;

decodeBase64Url

Added in v4.0.0 Source

Decodes a URL-safe Base64 string to a Uint8Array.

Details

- Fails with SchemaIssue.InvalidValue if the input is not valid Base64Url.

See

Signature

declare function decodeBase64Url<E extends string>(): Getter<Uint8Array<ArrayBufferLike>, E>;

decodeBase64UrlString

Added in v4.0.0 Source

Decodes a URL-safe Base64 string to a UTF-8 string.

Details

- Fails with SchemaIssue.InvalidValue if the input is not valid Base64Url.

See

Signature

declare function decodeBase64UrlString<E extends string>(): Getter<string, E>;

decodeFormData

Added in v4.0.0 Source

Decodes a FormData object into a nested tree structure using bracket-path notation.

When to use

Use when you need a schema getter to parse FormData from HTTP requests into structured objects.

Details

The getter is pure and never fails. It interprets bracket-path keys such as user[name] and items[0] to build nested objects or arrays, and each leaf value is a string or Blob.

See

Signature

declare function decodeFormData(): Getter<TreeRecord<string | Blob>, FormData>;

decodeHex

Added in v4.0.0 Source

Decodes a hexadecimal string to a Uint8Array.

Details

- Fails with SchemaIssue.InvalidValue if the input is not valid hex.

See

Signature

declare function decodeHex<E extends string>(): Getter<Uint8Array<ArrayBufferLike>, E>;

decodeHexString

Added in v4.0.0 Source

Decodes a hexadecimal string to a UTF-8 string.

Details

- Fails with SchemaIssue.InvalidValue if the input is not valid hex.

See

Signature

declare function decodeHexString<E extends string>(): Getter<string, E>;

decodeUriComponent

Added in v4.0.0 Source

Decodes a URI component encoded string using decodeURIComponent.

Details

- Fails with SchemaIssue.InvalidValue if the input contains malformed percent-encoding sequences.

See

Signature

declare function decodeUriComponent<E extends string>(): Getter<string, E>;

decodeURLSearchParams

Added in v4.0.0 Source

Decodes a URLSearchParams object into a nested tree structure using bracket-path notation.

When to use

Use when you need a schema getter to parse query parameters from URLs into structured objects.

Details

The getter is pure and never fails. It interprets bracket-path keys such as user[name] and items[0] to build nested objects or arrays, and each leaf value is a string.

See

Signature

declare function decodeURLSearchParams(): Getter<TreeRecord<string>, URLSearchParams>;

parseJson

Added in v4.0.0 Source

Parses a JSON string into a value.

When to use

Use when you need a schema getter to parse a present encoded JSON string during decoding.

Details

- Skips None inputs. - Without reviver: returns Schema.MutableJson (typed JSON). - With reviver: returns unknown (reviver may produce arbitrary values). - On parse failure, fails with SchemaIssue.InvalidValue containing a static message.

See

Signature

declare function parseJson<E extends string>(): Getter<MutableJson, E>;
declare function parseJson<E extends string>(options: ParseJsonOptions): Getter<unknown, E>;

Encoding

encodeBase64

Added in v4.0.0 Source

Encodes a Uint8Array or string to a Base64 string.

Details

The getter is pure and never fails.

See

Signature

declare function encodeBase64<E extends string | Uint8Array<ArrayBufferLike>>(): Getter<string, E>;

encodeBase64Url

Added in v4.0.0 Source

Encodes a Uint8Array or string to a URL-safe Base64 string.

Details

The getter is pure and never fails.

See

Signature

declare function encodeBase64Url<E extends string | Uint8Array<ArrayBufferLike>>(): Getter<
  string,
  E
>;

encodeFormData

Added in v4.0.0 Source

Encodes a nested object into a FormData instance using bracket-path notation.

When to use

Use when you need a schema getter to serialize structured data to FormData for HTTP requests.

Details

The getter is pure and never fails. It flattens nested objects or arrays into bracket-path keys such as user[name] and items[0]. Non-object inputs produce an empty FormData.

See

Signature

declare function encodeFormData(): Getter<FormData, unknown>;

encodeHex

Added in v4.0.0 Source

Encodes a Uint8Array or string to a hexadecimal string.

Details

The getter is pure and never fails.

See

Signature

declare function encodeHex<E extends string | Uint8Array<ArrayBufferLike>>(): Getter<string, E>;

encodeUriComponent

Added in v4.0.0 Source

Encodes a present string using encodeURIComponent.

Details

- Skips None inputs. - May throw a URIError for malformed surrogate pairs; this exception is not converted into an Issue.

See

Signature

declare function encodeUriComponent<E extends string>(): Getter<string, E>;

encodeURLSearchParams

Added in v4.0.0 Source

Encodes a nested object into a URLSearchParams instance using bracket-path notation.

When to use

Use when you need a schema getter to serialize structured data to query parameters for URLs.

Details

The getter is pure and never fails. It flattens nested objects or arrays into bracket-path keys. Non-object inputs produce an empty URLSearchParams.

See

Signature

declare function encodeURLSearchParams(): Getter<URLSearchParams, unknown>;

stringifyJson

Added in v4.0.0 Source

Stringifies a present value using JSON.stringify.

When to use

Use when you need a schema getter to serialize a present decoded value to JSON text during encoding.

Details

- Skips None inputs. - If JSON.stringify throws or returns undefined, fails with SchemaIssue.InvalidValue. - Supports optional replacer and space options, matching JSON.stringify.

See

Signature

declare function stringifyJson(options?: StringifyJsonOptions): Getter<string, unknown>;

Filtering

omit

Added in v4.0.0 Source

Creates a getter that always returns None, effectively omitting the value from output.

When to use

Use when you need a schema getter to exclude a field during decoding or encoding.

Details

- Always returns Option.None regardless of input. - Never fails.

See

Signature

declare function omit<T>(): Getter<never, T>;

Models

Getter

Added in v4.0.0 Source

Represents a composable transformation from an encoded type E to a decoded type T.

When to use

Use when you need a schema getter to build and compose custom transformations for Schema.decodeTo or Schema.decode.

Details

A getter wraps a function Option<E> -> Effect<Option<T>, Issue, R>. It receives Option.None when the encoded key is absent, such as a missing struct field, and returns Option.None to omit the value from the decoded output. It fails with Issue on invalid input and may require Effect services via R. .map(f) applies f to the decoded value inside Some while leaving None unchanged. .compose(other) chains two getters by feeding the output of this into other; passthrough getters on either side are optimized away.

See

Signature

declare class Getter<out T, in E, R = never> extends Class {
  constructor<out T, in E, R = never>(run: (input: Option<E>, options: ParseOptions) => Effect<Option<T>, Issue, R>);
  readonly run: (input: Option<E>, options: ParseOptions) => Effect<Option<T>, Issue, R>;
  compose<T2, R2>(other: Getter<T2, T, R2>): Getter<T2, E, R | R2>;
  map<T2>(f: (t: T) => T2): Getter<T2, E, R>;
}

Splitting

split

Added in v4.0.0 Source

Splits a string into an array of strings by a separator.

When to use

Use when you need a schema getter to split a present encoded string containing a delimited list, such as CSV values.

Details

The getter is pure and never fails. It splits by separator (default ,). An empty string produces an empty array, not [""].

See

Signature

declare function split<E extends string>(options?: {
  readonly separator?: string;
}): Getter<readonly Array<string>, E>

splitKeyValue

Added in v4.0.0 Source

Parses a string into a record of key-value pairs.

When to use

Use when you need a schema getter to parse a present encoded string that contains delimited key-value pairs (e.g. "a=1,b=2").

Details

The getter is pure and never fails. It splits the string by separator (default ,) and then each pair by keyValueSeparator (default =). Pairs missing a key or value are silently skipped.

See

Signature

declare function splitKeyValue<E extends string>(options?: {
  readonly keyValueSeparator?: string;
  readonly separator?: string;
}): Getter<Record<string, string>, E>;

Transforming

camelToSnake

Added in v4.0.0 Source

Converts a camelCase string to snake_case.

Details

- Pure, delegates to String.camelToSnake.

See

Signature

declare function camelToSnake<E extends string>(): Getter<string, E>;

capitalize

Added in v4.0.0 Source

Capitalizes the first character of a string.

Details

- Pure, delegates to String.capitalize.

Signature

declare function capitalize<E extends string>(): Getter<string, E>;

onNone

Added in v4.0.0 Source

Creates a getter that handles the case when the input is absent (Option.None).

When to use

Use when you need a schema getter to provide a fallback or computed value for missing struct keys. - Building custom "default value" logic more complex than withDefault.

Details

- When input is None, calls f to produce the result. - When input is Some, passes it through unchanged. - f receives the parse options and may return None to keep the value absent.

See

  • required when absent input should fail
  • withDefault for a simpler default value for undefined inputs
  • onSome to handle only present values

Signature

declare function onNone<T, E = T, R = never>(
  f: (options: ParseOptions) => Effect<Option<T>, Issue, R>,
): Getter<T, E, R>;

onSome

Added in v4.0.0 Source

Creates a getter that handles present values (Option.Some), passing None through.

When to use

Use when you need a schema getter to transform or validate only when a field value is present. - Missing keys should remain absent in the output.

Details

- When input is None, returns None (no-op). - When input is Some(e), calls f(e, options) to produce the result. - f may return None to omit the value, or fail with an Issue.

See

  • onNone to handle only absent values
  • transform for a simpler pure transformation of present values
  • transformOrFail for fallible transformation of present values

Signature

declare function onSome<T, E, R = never>(
  f: (e: E, options: ParseOptions) => Effect<Option<T>, Issue, R>,
): Getter<T, E, R>;

snakeToCamel

Added in v4.0.0 Source

Converts a snake_case string to camelCase.

Details

- Pure, delegates to String.snakeToCamel.

See

Signature

declare function snakeToCamel<E extends string>(): Getter<string, E>;

toLowerCase

Added in v4.0.0 Source

Converts a string to lowercase.

Details

- Pure, delegates to String.toLowerCase.

See

Signature

declare function toLowerCase<E extends string>(): Getter<string, E>;

toUpperCase

Added in v4.0.0 Source

Converts a string to uppercase.

Details

- Pure, delegates to String.toUpperCase.

See

Signature

declare function toUpperCase<E extends string>(): Getter<string, E>;

transform

Added in v4.0.0 Source

Creates a getter that applies a pure function to present values.

When to use

Use when you need a schema getter for a pure, infallible transformation between types. - Building encode/decode pairs for Schema.decodeTo.

Details

- This is the most commonly used constructor. - Transforms Some(e) to Some(f(e)) and leaves None unchanged. - Skips None inputs — only called when a value is present. - Never fails.

See

Signature

declare function transform<T, E>(f: (e: E) => T): Getter<T, E>;

transformOptional

Added in v4.0.0 Source

Creates a getter that transforms the full Option — both present and absent values.

When to use

Use when you need a schema getter to handle both Some and None cases.

Details

The getter is pure and never fails. It receives the full Option<E> and must return Option<T>, so it can turn a present value into absent or an absent value into present.

See

  • transform when you only need to transform present values
  • omit when you always want None

Signature

declare function transformOptional<T, E>(f: (oe: Option<E>) => Option<T>): Getter<T, E>;

transformOrFail

Added in v4.0.0 Source

Creates a getter that applies a fallible, effectful transformation to present values.

When to use

Use when you need a schema getter for a transformation that may fail, require Effect services, or run asynchronously.

Details

- Skips None inputs — only called when a value is present. - On success, wraps the result in Some. - On failure, propagates the Issue.

See

  • transform when transformation cannot fail
  • onSome when you need full Option control over the output

Signature

declare function transformOrFail<T, E, R = never>(
  f: (e: E, options: ParseOptions) => Effect<T, Issue, R>,
): Getter<T, E, R>;

trim

Added in v4.0.0 Source

Strips whitespace from both ends of a string.

Details

- Pure, delegates to String.trim.

Signature

declare function trim<E extends string>(): Getter<string, E>;

uncapitalize

Added in v4.0.0 Source

Uncapitalizes the first character of a string.

Details

- Pure, delegates to String.uncapitalize.

Signature

declare function uncapitalize<E extends string>(): Getter<string, E>;

withDefault

Added in v4.0.0 Source

Creates a getter that replaces undefined values with a default.

When to use

Use when you need a schema getter to provide a fallback for a field that may be undefined in the encoded input.

Details

- If the input is Some(undefined) or None, produces Some(T). - If the input is Some(value) where value is not undefined, passes it through. - defaultValue is an Effect that will be executed each time a default is needed.

See

  • onNone to handle only absent keys (not undefined values)
  • required when absent input should fail instead of using a default

Signature

declare function withDefault<T, R = never>(
  defaultValue: Effect<T, Issue, R>,
): Getter<T, T | undefined, R>;

Utility Types

JsonReplacer type

Added in v4.0.0 Source

Replacer function or property allowlist accepted by JSON.stringify.

Signature

type JsonReplacer = (this: any, key: string, value: any) => any | Array<string | number> | null;

Validation

checkEffect

Added in v4.0.0 Source

Creates a getter that validates a value using an effectful check function.

When to use

Use when you need a schema getter to validate a decoded value (e.g. check a constraint or call an external service). - The validation may be asynchronous or require Effect services.

Details

- Only runs when input is Some — None passes through. - The check function returns a validation result: - undefined or true — value is valid, passes through. - false or a string — value is invalid, fails with an Issue. - An Issue object — fails with that issue directly. - { path, issue } — fails with a nested path issue (issue may be a message string or a full SchemaIssue.Issue). - Does not transform the value — input and output types are the same.

See

  • transform when you need to change the value, not just validate
  • fail for unconditional failure

Signature

declare function checkEffect<T, R = never>(
  f: (input: T, options: ParseOptions) => Effect<boolean | FilterIssue | undefined, never, R>,
): Getter<T, T, R>;

required

Added in v4.0.0 Source

Creates a getter that fails with MissingKey if the input is absent (Option.None).

When to use

Use when you need a schema getter to require a struct field in the encoded input and report a missing key error when it is absent.

Details

- When input is None, fails with SchemaIssue.MissingKey. - When input is Some, passes it through unchanged. - Optional annotations customize the error message for the missing key.

See

  • onNone to provide a fallback instead of failing
  • withDefault to substitute a default for undefined values

Signature

declare function required<T, E = T>(annotations?: Key<T>): Getter<T, E>;