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

package/src/Struct.ts

@@ -83,10 +83,14 @@ import * as Reducer from "./Reducer.ts"
 /**
  * Flattens intersection types into a single object type for readability.
  *
- * - Use when hovering over a type shows `A & B & C` instead of the merged
- *   shape.
- * - Purely cosmetic — no runtime effect.
- * - Preserves `readonly` modifiers; use {@link Mutable} to strip them.
+ * **When to use**
+ *
+ * Use when hovering over a type shows `A & B & C` instead of the merged shape.
+ *
+ * **Details**
+ *
+ * This helper is purely cosmetic at the type level and has no runtime effect.
+ * It preserves `readonly` modifiers; use {@link Mutable} to strip them.
  *
  * **Example** (Flattening an intersection)
  *
@@ -102,7 +106,6 @@ import * as Reducer from "./Reducer.ts"
  *
  * @see {@link Mutable} – also flattens but removes `readonly`
  * @see {@link Assign} – merges two types with right-side precedence
- *
  * @category Type-Level Programming
  * @since 4.0.0
  */
@@ -111,9 +114,14 @@ export type Simplify<T> = { [K in keyof T]: T[K] } & {}
 /**
  * Removes `readonly` modifiers from all properties of an object type.
  *
- * - Use when you need a mutable version of a readonly interface.
- * - Purely cosmetic at the type level — no runtime effect.
- * - Also flattens intersections like {@link Simplify}.
+ * **When to use**
+ *
+ * Use when you need a mutable version of a readonly interface.
+ *
+ * **Details**
+ *
+ * This helper is purely cosmetic at the type level and has no runtime effect.
+ * It also flattens intersections like {@link Simplify}.
  *
  * **Example** (Making a readonly type mutable)
  *
@@ -126,7 +134,6 @@ export type Simplify<T> = { [K in keyof T]: T[K] } & {}
  * ```
  *
  * @see {@link Simplify} – flattens intersections without removing `readonly`
- *
  * @category Type-Level Programming
  * @since 4.0.0
  */
@@ -136,9 +143,14 @@ export type Mutable<T> = { -readonly [K in keyof T]: T[K] } & {}
  * Merges two object types with properties from `U` taking precedence over `T`
  * on overlapping keys (like `Object.assign` at the type level).
  *
- * - Use when you need the type-level equivalent of `{ ...T, ...U }`.
- * - When no keys overlap, returns a simple intersection for efficiency.
- * - When keys overlap, the type from `U` wins.
+ * **When to use**
+ *
+ * Use when you need the type-level equivalent of `{ ...T, ...U }`.
+ *
+ * **Details**
+ *
+ * When no keys overlap, this returns a simple intersection for efficiency.
+ * When keys overlap, the type from `U` wins.
  *
  * **Example** (Merging two types with overlapping keys)
  *
@@ -153,7 +165,6 @@ export type Mutable<T> = { -readonly [K in keyof T]: T[K] } & {}
  *
  * @see {@link assign} – the runtime equivalent
  * @see {@link Simplify} – flatten the resulting intersection
- *
  * @category Type-Level Programming
  * @since 4.0.0
  */
@@ -162,9 +173,13 @@ export type Assign<T, U> = Simplify<keyof T & keyof U extends never ? T & U : Om
 /**
  * Retrieves the value at `key` from a struct.
  *
- * - Use in a pipeline when you need to extract a single property.
- * - Does not mutate the input.
- * - The return type is narrowed to `S[K]`.
+ * **When to use**
+ *
+ * Use in a pipeline when you need to extract a single property.
+ *
+ * **Details**
+ *
+ * This does not mutate the input, and the return type is narrowed to `S[K]`.
  *
  * **Example** (Extracting a property in a pipeline)
  *
@@ -177,7 +192,6 @@ export type Assign<T, U> = Simplify<keyof T & keyof U extends never ? T & U : Om
  *
  * @see {@link keys} – list all string keys of a struct
  * @see {@link pick} – extract multiple properties into a new struct
- *
  * @category getters
  * @since 2.0.0
  */
@@ -185,9 +199,13 @@ export const get: {
   /**
    * Retrieves the value at `key` from a struct.
    *
-   * - Use in a pipeline when you need to extract a single property.
-   * - Does not mutate the input.
-   * - The return type is narrowed to `S[K]`.
+   * **When to use**
+   *
+   * Use in a pipeline when you need to extract a single property.
+   *
+   * **Details**
+   *
+   * This does not mutate the input, and the return type is narrowed to `S[K]`.
    *
    * **Example** (Extracting a property in a pipeline)
    *
@@ -200,7 +218,6 @@ export const get: {
    *
    * @see {@link keys} – list all string keys of a struct
    * @see {@link pick} – extract multiple properties into a new struct
-   *
    * @category getters
    * @since 2.0.0
    */
@@ -208,9 +225,13 @@ export const get: {
   /**
    * Retrieves the value at `key` from a struct.
    *
-   * - Use in a pipeline when you need to extract a single property.
-   * - Does not mutate the input.
-   * - The return type is narrowed to `S[K]`.
+   * **When to use**
+   *
+   * Use in a pipeline when you need to extract a single property.
+   *
+   * **Details**
+   *
+   * This does not mutate the input, and the return type is narrowed to `S[K]`.
    *
    * **Example** (Extracting a property in a pipeline)
    *
@@ -223,7 +244,6 @@ export const get: {
    *
    * @see {@link keys} – list all string keys of a struct
    * @see {@link pick} – extract multiple properties into a new struct
-   *
    * @category getters
    * @since 2.0.0
    */
@@ -233,10 +253,18 @@ export const get: {
 /**
  * Returns the string keys of a struct as a properly typed `Array<keyof S & string>`.
  *
- * - Use instead of `Object.keys` when you want the return type narrowed to the
- *   known keys of the struct.
- * - Symbol keys are excluded; only string keys are returned.
- * - Does not mutate the input.
+ * **When to use**
+ *
+ * Use instead of `Object.keys` when you want the return type narrowed to the
+ * known keys of the struct.
+ *
+ * **Details**
+ *
+ * This does not mutate the input.
+ *
+ * **Gotchas**
+ *
+ * Symbol keys are excluded; only string keys are returned.
  *
  * **Example** (Typed keys)
  *
@@ -251,7 +279,6 @@ export const get: {
  *
  * @see {@link get} – access a single key's value
  * @see {@link pick} – select a subset of keys into a new struct
- *
  * @category Key utilities
  * @since 3.6.0
  */
@@ -261,9 +288,17 @@ export const keys = <S extends object>(self: S): Array<(keyof S) & string> =>
 /**
  * Creates a new struct containing only the specified keys.
  *
- * - Use to narrow a struct down to a subset of its properties.
- * - Does not mutate the input; returns a fresh object.
- * - Keys not present in the struct are silently ignored.
+ * **When to use**
+ *
+ * Use to narrow a struct down to a subset of its properties.
+ *
+ * **Details**
+ *
+ * This does not mutate the input and returns a fresh object.
+ *
+ * **Gotchas**
+ *
+ * Keys not present in the struct are silently ignored.
  *
  * **Example** (Selecting specific properties)
  *
@@ -277,7 +312,6 @@ export const keys = <S extends object>(self: S): Array<(keyof S) & string> =>
  *
  * @see {@link omit} – the inverse (exclude keys instead)
  * @see {@link get} – extract a single value
- *
  * @category filtering
  * @since 2.0.0
  */
@@ -285,9 +319,17 @@ export const pick: {
   /**
    * Creates a new struct containing only the specified keys.
    *
-   * - Use to narrow a struct down to a subset of its properties.
-   * - Does not mutate the input; returns a fresh object.
-   * - Keys not present in the struct are silently ignored.
+   * **When to use**
+   *
+   * Use to narrow a struct down to a subset of its properties.
+   *
+   * **Details**
+   *
+   * This does not mutate the input and returns a fresh object.
+   *
+   * **Gotchas**
+   *
+   * Keys not present in the struct are silently ignored.
    *
    * **Example** (Selecting specific properties)
    *
@@ -301,7 +343,6 @@ export const pick: {
    *
    * @see {@link omit} – the inverse (exclude keys instead)
    * @see {@link get} – extract a single value
-   *
    * @category filtering
    * @since 2.0.0
    */
@@ -309,9 +350,17 @@ export const pick: {
   /**
    * Creates a new struct containing only the specified keys.
    *
-   * - Use to narrow a struct down to a subset of its properties.
-   * - Does not mutate the input; returns a fresh object.
-   * - Keys not present in the struct are silently ignored.
+   * **When to use**
+   *
+   * Use to narrow a struct down to a subset of its properties.
+   *
+   * **Details**
+   *
+   * This does not mutate the input and returns a fresh object.
+   *
+   * **Gotchas**
+   *
+   * Keys not present in the struct are silently ignored.
    *
    * **Example** (Selecting specific properties)
    *
@@ -325,7 +374,6 @@ export const pick: {
    *
    * @see {@link omit} – the inverse (exclude keys instead)
    * @see {@link get} – extract a single value
-   *
    * @category filtering
    * @since 2.0.0
    */
@@ -340,9 +388,17 @@ export const pick: {
 /**
  * Creates a new struct with the specified keys removed.
  *
- * - Use to exclude sensitive or irrelevant fields from a struct.
- * - Does not mutate the input; returns a fresh object.
- * - Keys not present in the struct are silently ignored.
+ * **When to use**
+ *
+ * Use to exclude sensitive or irrelevant fields from a struct.
+ *
+ * **Details**
+ *
+ * This does not mutate the input and returns a fresh object.
+ *
+ * **Gotchas**
+ *
+ * Keys not present in the struct are silently ignored.
  *
  * **Example** (Removing a property)
  *
@@ -355,7 +411,6 @@ export const pick: {
  * ```
  *
  * @see {@link pick} – the inverse (keep only specified keys)
- *
  * @category filtering
  * @since 2.0.0
  */
@@ -363,9 +418,17 @@ export const omit: {
   /**
    * Creates a new struct with the specified keys removed.
    *
-   * - Use to exclude sensitive or irrelevant fields from a struct.
-   * - Does not mutate the input; returns a fresh object.
-   * - Keys not present in the struct are silently ignored.
+   * **When to use**
+   *
+   * Use to exclude sensitive or irrelevant fields from a struct.
+   *
+   * **Details**
+   *
+   * This does not mutate the input and returns a fresh object.
+   *
+   * **Gotchas**
+   *
+   * Keys not present in the struct are silently ignored.
    *
    * **Example** (Removing a property)
    *
@@ -378,7 +441,6 @@ export const omit: {
    * ```
    *
    * @see {@link pick} – the inverse (keep only specified keys)
-   *
    * @category filtering
    * @since 2.0.0
    */
@@ -386,9 +448,17 @@ export const omit: {
   /**
    * Creates a new struct with the specified keys removed.
    *
-   * - Use to exclude sensitive or irrelevant fields from a struct.
-   * - Does not mutate the input; returns a fresh object.
-   * - Keys not present in the struct are silently ignored.
+   * **When to use**
+   *
+   * Use to exclude sensitive or irrelevant fields from a struct.
+   *
+   * **Details**
+   *
+   * This does not mutate the input and returns a fresh object.
+   *
+   * **Gotchas**
+   *
+   * Keys not present in the struct are silently ignored.
    *
    * **Example** (Removing a property)
    *
@@ -401,7 +471,6 @@ export const omit: {
    * ```
    *
    * @see {@link pick} – the inverse (keep only specified keys)
-   *
    * @category filtering
    * @since 2.0.0
    */
@@ -417,9 +486,14 @@ export const omit: {
  * Merges two structs into a new struct. When both structs share a key, the
  * value from `that` (the second struct) wins.
  *
- * - Use when you want `{ ...self, ...that }` with proper types.
- * - Does not mutate either input; returns a fresh object.
- * - The result type is `Simplify<Assign<S, O>>`.
+ * **When to use**
+ *
+ * Use when you want `{ ...self, ...that }` with proper types.
+ *
+ * **Details**
+ *
+ * This does not mutate either input and returns a fresh object. The result type
+ * is `Simplify<Assign<S, O>>`.
  *
  * **Example** (Merging structs with overlapping keys)
  *
@@ -434,7 +508,6 @@ export const omit: {
  *
  * @see {@link Assign} – the type-level equivalent
  * @see {@link evolve} – transform individual values instead of replacing them
- *
  * @category combining
  * @since 4.0.0
  */
@@ -443,9 +516,14 @@ export const assign: {
    * Merges two structs into a new struct. When both structs share a key, the
    * value from `that` (the second struct) wins.
    *
-   * - Use when you want `{ ...self, ...that }` with proper types.
-   * - Does not mutate either input; returns a fresh object.
-   * - The result type is `Simplify<Assign<S, O>>`.
+   * **When to use**
+   *
+   * Use when you want `{ ...self, ...that }` with proper types.
+   *
+   * **Details**
+   *
+   * This does not mutate either input and returns a fresh object. The result type
+   * is `Simplify<Assign<S, O>>`.
    *
    * **Example** (Merging structs with overlapping keys)
    *
@@ -460,7 +538,6 @@ export const assign: {
    *
    * @see {@link Assign} – the type-level equivalent
    * @see {@link evolve} – transform individual values instead of replacing them
-   *
    * @category combining
    * @since 4.0.0
    */
@@ -469,9 +546,14 @@ export const assign: {
    * Merges two structs into a new struct. When both structs share a key, the
    * value from `that` (the second struct) wins.
    *
-   * - Use when you want `{ ...self, ...that }` with proper types.
-   * - Does not mutate either input; returns a fresh object.
-   * - The result type is `Simplify<Assign<S, O>>`.
+   * **When to use**
+   *
+   * Use when you want `{ ...self, ...that }` with proper types.
+   *
+   * **Details**
+   *
+   * This does not mutate either input and returns a fresh object. The result type
+   * is `Simplify<Assign<S, O>>`.
    *
    * **Example** (Merging structs with overlapping keys)
    *
@@ -486,7 +568,6 @@ export const assign: {
    *
    * @see {@link Assign} – the type-level equivalent
    * @see {@link evolve} – transform individual values instead of replacing them
-   *
    * @category combining
    * @since 4.0.0
    */
@@ -508,10 +589,15 @@ type Evolved<S, E> = Simplify<
  * Selectively transforms values of a struct using per-key functions. Keys
  * without a corresponding function are copied unchanged.
  *
- * - Use when you want to update specific fields while keeping the rest intact.
- * - Does not mutate the input; returns a fresh object.
- * - Each transform function receives the current value and returns the new
- *   value; the return type can differ from the input type.
+ * **When to use**
+ *
+ * Use when you want to update specific fields while keeping the rest intact.
+ *
+ * **Details**
+ *
+ * This does not mutate the input and returns a fresh object. Each transform
+ * function receives the current value and returns the new value; the return
+ * type can differ from the input type.
  *
  * **Example** (Transforming selected values)
  *
@@ -531,7 +617,6 @@ type Evolved<S, E> = Simplify<
  * @see {@link evolveKeys} – transform keys instead of values
  * @see {@link evolveEntries} – transform both keys and values
  * @see {@link map} – apply the same transformation to all values
- *
  * @category transforming
  * @since 2.0.0
  */
@@ -540,10 +625,15 @@ export const evolve: {
    * Selectively transforms values of a struct using per-key functions. Keys
    * without a corresponding function are copied unchanged.
    *
-   * - Use when you want to update specific fields while keeping the rest intact.
-   * - Does not mutate the input; returns a fresh object.
-   * - Each transform function receives the current value and returns the new
-   *   value; the return type can differ from the input type.
+   * **When to use**
+   *
+   * Use when you want to update specific fields while keeping the rest intact.
+   *
+   * **Details**
+   *
+   * This does not mutate the input and returns a fresh object. Each transform
+   * function receives the current value and returns the new value; the return
+   * type can differ from the input type.
    *
    * **Example** (Transforming selected values)
    *
@@ -563,7 +653,6 @@ export const evolve: {
    * @see {@link evolveKeys} – transform keys instead of values
    * @see {@link evolveEntries} – transform both keys and values
    * @see {@link map} – apply the same transformation to all values
-   *
    * @category transforming
    * @since 2.0.0
    */
@@ -572,10 +661,15 @@ export const evolve: {
    * Selectively transforms values of a struct using per-key functions. Keys
    * without a corresponding function are copied unchanged.
    *
-   * - Use when you want to update specific fields while keeping the rest intact.
-   * - Does not mutate the input; returns a fresh object.
-   * - Each transform function receives the current value and returns the new
-   *   value; the return type can differ from the input type.
+   * **When to use**
+   *
+   * Use when you want to update specific fields while keeping the rest intact.
+   *
+   * **Details**
+   *
+   * This does not mutate the input and returns a fresh object. Each transform
+   * function receives the current value and returns the new value; the return
+   * type can differ from the input type.
    *
    * **Example** (Transforming selected values)
    *
@@ -595,7 +689,6 @@ export const evolve: {
    * @see {@link evolveKeys} – transform keys instead of values
    * @see {@link evolveEntries} – transform both keys and values
    * @see {@link map} – apply the same transformation to all values
-   *
    * @category transforming
    * @since 2.0.0
    */
@@ -617,10 +710,14 @@ type KeyEvolved<S, E> = Simplify<
  * Selectively transforms keys of a struct using per-key functions. Keys without
  * a corresponding function are copied unchanged.
  *
- * - Use when you need computed key names (e.g., uppercasing, prefixing).
- * - Each transform function receives the key name and must return a new
- *   `PropertyKey`.
- * - Does not mutate the input; returns a fresh object.
+ * **When to use**
+ *
+ * Use when you need computed key names, such as uppercasing or prefixing.
+ *
+ * **Details**
+ *
+ * Each transform function receives the key name and must return a new
+ * `PropertyKey`. This does not mutate the input and returns a fresh object.
  *
  * **Example** (Renaming keys with functions)
  *
@@ -639,7 +736,6 @@ type KeyEvolved<S, E> = Simplify<
  * @see {@link renameKeys} – rename keys with a static mapping
  * @see {@link evolve} – transform values instead of keys
  * @see {@link evolveEntries} – transform both keys and values
- *
  * @category Key utilities
  * @since 4.0.0
  */
@@ -648,10 +744,14 @@ export const evolveKeys: {
    * Selectively transforms keys of a struct using per-key functions. Keys without
    * a corresponding function are copied unchanged.
    *
-   * - Use when you need computed key names (e.g., uppercasing, prefixing).
-   * - Each transform function receives the key name and must return a new
-   *   `PropertyKey`.
-   * - Does not mutate the input; returns a fresh object.
+   * **When to use**
+   *
+   * Use when you need computed key names, such as uppercasing or prefixing.
+   *
+   * **Details**
+   *
+   * Each transform function receives the key name and must return a new
+   * `PropertyKey`. This does not mutate the input and returns a fresh object.
    *
    * **Example** (Renaming keys with functions)
    *
@@ -670,7 +770,6 @@ export const evolveKeys: {
    * @see {@link renameKeys} – rename keys with a static mapping
    * @see {@link evolve} – transform values instead of keys
    * @see {@link evolveEntries} – transform both keys and values
-   *
    * @category Key utilities
    * @since 4.0.0
    */
@@ -679,10 +778,14 @@ export const evolveKeys: {
    * Selectively transforms keys of a struct using per-key functions. Keys without
    * a corresponding function are copied unchanged.
    *
-   * - Use when you need computed key names (e.g., uppercasing, prefixing).
-   * - Each transform function receives the key name and must return a new
-   *   `PropertyKey`.
-   * - Does not mutate the input; returns a fresh object.
+   * **When to use**
+   *
+   * Use when you need computed key names, such as uppercasing or prefixing.
+   *
+   * **Details**
+   *
+   * Each transform function receives the key name and must return a new
+   * `PropertyKey`. This does not mutate the input and returns a fresh object.
    *
    * **Example** (Renaming keys with functions)
    *
@@ -701,7 +804,6 @@ export const evolveKeys: {
    * @see {@link renameKeys} – rename keys with a static mapping
    * @see {@link evolve} – transform values instead of keys
    * @see {@link evolveEntries} – transform both keys and values
-   *
    * @category Key utilities
    * @since 4.0.0
    */
@@ -730,9 +832,14 @@ type EntryEvolved<S, E> = {
  * function receives `(key, value)` and must return a `[newKey, newValue]`
  * tuple. Keys without a corresponding function are copied unchanged.
  *
- * - Use when you need to rename a key and change its value in one step.
- * - Does not mutate the input; returns a fresh object.
- * - The return type is fully tracked at the type level.
+ * **When to use**
+ *
+ * Use when you need to rename a key and change its value in one step.
+ *
+ * **Details**
+ *
+ * This does not mutate the input and returns a fresh object. The return type is
+ * fully tracked at the type level.
  *
  * **Example** (Transforming keys and values together)
  *
@@ -751,7 +858,6 @@ type EntryEvolved<S, E> = {
  *
  * @see {@link evolve} – transform values only
  * @see {@link evolveKeys} – transform keys only
- *
  * @category utils
  * @since 4.0.0
  */
@@ -761,9 +867,14 @@ export const evolveEntries: {
    * function receives `(key, value)` and must return a `[newKey, newValue]`
    * tuple. Keys without a corresponding function are copied unchanged.
    *
-   * - Use when you need to rename a key and change its value in one step.
-   * - Does not mutate the input; returns a fresh object.
-   * - The return type is fully tracked at the type level.
+   * **When to use**
+   *
+   * Use when you need to rename a key and change its value in one step.
+   *
+   * **Details**
+   *
+   * This does not mutate the input and returns a fresh object. The return type is
+   * fully tracked at the type level.
    *
    * **Example** (Transforming keys and values together)
    *
@@ -782,7 +893,6 @@ export const evolveEntries: {
    *
    * @see {@link evolve} – transform values only
    * @see {@link evolveKeys} – transform keys only
-   *
    * @category utils
    * @since 4.0.0
    */
@@ -792,9 +902,14 @@ export const evolveEntries: {
    * function receives `(key, value)` and must return a `[newKey, newValue]`
    * tuple. Keys without a corresponding function are copied unchanged.
    *
-   * - Use when you need to rename a key and change its value in one step.
-   * - Does not mutate the input; returns a fresh object.
-   * - The return type is fully tracked at the type level.
+   * **When to use**
+   *
+   * Use when you need to rename a key and change its value in one step.
+   *
+   * **Details**
+   *
+   * This does not mutate the input and returns a fresh object. The return type is
+   * fully tracked at the type level.
    *
    * **Example** (Transforming keys and values together)
    *
@@ -813,7 +928,6 @@ export const evolveEntries: {
    *
    * @see {@link evolve} – transform values only
    * @see {@link evolveKeys} – transform keys only
-   *
    * @category utils
    * @since 4.0.0
    */
@@ -829,9 +943,14 @@ export const evolveEntries: {
  * Renames keys in a struct using a static `{ oldKey: newKey }` mapping. Keys
  * not mentioned in the mapping are copied unchanged.
  *
- * - Use for simple, declarative key renaming without custom logic.
- * - Does not mutate the input; returns a fresh object.
- * - For computed key names, use {@link evolveKeys} instead.
+ * **When to use**
+ *
+ * Use for simple, declarative key renaming without custom logic.
+ *
+ * **Details**
+ *
+ * This does not mutate the input and returns a fresh object. For computed key
+ * names, use {@link evolveKeys} instead.
  *
  * **Example** (Renaming keys)
  *
@@ -847,7 +966,6 @@ export const evolveEntries: {
  *
  * @see {@link evolveKeys} – rename keys using functions
  * @see {@link evolveEntries} – rename keys and transform values
- *
  * @category Key utilities
  * @since 4.0.0
  */
@@ -856,9 +974,14 @@ export const renameKeys: {
    * Renames keys in a struct using a static `{ oldKey: newKey }` mapping. Keys
    * not mentioned in the mapping are copied unchanged.
    *
-   * - Use for simple, declarative key renaming without custom logic.
-   * - Does not mutate the input; returns a fresh object.
-   * - For computed key names, use {@link evolveKeys} instead.
+   * **When to use**
+   *
+   * Use for simple, declarative key renaming without custom logic.
+   *
+   * **Details**
+   *
+   * This does not mutate the input and returns a fresh object. For computed key
+   * names, use {@link evolveKeys} instead.
    *
    * **Example** (Renaming keys)
    *
@@ -874,7 +997,6 @@ export const renameKeys: {
    *
    * @see {@link evolveKeys} – rename keys using functions
    * @see {@link evolveEntries} – rename keys and transform values
-   *
    * @category Key utilities
    * @since 4.0.0
    */
@@ -883,9 +1005,14 @@ export const renameKeys: {
    * Renames keys in a struct using a static `{ oldKey: newKey }` mapping. Keys
    * not mentioned in the mapping are copied unchanged.
    *
-   * - Use for simple, declarative key renaming without custom logic.
-   * - Does not mutate the input; returns a fresh object.
-   * - For computed key names, use {@link evolveKeys} instead.
+   * **When to use**
+   *
+   * Use for simple, declarative key renaming without custom logic.
+   *
+   * **Details**
+   *
+   * This does not mutate the input and returns a fresh object. For computed key
+   * names, use {@link evolveKeys} instead.
    *
    * **Example** (Renaming keys)
    *
@@ -901,7 +1028,6 @@ export const renameKeys: {
    *
    * @see {@link evolveKeys} – rename keys using functions
    * @see {@link evolveEntries} – rename keys and transform values
-   *
    * @category Key utilities
    * @since 4.0.0
    */
@@ -915,11 +1041,15 @@ export const renameKeys: {
  * property. Two structs are equivalent when all their corresponding properties
  * are equivalent.
  *
- * Alias of `Equivalence.Struct`.
+ * **When to use**
  *
- * - Use when you need to compare structs property-by-property.
- * - Each property's equivalence is checked independently; all must return
- *   `true` for the overall result to be `true`.
+ * Use when you need to compare structs property-by-property.
+ *
+ * **Details**
+ *
+ * This is an alias of `Equivalence.Struct`. Each property's equivalence is
+ * checked independently; all must return `true` for the overall result to be
+ * `true`.
  *
  * **Example** (Comparing structs for equivalence)
  *
@@ -938,7 +1068,6 @@ export const renameKeys: {
  * ```
  *
  * @see {@link makeOrder} – create an `Order` for structs
- *
  * @category Equivalence
  * @since 4.0.0
  */
@@ -949,11 +1078,15 @@ export const makeEquivalence = Equivalence.Struct
  * Properties are compared in the order they appear in the fields object; the
  * first non-zero comparison determines the result.
  *
- * Alias of `Order.Struct`.
+ * **When to use**
  *
- * - Use to sort or compare structs by multiple fields with lexicographic
- *   priority.
- * - The order of keys in the `fields` object determines comparison priority.
+ * Use to sort or compare structs by multiple fields with lexicographic
+ * priority.
+ *
+ * **Details**
+ *
+ * This is an alias of `Order.Struct`. The order of keys in the `fields` object
+ * determines comparison priority.
  *
  * **Example** (Ordering structs by name then age)
  *
@@ -970,7 +1103,6 @@ export const makeEquivalence = Equivalence.Struct
  * ```
  *
  * @see {@link makeEquivalence} – create an `Equivalence` for structs
- *
  * @category Ordering
  * @since 4.0.0
  */
@@ -980,9 +1112,16 @@ export const makeOrder = order.Struct
  * Interface for type-level functions used by {@link map}, {@link mapPick}, and
  * {@link mapOmit}.
  *
- * - Extend this interface with concrete `~lambda.in` and `~lambda.out` types
- *   to describe how a function transforms values at the type level.
- * - At runtime, create lambda values with {@link lambda}.
+ * **When to use**
+ *
+ * Use this interface when defining a typed function for {@link map},
+ * {@link mapPick}, or {@link mapOmit}.
+ *
+ * **Details**
+ *
+ * Extend this interface with concrete `~lambda.in` and `~lambda.out` types to
+ * describe how a function transforms values at the type level. At runtime,
+ * create lambda values with {@link lambda}.
  *
  * **Example** (Defining a lambda type)
  *
@@ -997,7 +1136,6 @@ export const makeOrder = order.Struct
  * @see {@link Apply} – apply a Lambda to a concrete type
  * @see {@link lambda} – create a runtime lambda value
  * @see {@link map} – use a lambda to transform all struct values
- *
  * @category Lambda
  * @since 4.0.0
  */
@@ -1010,10 +1148,15 @@ export interface Lambda {
  * Applies a {@link Lambda} type-level function to a value type `V`, producing
  * the output type.
  *
- * - Use this when you need to compute what type a Lambda would produce for a
- *   given input.
- * - Works by intersecting the Lambda with `{ "~lambda.in": V }` and reading
- *   `"~lambda.out"`.
+ * **When to use**
+ *
+ * Use this when you need to compute what type a Lambda would produce for a
+ * given input.
+ *
+ * **Details**
+ *
+ * This works by intersecting the Lambda with `{ "~lambda.in": V }` and reading
+ * `"~lambda.out"`.
  *
  * **Example** (Computing the output type of a lambda)
  *
@@ -1029,7 +1172,6 @@ export interface Lambda {
  * ```
  *
  * @see {@link Lambda} – the base interface
- *
  * @category Lambda
  * @since 4.0.0
  */
@@ -1039,10 +1181,12 @@ export type Apply<L extends Lambda, V> = (L & { readonly "~lambda.in": V })["~la
  * Wraps a plain function as a {@link Lambda} value so it can be used with
  * {@link map}, {@link mapPick}, and {@link mapOmit}.
  *
- * - The type parameter `L` encodes both the input and output types at the type
- *   level, allowing the compiler to track how struct value types change.
- * - At runtime, the returned value is the same function — `lambda` only
- *   adjusts the type.
+ * **Details**
+ *
+ * The type parameter `L` encodes both the input and output types at the type
+ * level, allowing the compiler to track how struct value types change. At
+ * runtime, the returned value is the same function; `lambda` only adjusts the
+ * type.
  *
  * **Example** (Wrapping values in arrays)
  *
@@ -1061,7 +1205,6 @@ export type Apply<L extends Lambda, V> = (L & { readonly "~lambda.in": V })["~la
  *
  * @see {@link Lambda} – the type-level interface
  * @see {@link map} – apply a lambda to all struct values
- *
  * @category Lambda
  * @since 4.0.0
  */
@@ -1072,10 +1215,14 @@ export const lambda = <L extends (a: any) => any>(
 /**
  * Applies a {@link Lambda} transformation to every value in a struct.
  *
- * - Use when you want to apply the same function to every value in a struct.
- * - The lambda must be created with {@link lambda} so the compiler can track
- *   the output types.
- * - Does not mutate the input; returns a fresh object.
+ * **When to use**
+ *
+ * Use when you want to apply the same function to every value in a struct.
+ *
+ * **Details**
+ *
+ * The lambda must be created with {@link lambda} so the compiler can track the
+ * output types. This does not mutate the input and returns a fresh object.
  *
  * **Example** (Wrapping every value in an array)
  *
@@ -1095,7 +1242,6 @@ export const lambda = <L extends (a: any) => any>(
  * @see {@link mapPick} – apply a lambda only to selected keys
  * @see {@link mapOmit} – apply a lambda to all keys except selected ones
  * @see {@link evolve} – apply different functions to different keys
- *
  * @category mapping
  * @since 4.0.0
  */
@@ -1103,10 +1249,14 @@ export const map: {
   /**
    * Applies a {@link Lambda} transformation to every value in a struct.
    *
-   * - Use when you want to apply the same function to every value in a struct.
-   * - The lambda must be created with {@link lambda} so the compiler can track
-   *   the output types.
-   * - Does not mutate the input; returns a fresh object.
+   * **When to use**
+   *
+   * Use when you want to apply the same function to every value in a struct.
+   *
+   * **Details**
+   *
+   * The lambda must be created with {@link lambda} so the compiler can track the
+   * output types. This does not mutate the input and returns a fresh object.
    *
    * **Example** (Wrapping every value in an array)
    *
@@ -1126,7 +1276,6 @@ export const map: {
    * @see {@link mapPick} – apply a lambda only to selected keys
    * @see {@link mapOmit} – apply a lambda to all keys except selected ones
    * @see {@link evolve} – apply different functions to different keys
-   *
    * @category mapping
    * @since 4.0.0
    */
@@ -1134,10 +1283,14 @@ export const map: {
   /**
    * Applies a {@link Lambda} transformation to every value in a struct.
    *
-   * - Use when you want to apply the same function to every value in a struct.
-   * - The lambda must be created with {@link lambda} so the compiler can track
-   *   the output types.
-   * - Does not mutate the input; returns a fresh object.
+   * **When to use**
+   *
+   * Use when you want to apply the same function to every value in a struct.
+   *
+   * **Details**
+   *
+   * The lambda must be created with {@link lambda} so the compiler can track the
+   * output types. This does not mutate the input and returns a fresh object.
    *
    * **Example** (Wrapping every value in an array)
    *
@@ -1157,7 +1310,6 @@ export const map: {
    * @see {@link mapPick} – apply a lambda only to selected keys
    * @see {@link mapOmit} – apply a lambda to all keys except selected ones
    * @see {@link evolve} – apply different functions to different keys
-   *
    * @category mapping
    * @since 4.0.0
    */
@@ -1173,9 +1325,13 @@ export const map: {
  * Applies a {@link Lambda} transformation only to the specified keys; all
  * other keys are copied unchanged.
  *
- * - Use when you want to apply the same transformation to a subset of
- *   properties.
- * - Does not mutate the input; returns a fresh object.
+ * **When to use**
+ *
+ * Use when you want to apply the same transformation to a subset of properties.
+ *
+ * **Details**
+ *
+ * This does not mutate the input and returns a fresh object.
  *
  * **Example** (Wrapping only selected values in arrays)
  *
@@ -1197,7 +1353,6 @@ export const map: {
  *
  * @see {@link map} – apply a lambda to all keys
  * @see {@link mapOmit} – apply a lambda to all keys except selected ones
- *
  * @category mapping
  * @since 4.0.0
  */
@@ -1206,9 +1361,13 @@ export const mapPick: {
    * Applies a {@link Lambda} transformation only to the specified keys; all
    * other keys are copied unchanged.
    *
-   * - Use when you want to apply the same transformation to a subset of
-   *   properties.
-   * - Does not mutate the input; returns a fresh object.
+   * **When to use**
+   *
+   * Use when you want to apply the same transformation to a subset of properties.
+   *
+   * **Details**
+   *
+   * This does not mutate the input and returns a fresh object.
    *
    * **Example** (Wrapping only selected values in arrays)
    *
@@ -1230,7 +1389,6 @@ export const mapPick: {
    *
    * @see {@link map} – apply a lambda to all keys
    * @see {@link mapOmit} – apply a lambda to all keys except selected ones
-   *
    * @category mapping
    * @since 4.0.0
    */
@@ -1241,9 +1399,13 @@ export const mapPick: {
    * Applies a {@link Lambda} transformation only to the specified keys; all
    * other keys are copied unchanged.
    *
-   * - Use when you want to apply the same transformation to a subset of
-   *   properties.
-   * - Does not mutate the input; returns a fresh object.
+   * **When to use**
+   *
+   * Use when you want to apply the same transformation to a subset of properties.
+   *
+   * **Details**
+   *
+   * This does not mutate the input and returns a fresh object.
    *
    * **Example** (Wrapping only selected values in arrays)
    *
@@ -1265,7 +1427,6 @@ export const mapPick: {
    *
    * @see {@link map} – apply a lambda to all keys
    * @see {@link mapOmit} – apply a lambda to all keys except selected ones
-   *
    * @category mapping
    * @since 4.0.0
    */
@@ -1285,8 +1446,13 @@ export const mapPick: {
  * Applies a {@link Lambda} transformation to all keys except the specified
  * ones; the excluded keys are copied unchanged.
  *
- * - Use when most keys should be transformed but a few should be preserved.
- * - Does not mutate the input; returns a fresh object.
+ * **When to use**
+ *
+ * Use when most keys should be transformed but a few should be preserved.
+ *
+ * **Details**
+ *
+ * This does not mutate the input and returns a fresh object.
  *
  * **Example** (Wrapping all values except one in arrays)
  *
@@ -1308,7 +1474,6 @@ export const mapPick: {
  *
  * @see {@link map} – apply a lambda to all keys
  * @see {@link mapPick} – apply a lambda only to selected keys
- *
  * @category mapping
  * @since 4.0.0
  */
@@ -1317,8 +1482,13 @@ export const mapOmit: {
    * Applies a {@link Lambda} transformation to all keys except the specified
    * ones; the excluded keys are copied unchanged.
    *
-   * - Use when most keys should be transformed but a few should be preserved.
-   * - Does not mutate the input; returns a fresh object.
+   * **When to use**
+   *
+   * Use when most keys should be transformed but a few should be preserved.
+   *
+   * **Details**
+   *
+   * This does not mutate the input and returns a fresh object.
    *
    * **Example** (Wrapping all values except one in arrays)
    *
@@ -1340,7 +1510,6 @@ export const mapOmit: {
    *
    * @see {@link map} – apply a lambda to all keys
    * @see {@link mapPick} – apply a lambda only to selected keys
-   *
    * @category mapping
    * @since 4.0.0
    */
@@ -1351,8 +1520,13 @@ export const mapOmit: {
    * Applies a {@link Lambda} transformation to all keys except the specified
    * ones; the excluded keys are copied unchanged.
    *
-   * - Use when most keys should be transformed but a few should be preserved.
-   * - Does not mutate the input; returns a fresh object.
+   * **When to use**
+   *
+   * Use when most keys should be transformed but a few should be preserved.
+   *
+   * **Details**
+   *
+   * This does not mutate the input and returns a fresh object.
    *
    * **Example** (Wrapping all values except one in arrays)
    *
@@ -1374,7 +1548,6 @@ export const mapOmit: {
    *
    * @see {@link map} – apply a lambda to all keys
    * @see {@link mapPick} – apply a lambda only to selected keys
-   *
    * @category mapping
    * @since 4.0.0
    */
@@ -1422,11 +1595,16 @@ function buildStruct<
  * property. When two structs are combined, each property is merged using its
  * corresponding combiner.
  *
- * - Use when you need to merge two structs of the same shape (e.g., summing
- *   counters, concatenating strings).
- * - Pass `omitKeyWhen` to drop properties whose merged value matches a
- *   predicate (e.g., omit zero counters).
- * - Does not mutate the inputs; returns a fresh object.
+ * **When to use**
+ *
+ * Use when you need to merge two structs of the same shape, such as summing
+ * counters or concatenating strings.
+ *
+ * **Details**
+ *
+ * Pass `omitKeyWhen` to drop properties whose merged value matches a predicate,
+ * such as omitting zero counters. This does not mutate the inputs and returns a
+ * fresh object.
  *
  * **Example** (Combining struct properties)
  *
@@ -1443,7 +1621,6 @@ function buildStruct<
  * ```
  *
  * @see {@link makeReducer} – like `makeCombiner` but with an initial value
- *
  * @category combining
  * @since 4.0.0
  */
@@ -1472,10 +1649,14 @@ export function makeCombiner<A>(
  * `Reducer.initialValue`. When reducing a collection of structs, each property
  * is combined independently.
  *
- * - Use to fold a collection of structs into a single summary struct.
- * - Pass `omitKeyWhen` to drop properties whose reduced value matches a
- *   predicate.
- * - Does not mutate the inputs; returns a fresh object.
+ * **When to use**
+ *
+ * Use to fold a collection of structs into a single summary struct.
+ *
+ * **Details**
+ *
+ * Pass `omitKeyWhen` to drop properties whose reduced value matches a
+ * predicate. This does not mutate the inputs and returns a fresh object.
  *
  * **Example** (Reducing a collection of structs)
  *
@@ -1496,7 +1677,6 @@ export function makeCombiner<A>(
  * ```
  *
  * @see {@link makeCombiner} – like `makeReducer` but without an initial value
- *
  * @category folding
  * @since 4.0.0
  */