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

package/dist/SchemaGetter.js

@@ -92,26 +92,26 @@ import * as Option from "./Option.js";
 import * as Pipeable from "./Pipeable.js";
 import * as Predicate from "./Predicate.js";
 import * as Result from "./Result.js";
-import * as Issue from "./SchemaIssue.js";
+import * as SchemaIssue from "./SchemaIssue.js";
 import * as Str from "./String.js";
 /**
  * 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)
  *
@@ -155,13 +155,13 @@ export class Getter 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)
  *
@@ -186,7 +186,7 @@ export function succeed(t) {
  *
  * **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**
@@ -218,12 +218,13 @@ export function fail(f) {
  *
  * **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)
@@ -242,7 +243,7 @@ export function fail(f) {
  * @since 4.0.0
  */
 export function forbidden(message) {
-  return fail(oe => new Issue.Forbidden(oe, {
+  return fail(oe => new SchemaIssue.Forbidden(oe, {
     message: message(oe)
   }));
 }
@@ -264,7 +265,8 @@ export function passthroughSubtype() {
  *
  * **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**
@@ -298,12 +300,12 @@ export function onNone(f) {
  *
  * **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.
  *
@@ -322,14 +324,15 @@ export function onNone(f) {
  * @since 4.0.0
  */
 export function required(annotations) {
-  return onNone(() => Effect.fail(new Issue.MissingKey(annotations)));
+  return onNone(() => Effect.fail(new SchemaIssue.MissingKey(annotations)));
 }
 /**
  * Creates a getter that handles present values (`Option.Some`), passing `None` through.
  *
  * **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**
@@ -363,7 +366,8 @@ export function onSome(f) {
  *
  * **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**
@@ -374,7 +378,7 @@ export function onSome(f) {
  *   - `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)
@@ -396,7 +400,7 @@ export function onSome(f) {
 export function checkEffect(f) {
   return onSome((t, options) => {
     return f(t, options).pipe(Effect.flatMapEager(out => {
-      const issue = Issue.makeSingle(t, out);
+      const issue = SchemaIssue.makeSingle(t, out);
       return issue ? Effect.fail(issue) : Effect.succeed(Option.some(t));
     }));
   });
@@ -406,7 +410,8 @@ export function checkEffect(f) {
  *
  * **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**
@@ -444,8 +449,8 @@ export function transform(f) {
  *
  * **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**
  *
@@ -482,13 +487,13 @@ export function transformOrFail(f) {
  *
  * **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)
  *
@@ -514,7 +519,8 @@ export function transformOptional(f) {
  *
  * **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**
  *
@@ -543,7 +549,8 @@ export function omit() {
  *
  * **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**
  *
@@ -577,12 +584,12 @@ export function withDefault(defaultValue) {
  *
  * **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)
  *
@@ -606,12 +613,13 @@ export function String() {
  *
  * **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)
  *
@@ -635,12 +643,12 @@ export function Number() {
  *
  * **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)
  *
@@ -662,7 +670,8 @@ export function Boolean() {
  *
  * **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**
  *
@@ -689,7 +698,8 @@ export function BigInt() {
  *
  * **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**
  *
@@ -871,7 +881,7 @@ export function toUpperCase() {
 export function parseJson(options) {
   return onSome(input => Effect.try({
     try: () => Option.some(JSON.parse(input, options?.reviver)),
-    catch: e => new Issue.InvalidValue(Option.some(input), {
+    catch: e => new SchemaIssue.InvalidValue(Option.some(input), {
       message: globalThis.String(e)
     })
   }));
@@ -881,13 +891,14 @@ export function parseJson(options) {
  *
  * **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`,
@@ -905,13 +916,13 @@ export function parseJson(options) {
  *
  * @see {@link parseJson} for the inverse operation
  *
- * @category Json
+ * @category JSON getters
  * @since 4.0.0
  */
 export function stringifyJson(options) {
   return onSome(input => Effect.try({
     try: () => Option.some(JSON.stringify(input, options?.replacer, options?.space)),
-    catch: e => new Issue.InvalidValue(Option.some(input), {
+    catch: e => new SchemaIssue.InvalidValue(Option.some(input), {
       message: globalThis.String(e)
     })
   }));
@@ -921,13 +932,14 @@ export function stringifyJson(options) {
  *
  * **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)
  *
@@ -960,12 +972,14 @@ export function splitKeyValue(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)
  *
@@ -991,13 +1005,13 @@ export function joinKeyValue(options) {
  *
  * **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)
  *
@@ -1023,7 +1037,7 @@ export function split(options) {
  *
  * **Details**
  *
- * - Pure, never fails.
+ * The getter is pure and never fails.
  *
  * **Example** (Encode to Base64)
  *
@@ -1037,7 +1051,7 @@ export function split(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 function encodeBase64() {
@@ -1048,7 +1062,7 @@ export function encodeBase64() {
  *
  * **Details**
  *
- * - Pure, never fails.
+ * The getter is pure and never fails.
  *
  * **Example** (Encode to Base64Url)
  *
@@ -1062,7 +1076,7 @@ export function encodeBase64() {
  * @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 function encodeBase64Url() {
@@ -1073,7 +1087,7 @@ export function encodeBase64Url() {
  *
  * **Details**
  *
- * - Pure, never fails.
+ * The getter is pure and never fails.
  *
  * **Example** (Encode to hex)
  *
@@ -1086,7 +1100,7 @@ export function encodeBase64Url() {
  * @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 function encodeHex() {
@@ -1097,7 +1111,7 @@ export function encodeHex() {
  *
  * **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)
  *
@@ -1111,11 +1125,11 @@ export function encodeHex() {
  * @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 function decodeBase64() {
-  return transformOrFail(input => Effect.mapErrorEager(Effect.fromResult(Encoding.decodeBase64(input)), e => new Issue.InvalidValue(Option.some(input), {
+  return transformOrFail(input => Effect.mapErrorEager(Effect.fromResult(Encoding.decodeBase64(input)), e => new SchemaIssue.InvalidValue(Option.some(input), {
     message: e.message
   })));
 }
@@ -1124,7 +1138,7 @@ export function decodeBase64() {
  *
  * **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)
  *
@@ -1138,12 +1152,12 @@ export function decodeBase64() {
  * @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 function decodeBase64String() {
   return transformOrFail(input => Result.match(Encoding.decodeBase64String(input), {
-    onFailure: e => Effect.fail(new Issue.InvalidValue(Option.some(input), {
+    onFailure: e => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), {
       message: e.message
     })),
     onSuccess: Effect.succeed
@@ -1154,7 +1168,7 @@ export function decodeBase64String() {
  *
  * **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)
  *
@@ -1168,12 +1182,12 @@ export function decodeBase64String() {
  * @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 function decodeBase64Url() {
   return transformOrFail(input => Result.match(Encoding.decodeBase64Url(input), {
-    onFailure: e => Effect.fail(new Issue.InvalidValue(Option.some(input), {
+    onFailure: e => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), {
       message: e.message
     })),
     onSuccess: Effect.succeed
@@ -1184,7 +1198,7 @@ export function decodeBase64Url() {
  *
  * **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,12 +1212,12 @@ export function decodeBase64Url() {
  * @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 function decodeBase64UrlString() {
   return transformOrFail(input => Result.match(Encoding.decodeBase64UrlString(input), {
-    onFailure: e => Effect.fail(new Issue.InvalidValue(Option.some(input), {
+    onFailure: e => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), {
       message: e.message
     })),
     onSuccess: Effect.succeed
@@ -1214,7 +1228,7 @@ export function decodeBase64UrlString() {
  *
  * **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)
  *
@@ -1228,12 +1242,12 @@ export function decodeBase64UrlString() {
  * @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 function decodeHex() {
   return transformOrFail(input => Result.match(Encoding.decodeHex(input), {
-    onFailure: e => Effect.fail(new Issue.InvalidValue(Option.some(input), {
+    onFailure: e => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), {
       message: e.message
     })),
     onSuccess: Effect.succeed
@@ -1244,7 +1258,7 @@ export function decodeHex() {
  *
  * **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)
  *
@@ -1258,12 +1272,12 @@ export function decodeHex() {
  * @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 function decodeHexString() {
   return transformOrFail(input => Result.match(Encoding.decodeHexString(input), {
-    onFailure: e => Effect.fail(new Issue.InvalidValue(Option.some(input), {
+    onFailure: e => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), {
       message: e.message
     })),
     onSuccess: Effect.succeed
@@ -1299,7 +1313,7 @@ export function encodeUriComponent() {
  *
  * **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)
  *
@@ -1320,7 +1334,7 @@ export function decodeUriComponent() {
     try {
       return Effect.succeed(globalThis.decodeURIComponent(input));
     } catch (e) {
-      return Effect.fail(new Issue.InvalidValue(Option.some(input), {
+      return Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), {
         message: e instanceof URIError ? e.message : "Invalid URI component"
       }));
     }
@@ -1331,7 +1345,8 @@ export function decodeUriComponent() {
  *
  * **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**
  *
@@ -1339,7 +1354,7 @@ export function decodeUriComponent() {
  *   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)
@@ -1359,7 +1374,7 @@ export function decodeUriComponent() {
 export function dateTimeUtcFromInput() {
   return transformOrFail(input => {
     return Option.match(DateTime.make(input), {
-      onNone: () => Effect.fail(new Issue.InvalidValue(Option.some(input), {
+      onNone: () => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), {
         message: "Invalid DateTime input"
       })),
       onSome: dt => Effect.succeed(DateTime.toUtc(dt))
@@ -1371,13 +1386,14 @@ export function dateTimeUtcFromInput() {
  *
  * **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)
  *
@@ -1404,13 +1420,14 @@ const collectFormDataEntries = /*#__PURE__*/collectBracketPathEntries(value => t
  *
  * **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)
  *
@@ -1445,13 +1462,14 @@ export function encodeFormData() {
  *
  * **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)
  *
@@ -1466,7 +1484,7 @@ export function encodeFormData() {
  * @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 function decodeURLSearchParams() {
@@ -1478,13 +1496,13 @@ const collectURLSearchParamsEntries = /*#__PURE__*/collectBracketPathEntries(Pre
  *
  * **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)
  *
@@ -1499,7 +1517,7 @@ const collectURLSearchParamsEntries = /*#__PURE__*/collectBracketPathEntries(Pre
  * @see {@link collectBracketPathEntries} for the underlying flattener
  * @see {@link encodeFormData} for the FormData variant
  *
- * @category URLSearchParams
+ * @category search params
  * @since 4.0.0
  */
 export function encodeURLSearchParams() {
@@ -1527,7 +1545,8 @@ function bracketPathToTokens(bracketPath) {
  *
  * **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**
@@ -1613,7 +1632,8 @@ export function makeTreeRecord(bracketPathEntries) {
  *
  * **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**