effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/Struct.ts

@@ -67,7 +67,7 @@
  * ## See also
  *
  * - {@link Equivalence} – building equivalence relations for structs
- * - {@link Order} – ordering structs by their fields
+ * - `Order` – ordering structs by their fields
  * - {@link Combiner} – combining two values of the same type
  * - {@link Reducer} – combining with an initial value
  *
@@ -175,11 +175,11 @@ export type Assign<T, U> = Simplify<keyof T & keyof U extends never ? T & U : Om
  *
  * **When to use**
  *
- * Use in a pipeline when you need to extract a single property.
+ * Use to extract a single property in a pipeline.
  *
  * **Details**
  *
- * This does not mutate the input, and the return type is narrowed to `S[K]`.
+ * The return type is narrowed to `S[K]`.
  *
  * **Example** (Extracting a property in a pipeline)
  *
@@ -201,11 +201,11 @@ export const get: {
    *
    * **When to use**
    *
-   * Use in a pipeline when you need to extract a single property.
+   * Use to extract a single property in a pipeline.
    *
    * **Details**
    *
-   * This does not mutate the input, and the return type is narrowed to `S[K]`.
+   * The return type is narrowed to `S[K]`.
    *
    * **Example** (Extracting a property in a pipeline)
    *
@@ -227,11 +227,11 @@ export const get: {
    *
    * **When to use**
    *
-   * Use in a pipeline when you need to extract a single property.
+   * Use to extract a single property in a pipeline.
    *
    * **Details**
    *
-   * This does not mutate the input, and the return type is narrowed to `S[K]`.
+   * The return type is narrowed to `S[K]`.
    *
    * **Example** (Extracting a property in a pipeline)
    *
@@ -255,13 +255,9 @@ export const get: {
  *
  * **When to use**
  *
- * Use instead of `Object.keys` when you want the return type narrowed to the
+ * Use when you 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.
@@ -292,10 +288,6 @@ export const keys = <S extends object>(self: S): Array<(keyof S) & string> =>
  *
  * 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.
@@ -323,10 +315,6 @@ export const pick: {
    *
    * 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.
@@ -354,10 +342,6 @@ export const pick: {
    *
    * 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.
@@ -392,10 +376,6 @@ export const pick: {
  *
  * 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.
@@ -422,10 +402,6 @@ export const omit: {
    *
    * 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.
@@ -452,10 +428,6 @@ export const omit: {
    *
    * 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.
@@ -492,8 +464,7 @@ export const omit: {
  *
  * **Details**
  *
- * This does not mutate either input and returns a fresh object. The result type
- * is `Simplify<Assign<S, O>>`.
+ * The result type is `Simplify<Assign<S, O>>`.
  *
  * **Example** (Merging structs with overlapping keys)
  *
@@ -522,8 +493,7 @@ export const assign: {
    *
    * **Details**
    *
-   * This does not mutate either input and returns a fresh object. The result type
-   * is `Simplify<Assign<S, O>>`.
+   * The result type is `Simplify<Assign<S, O>>`.
    *
    * **Example** (Merging structs with overlapping keys)
    *
@@ -552,8 +522,7 @@ export const assign: {
    *
    * **Details**
    *
-   * This does not mutate either input and returns a fresh object. The result type
-   * is `Simplify<Assign<S, O>>`.
+   * The result type is `Simplify<Assign<S, O>>`.
    *
    * **Example** (Merging structs with overlapping keys)
    *
@@ -586,7 +555,7 @@ type Evolved<S, E> = Simplify<
 >
 
 /**
- * Selectively transforms values of a struct using per-key functions. Keys
+ * Transforms values of a struct selectively using per-key functions. Keys
  * without a corresponding function are copied unchanged.
  *
  * **When to use**
@@ -595,9 +564,8 @@ type Evolved<S, E> = Simplify<
  *
  * **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.
+ * 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)
  *
@@ -622,7 +590,7 @@ type Evolved<S, E> = Simplify<
  */
 export const evolve: {
   /**
-   * Selectively transforms values of a struct using per-key functions. Keys
+   * Transforms values of a struct selectively using per-key functions. Keys
    * without a corresponding function are copied unchanged.
    *
    * **When to use**
@@ -631,9 +599,8 @@ export const evolve: {
    *
    * **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.
+   * 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)
    *
@@ -658,7 +625,7 @@ export const evolve: {
    */
   <S extends object, E extends Evolver<S>>(e: E): (self: S) => Evolved<S, E>
   /**
-   * Selectively transforms values of a struct using per-key functions. Keys
+   * Transforms values of a struct selectively using per-key functions. Keys
    * without a corresponding function are copied unchanged.
    *
    * **When to use**
@@ -667,9 +634,8 @@ export const evolve: {
    *
    * **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.
+   * 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)
    *
@@ -707,7 +673,7 @@ type KeyEvolved<S, E> = Simplify<
 >
 
 /**
- * Selectively transforms keys of a struct using per-key functions. Keys without
+ * Transforms keys of a struct selectively using per-key functions. Keys without
  * a corresponding function are copied unchanged.
  *
  * **When to use**
@@ -717,7 +683,7 @@ type KeyEvolved<S, E> = Simplify<
  * **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.
+ * `PropertyKey`.
  *
  * **Example** (Renaming keys with functions)
  *
@@ -741,7 +707,7 @@ type KeyEvolved<S, E> = Simplify<
  */
 export const evolveKeys: {
   /**
-   * Selectively transforms keys of a struct using per-key functions. Keys without
+   * Transforms keys of a struct selectively using per-key functions. Keys without
    * a corresponding function are copied unchanged.
    *
    * **When to use**
@@ -751,7 +717,7 @@ export const evolveKeys: {
    * **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.
+   * `PropertyKey`.
    *
    * **Example** (Renaming keys with functions)
    *
@@ -775,7 +741,7 @@ export const evolveKeys: {
    */
   <S extends object, E extends KeyEvolver<S>>(e: E): (self: S) => KeyEvolved<S, E>
   /**
-   * Selectively transforms keys of a struct using per-key functions. Keys without
+   * Transforms keys of a struct selectively using per-key functions. Keys without
    * a corresponding function are copied unchanged.
    *
    * **When to use**
@@ -785,7 +751,7 @@ export const evolveKeys: {
    * **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.
+   * `PropertyKey`.
    *
    * **Example** (Renaming keys with functions)
    *
@@ -828,7 +794,7 @@ type EntryEvolved<S, E> = {
 }
 
 /**
- * Selectively transforms both keys and values of a struct. Each per-key
+ * Transforms both keys and values of a struct selectively. Each per-key
  * function receives `(key, value)` and must return a `[newKey, newValue]`
  * tuple. Keys without a corresponding function are copied unchanged.
  *
@@ -838,8 +804,7 @@ type EntryEvolved<S, E> = {
  *
  * **Details**
  *
- * This does not mutate the input and returns a fresh object. The return type is
- * fully tracked at the type level.
+ * The return type is fully tracked at the type level.
  *
  * **Example** (Transforming keys and values together)
  *
@@ -863,7 +828,7 @@ type EntryEvolved<S, E> = {
  */
 export const evolveEntries: {
   /**
-   * Selectively transforms both keys and values of a struct. Each per-key
+   * Transforms both keys and values of a struct selectively. Each per-key
    * function receives `(key, value)` and must return a `[newKey, newValue]`
    * tuple. Keys without a corresponding function are copied unchanged.
    *
@@ -873,8 +838,7 @@ export const evolveEntries: {
    *
    * **Details**
    *
-   * This does not mutate the input and returns a fresh object. The return type is
-   * fully tracked at the type level.
+   * The return type is fully tracked at the type level.
    *
    * **Example** (Transforming keys and values together)
    *
@@ -898,7 +862,7 @@ export const evolveEntries: {
    */
   <S extends object, E extends EntryEvolver<S>>(e: E): (self: S) => EntryEvolved<S, E>
   /**
-   * Selectively transforms both keys and values of a struct. Each per-key
+   * Transforms both keys and values of a struct selectively. Each per-key
    * function receives `(key, value)` and must return a `[newKey, newValue]`
    * tuple. Keys without a corresponding function are copied unchanged.
    *
@@ -908,8 +872,7 @@ export const evolveEntries: {
    *
    * **Details**
    *
-   * This does not mutate the input and returns a fresh object. The return type is
-   * fully tracked at the type level.
+   * The return type is fully tracked at the type level.
    *
    * **Example** (Transforming keys and values together)
    *
@@ -945,12 +908,11 @@ export const evolveEntries: {
  *
  * **When to use**
  *
- * Use for simple, declarative key renaming without custom logic.
+ * Use when you need 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.
+ * For computed key names, use {@link evolveKeys} instead.
  *
  * **Example** (Renaming keys)
  *
@@ -976,12 +938,11 @@ export const renameKeys: {
    *
    * **When to use**
    *
-   * Use for simple, declarative key renaming without custom logic.
+   * Use when you need 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.
+   * For computed key names, use {@link evolveKeys} instead.
    *
    * **Example** (Renaming keys)
    *
@@ -1007,12 +968,11 @@ export const renameKeys: {
    *
    * **When to use**
    *
-   * Use for simple, declarative key renaming without custom logic.
+   * Use when you need 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.
+   * For computed key names, use {@link evolveKeys} instead.
    *
    * **Example** (Renaming keys)
    *
@@ -1114,7 +1074,7 @@ export const makeOrder = order.Struct
  *
  * **When to use**
  *
- * Use this interface when defining a typed function for {@link map},
+ * Use when you use this interface when defining a typed function for {@link map},
  * {@link mapPick}, or {@link mapOmit}.
  *
  * **Details**
@@ -1150,7 +1110,7 @@ export interface Lambda {
  *
  * **When to use**
  *
- * Use this when you need to compute what type a Lambda would produce for a
+ * Use when you need to compute what type a Lambda would produce for a
  * given input.
  *
  * **Details**
@@ -1181,6 +1141,11 @@ 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}.
  *
+ * **When to use**
+ *
+ * Use to create a typed lambda for struct mapping APIs that need type-level
+ * input and output tracking.
+ *
  * **Details**
  *
  * The type parameter `L` encodes both the input and output types at the type
@@ -1222,7 +1187,7 @@ export const lambda = <L extends (a: any) => any>(
  * **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.
+ * output types.
  *
  * **Example** (Wrapping every value in an array)
  *
@@ -1256,7 +1221,7 @@ export const map: {
    * **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.
+   * output types.
    *
    * **Example** (Wrapping every value in an array)
    *
@@ -1290,7 +1255,7 @@ export const map: {
    * **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.
+   * output types.
    *
    * **Example** (Wrapping every value in an array)
    *
@@ -1329,10 +1294,6 @@ export const map: {
  *
  * 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)
  *
  * ```ts
@@ -1365,10 +1326,6 @@ export const mapPick: {
    *
    * 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)
    *
    * ```ts
@@ -1403,10 +1360,6 @@ export const mapPick: {
    *
    * 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)
    *
    * ```ts
@@ -1450,10 +1403,6 @@ export const mapPick: {
  *
  * 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)
  *
  * ```ts
@@ -1486,10 +1435,6 @@ export const mapOmit: {
    *
    * 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)
    *
    * ```ts
@@ -1524,10 +1469,6 @@ export const mapOmit: {
    *
    * 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)
    *
    * ```ts
@@ -1603,8 +1544,7 @@ function buildStruct<
  * **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.
+ * such as omitting zero counters.
  *
  * **Example** (Combining struct properties)
  *
@@ -1656,7 +1596,7 @@ export function makeCombiner<A>(
  * **Details**
  *
  * Pass `omitKeyWhen` to drop properties whose reduced value matches a
- * predicate. This does not mutate the inputs and returns a fresh object.
+ * predicate.
  *
  * **Example** (Reducing a collection of structs)
  *
@@ -1699,6 +1639,10 @@ export function makeReducer<A>(
 /**
  * Creates a record with the given keys and value.
  *
+ * **When to use**
+ *
+ * Use to build an object where each provided key receives the same value.
+ *
  * **Example** (Creating a record)
  *
  * ```ts