effect 4.0.0-beta.70 → 4.0.0-beta.72

package/dist/SchemaGetter.js

@@ -95,11 +95,11 @@ import * as Result from "./Result.js";
 import * as Issue from "./SchemaIssue.js";
 import * as Str from "./String.js";
 /**
- * A composable transformation from an encoded type `E` to a decoded type `T`.
+ * Represents a composable transformation from an encoded type `E` to a decoded type `T`.
  *
  * **When to use**
  *
- * - Building custom schema transformations with `Schema.decodeTo` or `Schema.decode`.
+ * Use to build custom schema transformations with `Schema.decodeTo` or `Schema.decode`.
  * - Composing multiple transformation steps into a single getter.
  *
  * **Details**
@@ -109,7 +109,6 @@ import * as Str from "./String.js";
  * - Returns `Option.None` to omit the value from the decoded output.
  * - Fails with `Issue` on invalid input.
  * - May require Effect services via `R`.
- * - Immutable — constructing or composing getters does not mutate existing instances.
  * - `.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.
@@ -125,9 +124,9 @@ import * as Str from "./String.js";
  * // composed: Getter<number, string> — parses then doubles
  * ```
  *
- * @see {@link transform} - create a getter from a pure function
- * @see {@link passthrough} - identity getter
- * @see {@link transformOrFail} - fallible transformation
+ * @see {@link transform} to create a getter from a pure function
+ * @see {@link passthrough} for the identity getter
+ * @see {@link transformOrFail} for fallible transformation
  *
  * @category models
  * @since 4.0.0
@@ -156,7 +155,7 @@ export class Getter extends Pipeable.Class {
  *
  * **When to use**
  *
- * - A schema field should always decode to a fixed value.
+ * Use when a schema field should always decode to a fixed value.
  * - You need a placeholder getter that produces a known default.
  *
  * **Details**
@@ -173,8 +172,8 @@ export class Getter extends Pipeable.Class {
  * // alwaysZero: Getter<0, unknown> — always produces 0
  * ```
  *
- * @see {@link transform} - when you need to use the input value
- * @see {@link passthrough} - when you want to keep the input as-is
+ * @see {@link transform} when you need to use the input value
+ * @see {@link passthrough} when you want to keep the input as-is
  *
  * @category constructors
  * @since 4.0.0
@@ -187,7 +186,7 @@ export function succeed(t) {
  *
  * **When to use**
  *
- * - A transformation should unconditionally reject input.
+ * Use when a transformation should unconditionally reject input.
  * - Building custom validation getters that produce specific error types.
  *
  * **Details**
@@ -205,8 +204,8 @@ export function succeed(t) {
  * )
  * ```
  *
- * @see {@link forbidden} - convenience for `Forbidden` issues
- * @see {@link checkEffect} - fail conditionally based on input value
+ * @see {@link forbidden} for a convenience helper for `Forbidden` issues
+ * @see {@link checkEffect} to fail conditionally based on input value
  *
  * @category constructors
  * @since 4.0.0
@@ -219,7 +218,7 @@ export function fail(f) {
  *
  * **When to use**
  *
- * - A field or direction (encode/decode) should be disallowed entirely.
+ * Use when a field or direction (encode/decode) should be disallowed entirely.
  * - You want a clear "forbidden" error message in schema validation output.
  *
  * **Details**
@@ -237,7 +236,7 @@ export function fail(f) {
  * )
  * ```
  *
- * @see {@link fail} - fail with a custom issue type
+ * @see {@link fail} to fail with a custom issue type
  *
  * @category constructors
  * @since 4.0.0
@@ -265,7 +264,7 @@ export function passthroughSubtype() {
  *
  * **When to use**
  *
- * - You need to provide a fallback or computed value for missing struct keys.
+ * Use when you need to provide a fallback or computed value for missing struct keys.
  * - Building custom "default value" logic more complex than {@link withDefault}.
  *
  * **Details**
@@ -284,9 +283,9 @@ export function passthroughSubtype() {
  * )
  * ```
  *
- * @see {@link required} - fails if input is absent
- * @see {@link withDefault} - simpler default value for undefined inputs
- * @see {@link onSome} - handle only present values
+ * @see {@link required} when absent input should fail
+ * @see {@link withDefault} for a simpler default value for undefined inputs
+ * @see {@link onSome} to handle only present values
  *
  * @category constructors
  * @since 4.0.0
@@ -299,7 +298,7 @@ export function onNone(f) {
  *
  * **When to use**
  *
- * - A struct field must be present in the encoded input.
+ * Use when a struct field must be present in the encoded input.
  * - You want schema validation to report a missing key error.
  *
  * **Details**
@@ -316,8 +315,8 @@ export function onNone(f) {
  * const mustExist = SchemaGetter.required<string>()
  * ```
  *
- * @see {@link onNone} - provide a fallback instead of failing
- * @see {@link withDefault} - substitute a default for undefined values
+ * @see {@link onNone} to provide a fallback instead of failing
+ * @see {@link withDefault} to substitute a default for undefined values
  *
  * @category constructors
  * @since 4.0.0
@@ -330,7 +329,7 @@ export function required(annotations) {
  *
  * **When to use**
  *
- * - You need to transform or validate only when a value is present.
+ * Use when you need to transform or validate only when a value is present.
  * - Missing keys should remain absent in the output.
  *
  * **Details**
@@ -349,9 +348,9 @@ export function required(annotations) {
  * )
  * ```
  *
- * @see {@link onNone} - handle only absent values
- * @see {@link transform} - simpler pure transformation of present values
- * @see {@link transformOrFail} - fallible transformation of present values
+ * @see {@link onNone} to handle only absent values
+ * @see {@link transform} for a simpler pure transformation of present values
+ * @see {@link transformOrFail} for fallible transformation of present values
  *
  * @category constructors
  * @since 4.0.0
@@ -364,7 +363,7 @@ export function onSome(f) {
  *
  * **When to use**
  *
- * - You need to validate a decoded value (e.g. check a constraint or call an external service).
+ * Use when you need 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**
@@ -388,8 +387,8 @@ export function onSome(f) {
  * )
  * ```
  *
- * @see {@link transform} - when you need to change the value, not just validate
- * @see {@link fail} - unconditional failure
+ * @see {@link transform} when you need to change the value, not just validate
+ * @see {@link fail} for unconditional failure
  *
  * @category constructors
  * @since 4.0.0
@@ -407,14 +406,13 @@ export function checkEffect(f) {
  *
  * **When to use**
  *
- * - You have a pure, infallible transformation between types.
+ * Use when you have a pure, infallible transformation between types.
  * - Building encode/decode pairs for `Schema.decodeTo`.
  *
  * **Details**
  *
  * - This is the most commonly used constructor.
  * - Transforms `Some(e)` to `Some(f(e))` and leaves `None` unchanged.
- * - Pure, does not mutate input.
  * - Skips `None` inputs — only called when a value is present.
  * - Never fails.
  *
@@ -431,9 +429,9 @@ export function checkEffect(f) {
  * )
  * ```
  *
- * @see {@link transformOrFail} - when the transformation can fail
- * @see {@link transformOptional} - when you need to handle `None` inputs
- * @see {@link passthrough} - when no transformation is needed
+ * @see {@link transformOrFail} when the transformation can fail
+ * @see {@link transformOptional} when you need to handle `None` inputs
+ * @see {@link passthrough} when no transformation is needed
  *
  * @category constructors
  * @since 4.0.0
@@ -446,7 +444,7 @@ export function transform(f) {
  *
  * **When to use**
  *
- * - The transformation may fail (e.g. parsing, validation).
+ * Use when the transformation may fail (e.g. parsing, validation).
  * - The transformation needs Effect services or is async.
  *
  * **Details**
@@ -470,8 +468,8 @@ export function transform(f) {
  * )
  * ```
  *
- * @see {@link transform} - when transformation cannot fail
- * @see {@link onSome} - when you need full `Option` control over the output
+ * @see {@link transform} when transformation cannot fail
+ * @see {@link onSome} when you need full `Option` control over the output
  *
  * @category constructors
  * @since 4.0.0
@@ -484,7 +482,7 @@ export function transformOrFail(f) {
  *
  * **When to use**
  *
- * - You need to handle both `Some` and `None` cases.
+ * Use when you need to handle both `Some` and `None` cases.
  * - You want to turn a present value into absent, or vice versa.
  *
  * **Details**
@@ -502,8 +500,8 @@ export function transformOrFail(f) {
  * )
  * ```
  *
- * @see {@link transform} - simpler, only handles present values
- * @see {@link omit} - always returns `None`
+ * @see {@link transform} when you only need to transform present values
+ * @see {@link omit} when you always want `None`
  *
  * @category constructors
  * @since 4.0.0
@@ -516,7 +514,7 @@ export function transformOptional(f) {
  *
  * **When to use**
  *
- * - A field should be excluded during decoding or encoding.
+ * Use when a field should be excluded during decoding or encoding.
  *
  * **Details**
  *
@@ -531,8 +529,8 @@ export function transformOptional(f) {
  * const omitField = SchemaGetter.omit<string>()
  * ```
  *
- * @see {@link transformOptional} - when you want conditional omission
- * @see {@link forbidden} - when you want to fail instead of silently omit
+ * @see {@link transformOptional} when you want conditional omission
+ * @see {@link forbidden} when you want to fail instead of silently omit
  *
  * @category constructors
  * @since 4.0.0
@@ -545,7 +543,7 @@ export function omit() {
  *
  * **When to use**
  *
- * - A field may be `undefined` in the encoded input and should have a fallback.
+ * Use when a field may be `undefined` in the encoded input and should have a fallback.
  *
  * **Details**
  *
@@ -562,8 +560,8 @@ export function omit() {
  * // Getter<number, number | undefined>
  * ```
  *
- * @see {@link onNone} - handle only absent keys (not `undefined` values)
- * @see {@link required} - fail instead of providing a default
+ * @see {@link onNone} to handle only absent keys (not `undefined` values)
+ * @see {@link required} when absent input should fail instead of using a default
  *
  * @category constructors
  * @since 4.0.0
@@ -579,7 +577,7 @@ export function withDefault(defaultValue) {
  *
  * **When to use**
  *
- * - You need a string representation of an arbitrary encoded value.
+ * Use when you need a string representation of an arbitrary encoded value.
  *
  * **Details**
  *
@@ -595,7 +593,7 @@ export function withDefault(defaultValue) {
  * // Getter<string, number>
  * ```
  *
- * @see {@link transform} - for custom string conversions
+ * @see {@link transform} for custom string conversions
  *
  * @category Coercions
  * @since 4.0.0
@@ -608,7 +606,7 @@ export function String() {
  *
  * **When to use**
  *
- * - You need numeric coercion of an encoded value.
+ * Use when you need numeric coercion of an encoded value.
  *
  * **Details**
  *
@@ -624,7 +622,7 @@ export function String() {
  * // Getter<number, string>
  * ```
  *
- * @see {@link transformOrFail} - for validated number parsing
+ * @see {@link transformOrFail} for validated number parsing
  *
  * @category Coercions
  * @since 4.0.0
@@ -637,7 +635,7 @@ export function Number() {
  *
  * **When to use**
  *
- * - You need boolean coercion (truthiness check) of an encoded value.
+ * Use when you need boolean coercion (truthiness check) of an encoded value.
  *
  * **Details**
  *
@@ -664,7 +662,7 @@ export function Boolean() {
  *
  * **When to use**
  *
- * - You need to convert strings, numbers, or booleans to `bigint`.
+ * Use when you need to convert strings, numbers, or booleans to `bigint`.
  *
  * **Details**
  *
@@ -691,7 +689,7 @@ export function BigInt() {
  *
  * **When to use**
  *
- * - You need to parse a string, number, or Date into a `Date` object.
+ * Use when you need to parse a string, number, or Date into a `Date` object.
  *
  * **Details**
  *
@@ -707,7 +705,7 @@ export function BigInt() {
  * // Getter<Date, string>
  * ```
  *
- * @see {@link dateTimeUtcFromInput} - validated DateTime parsing
+ * @see {@link dateTimeUtcFromInput} for validated DateTime parsing
  *
  * @category Coercions
  * @since 4.0.0
@@ -716,7 +714,7 @@ export function Date() {
   return transform(u => new globalThis.Date(u));
 }
 /**
- * Trims whitespace from both ends of a string.
+ * Strips whitespace from both ends of a string.
  *
  * **Details**
  *
@@ -758,7 +756,7 @@ export function capitalize() {
   return transform(Str.capitalize);
 }
 /**
- * Lowercases the first character of a string.
+ * Uncapitalizes the first character of a string.
  *
  * **Details**
  *
@@ -793,7 +791,7 @@ export function uncapitalize() {
  * const toCamel = SchemaGetter.snakeToCamel<string>()
  * ```
  *
- * @see {@link camelToSnake} - inverse operation
+ * @see {@link camelToSnake} for the inverse operation
  *
  * @category string
  * @since 4.0.0
@@ -816,7 +814,7 @@ export function snakeToCamel() {
  * const toSnake = SchemaGetter.camelToSnake<string>()
  * ```
  *
- * @see {@link snakeToCamel} - inverse operation
+ * @see {@link snakeToCamel} for the inverse operation
  *
  * @category string
  * @since 4.0.0
@@ -839,7 +837,7 @@ export function camelToSnake() {
  * const lower = SchemaGetter.toLowerCase<string>()
  * ```
  *
- * @see {@link toUpperCase} - inverse operation
+ * @see {@link toUpperCase} for the inverse operation
  *
  * @category string
  * @since 4.0.0
@@ -862,7 +860,7 @@ export function toLowerCase() {
  * const upper = SchemaGetter.toUpperCase<string>()
  * ```
  *
- * @see {@link toLowerCase} - inverse operation
+ * @see {@link toLowerCase} for the inverse operation
  *
  * @category string
  * @since 4.0.0
@@ -883,7 +881,7 @@ export function parseJson(options) {
  *
  * **When to use**
  *
- * - A decoded value needs to be serialized to JSON text during encoding.
+ * Use when a decoded value needs to be serialized to JSON text during encoding.
  *
  * **Details**
  *
@@ -905,7 +903,7 @@ export function parseJson(options) {
  * // Getter<string, unknown>
  * ```
  *
- * @see {@link parseJson} - inverse operation
+ * @see {@link parseJson} for the inverse operation
  *
  * @category Json
  * @since 4.0.0
@@ -923,7 +921,7 @@ export function stringifyJson(options) {
  *
  * **When to use**
  *
- * - An encoded string contains delimited key-value pairs (e.g. `"a=1,b=2"`).
+ * Use when an encoded string contains delimited key-value pairs (e.g. `"a=1,b=2"`).
  *
  * **Details**
  *
@@ -940,8 +938,8 @@ export function stringifyJson(options) {
  * // "a=1,b=2" -> { a: "1", b: "2" }
  * ```
  *
- * @see {@link joinKeyValue} - inverse operation
- * @see {@link split} - split into an array of strings
+ * @see {@link joinKeyValue} for the inverse operation
+ * @see {@link split} to split into an array of strings
  *
  * @category string
  * @since 4.0.0
@@ -962,7 +960,7 @@ export function splitKeyValue(options) {
  *
  * **When to use**
  *
- * - A decoded record needs to be serialized as a delimited key-value string.
+ * Use when a decoded record needs to be serialized as a delimited key-value string.
  *
  * **Details**
  *
@@ -978,7 +976,7 @@ export function splitKeyValue(options) {
  * // { a: "1", b: "2" } -> "a=1,b=2"
  * ```
  *
- * @see {@link splitKeyValue} - inverse operation
+ * @see {@link splitKeyValue} for the inverse operation
  *
  * @category string
  * @since 4.0.0
@@ -993,7 +991,7 @@ export function joinKeyValue(options) {
  *
  * **When to use**
  *
- * - An encoded string is a delimited list (e.g. CSV values).
+ * Use when an encoded string is a delimited list (e.g. CSV values).
  *
  * **Details**
  *
@@ -1011,7 +1009,7 @@ export function joinKeyValue(options) {
  * // "" -> []
  * ```
  *
- * @see {@link splitKeyValue} - when values are key-value pairs
+ * @see {@link splitKeyValue} when values are key-value pairs
  *
  * @category string
  * @since 4.0.0
@@ -1035,9 +1033,9 @@ export function split(options) {
  * const encode = SchemaGetter.encodeBase64<Uint8Array>()
  * ```
  *
- * @see {@link decodeBase64} - inverse (to `Uint8Array`)
- * @see {@link decodeBase64String} - inverse (to `string`)
- * @see {@link encodeBase64Url} - URL-safe variant
+ * @see {@link decodeBase64} for the inverse operation to `Uint8Array`
+ * @see {@link decodeBase64String} for the inverse operation to `string`
+ * @see {@link encodeBase64Url} for the URL-safe variant
  *
  * @category Base64
  * @since 4.0.0
@@ -1060,9 +1058,9 @@ export function encodeBase64() {
  * const encode = SchemaGetter.encodeBase64Url<Uint8Array>()
  * ```
  *
- * @see {@link decodeBase64Url} - inverse (to `Uint8Array`)
- * @see {@link decodeBase64UrlString} - inverse (to `string`)
- * @see {@link encodeBase64} - standard Base64 variant
+ * @see {@link decodeBase64Url} for the inverse operation to `Uint8Array`
+ * @see {@link decodeBase64UrlString} for the inverse operation to `string`
+ * @see {@link encodeBase64} for the standard Base64 variant
  *
  * @category Base64
  * @since 4.0.0
@@ -1085,8 +1083,8 @@ export function encodeBase64Url() {
  * const encode = SchemaGetter.encodeHex<Uint8Array>()
  * ```
  *
- * @see {@link decodeHex} - inverse (to `Uint8Array`)
- * @see {@link decodeHexString} - inverse (to `string`)
+ * @see {@link decodeHex} for the inverse operation to `Uint8Array`
+ * @see {@link decodeHexString} for the inverse operation to `string`
  *
  * @category Hex
  * @since 4.0.0
@@ -1110,8 +1108,8 @@ export function encodeHex() {
  * // Getter<Uint8Array, string>
  * ```
  *
- * @see {@link decodeBase64String} - decode to `string` instead
- * @see {@link encodeBase64} - inverse operation
+ * @see {@link decodeBase64String} to decode to `string` instead
+ * @see {@link encodeBase64} for the inverse operation
  *
  * @category Base64
  * @since 4.0.0
@@ -1137,8 +1135,8 @@ export function decodeBase64() {
  * // Getter<string, string>
  * ```
  *
- * @see {@link decodeBase64} - decode to `Uint8Array` instead
- * @see {@link encodeBase64} - inverse operation
+ * @see {@link decodeBase64} to decode to `Uint8Array` instead
+ * @see {@link encodeBase64} for the inverse operation
  *
  * @category Base64
  * @since 4.0.0
@@ -1167,8 +1165,8 @@ export function decodeBase64String() {
  * // Getter<Uint8Array, string>
  * ```
  *
- * @see {@link decodeBase64UrlString} - decode to `string` instead
- * @see {@link encodeBase64Url} - inverse operation
+ * @see {@link decodeBase64UrlString} to decode to `string` instead
+ * @see {@link encodeBase64Url} for the inverse operation
  *
  * @category Base64
  * @since 4.0.0
@@ -1197,8 +1195,8 @@ export function decodeBase64Url() {
  * // Getter<string, string>
  * ```
  *
- * @see {@link decodeBase64Url} - decode to `Uint8Array` instead
- * @see {@link encodeBase64Url} - inverse operation
+ * @see {@link decodeBase64Url} to decode to `Uint8Array` instead
+ * @see {@link encodeBase64Url} for the inverse operation
  *
  * @category Base64
  * @since 4.0.0
@@ -1227,8 +1225,8 @@ export function decodeBase64UrlString() {
  * // Getter<Uint8Array, string>
  * ```
  *
- * @see {@link decodeHexString} - decode to `string` instead
- * @see {@link encodeHex} - inverse operation
+ * @see {@link decodeHexString} to decode to `string` instead
+ * @see {@link encodeHex} for the inverse operation
  *
  * @category Hex
  * @since 4.0.0
@@ -1257,8 +1255,8 @@ export function decodeHex() {
  * // Getter<string, string>
  * ```
  *
- * @see {@link decodeHex} - decode to `Uint8Array` instead
- * @see {@link encodeHex} - inverse operation
+ * @see {@link decodeHex} to decode to `Uint8Array` instead
+ * @see {@link encodeHex} for the inverse operation
  *
  * @category Hex
  * @since 4.0.0
@@ -1288,7 +1286,7 @@ export function decodeHexString() {
  * const encode = SchemaGetter.encodeUriComponent<string>()
  * ```
  *
- * @see {@link decodeUriComponent} - inverse operation
+ * @see {@link decodeUriComponent} for the inverse operation
  *
  * @category URI
  * @since 4.0.0
@@ -1312,7 +1310,7 @@ export function encodeUriComponent() {
  * // Getter<string, string>
  * ```
  *
- * @see {@link encodeUriComponent} - inverse operation
+ * @see {@link encodeUriComponent} for the inverse operation
  *
  * @category URI
  * @since 4.0.0
@@ -1333,7 +1331,7 @@ export function decodeUriComponent() {
  *
  * **When to use**
  *
- * - An encoded value represents a date/time and should be decoded to a `DateTime.Utc`.
+ * Use when an encoded value represents a date/time and should be decoded to a `DateTime.Utc`.
  *
  * **Details**
  *
@@ -1353,7 +1351,7 @@ export function decodeUriComponent() {
  * // Getter<DateTime.Utc, string>
  * ```
  *
- * @see {@link Date} - simpler coercion to `Date` (no validation)
+ * @see {@link Date} for a simpler coercion to `Date` (no validation)
  *
  * @category DateTime
  * @since 4.0.0
@@ -1373,7 +1371,7 @@ export function dateTimeUtcFromInput() {
  *
  * **When to use**
  *
- * - Parsing `FormData` from HTTP requests into structured objects.
+ * Use to parse `FormData` from HTTP requests into structured objects.
  *
  * **Details**
  *
@@ -1390,9 +1388,9 @@ export function dateTimeUtcFromInput() {
  * // Getter<TreeObject<string | Blob>, FormData>
  * ```
  *
- * @see {@link encodeFormData} - inverse operation
- * @see {@link makeTreeRecord} - the underlying bracket-path parser
- * @see {@link decodeURLSearchParams} - similar for URLSearchParams
+ * @see {@link encodeFormData} for the inverse operation
+ * @see {@link makeTreeRecord} for the underlying bracket-path parser
+ * @see {@link decodeURLSearchParams} for the URLSearchParams variant
  *
  * @category FormData
  * @since 4.0.0
@@ -1406,7 +1404,7 @@ const collectFormDataEntries = /*#__PURE__*/collectBracketPathEntries(value => t
  *
  * **When to use**
  *
- * - Serializing structured data to `FormData` for HTTP requests.
+ * Use to serialize structured data to `FormData` for HTTP requests.
  *
  * **Details**
  *
@@ -1423,9 +1421,9 @@ const collectFormDataEntries = /*#__PURE__*/collectBracketPathEntries(value => t
  * // Getter<FormData, unknown>
  * ```
  *
- * @see {@link decodeFormData} - inverse operation
- * @see {@link collectBracketPathEntries} - the underlying flattener
- * @see {@link encodeURLSearchParams} - similar for URLSearchParams
+ * @see {@link decodeFormData} for the inverse operation
+ * @see {@link collectBracketPathEntries} for the underlying flattener
+ * @see {@link encodeURLSearchParams} for the URLSearchParams variant
  *
  * @category FormData
  * @since 4.0.0
@@ -1447,7 +1445,7 @@ export function encodeFormData() {
  *
  * **When to use**
  *
- * - Parsing query parameters from URLs into structured objects.
+ * Use to parse query parameters from URLs into structured objects.
  *
  * **Details**
  *
@@ -1464,9 +1462,9 @@ export function encodeFormData() {
  * // Getter<TreeObject<string>, URLSearchParams>
  * ```
  *
- * @see {@link encodeURLSearchParams} - inverse operation
- * @see {@link makeTreeRecord} - the underlying bracket-path parser
- * @see {@link decodeFormData} - similar for FormData
+ * @see {@link encodeURLSearchParams} for the inverse operation
+ * @see {@link makeTreeRecord} for the underlying bracket-path parser
+ * @see {@link decodeFormData} for the FormData variant
  *
  * @category URLSearchParams
  * @since 4.0.0
@@ -1480,7 +1478,7 @@ const collectURLSearchParamsEntries = /*#__PURE__*/collectBracketPathEntries(Pre
  *
  * **When to use**
  *
- * - Serializing structured data to query parameters for URLs.
+ * Use to serialize structured data to query parameters for URLs.
  *
  * **Details**
  *
@@ -1497,9 +1495,9 @@ const collectURLSearchParamsEntries = /*#__PURE__*/collectBracketPathEntries(Pre
  * // Getter<URLSearchParams, unknown>
  * ```
  *
- * @see {@link decodeURLSearchParams} - inverse operation
- * @see {@link collectBracketPathEntries} - the underlying flattener
- * @see {@link encodeFormData} - similar for FormData
+ * @see {@link decodeURLSearchParams} for the inverse operation
+ * @see {@link collectBracketPathEntries} for the underlying flattener
+ * @see {@link encodeFormData} for the FormData variant
  *
  * @category URLSearchParams
  * @since 4.0.0
@@ -1529,7 +1527,7 @@ function bracketPathToTokens(bracketPath) {
  *
  * **When to use**
  *
- * - Parsing FormData or URLSearchParams entries into structured objects.
+ * Use to parse FormData or URLSearchParams entries into structured objects.
  * - You have flat key-value pairs with bracket-path keys that need nesting.
  *
  * **Details**
@@ -1537,7 +1535,7 @@ function bracketPathToTokens(bracketPath) {
  * - A bracket path is a string like `"user[address][city]"` that describes nested
  *   object/array structure.
  * - Interprets bracket paths and constructs the corresponding nested object.
- * - Mutates and returns a new object (does not mutate the input array).
+ * - Builds and returns a nested object from the input entries.
  * - Supported syntax:
  *   - `"foo"` → object key `"foo"`
  *   - `"foo[bar]"` → nested `{ foo: { bar: ... } }`
@@ -1559,9 +1557,9 @@ function bracketPathToTokens(bracketPath) {
  * // { user: { name: "Alice", tags: ["admin", "editor"] } }
  * ```
  *
- * @see {@link collectBracketPathEntries} - inverse operation (tree to flat entries)
- * @see {@link decodeFormData} - uses this internally
- * @see {@link decodeURLSearchParams} - uses this internally
+ * @see {@link collectBracketPathEntries} for the inverse operation (tree to flat entries)
+ * @see {@link decodeFormData} for a higher-level FormData decoder
+ * @see {@link decodeURLSearchParams} for a higher-level URLSearchParams decoder
  *
  * @category Tree
  * @since 4.0.0
@@ -1615,7 +1613,7 @@ export function makeTreeRecord(bracketPathEntries) {
  *
  * **When to use**
  *
- * - Serializing structured objects to flat key-value entries.
+ * Use to serialize structured objects to flat key-value entries.
  * - Building custom `FormData` or `URLSearchParams` encoders.
  *
  * **Details**
@@ -1639,9 +1637,9 @@ export function makeTreeRecord(bracketPathEntries) {
  * // [["user[name]", "Alice"], ["user[tags]", "admin"], ["user[tags]", "editor"]]
  * ```
  *
- * @see {@link makeTreeRecord} - inverse operation (flat entries to tree)
- * @see {@link encodeFormData} - uses this internally
- * @see {@link encodeURLSearchParams} - uses this internally
+ * @see {@link makeTreeRecord} for the inverse operation (flat entries to tree)
+ * @see {@link encodeFormData} for a higher-level FormData encoder
+ * @see {@link encodeURLSearchParams} for a higher-level URLSearchParams encoder
  *
  * @category Tree
  * @since 4.0.0