effect 4.0.0-beta.74 → 4.0.0-beta.75

package/dist/SchemaTransformation.d.ts

@@ -89,18 +89,18 @@ import * as DateTime from "./DateTime.ts";
 import * as Duration from "./Duration.ts";
 import * as Effect from "./Effect.ts";
 import * as Option from "./Option.ts";
-import type * as AST from "./SchemaAST.ts";
-import * as Getter from "./SchemaGetter.ts";
-import * as Issue from "./SchemaIssue.ts";
+import type * as SchemaAST from "./SchemaAST.ts";
+import * as SchemaGetter from "./SchemaGetter.ts";
+import * as SchemaIssue from "./SchemaIssue.ts";
 /**
  * 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**
  *
@@ -136,9 +136,9 @@ import * as Issue from "./SchemaIssue.ts";
  */
 export declare class Middleware<in out T, in out E, RDE, RDT, RET, REE> {
     readonly _tag = "Middleware";
-    readonly decode: (effect: Effect.Effect<Option.Option<E>, Issue.Issue, RDE>, options: AST.ParseOptions) => Effect.Effect<Option.Option<T>, Issue.Issue, RDT>;
-    readonly encode: (effect: Effect.Effect<Option.Option<T>, Issue.Issue, RET>, options: AST.ParseOptions) => Effect.Effect<Option.Option<E>, Issue.Issue, REE>;
-    constructor(decode: (effect: Effect.Effect<Option.Option<E>, Issue.Issue, RDE>, options: AST.ParseOptions) => Effect.Effect<Option.Option<T>, Issue.Issue, RDT>, encode: (effect: Effect.Effect<Option.Option<T>, Issue.Issue, RET>, options: AST.ParseOptions) => Effect.Effect<Option.Option<E>, Issue.Issue, REE>);
+    readonly decode: (effect: Effect.Effect<Option.Option<E>, SchemaIssue.Issue, RDE>, options: SchemaAST.ParseOptions) => Effect.Effect<Option.Option<T>, SchemaIssue.Issue, RDT>;
+    readonly encode: (effect: Effect.Effect<Option.Option<T>, SchemaIssue.Issue, RET>, options: SchemaAST.ParseOptions) => Effect.Effect<Option.Option<E>, SchemaIssue.Issue, REE>;
+    constructor(decode: (effect: Effect.Effect<Option.Option<E>, SchemaIssue.Issue, RDE>, options: SchemaAST.ParseOptions) => Effect.Effect<Option.Option<T>, SchemaIssue.Issue, RDT>, encode: (effect: Effect.Effect<Option.Option<T>, SchemaIssue.Issue, RET>, options: SchemaAST.ParseOptions) => Effect.Effect<Option.Option<E>, SchemaIssue.Issue, REE>);
     flip(): Middleware<E, T, RET, REE, RDE, RDT>;
 }
 declare const TypeId = "~effect/SchemaTransformation/Transformation";
@@ -148,7 +148,8 @@ declare 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.
  *
@@ -186,9 +187,9 @@ declare const TypeId = "~effect/SchemaTransformation/Transformation";
 export declare class Transformation<in out T, in out E, RD = never, RE = never> {
     readonly [TypeId] = "~effect/SchemaTransformation/Transformation";
     readonly _tag = "Transformation";
-    readonly decode: Getter.Getter<T, E, RD>;
-    readonly encode: Getter.Getter<E, T, RE>;
-    constructor(decode: Getter.Getter<T, E, RD>, encode: Getter.Getter<E, T, RE>);
+    readonly decode: SchemaGetter.Getter<T, E, RD>;
+    readonly encode: SchemaGetter.Getter<E, T, RE>;
+    constructor(decode: SchemaGetter.Getter<T, E, RD>, encode: SchemaGetter.Getter<E, T, RE>);
     flip(): Transformation<E, T, RE, RD>;
     compose<T2, RD2, RE2>(other: Transformation<T2, T, RD2, RE2>): Transformation<T2, E, RD | RD2, RE | RE2>;
 }
@@ -197,7 +198,8 @@ export declare class Transformation<in out T, in out E, RD = never, RE = never>
  *
  * **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**
  *
@@ -229,7 +231,8 @@ export declare function isTransformation(u: unknown): u is Transformation<any, a
  *
  * **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**
@@ -255,8 +258,8 @@ export declare function isTransformation(u: unknown): u is Transformation<any, a
  * @since 3.10.0
  */
 export declare const make: <T, E, RD = never, RE = never>(options: {
-    readonly decode: Getter.Getter<T, E, RD>;
-    readonly encode: Getter.Getter<E, T, RE>;
+    readonly decode: SchemaGetter.Getter<T, E, RD>;
+    readonly encode: SchemaGetter.Getter<E, T, RE>;
 }) => Transformation<T, E, RD, RE>;
 /**
  * Creates a `Transformation` from effectful decode and encode functions that
@@ -264,8 +267,8 @@ export declare const make: <T, E, RD = never, RE = never>(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**
  *
@@ -302,8 +305,8 @@ export declare const make: <T, E, RD = never, RE = never>(options: {
  * @since 3.10.0
  */
 export declare function transformOrFail<T, E, RD = never, RE = never>(options: {
-    readonly decode: (e: E, options: AST.ParseOptions) => Effect.Effect<T, Issue.Issue, RD>;
-    readonly encode: (t: T, options: AST.ParseOptions) => Effect.Effect<E, Issue.Issue, RE>;
+    readonly decode: (e: E, options: SchemaAST.ParseOptions) => Effect.Effect<T, SchemaIssue.Issue, RD>;
+    readonly encode: (t: T, options: SchemaAST.ParseOptions) => Effect.Effect<E, SchemaIssue.Issue, RE>;
 }): Transformation<T, E, RD, RE>;
 /**
  * Creates a `Transformation` from pure (sync, infallible) decode and encode
@@ -311,8 +314,8 @@ export declare function transformOrFail<T, E, RD = never, RE = never>(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**
  *
@@ -353,7 +356,8 @@ export declare function transform<T, E>(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**
@@ -398,13 +402,14 @@ export declare function transformOptional<T, E>(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)
  *
@@ -430,13 +435,14 @@ export declare function trim(): Transformation<string, string>;
  *
  * **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)
  *
@@ -461,13 +467,13 @@ export declare function snakeToCamel(): Transformation<string, string>;
  *
  * **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)
  *
@@ -492,13 +498,13 @@ export declare function toLowerCase(): Transformation<string, string>;
  *
  * **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)
  *
@@ -523,12 +529,13 @@ export declare function toUpperCase(): Transformation<string, string>;
  *
  * **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)
  *
@@ -553,12 +560,13 @@ export declare function capitalize(): Transformation<string, string>;
  *
  * **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)
  *
@@ -583,14 +591,15 @@ export declare function uncapitalize(): Transformation<string, string>;
  *
  * **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)
  *
@@ -622,9 +631,8 @@ export declare function splitKeyValue(options?: {
  *
  * **When to use**
  *
- * Use when connecting two schemas that share the same type with no conversion.
- * - As a placeholder when `Schema.decodeTo` requires a transformation but
- *   no actual conversion is needed.
+ * Use when you need a schema transformation to connect two schemas that share
+ * the same type with no actual conversion.
  *
  * **Details**
  *
@@ -660,7 +668,7 @@ export declare function passthrough<T>(): Transformation<T, T>;
  *
  * **When to use**
  *
- * Use when the runtime value is unchanged but the decoded side should be
+ * Use when you need a no-op schema transformation whose decoded side is
  * narrower than the encoded side.
  *
  * **Details**
@@ -689,7 +697,8 @@ export declare function passthroughSupertype<T extends E, E>(): Transformation<T
  *
  * **When to use**
  *
- * Use when narrowing: the encoded side is more specific than the decoded side.
+ * Use when you need a no-op schema transformation whose encoded side is more
+ * specific than its decoded side.
  *
  * **Details**
  *
@@ -717,14 +726,15 @@ export declare function passthroughSubtype<T, E extends T>(): Transformation<T,
  *
  * **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)
  *
@@ -749,13 +759,14 @@ export declare const numberFromString: Transformation<number, string, never, nev
  *
  * **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)
  *
@@ -779,13 +790,14 @@ export declare const bigintFromString: Transformation<bigint, string, never, nev
  *
  * **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)
  *
@@ -810,14 +822,15 @@ export declare const dateFromString: Transformation<globalThis.Date, 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)
  *
@@ -842,13 +855,14 @@ export declare const durationFromString: Transformation<Duration.Duration, strin
  *
  * **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)
  *
@@ -872,8 +886,8 @@ export declare const durationFromNanos: Transformation<Duration.Duration, bigint
  *
  * **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**
  *
@@ -902,13 +916,14 @@ export declare const durationFromMillis: Transformation<Duration.Duration, numbe
  *
  * **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)
  *
@@ -935,13 +950,14 @@ export declare function optionFromNullOr<T>(): Transformation<Option.Option<T>,
  *
  * **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)
  *
@@ -970,15 +986,15 @@ export declare function optionFromUndefinedOr<T>(): Transformation<Option.Option
  *
  * **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)
  *
@@ -1008,14 +1024,15 @@ export declare function optionFromNullishOr<T>(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)
  *
@@ -1046,13 +1063,15 @@ export declare function optionFromOptionalKey<T>(): Transformation<Option.Option
  *
  * **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)
  *
@@ -1083,13 +1102,13 @@ export declare function optionFromOptional<T>(): Transformation<Option.Option<T>
  *
  * **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)
  *
@@ -1114,13 +1133,14 @@ export declare const urlFromString: Transformation<URL, string>;
  *
  * **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
@@ -1132,13 +1152,13 @@ export declare const bigDecimalFromString: Transformation<BigDecimal.BigDecimal,
  *
  * **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)
  *
@@ -1163,12 +1183,13 @@ export declare const uint8ArrayFromBase64String: Transformation<Uint8Array<Array
  *
  * **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)
  *
@@ -1192,12 +1213,13 @@ export declare const stringFromBase64String: Transformation<string, string>;
  *
  * **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)
  *
@@ -1221,12 +1243,13 @@ export declare const stringFromBase64UrlString: Transformation<string, string>;
  *
  * **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)
  *
@@ -1251,14 +1274,14 @@ export declare const stringFromHexString: Transformation<string, 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)
  *
@@ -1283,8 +1306,9 @@ export declare const stringFromUriComponent: Transformation<string, string>;
  *
  * **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**
  *
@@ -1314,8 +1338,8 @@ export declare const fromJsonString: Transformation<unknown, string, never, neve
  *
  * **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**
  *
@@ -1346,8 +1370,8 @@ export declare const fromFormData: Transformation<unknown, FormData, never, neve
  *
  * **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**
  *
@@ -1378,8 +1402,8 @@ export declare const fromURLSearchParams: Transformation<unknown, URLSearchParam
  *
  * **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**
  *
@@ -1399,8 +1423,8 @@ export declare const timeZoneOffsetFromNumber: Transformation<DateTime.TimeZone.
  *
  * **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**
  *
@@ -1419,8 +1443,8 @@ export declare const timeZoneNamedFromString: Transformation<DateTime.TimeZone.N
  *
  * **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**
  *
@@ -1441,8 +1465,8 @@ export declare const timeZoneFromString: Transformation<DateTime.TimeZone, strin
  *
  * **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**
  *
@@ -1463,8 +1487,8 @@ export declare const dateTimeUtcFromString: Transformation<DateTime.Utc, string>
  *
  * **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**
  *