effect 4.0.0-beta.69 → 4.0.0-beta.70

package/dist/SchemaGetter.js

@@ -97,17 +97,18 @@ import * as Str from "./String.js";
 /**
  * A composable transformation from an encoded type `E` to a decoded type `T`.
  *
- * 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`.
+ * **When to use**
  *
- * Use this when:
  * - Building custom schema transformations with `Schema.decodeTo` or `Schema.decode`.
  * - Composing multiple transformation steps into a single getter.
  *
- * Behavior:
+ * **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`.
  * - 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`.
@@ -124,10 +125,9 @@ import * as Str from "./String.js";
  * // composed: Getter<number, string> — parses then doubles
  * ```
  *
- * See also:
- * - {@link transform} — create a getter from a pure function
- * - {@link passthrough} — identity getter
- * - {@link transformOrFail} — fallible transformation
+ * @see {@link transform} - create a getter from a pure function
+ * @see {@link passthrough} - identity getter
+ * @see {@link transformOrFail} - fallible transformation
  *
  * @category models
  * @since 4.0.0
@@ -154,11 +154,13 @@ export class Getter extends Pipeable.Class {
 /**
  * Creates a getter that always produces the given constant value, ignoring the input.
  *
- * Use this when:
+ * **When to use**
+ *
  * - A schema field should always decode to a fixed value.
  * - You need a placeholder getter that produces a known default.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, no side effects.
  * - Always returns `Option.some(t)` regardless of whether input is `Some` or `None`.
  *
@@ -171,9 +173,8 @@ export class Getter extends Pipeable.Class {
  * // alwaysZero: Getter<0, unknown> — always produces 0
  * ```
  *
- * See also:
- * - {@link transform} — when you need to use the input value
- * - {@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
@@ -184,11 +185,13 @@ export function succeed(t) {
 /**
  * Creates a getter that always fails with the given issue.
  *
- * Use this when:
+ * **When to use**
+ *
  * - A transformation should unconditionally reject input.
  * - Building custom validation getters that produce specific error types.
  *
- * Behavior:
+ * **Details**
+ *
  * - Always fails with the `Issue` returned by `f`.
  * - The failure function receives the original `Option<E>` input for error context.
  *
@@ -202,9 +205,8 @@ export function succeed(t) {
  * )
  * ```
  *
- * See also:
- * - {@link forbidden} — convenience for `Forbidden` issues
- * - {@link checkEffect} — fail conditionally based on input value
+ * @see {@link forbidden} - convenience for `Forbidden` issues
+ * @see {@link checkEffect} - fail conditionally based on input value
  *
  * @category constructors
  * @since 4.0.0
@@ -215,11 +217,13 @@ export function fail(f) {
 /**
  * Creates a getter that always fails with a `Forbidden` issue.
  *
- * Use this when:
+ * **When to use**
+ *
  * - A field or direction (encode/decode) should be disallowed entirely.
  * - You want a clear "forbidden" error message in schema validation output.
  *
- * Behavior:
+ * **Details**
+ *
  * - Always fails with `Issue.Forbidden`.
  * - The message function receives the `Option<E>` input for context.
  *
@@ -233,8 +237,7 @@ export function fail(f) {
  * )
  * ```
  *
- * See also:
- * - {@link fail} — fail with a custom issue type
+ * @see {@link fail} - fail with a custom issue type
  *
  * @category constructors
  * @since 4.0.0
@@ -260,11 +263,13 @@ export function passthroughSubtype() {
 /**
  * Creates a getter that handles the case when the input is absent (`Option.None`).
  *
- * Use this when:
+ * **When to use**
+ *
  * - You need to provide a fallback or computed value for missing struct keys.
  * - Building custom "default value" logic more complex than {@link withDefault}.
  *
- * Behavior:
+ * **Details**
+ *
  * - When input is `None`, calls `f` to produce the result.
  * - When input is `Some`, passes it through unchanged.
  * - `f` receives the parse options and may return `None` to keep the value absent.
@@ -279,10 +284,9 @@ export function passthroughSubtype() {
  * )
  * ```
  *
- * See also:
- * - {@link required} — fails if input is absent
- * - {@link withDefault} — simpler default value for undefined inputs
- * - {@link onSome} — handle only present values
+ * @see {@link required} - fails if input is absent
+ * @see {@link withDefault} - simpler default value for undefined inputs
+ * @see {@link onSome} - handle only present values
  *
  * @category constructors
  * @since 4.0.0
@@ -293,11 +297,13 @@ export function onNone(f) {
 /**
  * Creates a getter that fails with `MissingKey` if the input is absent (`Option.None`).
  *
- * Use this when:
+ * **When to use**
+ *
  * - A struct field must be present in the encoded input.
  * - You want schema validation to report a missing key error.
  *
- * Behavior:
+ * **Details**
+ *
  * - When input is `None`, fails with `Issue.MissingKey`.
  * - When input is `Some`, passes it through unchanged.
  * - Optional `annotations` customize the error message for the missing key.
@@ -310,9 +316,8 @@ export function onNone(f) {
  * const mustExist = SchemaGetter.required<string>()
  * ```
  *
- * See also:
- * - {@link onNone} — provide a fallback instead of failing
- * - {@link withDefault} — substitute a default for undefined values
+ * @see {@link onNone} - provide a fallback instead of failing
+ * @see {@link withDefault} - substitute a default for undefined values
  *
  * @category constructors
  * @since 4.0.0
@@ -323,11 +328,13 @@ export function required(annotations) {
 /**
  * Creates a getter that handles present values (`Option.Some`), passing `None` through.
  *
- * Use this when:
+ * **When to use**
+ *
  * - You need to transform or validate only when a value is present.
  * - Missing keys should remain absent in the output.
  *
- * Behavior:
+ * **Details**
+ *
  * - When input is `None`, returns `None` (no-op).
  * - When input is `Some(e)`, calls `f(e, options)` to produce the result.
  * - `f` may return `None` to omit the value, or fail with an `Issue`.
@@ -342,10 +349,9 @@ export function required(annotations) {
  * )
  * ```
  *
- * See also:
- * - {@link onNone} — handle only absent values
- * - {@link transform} — simpler pure transformation of present values
- * - {@link transformOrFail} — fallible transformation of present values
+ * @see {@link onNone} - handle only absent values
+ * @see {@link transform} - simpler pure transformation of present values
+ * @see {@link transformOrFail} - fallible transformation of present values
  *
  * @category constructors
  * @since 4.0.0
@@ -356,11 +362,13 @@ export function onSome(f) {
 /**
  * Creates a getter that validates a value using an effectful check function.
  *
- * Use this when:
+ * **When to use**
+ *
  * - 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.
  *
- * Behavior:
+ * **Details**
+ *
  * - Only runs when input is `Some` — `None` passes through.
  * - The check function returns a validation result:
  *   - `undefined` or `true` — value is valid, passes through.
@@ -380,9 +388,8 @@ export function onSome(f) {
  * )
  * ```
  *
- * See also:
- * - {@link transform} — when you need to change the value, not just validate
- * - {@link fail} — unconditional failure
+ * @see {@link transform} - when you need to change the value, not just validate
+ * @see {@link fail} - unconditional failure
  *
  * @category constructors
  * @since 4.0.0
@@ -398,14 +405,15 @@ export function checkEffect(f) {
 /**
  * Creates a getter that applies a pure function to present values.
  *
- * This is the most commonly used constructor. It transforms `Some(e)` to
- * `Some(f(e))` and leaves `None` unchanged.
+ * **When to use**
  *
- * Use this when:
  * - You have a pure, infallible transformation between types.
  * - Building encode/decode pairs for `Schema.decodeTo`.
  *
- * Behavior:
+ * **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.
@@ -423,10 +431,9 @@ export function checkEffect(f) {
  * )
  * ```
  *
- * See also:
- * - {@link transformOrFail} — when the transformation can fail
- * - {@link transformOptional} — when you need to handle `None` inputs
- * - {@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
@@ -437,11 +444,13 @@ export function transform(f) {
 /**
  * Creates a getter that applies a fallible, effectful transformation to present values.
  *
- * Use this when:
+ * **When to use**
+ *
  * - The transformation may fail (e.g. parsing, validation).
  * - The transformation needs Effect services or is async.
  *
- * Behavior:
+ * **Details**
+ *
  * - Skips `None` inputs — only called when a value is present.
  * - On success, wraps the result in `Some`.
  * - On failure, propagates the `Issue`.
@@ -461,9 +470,8 @@ export function transform(f) {
  * )
  * ```
  *
- * See also:
- * - {@link transform} — when transformation cannot fail
- * - {@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
@@ -474,11 +482,13 @@ export function transformOrFail(f) {
 /**
  * Creates a getter that transforms the full `Option` — both present and absent values.
  *
- * Use this when:
+ * **When to use**
+ *
  * - You need to handle both `Some` and `None` cases.
  * - You want to turn a present value into absent, or vice versa.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, never fails.
  * - Receives the full `Option<E>` and must return `Option<T>`.
  *
@@ -492,9 +502,8 @@ export function transformOrFail(f) {
  * )
  * ```
  *
- * See also:
- * - {@link transform} — simpler, only handles present values
- * - {@link omit} — always returns `None`
+ * @see {@link transform} - simpler, only handles present values
+ * @see {@link omit} - always returns `None`
  *
  * @category constructors
  * @since 4.0.0
@@ -505,10 +514,12 @@ export function transformOptional(f) {
 /**
  * Creates a getter that always returns `None`, effectively omitting the value from output.
  *
- * Use this when:
+ * **When to use**
+ *
  * - A field should be excluded during decoding or encoding.
  *
- * Behavior:
+ * **Details**
+ *
  * - Always returns `Option.None` regardless of input.
  * - Never fails.
  *
@@ -520,9 +531,8 @@ export function transformOptional(f) {
  * const omitField = SchemaGetter.omit<string>()
  * ```
  *
- * See also:
- * - {@link transformOptional} — when you want conditional omission
- * - {@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
@@ -533,10 +543,12 @@ export function omit() {
 /**
  * Creates a getter that replaces `undefined` values with a default.
  *
- * Use this when:
+ * **When to use**
+ *
  * - A field may be `undefined` in the encoded input and should have a fallback.
  *
- * Behavior:
+ * **Details**
+ *
  * - If the input is `Some(undefined)` or `None`, produces `Some(T)`.
  * - If the input is `Some(value)` where value is not `undefined`, passes it through.
  * - `defaultValue` is an `Effect` that will be executed each time a default is needed.
@@ -550,9 +562,8 @@ export function omit() {
  * // Getter<number, number | undefined>
  * ```
  *
- * See also:
- * - {@link onNone} — handle only absent keys (not `undefined` values)
- * - {@link required} — fail instead of providing a default
+ * @see {@link onNone} - handle only absent keys (not `undefined` values)
+ * @see {@link required} - fail instead of providing a default
  *
  * @category constructors
  * @since 4.0.0
@@ -566,10 +577,12 @@ export function withDefault(defaultValue) {
 /**
  * Coerces any value to a `string` using the global `String()` constructor.
  *
- * Use this when:
+ * **When to use**
+ *
  * - You need a string representation of an arbitrary encoded value.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, never fails.
  * - Delegates to `globalThis.String`.
  *
@@ -582,8 +595,7 @@ export function withDefault(defaultValue) {
  * // Getter<string, number>
  * ```
  *
- * See also:
- * - {@link transform} — for custom string conversions
+ * @see {@link transform} - for custom string conversions
  *
  * @category Coercions
  * @since 4.0.0
@@ -594,10 +606,12 @@ export function String() {
 /**
  * Coerces any value to a `number` using the global `Number()` constructor.
  *
- * Use this when:
+ * **When to use**
+ *
  * - You need numeric coercion of an encoded value.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, never fails (may produce `NaN` for non-numeric inputs).
  * - Delegates to `globalThis.Number`.
  *
@@ -610,8 +624,7 @@ export function String() {
  * // Getter<number, string>
  * ```
  *
- * See also:
- * - {@link transformOrFail} — for validated number parsing
+ * @see {@link transformOrFail} - for validated number parsing
  *
  * @category Coercions
  * @since 4.0.0
@@ -622,10 +635,12 @@ export function Number() {
 /**
  * Coerces any value to a `boolean` using the global `Boolean()` constructor.
  *
- * Use this when:
+ * **When to use**
+ *
  * - You need boolean coercion (truthiness check) of an encoded value.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, never fails.
  * - Delegates to `globalThis.Boolean`.
  *
@@ -647,10 +662,12 @@ export function Boolean() {
 /**
  * Coerces a value to `bigint` using the global `BigInt()` constructor.
  *
- * Use this when:
+ * **When to use**
+ *
  * - You need to convert strings, numbers, or booleans to `bigint`.
  *
- * Behavior:
+ * **Details**
+ *
  * - Delegates to `globalThis.BigInt`.
  * - Throws at runtime if the input cannot be converted (e.g. non-numeric string).
  *
@@ -672,10 +689,12 @@ export function BigInt() {
 /**
  * Coerces a value to a `Date` using `new Date(input)`.
  *
- * Use this when:
+ * **When to use**
+ *
  * - You need to parse a string, number, or Date into a `Date` object.
  *
- * Behavior:
+ * **Details**
+ *
  * - Delegates to `new globalThis.Date(input)`.
  * - Does not validate the result — may produce an invalid Date.
  *
@@ -688,8 +707,7 @@ export function BigInt() {
  * // Getter<Date, string>
  * ```
  *
- * See also:
- * - {@link dateTimeUtcFromInput} — validated DateTime parsing
+ * @see {@link dateTimeUtcFromInput} - validated DateTime parsing
  *
  * @category Coercions
  * @since 4.0.0
@@ -700,7 +718,8 @@ export function Date() {
 /**
  * Trims whitespace from both ends of a string.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, delegates to `String.trim`.
  *
  * **Example** (Trim whitespace)
@@ -720,7 +739,8 @@ export function trim() {
 /**
  * Capitalizes the first character of a string.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, delegates to `String.capitalize`.
  *
  * **Example** (Capitalize string)
@@ -740,7 +760,8 @@ export function capitalize() {
 /**
  * Lowercases the first character of a string.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, delegates to `String.uncapitalize`.
  *
  * **Example** (Uncapitalize string)
@@ -760,7 +781,8 @@ export function uncapitalize() {
 /**
  * Converts a `snake_case` string to `camelCase`.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, delegates to `String.snakeToCamel`.
  *
  * **Example** (Snake to camel)
@@ -771,8 +793,7 @@ export function uncapitalize() {
  * const toCamel = SchemaGetter.snakeToCamel<string>()
  * ```
  *
- * See also:
- * - {@link camelToSnake} — inverse operation
+ * @see {@link camelToSnake} - inverse operation
  *
  * @category string
  * @since 4.0.0
@@ -783,7 +804,8 @@ export function snakeToCamel() {
 /**
  * Converts a `camelCase` string to `snake_case`.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, delegates to `String.camelToSnake`.
  *
  * **Example** (Camel to snake)
@@ -794,8 +816,7 @@ export function snakeToCamel() {
  * const toSnake = SchemaGetter.camelToSnake<string>()
  * ```
  *
- * See also:
- * - {@link snakeToCamel} — inverse operation
+ * @see {@link snakeToCamel} - inverse operation
  *
  * @category string
  * @since 4.0.0
@@ -806,7 +827,8 @@ export function camelToSnake() {
 /**
  * Converts a string to lowercase.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, delegates to `String.toLowerCase`.
  *
  * **Example** (To lowercase)
@@ -817,8 +839,7 @@ export function camelToSnake() {
  * const lower = SchemaGetter.toLowerCase<string>()
  * ```
  *
- * See also:
- * - {@link toUpperCase} — inverse operation
+ * @see {@link toUpperCase} - inverse operation
  *
  * @category string
  * @since 4.0.0
@@ -829,7 +850,8 @@ export function toLowerCase() {
 /**
  * Converts a string to uppercase.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, delegates to `String.toUpperCase`.
  *
  * **Example** (To uppercase)
@@ -840,8 +862,7 @@ export function toLowerCase() {
  * const upper = SchemaGetter.toUpperCase<string>()
  * ```
  *
- * See also:
- * - {@link toLowerCase} — inverse operation
+ * @see {@link toLowerCase} - inverse operation
  *
  * @category string
  * @since 4.0.0
@@ -860,10 +881,12 @@ export function parseJson(options) {
 /**
  * Stringifies a present value using `JSON.stringify`.
  *
- * Use this when:
+ * **When to use**
+ *
  * - A decoded value needs to be serialized to JSON text during encoding.
  *
- * Behavior:
+ * **Details**
+ *
  * - Skips `None` inputs.
  * - On thrown stringify failures, such as circular references, fails with
  *   `Issue.InvalidValue`.
@@ -882,8 +905,7 @@ export function parseJson(options) {
  * // Getter<string, unknown>
  * ```
  *
- * See also:
- * - {@link parseJson} — inverse operation
+ * @see {@link parseJson} - inverse operation
  *
  * @category Json
  * @since 4.0.0
@@ -899,10 +921,12 @@ export function stringifyJson(options) {
 /**
  * Parses a string into a record of key-value pairs.
  *
- * Use this when:
+ * **When to use**
+ *
  * - An encoded string contains delimited key-value pairs (e.g. `"a=1,b=2"`).
  *
- * Behavior:
+ * **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.
@@ -916,9 +940,8 @@ export function stringifyJson(options) {
  * // "a=1,b=2" -> { a: "1", b: "2" }
  * ```
  *
- * See also:
- * - {@link joinKeyValue} — inverse operation
- * - {@link split} — split into an array of strings
+ * @see {@link joinKeyValue} - inverse operation
+ * @see {@link split} - split into an array of strings
  *
  * @category string
  * @since 4.0.0
@@ -937,10 +960,12 @@ export function splitKeyValue(options) {
 /**
  * Joins a record of key-value pairs into a delimited string.
  *
- * Use this when:
+ * **When to use**
+ *
  * - A decoded record needs to be serialized as a delimited key-value string.
  *
- * Behavior:
+ * **Details**
+ *
  * - Joins entries with `separator` (default `,`) and key/value with `keyValueSeparator` (default `=`).
  * - Pure, never fails.
  *
@@ -953,8 +978,7 @@ export function splitKeyValue(options) {
  * // { a: "1", b: "2" } -> "a=1,b=2"
  * ```
  *
- * See also:
- * - {@link splitKeyValue} — inverse operation
+ * @see {@link splitKeyValue} - inverse operation
  *
  * @category string
  * @since 4.0.0
@@ -967,10 +991,12 @@ export function joinKeyValue(options) {
 /**
  * Splits a string into an array of strings by a separator.
  *
- * Use this when:
+ * **When to use**
+ *
  * - An encoded string is a delimited list (e.g. CSV values).
  *
- * Behavior:
+ * **Details**
+ *
  * - Splits by `separator` (default `,`).
  * - An empty string produces an empty array (not `[""]`).
  * - Pure, never fails.
@@ -985,8 +1011,7 @@ export function joinKeyValue(options) {
  * // "" -> []
  * ```
  *
- * See also:
- * - {@link splitKeyValue} — when values are key-value pairs
+ * @see {@link splitKeyValue} - when values are key-value pairs
  *
  * @category string
  * @since 4.0.0
@@ -998,7 +1023,8 @@ export function split(options) {
 /**
  * Encodes a `Uint8Array` or string to a Base64 string.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, never fails.
  *
  * **Example** (Encode to Base64)
@@ -1009,10 +1035,9 @@ export function split(options) {
  * const encode = SchemaGetter.encodeBase64<Uint8Array>()
  * ```
  *
- * See also:
- * - {@link decodeBase64} — inverse (to `Uint8Array`)
- * - {@link decodeBase64String} — inverse (to `string`)
- * - {@link encodeBase64Url} — URL-safe variant
+ * @see {@link decodeBase64} - inverse (to `Uint8Array`)
+ * @see {@link decodeBase64String} - inverse (to `string`)
+ * @see {@link encodeBase64Url} - URL-safe variant
  *
  * @category Base64
  * @since 4.0.0
@@ -1023,7 +1048,8 @@ export function encodeBase64() {
 /**
  * Encodes a `Uint8Array` or string to a URL-safe Base64 string.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, never fails.
  *
  * **Example** (Encode to Base64Url)
@@ -1034,10 +1060,9 @@ export function encodeBase64() {
  * const encode = SchemaGetter.encodeBase64Url<Uint8Array>()
  * ```
  *
- * See also:
- * - {@link decodeBase64Url} — inverse (to `Uint8Array`)
- * - {@link decodeBase64UrlString} — inverse (to `string`)
- * - {@link encodeBase64} — standard Base64 variant
+ * @see {@link decodeBase64Url} - inverse (to `Uint8Array`)
+ * @see {@link decodeBase64UrlString} - inverse (to `string`)
+ * @see {@link encodeBase64} - standard Base64 variant
  *
  * @category Base64
  * @since 4.0.0
@@ -1048,7 +1073,8 @@ export function encodeBase64Url() {
 /**
  * Encodes a `Uint8Array` or string to a hexadecimal string.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, never fails.
  *
  * **Example** (Encode to hex)
@@ -1059,9 +1085,8 @@ export function encodeBase64Url() {
  * const encode = SchemaGetter.encodeHex<Uint8Array>()
  * ```
  *
- * See also:
- * - {@link decodeHex} — inverse (to `Uint8Array`)
- * - {@link decodeHexString} — inverse (to `string`)
+ * @see {@link decodeHex} - inverse (to `Uint8Array`)
+ * @see {@link decodeHexString} - inverse (to `string`)
  *
  * @category Hex
  * @since 4.0.0
@@ -1072,7 +1097,8 @@ export function encodeHex() {
 /**
  * Decodes a Base64 string to a `Uint8Array`.
  *
- * Behavior:
+ * **Details**
+ *
  * - Fails with `Issue.InvalidValue` if the input is not valid Base64.
  *
  * **Example** (Decode Base64 to bytes)
@@ -1084,9 +1110,8 @@ export function encodeHex() {
  * // Getter<Uint8Array, string>
  * ```
  *
- * See also:
- * - {@link decodeBase64String} — decode to `string` instead
- * - {@link encodeBase64} — inverse operation
+ * @see {@link decodeBase64String} - decode to `string` instead
+ * @see {@link encodeBase64} - inverse operation
  *
  * @category Base64
  * @since 4.0.0
@@ -1099,7 +1124,8 @@ export function decodeBase64() {
 /**
  * Decodes a Base64 string to a UTF-8 `string`.
  *
- * Behavior:
+ * **Details**
+ *
  * - Fails with `Issue.InvalidValue` if the input is not valid Base64.
  *
  * **Example** (Decode Base64 to string)
@@ -1111,9 +1137,8 @@ export function decodeBase64() {
  * // Getter<string, string>
  * ```
  *
- * See also:
- * - {@link decodeBase64} — decode to `Uint8Array` instead
- * - {@link encodeBase64} — inverse operation
+ * @see {@link decodeBase64} - decode to `Uint8Array` instead
+ * @see {@link encodeBase64} - inverse operation
  *
  * @category Base64
  * @since 4.0.0
@@ -1129,7 +1154,8 @@ export function decodeBase64String() {
 /**
  * Decodes a URL-safe Base64 string to a `Uint8Array`.
  *
- * Behavior:
+ * **Details**
+ *
  * - Fails with `Issue.InvalidValue` if the input is not valid Base64Url.
  *
  * **Example** (Decode Base64Url to bytes)
@@ -1141,9 +1167,8 @@ export function decodeBase64String() {
  * // Getter<Uint8Array, string>
  * ```
  *
- * See also:
- * - {@link decodeBase64UrlString} — decode to `string` instead
- * - {@link encodeBase64Url} — inverse operation
+ * @see {@link decodeBase64UrlString} - decode to `string` instead
+ * @see {@link encodeBase64Url} - inverse operation
  *
  * @category Base64
  * @since 4.0.0
@@ -1159,7 +1184,8 @@ export function decodeBase64Url() {
 /**
  * Decodes a URL-safe Base64 string to a UTF-8 `string`.
  *
- * Behavior:
+ * **Details**
+ *
  * - Fails with `Issue.InvalidValue` if the input is not valid Base64Url.
  *
  * **Example** (Decode Base64Url to string)
@@ -1171,9 +1197,8 @@ export function decodeBase64Url() {
  * // Getter<string, string>
  * ```
  *
- * See also:
- * - {@link decodeBase64Url} — decode to `Uint8Array` instead
- * - {@link encodeBase64Url} — inverse operation
+ * @see {@link decodeBase64Url} - decode to `Uint8Array` instead
+ * @see {@link encodeBase64Url} - inverse operation
  *
  * @category Base64
  * @since 4.0.0
@@ -1189,7 +1214,8 @@ export function decodeBase64UrlString() {
 /**
  * Decodes a hexadecimal string to a `Uint8Array`.
  *
- * Behavior:
+ * **Details**
+ *
  * - Fails with `Issue.InvalidValue` if the input is not valid hex.
  *
  * **Example** (Decode hex to bytes)
@@ -1201,9 +1227,8 @@ export function decodeBase64UrlString() {
  * // Getter<Uint8Array, string>
  * ```
  *
- * See also:
- * - {@link decodeHexString} — decode to `string` instead
- * - {@link encodeHex} — inverse operation
+ * @see {@link decodeHexString} - decode to `string` instead
+ * @see {@link encodeHex} - inverse operation
  *
  * @category Hex
  * @since 4.0.0
@@ -1219,7 +1244,8 @@ export function decodeHex() {
 /**
  * Decodes a hexadecimal string to a UTF-8 `string`.
  *
- * Behavior:
+ * **Details**
+ *
  * - Fails with `Issue.InvalidValue` if the input is not valid hex.
  *
  * **Example** (Decode hex to string)
@@ -1231,9 +1257,8 @@ export function decodeHex() {
  * // Getter<string, string>
  * ```
  *
- * See also:
- * - {@link decodeHex} — decode to `Uint8Array` instead
- * - {@link encodeHex} — inverse operation
+ * @see {@link decodeHex} - decode to `Uint8Array` instead
+ * @see {@link encodeHex} - inverse operation
  *
  * @category Hex
  * @since 4.0.0
@@ -1249,7 +1274,8 @@ export function decodeHexString() {
 /**
  * Encodes a present string using `encodeURIComponent`.
  *
- * Behavior:
+ * **Details**
+ *
  * - Skips `None` inputs.
  * - May throw a `URIError` for malformed surrogate pairs; this exception is not
  *   converted into an `Issue`.
@@ -1262,8 +1288,7 @@ export function decodeHexString() {
  * const encode = SchemaGetter.encodeUriComponent<string>()
  * ```
  *
- * See also:
- * - {@link decodeUriComponent} - inverse operation
+ * @see {@link decodeUriComponent} - inverse operation
  *
  * @category URI
  * @since 4.0.0
@@ -1274,7 +1299,8 @@ export function encodeUriComponent() {
 /**
  * Decodes a URI component encoded string using `decodeURIComponent`.
  *
- * Behavior:
+ * **Details**
+ *
  * - Fails with `Issue.InvalidValue` if the input contains malformed percent-encoding sequences.
  *
  * **Example** (Decode a URI component)
@@ -1286,8 +1312,7 @@ export function encodeUriComponent() {
  * // Getter<string, string>
  * ```
  *
- * See also:
- * - {@link encodeUriComponent} - inverse operation
+ * @see {@link encodeUriComponent} - inverse operation
  *
  * @category URI
  * @since 4.0.0
@@ -1306,14 +1331,15 @@ export function decodeUriComponent() {
 /**
  * Parses a `DateTime.Input` value into a `DateTime.Utc`.
  *
- * Accepted input includes existing `DateTime` values, partial date/time parts,
- * instant objects, zoned instant objects, JavaScript `Date` instances, epoch
- * milliseconds, and date strings.
+ * **When to use**
  *
- * Use this when:
  * - An encoded value represents a date/time and should be decoded to a `DateTime.Utc`.
  *
- * Behavior:
+ * **Details**
+ *
+ * - Accepted input includes existing `DateTime` values, partial date/time parts,
+ *   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
  *   `DateTime`.
@@ -1327,8 +1353,7 @@ export function decodeUriComponent() {
  * // Getter<DateTime.Utc, string>
  * ```
  *
- * See also:
- * - {@link Date} — simpler coercion to `Date` (no validation)
+ * @see {@link Date} - simpler coercion to `Date` (no validation)
  *
  * @category DateTime
  * @since 4.0.0
@@ -1346,10 +1371,12 @@ export function dateTimeUtcFromInput() {
 /**
  * Decodes a `FormData` object into a nested tree structure using bracket-path notation.
  *
- * Use this when:
+ * **When to use**
+ *
  * - Parsing `FormData` from HTTP requests into structured objects.
  *
- * Behavior:
+ * **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`.
@@ -1363,10 +1390,9 @@ export function dateTimeUtcFromInput() {
  * // Getter<TreeObject<string | Blob>, FormData>
  * ```
  *
- * See also:
- * - {@link encodeFormData} — inverse operation
- * - {@link makeTreeRecord} — the underlying bracket-path parser
- * - {@link decodeURLSearchParams} — similar for URLSearchParams
+ * @see {@link encodeFormData} - inverse operation
+ * @see {@link makeTreeRecord} - the underlying bracket-path parser
+ * @see {@link decodeURLSearchParams} - similar for URLSearchParams
  *
  * @category FormData
  * @since 4.0.0
@@ -1378,10 +1404,12 @@ const collectFormDataEntries = /*#__PURE__*/collectBracketPathEntries(value => t
 /**
  * Encodes a nested object into a `FormData` instance using bracket-path notation.
  *
- * Use this when:
+ * **When to use**
+ *
  * - Serializing structured data to `FormData` for HTTP requests.
  *
- * Behavior:
+ * **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`.
@@ -1395,10 +1423,9 @@ const collectFormDataEntries = /*#__PURE__*/collectBracketPathEntries(value => t
  * // Getter<FormData, unknown>
  * ```
  *
- * See also:
- * - {@link decodeFormData} — inverse operation
- * - {@link collectBracketPathEntries} — the underlying flattener
- * - {@link encodeURLSearchParams} — similar for URLSearchParams
+ * @see {@link decodeFormData} - inverse operation
+ * @see {@link collectBracketPathEntries} - the underlying flattener
+ * @see {@link encodeURLSearchParams} - similar for URLSearchParams
  *
  * @category FormData
  * @since 4.0.0
@@ -1418,10 +1445,12 @@ export function encodeFormData() {
 /**
  * Decodes a `URLSearchParams` object into a nested tree structure using bracket-path notation.
  *
- * Use this when:
+ * **When to use**
+ *
  * - Parsing query parameters from URLs into structured objects.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, never fails.
  * - Interprets bracket-path keys (e.g. `user[name]`, `items[0]`) to build nested objects/arrays.
  * - Leaf values are `string`.
@@ -1435,10 +1464,9 @@ export function encodeFormData() {
  * // Getter<TreeObject<string>, URLSearchParams>
  * ```
  *
- * See also:
- * - {@link encodeURLSearchParams} — inverse operation
- * - {@link makeTreeRecord} — the underlying bracket-path parser
- * - {@link decodeFormData} — similar for FormData
+ * @see {@link encodeURLSearchParams} - inverse operation
+ * @see {@link makeTreeRecord} - the underlying bracket-path parser
+ * @see {@link decodeFormData} - similar for FormData
  *
  * @category URLSearchParams
  * @since 4.0.0
@@ -1450,10 +1478,12 @@ const collectURLSearchParamsEntries = /*#__PURE__*/collectBracketPathEntries(Pre
 /**
  * Encodes a nested object into a `URLSearchParams` instance using bracket-path notation.
  *
- * Use this when:
+ * **When to use**
+ *
  * - Serializing structured data to query parameters for URLs.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, never fails.
  * - Flattens nested objects/arrays into bracket-path keys.
  * - Non-object inputs produce an empty `URLSearchParams`.
@@ -1467,10 +1497,9 @@ const collectURLSearchParamsEntries = /*#__PURE__*/collectBracketPathEntries(Pre
  * // Getter<URLSearchParams, unknown>
  * ```
  *
- * See also:
- * - {@link decodeURLSearchParams} — inverse operation
- * - {@link collectBracketPathEntries} — the underlying flattener
- * - {@link encodeFormData} — similar for FormData
+ * @see {@link decodeURLSearchParams} - inverse operation
+ * @see {@link collectBracketPathEntries} - the underlying flattener
+ * @see {@link encodeFormData} - similar for FormData
  *
  * @category URLSearchParams
  * @since 4.0.0
@@ -1498,15 +1527,16 @@ function bracketPathToTokens(bracketPath) {
 /**
  * Builds a nested tree object from a list of bracket-path entries.
  *
- * A bracket path is a string like `"user[address][city]"` that describes nested
- * object/array structure. This function interprets those paths and constructs the
- * corresponding nested object.
+ * **When to use**
  *
- * Use this when:
  * - Parsing FormData or URLSearchParams entries into structured objects.
  * - You have flat key-value pairs with bracket-path keys that need nesting.
  *
- * Behavior:
+ * **Details**
+ *
+ * - 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).
  * - Supported syntax:
  *   - `"foo"` → object key `"foo"`
@@ -1529,10 +1559,9 @@ function bracketPathToTokens(bracketPath) {
  * // { user: { name: "Alice", tags: ["admin", "editor"] } }
  * ```
  *
- * See also:
- * - {@link collectBracketPathEntries} — inverse operation (tree to flat entries)
- * - {@link decodeFormData} — uses this internally
- * - {@link decodeURLSearchParams} — uses this internally
+ * @see {@link collectBracketPathEntries} - inverse operation (tree to flat entries)
+ * @see {@link decodeFormData} - uses this internally
+ * @see {@link decodeURLSearchParams} - uses this internally
  *
  * @category Tree
  * @since 4.0.0
@@ -1584,14 +1613,16 @@ export function makeTreeRecord(bracketPathEntries) {
 /**
  * Flattens a nested object into bracket-path entries, filtering leaf values by a type guard.
  *
- * This is the inverse of {@link makeTreeRecord}. It takes a nested object and produces
- * flat `[bracketPath, value]` pairs suitable for `FormData` or `URLSearchParams`.
+ * **When to use**
  *
- * Use this when:
  * - Serializing structured objects to flat key-value entries.
  * - Building custom `FormData` or `URLSearchParams` encoders.
  *
- * Behavior:
+ * **Details**
+ *
+ * - This is the inverse of {@link makeTreeRecord}.
+ * - Takes a nested object and produces flat `[bracketPath, value]` pairs suitable for
+ *   `FormData` or `URLSearchParams`.
  * - Returns a curried function: first call provides the leaf type guard, second call provides the object.
  * - Recursively traverses objects and arrays.
  * - If all elements of an array are leaves, encodes them as multiple entries with the same key
@@ -1608,10 +1639,9 @@ export function makeTreeRecord(bracketPathEntries) {
  * // [["user[name]", "Alice"], ["user[tags]", "admin"], ["user[tags]", "editor"]]
  * ```
  *
- * See also:
- * - {@link makeTreeRecord} — inverse operation (flat entries to tree)
- * - {@link encodeFormData} — uses this internally
- * - {@link encodeURLSearchParams} — uses this internally
+ * @see {@link makeTreeRecord} - inverse operation (flat entries to tree)
+ * @see {@link encodeFormData} - uses this internally
+ * @see {@link encodeURLSearchParams} - uses this internally
  *
  * @category Tree
  * @since 4.0.0