effect 4.0.0-beta.7 → 4.0.0-beta.8

package/src/Reducer.ts

@@ -1,17 +1,107 @@
 /**
+ * A module for reducing collections of values into a single result.
+ *
+ * A `Reducer<A>` extends {@link Combiner.Combiner} by adding an
+ * `initialValue` (identity element) and a `combineAll` method that folds an
+ * entire collection. Think `Array.prototype.reduce`, but packaged as a
+ * reusable, composable value.
+ *
+ * ## Mental model
+ *
+ * - **Reducer** – a {@link Combiner.Combiner} plus an `initialValue` and a
+ *   `combineAll` method.
+ * - **initialValue** – the neutral/identity element. Combining any value with
+ *   `initialValue` should return the original value unchanged (e.g. `0` for
+ *   addition, `""` for string concatenation).
+ * - **combineAll** – folds an `Iterable<A>` starting from `initialValue`.
+ *   When omitted from {@link make}, a default left-to-right fold is used.
+ * - **Purity** – all reducers produced by this module are pure; they never
+ *   mutate their arguments.
+ * - **Composability** – reducers can be lifted into `Option`, `Struct`,
+ *   `Tuple`, `Record`, and other container types via helpers in those modules.
+ * - **Subtype of Combiner** – every `Reducer` is also a valid
+ *   `Combiner`, so you can pass a `Reducer` anywhere a `Combiner` is
+ *   expected.
+ *
+ * ## Common tasks
+ *
+ * - Create a reducer from a combine function and initial value → {@link make}
+ * - Swap argument order → {@link flip}
+ * - Combine two values without an initial value → use {@link Combiner.Combiner}
+ *   instead
+ *
+ * ## Gotchas
+ *
+ * - `combineAll` on an empty iterable returns `initialValue`, not an error.
+ * - The default `combineAll` folds left-to-right. If your `combine` is not
+ *   associative, order matters. Pass a custom `combineAll` to {@link make} if
+ *   you need different traversal or short-circuiting.
+ * - A `Reducer` is also a valid `Combiner` — but a `Combiner` is *not* a
+ *   `Reducer` (it lacks `initialValue`).
+ *
+ * ## Quickstart
+ *
+ * **Example** (summing a list of numbers)
+ *
+ * ```ts
+ * import { Reducer } from "effect"
+ *
+ * const Sum = Reducer.make<number>((a, b) => a + b, 0)
+ *
+ * console.log(Sum.combine(3, 4))
+ * // Output: 7
+ *
+ * console.log(Sum.combineAll([1, 2, 3, 4]))
+ * // Output: 10
+ *
+ * console.log(Sum.combineAll([]))
+ * // Output: 0
+ * ```
+ *
+ * ## See also
+ *
+ * - {@link make} – the primary constructor
+ * - {@link Reducer} – the core interface
+ * - {@link Combiner.Combiner} – the parent interface (no `initialValue`)
+ *
  * @since 4.0.0
  */
 
 import type * as Combiner from "./Combiner.ts"
 
 /**
- * A `Reducer` is a `Combiner` with an `initialValue` and a way to
- * combine a whole collection. Think `Array.prototype.reduce`, but reusable.
+ * Represents a strategy for reducing a collection of values of type `A` into
+ * a single result.
+ *
+ * Extends {@link Combiner.Combiner} with:
+ * - `initialValue` – the identity/neutral element for `combine`.
+ * - `combineAll` – folds an entire `Iterable<A>` from `initialValue`.
+ *
+ * When to use:
+ * - You need to fold/reduce a collection into a single value.
+ * - You want a reusable reducing strategy that can be passed to library
+ *   functions like `Struct.makeReducer`, `Option.makeReducer`, or
+ *   `Record.makeReducerUnion`.
+ * - You need both the combining logic *and* a known starting value.
+ *
+ * Many modules ship pre-built reducers:
+ * - `Number.ReducerSum`, `Number.ReducerMultiply`
+ * - `String.ReducerConcat`
+ * - `Boolean.ReducerAnd`, `Boolean.ReducerOr`
  *
- * Common initial values:
- * - numbers with addition: `0`
- * - strings with concatenation: `""`
- * - arrays with concatenation: `[]`
+ * **Example** (string concatenation reducer)
+ *
+ * ```ts
+ * import { Reducer } from "effect"
+ *
+ * const Concat = Reducer.make<string>((a, b) => a + b, "")
+ *
+ * console.log(Concat.combineAll(["hello", " ", "world"]))
+ * // Output: "hello world"
+ * ```
+ *
+ * @see {@link make} – create a `Reducer` from a function and initial value
+ * @see {@link Combiner.Combiner} – parent interface without `initialValue`
  *
  * @category model
  * @since 4.0.0
@@ -27,7 +117,44 @@ export interface Reducer<A> extends Combiner.Combiner<A> {
 /**
  * Creates a `Reducer` from a `combine` function and an `initialValue`.
  *
- * If `combineAll` is omitted, a default implementation reduces left-to-right.
+ * When to use:
+ * - You have a custom reducing operation not covered by a pre-built reducer.
+ * - You want to provide an optimized `combineAll` (e.g. short-circuiting on
+ *   a known absorbing element like `0` for multiplication).
+ *
+ * Behavior:
+ * - If `combineAll` is omitted, a default left-to-right fold starting from
+ *   `initialValue` is used.
+ * - If `combineAll` is provided, it completely replaces the default fold.
+ * - Pure – the returned reducer does not mutate its arguments.
+ *
+ * **Example** (multiplication with short-circuit)
+ *
+ * ```ts
+ * import { Reducer } from "effect"
+ *
+ * const Product = Reducer.make<number>(
+ *   (a, b) => a * b,
+ *   1,
+ *   (collection) => {
+ *     let acc = 1
+ *     for (const n of collection) {
+ *       if (n === 0) return 0
+ *       acc *= n
+ *     }
+ *     return acc
+ *   }
+ * )
+ *
+ * console.log(Product.combineAll([2, 3, 4]))
+ * // Output: 24
+ *
+ * console.log(Product.combineAll([2, 0, 4]))
+ * // Output: 0
+ * ```
+ *
+ * @see {@link Reducer} – the interface this creates
+ * @see {@link flip} – reverse the argument order
  *
  * @since 4.0.0
  */
@@ -51,6 +178,38 @@ export function make<A>(
 }
 
 /**
+ * Reverses the argument order of a reducer's `combine` method.
+ *
+ * When to use:
+ * - You need the "right" value to act as the accumulator side.
+ * - You want to reverse the natural direction of a non-commutative reducer
+ *   (e.g. string concatenation becomes prepend).
+ *
+ * Behavior:
+ * - Returns a new `Reducer` where `combine(self, that)` calls the original
+ *   reducer as `combine(that, self)`.
+ * - The `initialValue` is preserved from the original reducer.
+ * - The `combineAll` is re-derived from the flipped `combine` (using the
+ *   default left-to-right fold), not carried over from the original.
+ * - Does not mutate the input reducer.
+ *
+ * **Example** (reversing string concatenation)
+ *
+ * ```ts
+ * import { Reducer, String } from "effect"
+ *
+ * const Prepend = Reducer.flip(String.ReducerConcat)
+ *
+ * console.log(Prepend.combine("a", "b"))
+ * // Output: "ba"
+ *
+ * console.log(Prepend.combineAll(["a", "b", "c"]))
+ * // Output: "cba"
+ * ```
+ *
+ * @see {@link make}
+ * @see {@link Combiner.flip} – the same operation on a plain `Combiner`
+ *
  * @since 4.0.0
  */
 export function flip<A>(reducer: Reducer<A>): Reducer<A> {

package/src/index.ts

@@ -444,6 +444,65 @@ export * as Chunk from "./Chunk.ts"
 export * as Clock from "./Clock.ts"
 
 /**
+ * A module for combining two values of the same type into one.
+ *
+ * A `Combiner<A>` wraps a single binary function `(self: A, that: A) => A`.
+ * It describes *how* two values merge but carries no initial/empty value
+ * (for that, see {@link Reducer} which extends `Combiner` with an
+ * `initialValue`).
+ *
+ * ## Mental model
+ *
+ * - **Combiner** – an object with a `combine(self, that)` method that returns
+ *   a value of the same type.
+ * - **Argument order** – `self` is the "left" / accumulator side, `that` is
+ *   the "right" / incoming side.
+ * - **No identity element** – unlike a monoid, a `Combiner` does not require
+ *   a neutral element. Use {@link Reducer} when you need one.
+ * - **Purity** – all combiners produced by this module are pure; they never
+ *   mutate their arguments.
+ * - **Composability** – combiners can be lifted into `Option`, `Struct`,
+ *   `Tuple`, and other container types via helpers in those modules.
+ *
+ * ## Common tasks
+ *
+ * - Create a combiner from any binary function → {@link make}
+ * - Swap argument order → {@link flip}
+ * - Pick the smaller / larger of two values → {@link min} / {@link max}
+ * - Always keep the first or last value → {@link first} / {@link last}
+ * - Ignore both values and return a fixed result → {@link constant}
+ * - Insert a separator between combined values → {@link intercalate}
+ *
+ * ## Gotchas
+ *
+ * - `min` and `max` require an `Order<A>`, not a raw comparator. Import from
+ *   e.g. `Number.Order` or `String.Order`.
+ * - `intercalate` is curried: call it with the separator first, then pass the
+ *   base combiner.
+ * - A `Reducer` (which adds `initialValue`) is also a valid `Combiner` — you
+ *   can pass a `Reducer` anywhere a `Combiner` is expected.
+ *
+ * ## Quickstart
+ *
+ * **Example** (combining strings with a separator)
+ *
+ * ```ts
+ * import { Combiner, String } from "effect"
+ *
+ * const csv = Combiner.intercalate(",")(String.ReducerConcat)
+ *
+ * console.log(csv.combine("a", "b"))
+ * // Output: "a,b"
+ *
+ * console.log(csv.combine(csv.combine("a", "b"), "c"))
+ * // Output: "a,b,c"
+ * ```
+ *
+ * ## See also
+ *
+ * - {@link make} – the primary constructor
+ * - {@link Combiner} – the core interface
+ *
  * @since 4.0.0
  */
 export * as Combiner from "./Combiner.ts"
@@ -2591,6 +2650,71 @@ export * as Redactable from "./Redactable.ts"
 export * as Redacted from "./Redacted.ts"
 
 /**
+ * A module for reducing collections of values into a single result.
+ *
+ * A `Reducer<A>` extends {@link Combiner.Combiner} by adding an
+ * `initialValue` (identity element) and a `combineAll` method that folds an
+ * entire collection. Think `Array.prototype.reduce`, but packaged as a
+ * reusable, composable value.
+ *
+ * ## Mental model
+ *
+ * - **Reducer** – a {@link Combiner.Combiner} plus an `initialValue` and a
+ *   `combineAll` method.
+ * - **initialValue** – the neutral/identity element. Combining any value with
+ *   `initialValue` should return the original value unchanged (e.g. `0` for
+ *   addition, `""` for string concatenation).
+ * - **combineAll** – folds an `Iterable<A>` starting from `initialValue`.
+ *   When omitted from {@link make}, a default left-to-right fold is used.
+ * - **Purity** – all reducers produced by this module are pure; they never
+ *   mutate their arguments.
+ * - **Composability** – reducers can be lifted into `Option`, `Struct`,
+ *   `Tuple`, `Record`, and other container types via helpers in those modules.
+ * - **Subtype of Combiner** – every `Reducer` is also a valid
+ *   `Combiner`, so you can pass a `Reducer` anywhere a `Combiner` is
+ *   expected.
+ *
+ * ## Common tasks
+ *
+ * - Create a reducer from a combine function and initial value → {@link make}
+ * - Swap argument order → {@link flip}
+ * - Combine two values without an initial value → use {@link Combiner.Combiner}
+ *   instead
+ *
+ * ## Gotchas
+ *
+ * - `combineAll` on an empty iterable returns `initialValue`, not an error.
+ * - The default `combineAll` folds left-to-right. If your `combine` is not
+ *   associative, order matters. Pass a custom `combineAll` to {@link make} if
+ *   you need different traversal or short-circuiting.
+ * - A `Reducer` is also a valid `Combiner` — but a `Combiner` is *not* a
+ *   `Reducer` (it lacks `initialValue`).
+ *
+ * ## Quickstart
+ *
+ * **Example** (summing a list of numbers)
+ *
+ * ```ts
+ * import { Reducer } from "effect"
+ *
+ * const Sum = Reducer.make<number>((a, b) => a + b, 0)
+ *
+ * console.log(Sum.combine(3, 4))
+ * // Output: 7
+ *
+ * console.log(Sum.combineAll([1, 2, 3, 4]))
+ * // Output: 10
+ *
+ * console.log(Sum.combineAll([]))
+ * // Output: 0
+ * ```
+ *
+ * ## See also
+ *
+ * - {@link make} – the primary constructor
+ * - {@link Reducer} – the core interface
+ * - {@link Combiner.Combiner} – the parent interface (no `initialValue`)
+ *
  * @since 4.0.0
  */
 export * as Reducer from "./Reducer.ts"

package/src/unstable/process/ChildProcess.ts

@@ -414,7 +414,7 @@ export interface CommandOptions extends KillOptions {
    * the value of `globalThis.process.env`, prioritizing the values in `env`
    * when conflicts exist.
    */
-  readonly env?: Record<string, string> | undefined
+  readonly env?: Record<string, string | undefined> | undefined
   /**
    * If set to `true`, the child process uses both the values in `env` as well
    * as the values in `globalThis.process.env`, prioritizing the values in `env`

package/src/unstable/sql/SqlSchema.ts

@@ -26,7 +26,7 @@ export const findAll = <Req extends Schema.Top, Res extends Schema.Top, E, R>(
     request: Req["Encoded"]
   ): Effect.Effect<
     Array<Res["Type"]>,
-    E | Schema.SchemaError | Cause.NoSuchElementError,
+    E | Schema.SchemaError,
     Req["EncodingServices"] | Res["DecodingServices"] | R
   > => Effect.flatMap(Effect.flatMap(encodeRequest(request), options.execute), decode)
 }