effect 4.0.0-beta.74 → 4.0.0-beta.76

package/dist/SchemaTransformation.js

@@ -88,20 +88,20 @@ import * as BigDecimal from "./BigDecimal.js";
 import * as DateTime from "./DateTime.js";
 import * as Duration from "./Duration.js";
 import * as Effect from "./Effect.js";
-import { formatDate } from "./Formatter.js";
+import { format, formatDate, formatJson } from "./Formatter.js";
 import * as Option from "./Option.js";
 import * as Predicate from "./Predicate.js";
-import * as Getter from "./SchemaGetter.js";
-import * as Issue from "./SchemaIssue.js";
+import * as SchemaGetter from "./SchemaGetter.js";
+import * as SchemaIssue from "./SchemaIssue.js";
 /**
  * Middleware that wraps the entire parsing `Effect` pipeline for both
  * decode and encode directions.
  *
  * **When to use**
  *
- * Use when you need to catch or recover from parsing errors (e.g. `Schema.catchDecoding`).
- * - You need to run side effects around the parsing pipeline.
- * - You need access to the full `Effect` rather than a single decoded value.
+ * Use when you need a schema middleware to catch or recover from parsing
+ * errors (e.g. `Schema.catchDecoding`), run side effects around the parsing
+ * pipeline, or access the full `Effect` rather than a single decoded value.
  *
  * **Details**
  *
@@ -154,7 +154,8 @@ const TypeId = "~effect/SchemaTransformation/Transformation";
  *
  * **When to use**
  *
- * Use when you need to define how a schema converts between two representations.
+ * Use when you need a schema transformation that defines how a schema converts
+ * between two representations.
  * - You want to compose multiple transformations into a pipeline.
  * - You want to flip a transformation to swap decode/encode.
  *
@@ -210,7 +211,8 @@ export class Transformation {
  *
  * **When to use**
  *
- * Use to check whether a value is already a Transformation before wrapping it.
+ * Use to check whether a value is already a schema transformation before
+ * wrapping it.
  *
  * **Details**
  *
@@ -244,7 +246,8 @@ export function isTransformation(u) {
  *
  * **When to use**
  *
- * Use when you already have `Getter` instances and want to pair them.
+ * Use when you already have schema getter instances and want to pair them into
+ * a schema transformation.
  * - You want idempotent wrapping (won't double-wrap).
  *
  * **Details**
@@ -281,8 +284,8 @@ export const make = options => {
  *
  * **When to use**
  *
- * Use when the transformation can fail (e.g. parsing, validation).
- * - The transformation requires Effect services.
+ * Use when you need a schema transformation that may fail or require Effect
+ * services.
  *
  * **Details**
  *
@@ -319,7 +322,7 @@ export const make = options => {
  * @since 3.10.0
  */
 export function transformOrFail(options) {
-  return new Transformation(Getter.transformOrFail(options.decode), Getter.transformOrFail(options.encode));
+  return new Transformation(SchemaGetter.transformOrFail(options.decode), SchemaGetter.transformOrFail(options.encode));
 }
 /**
  * Creates a `Transformation` from pure (sync, infallible) decode and encode
@@ -327,8 +330,8 @@ export function transformOrFail(options) {
  *
  * **When to use**
  *
- * Use when the conversion cannot fail.
- * - No Effect services are needed.
+ * Use when you need an infallible schema transformation that does not require
+ * Effect services.
  *
  * **Details**
  *
@@ -360,7 +363,7 @@ export function transformOrFail(options) {
  * @since 3.10.0
  */
 export function transform(options) {
-  return new Transformation(Getter.transform(options.decode), Getter.transform(options.encode));
+  return new Transformation(SchemaGetter.transform(options.decode), SchemaGetter.transform(options.encode));
 }
 /**
  * Creates a `Transformation` where decode and encode operate on `Option`
@@ -368,7 +371,8 @@ export function transform(options) {
  *
  * **When to use**
  *
- * Use when you need to produce or consume `Option.None` to represent absent keys.
+ * Use when you need a schema transformation to produce or consume `Option.None`
+ * for absent keys.
  * - You are working with optional struct fields.
  *
  * **Details**
@@ -404,7 +408,7 @@ export function transform(options) {
  * @since 4.0.0
  */
 export function transformOptional(options) {
-  return new Transformation(Getter.transformOptional(options.decode), Getter.transformOptional(options.encode));
+  return new Transformation(SchemaGetter.transformOptional(options.decode), SchemaGetter.transformOptional(options.encode));
 }
 /**
  * Transforms strings by trimming whitespace on decode.
@@ -412,13 +416,14 @@ export function transformOptional(options) {
  *
  * **When to use**
  *
- * Use to normalize user input by stripping leading/trailing whitespace.
+ * Use when you need a schema transformation to normalize user input by
+ * stripping leading/trailing whitespace.
  *
  * **Details**
  *
- * - Decode: applies `String.prototype.trim()`.
- * - Encode: passthrough (returns the string unchanged).
- * - Not round-trippable if the original had whitespace.
+ * Decoding applies `String.prototype.trim()`. Encoding is passthrough and
+ * returns the string unchanged. This is not round-trippable if the original had
+ * whitespace.
  *
  * **Example** (Trimming on decode)
  *
@@ -438,7 +443,7 @@ export function transformOptional(options) {
  * @since 4.0.0
  */
 export function trim() {
-  return new Transformation(Getter.trim(), Getter.passthrough());
+  return new Transformation(SchemaGetter.trim(), SchemaGetter.passthrough());
 }
 /**
  * Transforms strings by converting snake_case to camelCase
@@ -446,13 +451,14 @@ export function trim() {
  *
  * **When to use**
  *
- * Use to convert API field names between snake_case and camelCase conventions.
+ * Use when you need a schema transformation to convert API field names between
+ * snake_case and camelCase conventions.
  *
  * **Details**
  *
- * - Decode: `"my_field_name"` → `"myFieldName"`.
- * - Encode: `"myFieldName"` → `"my_field_name"`.
- * - Round-trippable for standard snake_case/camelCase.
+ * Decoding converts values such as `"my_field_name"` to `"myFieldName"`.
+ * Encoding converts values such as `"myFieldName"` back to `"my_field_name"`.
+ * The transformation is round-trippable for standard snake_case and camelCase.
  *
  * **Example** (Snake to camel conversion)
  *
@@ -471,7 +477,7 @@ export function trim() {
  * @since 4.0.0
  */
 export function snakeToCamel() {
-  return new Transformation(Getter.snakeToCamel(), Getter.camelToSnake());
+  return new Transformation(SchemaGetter.snakeToCamel(), SchemaGetter.camelToSnake());
 }
 /**
  * Transforms strings by lowercasing on decode.
@@ -479,13 +485,13 @@ export function snakeToCamel() {
  *
  * **When to use**
  *
- * Use to normalize strings to lowercase (e.g. email addresses).
+ * Use when you need a schema transformation to normalize strings to lowercase
+ * (e.g. email addresses).
  *
  * **Details**
  *
- * - Decode: applies `String.prototype.toLowerCase()`.
- * - Encode: passthrough.
- * - Not round-trippable if the original had uppercase characters.
+ * Decoding applies `String.prototype.toLowerCase()`. Encoding is passthrough.
+ * This is not round-trippable if the original had uppercase characters.
  *
  * **Example** (Lowercasing on decode)
  *
@@ -504,7 +510,7 @@ export function snakeToCamel() {
  * @since 4.0.0
  */
 export function toLowerCase() {
-  return new Transformation(Getter.toLowerCase(), Getter.passthrough());
+  return new Transformation(SchemaGetter.toLowerCase(), SchemaGetter.passthrough());
 }
 /**
  * Transforms strings by uppercasing on decode.
@@ -512,13 +518,13 @@ export function toLowerCase() {
  *
  * **When to use**
  *
- * Use to normalize strings to uppercase (e.g. country codes).
+ * Use when you need a schema transformation to normalize strings to uppercase
+ * (e.g. country codes).
  *
  * **Details**
  *
- * - Decode: applies `String.prototype.toUpperCase()`.
- * - Encode: passthrough.
- * - Not round-trippable if the original had lowercase characters.
+ * Decoding applies `String.prototype.toUpperCase()`. Encoding is passthrough.
+ * This is not round-trippable if the original had lowercase characters.
  *
  * **Example** (Uppercasing on decode)
  *
@@ -537,7 +543,7 @@ export function toLowerCase() {
  * @since 4.0.0
  */
 export function toUpperCase() {
-  return new Transformation(Getter.toUpperCase(), Getter.passthrough());
+  return new Transformation(SchemaGetter.toUpperCase(), SchemaGetter.passthrough());
 }
 /**
  * Transforms strings by capitalizing the first character on
@@ -545,12 +551,13 @@ export function toUpperCase() {
  *
  * **When to use**
  *
- * Use to normalize display names or titles.
+ * Use when you need a schema transformation to normalize display names or
+ * titles.
  *
  * **Details**
  *
- * - Decode: uppercases the first character, leaves the rest unchanged.
- * - Encode: passthrough.
+ * Decoding uppercases the first character and leaves the rest unchanged.
+ * Encoding is passthrough.
  *
  * **Example** (Capitalizing on decode)
  *
@@ -569,7 +576,7 @@ export function toUpperCase() {
  * @since 4.0.0
  */
 export function capitalize() {
-  return new Transformation(Getter.capitalize(), Getter.passthrough());
+  return new Transformation(SchemaGetter.capitalize(), SchemaGetter.passthrough());
 }
 /**
  * Transforms strings by lowercasing the first character on
@@ -577,12 +584,13 @@ export function capitalize() {
  *
  * **When to use**
  *
- * Use to normalize identifiers or field names.
+ * Use when you need a schema transformation to normalize identifiers or field
+ * names.
  *
  * **Details**
  *
- * - Decode: lowercases the first character, leaves the rest unchanged.
- * - Encode: passthrough.
+ * Decoding lowercases the first character and leaves the rest unchanged.
+ * Encoding is passthrough.
  *
  * **Example** (Uncapitalizing on decode)
  *
@@ -601,7 +609,7 @@ export function capitalize() {
  * @since 4.0.0
  */
 export function uncapitalize() {
-  return new Transformation(Getter.uncapitalize(), Getter.passthrough());
+  return new Transformation(SchemaGetter.uncapitalize(), SchemaGetter.passthrough());
 }
 /**
  * Transforms a string into a record of key-value pairs and
@@ -609,14 +617,15 @@ export function uncapitalize() {
  *
  * **When to use**
  *
- * Use to parse query-string-like or config-file-like strings into records.
+ * Use when you need a schema transformation to parse query-string-like or
+ * config-file-like strings into records.
  *
  * **Details**
  *
- * - Decode: splits the string by `separator` (default `","`) into pairs,
- *   then splits each pair by `keyValueSeparator` (default `"="`).
- * - Encode: joins the record back into a string using the same separators.
- * - Round-trippable when keys and values don't contain the separators.
+ * Decoding splits the string by `separator` (default `","`) into pairs, then
+ * splits each pair by `keyValueSeparator` (default `"="`). Encoding joins the
+ * record back into a string using the same separators. The transformation is
+ * round-trippable when keys and values do not contain the separators.
  *
  * **Example** (Parsing key-value pairs)
  *
@@ -639,9 +648,9 @@ export function uncapitalize() {
  * @since 4.0.0
  */
 export function splitKeyValue(options) {
-  return new Transformation(Getter.splitKeyValue(options), Getter.joinKeyValue(options));
+  return new Transformation(SchemaGetter.splitKeyValue(options), SchemaGetter.joinKeyValue(options));
 }
-const passthrough_ = /*#__PURE__*/new Transformation(/*#__PURE__*/Getter.passthrough(), /*#__PURE__*/Getter.passthrough());
+const passthrough_ = /*#__PURE__*/new Transformation(/*#__PURE__*/SchemaGetter.passthrough(), /*#__PURE__*/SchemaGetter.passthrough());
 export function passthrough() {
   return passthrough_;
 }
@@ -657,14 +666,15 @@ export function passthroughSubtype() {
  *
  * **When to use**
  *
- * Use to parse numeric strings from APIs, form data, or URL parameters.
+ * Use when you need a schema transformation to parse numeric strings from APIs,
+ * form data, or URL parameters.
  *
  * **Details**
  *
- * - Decode: coerces the string to a number (like `Number(s)`).
- * - Encode: coerces the number to a string (like `String(n)`).
- * - Does not validate that the result is finite — combine with
- *   `Schema.Finite` or `Schema.Int` for stricter checks.
+ * Decoding coerces the string to a number like `Number(s)`. Encoding coerces
+ * the number to a string like `String(n)`. This does not validate that the
+ * result is finite; combine with `Schema.Finite` or `Schema.Int` for stricter
+ * checks.
  *
  * **Example** (Number from string)
  *
@@ -682,20 +692,21 @@ export function passthroughSubtype() {
  * @category Coercions
  * @since 4.0.0
  */
-export const numberFromString = /*#__PURE__*/new Transformation(/*#__PURE__*/Getter.Number(), /*#__PURE__*/Getter.String());
+export const numberFromString = /*#__PURE__*/new Transformation(/*#__PURE__*/SchemaGetter.Number(), /*#__PURE__*/SchemaGetter.String());
 /**
  * Decodes a `string` into a `bigint` and encodes a `bigint` back to a
  * `string`.
  *
  * **When to use**
  *
- * Use to parse large integer strings (e.g. database IDs, blockchain values).
+ * Use when you need a schema transformation to parse large integer strings
+ * (e.g. database IDs, blockchain values).
  *
  * **Details**
  *
- * - Decode: coerces the string to a bigint (like `BigInt(s)`).
- * - Encode: coerces the bigint to a string (like `String(n)`).
- * - Fails on decode if the string is not a valid bigint representation.
+ * Decoding coerces the string to a bigint like `BigInt(s)`. Encoding coerces
+ * the bigint to a string like `String(n)`. Decoding fails if the string is not
+ * a valid bigint representation.
  *
  * **Example** (BigInt from string)
  *
@@ -713,19 +724,20 @@ export const numberFromString = /*#__PURE__*/new Transformation(/*#__PURE__*/Get
  * @category Coercions
  * @since 4.0.0
  */
-export const bigintFromString = /*#__PURE__*/new Transformation(/*#__PURE__*/Getter.BigInt(), /*#__PURE__*/Getter.String());
+export const bigintFromString = /*#__PURE__*/new Transformation(/*#__PURE__*/SchemaGetter.BigInt(), /*#__PURE__*/SchemaGetter.String());
 /**
  * Decodes a `string` into a `Date` and encodes a `Date` back to a `string`.
  *
  * **When to use**
  *
- * Use to parse ISO 8601 date strings from APIs or user input.
+ * Use when you need a schema transformation to parse ISO 8601 date strings from
+ * APIs or user input.
  *
  * **Details**
  *
- * - Decode: creates a `Date` from the string (like `new Date(s)`).
- * - Encode: converts the `Date` to an ISO string (like `date.toISOString()`),
- *   returning `"Invalid Date"` for invalid dates.
+ * Decoding creates a `Date` from the string like `new Date(s)`. Encoding
+ * converts the `Date` to an ISO string like `date.toISOString()`, returning
+ * `"Invalid Date"` for invalid dates.
  *
  * **Example** (Date from string)
  *
@@ -743,21 +755,22 @@ export const bigintFromString = /*#__PURE__*/new Transformation(/*#__PURE__*/Get
  * @category Coercions
  * @since 4.0.0
  */
-export const dateFromString = /*#__PURE__*/new Transformation(/*#__PURE__*/Getter.Date(), /*#__PURE__*/Getter.transform(formatDate));
+export const dateFromString = /*#__PURE__*/new Transformation(/*#__PURE__*/SchemaGetter.Date(), /*#__PURE__*/SchemaGetter.transform(formatDate));
 /**
  * Decodes a `string` into a `Duration` and encodes a `Duration` back to a
  * parseable `string`.
  *
  * **When to use**
  *
- * Use to parse human-readable duration strings from APIs, config, or user input.
+ * Use when you need a schema transformation to parse human-readable duration
+ * strings from APIs, config, or user input.
  *
  * **Details**
  *
- * - Decode: accepts any string that `Duration.fromInput` can parse, including
- *   `"Infinity"` and `"-Infinity"`.
- * - Encode: returns `String(duration)`, producing strings like `"2000 millis"`
- *   or `"10 nanos"` that round-trip through the parser.
+ * Decoding accepts any string that `Duration.fromInput` can parse, including
+ * `"Infinity"` and `"-Infinity"`. Encoding returns `String(duration)`,
+ * producing strings such as `"2000 millis"` or `"10 nanos"` that round-trip
+ * through the parser.
  *
  * **Example** (Duration from string)
  *
@@ -777,7 +790,7 @@ export const dateFromString = /*#__PURE__*/new Transformation(/*#__PURE__*/Gette
  */
 export const durationFromString = /*#__PURE__*/transformOrFail({
   decode: s => Option.match(Duration.fromInput(s), {
-    onNone: () => Effect.fail(new Issue.InvalidValue(Option.some(s), {
+    onNone: () => Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), {
       message: `Invalid Duration string: ${s}`
     })),
     onSome: Effect.succeed
@@ -790,13 +803,14 @@ export const durationFromString = /*#__PURE__*/transformOrFail({
  *
  * **When to use**
  *
- * Use when working with nanosecond-precision timestamps or intervals.
+ * Use when you need a schema transformation for nanosecond-precision timestamps
+ * or intervals.
  *
  * **Details**
  *
- * - Decode: always succeeds, creating a Duration from nanoseconds.
- * - Encode: fails with `InvalidValue` if the Duration cannot be represented
- *   as a `bigint` (e.g. `Duration.infinity`).
+ * Decoding always succeeds and creates a `Duration` from nanoseconds. Encoding
+ * fails with `InvalidValue` if the `Duration` cannot be represented as a
+ * `bigint`, such as `Duration.infinity`.
  *
  * **Example** (Duration from nanoseconds)
  *
@@ -816,7 +830,7 @@ export const durationFromString = /*#__PURE__*/transformOrFail({
 export const durationFromNanos = /*#__PURE__*/transformOrFail({
   decode: i => Effect.succeed(Duration.nanos(i)),
   encode: a => Option.match(Duration.toNanos(a), {
-    onNone: () => Effect.fail(new Issue.InvalidValue(Option.some(a), {
+    onNone: () => Effect.fail(new SchemaIssue.InvalidValue(Option.some(a), {
       message: `Unable to encode ${a} into a bigint`
     })),
     onSome: nanos => Effect.succeed(nanos)
@@ -828,8 +842,8 @@ export const durationFromNanos = /*#__PURE__*/transformOrFail({
  *
  * **When to use**
  *
- * Use when you use this for timeouts, delays, elapsed intervals, or other duration values
- * stored as millisecond counts.
+ * Use when you need a schema transformation to decode timeouts, delays, elapsed
+ * intervals, or other duration values stored as millisecond counts.
  *
  * **Details**
  *
@@ -855,24 +869,63 @@ export const durationFromMillis = /*#__PURE__*/transform({
   decode: i => Duration.millis(i),
   encode: a => Duration.toMillis(a)
 });
-/** @internal */
-export const errorFromErrorJsonEncoded = options => transform({
-  decode: i => {
-    const err = new Error(i.message);
-    if (typeof i.name === "string" && i.name !== "Error") err.name = i.name;
-    if (typeof i.stack === "string") err.stack = i.stack;
-    return err;
-  },
-  encode: a => {
-    const e = {
-      name: a.name,
-      message: a.message
-    };
-    if (options?.includeStack && typeof a.stack === "string") {
-      e.stack = a.stack;
-    }
-    return e;
+const isJsonError = input => Predicate.isObject(input) && typeof input["message"] === "string";
+const decodeJsonError = input => {
+  const hasCause = Object.hasOwn(input, "cause");
+  const err = hasCause ? new Error(input.message, {
+    cause: decodeDefect(input.cause)
+  }) : new Error(input.message);
+  if (typeof input.name === "string" && input.name !== "Error") err.name = input.name;
+  if (typeof input.stack === "string") err.stack = input.stack;
+  return err;
+};
+const encodeUnknownAsJson = input => {
+  try {
+    const json = formatJson(input);
+    return json === undefined ? format(input) : JSON.parse(json);
+  } catch {
+    return format(input);
   }
+};
+const encodeJsonError = (input, options, encodeDefect) => {
+  const encoded = {
+    name: input.name,
+    message: input.message
+  };
+  if (options?.includeStack && typeof input.stack === "string") {
+    encoded.stack = input.stack;
+  }
+  if (!options?.excludeCause && input.cause !== undefined) {
+    encoded.cause = encodeDefect(input.cause);
+  }
+  return encoded;
+};
+const makeEncodeDefect = options => {
+  const seen = new WeakSet();
+  const encode = input => {
+    if (Predicate.isError(input)) {
+      if (seen.has(input)) {
+        return "[Circular]";
+      }
+      seen.add(input);
+      const encoded = encodeJsonError(input, options, encode);
+      seen.delete(input);
+      return encoded;
+    }
+    return encodeUnknownAsJson(input);
+  };
+  return encode;
+};
+const decodeDefect = input => isJsonError(input) ? decodeJsonError(input) : input;
+/** @internal */
+export const errorFromJsonError = options => transform({
+  decode: decodeJsonError,
+  encode: input => makeEncodeDefect(options)(input)
+});
+/** @internal */
+export const defectFromJson = options => transform({
+  decode: decodeDefect,
+  encode: makeEncodeDefect(options)
 });
 /**
  * Decodes `T | null` into `Option<T>` and encodes `Option<T>` back to
@@ -880,13 +933,14 @@ export const errorFromErrorJsonEncoded = options => transform({
  *
  * **When to use**
  *
- * Use to convert nullable API fields to `Option`.
+ * Use when you need a schema transformation to convert nullable API fields to
+ * `Option`.
  *
  * **Details**
  *
- * - Decode: `null` → `Option.none()`, non-null → `Option.some(value)`.
- * - Encode: `Option.none()` → `null`, `Option.some(value)` → `value`.
- * - Pure and synchronous.
+ * Decoding maps `null` to `Option.none()` and non-null values to
+ * `Option.some(value)`. Encoding maps `Option.none()` to `null` and
+ * `Option.some(value)` to `value`. The transformation is pure and synchronous.
  *
  * **Example** (Option from nullable)
  *
@@ -918,13 +972,14 @@ export function optionFromNullOr() {
  *
  * **When to use**
  *
- * Use to convert undefined-or API fields to `Option`.
+ * Use when you need a schema transformation to convert API fields that use
+ * `undefined` for absence to `Option`.
  *
  * **Details**
  *
- * - Decode: `undefined` → `Option.none()`, non-undefined → `Option.some(value)`.
- * - Encode: `Option.none()` → `undefined`, `Option.some(value)` → `value`.
- * - Pure and synchronous.
+ * Decoding maps `undefined` to `Option.none()` and non-undefined values to
+ * `Option.some(value)`. Encoding maps `Option.none()` to `undefined` and
+ * `Option.some(value)` to `value`. The transformation is pure and synchronous.
  *
  * **Example** (Option from undefined-or)
  *
@@ -958,15 +1013,15 @@ export function optionFromUndefinedOr() {
  *
  * **When to use**
  *
- * Use to convert nullish API fields to `Option` when both `null` and
- *   `undefined` represent absence.
+ * Use when you need a schema transformation to convert nullish API fields to
+ * `Option` when both `null` and `undefined` represent absence.
  *
  * **Details**
  *
- * - Decode: `null` or `undefined` → `Option.none()`, otherwise → `Option.some(value)`.
- * - Encode: `Option.none()` → `null` or `undefined` (per `options.onNoneEncoding`),
- *   `Option.some(value)` → `value`.
- * - Pure and synchronous.
+ * Decoding maps `null` and `undefined` to `Option.none()` and all other values
+ * to `Option.some(value)`. Encoding maps `Option.none()` to `null` or
+ * `undefined` according to `options.onNoneEncoding`, and maps
+ * `Option.some(value)` to `value`. The transformation is pure and synchronous.
  *
  * **Example** (Option from nullish, encoding None as null)
  *
@@ -999,14 +1054,15 @@ export function optionFromNullishOr(options) {
  *
  * **When to use**
  *
- * Use to convert optional struct keys (declared with `Schema.optionalKey`) to
- *   `Option` values.
+ * Use when you need a schema transformation to convert optional struct keys
+ * (declared with `Schema.optionalKey`) to `Option` values.
  *
  * **Details**
  *
- * - Decode: absent key (`None`) → `Some(None)`, present key (`Some(v)`) → `Some(Some(v))`.
- * - Encode: `Some(None)` → `None` (omit key), `Some(Some(v))` → `Some(v)`.
- * - Uses `transformOptional` under the hood.
+ * Decoding maps an absent key (`None`) to `Some(None)` and a present key
+ * (`Some(v)`) to `Some(Some(v))`. Encoding maps `Some(None)` to `None` to omit
+ * the key, and maps `Some(Some(v))` to `Some(v)`. This uses
+ * `transformOptional` under the hood.
  *
  * **Example** (Optional key to Option)
  *
@@ -1042,13 +1098,15 @@ export function optionFromOptionalKey() {
  *
  * **When to use**
  *
- * Use to convert optional (possibly `undefined`) values to `Option`.
+ * Use when you need a schema transformation to convert optional (possibly
+ * `undefined`) values to `Option`.
  *
  * **Details**
  *
- * - Decode: absent or `undefined` → `Some(None)`, present → `Some(Some(v))`.
- * - Encode: `Some(None)` → `None` (omit), `Some(Some(v))` → `Some(v)`.
- * - Uses `transformOptional` under the hood; filters out `undefined` on decode.
+ * Decoding maps an absent or `undefined` value to `Some(None)` and a present
+ * value to `Some(Some(v))`. Encoding maps `Some(None)` to `None` to omit the
+ * value, and maps `Some(Some(v))` to `Some(v)`. This uses
+ * `transformOptional` under the hood and filters out `undefined` on decode.
  *
  * **Example** (Optional value to Option)
  *
@@ -1084,13 +1142,13 @@ export function optionFromOptional() {
  *
  * **When to use**
  *
- * Use to parse URL strings from user input or API responses.
+ * Use when you need a schema transformation to parse URL strings from user
+ * input or API responses.
  *
  * **Details**
  *
- * - Decode: calls `new URL(s)`. Fails with `InvalidValue` if the string
- *   is not a valid URL.
- * - Encode: returns `url.href`.
+ * Decoding calls `new URL(s)` and fails with `InvalidValue` if the string is
+ * not a valid URL. Encoding returns `url.href`.
  *
  * **Example** (URL from string)
  *
@@ -1111,7 +1169,7 @@ export function optionFromOptional() {
 export const urlFromString = /*#__PURE__*/transformOrFail({
   decode: s => Effect.try({
     try: () => new URL(s),
-    catch: () => new Issue.InvalidValue(Option.some(s), {
+    catch: () => new SchemaIssue.InvalidValue(Option.some(s), {
       message: `Invalid URL string: ${s}`
     })
   }),
@@ -1123,13 +1181,14 @@ export const urlFromString = /*#__PURE__*/transformOrFail({
  *
  * **When to use**
  *
- * Use to parse decimal number strings from APIs or user input.
+ * Use when you need a schema transformation to parse decimal number strings
+ * from APIs or user input.
  *
  * **Details**
  *
- * - Decode: calls `BigDecimal.fromString(s)`. Fails with `InvalidValue` if the
- *   string is not a valid BigDecimal representation.
- * - Encode: returns `BigDecimal.format(bd)`.
+ * Decoding calls `BigDecimal.fromString(s)` and fails with `InvalidValue` if
+ * the string is not a valid `BigDecimal` representation. Encoding returns
+ * `BigDecimal.format(bd)`.
  *
  * @category transforming
  * @since 4.0.0
@@ -1137,7 +1196,7 @@ export const urlFromString = /*#__PURE__*/transformOrFail({
 export const bigDecimalFromString = /*#__PURE__*/transformOrFail({
   decode: s => {
     const result = BigDecimal.fromString(s);
-    return Option.isNone(result) ? Effect.fail(new Issue.InvalidValue(Option.some(s), {
+    return Option.isNone(result) ? Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), {
       message: `Invalid BigDecimal string: ${s}`
     })) : Effect.succeed(result.value);
   },
@@ -1149,13 +1208,13 @@ export const bigDecimalFromString = /*#__PURE__*/transformOrFail({
  *
  * **When to use**
  *
- * Use when handling binary data transmitted as Base64 strings (e.g. file uploads,
- *   API payloads).
+ * Use when you need a schema transformation for binary data transmitted as
+ * Base64 strings (e.g. file uploads, API payloads).
  *
  * **Details**
  *
- * - Decode: parses the Base64 string into bytes.
- * - Encode: encodes the byte array as a Base64 string.
+ * Decoding parses the Base64 string into bytes. Encoding writes the byte array
+ * as a Base64 string.
  *
  * **Example** (Uint8Array from Base64)
  *
@@ -1173,19 +1232,20 @@ export const bigDecimalFromString = /*#__PURE__*/transformOrFail({
  * @category encoding
  * @since 4.0.0
  */
-export const uint8ArrayFromBase64String = /*#__PURE__*/new Transformation(/*#__PURE__*/Getter.decodeBase64(), /*#__PURE__*/Getter.encodeBase64());
+export const uint8ArrayFromBase64String = /*#__PURE__*/new Transformation(/*#__PURE__*/SchemaGetter.decodeBase64(), /*#__PURE__*/SchemaGetter.encodeBase64());
 /**
  * Decodes a Base64-encoded `string` into a UTF-8 `string` and encodes a
  * UTF-8 `string` back to a Base64 string.
  *
  * **When to use**
  *
- * Use when handling text data transmitted as Base64 strings.
+ * Use when you need a schema transformation for text data transmitted as Base64
+ * strings.
  *
  * **Details**
  *
- * - Decode: parses the Base64 string into a UTF-8 string.
- * - Encode: encodes the string as a Base64 string.
+ * Decoding parses the Base64 string into a UTF-8 string. Encoding writes the
+ * string as a Base64 string.
  *
  * **Example** (String from Base64)
  *
@@ -1203,18 +1263,19 @@ export const uint8ArrayFromBase64String = /*#__PURE__*/new Transformation(/*#__P
  * @category encoding
  * @since 4.0.0
  */
-export const stringFromBase64String = /*#__PURE__*/new Transformation(/*#__PURE__*/Getter.decodeBase64String(), /*#__PURE__*/Getter.encodeBase64());
+export const stringFromBase64String = /*#__PURE__*/new Transformation(/*#__PURE__*/SchemaGetter.decodeBase64String(), /*#__PURE__*/SchemaGetter.encodeBase64());
 /**
  * Decodes a base64 (URL) encoded `string` into a UTF-8 `string` and encodes it back.
  *
  * **When to use**
  *
- * Use when handling text data transmitted as Base64 URL-safe strings.
+ * Use when you need a schema transformation for text data transmitted as Base64
+ * URL-safe strings.
  *
  * **Details**
  *
- * - Decode: parses the Base64 URL string into a UTF-8 string.
- * - Encode: encodes the string as a Base64 URL string.
+ * Decoding parses the Base64 URL string into a UTF-8 string. Encoding writes
+ * the string as a Base64 URL string.
  *
  * **Example** (String from Base64Url)
  *
@@ -1232,18 +1293,19 @@ export const stringFromBase64String = /*#__PURE__*/new Transformation(/*#__PURE_
  * @category encoding
  * @since 4.0.0
  */
-export const stringFromBase64UrlString = /*#__PURE__*/new Transformation(/*#__PURE__*/Getter.decodeBase64UrlString(), /*#__PURE__*/Getter.encodeBase64Url());
+export const stringFromBase64UrlString = /*#__PURE__*/new Transformation(/*#__PURE__*/SchemaGetter.decodeBase64UrlString(), /*#__PURE__*/SchemaGetter.encodeBase64Url());
 /**
  * Decodes a hex encoded `string` into a UTF-8 `string` and encodes it back.
  *
  * **When to use**
  *
- * Use when handling text data transmitted as hexadecimal strings.
+ * Use when you need a schema transformation for text data transmitted as
+ * hexadecimal strings.
  *
  * **Details**
  *
- * - Decode: parses the hex string into a UTF-8 string.
- * - Encode: encodes the string as a hex string.
+ * Decoding parses the hex string into a UTF-8 string. Encoding writes the
+ * string as a hex string.
  *
  * **Example** (String from Hex)
  *
@@ -1261,21 +1323,21 @@ export const stringFromBase64UrlString = /*#__PURE__*/new Transformation(/*#__PU
  * @category encoding
  * @since 4.0.0
  */
-export const stringFromHexString = /*#__PURE__*/new Transformation(/*#__PURE__*/Getter.decodeHexString(), /*#__PURE__*/Getter.encodeHex());
+export const stringFromHexString = /*#__PURE__*/new Transformation(/*#__PURE__*/SchemaGetter.decodeHexString(), /*#__PURE__*/SchemaGetter.encodeHex());
 /**
  * Decodes a URI component encoded string into a UTF-8 string and encodes a
  * UTF-8 string into a URI component encoded string.
  *
  * **When to use**
  *
- * Use when storing structured data in URL query parameters or fragments.
- * - Composing with `Schema.parseJson` to round-trip JSON through a URL.
+ * Use when you need a schema transformation to store structured data in URL
+ * query parameters or fragments, such as composing with `Schema.parseJson` to
+ * round-trip JSON through a URL.
  *
  * **Details**
  *
- * - Decode: calls `decodeURIComponent`. Fails if the input contains malformed
- *   percent-encoding sequences.
- * - Encode: calls `encodeURIComponent`.
+ * Decoding calls `decodeURIComponent` and fails if the input contains malformed
+ * percent-encoding sequences. Encoding calls `encodeURIComponent`.
  *
  * **Example** (URI component schema)
  *
@@ -1293,15 +1355,16 @@ export const stringFromHexString = /*#__PURE__*/new Transformation(/*#__PURE__*/
  * @category encoding
  * @since 4.0.0
  */
-export const stringFromUriComponent = /*#__PURE__*/new Transformation(/*#__PURE__*/Getter.decodeUriComponent(), /*#__PURE__*/Getter.encodeUriComponent());
+export const stringFromUriComponent = /*#__PURE__*/new Transformation(/*#__PURE__*/SchemaGetter.decodeUriComponent(), /*#__PURE__*/SchemaGetter.encodeUriComponent());
 /**
  * Decodes a JSON string with `JSON.parse` and encodes a value with
  * `JSON.stringify`.
  *
  * **When to use**
  *
- * Use when you use this for JSON stored or transmitted as a string, usually before composing
- * with another schema that validates the parsed structure.
+ * Use when you need a schema transformation to decode JSON stored or
+ * transmitted as a string, usually before composing with another schema that
+ * validates the parsed structure.
  *
  * **Details**
  *
@@ -1324,15 +1387,15 @@ export const stringFromUriComponent = /*#__PURE__*/new Transformation(/*#__PURE_
  * @category decoding
  * @since 4.0.0
  */
-export const fromJsonString = /*#__PURE__*/new Transformation(/*#__PURE__*/Getter.parseJson(), /*#__PURE__*/Getter.stringifyJson());
+export const fromJsonString = /*#__PURE__*/new Transformation(/*#__PURE__*/SchemaGetter.parseJson(), /*#__PURE__*/SchemaGetter.stringifyJson());
 /**
  * Decodes a `FormData` instance into a nested record using bracket-path keys and
  * encodes object-like values back into `FormData`.
  *
  * **When to use**
  *
- * Use when you use this for form or multipart payloads where keys such as `user[name]` or
- * `items[0]` should become nested data.
+ * Use when you need a schema transformation for form or multipart payloads
+ * whose keys, such as `user[name]` or `items[0]`, should become nested data.
  *
  * **Details**
  *
@@ -1356,15 +1419,15 @@ export const fromJsonString = /*#__PURE__*/new Transformation(/*#__PURE__*/Gette
  * @category decoding
  * @since 4.0.0
  */
-export const fromFormData = /*#__PURE__*/new Transformation(/*#__PURE__*/Getter.decodeFormData(), /*#__PURE__*/Getter.encodeFormData());
+export const fromFormData = /*#__PURE__*/new Transformation(/*#__PURE__*/SchemaGetter.decodeFormData(), /*#__PURE__*/SchemaGetter.encodeFormData());
 /**
  * Decodes `URLSearchParams` into a nested record using bracket-path keys and
  * encodes object-like values back into `URLSearchParams`.
  *
  * **When to use**
  *
- * Use when you use this for query strings where keys such as `filter[name]` or `items[0]`
- * should become nested data.
+ * Use when you need a schema transformation for query strings whose keys, such
+ * as `filter[name]` or `items[0]`, should become nested data.
  *
  * **Details**
  *
@@ -1388,15 +1451,15 @@ export const fromFormData = /*#__PURE__*/new Transformation(/*#__PURE__*/Getter.
  * @category decoding
  * @since 4.0.0
  */
-export const fromURLSearchParams = /*#__PURE__*/new Transformation(/*#__PURE__*/Getter.decodeURLSearchParams(), /*#__PURE__*/Getter.encodeURLSearchParams());
+export const fromURLSearchParams = /*#__PURE__*/new Transformation(/*#__PURE__*/SchemaGetter.decodeURLSearchParams(), /*#__PURE__*/SchemaGetter.encodeURLSearchParams());
 /**
  * Decodes a numeric time-zone offset in milliseconds into a
  * `DateTime.TimeZone.Offset` and encodes it back to the offset number.
  *
  * **When to use**
  *
- * Use to represent fixed-offset time zones with numeric millisecond offsets in
- * schema transformations or JSON codecs.
+ * Use when you need a schema transformation to represent fixed-offset time
+ * zones with numeric millisecond offsets.
  *
  * **Details**
  *
@@ -1419,8 +1482,8 @@ export const timeZoneOffsetFromNumber = /*#__PURE__*/transform({
  *
  * **When to use**
  *
- * Use when a schema transformation should accept only IANA time-zone identifier
- * strings and produce `DateTime.TimeZone.Named` values.
+ * Use when you need a schema transformation to accept only IANA time-zone
+ * identifier strings and produce `DateTime.TimeZone.Named` values.
  *
  * **Details**
  *
@@ -1435,7 +1498,7 @@ export const timeZoneOffsetFromNumber = /*#__PURE__*/transform({
 export const timeZoneNamedFromString = /*#__PURE__*/transformOrFail({
   decode: s => {
     return Option.match(DateTime.zoneMakeNamed(s), {
-      onNone: () => Effect.fail(new Issue.InvalidValue(Option.some(s), {
+      onNone: () => Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), {
         message: `Invalid IANA time zone: ${s}`
       })),
       onSome: Effect.succeed
@@ -1449,8 +1512,8 @@ export const timeZoneNamedFromString = /*#__PURE__*/transformOrFail({
  *
  * **When to use**
  *
- * Use when schema decoding should accept either an IANA time-zone identifier or
- * an offset string and produce a general `DateTime.TimeZone`.
+ * Use when you need a schema transformation to accept either an IANA time-zone
+ * identifier or an offset string and produce a general `DateTime.TimeZone`.
  *
  * **Details**
  *
@@ -1467,7 +1530,7 @@ export const timeZoneNamedFromString = /*#__PURE__*/transformOrFail({
 export const timeZoneFromString = /*#__PURE__*/transformOrFail({
   decode: s => {
     return Option.match(DateTime.zoneFromString(s), {
-      onNone: () => Effect.fail(new Issue.InvalidValue(Option.some(s), {
+      onNone: () => Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), {
         message: `Invalid time zone: ${s}`
       })),
       onSome: Effect.succeed
@@ -1481,8 +1544,8 @@ export const timeZoneFromString = /*#__PURE__*/transformOrFail({
  *
  * **When to use**
  *
- * Use to decode date-time strings when the schema value should be a normalized
- * `DateTime.Utc` and encode back as a UTC ISO string.
+ * Use when you need a schema transformation to decode date-time strings to a
+ * normalized `DateTime.Utc` and encode back as a UTC ISO string.
  *
  * **Details**
  *
@@ -1499,7 +1562,7 @@ export const timeZoneFromString = /*#__PURE__*/transformOrFail({
 export const dateTimeUtcFromString = /*#__PURE__*/transformOrFail({
   decode: s => {
     return Option.match(DateTime.make(s), {
-      onNone: () => Effect.fail(new Issue.InvalidValue(Option.some(s), {
+      onNone: () => Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), {
         message: `Invalid UTC DateTime string: ${s}`
       })),
       onSome: result => Effect.succeed(DateTime.toUtc(result))
@@ -1513,8 +1576,8 @@ export const dateTimeUtcFromString = /*#__PURE__*/transformOrFail({
  *
  * **When to use**
  *
- * Use to define a schema transformation for ISO zoned date-time strings that
- * decode to `DateTime.Zoned` and encode with `DateTime.formatIsoZoned`.
+ * Use when you need a schema transformation for ISO zoned date-time strings
+ * that decode to `DateTime.Zoned` and encode with `DateTime.formatIsoZoned`.
  *
  * **Details**
  *
@@ -1530,7 +1593,7 @@ export const dateTimeUtcFromString = /*#__PURE__*/transformOrFail({
 export const dateTimeZonedFromString = /*#__PURE__*/transformOrFail({
   decode: s => {
     return Option.match(DateTime.makeZonedFromString(s), {
-      onNone: () => Effect.fail(new Issue.InvalidValue(Option.some(s), {
+      onNone: () => Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), {
         message: `Invalid Zoned DateTime string: ${s}`
       })),
       onSome: Effect.succeed