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

package/dist/SchemaTransformation.js

@@ -97,16 +97,18 @@ import * as Issue from "./SchemaIssue.js";
  * A middleware that wraps the entire parsing `Effect` pipeline for both
  * decode and encode directions.
  *
- * Unlike `Transformation`, which operates on individual values via `Getter`,
- * `Middleware` receives the full `Effect` produced by the inner schema and can
- * intercept, modify, retry, or replace it.
+ * **When to use**
  *
- * When to use this:
  * - You need to catch or recover from parsing errors (e.g. `Schema.catchDecoding`).
  * - You need to run side effects around the parsing pipeline.
  * - You need access to the full `Effect` rather than a single decoded value.
  *
- * Behavior:
+ * **Details**
+ *
+ * Unlike `Transformation`, which operates on individual values via `Getter`,
+ * `Middleware` receives the full `Effect` produced by the inner schema and can
+ * intercept, modify, retry, or replace it.
+ *
  * - Immutable — constructing a Middleware does not mutate existing instances.
  * - `decode` receives an `Effect<Option<E>, Issue, RDE>` and returns
  *   `Effect<Option<T>, Issue, RDT>`.
@@ -129,8 +131,7 @@ import * as Issue from "./SchemaIssue.js";
  * )
  * ```
  *
- * See also:
- * - {@link Transformation} — value-level bidirectional transformation
+ * @see {@link Transformation} — value-level bidirectional transformation
  *
  * @category models
  * @since 4.0.0
@@ -152,16 +153,18 @@ const TypeId = "~effect/SchemaTransformation/Transformation";
  * A bidirectional transformation between a decoded type `T` and an encoded
  * type `E`, built from a pair of `Getter`s.
  *
- * This is the primary building block for `Schema.decodeTo`, `Schema.encodeTo`,
- * `Schema.decode`, `Schema.encode`, and `Schema.link`. Each direction is a
- * `SchemaGetter.Getter` that handles optionality, failure, and Effect services.
+ * **When to use**
  *
- * When to use this:
  * - You need to define how a schema converts between two representations.
  * - You want to compose multiple transformations into a pipeline.
  * - You want to flip a transformation to swap decode/encode.
  *
- * Behavior:
+ * **Details**
+ *
+ * This is the primary building block for `Schema.decodeTo`, `Schema.encodeTo`,
+ * `Schema.decode`, `Schema.encode`, and `Schema.link`. Each direction is a
+ * `SchemaGetter.Getter` that handles optionality, failure, and Effect services.
+ *
  * - Immutable — `flip()` and `compose()` return new instances.
  * - `flip()` swaps the decode and encode getters.
  * - `compose(other)` chains: `this.decode` then `other.decode` for decoding,
@@ -179,11 +182,10 @@ const TypeId = "~effect/SchemaTransformation/Transformation";
  * // encode: passthrough (both directions)
  * ```
  *
- * See also:
- * - {@link make} — construct from `{ decode, encode }` getters
- * - {@link transform} — construct from pure functions
- * - {@link transformOrFail} — construct from effectful functions
- * - {@link Middleware} — effect-pipeline-level alternative
+ * @see {@link make} — construct from `{ decode, encode }` getters
+ * @see {@link transform} — construct from pure functions
+ * @see {@link transformOrFail} — construct from effectful functions
+ * @see {@link Middleware} — effect-pipeline-level alternative
  *
  * @category models
  * @since 4.0.0
@@ -207,10 +209,12 @@ export class Transformation {
 /**
  * Returns `true` if `u` is a `Transformation` instance.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Checking whether a value is already a Transformation before wrapping it.
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure predicate, no side effects.
  * - Acts as a TypeScript type guard.
  *
@@ -226,9 +230,8 @@ export class Transformation {
  * // false
  * ```
  *
- * See also:
- * - {@link Transformation}
- * - {@link make}
+ * @see {@link Transformation}
+ * @see {@link make}
  *
  * @category guards
  * @since 4.0.0
@@ -240,11 +243,13 @@ export function isTransformation(u) {
  * Constructs a `Transformation` from an object with `decode` and `encode`
  * `Getter`s. If the input is already a `Transformation`, returns it as-is.
  *
- * When to use this:
+ * **When to use**
+ *
  * - You already have `Getter` instances and want to pair them.
  * - You want idempotent wrapping (won't double-wrap).
  *
- * Behavior:
+ * **Details**
+ *
  * - Does not mutate the input.
  * - Returns the input unchanged if it is already a `Transformation`.
  *
@@ -259,10 +264,9 @@ export function isTransformation(u) {
  * })
  * ```
  *
- * See also:
- * - {@link transform} — simpler constructor from pure functions
- * - {@link transformOrFail} — constructor from effectful functions
- * - {@link Transformation}
+ * @see {@link transform} — simpler constructor from pure functions
+ * @see {@link transformOrFail} — constructor from effectful functions
+ * @see {@link Transformation}
  *
  * @category constructors
  * @since 3.10.0
@@ -277,11 +281,13 @@ export const make = options => {
  * Creates a `Transformation` from effectful decode and encode functions that
  * can fail with `Issue`.
  *
- * When to use this:
+ * **When to use**
+ *
  * - The transformation can fail (e.g. parsing, validation).
  * - The transformation requires Effect services.
  *
- * Behavior:
+ * **Details**
+ *
  * - Each function receives the input value and `ParseOptions`.
  * - Must return an `Effect` that succeeds with the output or fails with `Issue`.
  * - Skips `None` inputs (missing keys) — functions are only called on present values.
@@ -307,10 +313,9 @@ export const make = options => {
  * )
  * ```
  *
- * See also:
- * - {@link transform} — for infallible, pure transformations
- * - {@link transformOptional} — for transformations that handle missing keys
- * - {@link make} — for transformations from existing Getters
+ * @see {@link transform} — for infallible, pure transformations
+ * @see {@link transformOptional} — for transformations that handle missing keys
+ * @see {@link make} — for transformations from existing Getters
  *
  * @category constructors
  * @since 3.10.0
@@ -322,11 +327,13 @@ export function transformOrFail(options) {
  * Creates a `Transformation` from pure (sync, infallible) decode and encode
  * functions.
  *
- * When to use this:
+ * **When to use**
+ *
  * - The conversion cannot fail.
  * - No Effect services are needed.
  *
- * Behavior:
+ * **Details**
+ *
  * - Each function receives the input and returns the output directly.
  * - Skips `None` inputs (missing keys) — functions are only called on present values.
  * - Does not allocate Effects internally; uses optimized sync path.
@@ -347,10 +354,9 @@ export function transformOrFail(options) {
  * )
  * ```
  *
- * See also:
- * - {@link transformOrFail} — for fallible or effectful transformations
- * - {@link transformOptional} — for transformations that handle missing keys
- * - {@link passthrough} — when no conversion is needed
+ * @see {@link transformOrFail} — for fallible or effectful transformations
+ * @see {@link transformOptional} — for transformations that handle missing keys
+ * @see {@link passthrough} — when no conversion is needed
  *
  * @category constructors
  * @since 3.10.0
@@ -362,11 +368,13 @@ export function transform(options) {
  * Creates a `Transformation` where decode and encode operate on `Option`
  * values, giving full control over missing-key handling.
  *
- * When to use this:
+ * **When to use**
+ *
  * - You need to produce or consume `Option.None` to represent absent keys.
  * - You are working with optional struct fields.
  *
- * Behavior:
+ * **Details**
+ *
  * - Each function receives `Option<input>` and returns `Option<output>`.
  * - `Option.None` input means the key is absent; returning `Option.None`
  *   omits the key from the output.
@@ -390,10 +398,9 @@ export function transform(options) {
  * })
  * ```
  *
- * See also:
- * - {@link transform} — when you don't need Option-level control
- * - {@link optionFromOptionalKey} — built-in for the common optional-key-to-Option pattern
- * - {@link optionFromOptional} — built-in for optional (undefined) to Option
+ * @see {@link transform} — when you don't need Option-level control
+ * @see {@link optionFromOptionalKey} — built-in for the common optional-key-to-Option pattern
+ * @see {@link optionFromOptional} — built-in for optional (undefined) to Option
  *
  * @category constructors
  * @since 4.0.0
@@ -405,10 +412,12 @@ export function transformOptional(options) {
  * A string-to-string transformation that trims whitespace on decode.
  * Encode is passthrough (no change).
  *
- * When to use this:
+ * **When to use**
+ *
  * - Normalizing user input by stripping leading/trailing whitespace.
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: applies `String.prototype.trim()`.
  * - Encode: passthrough (returns the string unchanged).
  * - Not round-trippable if the original had whitespace.
@@ -423,10 +432,9 @@ export function transformOptional(options) {
  * )
  * ```
  *
- * See also:
- * - {@link toLowerCase}
- * - {@link toUpperCase}
- * - {@link snakeToCamel}
+ * @see {@link toLowerCase}
+ * @see {@link toUpperCase}
+ * @see {@link snakeToCamel}
  *
  * @category String transformations
  * @since 4.0.0
@@ -438,10 +446,12 @@ export function trim() {
  * A string-to-string transformation that converts snake_case to camelCase
  * on decode and camelCase to snake_case on encode.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Converting API field names between snake_case and camelCase conventions.
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: `"my_field_name"` → `"myFieldName"`.
  * - Encode: `"myFieldName"` → `"my_field_name"`.
  * - Round-trippable for standard snake_case/camelCase.
@@ -456,9 +466,8 @@ export function trim() {
  * )
  * ```
  *
- * See also:
- * - {@link trim}
- * - {@link toLowerCase}
+ * @see {@link trim}
+ * @see {@link toLowerCase}
  *
  * @category String transformations
  * @since 4.0.0
@@ -470,10 +479,12 @@ export function snakeToCamel() {
  * A string-to-string transformation that lowercases on decode.
  * Encode is passthrough.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Normalizing strings to lowercase (e.g. email addresses).
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: applies `String.prototype.toLowerCase()`.
  * - Encode: passthrough.
  * - Not round-trippable if the original had uppercase characters.
@@ -488,9 +499,8 @@ export function snakeToCamel() {
  * )
  * ```
  *
- * See also:
- * - {@link toUpperCase}
- * - {@link trim}
+ * @see {@link toUpperCase}
+ * @see {@link trim}
  *
  * @category String transformations
  * @since 4.0.0
@@ -502,10 +512,12 @@ export function toLowerCase() {
  * A string-to-string transformation that uppercases on decode.
  * Encode is passthrough.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Normalizing strings to uppercase (e.g. country codes).
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: applies `String.prototype.toUpperCase()`.
  * - Encode: passthrough.
  * - Not round-trippable if the original had lowercase characters.
@@ -520,9 +532,8 @@ export function toLowerCase() {
  * )
  * ```
  *
- * See also:
- * - {@link toLowerCase}
- * - {@link trim}
+ * @see {@link toLowerCase}
+ * @see {@link trim}
  *
  * @category String transformations
  * @since 4.0.0
@@ -534,10 +545,12 @@ export function toUpperCase() {
  * A string-to-string transformation that capitalizes the first character on
  * decode. Encode is passthrough.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Normalizing display names or titles.
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: uppercases the first character, leaves the rest unchanged.
  * - Encode: passthrough.
  *
@@ -551,9 +564,8 @@ export function toUpperCase() {
  * )
  * ```
  *
- * See also:
- * - {@link uncapitalize}
- * - {@link toUpperCase}
+ * @see {@link uncapitalize}
+ * @see {@link toUpperCase}
  *
  * @category String transformations
  * @since 4.0.0
@@ -565,10 +577,12 @@ export function capitalize() {
  * A string-to-string transformation that lowercases the first character on
  * decode. Encode is passthrough.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Normalizing identifiers or field names.
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: lowercases the first character, leaves the rest unchanged.
  * - Encode: passthrough.
  *
@@ -582,9 +596,8 @@ export function capitalize() {
  * )
  * ```
  *
- * See also:
- * - {@link capitalize}
- * - {@link toLowerCase}
+ * @see {@link capitalize}
+ * @see {@link toLowerCase}
  *
  * @category String transformations
  * @since 4.0.0
@@ -596,10 +609,12 @@ export function uncapitalize() {
  * A transformation that decodes a string into a record of key-value pairs and
  * encodes a record of key-value pairs into a string.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Parsing query-string-like or config-file-like strings into records.
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: splits the string by `separator` (default `","`) into pairs,
  *   then splits each pair by `keyValueSeparator` (default `"="`).
  * - Encode: joins the record back into a string using the same separators.
@@ -619,9 +634,8 @@ export function uncapitalize() {
  * // "host:localhost;port:3000" → { host: "localhost", port: "3000" }
  * ```
  *
- * See also:
- * - {@link trim}
- * - {@link snakeToCamel}
+ * @see {@link trim}
+ * @see {@link snakeToCamel}
  *
  * @category String transformations
  * @since 4.0.0
@@ -643,10 +657,12 @@ export function passthroughSubtype() {
  * Decodes a `string` into a `number` and encodes a `number` back to a
  * `string`.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Parsing numeric strings from APIs, form data, or URL parameters.
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: coerces the string to a number (like `Number(s)`).
  * - Encode: coerces the number to a string (like `String(n)`).
  * - Does not validate that the result is finite — combine with
@@ -662,9 +678,8 @@ export function passthroughSubtype() {
  * )
  * ```
  *
- * See also:
- * - {@link bigintFromString}
- * - {@link transform}
+ * @see {@link bigintFromString}
+ * @see {@link transform}
  *
  * @category Coercions
  * @since 4.0.0
@@ -674,10 +689,12 @@ export const numberFromString = /*#__PURE__*/new Transformation(/*#__PURE__*/Get
  * Decodes a `string` into a `bigint` and encodes a `bigint` back to a
  * `string`.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Parsing large integer strings (e.g. database IDs, blockchain values).
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: coerces the string to a bigint (like `BigInt(s)`).
  * - Encode: coerces the bigint to a string (like `String(n)`).
  * - Fails on decode if the string is not a valid bigint representation.
@@ -692,9 +709,8 @@ export const numberFromString = /*#__PURE__*/new Transformation(/*#__PURE__*/Get
  * )
  * ```
  *
- * See also:
- * - {@link numberFromString}
- * - {@link transform}
+ * @see {@link numberFromString}
+ * @see {@link transform}
  *
  * @category Coercions
  * @since 4.0.0
@@ -703,10 +719,12 @@ export const bigintFromString = /*#__PURE__*/new Transformation(/*#__PURE__*/Get
 /**
  * Decodes a `string` into a `Date` and encodes a `Date` back to a `string`.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Parsing ISO 8601 date strings from APIs or user input.
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: creates a `Date` from the string (like `new Date(s)`).
  * - Encode: converts the `Date` to an ISO string (like `date.toISOString()`),
  *   returning `"Invalid Date"` for invalid dates.
@@ -721,9 +739,8 @@ export const bigintFromString = /*#__PURE__*/new Transformation(/*#__PURE__*/Get
  * )
  * ```
  *
- * See also:
- * - {@link numberFromString}
- * - {@link dateTimeUtcFromString}
+ * @see {@link numberFromString}
+ * @see {@link dateTimeUtcFromString}
  *
  * @category Coercions
  * @since 4.0.0
@@ -733,10 +750,12 @@ export const dateFromString = /*#__PURE__*/new Transformation(/*#__PURE__*/Gette
  * Decodes a `string` into a `Duration` and encodes a `Duration` back to a
  * parseable `string`.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Parsing human-readable duration strings from APIs, config, or user input.
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: accepts any string that `Duration.fromInput` can parse, including
  *   `"Infinity"` and `"-Infinity"`.
  * - Encode: returns `String(duration)`, producing strings like `"2000 millis"`
@@ -752,9 +771,8 @@ export const dateFromString = /*#__PURE__*/new Transformation(/*#__PURE__*/Gette
  * )
  * ```
  *
- * See also:
- * - {@link durationFromNanos}
- * - {@link durationFromMillis}
+ * @see {@link durationFromNanos}
+ * @see {@link durationFromMillis}
  *
  * @category transforming
  * @since 4.0.0
@@ -772,10 +790,12 @@ export const durationFromString = /*#__PURE__*/transformOrFail({
  * Decodes a `bigint` (nanoseconds) into a `Duration` and encodes a
  * `Duration` back to `bigint` nanoseconds.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Working with nanosecond-precision timestamps or intervals.
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: always succeeds, creating a Duration from nanoseconds.
  * - Encode: fails with `InvalidValue` if the Duration cannot be represented
  *   as a `bigint` (e.g. `Duration.infinity`).
@@ -790,8 +810,7 @@ export const durationFromString = /*#__PURE__*/transformOrFail({
  * )
  * ```
  *
- * See also:
- * - {@link durationFromMillis}
+ * @see {@link durationFromMillis}
  *
  * @category transforming
  * @since 4.0.0
@@ -809,9 +828,15 @@ export const durationFromNanos = /*#__PURE__*/transformOrFail({
  * Decodes a `number` of milliseconds into a `Duration` and encodes a `Duration`
  * back to milliseconds.
  *
+ * **When to use**
+ *
  * Use this for timeouts, delays, elapsed intervals, or other duration values
- * stored as millisecond counts. Decode creates a duration from the number, and
- * encode returns the duration length in milliseconds.
+ * stored as millisecond counts.
+ *
+ * **Details**
+ *
+ * Decode creates a duration from the number, and encode returns the duration
+ * length in milliseconds.
  *
  * **Example** (Duration from milliseconds)
  *
@@ -823,8 +848,7 @@ export const durationFromNanos = /*#__PURE__*/transformOrFail({
  * )
  * ```
  *
- * See also:
- * - {@link durationFromNanos}
+ * @see {@link durationFromNanos}
  *
  * @category transforming
  * @since 4.0.0
@@ -856,10 +880,12 @@ export const errorFromErrorJsonEncoded = options => transform({
  * Decodes `T | null` into `Option<T>` and encodes `Option<T>` back to
  * `T | null`.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Converting nullable API fields to `Option`.
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: `null` → `Option.none()`, non-null → `Option.some(value)`.
  * - Encode: `Option.none()` → `null`, `Option.some(value)` → `value`.
  * - Pure and synchronous.
@@ -877,8 +903,7 @@ export const errorFromErrorJsonEncoded = options => transform({
  * )
  * ```
  *
- * See also:
- * - {@link optionFromNullishOr}
+ * @see {@link optionFromNullishOr}
  *
  * @category transforming
  * @since 4.0.0
@@ -893,10 +918,12 @@ export function optionFromNullOr() {
  * Decodes `T | undefined` into `Option<T>` and encodes `Option<T>` back
  * to `T | undefined`.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Converting undefined-or API fields to `Option`.
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: `undefined` → `Option.none()`, non-undefined → `Option.some(value)`.
  * - Encode: `Option.none()` → `undefined`, `Option.some(value)` → `value`.
  * - Pure and synchronous.
@@ -914,9 +941,8 @@ export function optionFromNullOr() {
  * )
  * ```
  *
- * See also:
- * - {@link optionFromOptionalKey}
- * - {@link optionFromOptional}
+ * @see {@link optionFromOptionalKey}
+ * @see {@link optionFromOptional}
  *
  * @category transforming
  * @since 4.0.0
@@ -929,13 +955,16 @@ export function optionFromUndefinedOr() {
 }
 /**
  * Decodes `T | null | undefined` into `Option<T>` and encodes `Option<T>`
- * back to `T | null` or `T | undefined` depending on the provided `options.onNoneEncoding` (defaults to `undefined`).
+ * back to `T | null` or `T | undefined` depending on the provided
+ * `options.onNoneEncoding` (defaults to `undefined`).
+ *
+ * **When to use**
  *
- * When to use this:
  * - Converting nullish API fields to `Option` when both `null` and
  *   `undefined` represent absence.
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: `null` or `undefined` → `Option.none()`, otherwise → `Option.some(value)`.
  * - Encode: `Option.none()` → `null` or `undefined` (per `options.onNoneEncoding`),
  *   `Option.some(value)` → `value`.
@@ -954,9 +983,8 @@ export function optionFromUndefinedOr() {
  * )
  * ```
  *
- * See also:
- * - {@link optionFromNullOr}
- * - {@link optionFromUndefinedOr}
+ * @see {@link optionFromNullOr}
+ * @see {@link optionFromUndefinedOr}
  *
  * @category transforming
  * @since 4.0.0
@@ -971,11 +999,13 @@ export function optionFromNullishOr(options) {
  * Decodes an optional struct key into `Option<T>` and encodes `Option<T>`
  * back to an optional key.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Converting optional struct keys (declared with `Schema.optionalKey`) to
  *   `Option` values.
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: absent key (`None`) → `Some(None)`, present key (`Some(v)`) → `Some(Some(v))`.
  * - Encode: `Some(None)` → `None` (omit key), `Some(Some(v))` → `Some(v)`.
  * - Uses `transformOptional` under the hood.
@@ -995,10 +1025,9 @@ export function optionFromNullishOr(options) {
  * })
  * ```
  *
- * See also:
- * - {@link optionFromOptional}
- * - {@link optionFromUndefinedOr}
- * - {@link transformOptional}
+ * @see {@link optionFromOptional}
+ * @see {@link optionFromUndefinedOr}
+ * @see {@link transformOptional}
  *
  * @category transforming
  * @since 4.0.0
@@ -1013,10 +1042,12 @@ export function optionFromOptionalKey() {
  * Decodes `T | undefined` into `Option<T>` and encodes `Option<T>` back
  * to `T | undefined`.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Converting optional (possibly `undefined`) values to `Option`.
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: absent or `undefined` → `Some(None)`, present → `Some(Some(v))`.
  * - Encode: `Some(None)` → `None` (omit), `Some(Some(v))` → `Some(v)`.
  * - Uses `transformOptional` under the hood; filters out `undefined` on decode.
@@ -1036,10 +1067,9 @@ export function optionFromOptionalKey() {
  * })
  * ```
  *
- * See also:
- * - {@link optionFromOptionalKey}
- * - {@link optionFromUndefinedOr}
- * - {@link transformOptional}
+ * @see {@link optionFromOptionalKey}
+ * @see {@link optionFromUndefinedOr}
+ * @see {@link transformOptional}
  *
  * @category transforming
  * @since 4.0.0
@@ -1054,10 +1084,12 @@ export function optionFromOptional() {
  * Decodes a `string` into a `URL` and encodes a `URL` back to its `href`
  * string.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Parsing URL strings from user input or API responses.
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: calls `new URL(s)`. Fails with `InvalidValue` if the string
  *   is not a valid URL.
  * - Encode: returns `url.href`.
@@ -1072,9 +1104,8 @@ export function optionFromOptional() {
  * )
  * ```
  *
- * See also:
- * - {@link numberFromString}
- * - {@link transformOrFail}
+ * @see {@link numberFromString}
+ * @see {@link transformOrFail}
  *
  * @category transforming
  * @since 4.0.0
@@ -1092,10 +1123,12 @@ export const urlFromString = /*#__PURE__*/transformOrFail({
  * Decodes a `string` into a `BigDecimal` and encodes a `BigDecimal` back to
  * its string representation.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Parsing decimal number strings from APIs or user input.
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: calls `BigDecimal.fromString(s)`. Fails with `InvalidValue` if the
  *   string is not a valid BigDecimal representation.
  * - Encode: returns `BigDecimal.format(bd)`.
@@ -1116,11 +1149,13 @@ export const bigDecimalFromString = /*#__PURE__*/transformOrFail({
  * Decodes a Base64-encoded `string` into a `Uint8Array` and encodes a
  * `Uint8Array` back to a Base64 string.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Handling binary data transmitted as Base64 strings (e.g. file uploads,
  *   API payloads).
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: parses the Base64 string into bytes.
  * - Encode: encodes the byte array as a Base64 string.
  *
@@ -1134,9 +1169,8 @@ export const bigDecimalFromString = /*#__PURE__*/transformOrFail({
  * )
  * ```
  *
- * See also:
- * - {@link fromJsonString}
- * - `Schema.Uint8ArrayFromBase64` - a ready-made schema wrapping this transformation.
+ * @see {@link fromJsonString}
+ * @see `Schema.Uint8ArrayFromBase64` - a ready-made schema wrapping this transformation.
  *
  * @category encoding
  * @since 4.0.0
@@ -1146,10 +1180,12 @@ export const uint8ArrayFromBase64String = /*#__PURE__*/new Transformation(/*#__P
  * Decodes a Base64-encoded `string` into a UTF-8 `string` and encodes a
  * UTF-8 `string` back to a Base64 string.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Handling text data transmitted as Base64 strings.
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: parses the Base64 string into a UTF-8 string.
  * - Encode: encodes the string as a Base64 string.
  *
@@ -1163,9 +1199,8 @@ export const uint8ArrayFromBase64String = /*#__PURE__*/new Transformation(/*#__P
  * )
  * ```
  *
- * See also:
- * - {@link uint8ArrayFromBase64String}
- * - `Schema.StringFromBase64` - a ready-made schema wrapping this transformation.
+ * @see {@link uint8ArrayFromBase64String}
+ * @see `Schema.StringFromBase64` - a ready-made schema wrapping this transformation.
  *
  * @category encoding
  * @since 4.0.0
@@ -1174,10 +1209,12 @@ export const stringFromBase64String = /*#__PURE__*/new Transformation(/*#__PURE_
 /**
  * Decodes a base64 (URL) encoded `string` into a UTF-8 `string` and encodes it back.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Handling text data transmitted as Base64 URL-safe strings.
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: parses the Base64 URL string into a UTF-8 string.
  * - Encode: encodes the string as a Base64 URL string.
  *
@@ -1191,9 +1228,8 @@ export const stringFromBase64String = /*#__PURE__*/new Transformation(/*#__PURE_
  * )
  * ```
  *
- * See also:
- * - {@link stringFromBase64String}
- * - `Schema.StringFromBase64Url` - a ready-made schema wrapping this transformation.
+ * @see {@link stringFromBase64String}
+ * @see `Schema.StringFromBase64Url` - a ready-made schema wrapping this transformation.
  *
  * @category encoding
  * @since 4.0.0
@@ -1202,10 +1238,12 @@ export const stringFromBase64UrlString = /*#__PURE__*/new Transformation(/*#__PU
 /**
  * Decodes a hex encoded `string` into a UTF-8 `string` and encodes it back.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Handling text data transmitted as hexadecimal strings.
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: parses the hex string into a UTF-8 string.
  * - Encode: encodes the string as a hex string.
  *
@@ -1219,9 +1257,8 @@ export const stringFromBase64UrlString = /*#__PURE__*/new Transformation(/*#__PU
  * )
  * ```
  *
- * See also:
- * - {@link stringFromBase64String}
- * - `Schema.StringFromHex` - a ready-made schema wrapping this transformation.
+ * @see {@link stringFromBase64String}
+ * @see `Schema.StringFromHex` - a ready-made schema wrapping this transformation.
  *
  * @category encoding
  * @since 4.0.0
@@ -1231,11 +1268,13 @@ export const stringFromHexString = /*#__PURE__*/new Transformation(/*#__PURE__*/
  * Decodes a URI component encoded string into a UTF-8 string and encodes a
  * UTF-8 string into a URI component encoded string.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Storing structured data in URL query parameters or fragments.
  * - Composing with `Schema.parseJson` to round-trip JSON through a URL.
  *
- * Behavior:
+ * **Details**
+ *
  * - Decode: calls `decodeURIComponent`. Fails if the input contains malformed
  *   percent-encoding sequences.
  * - Encode: calls `encodeURIComponent`.
@@ -1250,9 +1289,8 @@ export const stringFromHexString = /*#__PURE__*/new Transformation(/*#__PURE__*/
  * )
  * ```
  *
- * See also:
- * - {@link stringFromBase64String}
- * - `Schema.StringFromUriComponent` - a ready-made schema wrapping this transformation.
+ * @see {@link stringFromBase64String}
+ * @see `Schema.StringFromUriComponent` - a ready-made schema wrapping this transformation.
  *
  * @category encoding
  * @since 4.0.0
@@ -1262,10 +1300,15 @@ export const stringFromUriComponent = /*#__PURE__*/new Transformation(/*#__PURE_
  * Decodes a JSON string with `JSON.parse` and encodes a value with
  * `JSON.stringify`.
  *
+ * **When to use**
+ *
  * Use this for JSON stored or transmitted as a string, usually before composing
- * with another schema that validates the parsed structure. Decode fails with
- * `InvalidValue` for invalid JSON, and encode can fail with `InvalidValue` when
- * `JSON.stringify` cannot serialize the value.
+ * with another schema that validates the parsed structure.
+ *
+ * **Details**
+ *
+ * Decode fails with `InvalidValue` for invalid JSON, and encode can fail with
+ * `InvalidValue` when `JSON.stringify` cannot serialize the value.
  *
  * **Example** (Parsing JSON)
  *
@@ -1277,9 +1320,8 @@ export const stringFromUriComponent = /*#__PURE__*/new Transformation(/*#__PURE_
  * )
  * ```
  *
- * See also:
- * - {@link uint8ArrayFromBase64String}
- * - {@link fromFormData}
+ * @see {@link uint8ArrayFromBase64String}
+ * @see {@link fromFormData}
  *
  * @category decoding
  * @since 4.0.0
@@ -1289,10 +1331,16 @@ export const fromJsonString = /*#__PURE__*/new Transformation(/*#__PURE__*/Gette
  * Decodes a `FormData` instance into a nested record using bracket-path keys and
  * encodes object-like values back into `FormData`.
  *
+ * **When to use**
+ *
  * Use this for form or multipart payloads where keys such as `user[name]` or
- * `items[0]` should become nested data. Decode preserves string and `Blob`
- * leaves. Encode flattens nested objects and arrays into bracket-path entries
- * and returns an empty `FormData` for non-object inputs.
+ * `items[0]` should become nested data.
+ *
+ * **Details**
+ *
+ * Decode preserves string and `Blob` leaves. Encode flattens nested objects and
+ * arrays into bracket-path entries and returns an empty `FormData` for
+ * non-object inputs.
  *
  * **Example** (Decoding FormData)
  *
@@ -1304,9 +1352,8 @@ export const fromJsonString = /*#__PURE__*/new Transformation(/*#__PURE__*/Gette
  * )
  * ```
  *
- * See also:
- * - {@link fromURLSearchParams}
- * - {@link fromJsonString}
+ * @see {@link fromURLSearchParams}
+ * @see {@link fromJsonString}
  *
  * @category decoding
  * @since 4.0.0
@@ -1316,10 +1363,16 @@ export const fromFormData = /*#__PURE__*/new Transformation(/*#__PURE__*/Getter.
  * Decodes `URLSearchParams` into a nested record using bracket-path keys and
  * encodes object-like values back into `URLSearchParams`.
  *
+ * **When to use**
+ *
  * Use this for query strings where keys such as `filter[name]` or `items[0]`
- * should become nested data. Decode produces string leaves. Encode flattens
- * nested objects and arrays into bracket-path entries and returns empty
- * `URLSearchParams` for non-object inputs.
+ * should become nested data.
+ *
+ * **Details**
+ *
+ * Decode produces string leaves. Encode flattens nested objects and arrays into
+ * bracket-path entries and returns empty `URLSearchParams` for non-object
+ * inputs.
  *
  * **Example** (Decoding URLSearchParams)
  *
@@ -1331,9 +1384,8 @@ export const fromFormData = /*#__PURE__*/new Transformation(/*#__PURE__*/Getter.
  * )
  * ```
  *
- * See also:
- * - {@link fromFormData}
- * - {@link fromJsonString}
+ * @see {@link fromFormData}
+ * @see {@link fromJsonString}
  *
  * @category decoding
  * @since 4.0.0
@@ -1343,6 +1395,8 @@ export const fromURLSearchParams = /*#__PURE__*/new Transformation(/*#__PURE__*/
  * Decodes a numeric time-zone offset in milliseconds into a
  * `DateTime.TimeZone.Offset` and encodes it back to the offset number.
  *
+ * **Details**
+ *
  * Decode uses `DateTime.zoneMakeOffset`; encode returns the offset's `offset`
  * field.
  *
@@ -1357,6 +1411,8 @@ export const timeZoneOffsetFromNumber = /*#__PURE__*/transform({
  * Decodes an IANA time-zone identifier string into a
  * `DateTime.TimeZone.Named` and encodes a named time zone back to its `id`.
  *
+ * **Details**
+ *
  * Decode fails with `InvalidValue` when the string is not a valid IANA time-zone
  * identifier.
  *
@@ -1378,6 +1434,8 @@ export const timeZoneNamedFromString = /*#__PURE__*/transformOrFail({
  * Decodes a string into a `DateTime.TimeZone` and encodes a time zone back to
  * its string representation.
  *
+ * **Details**
+ *
  * Accepted decode inputs include valid IANA identifiers and offset strings such
  * as `"+03:00"`. Decode fails with `InvalidValue` when the string cannot be
  * parsed as a time zone.
@@ -1400,6 +1458,8 @@ export const timeZoneFromString = /*#__PURE__*/transformOrFail({
  * Decodes a date-time string into a `DateTime.Utc` and encodes it back to an ISO
  * string.
  *
+ * **Details**
+ *
  * Decode accepts strings supported by `DateTime.make`, converts the result to
  * UTC, and fails with `InvalidValue` when parsing fails. Encode uses
  * `DateTime.formatIso`.
@@ -1422,6 +1482,8 @@ export const dateTimeUtcFromString = /*#__PURE__*/transformOrFail({
  * Decodes a zoned date-time string into a `DateTime.Zoned` and encodes it back
  * to an ISO zoned string.
  *
+ * **Details**
+ *
  * Decode uses `DateTime.makeZonedFromString` and fails with `InvalidValue` when
  * the input is not a valid zoned date-time. Encode uses
  * `DateTime.formatIsoZoned`.