effect 4.0.0-beta.102 → 4.0.0-beta.103

package/src/SchemaGetter.ts

@@ -45,13 +45,13 @@ import * as Str from "./String.ts"
  *
  * **Example** (Creating and composing getters)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, 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
+ * await Effect.runPromise(composed.run(Option.some("21"), {})) // => Option.some(42)
  * ```
  *
  * @see {@link transform} to create a getter from a pure function
@@ -105,11 +105,11 @@ export class Getter<out T, in E, R = never> extends Pipeable.Class {
  *
  * **Example** (Returning a constant getter)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const alwaysZero = SchemaGetter.succeed(0)
- * // alwaysZero: Getter<0, unknown> — always produces 0
+ * await Effect.runPromise(alwaysZero.run(Option.none(), {})) // => Option.some(0)
  * ```
  *
  * @see {@link transform} when you need to use the input value
@@ -137,12 +137,14 @@ export function succeed<const T, E>(t: T): Getter<T, E> {
  *
  * **Example** (Defining an always-failing getter)
  *
- * ```ts
- * import { Option, SchemaGetter, SchemaIssue } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter, SchemaIssue } from "effect"
  *
  * const rejectAll = SchemaGetter.fail<string, string>(
- *   (oe) => new SchemaIssue.InvalidValue(oe, { message: "not allowed" })
+ *   () => new SchemaIssue.InvalidValue({ message: "not allowed" })
  * )
+ * const issue = await Effect.runPromise(Effect.flip(rejectAll.run(Option.some("x"), {})))
+ * issue._tag // => "InvalidValue"
  * ```
  *
  * @see {@link forbidden} for a convenience helper for `Forbidden` issues
@@ -171,12 +173,14 @@ export function fail<T, E>(f: (oe: Option.Option<E>) => SchemaIssue.Issue): Gett
  *
  * **Example** (Forbidding a decode direction)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const noEncode = SchemaGetter.forbidden<string, number>(
  *   () => "encoding is not supported"
  * )
+ * const issue = await Effect.runPromise(Effect.flip(noEncode.run(Option.some(1), {})))
+ * issue._tag // => "Forbidden"
  * ```
  *
  * @see {@link fail} to fail with a custom issue type
@@ -185,7 +189,7 @@ export function fail<T, E>(f: (oe: Option.Option<E>) => SchemaIssue.Issue): Gett
  * @since 4.0.0
  */
 export function forbidden<T, E>(message: (oe: Option.Option<E>) => string): Getter<T, E> {
-  return fail<T, E>((oe) => new SchemaIssue.Forbidden(oe, { message: message(oe) }))
+  return fail<T, E>((oe) => new SchemaIssue.Forbidden({ message: message(oe) }))
 }
 
 const passthrough_ = new Getter<any, any>(Effect.succeed)
@@ -211,7 +215,7 @@ function isPassthrough<T, E, R>(getter: Getter<T, E, R>): getter is typeof passt
  *
  * **Example** (Passing through identity transformations)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaGetter } from "effect"
  *
  * // No transformation needed — types already match
@@ -221,6 +225,7 @@ function isPassthrough<T, E, R>(getter: Getter<T, E, R>): getter is typeof passt
  *     encode: SchemaGetter.passthrough()
  *   })
  * )
+ * Schema.decodeSync(StringToString)("hello") // => "hello"
  * ```
  *
  * @see {@link passthroughSupertype} when `T extends E`
@@ -250,11 +255,12 @@ export function passthrough<T>(): Getter<T, T> {
  *
  * **Example** (Passing through supertypes)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * // string extends string, so this is valid
  * const g = SchemaGetter.passthroughSupertype<string, string>()
+ * await Effect.runPromise(g.run(Option.some("hello"), {})) // => Option.some("hello")
  * ```
  *
  * @see {@link passthrough} when types are identical
@@ -282,11 +288,12 @@ export function passthroughSupertype<T>(): Getter<T, T> {
  *
  * **Example** (Passing through subtypes)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * // "hello" extends string, so E extends T
  * const g = SchemaGetter.passthroughSubtype<string, "hello">()
+ * await Effect.runPromise(g.run(Option.some("hello"), {})) // => Option.some("hello")
  * ```
  *
  * @see {@link passthrough} when types are identical
@@ -317,19 +324,20 @@ export function passthroughSubtype<T>(): Getter<T, T> {
  *
  * **Example** (Providing a default timestamp for a missing field)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const withTimestamp = SchemaGetter.onNone<number>(() =>
- *   Effect.succeed(Option.some(Date.now()))
+ *   Effect.succeed(Option.some(0))
  * )
+ * await Effect.runPromise(withTimestamp.run(Option.none(), {})) // => Option.some(0)
  * ```
  *
  * @see {@link required} when absent input should fail
  * @see {@link withDefault} for a simpler default value for undefined inputs
  * @see {@link onSome} to handle only present values
  *
- * @category constructors
+ * @category transforming
  * @since 4.0.0
  */
 export function onNone<T, E extends T = T, R = never>(
@@ -354,16 +362,18 @@ export function onNone<T, E extends T = T, R = never>(
  *
  * **Example** (Defining a required struct field)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const mustExist = SchemaGetter.required<string>()
+ * const issue = await Effect.runPromise(Effect.flip(mustExist.run(Option.none(), {})))
+ * issue._tag // => "MissingKey"
  * ```
  *
  * @see {@link onNone} to provide a fallback instead of failing
  * @see {@link withDefault} to substitute a default for undefined values
  *
- * @category constructors
+ * @category validation
  * @since 4.0.0
  */
 export function required<T, E extends T = T>(annotations?: Schema.Annotations.Key<T>): Getter<T, E> {
@@ -387,19 +397,20 @@ export function required<T, E extends T = T>(annotations?: Schema.Annotations.Ke
  *
  * **Example** (Transforming only present values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const parseIfPresent = SchemaGetter.onSome<number, string>(
  *   (s) => Effect.succeed(Option.some(Number(s)))
  * )
+ * await Effect.runPromise(parseIfPresent.run(Option.some("42"), {})) // => Option.some(42)
  * ```
  *
  * @see {@link onNone} to handle only absent values
  * @see {@link transform} for a simpler pure transformation of present values
  * @see {@link transformOrFail} for fallible transformation of present values
  *
- * @category constructors
+ * @category transforming
  * @since 4.0.0
  */
 export function onSome<T, E, R = never>(
@@ -430,18 +441,19 @@ export function onSome<T, E, R = never>(
  *
  * **Example** (Validating effectfully)
  *
- * ```ts
- * import { Effect, SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const nonNegative = SchemaGetter.checkEffect<number>((n) =>
  *   Effect.succeed(n >= 0 ? undefined : "must be non-negative")
  * )
+ * await Effect.runPromise(nonNegative.run(Option.some(1), {})) // => Option.some(1)
  * ```
  *
  * @see {@link transform} when you need to change the value, not just validate
  * @see {@link fail} for unconditional failure
  *
- * @category constructors
+ * @category validation
  * @since 4.0.0
  */
 export function checkEffect<T, R = never>(
@@ -453,7 +465,7 @@ export function checkEffect<T, R = never>(
 ): Getter<T, T, R> {
   return onSome((t, options) => {
     return f(t, options).pipe(Effect.flatMapEager((out) => {
-      const issue = SchemaIssue.makeSingle(t, out)
+      const issue = SchemaIssue.makeSingle(out)
       return issue ?
         Effect.fail(issue) :
         Effect.succeed(Option.some(t))
@@ -479,7 +491,7 @@ export function checkEffect<T, R = never>(
  *
  * **Example** (Transforming strings to numbers)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaGetter } from "effect"
  *
  * const NumberFromString = Schema.String.pipe(
@@ -488,13 +500,14 @@ export function checkEffect<T, R = never>(
  *     encode: SchemaGetter.transform((n) => String(n))
  *   })
  * )
+ * Schema.decodeSync(NumberFromString)("42") // => 42
  * ```
  *
  * @see {@link transformOrFail} when the transformation can fail
  * @see {@link transformOptional} when you need to handle `None` inputs
  * @see {@link passthrough} when no transformation is needed
  *
- * @category constructors
+ * @category transforming
  * @since 4.0.0
  */
 export function transform<T, E>(f: (e: E) => T): Getter<T, E> {
@@ -517,23 +530,24 @@ export function transform<T, E>(f: (e: E) => T): Getter<T, E> {
  *
  * **Example** (Parsing with failure)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Option, SchemaGetter, SchemaIssue } from "effect"
  *
  * const safeParseInt = SchemaGetter.transformOrFail<number, string>(
  *   (s) => {
  *     const n = parseInt(s, 10)
  *     return isNaN(n)
- *       ? Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), { message: "not an integer" }))
+ *       ? Effect.fail(new SchemaIssue.InvalidValue({ message: "not an integer" }))
  *       : Effect.succeed(n)
  *   }
  * )
+ * await Effect.runPromise(safeParseInt.run(Option.some("42"), {})) // => Option.some(42)
  * ```
  *
  * @see {@link transform} when transformation cannot fail
  * @see {@link onSome} when you need full `Option` control over the output
  *
- * @category constructors
+ * @category transforming
  * @since 4.0.0
  */
 export function transformOrFail<T, E, R = never>(
@@ -557,18 +571,19 @@ export function transformOrFail<T, E, R = never>(
  *
  * **Example** (Filtering out empty strings)
  *
- * ```ts
- * import { Option, SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const skipEmpty = SchemaGetter.transformOptional<string, string>((o) =>
  *   Option.filter(o, (s) => s.length > 0)
  * )
+ * await Effect.runPromise(skipEmpty.run(Option.some(""), {})) // => Option.none()
  * ```
  *
  * @see {@link transform} when you only need to transform present values
  * @see {@link omit} when you always want `None`
  *
- * @category constructors
+ * @category transforming
  * @since 4.0.0
  */
 export function transformOptional<T, E>(f: (oe: Option.Option<E>) => Option.Option<T>): Getter<T, E> {
@@ -590,16 +605,17 @@ export function transformOptional<T, E>(f: (oe: Option.Option<E>) => Option.Opti
  *
  * **Example** (Omitting a field during encoding)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const omitField = SchemaGetter.omit<string>()
+ * await Effect.runPromise(omitField.run(Option.some("hidden"), {})) // => Option.none()
  * ```
  *
  * @see {@link transformOptional} when you want conditional omission
  * @see {@link forbidden} when you want to fail instead of silently omit
  *
- * @category constructors
+ * @category filtering
  * @since 4.0.0
  */
 export function omit<T>(): Getter<never, T> {
@@ -622,17 +638,17 @@ export function omit<T>(): Getter<never, T> {
  *
  * **Example** (Providing a default value for an optional field)
  *
- * ```ts
- * import { Effect, SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const withZero = SchemaGetter.withDefault(Effect.succeed(0))
- * // Getter<number, number | undefined>
+ * await Effect.runPromise(withZero.run(Option.some(undefined), {})) // => Option.some(0)
  * ```
  *
  * @see {@link onNone} to handle only absent keys (not `undefined` values)
  * @see {@link required} when absent input should fail instead of using a default
  *
- * @category constructors
+ * @category transforming
  * @since 4.0.0
  */
 export function withDefault<T, R = never>(
@@ -658,16 +674,16 @@ export function withDefault<T, R = never>(
  *
  * **Example** (Coercing to a string)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const toString = SchemaGetter.String<number>()
- * // Getter<string, number>
+ * await Effect.runPromise(toString.run(Option.some(42), {})) // => Option.some("42")
  * ```
  *
  * @see {@link transform} for custom string conversions
  *
- * @category Coercions
+ * @category converting
  * @since 4.0.0
  */
 export function String<E>(): Getter<string, E> {
@@ -689,16 +705,16 @@ export function String<E>(): Getter<string, E> {
  *
  * **Example** (Coercing to a number)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const toNumber = SchemaGetter.Number<string>()
- * // Getter<number, string>
+ * await Effect.runPromise(toNumber.run(Option.some("42"), {})) // => Option.some(42)
  * ```
  *
  * @see {@link transformOrFail} for validated number parsing
  *
- * @category Coercions
+ * @category converting
  * @since 4.0.0
  */
 export function Number<E>(): Getter<number, E> {
@@ -719,14 +735,14 @@ export function Number<E>(): Getter<number, E> {
  *
  * **Example** (Coercing to a boolean)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const toBool = SchemaGetter.Boolean<string>()
- * // Getter<boolean, string>
+ * await Effect.runPromise(toBool.run(Option.some("true"), {})) // => Option.some(true)
  * ```
  *
- * @category Coercions
+ * @category converting
  * @since 4.0.0
  */
 export function Boolean<E>(): Getter<boolean, E> {
@@ -748,14 +764,14 @@ export function Boolean<E>(): Getter<boolean, E> {
  *
  * **Example** (Coercing to a bigint)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const toBigInt = SchemaGetter.BigInt<string>()
- * // Getter<bigint, string>
+ * await Effect.runPromise(toBigInt.run(Option.some("42"), {})) // => Option.some(42n)
  * ```
  *
- * @category Coercions
+ * @category converting
  * @since 4.0.0
  */
 export function BigInt<E extends string | number | bigint | boolean>(): Getter<bigint, E> {
@@ -777,16 +793,17 @@ export function BigInt<E extends string | number | bigint | boolean>(): Getter<b
  *
  * **Example** (Coercing to a Date)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const toDate = SchemaGetter.Date<string>()
- * // Getter<Date, string>
+ * const result = await Effect.runPromise(toDate.run(Option.some("1970-01-01"), {}))
+ * Option.map(result, (date) => date.toISOString()) // => Option.some("1970-01-01T00:00:00.000Z")
  * ```
  *
  * @see {@link dateTimeUtcFromInput} for validated DateTime parsing
  *
- * @category Coercions
+ * @category converting
  * @since 4.0.0
  */
 export function Date<E extends string | number | Date>(): Getter<Date, E> {
@@ -802,13 +819,14 @@ export function Date<E extends string | number | Date>(): Getter<Date, E> {
  *
  * **Example** (Trimming whitespace)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const trimmed = SchemaGetter.trim<string>()
+ * await Effect.runPromise(trimmed.run(Option.some("  hello  "), {})) // => Option.some("hello")
  * ```
  *
- * @category string
+ * @category transforming
  * @since 4.0.0
  */
 export function trim<E extends string>(): Getter<string, E> {
@@ -824,13 +842,14 @@ export function trim<E extends string>(): Getter<string, E> {
  *
  * **Example** (Capitalizing a string)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const cap = SchemaGetter.capitalize<string>()
+ * await Effect.runPromise(cap.run(Option.some("hello"), {})) // => Option.some("Hello")
  * ```
  *
- * @category string
+ * @category transforming
  * @since 4.0.0
  */
 export function capitalize<E extends string>(): Getter<string, E> {
@@ -846,13 +865,14 @@ export function capitalize<E extends string>(): Getter<string, E> {
  *
  * **Example** (Uncapitalizing a string)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const uncap = SchemaGetter.uncapitalize<string>()
+ * await Effect.runPromise(uncap.run(Option.some("Hello"), {})) // => Option.some("hello")
  * ```
  *
- * @category string
+ * @category transforming
  * @since 4.0.0
  */
 export function uncapitalize<E extends string>(): Getter<string, E> {
@@ -868,15 +888,16 @@ export function uncapitalize<E extends string>(): Getter<string, E> {
  *
  * **Example** (Converting snake case to camel case)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const toCamel = SchemaGetter.snakeToCamel<string>()
+ * await Effect.runPromise(toCamel.run(Option.some("user_name"), {})) // => Option.some("userName")
  * ```
  *
  * @see {@link camelToSnake} for the inverse operation
  *
- * @category string
+ * @category transforming
  * @since 4.0.0
  */
 export function snakeToCamel<E extends string>(): Getter<string, E> {
@@ -892,15 +913,16 @@ export function snakeToCamel<E extends string>(): Getter<string, E> {
  *
  * **Example** (Converting camel case to snake case)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const toSnake = SchemaGetter.camelToSnake<string>()
+ * await Effect.runPromise(toSnake.run(Option.some("userName"), {})) // => Option.some("user_name")
  * ```
  *
  * @see {@link snakeToCamel} for the inverse operation
  *
- * @category string
+ * @category transforming
  * @since 4.0.0
  */
 export function camelToSnake<E extends string>(): Getter<string, E> {
@@ -916,15 +938,16 @@ export function camelToSnake<E extends string>(): Getter<string, E> {
  *
  * **Example** (Converting to lowercase)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const lower = SchemaGetter.toLowerCase<string>()
+ * await Effect.runPromise(lower.run(Option.some("HELLO"), {})) // => Option.some("hello")
  * ```
  *
  * @see {@link toUpperCase} for the inverse operation
  *
- * @category string
+ * @category transforming
  * @since 4.0.0
  */
 export function toLowerCase<E extends string>(): Getter<string, E> {
@@ -940,15 +963,16 @@ export function toLowerCase<E extends string>(): Getter<string, E> {
  *
  * **Example** (Converting to uppercase)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const upper = SchemaGetter.toUpperCase<string>()
+ * await Effect.runPromise(upper.run(Option.some("hello"), {})) // => Option.some("HELLO")
  * ```
  *
  * @see {@link toLowerCase} for the inverse operation
  *
- * @category string
+ * @category transforming
  * @since 4.0.0
  */
 export function toUpperCase<E extends string>(): Getter<string, E> {
@@ -972,20 +996,20 @@ type ParseJsonOptions = {
  * - 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 the error message.
+ * - On parse failure, fails with `SchemaIssue.InvalidValue` containing a static message.
  *
  * **Example** (Parsing JSON)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const parse = SchemaGetter.parseJson<string>()
- * // Getter<MutableJson, string>
+ * await Effect.runPromise(parse.run(Option.some("{\"a\":1}"), {})) // => Option.some({ a: 1 })
  * ```
  *
  * @see {@link stringifyJson} for the inverse operation
  *
- * @category JSON getters
+ * @category decoding
  * @since 4.0.0
  */
 export function parseJson<E extends string>(): Getter<Schema.MutableJson, E>
@@ -994,13 +1018,24 @@ export function parseJson<E extends string>(options?: ParseJsonOptions | undefin
   return onSome((input) =>
     Effect.try({
       try: () => Option.some(JSON.parse(input, options?.reviver)),
-      catch: (e) => new SchemaIssue.InvalidValue(Option.some(input), { message: globalThis.String(e) })
+      catch: () => new SchemaIssue.InvalidValue({ message: "Expected a valid JSON string" })
     })
   )
 }
 
+/**
+ * Replacer function or property allowlist accepted by `JSON.stringify`.
+ *
+ * @category utility types
+ * @since 4.0.0
+ */
+export type JsonReplacer =
+  | ((this: any, key: string, value: any) => any)
+  | Array<string | number>
+  | null
+
 type StringifyJsonOptions = {
-  readonly replacer?: Parameters<typeof JSON.stringify>[1]
+  readonly replacer?: JsonReplacer | undefined
   readonly space?: Parameters<typeof JSON.stringify>[2]
 }
 
@@ -1022,29 +1057,29 @@ type StringifyJsonOptions = {
  *
  * **Example** (Stringifying JSON)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const stringify = SchemaGetter.stringifyJson()
- * // Getter<string, unknown>
+ * await Effect.runPromise(stringify.run(Option.some({ a: 1 }), {})) // => Option.some("{\"a\":1}")
  * ```
  *
  * @see {@link parseJson} for the inverse operation
  *
- * @category JSON getters
+ * @category encoding
  * @since 4.0.0
  */
 export function stringifyJson(options?: StringifyJsonOptions): Getter<string, unknown> {
   return onSome((input) =>
     Effect.try({
       try: () => {
-        const output = JSON.stringify(input, options?.replacer, options?.space)
+        const output = JSON.stringify(input, options?.replacer as any, options?.space)
         if (output === undefined) {
           throw new TypeError("Value cannot be represented as JSON")
         }
         return Option.some(output)
       },
-      catch: (e) => new SchemaIssue.InvalidValue(Option.some(input), { message: globalThis.String(e) })
+      catch: () => new SchemaIssue.InvalidValue({ message: "Expected a JSON-serializable value" })
     })
   )
 }
@@ -1065,17 +1100,17 @@ export function stringifyJson(options?: StringifyJsonOptions): Getter<string, un
  *
  * **Example** (Parsing a key-value string)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const parse = SchemaGetter.splitKeyValue<string>()
- * // "a=1,b=2" -> { a: "1", b: "2" }
+ * await Effect.runPromise(parse.run(Option.some("a=1,b=2"), {})) // => Option.some({ a: "1", b: "2" })
  * ```
  *
  * @see {@link joinKeyValue} for the inverse operation
  * @see {@link split} to split into an array of strings
  *
- * @category string
+ * @category splitting
  * @since 4.0.0
  */
 export function splitKeyValue<E extends string>(options?: {
@@ -1111,16 +1146,16 @@ export function splitKeyValue<E extends string>(options?: {
  *
  * **Example** (Joining key-value records)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const join = SchemaGetter.joinKeyValue()
- * // { a: "1", b: "2" } -> "a=1,b=2"
+ * await Effect.runPromise(join.run(Option.some({ a: "1", b: "2" }), {})) // => Option.some("a=1,b=2")
  * ```
  *
  * @see {@link splitKeyValue} for the inverse operation
  *
- * @category string
+ * @category combining
  * @since 4.0.0
  */
 export function joinKeyValue<E extends Record<PropertyKey, string>>(options?: {
@@ -1149,17 +1184,16 @@ export function joinKeyValue<E extends Record<PropertyKey, string>>(options?: {
  *
  * **Example** (Splitting a comma-separated string)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const splitComma = SchemaGetter.split<string>()
- * // "a,b,c" -> ["a", "b", "c"]
- * // "" -> []
+ * await Effect.runPromise(splitComma.run(Option.some("a,b,c"), {})) // => Option.some(["a", "b", "c"])
  * ```
  *
  * @see {@link splitKeyValue} when values are key-value pairs
  *
- * @category string
+ * @category splitting
  * @since 4.0.0
  */
 export function split<E extends string>(options?: {
@@ -1178,17 +1212,18 @@ export function split<E extends string>(options?: {
  *
  * **Example** (Encoding to Base64)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const encode = SchemaGetter.encodeBase64<Uint8Array>()
+ * await Effect.runPromise(encode.run(Option.some(new Uint8Array([1, 2, 3])), {})) // => Option.some("AQID")
  * ```
  *
  * @see {@link decodeBase64} for the inverse operation to `Uint8Array`
  * @see {@link decodeBase64String} for the inverse operation to `string`
  * @see {@link encodeBase64Url} for the URL-safe variant
  *
- * @category Base64 getters
+ * @category encoding
  * @since 4.0.0
  */
 export function encodeBase64<E extends Uint8Array | string>(): Getter<string, E> {
@@ -1204,17 +1239,18 @@ export function encodeBase64<E extends Uint8Array | string>(): Getter<string, E>
  *
  * **Example** (Encoding to Base64Url)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const encode = SchemaGetter.encodeBase64Url<Uint8Array>()
+ * await Effect.runPromise(encode.run(Option.some(new Uint8Array([251, 255])), {})) // => Option.some("-_8")
  * ```
  *
  * @see {@link decodeBase64Url} for the inverse operation to `Uint8Array`
  * @see {@link decodeBase64UrlString} for the inverse operation to `string`
  * @see {@link encodeBase64} for the standard Base64 variant
  *
- * @category Base64 getters
+ * @category encoding
  * @since 4.0.0
  */
 export function encodeBase64Url<E extends Uint8Array | string>(): Getter<string, E> {
@@ -1230,16 +1266,17 @@ export function encodeBase64Url<E extends Uint8Array | string>(): Getter<string,
  *
  * **Example** (Encoding to hex)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const encode = SchemaGetter.encodeHex<Uint8Array>()
+ * await Effect.runPromise(encode.run(Option.some(new Uint8Array([1, 2, 3])), {})) // => Option.some("010203")
  * ```
  *
  * @see {@link decodeHex} for the inverse operation to `Uint8Array`
  * @see {@link decodeHexString} for the inverse operation to `string`
  *
- * @category Hex getters
+ * @category encoding
  * @since 4.0.0
  */
 export function encodeHex<E extends Uint8Array | string>(): Getter<string, E> {
@@ -1255,24 +1292,25 @@ export function encodeHex<E extends Uint8Array | string>(): Getter<string, E> {
  *
  * **Example** (Decoding Base64 to bytes)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const decode = SchemaGetter.decodeBase64<string>()
- * // Getter<Uint8Array, string>
+ * const result = await Effect.runPromise(decode.run(Option.some("AQID"), {}))
+ * Option.map(result, Array.from) // => Option.some([1, 2, 3])
  * ```
  *
  * @see {@link decodeBase64String} to decode to `string` instead
  * @see {@link encodeBase64} for the inverse operation
  *
- * @category Base64 getters
+ * @category decoding
  * @since 4.0.0
  */
 export function decodeBase64<E extends string>(): Getter<Uint8Array, E> {
   return transformOrFail((input) =>
     Effect.mapErrorEager(
       Effect.fromResult(Encoding.decodeBase64(input)),
-      (e) => new SchemaIssue.InvalidValue(Option.some(input), { message: e.message })
+      () => new SchemaIssue.InvalidValue({ message: "Expected a valid Base64 string" })
     )
   )
 }
@@ -1286,23 +1324,23 @@ export function decodeBase64<E extends string>(): Getter<Uint8Array, E> {
  *
  * **Example** (Decoding Base64 to string)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const decode = SchemaGetter.decodeBase64String<string>()
- * // Getter<string, string>
+ * await Effect.runPromise(decode.run(Option.some("aGVsbG8="), {})) // => Option.some("hello")
  * ```
  *
  * @see {@link decodeBase64} to decode to `Uint8Array` instead
  * @see {@link encodeBase64} for the inverse operation
  *
- * @category Base64 getters
+ * @category decoding
  * @since 4.0.0
  */
 export function decodeBase64String<E extends string>(): Getter<string, E> {
   return transformOrFail((input) =>
     Result.match(Encoding.decodeBase64String(input), {
-      onFailure: (e) => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), { message: e.message })),
+      onFailure: () => Effect.fail(new SchemaIssue.InvalidValue({ message: "Expected a valid Base64 string" })),
       onSuccess: Effect.succeed
     })
   )
@@ -1317,23 +1355,24 @@ export function decodeBase64String<E extends string>(): Getter<string, E> {
  *
  * **Example** (Decoding Base64Url to bytes)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const decode = SchemaGetter.decodeBase64Url<string>()
- * // Getter<Uint8Array, string>
+ * const result = await Effect.runPromise(decode.run(Option.some("-_8="), {}))
+ * Option.map(result, Array.from) // => Option.some([251, 255])
  * ```
  *
  * @see {@link decodeBase64UrlString} to decode to `string` instead
  * @see {@link encodeBase64Url} for the inverse operation
  *
- * @category Base64 getters
+ * @category decoding
  * @since 4.0.0
  */
 export function decodeBase64Url<E extends string>(): Getter<Uint8Array, E> {
   return transformOrFail((input) =>
     Result.match(Encoding.decodeBase64Url(input), {
-      onFailure: (e) => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), { message: e.message })),
+      onFailure: () => Effect.fail(new SchemaIssue.InvalidValue({ message: "Expected a valid Base64Url string" })),
       onSuccess: Effect.succeed
     })
   )
@@ -1348,23 +1387,23 @@ export function decodeBase64Url<E extends string>(): Getter<Uint8Array, E> {
  *
  * **Example** (Decoding Base64Url to string)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const decode = SchemaGetter.decodeBase64UrlString<string>()
- * // Getter<string, string>
+ * await Effect.runPromise(decode.run(Option.some("aGVsbG8"), {})) // => Option.some("hello")
  * ```
  *
  * @see {@link decodeBase64Url} to decode to `Uint8Array` instead
  * @see {@link encodeBase64Url} for the inverse operation
  *
- * @category Base64 getters
+ * @category decoding
  * @since 4.0.0
  */
 export function decodeBase64UrlString<E extends string>(): Getter<string, E> {
   return transformOrFail((input) =>
     Result.match(Encoding.decodeBase64UrlString(input), {
-      onFailure: (e) => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), { message: e.message })),
+      onFailure: () => Effect.fail(new SchemaIssue.InvalidValue({ message: "Expected a valid Base64Url string" })),
       onSuccess: Effect.succeed
     })
   )
@@ -1379,23 +1418,27 @@ export function decodeBase64UrlString<E extends string>(): Getter<string, E> {
  *
  * **Example** (Decoding hex to bytes)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const decode = SchemaGetter.decodeHex<string>()
- * // Getter<Uint8Array, string>
+ * const result = await Effect.runPromise(decode.run(Option.some("010203"), {}))
+ * Option.map(result, Array.from) // => Option.some([1, 2, 3])
  * ```
  *
  * @see {@link decodeHexString} to decode to `string` instead
  * @see {@link encodeHex} for the inverse operation
  *
- * @category Hex getters
+ * @category decoding
  * @since 4.0.0
  */
 export function decodeHex<E extends string>(): Getter<Uint8Array, E> {
   return transformOrFail((input) =>
     Result.match(Encoding.decodeHex(input), {
-      onFailure: (e) => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), { message: e.message })),
+      onFailure: () =>
+        Effect.fail(
+          new SchemaIssue.InvalidValue({ message: "Expected a valid hexadecimal string" })
+        ),
       onSuccess: Effect.succeed
     })
   )
@@ -1410,23 +1453,26 @@ export function decodeHex<E extends string>(): Getter<Uint8Array, E> {
  *
  * **Example** (Decoding hex to string)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const decode = SchemaGetter.decodeHexString<string>()
- * // Getter<string, string>
+ * await Effect.runPromise(decode.run(Option.some("68656c6c6f"), {})) // => Option.some("hello")
  * ```
  *
  * @see {@link decodeHex} to decode to `Uint8Array` instead
  * @see {@link encodeHex} for the inverse operation
  *
- * @category Hex getters
+ * @category decoding
  * @since 4.0.0
  */
 export function decodeHexString<E extends string>(): Getter<string, E> {
   return transformOrFail((input) =>
     Result.match(Encoding.decodeHexString(input), {
-      onFailure: (e) => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), { message: e.message })),
+      onFailure: () =>
+        Effect.fail(
+          new SchemaIssue.InvalidValue({ message: "Expected a valid hexadecimal string" })
+        ),
       onSuccess: Effect.succeed
     })
   )
@@ -1443,15 +1489,16 @@ export function decodeHexString<E extends string>(): Getter<string, E> {
  *
  * **Example** (Encoding a URI component)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const encode = SchemaGetter.encodeUriComponent<string>()
+ * await Effect.runPromise(encode.run(Option.some("hello world"), {})) // => Option.some("hello%20world")
  * ```
  *
  * @see {@link decodeUriComponent} for the inverse operation
  *
- * @category URI
+ * @category encoding
  * @since 4.0.0
  */
 export function encodeUriComponent<E extends string>(): Getter<string, E> {
@@ -1467,26 +1514,26 @@ export function encodeUriComponent<E extends string>(): Getter<string, E> {
  *
  * **Example** (Decoding a URI component)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const decode = SchemaGetter.decodeUriComponent<string>()
- * // Getter<string, string>
+ * await Effect.runPromise(decode.run(Option.some("hello%20world"), {})) // => Option.some("hello world")
  * ```
  *
  * @see {@link encodeUriComponent} for the inverse operation
  *
- * @category URI
+ * @category decoding
  * @since 4.0.0
  */
 export function decodeUriComponent<E extends string>(): Getter<string, E> {
   return transformOrFail((input) => {
     try {
       return Effect.succeed(globalThis.decodeURIComponent(input))
-    } catch (e) {
+    } catch {
       return Effect.fail(
-        new SchemaIssue.InvalidValue(Option.some(input), {
-          message: e instanceof URIError ? e.message : "Invalid URI component"
+        new SchemaIssue.InvalidValue({
+          message: "Expected a valid URI component"
         })
       )
     }
@@ -1512,23 +1559,23 @@ export function decodeUriComponent<E extends string>(): Getter<string, E> {
  *
  * **Example** (Parsing DateTime)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { DateTime, Effect, Option, SchemaGetter } from "effect"
  *
  * const parseDate = SchemaGetter.dateTimeUtcFromInput<string>()
- * // Getter<DateTime.Utc, string>
+ * const result = await Effect.runPromise(parseDate.run(Option.some("2024-01-01T00:00:00Z"), {}))
+ * Option.map(result, DateTime.toEpochMillis) // => Option.some(1704067200000)
  * ```
  *
  * @see {@link Date} for a simpler coercion to `Date` (no validation)
  *
- * @category DateTime
+ * @category converting
  * @since 4.0.0
  */
 export function dateTimeUtcFromInput<E extends DateTime.DateTime.Input>(): Getter<DateTime.Utc, E> {
   return transformOrFail((input) => {
     return Option.match(DateTime.make(input), {
-      onNone: () =>
-        Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), { message: "Invalid DateTime input" })),
+      onNone: () => Effect.fail(new SchemaIssue.InvalidValue({ message: "Invalid DateTime input" })),
       onSome: (dt) => Effect.succeed(DateTime.toUtc(dt))
     })
   })
@@ -1550,18 +1597,20 @@ export function dateTimeUtcFromInput<E extends DateTime.DateTime.Input>(): Gette
  *
  * **Example** (Decoding FormData)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const decode = SchemaGetter.decodeFormData()
- * // Getter<TreeObject<string | Blob>, FormData>
+ * const formData = new FormData()
+ * formData.append("user[name]", "Alice")
+ * await Effect.runPromise(decode.run(Option.some(formData), {})) // => Option.some({ user: { name: "Alice" } })
  * ```
  *
  * @see {@link encodeFormData} for the corresponding encoder
  * @see {@link makeTreeRecord} for the underlying bracket-path parser
  * @see {@link decodeURLSearchParams} for the URLSearchParams variant
  *
- * @category FormData
+ * @category decoding
  * @since 4.0.0
  */
 export function decodeFormData(): Getter<Schema.TreeRecord<string | Blob>, FormData> {
@@ -1588,18 +1637,19 @@ const collectFormDataEntries = collectBracketPathEntries((value): value is strin
  *
  * **Example** (Encoding to FormData)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const encode = SchemaGetter.encodeFormData()
- * // Getter<FormData, unknown>
+ * const result = await Effect.runPromise(encode.run(Option.some({ name: "Alice" }), {}))
+ * Option.map(result, (formData) => formData.get("name")) // => Option.some("Alice")
  * ```
  *
  * @see {@link decodeFormData} for the corresponding decoder
  * @see {@link collectBracketPathEntries} for the underlying flattener
  * @see {@link encodeURLSearchParams} for the URLSearchParams variant
  *
- * @category FormData
+ * @category encoding
  * @since 4.0.0
  */
 export function encodeFormData(): Getter<FormData, unknown> {
@@ -1631,18 +1681,19 @@ export function encodeFormData(): Getter<FormData, unknown> {
  *
  * **Example** (Decoding URLSearchParams)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const decode = SchemaGetter.decodeURLSearchParams()
- * // Getter<TreeObject<string>, URLSearchParams>
+ * const params = new URLSearchParams("user[name]=Alice")
+ * await Effect.runPromise(decode.run(Option.some(params), {})) // => Option.some({ user: { name: "Alice" } })
  * ```
  *
  * @see {@link encodeURLSearchParams} for the corresponding encoder
  * @see {@link makeTreeRecord} for the underlying bracket-path parser
  * @see {@link decodeFormData} for the FormData variant
  *
- * @category search params
+ * @category decoding
  * @since 4.0.0
  */
 export function decodeURLSearchParams(): Getter<Schema.TreeRecord<string>, URLSearchParams> {
@@ -1666,18 +1717,19 @@ const collectURLSearchParamsEntries = collectBracketPathEntries(Predicate.isStri
  *
  * **Example** (Encoding to URLSearchParams)
  *
- * ```ts
- * import { SchemaGetter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
  *
  * const encode = SchemaGetter.encodeURLSearchParams()
- * // Getter<URLSearchParams, unknown>
+ * const result = await Effect.runPromise(encode.run(Option.some({ name: "Alice" }), {}))
+ * Option.map(result, (params) => params.toString()) // => Option.some("name=Alice")
  * ```
  *
  * @see {@link decodeURLSearchParams} for the corresponding decoder
  * @see {@link collectBracketPathEntries} for the underlying flattener
  * @see {@link encodeFormData} for the FormData variant
  *
- * @category search params
+ * @category encoding
  * @since 4.0.0
  */
 export function encodeURLSearchParams(): Getter<URLSearchParams, unknown> {
@@ -1736,22 +1788,21 @@ function bracketPathToTokens(bracketPath: string): Array<string | number> {
  *
  * **Example** (Building a tree from bracket paths)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { SchemaGetter } from "effect"
  *
- * const tree = SchemaGetter.makeTreeRecord([
+ * SchemaGetter.makeTreeRecord([
  *   ["user[name]", "Alice"],
  *   ["user[tags][]", "admin"],
  *   ["user[tags][]", "editor"]
- * ])
- * // { user: { name: "Alice", tags: ["admin", "editor"] } }
+ * ]) // => { user: { name: "Alice", tags: ["admin", "editor"] } }
  * ```
  *
  * @see {@link collectBracketPathEntries} for flattening trees into bracket-path entries
  * @see {@link decodeFormData} for a higher-level FormData decoder
  * @see {@link decodeURLSearchParams} for a higher-level URLSearchParams decoder
  *
- * @category Tree
+ * @category constructors
  * @since 4.0.0
  */
 export function makeTreeRecord<A>(
@@ -1833,19 +1884,20 @@ export function makeTreeRecord<A>(
  *
  * **Example** (Flattening an object to bracket paths)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Predicate, SchemaGetter } from "effect"
  *
  * const collectStrings = SchemaGetter.collectBracketPathEntries(Predicate.isString)
  * const entries = collectStrings({ user: { name: "Alice", tags: ["admin", "editor"] } })
- * // [["user[name]", "Alice"], ["user[tags]", "admin"], ["user[tags]", "editor"]]
+ *
+ * entries // => [["user[name]", "Alice"], ["user[tags]", "admin"], ["user[tags]", "editor"]]
  * ```
  *
  * @see {@link makeTreeRecord} for building trees from bracket-path entries
  * @see {@link encodeFormData} for a higher-level FormData encoder
  * @see {@link encodeURLSearchParams} for a higher-level URLSearchParams encoder
  *
- * @category Tree
+ * @category converting
  * @since 4.0.0
  */
 export function collectBracketPathEntries<A>(isLeaf: (value: unknown) => value is A) {