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

package/src/SchemaGetter.ts

@@ -100,17 +100,18 @@ import * as Str from "./String.ts"
 /**
  * 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`.
@@ -127,10 +128,9 @@ import * as Str from "./String.ts"
  * // 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
@@ -167,11 +167,13 @@ export class Getter<out T, in E, R = never> 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`.
  *
@@ -184,9 +186,8 @@ export class Getter<out T, in E, R = never> 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
@@ -198,11 +199,13 @@ export function succeed<const T, E>(t: T): Getter<T, E> {
 /**
  * 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.
  *
@@ -216,9 +219,8 @@ export function succeed<const T, E>(t: T): Getter<T, E> {
  * )
  * ```
  *
- * 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
@@ -230,11 +232,13 @@ export function fail<T, E>(f: (oe: Option.Option<E>) => Issue.Issue): Getter<T,
 /**
  * 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.
  *
@@ -248,8 +252,7 @@ export function fail<T, E>(f: (oe: Option.Option<E>) => Issue.Issue): Getter<T,
  * )
  * ```
  *
- * 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
@@ -267,11 +270,13 @@ function isPassthrough<T, E, R>(getter: Getter<T, E, R>): getter is typeof passt
 /**
  * Returns the identity getter — passes the value through unchanged.
  *
- * Use this when:
+ * **When to use**
+ *
  * - No transformation is needed between encoded and decoded types.
  * - One side of a `decodeTo` pair (encode or decode) should be a no-op.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, no allocation (singleton instance).
  * - Optimized away during `.compose()` — composing with a passthrough is free.
  * - The default overload requires `T === E`. Pass `{ strict: false }` to opt
@@ -291,10 +296,9 @@ function isPassthrough<T, E, R>(getter: Getter<T, E, R>): getter is typeof passt
  * )
  * ```
  *
- * See also:
- * - {@link passthroughSupertype} — when `T extends E`
- * - {@link passthroughSubtype} — when `E extends T`
- * - {@link transform} — when you need to change the value
+ * @see {@link passthroughSupertype} - when `T extends E`
+ * @see {@link passthroughSubtype} - when `E extends T`
+ * @see {@link transform} - when you need to change the value
  *
  * @category constructors
  * @since 4.0.0
@@ -308,11 +312,14 @@ export function passthrough<T>(): Getter<T, T> {
 /**
  * Returns the identity getter typed for the relationship `T extends E`.
  *
+ * **When to use**
+ *
  * Use this 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.
  *
- * Behavior:
+ * **Details**
+ *
  * - Same singleton as {@link passthrough} — no allocation, optimized in composition.
  *
  * **Example** (Supertype passthrough)
@@ -324,9 +331,8 @@ export function passthrough<T>(): Getter<T, T> {
  * const g = SchemaGetter.passthroughSupertype<string, string>()
  * ```
  *
- * See also:
- * - {@link passthrough} — when types are identical
- * - {@link passthroughSubtype} — when `E extends T`
+ * @see {@link passthrough} - when types are identical
+ * @see {@link passthroughSubtype} - when `E extends T`
  *
  * @category constructors
  * @since 4.0.0
@@ -339,11 +345,13 @@ export function passthroughSupertype<T>(): Getter<T, T> {
 /**
  * Returns the identity getter, typed for when the encoded type `E` is a subtype of `T`.
  *
- * Use this when:
+ * **When to use**
+ *
  * - The encoded type is narrower than the decoded type.
  * - You need type-safe passthrough without `{ strict: false }`.
  *
- * Behavior:
+ * **Details**
+ *
  * - Same singleton as {@link passthrough} — no allocation, optimized in composition.
  *
  * **Example** (Subtype passthrough)
@@ -355,9 +363,8 @@ export function passthroughSupertype<T>(): Getter<T, T> {
  * const g = SchemaGetter.passthroughSubtype<string, "hello">()
  * ```
  *
- * See also:
- * - {@link passthrough} — when types are identical
- * - {@link passthroughSupertype} — when `T extends E`
+ * @see {@link passthrough} - when types are identical
+ * @see {@link passthroughSupertype} - when `T extends E`
  *
  * @category constructors
  * @since 4.0.0
@@ -370,11 +377,13 @@ export function passthroughSubtype<T>(): Getter<T, T> {
 /**
  * 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.
@@ -389,10 +398,9 @@ export function passthroughSubtype<T>(): Getter<T, T> {
  * )
  * ```
  *
- * 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
@@ -406,11 +414,13 @@ export function onNone<T, E extends T = T, R = never>(
 /**
  * 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.
@@ -423,9 +433,8 @@ export function onNone<T, E extends T = T, R = never>(
  * 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
@@ -437,11 +446,13 @@ export function required<T, E extends T = T>(annotations?: Schema.Annotations.Ke
 /**
  * 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`.
@@ -456,10 +467,9 @@ export function required<T, E extends T = T>(annotations?: Schema.Annotations.Ke
  * )
  * ```
  *
- * 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
@@ -473,11 +483,13 @@ export function onSome<T, E, R = never>(
 /**
  * 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.
@@ -497,9 +509,8 @@ export function onSome<T, E, R = never>(
  * )
  * ```
  *
- * 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
@@ -524,14 +535,15 @@ export function checkEffect<T, R = never>(
 /**
  * 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.
@@ -549,10 +561,9 @@ export function checkEffect<T, R = never>(
  * )
  * ```
  *
- * 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
@@ -564,11 +575,13 @@ export function transform<T, E>(f: (e: E) => T): Getter<T, E> {
 /**
  * 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`.
@@ -588,9 +601,8 @@ export function transform<T, E>(f: (e: E) => T): Getter<T, E> {
  * )
  * ```
  *
- * 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
@@ -604,11 +616,13 @@ export function transformOrFail<T, E, R = never>(
 /**
  * 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>`.
  *
@@ -622,9 +636,8 @@ export function transformOrFail<T, E, R = never>(
  * )
  * ```
  *
- * 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
@@ -636,10 +649,12 @@ export function transformOptional<T, E>(f: (oe: Option.Option<E>) => Option.Opti
 /**
  * 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.
  *
@@ -651,9 +666,8 @@ export function transformOptional<T, E>(f: (oe: Option.Option<E>) => Option.Opti
  * 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
@@ -665,10 +679,12 @@ export function omit<T>(): Getter<never, T> {
 /**
  * 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.
@@ -682,9 +698,8 @@ export function omit<T>(): Getter<never, T> {
  * // 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
@@ -701,10 +716,12 @@ export function withDefault<T, R = never>(
 /**
  * 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`.
  *
@@ -717,8 +734,7 @@ export function withDefault<T, R = never>(
  * // Getter<string, number>
  * ```
  *
- * See also:
- * - {@link transform} — for custom string conversions
+ * @see {@link transform} - for custom string conversions
  *
  * @category Coercions
  * @since 4.0.0
@@ -730,10 +746,12 @@ export function String<E>(): Getter<string, E> {
 /**
  * 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`.
  *
@@ -746,8 +764,7 @@ export function String<E>(): Getter<string, E> {
  * // Getter<number, string>
  * ```
  *
- * See also:
- * - {@link transformOrFail} — for validated number parsing
+ * @see {@link transformOrFail} - for validated number parsing
  *
  * @category Coercions
  * @since 4.0.0
@@ -759,10 +776,12 @@ export function Number<E>(): Getter<number, E> {
 /**
  * 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`.
  *
@@ -785,10 +804,12 @@ export function Boolean<E>(): Getter<boolean, E> {
 /**
  * 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).
  *
@@ -811,10 +832,12 @@ export function BigInt<E extends string | number | bigint | boolean>(): Getter<b
 /**
  * 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.
  *
@@ -827,8 +850,7 @@ export function BigInt<E extends string | number | bigint | boolean>(): Getter<b
  * // Getter<Date, string>
  * ```
  *
- * See also:
- * - {@link dateTimeUtcFromInput} — validated DateTime parsing
+ * @see {@link dateTimeUtcFromInput} - validated DateTime parsing
  *
  * @category Coercions
  * @since 4.0.0
@@ -840,7 +862,8 @@ export function Date<E extends string | number | Date>(): Getter<Date, E> {
 /**
  * Trims whitespace from both ends of a string.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, delegates to `String.trim`.
  *
  * **Example** (Trim whitespace)
@@ -861,7 +884,8 @@ export function trim<E extends string>(): Getter<string, E> {
 /**
  * Capitalizes the first character of a string.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, delegates to `String.capitalize`.
  *
  * **Example** (Capitalize string)
@@ -882,7 +906,8 @@ export function capitalize<E extends string>(): Getter<string, E> {
 /**
  * Lowercases the first character of a string.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, delegates to `String.uncapitalize`.
  *
  * **Example** (Uncapitalize string)
@@ -903,7 +928,8 @@ export function uncapitalize<E extends string>(): Getter<string, E> {
 /**
  * Converts a `snake_case` string to `camelCase`.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, delegates to `String.snakeToCamel`.
  *
  * **Example** (Snake to camel)
@@ -914,8 +940,7 @@ export function uncapitalize<E extends string>(): Getter<string, E> {
  * const toCamel = SchemaGetter.snakeToCamel<string>()
  * ```
  *
- * See also:
- * - {@link camelToSnake} — inverse operation
+ * @see {@link camelToSnake} - inverse operation
  *
  * @category string
  * @since 4.0.0
@@ -927,7 +952,8 @@ export function snakeToCamel<E extends string>(): Getter<string, E> {
 /**
  * Converts a `camelCase` string to `snake_case`.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, delegates to `String.camelToSnake`.
  *
  * **Example** (Camel to snake)
@@ -938,8 +964,7 @@ export function snakeToCamel<E extends string>(): Getter<string, E> {
  * const toSnake = SchemaGetter.camelToSnake<string>()
  * ```
  *
- * See also:
- * - {@link snakeToCamel} — inverse operation
+ * @see {@link snakeToCamel} - inverse operation
  *
  * @category string
  * @since 4.0.0
@@ -951,7 +976,8 @@ export function camelToSnake<E extends string>(): Getter<string, E> {
 /**
  * Converts a string to lowercase.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, delegates to `String.toLowerCase`.
  *
  * **Example** (To lowercase)
@@ -962,8 +988,7 @@ export function camelToSnake<E extends string>(): Getter<string, E> {
  * const lower = SchemaGetter.toLowerCase<string>()
  * ```
  *
- * See also:
- * - {@link toUpperCase} — inverse operation
+ * @see {@link toUpperCase} - inverse operation
  *
  * @category string
  * @since 4.0.0
@@ -975,7 +1000,8 @@ export function toLowerCase<E extends string>(): Getter<string, E> {
 /**
  * Converts a string to uppercase.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, delegates to `String.toUpperCase`.
  *
  * **Example** (To uppercase)
@@ -986,8 +1012,7 @@ export function toLowerCase<E extends string>(): Getter<string, E> {
  * const upper = SchemaGetter.toUpperCase<string>()
  * ```
  *
- * See also:
- * - {@link toLowerCase} — inverse operation
+ * @see {@link toLowerCase} - inverse operation
  *
  * @category string
  * @since 4.0.0
@@ -1003,10 +1028,12 @@ type ParseJsonOptions = {
 /**
  * Parses a JSON string into a value.
  *
- * Use this when:
+ * **When to use**
+ *
  * - An encoded value is a JSON string that needs to be parsed during decoding.
  *
- * Behavior:
+ * **Details**
+ *
  * - Skips `None` inputs.
  * - Without `reviver`: returns `Schema.MutableJson` (typed JSON).
  * - With `reviver`: returns `unknown` (reviver may produce arbitrary values).
@@ -1021,8 +1048,7 @@ type ParseJsonOptions = {
  * // Getter<MutableJson, string>
  * ```
  *
- * See also:
- * - {@link stringifyJson} — inverse operation
+ * @see {@link stringifyJson} - inverse operation
  *
  * @category Json
  * @since 4.0.0
@@ -1046,10 +1072,12 @@ type StringifyJsonOptions = {
 /**
  * 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`.
@@ -1068,8 +1096,7 @@ type StringifyJsonOptions = {
  * // Getter<string, unknown>
  * ```
  *
- * See also:
- * - {@link parseJson} — inverse operation
+ * @see {@link parseJson} - inverse operation
  *
  * @category Json
  * @since 4.0.0
@@ -1086,10 +1113,12 @@ export function stringifyJson(options?: StringifyJsonOptions): Getter<string, un
 /**
  * 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.
@@ -1103,9 +1132,8 @@ export function stringifyJson(options?: StringifyJsonOptions): Getter<string, un
  * // "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
@@ -1130,10 +1158,12 @@ export function splitKeyValue<E extends string>(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.
  *
@@ -1146,8 +1176,7 @@ export function splitKeyValue<E extends string>(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
@@ -1166,10 +1195,12 @@ export function joinKeyValue<E extends Record<PropertyKey, string>>(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.
@@ -1184,8 +1215,7 @@ export function joinKeyValue<E extends Record<PropertyKey, string>>(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
@@ -1200,7 +1230,8 @@ export function split<E extends string>(options?: {
 /**
  * Encodes a `Uint8Array` or string to a Base64 string.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, never fails.
  *
  * **Example** (Encode to Base64)
@@ -1211,10 +1242,9 @@ export function split<E extends string>(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
@@ -1226,7 +1256,8 @@ export function encodeBase64<E extends Uint8Array | string>(): Getter<string, E>
 /**
  * Encodes a `Uint8Array` or string to a URL-safe Base64 string.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, never fails.
  *
  * **Example** (Encode to Base64Url)
@@ -1237,10 +1268,9 @@ export function encodeBase64<E extends Uint8Array | string>(): Getter<string, E>
  * 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
@@ -1252,7 +1282,8 @@ export function encodeBase64Url<E extends Uint8Array | string>(): Getter<string,
 /**
  * Encodes a `Uint8Array` or string to a hexadecimal string.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, never fails.
  *
  * **Example** (Encode to hex)
@@ -1263,9 +1294,8 @@ export function encodeBase64Url<E extends Uint8Array | string>(): Getter<string,
  * 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
@@ -1277,7 +1307,8 @@ export function encodeHex<E extends Uint8Array | string>(): Getter<string, E> {
 /**
  * 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)
@@ -1289,9 +1320,8 @@ export function encodeHex<E extends Uint8Array | string>(): Getter<string, E> {
  * // 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
@@ -1308,7 +1338,8 @@ export function decodeBase64<E extends string>(): Getter<Uint8Array, E> {
 /**
  * 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)
@@ -1320,9 +1351,8 @@ export function decodeBase64<E extends string>(): Getter<Uint8Array, E> {
  * // 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
@@ -1339,7 +1369,8 @@ export function decodeBase64String<E extends string>(): Getter<string, E> {
 /**
  * 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)
@@ -1351,9 +1382,8 @@ export function decodeBase64String<E extends string>(): Getter<string, E> {
  * // 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
@@ -1370,7 +1400,8 @@ export function decodeBase64Url<E extends string>(): Getter<Uint8Array, E> {
 /**
  * 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)
@@ -1382,9 +1413,8 @@ export function decodeBase64Url<E extends string>(): Getter<Uint8Array, E> {
  * // 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
@@ -1401,7 +1431,8 @@ export function decodeBase64UrlString<E extends string>(): Getter<string, E> {
 /**
  * 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)
@@ -1413,9 +1444,8 @@ export function decodeBase64UrlString<E extends string>(): Getter<string, E> {
  * // 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
@@ -1432,7 +1462,8 @@ export function decodeHex<E extends string>(): Getter<Uint8Array, E> {
 /**
  * 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)
@@ -1444,9 +1475,8 @@ export function decodeHex<E extends string>(): Getter<Uint8Array, E> {
  * // 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
@@ -1463,7 +1493,8 @@ export function decodeHexString<E extends string>(): Getter<string, E> {
 /**
  * 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`.
@@ -1476,8 +1507,7 @@ export function decodeHexString<E extends string>(): Getter<string, E> {
  * const encode = SchemaGetter.encodeUriComponent<string>()
  * ```
  *
- * See also:
- * - {@link decodeUriComponent} - inverse operation
+ * @see {@link decodeUriComponent} - inverse operation
  *
  * @category URI
  * @since 4.0.0
@@ -1489,7 +1519,8 @@ export function encodeUriComponent<E extends string>(): Getter<string, E> {
 /**
  * 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)
@@ -1501,8 +1532,7 @@ export function encodeUriComponent<E extends string>(): Getter<string, E> {
  * // Getter<string, string>
  * ```
  *
- * See also:
- * - {@link encodeUriComponent} - inverse operation
+ * @see {@link encodeUriComponent} - inverse operation
  *
  * @category URI
  * @since 4.0.0
@@ -1524,14 +1554,15 @@ export function decodeUriComponent<E extends string>(): Getter<string, E> {
 /**
  * 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`.
@@ -1545,8 +1576,7 @@ export function decodeUriComponent<E extends string>(): Getter<string, E> {
  * // 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
@@ -1563,10 +1593,12 @@ export function dateTimeUtcFromInput<E extends DateTime.DateTime.Input>(): Gette
 /**
  * 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`.
@@ -1580,10 +1612,9 @@ export function dateTimeUtcFromInput<E extends DateTime.DateTime.Input>(): Gette
  * // 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
@@ -1599,10 +1630,12 @@ const collectFormDataEntries = collectBracketPathEntries((value): value is strin
 /**
  * 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`.
@@ -1616,10 +1649,9 @@ const collectFormDataEntries = collectBracketPathEntries((value): value is strin
  * // 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
@@ -1640,10 +1672,12 @@ export function encodeFormData(): Getter<FormData, unknown> {
 /**
  * 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`.
@@ -1657,10 +1691,9 @@ export function encodeFormData(): Getter<FormData, unknown> {
  * // 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
@@ -1674,10 +1707,12 @@ const collectURLSearchParamsEntries = collectBracketPathEntries(Predicate.isStri
 /**
  * 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`.
@@ -1691,10 +1726,9 @@ const collectURLSearchParamsEntries = collectBracketPathEntries(Predicate.isStri
  * // 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
@@ -1729,15 +1763,16 @@ function bracketPathToTokens(bracketPath: string): Array<string | number> {
 /**
  * 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"`
@@ -1760,10 +1795,9 @@ function bracketPathToTokens(bracketPath: string): Array<string | number> {
  * // { 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
@@ -1823,14 +1857,16 @@ export function makeTreeRecord<A>(
 /**
  * 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
@@ -1847,10 +1883,9 @@ export function makeTreeRecord<A>(
  * // [["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