effect 4.0.0-beta.6 → 4.0.0-beta.8

package/src/Combiner.ts

@@ -1,16 +1,92 @@
 /**
+ * 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
  */
 import type * as Order from "./Order.ts"
 
 /**
- * A `Combiner` represents any type of value that can be combined
- * with another value of the same type to produce a new value.
+ * Represents a strategy for combining two values of the same type `A`.
+ *
+ * A `Combiner` contains a single `combine` method that takes two values and
+ * returns a merged result. It does not include an identity/empty value; use
+ * `Reducer` when you need one.
+ *
+ * When to use:
+ * - You need to describe how two values of the same type merge.
+ * - You want to pass a reusable combining strategy to library functions like
+ *   `Struct.makeCombiner` or `Option.makeCombinerFailFast`.
+ * - You are building a `Reducer` and need to define the combining step first.
+ *
+ * **Example** (number addition combiner)
+ *
+ * ```ts
+ * import { Combiner } from "effect"
+ *
+ * const Sum = Combiner.make<number>((self, that) => self + that)
  *
- * Examples:
- * - numbers with addition
- * - strings with concatenation
- * - arrays with merging
+ * console.log(Sum.combine(3, 4))
+ * // Output: 7
+ * ```
+ *
+ * @see {@link make} – create a `Combiner` from a function
  *
  * @category model
  * @since 4.0.0
@@ -23,7 +99,29 @@ export interface Combiner<A> {
 }
 
 /**
- * Creates a `Combiner` from a `combine` function.
+ * Creates a `Combiner` from a binary function.
+ *
+ * When to use:
+ * - You have a custom combining operation that is not covered by the built-in
+ *   constructors (`min`, `max`, `first`, `last`, `constant`).
+ *
+ * Behavior:
+ * - Returns a new `Combiner` whose `combine` method delegates to the provided
+ *   function.
+ * - Pure – the returned combiner does not mutate its arguments.
+ *
+ * **Example** (multiplying numbers)
+ *
+ * ```ts
+ * import { Combiner } from "effect"
+ *
+ * const Product = Combiner.make<number>((self, that) => self * that)
+ *
+ * console.log(Product.combine(3, 5))
+ * // Output: 15
+ * ```
+ *
+ * @see {@link Combiner} – the interface this creates
  *
  * @since 4.0.0
  */
@@ -32,6 +130,31 @@ export function make<A>(combine: (self: A, that: A) => A): Combiner<A> {
 }
 
 /**
+ * Reverses the argument order of a combiner'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 combiner
+ *   (e.g. string concatenation).
+ *
+ * Behavior:
+ * - Returns a new `Combiner` where `combine(self, that)` calls the original
+ *   combiner as `combine(that, self)`.
+ * - Does not mutate the input combiner.
+ *
+ * **Example** (reversing string concatenation)
+ *
+ * ```ts
+ * import { Combiner, String } from "effect"
+ *
+ * const Prepend = Combiner.flip(String.ReducerConcat)
+ *
+ * console.log(Prepend.combine("a", "b"))
+ * // Output: "ba"
+ * ```
+ *
+ * @see {@link make}
+ *
  * @since 4.0.0
  */
 export function flip<A>(combiner: Combiner<A>): Combiner<A> {
@@ -39,7 +162,33 @@ export function flip<A>(combiner: Combiner<A>): Combiner<A> {
 }
 
 /**
- * Creates a `Combiner` that returns the smaller of two values.
+ * Creates a `Combiner` that returns the smaller of two values according to
+ * the provided `Order`.
+ *
+ * When to use:
+ * - You want to accumulate the minimum value across a collection.
+ * - You are building a `Reducer` that tracks the running minimum.
+ *
+ * Behavior:
+ * - Compares using the given `Order`. When values are equal, returns `that`
+ *   (the second argument).
+ * - Pure – does not mutate either argument.
+ *
+ * **Example** (minimum of two numbers)
+ *
+ * ```ts
+ * import { Combiner, Number } from "effect"
+ *
+ * const Min = Combiner.min(Number.Order)
+ *
+ * console.log(Min.combine(3, 1))
+ * // Output: 1
+ *
+ * console.log(Min.combine(1, 3))
+ * // Output: 1
+ * ```
+ *
+ * @see {@link max}
  *
  * @since 4.0.0
  */
@@ -48,7 +197,33 @@ export function min<A>(order: Order.Order<A>): Combiner<A> {
 }
 
 /**
- * Creates a `Combiner` that returns the larger of two values.
+ * Creates a `Combiner` that returns the larger of two values according to
+ * the provided `Order`.
+ *
+ * When to use:
+ * - You want to accumulate the maximum value across a collection.
+ * - You are building a `Reducer` that tracks the running maximum.
+ *
+ * Behavior:
+ * - Compares using the given `Order`. When values are equal, returns `that`
+ *   (the second argument).
+ * - Pure – does not mutate either argument.
+ *
+ * **Example** (maximum of two numbers)
+ *
+ * ```ts
+ * import { Combiner, Number } from "effect"
+ *
+ * const Max = Combiner.max(Number.Order)
+ *
+ * console.log(Max.combine(3, 1))
+ * // Output: 3
+ *
+ * console.log(Max.combine(1, 3))
+ * // Output: 3
+ * ```
+ *
+ * @see {@link min}
  *
  * @since 4.0.0
  */
@@ -57,7 +232,29 @@ export function max<A>(order: Order.Order<A>): Combiner<A> {
 }
 
 /**
- * Creates a `Combiner` that returns the first value.
+ * Creates a `Combiner` that always returns the first (left) argument.
+ *
+ * When to use:
+ * - You want "first write wins" semantics when merging values.
+ * - You need a combiner but the combining logic should be a no-op that keeps
+ *   the existing value.
+ *
+ * Behavior:
+ * - `combine(self, that)` returns `self`, ignoring `that`.
+ * - Pure – the second argument is discarded, not mutated.
+ *
+ * **Example** (keeping the first value)
+ *
+ * ```ts
+ * import { Combiner } from "effect"
+ *
+ * const First = Combiner.first<number>()
+ *
+ * console.log(First.combine(1, 2))
+ * // Output: 1
+ * ```
+ *
+ * @see {@link last}
  *
  * @since 4.0.0
  */
@@ -66,7 +263,28 @@ export function first<A>(): Combiner<A> {
 }
 
 /**
- * Creates a `Combiner` that returns the last value.
+ * Creates a `Combiner` that always returns the last (right) argument.
+ *
+ * When to use:
+ * - You want "last write wins" semantics when merging values.
+ * - You need a combiner that replaces the accumulator with each new value.
+ *
+ * Behavior:
+ * - `combine(self, that)` returns `that`, ignoring `self`.
+ * - Pure – the first argument is discarded, not mutated.
+ *
+ * **Example** (keeping the last value)
+ *
+ * ```ts
+ * import { Combiner } from "effect"
+ *
+ * const Last = Combiner.last<number>()
+ *
+ * console.log(Last.combine(1, 2))
+ * // Output: 2
+ * ```
+ *
+ * @see {@link first}
  *
  * @since 4.0.0
  */
@@ -75,7 +293,31 @@ export function last<A>(): Combiner<A> {
 }
 
 /**
- * Creates a `Combiner` that returns a constant value.
+ * Creates a `Combiner` that ignores both arguments and always returns the
+ * given constant value.
+ *
+ * When to use:
+ * - You need a combiner that produces a fixed result regardless of input.
+ * - You are providing a combiner to a generic API but the combined value is
+ *   predetermined.
+ *
+ * Behavior:
+ * - `combine(self, that)` returns the constant `a`, ignoring both arguments.
+ * - Pure – no mutation occurs.
+ *
+ * **Example** (always returning zero)
+ *
+ * ```ts
+ * import { Combiner } from "effect"
+ *
+ * const Zero = Combiner.constant(0)
+ *
+ * console.log(Zero.combine(42, 99))
+ * // Output: 0
+ * ```
+ *
+ * @see {@link first}
+ * @see {@link last}
  *
  * @since 4.0.0
  */
@@ -84,7 +326,32 @@ export function constant<A>(a: A): Combiner<A> {
 }
 
 /**
- * Between each pair of elements insert `middle`.
+ * Wraps a `Combiner` so that a separator value is inserted between every
+ * pair of combined elements.
+ *
+ * When to use:
+ * - You are building delimited strings (CSV, paths, etc.) by repeated
+ *   combination.
+ * - You need to inject a fixed separator between accumulated values.
+ *
+ * Behavior:
+ * - `intercalate(middle)(combiner).combine(self, that)` is equivalent to
+ *   `combiner.combine(self, combiner.combine(middle, that))`.
+ * - Curried: first provide the separator, then the base combiner.
+ * - Does not mutate the input combiner; returns a new one.
+ *
+ * **Example** (joining strings with a separator)
+ *
+ * ```ts
+ * import { Combiner, String } from "effect"
+ *
+ * const commaSep = Combiner.intercalate(",")(String.ReducerConcat)
+ *
+ * console.log(commaSep.combine("a", "b"))
+ * // Output: "a,b"
+ * ```
+ *
+ * @see {@link make}
  *
  * @since 4.0.0
  */

package/src/Config.ts

@@ -938,7 +938,7 @@ export const Boolean = Schema.Literals([...TrueValues.literals, ...FalseValues.l
  * - Pass to {@link schema} for custom paths, or use the {@link duration}
  *   convenience constructor.
  *
- * Accepts any string that `Duration.fromDurationInput` can parse (e.g.
+ * Accepts any string that `Duration.fromInput` can parse (e.g.
  * `"10 seconds"`, `"500 millis"`).
  *
  * @see {@link duration} – convenience constructor
@@ -948,7 +948,7 @@ export const Boolean = Schema.Literals([...TrueValues.literals, ...FalseValues.l
  */
 export const Duration = Schema.String.pipe(Schema.decodeTo(Schema.Duration, {
   decode: Getter.transformOrFail((s) => {
-    const d = Duration_.fromDurationInput(s as any)
+    const d = Duration_.fromInput(s as any)
     return d ? Effect.succeed(d) : Effect.fail(new Issue.InvalidValue(Option.some(s)))
   }),
   encode: Getter.forbidden(() => "Encoding Duration is not supported")
@@ -1235,7 +1235,7 @@ export function boolean(name?: string) {
  *
  * Shortcut for `Config.schema(Config.Duration, name)`.
  *
- * Accepts any string that `Duration.fromDurationInput` can parse (e.g.
+ * Accepts any string that `Duration.fromInput` can parse (e.g.
  * `"10 seconds"`, `"500 millis"`, `"2 minutes"`).
  *
  * **Example** (Reading a duration)

package/src/DateTime.ts

@@ -12,7 +12,6 @@ import { provideService } from "./internal/effect.ts"
 import * as Layer from "./Layer.ts"
 import type * as order from "./Order.ts"
 import type { Pipeable } from "./Pipeable.ts"
-import type * as Result from "./Result.ts"
 import * as ServiceMap from "./ServiceMap.ts"
 
 const TypeId = Internal.TypeId
@@ -1174,10 +1173,12 @@ export const setZoneNamedUnsafe: {
 // =============================================================================
 
 /**
- * Calulate the difference between two `DateTime` values, returning the number
- * of milliseconds the `other` DateTime is from `self`.
+ * Calulate the difference between two `DateTime` values, returning a
+ * `Duration` representing the amount of time between them.
  *
- * If `other` is *after* `self`, the result will be a positive number.
+ * If `other` is *after* `self`, the result will be a positive `Duration`. If
+ * `other` is *before* `self`, the result will be a negative `Duration`. If they
+ * are equal, the result will be a `Duration` of zero.
  *
  * @since 3.6.0
  * @category comparisons
@@ -1189,7 +1190,7 @@ export const setZoneNamedUnsafe: {
  *   const now = yield* DateTime.now
  *   const other = DateTime.add(now, { minutes: 1 })
  *
- *   // returns 60000
+ *   // returns Duration.minutes(1)
  *   DateTime.distance(now, other)
  * })
  * ```
@@ -1200,10 +1201,12 @@ export const distance: {
   // =============================================================================
 
   /**
-   * Calulate the difference between two `DateTime` values, returning the number
-   * of milliseconds the `other` DateTime is from `self`.
+   * Calulate the difference between two `DateTime` values, returning a
+   * `Duration` representing the amount of time between them.
    *
-   * If `other` is *after* `self`, the result will be a positive number.
+   * If `other` is *after* `self`, the result will be a positive `Duration`. If
+   * `other` is *before* `self`, the result will be a negative `Duration`. If they
+   * are equal, the result will be a `Duration` of zero.
    *
    * @since 3.6.0
    * @category comparisons
@@ -1215,147 +1218,23 @@ export const distance: {
    *   const now = yield* DateTime.now
    *   const other = DateTime.add(now, { minutes: 1 })
    *
-   *   // returns 60000
+   *   // returns Duration.minutes(1)
    *   DateTime.distance(now, other)
    * })
    * ```
    */
-  (other: DateTime): (self: DateTime) => number
+  (other: DateTime): (self: DateTime) => Duration.Duration
   // =============================================================================
   // comparisons
   // =============================================================================
 
   /**
-   * Calulate the difference between two `DateTime` values, returning the number
-   * of milliseconds the `other` DateTime is from `self`.
-   *
-   * If `other` is *after* `self`, the result will be a positive number.
-   *
-   * @since 3.6.0
-   * @category comparisons
-   * @example
-   * ```ts
-   * import { DateTime, Effect } from "effect"
-   *
-   * Effect.gen(function*() {
-   *   const now = yield* DateTime.now
-   *   const other = DateTime.add(now, { minutes: 1 })
-   *
-   *   // returns 60000
-   *   DateTime.distance(now, other)
-   * })
-   * ```
-   */
-  (self: DateTime, other: DateTime): number
-} = Internal.distance
-
-/**
- * Calulate the difference between two `DateTime` values.
- *
- * If the `other` DateTime is before `self`, the result will be a negative
- * `Duration`, returned as a `Failure`.
- *
- * If the `other` DateTime is after `self`, the result will be a positive
- * `Duration`, returned as a `Success`.
- *
- * @since 3.6.0
- * @category comparisons
- * @example
- * ```ts
- * import { DateTime, Effect } from "effect"
- *
- * Effect.gen(function*() {
- *   const now = yield* DateTime.now
- *   const other = DateTime.add(now, { minutes: 1 })
- *
- *   // returns Result.succeed(Duration.minutes(1))
- *   DateTime.distanceDurationResult(now, other)
- *
- *   // returns Result.fail(Duration.minutes(1))
- *   DateTime.distanceDurationResult(other, now)
- * })
- * ```
- */
-export const distanceDurationResult: {
-  /**
-   * Calulate the difference between two `DateTime` values.
-   *
-   * If the `other` DateTime is before `self`, the result will be a negative
-   * `Duration`, returned as a `Failure`.
+   * Calulate the difference between two `DateTime` values, returning a
+   * `Duration` representing the amount of time between them.
    *
-   * If the `other` DateTime is after `self`, the result will be a positive
-   * `Duration`, returned as a `Success`.
-   *
-   * @since 3.6.0
-   * @category comparisons
-   * @example
-   * ```ts
-   * import { DateTime, Effect } from "effect"
-   *
-   * Effect.gen(function*() {
-   *   const now = yield* DateTime.now
-   *   const other = DateTime.add(now, { minutes: 1 })
-   *
-   *   // returns Result.succeed(Duration.minutes(1))
-   *   DateTime.distanceDurationResult(now, other)
-   *
-   *   // returns Result.fail(Duration.minutes(1))
-   *   DateTime.distanceDurationResult(other, now)
-   * })
-   * ```
-   */
-  (other: DateTime): (self: DateTime) => Result.Result<Duration.Duration, Duration.Duration>
-  /**
-   * Calulate the difference between two `DateTime` values.
-   *
-   * If the `other` DateTime is before `self`, the result will be a negative
-   * `Duration`, returned as a `Failure`.
-   *
-   * If the `other` DateTime is after `self`, the result will be a positive
-   * `Duration`, returned as a `Success`.
-   *
-   * @since 3.6.0
-   * @category comparisons
-   * @example
-   * ```ts
-   * import { DateTime, Effect } from "effect"
-   *
-   * Effect.gen(function*() {
-   *   const now = yield* DateTime.now
-   *   const other = DateTime.add(now, { minutes: 1 })
-   *
-   *   // returns Result.succeed(Duration.minutes(1))
-   *   DateTime.distanceDurationResult(now, other)
-   *
-   *   // returns Result.fail(Duration.minutes(1))
-   *   DateTime.distanceDurationResult(other, now)
-   * })
-   * ```
-   */
-  (self: DateTime, other: DateTime): Result.Result<Duration.Duration, Duration.Duration>
-} = Internal.distanceDurationResult
-
-/**
- * Calulate the distance between two `DateTime` values.
- *
- * @since 3.6.0
- * @category comparisons
- * @example
- * ```ts
- * import { DateTime, Effect } from "effect"
- *
- * Effect.gen(function*() {
- *   const now = yield* DateTime.now
- *   const other = DateTime.add(now, { minutes: 1 })
- *
- *   // returns Duration.minutes(1)
- *   DateTime.distanceDuration(now, other)
- * })
- * ```
- */
-export const distanceDuration: {
-  /**
-   * Calulate the distance between two `DateTime` values.
+   * If `other` is *after* `self`, the result will be a positive `Duration`. If
+   * `other` is *before* `self`, the result will be a negative `Duration`. If they
+   * are equal, the result will be a `Duration` of zero.
    *
    * @since 3.6.0
    * @category comparisons
@@ -1368,31 +1247,12 @@ export const distanceDuration: {
    *   const other = DateTime.add(now, { minutes: 1 })
    *
    *   // returns Duration.minutes(1)
-   *   DateTime.distanceDuration(now, other)
-   * })
-   * ```
-   */
-  (other: DateTime): (self: DateTime) => Duration.Duration
-  /**
-   * Calulate the distance between two `DateTime` values.
-   *
-   * @since 3.6.0
-   * @category comparisons
-   * @example
-   * ```ts
-   * import { DateTime, Effect } from "effect"
-   *
-   * Effect.gen(function*() {
-   *   const now = yield* DateTime.now
-   *   const other = DateTime.add(now, { minutes: 1 })
-   *
-   *   // returns Duration.minutes(1)
-   *   DateTime.distanceDuration(now, other)
+   *   DateTime.distance(now, other)
    * })
    * ```
    */
   (self: DateTime, other: DateTime): Duration.Duration
-} = Internal.distanceDuration
+} = Internal.distance
 
 /**
  * Returns the earlier of two `DateTime` values.
@@ -3054,7 +2914,7 @@ export const addDuration: {
    * )
    * ```
    */
-  (duration: Duration.DurationInput): <A extends DateTime>(self: A) => A
+  (duration: Duration.Input): <A extends DateTime>(self: A) => A
   // =============================================================================
   // math
   // =============================================================================
@@ -3074,7 +2934,7 @@ export const addDuration: {
    * )
    * ```
    */
-  <A extends DateTime>(self: A, duration: Duration.DurationInput): A
+  <A extends DateTime>(self: A, duration: Duration.Input): A
 } = Internal.addDuration
 
 /**
@@ -3108,7 +2968,7 @@ export const subtractDuration: {
    * )
    * ```
    */
-  (duration: Duration.DurationInput): <A extends DateTime>(self: A) => A
+  (duration: Duration.Input): <A extends DateTime>(self: A) => A
   /**
    * Subtract the given `Duration` from a `DateTime`.
    *
@@ -3124,7 +2984,7 @@ export const subtractDuration: {
    * )
    * ```
    */
-  <A extends DateTime>(self: A, duration: Duration.DurationInput): A
+  <A extends DateTime>(self: A, duration: Duration.Input): A
 } = Internal.subtractDuration
 
 /**