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

package/dist/SchemaGetter.js

@@ -14,7 +14,7 @@
 import * as DateTime from "./DateTime.js";
 import * as Effect from "./Effect.js";
 import * as Encoding from "./Encoding.js";
-import * as internalRecord from "./internal/record.js";
+import * as InternalRecord from "./internal/record.js";
 import * as Option from "./Option.js";
 import * as Pipeable from "./Pipeable.js";
 import * as Predicate from "./Predicate.js";
@@ -42,13 +42,13 @@ import * as Str from "./String.js";
  *
  * **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
@@ -92,11 +92,11 @@ export class Getter 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
@@ -119,16 +119,19 @@ export function succeed(t) {
  * **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
@@ -138,7 +141,7 @@ export function succeed(t) {
  * @since 4.0.0
  */
 export function fail(f) {
-  return new Getter(oe => Effect.fail(f(oe)));
+  return new Getter((oe, options) => Effect.fail(f(oe, options)));
 }
 /**
  * Creates a getter that always fails with a `Forbidden` issue.
@@ -156,12 +159,14 @@ export function fail(f) {
  *
  * **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
@@ -170,9 +175,12 @@ export function fail(f) {
  * @since 4.0.0
  */
 export function forbidden(message) {
-  return fail(oe => new SchemaIssue.Forbidden(oe, {
-    message: message(oe)
-  }));
+  return fail((oe, options) => {
+    const annotations = {
+      message: message(oe)
+    };
+    return Option.isSome(oe) ? new SchemaIssue.Forbidden(annotations, oe.value, options) : new SchemaIssue.Forbidden(annotations);
+  });
 }
 const passthrough_ = /*#__PURE__*/new Getter(Effect.succeed);
 function isPassthrough(getter) {
@@ -204,19 +212,20 @@ export function passthroughSubtype() {
  *
  * **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(f) {
@@ -238,16 +247,18 @@ export function onNone(f) {
  *
  * **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(annotations) {
@@ -270,19 +281,20 @@ export function required(annotations) {
  *
  * **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(f) {
@@ -310,24 +322,25 @@ export function onSome(f) {
  *
  * **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(f) {
   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));
     }));
   });
@@ -350,7 +363,7 @@ export function checkEffect(f) {
  *
  * **Example** (Transforming strings to numbers)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaGetter } from "effect"
  *
  * const NumberFromString = Schema.String.pipe(
@@ -359,13 +372,14 @@ export function checkEffect(f) {
  *     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(f) {
@@ -387,23 +401,24 @@ export function transform(f) {
  *
  * **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(f) {
@@ -424,18 +439,19 @@ export function transformOrFail(f) {
  *
  * **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(f) {
@@ -456,16 +472,17 @@ export function transformOptional(f) {
  *
  * **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() {
@@ -487,17 +504,17 @@ export function omit() {
  *
  * **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(defaultValue) {
@@ -520,16 +537,16 @@ export function withDefault(defaultValue) {
  *
  * **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() {
@@ -550,16 +567,16 @@ export function String() {
  *
  * **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() {
@@ -579,14 +596,14 @@ export function Number() {
  *
  * **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() {
@@ -607,14 +624,14 @@ export function Boolean() {
  *
  * **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() {
@@ -635,16 +652,17 @@ export function BigInt() {
  *
  * **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() {
@@ -659,13 +677,14 @@ export function Date() {
  *
  * **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() {
@@ -680,13 +699,14 @@ export function trim() {
  *
  * **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() {
@@ -701,13 +721,14 @@ export function capitalize() {
  *
  * **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() {
@@ -722,15 +743,16 @@ export function uncapitalize() {
  *
  * **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() {
@@ -745,15 +767,16 @@ export function snakeToCamel() {
  *
  * **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() {
@@ -768,15 +791,16 @@ export function camelToSnake() {
  *
  * **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() {
@@ -791,26 +815,27 @@ export function toLowerCase() {
  *
  * **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() {
   return transform(Str.toUpperCase);
 }
 export function parseJson(options) {
-  return onSome(input => Effect.try({
+  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)
   }));
 }
 /**
@@ -824,34 +849,37 @@ export function parseJson(options) {
  * **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) {
-  return onSome(input => Effect.try({
-    try: () => Option.some(JSON.stringify(input, options?.replacer, options?.space)),
-    catch: e => new SchemaIssue.InvalidValue(Option.some(input), {
-      message: globalThis.String(e)
-    })
+  return onSome((input, parseOptions) => Effect.try({
+    try: () => {
+      const output = JSON.stringify(input, options?.replacer, 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)
   }));
 }
 /**
@@ -870,17 +898,17 @@ export function stringifyJson(options) {
  *
  * **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(options) {
@@ -889,7 +917,7 @@ export function splitKeyValue(options) {
   return transform(input => 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;
   }, {}));
@@ -910,16 +938,16 @@ export function splitKeyValue(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(options) {
@@ -942,17 +970,16 @@ export function joinKeyValue(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(options) {
@@ -968,17 +995,18 @@ export function split(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() {
@@ -993,17 +1021,18 @@ export function encodeBase64() {
  *
  * **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() {
@@ -1018,16 +1047,17 @@ export function encodeBase64Url() {
  *
  * **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() {
@@ -1042,23 +1072,24 @@ export function encodeHex() {
  *
  * **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() {
-  return transformOrFail(input => Effect.mapErrorEager(Effect.fromResult(Encoding.decodeBase64(input)), e => new SchemaIssue.InvalidValue(Option.some(input), {
-    message: e.message
-  })));
+  return transformOrFail((input, options) => Effect.mapErrorEager(Effect.fromResult(Encoding.decodeBase64(input)), () => new SchemaIssue.InvalidValue({
+    expected: "a valid Base64 string"
+  }, input, options)));
 }
 /**
  * Decodes a Base64 string to a UTF-8 `string`.
@@ -1069,24 +1100,24 @@ export function decodeBase64() {
  *
  * **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() {
-  return transformOrFail(input => Result.match(Encoding.decodeBase64String(input), {
-    onFailure: e => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), {
-      message: e.message
-    })),
+  return transformOrFail((input, options) => Result.match(Encoding.decodeBase64String(input), {
+    onFailure: () => Effect.fail(new SchemaIssue.InvalidValue({
+      expected: "a valid Base64 string"
+    }, input, options)),
     onSuccess: Effect.succeed
   }));
 }
@@ -1099,24 +1130,25 @@ export function decodeBase64String() {
  *
  * **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() {
-  return transformOrFail(input => Result.match(Encoding.decodeBase64Url(input), {
-    onFailure: e => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), {
-      message: e.message
-    })),
+  return transformOrFail((input, options) => Result.match(Encoding.decodeBase64Url(input), {
+    onFailure: () => Effect.fail(new SchemaIssue.InvalidValue({
+      expected: "a valid Base64Url string"
+    }, input, options)),
     onSuccess: Effect.succeed
   }));
 }
@@ -1129,24 +1161,24 @@ export function decodeBase64Url() {
  *
  * **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() {
-  return transformOrFail(input => Result.match(Encoding.decodeBase64UrlString(input), {
-    onFailure: e => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), {
-      message: e.message
-    })),
+  return transformOrFail((input, options) => Result.match(Encoding.decodeBase64UrlString(input), {
+    onFailure: () => Effect.fail(new SchemaIssue.InvalidValue({
+      expected: "a valid Base64Url string"
+    }, input, options)),
     onSuccess: Effect.succeed
   }));
 }
@@ -1159,24 +1191,25 @@ export function decodeBase64UrlString() {
  *
  * **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() {
-  return transformOrFail(input => Result.match(Encoding.decodeHex(input), {
-    onFailure: e => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), {
-      message: e.message
-    })),
+  return transformOrFail((input, options) => Result.match(Encoding.decodeHex(input), {
+    onFailure: () => Effect.fail(new SchemaIssue.InvalidValue({
+      expected: "a valid hexadecimal string"
+    }, input, options)),
     onSuccess: Effect.succeed
   }));
 }
@@ -1189,24 +1222,24 @@ export function decodeHex() {
  *
  * **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() {
-  return transformOrFail(input => Result.match(Encoding.decodeHexString(input), {
-    onFailure: e => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), {
-      message: e.message
-    })),
+  return transformOrFail((input, options) => Result.match(Encoding.decodeHexString(input), {
+    onFailure: () => Effect.fail(new SchemaIssue.InvalidValue({
+      expected: "a valid hexadecimal string"
+    }, input, options)),
     onSuccess: Effect.succeed
   }));
 }
@@ -1221,15 +1254,16 @@ export function decodeHexString() {
  *
  * **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() {
@@ -1244,26 +1278,26 @@ export function encodeUriComponent() {
  *
  * **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() {
-  return transformOrFail(input => {
+  return transformOrFail((input, options) => {
     try {
       return Effect.succeed(globalThis.decodeURIComponent(input));
-    } catch (e) {
-      return Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), {
-        message: e instanceof URIError ? e.message : "Invalid URI component"
-      }));
+    } catch {
+      return Effect.fail(new SchemaIssue.InvalidValue({
+        expected: "a valid URI component"
+      }, input, options));
     }
   });
 }
@@ -1286,24 +1320,25 @@ export function decodeUriComponent() {
  *
  * **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() {
-  return transformOrFail(input => {
+  return transformOrFail((input, options) => {
     return Option.match(DateTime.make(input), {
-      onNone: () => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), {
+      onNone: () => Effect.fail(new SchemaIssue.InvalidValue({
         message: "Invalid DateTime input"
-      })),
+      }, input, options)),
       onSome: dt => Effect.succeed(DateTime.toUtc(dt))
     });
   });
@@ -1324,18 +1359,20 @@ export function dateTimeUtcFromInput() {
  *
  * **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() {
@@ -1358,18 +1395,19 @@ const collectFormDataEntries = /*#__PURE__*/collectBracketPathEntries(value => t
  *
  * **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() {
@@ -1400,18 +1438,19 @@ export function encodeFormData() {
  *
  * **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() {
@@ -1433,18 +1472,19 @@ const collectURLSearchParamsEntries = /*#__PURE__*/collectBracketPathEntries(Pre
  *
  * **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() {
@@ -1467,15 +1507,6 @@ function bracketPathToTokens(bracketPath) {
   const start = replaced.startsWith(".") ? 1 : 0;
   return parts.slice(start).map(part => INDEX_REGEXP.test(part) ? globalThis.Number(part) : part);
 }
-function getOrCreateContainer(self, key, shouldBeArray) {
-  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.
  *
@@ -1498,29 +1529,43 @@ function getOrCreateContainer(self, key, shouldBeArray) {
  *   - `"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(bracketPathEntries) {
   const out = {};
+  const containers = new WeakSet();
+  function getOrCreateContainer(self, key, shouldBeArray) {
+    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 = out;
@@ -1544,9 +1589,9 @@ export function makeTreeRecord(bracketPathEntries) {
         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];
@@ -1569,7 +1614,6 @@ export function makeTreeRecord(bracketPathEntries) {
  *
  * **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.
@@ -1577,22 +1621,25 @@ export function makeTreeRecord(bracketPathEntries) {
  * - 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(isLeaf) {