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

package/dist/SchemaGetter.d.ts

@@ -95,17 +95,18 @@ import * as Issue from "./SchemaIssue.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`.
@@ -122,10 +123,9 @@ import * as Issue from "./SchemaIssue.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
@@ -139,11 +139,13 @@ export declare 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`.
  *
@@ -156,9 +158,8 @@ export declare 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
@@ -167,11 +168,13 @@ export declare 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.
  *
@@ -185,9 +188,8 @@ export declare 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
@@ -196,11 +198,13 @@ export declare function fail<T, E>(f: (oe: Option.Option<E>) => Issue.Issue): Ge
 /**
  * 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.
  *
@@ -214,8 +218,7 @@ export declare function fail<T, E>(f: (oe: Option.Option<E>) => Issue.Issue): Ge
  * )
  * ```
  *
- * 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
@@ -224,11 +227,13 @@ export declare function forbidden<T, E>(message: (oe: Option.Option<E>) => strin
 /**
  * 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
@@ -248,10 +253,9 @@ export declare function forbidden<T, E>(message: (oe: Option.Option<E>) => strin
  * )
  * ```
  *
- * 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
@@ -263,11 +267,14 @@ export declare 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)
@@ -279,9 +286,8 @@ export declare 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
@@ -290,11 +296,13 @@ export declare function passthroughSupertype<T extends E, E>(): Getter<T, E>;
 /**
  * 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)
@@ -306,9 +314,8 @@ export declare function passthroughSupertype<T extends E, E>(): Getter<T, E>;
  * 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
@@ -317,11 +324,13 @@ export declare function passthroughSubtype<T, E extends T>(): Getter<T, E>;
 /**
  * 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.
@@ -336,10 +345,9 @@ export declare function passthroughSubtype<T, E extends T>(): Getter<T, E>;
  * )
  * ```
  *
- * 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
@@ -348,11 +356,13 @@ export declare function onNone<T, E extends T = T, R = never>(f: (options: AST.P
 /**
  * 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.
@@ -365,9 +375,8 @@ export declare function onNone<T, E extends T = T, R = never>(f: (options: AST.P
  * 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
@@ -376,11 +385,13 @@ export declare function required<T, E extends T = T>(annotations?: Schema.Annota
 /**
  * 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`.
@@ -395,10 +406,9 @@ export declare function required<T, E extends T = T>(annotations?: Schema.Annota
  * )
  * ```
  *
- * 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
@@ -407,11 +417,13 @@ export declare function onSome<T, E, R = never>(f: (e: E, options: AST.ParseOpti
 /**
  * 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.
@@ -431,9 +443,8 @@ export declare function onSome<T, E, R = never>(f: (e: E, options: AST.ParseOpti
  * )
  * ```
  *
- * 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
@@ -442,14 +453,15 @@ export declare function checkEffect<T, R = never>(f: (input: T, options: AST.Par
 /**
  * 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.
@@ -467,10 +479,9 @@ export declare function checkEffect<T, R = never>(f: (input: T, options: AST.Par
  * )
  * ```
  *
- * 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
@@ -479,11 +490,13 @@ export declare 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`.
@@ -503,9 +516,8 @@ export declare 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
@@ -514,11 +526,13 @@ export declare function transformOrFail<T, E, R = never>(f: (e: E, options: AST.
 /**
  * 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>`.
  *
@@ -532,9 +546,8 @@ export declare function transformOrFail<T, E, R = never>(f: (e: E, options: AST.
  * )
  * ```
  *
- * 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
@@ -543,10 +556,12 @@ export declare function transformOptional<T, E>(f: (oe: Option.Option<E>) => Opt
 /**
  * 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.
  *
@@ -558,9 +573,8 @@ export declare function transformOptional<T, E>(f: (oe: Option.Option<E>) => Opt
  * 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
@@ -569,10 +583,12 @@ export declare 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.
@@ -586,9 +602,8 @@ export declare 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
@@ -597,10 +612,12 @@ export declare function withDefault<T, R = never>(defaultValue: Effect.Effect<T,
 /**
  * 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`.
  *
@@ -613,8 +630,7 @@ export declare function withDefault<T, R = never>(defaultValue: Effect.Effect<T,
  * // Getter<string, number>
  * ```
  *
- * See also:
- * - {@link transform} — for custom string conversions
+ * @see {@link transform} - for custom string conversions
  *
  * @category Coercions
  * @since 4.0.0
@@ -623,10 +639,12 @@ export declare 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`.
  *
@@ -639,8 +657,7 @@ export declare 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
@@ -649,10 +666,12 @@ export declare 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`.
  *
@@ -672,10 +691,12 @@ export declare 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).
  *
@@ -695,10 +716,12 @@ export declare function BigInt<E extends string | number | bigint | boolean>():
 /**
  * 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.
  *
@@ -711,8 +734,7 @@ export declare function BigInt<E extends string | number | bigint | boolean>():
  * // Getter<Date, string>
  * ```
  *
- * See also:
- * - {@link dateTimeUtcFromInput} — validated DateTime parsing
+ * @see {@link dateTimeUtcFromInput} - validated DateTime parsing
  *
  * @category Coercions
  * @since 4.0.0
@@ -721,7 +743,8 @@ export declare 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)
@@ -739,7 +762,8 @@ export declare 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)
@@ -757,7 +781,8 @@ export declare 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)
@@ -775,7 +800,8 @@ export declare 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)
@@ -786,8 +812,7 @@ export declare 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
@@ -796,7 +821,8 @@ export declare 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)
@@ -807,8 +833,7 @@ export declare 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
@@ -817,7 +842,8 @@ export declare function camelToSnake<E extends string>(): Getter<string, E>;
 /**
  * Converts a string to lowercase.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, delegates to `String.toLowerCase`.
  *
  * **Example** (To lowercase)
@@ -828,8 +854,7 @@ export declare 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
@@ -838,7 +863,8 @@ export declare function toLowerCase<E extends string>(): Getter<string, E>;
 /**
  * Converts a string to uppercase.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, delegates to `String.toUpperCase`.
  *
  * **Example** (To uppercase)
@@ -849,8 +875,7 @@ export declare 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
@@ -862,10 +887,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).
@@ -880,8 +907,7 @@ type ParseJsonOptions = {
  * // Getter<MutableJson, string>
  * ```
  *
- * See also:
- * - {@link stringifyJson} — inverse operation
+ * @see {@link stringifyJson} - inverse operation
  *
  * @category Json
  * @since 4.0.0
@@ -895,10 +921,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`.
@@ -917,8 +945,7 @@ type StringifyJsonOptions = {
  * // Getter<string, unknown>
  * ```
  *
- * See also:
- * - {@link parseJson} — inverse operation
+ * @see {@link parseJson} - inverse operation
  *
  * @category Json
  * @since 4.0.0
@@ -927,10 +954,12 @@ export declare function stringifyJson(options?: StringifyJsonOptions): Getter<st
 /**
  * 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.
@@ -944,9 +973,8 @@ export declare function stringifyJson(options?: StringifyJsonOptions): Getter<st
  * // "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
@@ -958,10 +986,12 @@ export declare 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.
  *
@@ -974,8 +1004,7 @@ export declare 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
@@ -987,10 +1016,12 @@ export declare function joinKeyValue<E extends Record<PropertyKey, string>>(opti
 /**
  * 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.
@@ -1005,8 +1036,7 @@ export declare function joinKeyValue<E extends Record<PropertyKey, string>>(opti
  * // "" -> []
  * ```
  *
- * 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
@@ -1017,7 +1047,8 @@ export declare function split<E extends string>(options?: {
 /**
  * Encodes a `Uint8Array` or string to a Base64 string.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, never fails.
  *
  * **Example** (Encode to Base64)
@@ -1028,10 +1059,9 @@ export declare 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
@@ -1040,7 +1070,8 @@ export declare function encodeBase64<E extends Uint8Array | string>(): Getter<st
 /**
  * Encodes a `Uint8Array` or string to a URL-safe Base64 string.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, never fails.
  *
  * **Example** (Encode to Base64Url)
@@ -1051,10 +1082,9 @@ export declare function encodeBase64<E extends Uint8Array | string>(): Getter<st
  * 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
@@ -1063,7 +1093,8 @@ export declare function encodeBase64Url<E extends Uint8Array | string>(): Getter
 /**
  * Encodes a `Uint8Array` or string to a hexadecimal string.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure, never fails.
  *
  * **Example** (Encode to hex)
@@ -1074,9 +1105,8 @@ export declare function encodeBase64Url<E extends Uint8Array | string>(): Getter
  * 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
@@ -1085,7 +1115,8 @@ export declare function encodeHex<E extends Uint8Array | string>(): Getter<strin
 /**
  * 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)
@@ -1097,9 +1128,8 @@ export declare function encodeHex<E extends Uint8Array | string>(): Getter<strin
  * // 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
@@ -1108,7 +1138,8 @@ export declare 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)
@@ -1120,9 +1151,8 @@ export declare 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
@@ -1131,7 +1161,8 @@ export declare 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)
@@ -1143,9 +1174,8 @@ export declare 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
@@ -1154,7 +1184,8 @@ export declare function decodeBase64Url<E extends string>(): Getter<Uint8Array,
 /**
  * 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)
@@ -1166,9 +1197,8 @@ export declare function decodeBase64Url<E extends string>(): Getter<Uint8Array,
  * // 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
@@ -1177,7 +1207,8 @@ export declare function decodeBase64UrlString<E extends string>(): Getter<string
 /**
  * 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)
@@ -1189,9 +1220,8 @@ export declare function decodeBase64UrlString<E extends string>(): Getter<string
  * // 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
@@ -1200,7 +1230,8 @@ export declare 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)
@@ -1212,9 +1243,8 @@ export declare 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
@@ -1223,7 +1253,8 @@ export declare 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`.
@@ -1236,8 +1267,7 @@ export declare 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
@@ -1246,7 +1276,8 @@ export declare 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)
@@ -1258,8 +1289,7 @@ export declare 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
@@ -1268,14 +1298,15 @@ export declare 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`.
@@ -1289,8 +1320,7 @@ export declare 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
@@ -1299,10 +1329,12 @@ export declare function dateTimeUtcFromInput<E extends DateTime.DateTime.Input>(
 /**
  * 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`.
@@ -1316,10 +1348,9 @@ export declare function dateTimeUtcFromInput<E extends DateTime.DateTime.Input>(
  * // 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
@@ -1328,10 +1359,12 @@ export declare function decodeFormData(): Getter<Schema.TreeRecord<string | Blob
 /**
  * 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`.
@@ -1345,10 +1378,9 @@ export declare function decodeFormData(): Getter<Schema.TreeRecord<string | Blob
  * // 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
@@ -1357,10 +1389,12 @@ export declare 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`.
@@ -1374,10 +1408,9 @@ export declare 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
@@ -1386,10 +1419,12 @@ export declare function decodeURLSearchParams(): Getter<Schema.TreeRecord<string
 /**
  * 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`.
@@ -1403,10 +1438,9 @@ export declare function decodeURLSearchParams(): Getter<Schema.TreeRecord<string
  * // 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
@@ -1415,15 +1449,16 @@ export declare function encodeURLSearchParams(): Getter<URLSearchParams, unknown
 /**
  * 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"`
@@ -1446,10 +1481,9 @@ export declare function encodeURLSearchParams(): Getter<URLSearchParams, unknown
  * // { 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
@@ -1458,14 +1492,16 @@ export declare function makeTreeRecord<A>(bracketPathEntries: ReadonlyArray<read
 /**
  * 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
@@ -1482,10 +1518,9 @@ export declare function makeTreeRecord<A>(bracketPathEntries: ReadonlyArray<read
  * // [["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