effect 4.0.0-beta.98 → 4.0.0-rc.108

package/src/SchemaGetter.ts

@@ -14,7 +14,7 @@
 import * as DateTime from "./DateTime.ts"
 import * as Effect from "./Effect.ts"
 import * as Encoding from "./Encoding.ts"
-import * as internalRecord from "./internal/record.ts"
+import * as InternalRecord from "./internal/record.ts"
 import * as Option from "./Option.ts"
 import * as Pipeable from "./Pipeable.ts"
 import * as Predicate from "./Predicate.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
@@ -133,16 +133,19 @@ export function succeed<const T, E>(t: T): Getter<T, E> {
  * **Details**
  *
  * - Always fails with the `Issue` returned by `f`.
- * - The failure function receives the original `Option<E>` input for error context.
+ * - The failure function receives the original `Option<E>` input and the
+ *   effective `ParseOptions` for error context.
  *
  * **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
@@ -151,8 +154,10 @@ export function succeed<const T, E>(t: T): Getter<T, E> {
  * @category constructors
  * @since 4.0.0
  */
-export function fail<T, E>(f: (oe: Option.Option<E>) => SchemaIssue.Issue): Getter<T, E> {
-  return new Getter((oe) => Effect.fail(f(oe)))
+export function fail<T, E>(
+  f: (oe: Option.Option<E>, options: SchemaAST.ParseOptions) => SchemaIssue.Issue
+): Getter<T, E> {
+  return new Getter((oe, options) => Effect.fail(f(oe, options)))
 }
 
 /**
@@ -171,12 +176,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 +192,12 @@ 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, options) => {
+    const annotations = { message: message(oe) }
+    return Option.isSome(oe)
+      ? new SchemaIssue.Forbidden(annotations, oe.value, options)
+      : new SchemaIssue.Forbidden(annotations)
+  })
 }
 
 const passthrough_ = new Getter<any, any>(Effect.succeed)
@@ -211,7 +223,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 +233,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 +263,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 +296,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 +332,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 +370,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 +405,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 +449,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 +473,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, t, options)
       return issue ?
         Effect.fail(issue) :
         Effect.succeed(Option.some(t))
@@ -479,7 +499,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 +508,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 +538,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) => {
+ *   (s, options) => {
  *     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" }, s, options))
  *       : 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 +579,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 +613,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 +646,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 +682,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 +713,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 +743,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 +772,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 +801,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 +827,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 +850,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 +873,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 +896,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 +921,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 +946,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 +971,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,35 +1004,53 @@ 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` whose `expected`
+ *   annotation is `"a valid JSON string"`. Its default message includes the
+ *   reported input when `reportInput` is enabled.
  *
  * **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>
 export function parseJson<E extends string>(options: ParseJsonOptions): Getter<unknown, E>
 export function parseJson<E extends string>(options?: ParseJsonOptions | undefined): Getter<unknown, E> {
-  return onSome((input) =>
+  return onSome((input, parseOptions) =>
     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(
+          { expected: "a valid JSON string" },
+          input,
+          parseOptions
+        )
     })
   )
 }
 
+/**
+ * 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]
 }
 
@@ -1015,33 +1065,41 @@ 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 function stringifyJson(options?: StringifyJsonOptions): Getter<string, unknown> {
-  return onSome((input) =>
+  return onSome((input, parseOptions) =>
     Effect.try({
-      try: () => Option.some(JSON.stringify(input, options?.replacer, options?.space)),
-      catch: (e) => new SchemaIssue.InvalidValue(Option.some(input), { message: globalThis.String(e) })
+      try: () => {
+        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: () =>
+        new SchemaIssue.InvalidValue(
+          { expected: "a JSON-serializable value" },
+          input,
+          parseOptions
+        )
     })
   )
 }
@@ -1062,17 +1120,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?: {
@@ -1085,7 +1143,7 @@ export function splitKeyValue<E extends string>(options?: {
     input.split(separator).reduce((acc, pair) => {
       const [key, value] = pair.split(keyValueSeparator)
       if (key && value) {
-        acc[key] = value
+        InternalRecord.assignProperty(acc, key, value)
       }
       return acc
     }, {} as Record<string, string>)
@@ -1108,16 +1166,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?: {
@@ -1146,17 +1204,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?: {
@@ -1175,17 +1232,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> {
@@ -1201,17 +1259,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> {
@@ -1227,16 +1286,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> {
@@ -1252,24 +1312,30 @@ 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) =>
+  return transformOrFail((input, options) =>
     Effect.mapErrorEager(
       Effect.fromResult(Encoding.decodeBase64(input)),
-      (e) => new SchemaIssue.InvalidValue(Option.some(input), { message: e.message })
+      () =>
+        new SchemaIssue.InvalidValue(
+          { expected: "a valid Base64 string" },
+          input,
+          options
+        )
     )
   )
 }
@@ -1283,23 +1349,30 @@ 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) =>
+  return transformOrFail((input, options) =>
     Result.match(Encoding.decodeBase64String(input), {
-      onFailure: (e) => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), { message: e.message })),
+      onFailure: () =>
+        Effect.fail(
+          new SchemaIssue.InvalidValue(
+            { expected: "a valid Base64 string" },
+            input,
+            options
+          )
+        ),
       onSuccess: Effect.succeed
     })
   )
@@ -1314,23 +1387,31 @@ 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) =>
+  return transformOrFail((input, options) =>
     Result.match(Encoding.decodeBase64Url(input), {
-      onFailure: (e) => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), { message: e.message })),
+      onFailure: () =>
+        Effect.fail(
+          new SchemaIssue.InvalidValue(
+            { expected: "a valid Base64Url string" },
+            input,
+            options
+          )
+        ),
       onSuccess: Effect.succeed
     })
   )
@@ -1345,23 +1426,30 @@ 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) =>
+  return transformOrFail((input, options) =>
     Result.match(Encoding.decodeBase64UrlString(input), {
-      onFailure: (e) => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), { message: e.message })),
+      onFailure: () =>
+        Effect.fail(
+          new SchemaIssue.InvalidValue(
+            { expected: "a valid Base64Url string" },
+            input,
+            options
+          )
+        ),
       onSuccess: Effect.succeed
     })
   )
@@ -1376,23 +1464,31 @@ 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) =>
+  return transformOrFail((input, options) =>
     Result.match(Encoding.decodeHex(input), {
-      onFailure: (e) => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), { message: e.message })),
+      onFailure: () =>
+        Effect.fail(
+          new SchemaIssue.InvalidValue(
+            { expected: "a valid hexadecimal string" },
+            input,
+            options
+          )
+        ),
       onSuccess: Effect.succeed
     })
   )
@@ -1407,23 +1503,30 @@ 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) =>
+  return transformOrFail((input, options) =>
     Result.match(Encoding.decodeHexString(input), {
-      onFailure: (e) => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), { message: e.message })),
+      onFailure: () =>
+        Effect.fail(
+          new SchemaIssue.InvalidValue(
+            { expected: "a valid hexadecimal string" },
+            input,
+            options
+          )
+        ),
       onSuccess: Effect.succeed
     })
   )
@@ -1440,15 +1543,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> {
@@ -1464,27 +1568,29 @@ 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) => {
+  return transformOrFail((input, options) => {
     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(
+          { expected: "a valid URI component" },
+          input,
+          options
+        )
       )
     }
   })
@@ -1509,23 +1615,26 @@ 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 transformOrFail((input, options) => {
     return Option.match(DateTime.make(input), {
       onNone: () =>
-        Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), { message: "Invalid DateTime input" })),
+        Effect.fail(
+          new SchemaIssue.InvalidValue({ message: "Invalid DateTime input" }, input, options)
+        ),
       onSome: (dt) => Effect.succeed(DateTime.toUtc(dt))
     })
   })
@@ -1547,18 +1656,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 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 function decodeFormData(): Getter<Schema.TreeRecord<string | Blob>, FormData> {
@@ -1585,18 +1696,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 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 function encodeFormData(): Getter<FormData, unknown> {
@@ -1628,18 +1740,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 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 function decodeURLSearchParams(): Getter<Schema.TreeRecord<string>, URLSearchParams> {
@@ -1663,18 +1776,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 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 function encodeURLSearchParams(): Getter<URLSearchParams, unknown> {
@@ -1704,20 +1818,6 @@ function bracketPathToTokens(bracketPath: string): Array<string | number> {
     .map((part) => (INDEX_REGEXP.test(part) ? globalThis.Number(part) : part))
 }
 
-function getOrCreateContainer(
-  self: any,
-  key: PropertyKey,
-  shouldBeArray: boolean
-): any {
-  const current = Object.hasOwn(self, key) ? self[key] : undefined
-  if (current !== undefined) {
-    return current
-  }
-  const container = shouldBeArray ? [] : {}
-  internalRecord.set(self, key, container)
-  return container
-}
-
 /**
  * Builds a nested tree object from a list of bracket-path entries.
  *
@@ -1740,31 +1840,47 @@ function getOrCreateContainer(
  *   - `"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 function makeTreeRecord<A>(
   bracketPathEntries: ReadonlyArray<readonly [bracketPath: string, value: A]>
 ): Schema.TreeRecord<A> {
   const out: any = {}
+  const containers = new WeakSet<object>()
+
+  function getOrCreateContainer(self: any, key: PropertyKey, shouldBeArray: boolean): any {
+    const current = Object.hasOwn(self, key) ? self[key] : undefined
+    if (containers.has(current) && Array.isArray(current) === shouldBeArray) {
+      return current
+    }
+    const container = shouldBeArray ? [] : {}
+    containers.add(container)
+    InternalRecord.assignProperty(self, key, container)
+    return container
+  }
+
   bracketPathEntries.forEach(([key, value]) => {
     const tokens = bracketPathToTokens(key)
     let cur: any = out
@@ -1789,9 +1905,9 @@ export function makeTreeRecord<A>(
         if (hasOwn && Array.isArray(cur[token])) {
           cur[token].push(value)
         } else if (hasOwn) {
-          internalRecord.set(cur, token, [cur[token], value])
+          InternalRecord.assignProperty(cur, token, [cur[token], value])
         } else {
-          internalRecord.set(cur, token, value)
+          InternalRecord.assignProperty(cur, token, value)
         }
       } else {
         const next = tokens[i + 1]
@@ -1815,7 +1931,6 @@ export function makeTreeRecord<A>(
  *
  * **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.
@@ -1823,22 +1938,25 @@ export function makeTreeRecord<A>(
  * - 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 function collectBracketPathEntries<A>(isLeaf: (value: unknown) => value is A) {