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

package/src/Clock.ts

@@ -67,6 +67,11 @@ import * as effect from "./internal/effect.ts"
  * Represents a time-based clock which provides functionality related to time
  * and scheduling.
  *
+ * **When to use**
+ *
+ * Use to define or provide a clock service for current-time and sleep
+ * operations.
+ *
  * **Example** (Reading current time)
  *
  * ```ts
@@ -86,29 +91,56 @@ import * as effect from "./internal/effect.ts"
  */
 export interface Clock {
   /**
-   * Unsafely returns the current time in milliseconds.
+   * Returns the current time in milliseconds unsafely.
+   *
+   * **When to use**
+   *
+   * Use to read millisecond time synchronously when you already have a `Clock`
+   * service and can accept non-effectful access.
    */
   currentTimeMillisUnsafe(): number
   /**
    * Returns the current time in milliseconds.
+   *
+   * **When to use**
+   *
+   * Use to read millisecond time through this `Clock` service in `Effect`.
    */
   readonly currentTimeMillis: Effect<number>
   /**
-   * Unsafely returns the current time in nanoseconds.
+   * Returns the current time in nanoseconds unsafely.
+   *
+   * **When to use**
+   *
+   * Use to read nanosecond time synchronously when you already have a `Clock`
+   * service and can accept non-effectful access.
    */
   currentTimeNanosUnsafe(): bigint
   /**
    * Returns the current time in nanoseconds.
+   *
+   * **When to use**
+   *
+   * Use to read nanosecond time through this `Clock` service in `Effect`.
    */
   readonly currentTimeNanos: Effect<bigint>
   /**
    * Asynchronously sleeps for the specified duration.
+   *
+   * **When to use**
+   *
+   * Use to delay an `Effect` workflow by a duration through this `Clock` service.
    */
   sleep(duration: Duration.Duration): Effect<void>
 }
 
 /**
- * A reference to the current Clock service in the environment.
+ * Context reference for the current Clock service in the environment.
+ *
+ * **When to use**
+ *
+ * Use when you need to access or provide the full Clock service rather than a
+ * single timestamp accessor.
  *
  * **Example** (Accessing the Clock service)
  *
@@ -121,6 +153,10 @@ export interface Clock {
  * })
  * ```
  *
+ * @see {@link clockWith} for using the current Clock service inside an effect
+ * @see {@link currentTimeMillis} for reading the current time in milliseconds
+ * @see {@link currentTimeNanos} for reading the current time in nanoseconds
+ *
  * @category references
  * @since 2.0.0
  */
@@ -129,6 +165,11 @@ export const Clock: Context.Reference<Clock> = effect.ClockRef
 /**
  * Accesses the current Clock service and uses it to run the provided function.
  *
+ * **When to use**
+ *
+ * Use when you need the full Clock service interface to perform multiple time
+ * operations or call unsafe variants within a single effect.
+ *
  * **Example** (Using the current Clock service)
  *
  * ```ts
@@ -143,6 +184,9 @@ export const Clock: Context.Reference<Clock> = effect.ClockRef
  * )
  * ```
  *
+ * @see {@link Clock} for the service reference
+ * @see {@link currentTimeMillis} for convenience accessor that returns milliseconds
+ * @see {@link currentTimeNanos} for convenience accessor that returns nanoseconds
  * @category constructors
  * @since 2.0.0
  */
@@ -151,6 +195,11 @@ export const clockWith: <A, E, R>(f: (clock: Clock) => Effect<A, E, R>) => Effec
 /**
  * Returns an Effect that succeeds with the current time in milliseconds.
  *
+ * **When to use**
+ *
+ * Use to read wall-clock time from the active Clock service with millisecond
+ * precision.
+ *
  * **Example** (Reading milliseconds)
  *
  * ```ts
@@ -163,6 +212,9 @@ export const clockWith: <A, E, R>(f: (clock: Clock) => Effect<A, E, R>) => Effec
  * })
  * ```
  *
+ * @see {@link currentTimeNanos} for nanosecond precision
+ * @see {@link clockWith} for accessing the full Clock service
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -171,6 +223,11 @@ export const currentTimeMillis: Effect<number> = effect.currentTimeMillis
 /**
  * Returns an Effect that succeeds with the current time in nanoseconds.
  *
+ * **When to use**
+ *
+ * Use to read wall-clock time from the active `Clock` service with nanosecond
+ * precision.
+ *
  * **Example** (Reading nanoseconds)
  *
  * ```ts

package/src/Combiner.ts

@@ -3,7 +3,7 @@
  *
  * 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
+ * (for that, see `Reducer` which extends `Combiner` with an
  * `initialValue`).
  *
  * ## Mental model
@@ -13,7 +13,7 @@
  * - **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.
+ *   a neutral element. Use `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`,
@@ -70,7 +70,7 @@ import type * as Order from "./Order.ts"
  *
  * **When to use**
  *
- * Use `Combiner` when you need to describe how two values of the same type
+ * Use when you need to describe how two values of the same type
  * merge, pass a reusable combining strategy to library functions like
  * `Struct.makeCombiner` or `Option.makeCombinerFailFast`, or define the
  * combining step for a `Reducer`.
@@ -93,6 +93,10 @@ import type * as Order from "./Order.ts"
 export interface Combiner<A> {
   /**
    * Combines two values into a new value.
+   *
+   * **When to use**
+   *
+   * Use to merge two values according to this combining strategy.
    */
   readonly combine: (self: A, that: A) => A
 }
@@ -102,7 +106,7 @@ export interface Combiner<A> {
  *
  * **When to use**
  *
- * Use this when you have a custom combining operation that is not covered by
+ * Use when you have a custom combining operation that is not covered by
  * the built-in constructors (`min`, `max`, `first`, `last`, `constant`).
  *
  * **Details**
@@ -134,14 +138,14 @@ export function make<A>(combine: (self: A, that: A) => A): Combiner<A> {
  *
  * **When to use**
  *
- * Use this when the "right" value should act as the accumulator side, or when
+ * Use when the "right" value should act as the accumulator side, or when
  * you want to reverse the natural direction of a non-commutative combiner such
  * as string concatenation.
  *
  * **Details**
  *
  * Returns a new `Combiner` where `combine(self, that)` calls the original
- * combiner as `combine(that, self)`. The input combiner is not mutated.
+ * combiner as `combine(that, self)`.
  *
  * **Example** (reversing string concatenation)
  *
@@ -168,13 +172,13 @@ export function flip<A>(combiner: Combiner<A>): Combiner<A> {
  *
  * **When to use**
  *
- * Use this when you want to accumulate the minimum value across a collection or
+ * Use when you want to accumulate the minimum value across a collection or
  * build a `Reducer` that tracks the running minimum.
  *
  * **Details**
  *
  * The combiner compares values using the given `Order`. When values are equal,
- * it returns `that` (the second argument). It does not mutate either argument.
+ * it returns `that` (the second argument).
  *
  * **Example** (minimum of two numbers)
  *
@@ -204,13 +208,13 @@ export function min<A>(order: Order.Order<A>): Combiner<A> {
  *
  * **When to use**
  *
- * Use this when you want to accumulate the maximum value across a collection or
+ * Use when you want to accumulate the maximum value across a collection or
  * build a `Reducer` that tracks the running maximum.
  *
  * **Details**
  *
  * The combiner compares values using the given `Order`. When values are equal,
- * it returns `that` (the second argument). It does not mutate either argument.
+ * it returns `that` (the second argument).
  *
  * **Example** (maximum of two numbers)
  *
@@ -239,13 +243,12 @@ export function max<A>(order: Order.Order<A>): Combiner<A> {
  *
  * **When to use**
  *
- * Use this when you want "first write wins" semantics while merging values, or
+ * Use when you want "first write wins" semantics while merging values, or
  * when the combining logic should keep the existing value.
  *
  * **Details**
  *
- * `combine(self, that)` returns `self` and ignores `that`. The second argument
- * is discarded, not mutated.
+ * `combine(self, that)` returns `self` and ignores `that`.
  *
  * **Example** (keeping the first value)
  *
@@ -271,13 +274,12 @@ export function first<A>(): Combiner<A> {
  *
  * **When to use**
  *
- * Use this when you want "last write wins" semantics while merging values, or
+ * Use when you want "last write wins" semantics while merging values, or
  * when each new value should replace the accumulator.
  *
  * **Details**
  *
- * `combine(self, that)` returns `that` and ignores `self`. The first argument
- * is discarded, not mutated.
+ * `combine(self, that)` returns `that` and ignores `self`.
  *
  * **Example** (keeping the last value)
  *
@@ -304,14 +306,13 @@ export function last<A>(): Combiner<A> {
  *
  * **When to use**
  *
- * Use this when a combiner should produce a fixed result regardless of input,
+ * Use when a combiner should produce a fixed result regardless of input,
  * or when a generic API needs a combiner but the combined value is
  * predetermined.
  *
  * **Details**
  *
  * `combine(self, that)` returns the constant `a` and ignores both arguments.
- * No mutation occurs.
  *
  * **Example** (always returning zero)
  *
@@ -339,7 +340,7 @@ export function constant<A>(a: A): Combiner<A> {
  *
  * **When to use**
  *
- * Use this when you are building delimited strings (CSV, paths, etc.) by
+ * Use when you are building delimited strings (CSV, paths, etc.) by
  * repeated combination, or when you need to inject a fixed separator between
  * accumulated values.
  *
@@ -347,8 +348,7 @@ export function constant<A>(a: A): Combiner<A> {
  *
  * `intercalate(middle)(combiner).combine(self, that)` is equivalent to
  * `combiner.combine(self, combiner.combine(middle, that))`. This function is
- * curried: first provide the separator, then the base combiner. It returns a
- * new combiner and does not mutate the input combiner.
+ * curried: first provide the separator, then the base combiner.
  *
  * **Example** (joining strings with a separator)
  *