effect 4.0.0-beta.73 → 4.0.0-beta.75

package/dist/SchemaGetter.d.ts

@@ -90,26 +90,26 @@ import * as Effect from "./Effect.ts";
 import * as Option from "./Option.ts";
 import * as Pipeable from "./Pipeable.ts";
 import type * as Schema from "./Schema.ts";
-import type * as AST from "./SchemaAST.ts";
-import * as Issue from "./SchemaIssue.ts";
+import type * as SchemaAST from "./SchemaAST.ts";
+import * as SchemaIssue from "./SchemaIssue.ts";
 /**
  * Represents a composable transformation from an encoded type `E` to a decoded type `T`.
  *
  * **When to use**
  *
- * Use to build custom schema transformations with `Schema.decodeTo` or `Schema.decode`.
- * - Composing multiple transformation steps into a single getter.
+ * Use when you need a schema getter to build and compose custom transformations
+ * for `Schema.decodeTo` or `Schema.decode`.
  *
  * **Details**
  *
- * - A getter wraps a function `Option<E> -> Effect<Option<T>, Issue, R>`.
- * - Receives `Option.None` when the encoded key is absent (e.g. missing struct field).
- * - Returns `Option.None` to omit the value from the decoded output.
- * - Fails with `Issue` on invalid input.
- * - May require Effect services via `R`.
- * - `.map(f)` applies `f` to the decoded value (inside the `Some`), leaving `None` unchanged.
- * - `.compose(other)` chains two getters: the output of `this` feeds into `other`.
- *   Passthrough getters on either side are optimized away.
+ * A getter wraps a function `Option<E> -> Effect<Option<T>, Issue, R>`. It
+ * receives `Option.None` when the encoded key is absent, such as a missing
+ * struct field, and returns `Option.None` to omit the value from the decoded
+ * output. It fails with `Issue` on invalid input and may require Effect
+ * services via `R`. `.map(f)` applies `f` to the decoded value inside `Some`
+ * while leaving `None` unchanged. `.compose(other)` chains two getters by
+ * feeding the output of `this` into `other`; passthrough getters on either side
+ * are optimized away.
  *
  * **Example** (Creating and composing getters)
  *
@@ -130,8 +130,8 @@ import * as Issue from "./SchemaIssue.ts";
  * @since 4.0.0
  */
 export declare class Getter<out T, in E, R = never> extends Pipeable.Class {
-    readonly run: (input: Option.Option<E>, options: AST.ParseOptions) => Effect.Effect<Option.Option<T>, Issue.Issue, R>;
-    constructor(run: (input: Option.Option<E>, options: AST.ParseOptions) => Effect.Effect<Option.Option<T>, Issue.Issue, R>);
+    readonly run: (input: Option.Option<E>, options: SchemaAST.ParseOptions) => Effect.Effect<Option.Option<T>, SchemaIssue.Issue, R>;
+    constructor(run: (input: Option.Option<E>, options: SchemaAST.ParseOptions) => Effect.Effect<Option.Option<T>, SchemaIssue.Issue, R>);
     map<T2>(f: (t: T) => T2): Getter<T2, E, R>;
     compose<T2, R2>(other: Getter<T2, T, R2>): Getter<T2, E, R | R2>;
 }
@@ -140,13 +140,13 @@ export declare class Getter<out T, in E, R = never> extends Pipeable.Class {
  *
  * **When to use**
  *
- * Use when a schema field should always decode to a fixed value.
- * - You need a placeholder getter that produces a known default.
+ * Use when you need a schema getter that always decodes a field to a fixed
+ * value.
  *
  * **Details**
  *
- * - Pure, no side effects.
- * - Always returns `Option.some(t)` regardless of whether input is `Some` or `None`.
+ * The getter is pure and always returns `Option.some(t)` regardless of whether
+ * the input is `Some` or `None`.
  *
  * **Example** (Constant getter)
  *
@@ -169,7 +169,7 @@ export declare function succeed<const T, E>(t: T): Getter<T, E>;
  *
  * **When to use**
  *
- * Use when a transformation should unconditionally reject input.
+ * Use when you need a schema getter that unconditionally rejects input.
  * - Building custom validation getters that produce specific error types.
  *
  * **Details**
@@ -193,18 +193,19 @@ export declare function succeed<const T, E>(t: T): Getter<T, E>;
  * @category constructors
  * @since 4.0.0
  */
-export declare function fail<T, E>(f: (oe: Option.Option<E>) => Issue.Issue): Getter<T, E>;
+export declare function fail<T, E>(f: (oe: Option.Option<E>) => SchemaIssue.Issue): Getter<T, E>;
 /**
  * Creates a getter that always fails with a `Forbidden` issue.
  *
  * **When to use**
  *
- * Use when a field or direction (encode/decode) should be disallowed entirely.
+ * Use when you need a schema getter to disallow a field or direction
+ * (encode/decode) entirely.
  * - You want a clear "forbidden" error message in schema validation output.
  *
  * **Details**
  *
- * - Always fails with `Issue.Forbidden`.
+ * - Always fails with `SchemaIssue.Forbidden`.
  * - The message function receives the `Option<E>` input for context.
  *
  * **Example** (Forbidding a decode direction)
@@ -228,8 +229,8 @@ export declare function forbidden<T, E>(message: (oe: Option.Option<E>) => strin
  *
  * **When to use**
  *
- * Use when no transformation is needed between encoded and decoded types.
- * - One side of a `decodeTo` pair (encode or decode) should be a no-op.
+ * Use when you need a schema getter for one side of a `decodeTo` pair, either
+ * encode or decode, to pass values through unchanged.
  *
  * **Details**
  *
@@ -268,9 +269,8 @@ export declare function passthrough<T>(): Getter<T, T>;
  *
  * **When to use**
  *
- * Use when no runtime conversion is needed but the getter should be typed
- * as producing a decoded/output type that is narrower than the encoded/input
- * type.
+ * Use when you need a schema getter that passes values through when the
+ * decoded/output type is narrower than the encoded/input type.
  *
  * **Details**
  *
@@ -297,8 +297,8 @@ export declare function passthroughSupertype<T extends E, E>(): Getter<T, E>;
  *
  * **When to use**
  *
- * Use when the encoded type is narrower than the decoded type.
- * - You need type-safe passthrough without `{ strict: false }`.
+ * Use when you need a schema getter that passes values through without
+ * `{ strict: false }` for an encoded type that narrows the decoded type.
  *
  * **Details**
  *
@@ -325,7 +325,8 @@ export declare function passthroughSubtype<T, E extends T>(): Getter<T, E>;
  *
  * **When to use**
  *
- * Use when you need to provide a fallback or computed value for missing struct keys.
+ * Use when you need a schema getter to provide a fallback or computed value for
+ * missing struct keys.
  * - Building custom "default value" logic more complex than {@link withDefault}.
  *
  * **Details**
@@ -351,18 +352,18 @@ export declare function passthroughSubtype<T, E extends T>(): Getter<T, E>;
  * @category constructors
  * @since 4.0.0
  */
-export declare function onNone<T, E extends T = T, R = never>(f: (options: AST.ParseOptions) => Effect.Effect<Option.Option<T>, Issue.Issue, R>): Getter<T, E, R>;
+export declare function onNone<T, E extends T = T, R = never>(f: (options: SchemaAST.ParseOptions) => Effect.Effect<Option.Option<T>, SchemaIssue.Issue, R>): Getter<T, E, R>;
 /**
  * Creates a getter that fails with `MissingKey` if the input is absent (`Option.None`).
  *
  * **When to use**
  *
- * Use when a struct field must be present in the encoded input.
- * - You want schema validation to report a missing key error.
+ * Use when you need a schema getter to require a struct field in the encoded
+ * input and report a missing key error when it is absent.
  *
  * **Details**
  *
- * - When input is `None`, fails with `Issue.MissingKey`.
+ * - When input is `None`, fails with `SchemaIssue.MissingKey`.
  * - When input is `Some`, passes it through unchanged.
  * - Optional `annotations` customize the error message for the missing key.
  *
@@ -386,7 +387,8 @@ export declare function required<T, E extends T = T>(annotations?: Schema.Annota
  *
  * **When to use**
  *
- * Use when you need to transform or validate only when a value is present.
+ * Use when you need a schema getter to transform or validate only when a field
+ * value is present.
  * - Missing keys should remain absent in the output.
  *
  * **Details**
@@ -412,13 +414,14 @@ export declare function required<T, E extends T = T>(annotations?: Schema.Annota
  * @category constructors
  * @since 4.0.0
  */
-export declare function onSome<T, E, R = never>(f: (e: E, options: AST.ParseOptions) => Effect.Effect<Option.Option<T>, Issue.Issue, R>): Getter<T, E, R>;
+export declare function onSome<T, E, R = never>(f: (e: E, options: SchemaAST.ParseOptions) => Effect.Effect<Option.Option<T>, SchemaIssue.Issue, R>): Getter<T, E, R>;
 /**
  * Creates a getter that validates a value using an effectful check function.
  *
  * **When to use**
  *
- * Use when you need to validate a decoded value (e.g. check a constraint or call an external service).
+ * Use when you need a schema getter to validate a decoded value (e.g. check a
+ * constraint or call an external service).
  * - The validation may be asynchronous or require Effect services.
  *
  * **Details**
@@ -429,7 +432,7 @@ export declare function onSome<T, E, R = never>(f: (e: E, options: AST.ParseOpti
  *   - `false` or a `string` — value is invalid, fails with an `Issue`.
  *   - An `Issue` object — fails with that issue directly.
  *   - `{ path, issue }` — fails with a nested path issue (`issue` may be a
- *     message string or a full {@link Issue.Issue}).
+ *     message string or a full {@link SchemaIssue.Issue}).
  * - Does not transform the value — input and output types are the same.
  *
  * **Example** (Effectful validation)
@@ -448,13 +451,14 @@ export declare function onSome<T, E, R = never>(f: (e: E, options: AST.ParseOpti
  * @category constructors
  * @since 4.0.0
  */
-export declare function checkEffect<T, R = never>(f: (input: T, options: AST.ParseOptions) => Effect.Effect<undefined | boolean | Schema.FilterIssue, never, R>): Getter<T, T, R>;
+export declare function checkEffect<T, R = never>(f: (input: T, options: SchemaAST.ParseOptions) => Effect.Effect<undefined | boolean | Schema.FilterIssue, never, R>): Getter<T, T, R>;
 /**
  * Creates a getter that applies a pure function to present values.
  *
  * **When to use**
  *
- * Use when you have a pure, infallible transformation between types.
+ * Use when you need a schema getter for a pure, infallible transformation
+ * between types.
  * - Building encode/decode pairs for `Schema.decodeTo`.
  *
  * **Details**
@@ -490,8 +494,8 @@ export declare function transform<T, E>(f: (e: E) => T): Getter<T, E>;
  *
  * **When to use**
  *
- * Use when the transformation may fail (e.g. parsing, validation).
- * - The transformation needs Effect services or is async.
+ * Use when you need a schema getter for a transformation that may fail, require
+ * Effect services, or run asynchronously.
  *
  * **Details**
  *
@@ -520,19 +524,19 @@ export declare function transform<T, E>(f: (e: E) => T): Getter<T, E>;
  * @category constructors
  * @since 4.0.0
  */
-export declare function transformOrFail<T, E, R = never>(f: (e: E, options: AST.ParseOptions) => Effect.Effect<T, Issue.Issue, R>): Getter<T, E, R>;
+export declare function transformOrFail<T, E, R = never>(f: (e: E, options: SchemaAST.ParseOptions) => Effect.Effect<T, SchemaIssue.Issue, R>): Getter<T, E, R>;
 /**
  * Creates a getter that transforms the full `Option` — both present and absent values.
  *
  * **When to use**
  *
- * Use when you need to handle both `Some` and `None` cases.
- * - You want to turn a present value into absent, or vice versa.
+ * Use when you need a schema getter to handle both `Some` and `None` cases.
  *
  * **Details**
  *
- * - Pure, never fails.
- * - Receives the full `Option<E>` and must return `Option<T>`.
+ * The getter is pure and never fails. It receives the full `Option<E>` and
+ * must return `Option<T>`, so it can turn a present value into absent or an
+ * absent value into present.
  *
  * **Example** (Filter out empty strings)
  *
@@ -556,7 +560,8 @@ export declare function transformOptional<T, E>(f: (oe: Option.Option<E>) => Opt
  *
  * **When to use**
  *
- * Use when a field should be excluded during decoding or encoding.
+ * Use when you need a schema getter to exclude a field during decoding or
+ * encoding.
  *
  * **Details**
  *
@@ -583,7 +588,8 @@ export declare function omit<T>(): Getter<never, T>;
  *
  * **When to use**
  *
- * Use when a field may be `undefined` in the encoded input and should have a fallback.
+ * Use when you need a schema getter to provide a fallback for a field that may
+ * be `undefined` in the encoded input.
  *
  * **Details**
  *
@@ -606,18 +612,18 @@ export declare function omit<T>(): Getter<never, T>;
  * @category constructors
  * @since 4.0.0
  */
-export declare function withDefault<T, R = never>(defaultValue: Effect.Effect<T, Issue.Issue, R>): Getter<T, T | undefined, R>;
+export declare function withDefault<T, R = never>(defaultValue: Effect.Effect<T, SchemaIssue.Issue, R>): Getter<T, T | undefined, R>;
 /**
  * Coerces any value to a `string` using the global `String()` constructor.
  *
  * **When to use**
  *
- * Use when you need a string representation of an arbitrary encoded value.
+ * Use when you need a schema getter to coerce a present encoded value to a
+ * string with `String()`.
  *
  * **Details**
  *
- * - Pure, never fails.
- * - Delegates to `globalThis.String`.
+ * The getter is pure, never fails, and delegates to `globalThis.String`.
  *
  * **Example** (Coerce to string)
  *
@@ -639,12 +645,13 @@ export declare function String<E>(): Getter<string, E>;
  *
  * **When to use**
  *
- * Use when you need numeric coercion of an encoded value.
+ * Use when you need a schema getter to coerce a present encoded value to a
+ * number with `Number()`.
  *
  * **Details**
  *
- * - Pure, never fails (may produce `NaN` for non-numeric inputs).
- * - Delegates to `globalThis.Number`.
+ * The getter is pure, never fails, and delegates to `globalThis.Number`. It may
+ * produce `NaN` for non-numeric inputs.
  *
  * **Example** (Coerce to number)
  *
@@ -666,12 +673,12 @@ export declare function Number<E>(): Getter<number, E>;
  *
  * **When to use**
  *
- * Use when you need boolean coercion (truthiness check) of an encoded value.
+ * Use when you need a schema getter to coerce a present encoded value to a
+ * boolean with `Boolean()`.
  *
  * **Details**
  *
- * - Pure, never fails.
- * - Delegates to `globalThis.Boolean`.
+ * The getter is pure, never fails, and delegates to `globalThis.Boolean`.
  *
  * **Example** (Coerce to boolean)
  *
@@ -691,7 +698,8 @@ export declare function Boolean<E>(): Getter<boolean, E>;
  *
  * **When to use**
  *
- * Use when you need to convert strings, numbers, or booleans to `bigint`.
+ * Use when you need a schema getter to convert a present string, number, or
+ * boolean value to `bigint`.
  *
  * **Details**
  *
@@ -716,7 +724,8 @@ export declare function BigInt<E extends string | number | bigint | boolean>():
  *
  * **When to use**
  *
- * Use when you need to parse a string, number, or Date into a `Date` object.
+ * Use when you need a schema getter to coerce a present string, number, or
+ * existing date object into a new date object.
  *
  * **Details**
  *
@@ -887,14 +896,15 @@ type ParseJsonOptions = {
  *
  * **When to use**
  *
- * Use when an encoded value is a JSON string that needs to be parsed during decoding.
+ * Use when you need a schema getter to parse a present encoded JSON string
+ * during decoding.
  *
  * **Details**
  *
  * - Skips `None` inputs.
  * - Without `reviver`: returns `Schema.MutableJson` (typed JSON).
  * - With `reviver`: returns `unknown` (reviver may produce arbitrary values).
- * - On parse failure, fails with `Issue.InvalidValue` containing the error message.
+ * - On parse failure, fails with `SchemaIssue.InvalidValue` containing the error message.
  *
  * **Example** (Parse JSON)
  *
@@ -907,7 +917,7 @@ type ParseJsonOptions = {
  *
  * @see {@link stringifyJson} for the inverse operation
  *
- * @category Json
+ * @category JSON getters
  * @since 4.0.0
  */
 export declare function parseJson<E extends string>(): Getter<Schema.MutableJson, E>;
@@ -921,13 +931,14 @@ type StringifyJsonOptions = {
  *
  * **When to use**
  *
- * Use when a decoded value needs to be serialized to JSON text during encoding.
+ * Use when you need a schema getter to serialize a present decoded value to
+ * JSON text during encoding.
  *
  * **Details**
  *
  * - Skips `None` inputs.
  * - On thrown stringify failures, such as circular references, fails with
- *   `Issue.InvalidValue`.
+ *   `SchemaIssue.InvalidValue`.
  * - Supports optional `replacer` and `space` options, matching
  *   `JSON.stringify`.
  * - If `JSON.stringify` returns `undefined`, such as for `undefined`,
@@ -945,7 +956,7 @@ type StringifyJsonOptions = {
  *
  * @see {@link parseJson} for the inverse operation
  *
- * @category Json
+ * @category JSON getters
  * @since 4.0.0
  */
 export declare function stringifyJson(options?: StringifyJsonOptions): Getter<string, unknown>;
@@ -954,13 +965,14 @@ export declare function stringifyJson(options?: StringifyJsonOptions): Getter<st
  *
  * **When to use**
  *
- * Use when an encoded string contains delimited key-value pairs (e.g. `"a=1,b=2"`).
+ * Use when you need a schema getter to parse a present encoded string that
+ * contains delimited key-value pairs (e.g. `"a=1,b=2"`).
  *
  * **Details**
  *
- * - Splits the string by `separator` (default `,`), then each pair by `keyValueSeparator` (default `=`).
- * - Pairs missing a key or value are silently skipped.
- * - Pure, never fails.
+ * The getter is pure and never fails. It splits the string by `separator`
+ * (default `,`) and then each pair by `keyValueSeparator` (default `=`). Pairs
+ * missing a key or value are silently skipped.
  *
  * **Example** (Parse key-value string)
  *
@@ -986,12 +998,14 @@ export declare function splitKeyValue<E extends string>(options?: {
  *
  * **When to use**
  *
- * Use when a decoded record needs to be serialized as a delimited key-value string.
+ * Use when you need a schema getter to serialize a present decoded record as a
+ * delimited key-value string.
  *
  * **Details**
  *
- * - Joins entries with `separator` (default `,`) and key/value with `keyValueSeparator` (default `=`).
- * - Pure, never fails.
+ * The getter is pure and never fails. It joins entries with `separator`
+ * (default `,`) and joins each key and value with `keyValueSeparator` (default
+ * `=`).
  *
  * **Example** (Join key-value record)
  *
@@ -1016,13 +1030,13 @@ export declare function joinKeyValue<E extends Record<PropertyKey, string>>(opti
  *
  * **When to use**
  *
- * Use when an encoded string is a delimited list (e.g. CSV values).
+ * Use when you need a schema getter to split a present encoded string
+ * containing a delimited list, such as CSV values.
  *
  * **Details**
  *
- * - Splits by `separator` (default `,`).
- * - An empty string produces an empty array (not `[""]`).
- * - Pure, never fails.
+ * The getter is pure and never fails. It splits by `separator` (default `,`).
+ * An empty string produces an empty array, not `[""]`.
  *
  * **Example** (Split comma-separated string)
  *
@@ -1047,7 +1061,7 @@ export declare function split<E extends string>(options?: {
  *
  * **Details**
  *
- * - Pure, never fails.
+ * The getter is pure and never fails.
  *
  * **Example** (Encode to Base64)
  *
@@ -1061,7 +1075,7 @@ export declare function split<E extends string>(options?: {
  * @see {@link decodeBase64String} for the inverse operation to `string`
  * @see {@link encodeBase64Url} for the URL-safe variant
  *
- * @category Base64
+ * @category Base64 getters
  * @since 4.0.0
  */
 export declare function encodeBase64<E extends Uint8Array | string>(): Getter<string, E>;
@@ -1070,7 +1084,7 @@ export declare function encodeBase64<E extends Uint8Array | string>(): Getter<st
  *
  * **Details**
  *
- * - Pure, never fails.
+ * The getter is pure and never fails.
  *
  * **Example** (Encode to Base64Url)
  *
@@ -1084,7 +1098,7 @@ export declare function encodeBase64<E extends Uint8Array | string>(): Getter<st
  * @see {@link decodeBase64UrlString} for the inverse operation to `string`
  * @see {@link encodeBase64} for the standard Base64 variant
  *
- * @category Base64
+ * @category Base64 getters
  * @since 4.0.0
  */
 export declare function encodeBase64Url<E extends Uint8Array | string>(): Getter<string, E>;
@@ -1093,7 +1107,7 @@ export declare function encodeBase64Url<E extends Uint8Array | string>(): Getter
  *
  * **Details**
  *
- * - Pure, never fails.
+ * The getter is pure and never fails.
  *
  * **Example** (Encode to hex)
  *
@@ -1106,7 +1120,7 @@ export declare function encodeBase64Url<E extends Uint8Array | string>(): Getter
  * @see {@link decodeHex} for the inverse operation to `Uint8Array`
  * @see {@link decodeHexString} for the inverse operation to `string`
  *
- * @category Hex
+ * @category Hex getters
  * @since 4.0.0
  */
 export declare function encodeHex<E extends Uint8Array | string>(): Getter<string, E>;
@@ -1115,7 +1129,7 @@ export declare function encodeHex<E extends Uint8Array | string>(): Getter<strin
  *
  * **Details**
  *
- * - Fails with `Issue.InvalidValue` if the input is not valid Base64.
+ * - Fails with `SchemaIssue.InvalidValue` if the input is not valid Base64.
  *
  * **Example** (Decode Base64 to bytes)
  *
@@ -1129,7 +1143,7 @@ export declare function encodeHex<E extends Uint8Array | string>(): Getter<strin
  * @see {@link decodeBase64String} to decode to `string` instead
  * @see {@link encodeBase64} for the inverse operation
  *
- * @category Base64
+ * @category Base64 getters
  * @since 4.0.0
  */
 export declare function decodeBase64<E extends string>(): Getter<Uint8Array, E>;
@@ -1138,7 +1152,7 @@ export declare function decodeBase64<E extends string>(): Getter<Uint8Array, E>;
  *
  * **Details**
  *
- * - Fails with `Issue.InvalidValue` if the input is not valid Base64.
+ * - Fails with `SchemaIssue.InvalidValue` if the input is not valid Base64.
  *
  * **Example** (Decode Base64 to string)
  *
@@ -1152,7 +1166,7 @@ export declare function decodeBase64<E extends string>(): Getter<Uint8Array, E>;
  * @see {@link decodeBase64} to decode to `Uint8Array` instead
  * @see {@link encodeBase64} for the inverse operation
  *
- * @category Base64
+ * @category Base64 getters
  * @since 4.0.0
  */
 export declare function decodeBase64String<E extends string>(): Getter<string, E>;
@@ -1161,7 +1175,7 @@ export declare function decodeBase64String<E extends string>(): Getter<string, E
  *
  * **Details**
  *
- * - Fails with `Issue.InvalidValue` if the input is not valid Base64Url.
+ * - Fails with `SchemaIssue.InvalidValue` if the input is not valid Base64Url.
  *
  * **Example** (Decode Base64Url to bytes)
  *
@@ -1175,7 +1189,7 @@ export declare function decodeBase64String<E extends string>(): Getter<string, E
  * @see {@link decodeBase64UrlString} to decode to `string` instead
  * @see {@link encodeBase64Url} for the inverse operation
  *
- * @category Base64
+ * @category Base64 getters
  * @since 4.0.0
  */
 export declare function decodeBase64Url<E extends string>(): Getter<Uint8Array, E>;
@@ -1184,7 +1198,7 @@ export declare function decodeBase64Url<E extends string>(): Getter<Uint8Array,
  *
  * **Details**
  *
- * - Fails with `Issue.InvalidValue` if the input is not valid Base64Url.
+ * - Fails with `SchemaIssue.InvalidValue` if the input is not valid Base64Url.
  *
  * **Example** (Decode Base64Url to string)
  *
@@ -1198,7 +1212,7 @@ export declare function decodeBase64Url<E extends string>(): Getter<Uint8Array,
  * @see {@link decodeBase64Url} to decode to `Uint8Array` instead
  * @see {@link encodeBase64Url} for the inverse operation
  *
- * @category Base64
+ * @category Base64 getters
  * @since 4.0.0
  */
 export declare function decodeBase64UrlString<E extends string>(): Getter<string, E>;
@@ -1207,7 +1221,7 @@ export declare function decodeBase64UrlString<E extends string>(): Getter<string
  *
  * **Details**
  *
- * - Fails with `Issue.InvalidValue` if the input is not valid hex.
+ * - Fails with `SchemaIssue.InvalidValue` if the input is not valid hex.
  *
  * **Example** (Decode hex to bytes)
  *
@@ -1221,7 +1235,7 @@ export declare function decodeBase64UrlString<E extends string>(): Getter<string
  * @see {@link decodeHexString} to decode to `string` instead
  * @see {@link encodeHex} for the inverse operation
  *
- * @category Hex
+ * @category Hex getters
  * @since 4.0.0
  */
 export declare function decodeHex<E extends string>(): Getter<Uint8Array, E>;
@@ -1230,7 +1244,7 @@ export declare function decodeHex<E extends string>(): Getter<Uint8Array, E>;
  *
  * **Details**
  *
- * - Fails with `Issue.InvalidValue` if the input is not valid hex.
+ * - Fails with `SchemaIssue.InvalidValue` if the input is not valid hex.
  *
  * **Example** (Decode hex to string)
  *
@@ -1244,7 +1258,7 @@ export declare function decodeHex<E extends string>(): Getter<Uint8Array, E>;
  * @see {@link decodeHex} to decode to `Uint8Array` instead
  * @see {@link encodeHex} for the inverse operation
  *
- * @category Hex
+ * @category Hex getters
  * @since 4.0.0
  */
 export declare function decodeHexString<E extends string>(): Getter<string, E>;
@@ -1276,7 +1290,7 @@ export declare function encodeUriComponent<E extends string>(): Getter<string, E
  *
  * **Details**
  *
- * - Fails with `Issue.InvalidValue` if the input contains malformed percent-encoding sequences.
+ * - Fails with `SchemaIssue.InvalidValue` if the input contains malformed percent-encoding sequences.
  *
  * **Example** (Decode a URI component)
  *
@@ -1298,7 +1312,8 @@ export declare function decodeUriComponent<E extends string>(): Getter<string, E
  *
  * **When to use**
  *
- * Use when an encoded value represents a date/time and should be decoded to a `DateTime.Utc`.
+ * Use when you need a schema getter to decode a present encoded date/time value
+ * to a `DateTime.Utc`.
  *
  * **Details**
  *
@@ -1306,7 +1321,7 @@ export declare function decodeUriComponent<E extends string>(): Getter<string, E
  *   instant objects, zoned instant objects, JavaScript `Date` instances, epoch
  *   milliseconds, and date strings.
  * - Converts successfully parsed values to UTC.
- * - Fails with `Issue.InvalidValue` if the input cannot be parsed as a valid
+ * - Fails with `SchemaIssue.InvalidValue` if the input cannot be parsed as a valid
  *   `DateTime`.
  *
  * **Example** (Parse DateTime)
@@ -1329,13 +1344,14 @@ export declare function dateTimeUtcFromInput<E extends DateTime.DateTime.Input>(
  *
  * **When to use**
  *
- * Use to parse `FormData` from HTTP requests into structured objects.
+ * Use when you need a schema getter to parse `FormData` from HTTP requests into
+ * structured objects.
  *
  * **Details**
  *
- * - Pure, never fails.
- * - Interprets bracket-path keys (e.g. `user[name]`, `items[0]`) to build nested objects/arrays.
- * - Leaf values are `string` or `Blob`.
+ * The getter is pure and never fails. It interprets bracket-path keys such as
+ * `user[name]` and `items[0]` to build nested objects or arrays, and each leaf
+ * value is a `string` or `Blob`.
  *
  * **Example** (Decode FormData)
  *
@@ -1359,13 +1375,14 @@ export declare function decodeFormData(): Getter<Schema.TreeRecord<string | Blob
  *
  * **When to use**
  *
- * Use to serialize structured data to `FormData` for HTTP requests.
+ * Use when you need a schema getter to serialize structured data to `FormData`
+ * for HTTP requests.
  *
  * **Details**
  *
- * - Pure, never fails.
- * - Flattens nested objects/arrays into bracket-path keys (e.g. `user[name]`, `items[0]`).
- * - Non-object inputs produce an empty `FormData`.
+ * The getter is pure and never fails. It flattens nested objects or arrays into
+ * bracket-path keys such as `user[name]` and `items[0]`. Non-object inputs
+ * produce an empty `FormData`.
  *
  * **Example** (Encode to FormData)
  *
@@ -1389,13 +1406,14 @@ export declare function encodeFormData(): Getter<FormData, unknown>;
  *
  * **When to use**
  *
- * Use to parse query parameters from URLs into structured objects.
+ * Use when you need a schema getter to parse query parameters from URLs into
+ * structured objects.
  *
  * **Details**
  *
- * - Pure, never fails.
- * - Interprets bracket-path keys (e.g. `user[name]`, `items[0]`) to build nested objects/arrays.
- * - Leaf values are `string`.
+ * The getter is pure and never fails. It interprets bracket-path keys such as
+ * `user[name]` and `items[0]` to build nested objects or arrays, and each leaf
+ * value is a `string`.
  *
  * **Example** (Decode URLSearchParams)
  *
@@ -1410,7 +1428,7 @@ export declare function encodeFormData(): Getter<FormData, unknown>;
  * @see {@link makeTreeRecord} for the underlying bracket-path parser
  * @see {@link decodeFormData} for the FormData variant
  *
- * @category URLSearchParams
+ * @category search params
  * @since 4.0.0
  */
 export declare function decodeURLSearchParams(): Getter<Schema.TreeRecord<string>, URLSearchParams>;
@@ -1419,13 +1437,13 @@ export declare function decodeURLSearchParams(): Getter<Schema.TreeRecord<string
  *
  * **When to use**
  *
- * Use to serialize structured data to query parameters for URLs.
+ * Use when you need a schema getter to serialize structured data to query
+ * parameters for URLs.
  *
  * **Details**
  *
- * - Pure, never fails.
- * - Flattens nested objects/arrays into bracket-path keys.
- * - Non-object inputs produce an empty `URLSearchParams`.
+ * The getter is pure and never fails. It flattens nested objects or arrays into
+ * bracket-path keys. Non-object inputs produce an empty `URLSearchParams`.
  *
  * **Example** (Encode to URLSearchParams)
  *
@@ -1440,7 +1458,7 @@ export declare function decodeURLSearchParams(): Getter<Schema.TreeRecord<string
  * @see {@link collectBracketPathEntries} for the underlying flattener
  * @see {@link encodeFormData} for the FormData variant
  *
- * @category URLSearchParams
+ * @category search params
  * @since 4.0.0
  */
 export declare function encodeURLSearchParams(): Getter<URLSearchParams, unknown>;
@@ -1449,7 +1467,8 @@ export declare function encodeURLSearchParams(): Getter<URLSearchParams, unknown
  *
  * **When to use**
  *
- * Use to parse FormData or URLSearchParams entries into structured objects.
+ * Use when you need a schema getter to parse FormData or URLSearchParams
+ * entries into structured objects.
  * - You have flat key-value pairs with bracket-path keys that need nesting.
  *
  * **Details**
@@ -1492,7 +1511,8 @@ export declare function makeTreeRecord<A>(bracketPathEntries: ReadonlyArray<read
  *
  * **When to use**
  *
- * Use to serialize structured objects to flat key-value entries.
+ * Use when you need a schema getter to serialize structured objects to flat
+ * key-value entries.
  * - Building custom `FormData` or `URLSearchParams` encoders.
  *
  * **Details**