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

package/dist/Struct.d.ts

@@ -80,10 +80,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)
  *
@@ -99,7 +103,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
  */
@@ -109,9 +112,14 @@ export type Simplify<T> = {
 /**
  * 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)
  *
@@ -124,7 +132,6 @@ export type Simplify<T> = {
  * ```
  *
  * @see {@link Simplify} – flattens intersections without removing `readonly`
- *
  * @category Type-Level Programming
  * @since 4.0.0
  */
@@ -135,9 +142,14 @@ export type Mutable<T> = {
  * 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)
  *
@@ -152,7 +164,6 @@ export type Mutable<T> = {
  *
  * @see {@link assign} – the runtime equivalent
  * @see {@link Simplify} – flatten the resulting intersection
- *
  * @category Type-Level Programming
  * @since 4.0.0
  */
@@ -160,9 +171,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)
  *
@@ -175,7 +190,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
  */
@@ -183,9 +197,13 @@ export declare 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)
      *
@@ -198,7 +216,6 @@ export declare 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
      */
@@ -206,9 +223,13 @@ export declare 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)
      *
@@ -221,7 +242,6 @@ export declare 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
      */
@@ -230,10 +250,18 @@ export declare 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)
  *
@@ -248,7 +276,6 @@ export declare 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
  */
@@ -256,9 +283,17 @@ export declare const keys: <S extends object>(self: S) => Array<(keyof S) & stri
 /**
  * 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)
  *
@@ -272,7 +307,6 @@ export declare const keys: <S extends object>(self: S) => Array<(keyof S) & stri
  *
  * @see {@link omit} – the inverse (exclude keys instead)
  * @see {@link get} – extract a single value
- *
  * @category filtering
  * @since 2.0.0
  */
@@ -280,9 +314,17 @@ export declare 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)
      *
@@ -296,7 +338,6 @@ export declare const pick: {
      *
      * @see {@link omit} – the inverse (exclude keys instead)
      * @see {@link get} – extract a single value
-     *
      * @category filtering
      * @since 2.0.0
      */
@@ -304,9 +345,17 @@ export declare 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)
      *
@@ -320,7 +369,6 @@ export declare const pick: {
      *
      * @see {@link omit} – the inverse (exclude keys instead)
      * @see {@link get} – extract a single value
-     *
      * @category filtering
      * @since 2.0.0
      */
@@ -329,9 +377,17 @@ export declare 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)
  *
@@ -344,7 +400,6 @@ export declare const pick: {
  * ```
  *
  * @see {@link pick} – the inverse (keep only specified keys)
- *
  * @category filtering
  * @since 2.0.0
  */
@@ -352,9 +407,17 @@ export declare 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)
      *
@@ -367,7 +430,6 @@ export declare const omit: {
      * ```
      *
      * @see {@link pick} – the inverse (keep only specified keys)
-     *
      * @category filtering
      * @since 2.0.0
      */
@@ -375,9 +437,17 @@ export declare 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)
      *
@@ -390,7 +460,6 @@ export declare const omit: {
      * ```
      *
      * @see {@link pick} – the inverse (keep only specified keys)
-     *
      * @category filtering
      * @since 2.0.0
      */
@@ -400,9 +469,14 @@ export declare 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)
  *
@@ -417,7 +491,6 @@ export declare 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
  */
@@ -426,9 +499,14 @@ export declare 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)
      *
@@ -443,7 +521,6 @@ export declare 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
      */
@@ -452,9 +529,14 @@ export declare 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)
      *
@@ -469,7 +551,6 @@ export declare 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
      */
@@ -485,10 +566,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)
  *
@@ -508,7 +594,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
  */
@@ -517,10 +602,15 @@ export declare 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)
      *
@@ -540,7 +630,6 @@ export declare 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
      */
@@ -549,10 +638,15 @@ export declare 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)
      *
@@ -572,7 +666,6 @@ export declare 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
      */
@@ -588,10 +681,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)
  *
@@ -610,7 +707,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
  */
@@ -619,10 +715,14 @@ export declare 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)
      *
@@ -641,7 +741,6 @@ export declare 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
      */
@@ -650,10 +749,14 @@ export declare 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)
      *
@@ -672,7 +775,6 @@ export declare 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
      */
@@ -689,9 +791,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)
  *
@@ -710,7 +817,6 @@ type EntryEvolved<S, E> = {
  *
  * @see {@link evolve} – transform values only
  * @see {@link evolveKeys} – transform keys only
- *
  * @category utils
  * @since 4.0.0
  */
@@ -720,9 +826,14 @@ export declare 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)
      *
@@ -741,7 +852,6 @@ export declare const evolveEntries: {
      *
      * @see {@link evolve} – transform values only
      * @see {@link evolveKeys} – transform keys only
-     *
      * @category utils
      * @since 4.0.0
      */
@@ -751,9 +861,14 @@ export declare 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)
      *
@@ -772,7 +887,6 @@ export declare const evolveEntries: {
      *
      * @see {@link evolve} – transform values only
      * @see {@link evolveKeys} – transform keys only
-     *
      * @category utils
      * @since 4.0.0
      */
@@ -782,9 +896,14 @@ export declare 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)
  *
@@ -800,7 +919,6 @@ export declare const evolveEntries: {
  *
  * @see {@link evolveKeys} – rename keys using functions
  * @see {@link evolveEntries} – rename keys and transform values
- *
  * @category Key utilities
  * @since 4.0.0
  */
@@ -809,9 +927,14 @@ export declare 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)
      *
@@ -827,7 +950,6 @@ export declare const renameKeys: {
      *
      * @see {@link evolveKeys} – rename keys using functions
      * @see {@link evolveEntries} – rename keys and transform values
-     *
      * @category Key utilities
      * @since 4.0.0
      */
@@ -840,9 +962,14 @@ export declare 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)
      *
@@ -858,7 +985,6 @@ export declare const renameKeys: {
      *
      * @see {@link evolveKeys} – rename keys using functions
      * @see {@link evolveEntries} – rename keys and transform values
-     *
      * @category Key utilities
      * @since 4.0.0
      */
@@ -873,11 +999,15 @@ export declare 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)
  *
@@ -896,7 +1026,6 @@ export declare const renameKeys: {
  * ```
  *
  * @see {@link makeOrder} – create an `Order` for structs
- *
  * @category Equivalence
  * @since 4.0.0
  */
@@ -906,11 +1035,15 @@ export declare const makeEquivalence: typeof 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)
  *
@@ -927,7 +1060,6 @@ export declare const makeEquivalence: typeof Equivalence.Struct;
  * ```
  *
  * @see {@link makeEquivalence} – create an `Equivalence` for structs
- *
  * @category Ordering
  * @since 4.0.0
  */
@@ -936,9 +1068,16 @@ export declare const makeOrder: typeof 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)
  *
@@ -953,7 +1092,6 @@ export declare const makeOrder: typeof 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
  */
@@ -965,10 +1103,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)
  *
@@ -984,7 +1127,6 @@ export interface Lambda {
  * ```
  *
  * @see {@link Lambda} – the base interface
- *
  * @category Lambda
  * @since 4.0.0
  */
@@ -995,10 +1137,12 @@ export type Apply<L extends Lambda, V> = (L & {
  * 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)
  *
@@ -1017,7 +1161,6 @@ export type Apply<L extends Lambda, V> = (L & {
  *
  * @see {@link Lambda} – the type-level interface
  * @see {@link map} – apply a lambda to all struct values
- *
  * @category Lambda
  * @since 4.0.0
  */
@@ -1025,10 +1168,14 @@ export declare const lambda: <L extends (a: any) => any>(f: (a: Parameters<L>[0]
 /**
  * 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)
  *
@@ -1048,7 +1195,6 @@ export declare const lambda: <L extends (a: any) => any>(f: (a: Parameters<L>[0]
  * @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
  */
@@ -1056,10 +1202,14 @@ export declare 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)
      *
@@ -1079,7 +1229,6 @@ export declare 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
      */
@@ -1089,10 +1238,14 @@ export declare 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)
      *
@@ -1112,7 +1265,6 @@ export declare 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
      */
@@ -1124,9 +1276,13 @@ export declare 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)
  *
@@ -1148,7 +1304,6 @@ export declare 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
  */
@@ -1157,9 +1312,13 @@ export declare 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)
      *
@@ -1181,7 +1340,6 @@ export declare 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
      */
@@ -1192,9 +1350,13 @@ export declare 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)
      *
@@ -1216,7 +1378,6 @@ export declare 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
      */
@@ -1228,8 +1389,13 @@ export declare 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)
  *
@@ -1251,7 +1417,6 @@ export declare 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
  */
@@ -1260,8 +1425,13 @@ export declare 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)
      *
@@ -1283,7 +1453,6 @@ export declare 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
      */
@@ -1294,8 +1463,13 @@ export declare 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)
      *
@@ -1317,7 +1491,6 @@ export declare 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
      */
@@ -1330,11 +1503,16 @@ export declare const mapOmit: {
  * 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)
  *
@@ -1351,7 +1529,6 @@ export declare const mapOmit: {
  * ```
  *
  * @see {@link makeReducer} – like `makeCombiner` but with an initial value
- *
  * @category combining
  * @since 4.0.0
  */
@@ -1366,10 +1543,14 @@ export declare function makeCombiner<A>(combiners: {
  * `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)
  *
@@ -1390,7 +1571,6 @@ export declare function makeCombiner<A>(combiners: {
  * ```
  *
  * @see {@link makeCombiner} – like `makeReducer` but without an initial value
- *
  * @category folding
  * @since 4.0.0
  */