effect 4.0.0-beta.101 → 4.0.0-beta.103

package/dist/SchemaGetter.d.ts

@@ -39,13 +39,13 @@ import * as SchemaIssue from "./SchemaIssue.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
@@ -76,11 +76,11 @@ export declare 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
@@ -105,12 +105,14 @@ export declare 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
@@ -136,12 +138,14 @@ export declare function fail<T, E>(f: (oe: Option.Option<E>) => SchemaIssue.Issu
  *
  * **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
@@ -167,7 +171,7 @@ export declare function forbidden<T, E>(message: (oe: Option.Option<E>) => strin
  *
  * **Example** (Passing through identity transformations)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaGetter } from "effect"
  *
  * // No transformation needed — types already match
@@ -177,6 +181,7 @@ export declare function forbidden<T, E>(message: (oe: Option.Option<E>) => strin
  *     encode: SchemaGetter.passthrough()
  *   })
  * )
+ * Schema.decodeSync(StringToString)("hello") // => "hello"
  * ```
  *
  * @see {@link passthroughSupertype} when `T extends E`
@@ -204,11 +209,12 @@ export declare 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
@@ -232,11 +238,12 @@ export declare function passthroughSupertype<T extends E, E>(): Getter<T, E>;
  *
  * **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
@@ -263,19 +270,20 @@ export declare function passthroughSubtype<T, E extends T>(): Getter<T, E>;
  *
  * **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 declare function onNone<T, E extends T = T, R = never>(f: (options: SchemaAST.ParseOptions) => Effect.Effect<Option.Option<T>, SchemaIssue.Issue, R>): Getter<T, E, R>;
@@ -295,16 +303,18 @@ export declare function onNone<T, E extends T = T, R = never>(f: (options: Schem
  *
  * **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 declare function required<T, E extends T = T>(annotations?: Schema.Annotations.Key<T>): Getter<T, E>;
@@ -325,19 +335,20 @@ export declare function required<T, E extends T = T>(annotations?: Schema.Annota
  *
  * **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 declare function onSome<T, E, R = never>(f: (e: E, options: SchemaAST.ParseOptions) => Effect.Effect<Option.Option<T>, SchemaIssue.Issue, R>): Getter<T, E, R>;
@@ -363,18 +374,19 @@ export declare function onSome<T, E, R = never>(f: (e: E, options: SchemaAST.Par
  *
  * **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 declare function checkEffect<T, R = never>(f: (input: T, options: SchemaAST.ParseOptions) => Effect.Effect<undefined | boolean | Schema.FilterIssue, never, R>): Getter<T, T, R>;
@@ -396,7 +408,7 @@ export declare function checkEffect<T, R = never>(f: (input: T, options: SchemaA
  *
  * **Example** (Transforming strings to numbers)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaGetter } from "effect"
  *
  * const NumberFromString = Schema.String.pipe(
@@ -405,13 +417,14 @@ export declare function checkEffect<T, R = never>(f: (input: T, options: SchemaA
  *     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 declare function transform<T, E>(f: (e: E) => T): Getter<T, E>;
@@ -431,23 +444,24 @@ export declare 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 declare function transformOrFail<T, E, R = never>(f: (e: E, options: SchemaAST.ParseOptions) => Effect.Effect<T, SchemaIssue.Issue, R>): Getter<T, E, R>;
@@ -466,18 +480,19 @@ export declare function transformOrFail<T, E, R = never>(f: (e: E, options: Sche
  *
  * **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 declare function transformOptional<T, E>(f: (oe: Option.Option<E>) => Option.Option<T>): Getter<T, E>;
@@ -496,16 +511,17 @@ export declare function transformOptional<T, E>(f: (oe: Option.Option<E>) => Opt
  *
  * **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 declare function omit<T>(): Getter<never, T>;
@@ -525,17 +541,17 @@ export declare 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 declare function withDefault<T, R = never>(defaultValue: Effect.Effect<T, SchemaIssue.Issue, R>): Getter<T, T | undefined, R>;
@@ -553,16 +569,16 @@ export declare function withDefault<T, R = never>(defaultValue: Effect.Effect<T,
  *
  * **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 declare function String<E>(): Getter<string, E>;
@@ -581,16 +597,16 @@ export declare 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 declare function Number<E>(): Getter<number, E>;
@@ -608,14 +624,14 @@ export declare 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 declare function Boolean<E>(): Getter<boolean, E>;
@@ -634,14 +650,14 @@ export declare 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 declare function BigInt<E extends string | number | bigint | boolean>(): Getter<bigint, E>;
@@ -660,16 +676,17 @@ export declare function BigInt<E extends string | number | bigint | boolean>():
  *
  * **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 declare function Date<E extends string | number | Date>(): Getter<Date, E>;
@@ -682,13 +699,14 @@ export declare 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 declare function trim<E extends string>(): Getter<string, E>;
@@ -701,13 +719,14 @@ export declare 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 declare function capitalize<E extends string>(): Getter<string, E>;
@@ -720,13 +739,14 @@ export declare 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 declare function uncapitalize<E extends string>(): Getter<string, E>;
@@ -739,15 +759,16 @@ export declare 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 declare function snakeToCamel<E extends string>(): Getter<string, E>;
@@ -760,15 +781,16 @@ export declare 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 declare function camelToSnake<E extends string>(): Getter<string, E>;
@@ -781,15 +803,16 @@ export declare 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 declare function toLowerCase<E extends string>(): Getter<string, E>;
@@ -802,15 +825,16 @@ export declare 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 declare function toUpperCase<E extends string>(): Getter<string, E>;
@@ -830,26 +854,33 @@ 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 declare function parseJson<E extends string>(): Getter<Schema.MutableJson, E>;
 export declare function parseJson<E extends string>(options: ParseJsonOptions): Getter<unknown, E>;
+/**
+ * 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];
 };
 /**
@@ -863,26 +894,23 @@ type StringifyJsonOptions = {
  * **Details**
  *
  * - Skips `None` inputs.
- * - On thrown stringify failures, such as circular references, fails with
+ * - If `JSON.stringify` throws or returns `undefined`, 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)
  *
- * ```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 declare function stringifyJson(options?: StringifyJsonOptions): Getter<string, unknown>;
@@ -902,17 +930,17 @@ export declare function stringifyJson(options?: StringifyJsonOptions): Getter<st
  *
  * **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 declare function splitKeyValue<E extends string>(options?: {
@@ -935,16 +963,16 @@ export declare 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 declare function joinKeyValue<E extends Record<PropertyKey, string>>(options?: {
@@ -966,17 +994,16 @@ export declare function joinKeyValue<E extends Record<PropertyKey, string>>(opti
  *
  * **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 declare function split<E extends string>(options?: {
@@ -991,17 +1018,18 @@ export declare 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 declare function encodeBase64<E extends Uint8Array | string>(): Getter<string, E>;
@@ -1014,17 +1042,18 @@ export declare function encodeBase64<E extends Uint8Array | string>(): Getter<st
  *
  * **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 declare function encodeBase64Url<E extends Uint8Array | string>(): Getter<string, E>;
@@ -1037,16 +1066,17 @@ export declare function encodeBase64Url<E extends Uint8Array | string>(): Getter
  *
  * **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 declare function encodeHex<E extends Uint8Array | string>(): Getter<string, E>;
@@ -1059,17 +1089,18 @@ export declare function encodeHex<E extends Uint8Array | string>(): Getter<strin
  *
  * **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 declare function decodeBase64<E extends string>(): Getter<Uint8Array, E>;
@@ -1082,17 +1113,17 @@ export declare 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 declare function decodeBase64String<E extends string>(): Getter<string, E>;
@@ -1105,17 +1136,18 @@ export declare 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 declare function decodeBase64Url<E extends string>(): Getter<Uint8Array, E>;
@@ -1128,17 +1160,17 @@ export declare function decodeBase64Url<E extends string>(): Getter<Uint8Array,
  *
  * **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 declare function decodeBase64UrlString<E extends string>(): Getter<string, E>;
@@ -1151,17 +1183,18 @@ export declare function decodeBase64UrlString<E extends string>(): Getter<string
  *
  * **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 declare function decodeHex<E extends string>(): Getter<Uint8Array, E>;
@@ -1174,17 +1207,17 @@ export declare 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 declare function decodeHexString<E extends string>(): Getter<string, E>;
@@ -1199,15 +1232,16 @@ export declare 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 declare function encodeUriComponent<E extends string>(): Getter<string, E>;
@@ -1220,16 +1254,16 @@ export declare 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 declare function decodeUriComponent<E extends string>(): Getter<string, E>;
@@ -1252,16 +1286,17 @@ export declare 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 declare function dateTimeUtcFromInput<E extends DateTime.DateTime.Input>(): Getter<DateTime.Utc, E>;
@@ -1281,18 +1316,20 @@ export declare function dateTimeUtcFromInput<E extends DateTime.DateTime.Input>(
  *
  * **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 inverse operation
+ * @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 declare function decodeFormData(): Getter<Schema.TreeRecord<string | Blob>, FormData>;
@@ -1312,18 +1349,19 @@ export declare function decodeFormData(): Getter<Schema.TreeRecord<string | Blob
  *
  * **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 inverse operation
+ * @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 declare function encodeFormData(): Getter<FormData, unknown>;
@@ -1343,18 +1381,19 @@ export declare 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 inverse operation
+ * @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 declare function decodeURLSearchParams(): Getter<Schema.TreeRecord<string>, URLSearchParams>;
@@ -1373,18 +1412,19 @@ export declare function decodeURLSearchParams(): Getter<Schema.TreeRecord<string
  *
  * **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 inverse operation
+ * @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 declare function encodeURLSearchParams(): Getter<URLSearchParams, unknown>;
@@ -1410,25 +1450,28 @@ export declare function encodeURLSearchParams(): Getter<URLSearchParams, unknown
  *   - `"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.
  *
  * **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 the inverse operation (tree to flat entries)
+ * @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 declare function makeTreeRecord<A>(bracketPathEntries: ReadonlyArray<readonly [bracketPath: string, value: A]>): Schema.TreeRecord<A>;
@@ -1443,7 +1486,6 @@ export declare function makeTreeRecord<A>(bracketPathEntries: ReadonlyArray<read
  *
  * **Details**
  *
- * - This is the inverse of {@link makeTreeRecord}.
  * - 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.
@@ -1451,22 +1493,25 @@ export declare function makeTreeRecord<A>(bracketPathEntries: ReadonlyArray<read
  * - 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.
  *
  * **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 the inverse operation (flat entries to tree)
+ * @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 declare function collectBracketPathEntries<A>(isLeaf: (value: unknown) => value is A): (input: object) => Array<[bracketPath: string, value: A]>;