(options?: StringifyJsonOptions): Getter<string, unknown>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
Noneinputs. - On thrown stringify failures, such as circular references, fails with
SchemaIssue.InvalidValue. - Supports optional
replacerandspaceoptions, matchingJSON.stringify. - If
JSON.stringifyreturnsundefined, such as forundefined, functions, symbols, or a replacer that removes the root value, thatundefinedresult is returned rather than converted into anIssue.
Example (Stringifying JSON)
import { SchemaGetter } from "effect"
const stringify = SchemaGetter.stringifyJson()
// Getter<string, unknown>export function function stringifyJson(
options?: StringifyJsonOptions
): Getter<string, unknown>
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.
- On thrown stringify failures, such as circular references, fails with
SchemaIssue.InvalidValue.
- Supports optional
replacer and space options, matching
JSON.stringify.
- If
JSON.stringify returns undefined, such as for undefined,
functions, symbols, or a replacer that removes the root value, that
undefined result is returned rather than converted into an Issue.
Example (Stringifying JSON)
import { SchemaGetter } from "effect"
const stringify = SchemaGetter.stringifyJson()
// Getter<string, unknown>
stringifyJson(options: StringifyJsonOptions | undefinedoptions?: type StringifyJsonOptions = {
readonly replacer?: Parameters<
typeof JSON.stringify
>[1]
readonly space?: Parameters<
typeof JSON.stringify
>[2]
}
class Getter<out T, in E, R = never>class Getter {
run: (input: Option.Option<E>, options: SchemaAST.ParseOptions) => Effect.Effect<Option.Option<T>, SchemaIssue.Issue, R>;
map: <T2>(f: (t: T) => T2) => Getter<T2, E, R>;
compose: <T2, R2>(other: Getter<T2, T, R2>) => Getter<T2, E, R | R2>;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
}
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.
Example (Creating and composing getters)
import { SchemaGetter } from "effect"
const parseNumber = SchemaGetter.transform<number, string>((s) => Number(s))
const double = SchemaGetter.transform<number, number>((n) => n * 2)
const composed = parseNumber.compose(double)
// composed: Getter<number, string> — parses then doubles
Getter<string, unknown> {
return function onSome<T, E, R = never>(
f: (
e: E,
options: SchemaAST.ParseOptions
) => Effect.Effect<
Option.Option<T>,
SchemaIssue.Issue,
R
>
): Getter<T, E, R>
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.
Example (Transforming only present values)
import { Effect, Option, SchemaGetter } from "effect"
const parseIfPresent = SchemaGetter.onSome<number, string>(
(s) => Effect.succeed(Option.some(Number(s)))
)
onSome((input: unknowninput) =>
import EffectEffect.try<A, E = Cause.UnknownError>(options: { readonly try: LazyArg<A>; readonly catch: (error: unknown) => E } | LazyArg<A>): Effect<A, E>Creates an Effect from a synchronous computation that may throw, mapping
thrown values into the error channel.
When to use
Use when you need to perform synchronous operations that might throw, such
as parsing JSON, and want thrown exceptions captured as Effect errors.
Details
The thunk is evaluated when the effect runs. If it returns normally, the
returned value becomes the success value. If it throws, the thrown value is
mapped into the error channel.
Passing the thunk directly maps failures to
Cause.UnknownError
.
Passing { try, catch } uses catch to map failures to an error of type
E.
Gotchas
If catch throws while mapping the error, that thrown value is treated as
a defect. Return the error value you want in the error channel instead of
throwing it.
Example (Parsing JSON)
import { Effect } from "effect"
const parseJSON = (input: string) =>
Effect.try(() => JSON.parse(input))
// Success case
Effect.runPromise(parseJSON("{\"name\": \"Alice\"}")).then(console.log)
// Output: { name: "Alice" }
// Failure case maps the thrown value to UnknownError
Effect.runPromiseExit(parseJSON("invalid json")).then(console.log)
Example (Mapping exceptions to a tagged error)
import { Data, Effect } from "effect"
class JsonParsingError extends Data.TaggedError("JsonParsingError")<{ readonly cause: unknown }> {}
const parseJSON = (input: string) =>
Effect.try({
try: () => JSON.parse(input),
catch: (cause) => new JsonParsingError({ cause })
})
Effect.runPromiseExit(parseJSON("invalid json")).then(console.log)
// Output: Exit.failure with custom Error message
try({
try: LazyArg<Option.Option<string>>try: () => import OptionOption.const some: <A>(value: A) => Option<A>Wraps the given value into an Option to represent its presence.
When to use
Use to wrap a known present value as Option
- Returning a successful result from a partial function
Details
- Always returns
Some<A>
- Does not filter
null or undefined; use
fromNullishOr
for that
Example (Wrapping a value)
import { Option } from "effect"
// ┌─── Option<number>
// ▼
const value = Option.some(1)
console.log(value)
// Output: { _id: 'Option', _tag: 'Some', value: 1 }
some(var JSON: JSONAn intrinsic object that provides functions to convert JavaScript values to and from the JavaScript Object Notation (JSON) format.
JSON.JSON.stringify(value: any, replacer?: (number | string)[] | null, space?: string | number): string (+1 overload)Converts a JavaScript value to a JavaScript Object Notation (JSON) string.
stringify(input: unknowninput, options: StringifyJsonOptions | undefinedoptions?.replacer?: (string | number)[] | null | undefinedreplacer, options: StringifyJsonOptions | undefinedoptions?.space?: string | number | undefinedspace)),
catch: (
error: unknown
) => SchemaIssue.InvalidValue
e: unknowne) => new import SchemaIssueSchemaIssue.constructor InvalidValue(actual: Option.Option<unknown>, annotations?: Schema.Annotations.Issue | undefined): SchemaIssue.InvalidValueRepresents a schema issue produced when the input has the correct type but its value violates a
constraint (e.g. a string that is too short, a number out of range).
When to use
Use when you need to detect constraint violations from Schema.filter,
Schema.minLength, Schema.greaterThan, or similar checks.
Details
actual is Option.some(value) when the failing value is known, or
Option.none() when absent.annotations optionally carries a message string for formatting.- The default formatter renders this as
"Invalid data <actual>" unless a
custom message annotation is provided.
Example (Returning InvalidValue from a custom filter)
import { Option, SchemaIssue } from "effect"
const issue = new SchemaIssue.InvalidValue(
Option.some(""),
{ message: "must not be empty" }
)
console.log(String(issue))
// "must not be empty"
InvalidValue(import OptionOption.const some: <A>(value: A) => Option<A>Wraps the given value into an Option to represent its presence.
When to use
Use to wrap a known present value as Option
- Returning a successful result from a partial function
Details
- Always returns
Some<A>
- Does not filter
null or undefined; use
fromNullishOr
for that
Example (Wrapping a value)
import { Option } from "effect"
// ┌─── Option<number>
// ▼
const value = Option.some(1)
console.log(value)
// Output: { _id: 'Option', _tag: 'Some', value: 1 }
some(input: unknowninput), { Annotations.Issue.message?: string | undefinedmessage: module globalThisglobalThis.var String: StringConstructor
;(value?: any) => string
Allows manipulation and formatting of text strings and determination and location of substrings within strings.
String(e: unknowne) })
})
)
}