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

package/dist/SchemaTransformation.d.ts

@@ -96,16 +96,18 @@ import * as Issue from "./SchemaIssue.ts";
  * 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>`.
@@ -128,8 +130,7 @@ import * as Issue from "./SchemaIssue.ts";
  * )
  * ```
  *
- * See also:
- * - {@link Transformation} — value-level bidirectional transformation
+ * @see {@link Transformation} — value-level bidirectional transformation
  *
  * @category models
  * @since 4.0.0
@@ -146,16 +147,18 @@ declare 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,
@@ -173,11 +176,10 @@ declare 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
@@ -194,10 +196,12 @@ export declare class Transformation<in out T, in out E, RD = never, RE = never>
 /**
  * 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.
  *
@@ -213,9 +217,8 @@ export declare class Transformation<in out T, in out E, RD = never, RE = never>
  * // false
  * ```
  *
- * See also:
- * - {@link Transformation}
- * - {@link make}
+ * @see {@link Transformation}
+ * @see {@link make}
  *
  * @category guards
  * @since 4.0.0
@@ -225,11 +228,13 @@ export declare function isTransformation(u: unknown): u is Transformation<any, a
  * 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`.
  *
@@ -244,10 +249,9 @@ export declare function isTransformation(u: unknown): u is Transformation<any, a
  * })
  * ```
  *
- * 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
@@ -260,11 +264,13 @@ export declare const make: <T, E, RD = never, RE = never>(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.
@@ -290,10 +296,9 @@ export declare const make: <T, E, RD = never, RE = never>(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
@@ -306,11 +311,13 @@ export declare function transformOrFail<T, E, RD = never, RE = never>(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.
@@ -331,10 +338,9 @@ export declare function transformOrFail<T, E, RD = never, RE = never>(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
@@ -347,11 +353,13 @@ export declare function transform<T, E>(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.
@@ -375,10 +383,9 @@ export declare function transform<T, E>(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
@@ -391,10 +398,12 @@ export declare function transformOptional<T, E>(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.
@@ -409,10 +418,9 @@ export declare function transformOptional<T, E>(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
@@ -422,10 +430,12 @@ export declare function trim(): Transformation<string, string>;
  * 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.
@@ -440,9 +450,8 @@ export declare function trim(): Transformation<string, string>;
  * )
  * ```
  *
- * See also:
- * - {@link trim}
- * - {@link toLowerCase}
+ * @see {@link trim}
+ * @see {@link toLowerCase}
  *
  * @category String transformations
  * @since 4.0.0
@@ -452,10 +461,12 @@ export declare function snakeToCamel(): Transformation<string, string>;
  * 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.
@@ -470,9 +481,8 @@ export declare function snakeToCamel(): Transformation<string, string>;
  * )
  * ```
  *
- * See also:
- * - {@link toUpperCase}
- * - {@link trim}
+ * @see {@link toUpperCase}
+ * @see {@link trim}
  *
  * @category String transformations
  * @since 4.0.0
@@ -482,10 +492,12 @@ export declare function toLowerCase(): Transformation<string, string>;
  * 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.
@@ -500,9 +512,8 @@ export declare function toLowerCase(): Transformation<string, string>;
  * )
  * ```
  *
- * See also:
- * - {@link toLowerCase}
- * - {@link trim}
+ * @see {@link toLowerCase}
+ * @see {@link trim}
  *
  * @category String transformations
  * @since 4.0.0
@@ -512,10 +523,12 @@ export declare function toUpperCase(): Transformation<string, string>;
  * 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.
  *
@@ -529,9 +542,8 @@ export declare function toUpperCase(): Transformation<string, string>;
  * )
  * ```
  *
- * See also:
- * - {@link uncapitalize}
- * - {@link toUpperCase}
+ * @see {@link uncapitalize}
+ * @see {@link toUpperCase}
  *
  * @category String transformations
  * @since 4.0.0
@@ -541,10 +553,12 @@ export declare function capitalize(): Transformation<string, string>;
  * 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.
  *
@@ -558,9 +572,8 @@ export declare function capitalize(): Transformation<string, string>;
  * )
  * ```
  *
- * See also:
- * - {@link capitalize}
- * - {@link toLowerCase}
+ * @see {@link capitalize}
+ * @see {@link toLowerCase}
  *
  * @category String transformations
  * @since 4.0.0
@@ -570,10 +583,12 @@ export declare function uncapitalize(): Transformation<string, string>;
  * 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.
@@ -593,9 +608,8 @@ export declare function uncapitalize(): Transformation<string, string>;
  * // "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
@@ -608,12 +622,14 @@ export declare function splitKeyValue(options?: {
  * The identity transformation — returns the input unchanged in both
  * directions.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Connecting two schemas that share the same type with no conversion.
  * - As a placeholder when `Schema.decodeTo` requires a transformation but
  *   no actual conversion is needed.
  *
- * Behavior:
+ * **Details**
+ *
  * - Both decode and encode are no-ops.
  * - Returns a shared singleton instance (no allocation per call).
  * - By default, `T` and `E` must be the same type. Pass `{ strict: false }`
@@ -629,10 +645,9 @@ export declare function splitKeyValue(options?: {
  * )
  * ```
  *
- * See also:
- * - {@link passthroughSupertype}
- * - {@link passthroughSubtype}
- * - {@link transform}
+ * @see {@link passthroughSupertype}
+ * @see {@link passthroughSubtype}
+ * @see {@link transform}
  *
  * @category constructors
  * @since 4.0.0
@@ -645,9 +660,15 @@ export declare function passthrough<T>(): Transformation<T, T>;
  * A passthrough transformation typed so that `T extends E`, where the decoded
  * type `T` is a subtype of the encoded type `E`.
  *
+ * **When to use**
+ *
  * Use this when the runtime value is unchanged but the decoded side should be
- * narrower than the encoded side. Both decode and encode are no-ops and return a
- * shared singleton transformation.
+ * narrower than the encoded side.
+ *
+ * **Details**
+ *
+ * Both decode and encode are no-ops and return a shared singleton
+ * transformation.
  *
  * **Example** (Supertype passthrough)
  *
@@ -657,9 +678,8 @@ export declare function passthrough<T>(): Transformation<T, T>;
  * const t = SchemaTransformation.passthroughSupertype<"a" | "b", string>()
  * ```
  *
- * See also:
- * - {@link passthrough}
- * - {@link passthroughSubtype}
+ * @see {@link passthrough}
+ * @see {@link passthroughSubtype}
  *
  * @category constructors
  * @since 4.0.0
@@ -669,10 +689,12 @@ export declare function passthroughSupertype<T extends E, E>(): Transformation<T
  * A passthrough transformation typed so that `E extends T` — the encoded
  * type is a subtype of the decoded type.
  *
- * When to use this:
+ * **When to use**
+ *
  * - Narrowing: the encoded side is more specific than the decoded side.
  *
- * Behavior:
+ * **Details**
+ *
  * - Both decode and encode are no-ops (same as {@link passthrough}).
  * - Returns a shared singleton instance.
  *
@@ -684,9 +706,8 @@ export declare function passthroughSupertype<T extends E, E>(): Transformation<T
  * const t = SchemaTransformation.passthroughSubtype<string, "a" | "b">()
  * ```
  *
- * See also:
- * - {@link passthrough}
- * - {@link passthroughSupertype}
+ * @see {@link passthrough}
+ * @see {@link passthroughSupertype}
  *
  * @category constructors
  * @since 4.0.0
@@ -696,10 +717,12 @@ export declare function passthroughSubtype<T, E extends T>(): Transformation<T,
  * 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
@@ -715,9 +738,8 @@ export declare function passthroughSubtype<T, E extends T>(): Transformation<T,
  * )
  * ```
  *
- * See also:
- * - {@link bigintFromString}
- * - {@link transform}
+ * @see {@link bigintFromString}
+ * @see {@link transform}
  *
  * @category Coercions
  * @since 4.0.0
@@ -727,10 +749,12 @@ export declare const numberFromString: Transformation<number, string, never, nev
  * 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.
@@ -745,9 +769,8 @@ export declare const numberFromString: Transformation<number, string, never, nev
  * )
  * ```
  *
- * See also:
- * - {@link numberFromString}
- * - {@link transform}
+ * @see {@link numberFromString}
+ * @see {@link transform}
  *
  * @category Coercions
  * @since 4.0.0
@@ -756,10 +779,12 @@ export declare const bigintFromString: Transformation<bigint, string, never, nev
 /**
  * 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.
@@ -774,9 +799,8 @@ export declare const bigintFromString: Transformation<bigint, string, never, nev
  * )
  * ```
  *
- * See also:
- * - {@link numberFromString}
- * - {@link dateTimeUtcFromString}
+ * @see {@link numberFromString}
+ * @see {@link dateTimeUtcFromString}
  *
  * @category Coercions
  * @since 4.0.0
@@ -786,10 +810,12 @@ export declare const dateFromString: Transformation<globalThis.Date, string>;
  * 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"`
@@ -805,9 +831,8 @@ export declare const dateFromString: Transformation<globalThis.Date, string>;
  * )
  * ```
  *
- * See also:
- * - {@link durationFromNanos}
- * - {@link durationFromMillis}
+ * @see {@link durationFromNanos}
+ * @see {@link durationFromMillis}
  *
  * @category transforming
  * @since 4.0.0
@@ -817,10 +842,12 @@ export declare const durationFromString: Transformation<Duration.Duration, strin
  * 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`).
@@ -835,8 +862,7 @@ export declare const durationFromString: Transformation<Duration.Duration, strin
  * )
  * ```
  *
- * See also:
- * - {@link durationFromMillis}
+ * @see {@link durationFromMillis}
  *
  * @category transforming
  * @since 4.0.0
@@ -846,9 +872,15 @@ export declare const durationFromNanos: Transformation<Duration.Duration, bigint
  * 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)
  *
@@ -860,8 +892,7 @@ export declare const durationFromNanos: Transformation<Duration.Duration, bigint
  * )
  * ```
  *
- * See also:
- * - {@link durationFromNanos}
+ * @see {@link durationFromNanos}
  *
  * @category transforming
  * @since 4.0.0
@@ -871,10 +902,12 @@ export declare const durationFromMillis: Transformation<Duration.Duration, numbe
  * 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.
@@ -892,8 +925,7 @@ export declare const durationFromMillis: Transformation<Duration.Duration, numbe
  * )
  * ```
  *
- * See also:
- * - {@link optionFromNullishOr}
+ * @see {@link optionFromNullishOr}
  *
  * @category transforming
  * @since 4.0.0
@@ -903,10 +935,12 @@ export declare function optionFromNullOr<T>(): Transformation<Option.Option<T>,
  * 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.
@@ -924,9 +958,8 @@ export declare function optionFromNullOr<T>(): Transformation<Option.Option<T>,
  * )
  * ```
  *
- * See also:
- * - {@link optionFromOptionalKey}
- * - {@link optionFromOptional}
+ * @see {@link optionFromOptionalKey}
+ * @see {@link optionFromOptional}
  *
  * @category transforming
  * @since 4.0.0
@@ -934,13 +967,16 @@ export declare function optionFromNullOr<T>(): Transformation<Option.Option<T>,
 export declare function optionFromUndefinedOr<T>(): Transformation<Option.Option<T>, T | undefined>;
 /**
  * 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`.
@@ -959,9 +995,8 @@ export declare function optionFromUndefinedOr<T>(): Transformation<Option.Option
  * )
  * ```
  *
- * See also:
- * - {@link optionFromNullOr}
- * - {@link optionFromUndefinedOr}
+ * @see {@link optionFromNullOr}
+ * @see {@link optionFromUndefinedOr}
  *
  * @category transforming
  * @since 4.0.0
@@ -973,11 +1008,13 @@ export declare function optionFromNullishOr<T>(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.
@@ -997,10 +1034,9 @@ export declare function optionFromNullishOr<T>(options?: {
  * })
  * ```
  *
- * See also:
- * - {@link optionFromOptional}
- * - {@link optionFromUndefinedOr}
- * - {@link transformOptional}
+ * @see {@link optionFromOptional}
+ * @see {@link optionFromUndefinedOr}
+ * @see {@link transformOptional}
  *
  * @category transforming
  * @since 4.0.0
@@ -1010,10 +1046,12 @@ export declare function optionFromOptionalKey<T>(): Transformation<Option.Option
  * 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.
@@ -1033,10 +1071,9 @@ export declare function optionFromOptionalKey<T>(): Transformation<Option.Option
  * })
  * ```
  *
- * See also:
- * - {@link optionFromOptionalKey}
- * - {@link optionFromUndefinedOr}
- * - {@link transformOptional}
+ * @see {@link optionFromOptionalKey}
+ * @see {@link optionFromUndefinedOr}
+ * @see {@link transformOptional}
  *
  * @category transforming
  * @since 4.0.0
@@ -1046,10 +1083,12 @@ export declare function optionFromOptional<T>(): Transformation<Option.Option<T>
  * 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`.
@@ -1064,9 +1103,8 @@ export declare function optionFromOptional<T>(): Transformation<Option.Option<T>
  * )
  * ```
  *
- * See also:
- * - {@link numberFromString}
- * - {@link transformOrFail}
+ * @see {@link numberFromString}
+ * @see {@link transformOrFail}
  *
  * @category transforming
  * @since 4.0.0
@@ -1076,10 +1114,12 @@ export declare const urlFromString: Transformation<URL, string>;
  * 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)`.
@@ -1092,11 +1132,13 @@ export declare const bigDecimalFromString: Transformation<BigDecimal.BigDecimal,
  * 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.
  *
@@ -1110,9 +1152,8 @@ export declare const bigDecimalFromString: Transformation<BigDecimal.BigDecimal,
  * )
  * ```
  *
- * 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
@@ -1122,10 +1163,12 @@ export declare const uint8ArrayFromBase64String: Transformation<Uint8Array<Array
  * 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.
  *
@@ -1139,9 +1182,8 @@ export declare const uint8ArrayFromBase64String: Transformation<Uint8Array<Array
  * )
  * ```
  *
- * 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
@@ -1150,10 +1192,12 @@ export declare const stringFromBase64String: Transformation<string, string>;
 /**
  * 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.
  *
@@ -1167,9 +1211,8 @@ export declare const stringFromBase64String: Transformation<string, string>;
  * )
  * ```
  *
- * 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
@@ -1178,10 +1221,12 @@ export declare const stringFromBase64UrlString: Transformation<string, string>;
 /**
  * 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.
  *
@@ -1195,9 +1240,8 @@ export declare const stringFromBase64UrlString: Transformation<string, string>;
  * )
  * ```
  *
- * 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
@@ -1207,11 +1251,13 @@ export declare const stringFromHexString: Transformation<string, string>;
  * 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`.
@@ -1226,9 +1272,8 @@ export declare const stringFromHexString: Transformation<string, string>;
  * )
  * ```
  *
- * 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
@@ -1238,10 +1283,15 @@ export declare const stringFromUriComponent: Transformation<string, string>;
  * 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)
  *
@@ -1253,9 +1303,8 @@ export declare const stringFromUriComponent: Transformation<string, string>;
  * )
  * ```
  *
- * See also:
- * - {@link uint8ArrayFromBase64String}
- * - {@link fromFormData}
+ * @see {@link uint8ArrayFromBase64String}
+ * @see {@link fromFormData}
  *
  * @category decoding
  * @since 4.0.0
@@ -1265,10 +1314,16 @@ export declare const fromJsonString: Transformation<unknown, string, never, neve
  * 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)
  *
@@ -1280,9 +1335,8 @@ export declare const fromJsonString: Transformation<unknown, string, never, neve
  * )
  * ```
  *
- * See also:
- * - {@link fromURLSearchParams}
- * - {@link fromJsonString}
+ * @see {@link fromURLSearchParams}
+ * @see {@link fromJsonString}
  *
  * @category decoding
  * @since 4.0.0
@@ -1292,10 +1346,16 @@ export declare const fromFormData: Transformation<unknown, FormData, never, neve
  * 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)
  *
@@ -1307,9 +1367,8 @@ export declare const fromFormData: Transformation<unknown, FormData, never, neve
  * )
  * ```
  *
- * See also:
- * - {@link fromFormData}
- * - {@link fromJsonString}
+ * @see {@link fromFormData}
+ * @see {@link fromJsonString}
  *
  * @category decoding
  * @since 4.0.0
@@ -1319,6 +1378,8 @@ export declare const fromURLSearchParams: Transformation<unknown, URLSearchParam
  * 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.
  *
@@ -1330,6 +1391,8 @@ export declare const timeZoneOffsetFromNumber: Transformation<DateTime.TimeZone.
  * 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.
  *
@@ -1341,6 +1404,8 @@ export declare const timeZoneNamedFromString: Transformation<DateTime.TimeZone.N
  * 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.
@@ -1353,6 +1418,8 @@ export declare const timeZoneFromString: Transformation<DateTime.TimeZone, strin
  * 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`.
@@ -1365,6 +1432,8 @@ export declare const dateTimeUtcFromString: Transformation<DateTime.Utc, string>
  * 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`.