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

package/src/Differ.ts

@@ -41,6 +41,11 @@
 /**
  * Describes how to compute, combine, and apply patches for values of type `T`.
  *
+ * **When to use**
+ *
+ * Use to model patch-based updates for a value type when callers need to
+ * compute a patch from two values, combine patches, and apply a patch later.
+ *
  * **Details**
  *
  * A `Differ` provides an empty patch, computes the patch between two values,

package/src/Duration.ts

@@ -1,15 +1,51 @@
 /**
- * This module provides utilities for working with durations of time. A `Duration`
- * is an immutable data type that represents a span of time with high precision,
- * supporting operations from nanoseconds to weeks.
- *
- * Durations support:
- * - **High precision**: Nanosecond-level accuracy using BigInt
- * - **Multiple formats**: Numbers (millis), BigInt (nanos), tuples, strings
- * - **Arithmetic operations**: Add, subtract, multiply, divide
- * - **Comparisons**: Equal, less than, greater than
- * - **Conversions**: Between different time units
- * - **Human-readable formatting**: Pretty printing and parsing
+ * The `Duration` module models spans of time as immutable values with support
+ * for unit conversion, ordering, arithmetic, and positive or negative infinity.
+ * It is the standard representation for delays, timeouts, intervals, and
+ * TTL-like values across Effect APIs.
+ *
+ * **Mental model**
+ *
+ * - A `Duration` stores either milliseconds, nanoseconds, `Infinity`, or
+ *   `-Infinity`; operations preserve that distinction where it matters
+ * - Constructor helpers such as {@link seconds} and {@link millis} build
+ *   duration values for the chosen unit
+ * - {@link Input} values are decoded at API boundaries: numbers mean
+ *   milliseconds, bigints mean nanoseconds, tuples mean `[seconds, nanos]`,
+ *   and strings use units such as `"5 seconds"`
+ * - Arithmetic and ordering helpers return new duration values rather than
+ *   mutating existing ones
+ *
+ * **Common tasks**
+ *
+ * - Build durations with {@link nanos}, {@link micros}, {@link millis},
+ *   {@link seconds}, {@link minutes}, {@link hours}, {@link days}, or
+ *   {@link weeks}
+ * - Decode flexible inputs with {@link fromInput} or {@link fromInputUnsafe}
+ * - Convert with {@link toMillis}, {@link toSeconds}, {@link toNanos},
+ *   {@link toHrTime}, {@link parts}, or {@link format}
+ * - Compare and constrain durations with {@link Order}, {@link between},
+ *   {@link min}, {@link max}, and {@link clamp}
+ * - Combine durations with {@link sum}, {@link subtract}, {@link times}, and
+ *   {@link divide}
+ *
+ * **Gotchas**
+ *
+ * - Passing a plain number means milliseconds, not seconds
+ * - {@link toNanosUnsafe} throws for infinite durations; {@link toNanos}
+ *   returns `Option.none()` instead
+ * - Unsafe decoders and unsafe math helpers throw or apply fallback rules for
+ *   invalid inputs; prefer the safe variants when input is external
+ *
+ * **Example** (Decoding and formatting a duration)
+ *
+ * ```ts
+ * import { Duration, Option } from "effect"
+ *
+ * const formatted = Duration.fromInput("90 seconds").pipe(
+ *   Option.map((duration) => Duration.format(duration))
+ * )
+ * ```
  *
  * @since 2.0.0
  */
@@ -40,6 +76,16 @@ const bigint1e9 = BigInt(1_000_000_000)
  * Represents a span of time with high precision, supporting operations from
  * nanoseconds to weeks.
  *
+ * **When to use**
+ *
+ * Use to model elapsed time, delays, timeouts, schedule intervals, and cache
+ * TTLs as immutable duration values.
+ *
+ * @see {@link Input} for values accepted by APIs that decode duration-like
+ * inputs
+ * @see {@link DurationValue} for the tagged representation exposed by the
+ * `value` field
+ *
  * @category models
  * @since 2.0.0
  */
@@ -51,11 +97,21 @@ export interface Duration extends Equal.Equal, Pipeable, Inspectable.Inspectable
 /**
  * Tagged representation of a `Duration` value.
  *
+ * **When to use**
+ *
+ * Use when modeling or inspecting the exact tagged representation stored in a
+ * `Duration`, including finite millisecond or nanosecond values and infinite
+ * sentinels.
+ *
  * **Details**
  *
  * A duration is represented as milliseconds, nanoseconds, positive infinity,
  * or negative infinity.
  *
+ * @see {@link Duration} for the public type whose `value` field contains this
+ * representation
+ * @see {@link match} for pattern matching without reading `value` directly
+ *
  * @category models
  * @since 2.0.0
  */
@@ -68,6 +124,13 @@ export type DurationValue =
 /**
  * Valid time units that can be used in duration string representations.
  *
+ * **When to use**
+ *
+ * Use when typing the unit portion of duration string inputs accepted by
+ * `Duration.Input`.
+ *
+ * @see {@link Input} for the full duration input union
+ *
  * @category models
  * @since 2.0.0
  */
@@ -92,11 +155,23 @@ export type Unit =
 /**
  * Valid input types that can be converted to a Duration.
  *
+ * **When to use**
+ *
+ * Use when an API should accept any value that Effect can convert into a
+ * `Duration`, including existing durations, millisecond numbers, nanosecond
+ * bigints, high-resolution tuples, duration strings, infinity strings, or
+ * duration objects.
+ *
  * **Details**
  *
  * String inputs accept values like `"10 seconds"`, `"500 millis"`,
  * `"Infinity"`, and `"-Infinity"`.
  *
+ * @see {@link fromInput} for safe conversion to `Option`
+ * @see {@link fromInputUnsafe} for throwing conversion
+ * @see {@link DurationObject} for object-shaped duration input
+ * @see {@link Unit} for supported string units
+ *
  * @category models
  * @since 4.0.0
  */
@@ -252,7 +327,7 @@ const invalid = (input: unknown): never => {
 }
 
 /**
- * Safely decodes a `Input` value into a `Duration`, returning
+ * Decodes a `Input` value into a `Duration` safely, returning
  * `Option.none()` if decoding fails.
  *
  * **Example** (Safely decoding duration inputs)
@@ -337,7 +412,7 @@ const make = (input: number | bigint): Duration => {
 }
 
 /**
- * Checks if a value is a Duration.
+ * Checks whether a value is a Duration.
  *
  * **Example** (Checking for durations)
  *
@@ -354,7 +429,7 @@ const make = (input: number | bigint): Duration => {
 export const isDuration = (u: unknown): u is Duration => hasProperty(u, TypeId)
 
 /**
- * Checks if a Duration is finite (not infinite).
+ * Checks whether a Duration is finite (not infinite).
  *
  * **Example** (Checking finite durations)
  *
@@ -372,7 +447,7 @@ export const isFinite = (self: Duration): boolean =>
   self.value._tag !== "Infinity" && self.value._tag !== "NegativeInfinity"
 
 /**
- * Checks if a Duration is zero.
+ * Checks whether a Duration is zero.
  *
  * **Example** (Checking for zero durations)
  *
@@ -484,7 +559,7 @@ export const abs = (self: Duration): Duration => {
 }
 
 /**
- * Negates the duration.
+ * Returns the negated duration.
  *
  * **Example** (Negating durations)
  *
@@ -834,7 +909,7 @@ export const toWeeks = (self: Input): number =>
   })
 
 /**
- * Get the duration in nanoseconds as a bigint.
+ * Gets the duration in nanoseconds as a bigint, throwing for infinite durations.
  *
  * **Gotchas**
  *
@@ -870,7 +945,7 @@ export const toNanosUnsafe = (input: Input): bigint => {
 }
 
 /**
- * Get the duration in nanoseconds as a bigint.
+ * Gets the duration in nanoseconds safely as an `Option<bigint>`.
  *
  * **Details**
  *
@@ -1148,7 +1223,7 @@ export const matchPair: {
 })
 
 /**
- * Order instance for `Duration`, allowing comparison operations.
+ * Provides an `Order` instance for comparing `Duration` values.
  *
  * **Details**
  *
@@ -1191,6 +1266,19 @@ export const Order: order.Order<Duration> = order.make((self, that) =>
  * Returns `true` if a `Duration` is greater than or equal to `minimum` and
  * less than or equal to `maximum`, according to `Duration.Order`.
  *
+ * **When to use**
+ *
+ * Use to test whether a duration is inside an inclusive range.
+ *
+ * **Details**
+ *
+ * Both bounds are inclusive and compared with `Duration.Order`.
+ *
+ * **Gotchas**
+ *
+ * The bounds are not normalized. If `minimum` is greater than `maximum`, the
+ * predicate returns `false` for every duration.
+ *
  * **Example** (Checking duration ranges)
  *
  * ```ts
@@ -1203,6 +1291,10 @@ export const Order: order.Order<Duration> = order.make((self, that) =>
  * console.log(isInRange) // true
  * ```
  *
+ * @see {@link clamp} for constraining a duration to a range
+ * @see {@link isGreaterThanOrEqualTo} for checking only the lower bound
+ * @see {@link isLessThanOrEqualTo} for checking only the upper bound
+ *
  * @category predicates
  * @since 2.0.0
  */
@@ -1211,6 +1303,19 @@ export const between: {
    * Returns `true` if a `Duration` is greater than or equal to `minimum` and
    * less than or equal to `maximum`, according to `Duration.Order`.
    *
+   * **When to use**
+   *
+   * Use to test whether a duration is inside an inclusive range.
+   *
+   * **Details**
+   *
+   * Both bounds are inclusive and compared with `Duration.Order`.
+   *
+   * **Gotchas**
+   *
+   * The bounds are not normalized. If `minimum` is greater than `maximum`, the
+   * predicate returns `false` for every duration.
+   *
    * **Example** (Checking duration ranges)
    *
    * ```ts
@@ -1223,6 +1328,10 @@ export const between: {
    * console.log(isInRange) // true
    * ```
    *
+   * @see {@link clamp} for constraining a duration to a range
+   * @see {@link isGreaterThanOrEqualTo} for checking only the lower bound
+   * @see {@link isLessThanOrEqualTo} for checking only the upper bound
+   *
    * @category predicates
    * @since 2.0.0
    */
@@ -1231,6 +1340,19 @@ export const between: {
    * Returns `true` if a `Duration` is greater than or equal to `minimum` and
    * less than or equal to `maximum`, according to `Duration.Order`.
    *
+   * **When to use**
+   *
+   * Use to test whether a duration is inside an inclusive range.
+   *
+   * **Details**
+   *
+   * Both bounds are inclusive and compared with `Duration.Order`.
+   *
+   * **Gotchas**
+   *
+   * The bounds are not normalized. If `minimum` is greater than `maximum`, the
+   * predicate returns `false` for every duration.
+   *
    * **Example** (Checking duration ranges)
    *
    * ```ts
@@ -1243,6 +1365,10 @@ export const between: {
    * console.log(isInRange) // true
    * ```
    *
+   * @see {@link clamp} for constraining a duration to a range
+   * @see {@link isGreaterThanOrEqualTo} for checking only the lower bound
+   * @see {@link isLessThanOrEqualTo} for checking only the upper bound
+   *
    * @category predicates
    * @since 2.0.0
    */
@@ -1250,7 +1376,7 @@ export const between: {
 } = order.isBetween(Order)
 
 /**
- * Equivalence instance for `Duration`, allowing equality comparisons.
+ * Provides an `Equivalence` instance for comparing `Duration` values.
  *
  * **Example** (Comparing durations for equivalence)
  *
@@ -1283,7 +1409,7 @@ export const Equivalence: Equ.Equivalence<Duration> = (self, that) =>
  * console.log(Duration.toSeconds(shorter)) // 3
  * ```
  *
- * @category order
+ * @category ordering
  * @since 2.0.0
  */
 export const min: {
@@ -1299,7 +1425,7 @@ export const min: {
    * console.log(Duration.toSeconds(shorter)) // 3
    * ```
    *
-   * @category order
+   * @category ordering
    * @since 2.0.0
    */
   (that: Duration): (self: Duration) => Duration
@@ -1315,7 +1441,7 @@ export const min: {
    * console.log(Duration.toSeconds(shorter)) // 3
    * ```
    *
-   * @category order
+   * @category ordering
    * @since 2.0.0
    */
   (self: Duration, that: Duration): Duration
@@ -1372,7 +1498,7 @@ export const max: {
 } = order.max(Order)
 
 /**
- * Clamps a Duration between a minimum and maximum value.
+ * Returns a `Duration` constrained between a minimum and maximum value.
  *
  * **Example** (Clamping durations to a range)
  *
@@ -1391,7 +1517,7 @@ export const max: {
  */
 export const clamp: {
   /**
-   * Clamps a Duration between a minimum and maximum value.
+   * Returns a `Duration` constrained between a minimum and maximum value.
    *
    * **Example** (Clamping durations to a range)
    *
@@ -1410,7 +1536,7 @@ export const clamp: {
    */
   (options: { minimum: Duration; maximum: Duration }): (self: Duration) => Duration
   /**
-   * Clamps a Duration between a minimum and maximum value.
+   * Returns a `Duration` constrained between a minimum and maximum value.
    *
    * **Example** (Clamping durations to a range)
    *
@@ -1431,7 +1557,7 @@ export const clamp: {
 } = order.clamp(Order)
 
 /**
- * Safely divides a `Duration` by a finite, non-zero number.
+ * Divides a `Duration` by a finite, non-zero number safely.
  *
  * **Details**
  *
@@ -1455,7 +1581,7 @@ export const clamp: {
  */
 export const divide: {
   /**
-   * Safely divides a `Duration` by a finite, non-zero number.
+   * Divides a `Duration` by a finite, non-zero number safely.
    *
    * **Details**
    *
@@ -1479,7 +1605,7 @@ export const divide: {
    */
   (by: number): (self: Duration) => Option.Option<Duration>
   /**
-   * Safely divides a `Duration` by a finite, non-zero number.
+   * Divides a `Duration` by a finite, non-zero number safely.
    *
    * **Details**
    *
@@ -1633,7 +1759,7 @@ export const divideUnsafe: {
 )
 
 /**
- * Multiplies a `Duration` by a number.
+ * Returns a `Duration` multiplied by a number.
  *
  * **Details**
  *
@@ -1656,7 +1782,7 @@ export const divideUnsafe: {
  */
 export const times: {
   /**
-   * Multiplies a `Duration` by a number.
+   * Returns a `Duration` multiplied by a number.
    *
    * **Details**
    *
@@ -1679,7 +1805,7 @@ export const times: {
    */
   (times: number): (self: Duration) => Duration
   /**
-   * Multiplies a `Duration` by a number.
+   * Returns a `Duration` multiplied by a number.
    *
    * **Details**
    *
@@ -1913,7 +2039,7 @@ export const sum: {
 )
 
 /**
- * Checks if the first Duration is less than the second.
+ * Checks whether the first Duration is less than the second.
  *
  * **Example** (Comparing durations with less than)
  *
@@ -1929,7 +2055,7 @@ export const sum: {
  */
 export const isLessThan: {
   /**
-   * Checks if the first Duration is less than the second.
+   * Checks whether the first Duration is less than the second.
    *
    * **Example** (Comparing durations with less than)
    *
@@ -1945,7 +2071,7 @@ export const isLessThan: {
    */
   (that: Duration): (self: Duration) => boolean
   /**
-   * Checks if the first Duration is less than the second.
+   * Checks whether the first Duration is less than the second.
    *
    * **Example** (Comparing durations with less than)
    *
@@ -1963,7 +2089,7 @@ export const isLessThan: {
 } = order.isLessThan(Order)
 
 /**
- * Checks if the first Duration is less than or equal to the second.
+ * Checks whether the first Duration is less than or equal to the second.
  *
  * **Example** (Comparing durations with less than or equal)
  *
@@ -1982,7 +2108,7 @@ export const isLessThan: {
  */
 export const isLessThanOrEqualTo: {
   /**
-   * Checks if the first Duration is less than or equal to the second.
+   * Checks whether the first Duration is less than or equal to the second.
    *
    * **Example** (Comparing durations with less than or equal)
    *
@@ -2001,7 +2127,7 @@ export const isLessThanOrEqualTo: {
    */
   (that: Duration): (self: Duration) => boolean
   /**
-   * Checks if the first Duration is less than or equal to the second.
+   * Checks whether the first Duration is less than or equal to the second.
    *
    * **Example** (Comparing durations with less than or equal)
    *
@@ -2022,7 +2148,7 @@ export const isLessThanOrEqualTo: {
 } = order.isLessThanOrEqualTo(Order)
 
 /**
- * Checks if the first Duration is greater than the second.
+ * Checks whether the first Duration is greater than the second.
  *
  * **Example** (Comparing durations with greater than)
  *
@@ -2038,7 +2164,7 @@ export const isLessThanOrEqualTo: {
  */
 export const isGreaterThan: {
   /**
-   * Checks if the first Duration is greater than the second.
+   * Checks whether the first Duration is greater than the second.
    *
    * **Example** (Comparing durations with greater than)
    *
@@ -2054,7 +2180,7 @@ export const isGreaterThan: {
    */
   (that: Duration): (self: Duration) => boolean
   /**
-   * Checks if the first Duration is greater than the second.
+   * Checks whether the first Duration is greater than the second.
    *
    * **Example** (Comparing durations with greater than)
    *
@@ -2072,7 +2198,7 @@ export const isGreaterThan: {
 } = order.isGreaterThan(Order)
 
 /**
- * Checks if the first Duration is greater than or equal to the second.
+ * Checks whether the first Duration is greater than or equal to the second.
  *
  * **Example** (Comparing durations with greater than or equal)
  *
@@ -2091,7 +2217,7 @@ export const isGreaterThan: {
  */
 export const isGreaterThanOrEqualTo: {
   /**
-   * Checks if the first Duration is greater than or equal to the second.
+   * Checks whether the first Duration is greater than or equal to the second.
    *
    * **Example** (Comparing durations with greater than or equal)
    *
@@ -2110,7 +2236,7 @@ export const isGreaterThanOrEqualTo: {
    */
   (that: Duration): (self: Duration) => boolean
   /**
-   * Checks if the first Duration is greater than or equal to the second.
+   * Checks whether the first Duration is greater than or equal to the second.
    *
    * **Example** (Comparing durations with greater than or equal)
    *
@@ -2131,7 +2257,7 @@ export const isGreaterThanOrEqualTo: {
 } = order.isGreaterThanOrEqualTo(Order)
 
 /**
- * Checks if two Durations are equal.
+ * Checks whether two Durations are equal.
  *
  * **Example** (Checking duration equality)
  *
@@ -2147,7 +2273,7 @@ export const isGreaterThanOrEqualTo: {
  */
 export const equals: {
   /**
-   * Checks if two Durations are equal.
+   * Checks whether two Durations are equal.
    *
    * **Example** (Checking duration equality)
    *
@@ -2163,7 +2289,7 @@ export const equals: {
    */
   (that: Duration): (self: Duration) => boolean
   /**
-   * Checks if two Durations are equal.
+   * Checks whether two Durations are equal.
    *
    * **Example** (Checking duration equality)
    *
@@ -2337,7 +2463,20 @@ export const format = (self: Duration): string => {
 }
 
 /**
- * A `Reducer` for summing `Duration`s.
+ * Reducer for summing `Duration`s.
+ *
+ * **When to use**
+ *
+ * Use to sum many `Duration` values through APIs that consume a `Reducer`.
+ *
+ * **Details**
+ *
+ * `ReducerSum` uses `sum` and starts from `zero`, so `combineAll([])` returns
+ * `zero`.
+ *
+ * @see {@link sum} for adding two duration values directly
+ * @see {@link CombinerMax} for keeping the longest duration instead of summing
+ * @see {@link CombinerMin} for keeping the shortest duration instead of summing
  *
  * @category math
  * @since 4.0.0
@@ -2345,7 +2484,14 @@ export const format = (self: Duration): string => {
 export const ReducerSum: Reducer.Reducer<Duration> = Reducer.make(sum, zero)
 
 /**
- * A `Combiner` that returns the maximum `Duration`.
+ * Combiner that returns the maximum `Duration`.
+ *
+ * **When to use**
+ *
+ * Use to keep the longest `Duration` when an API consumes a `Combiner`.
+ *
+ * @see {@link CombinerMin} for keeping the shortest `Duration`
+ * @see {@link max} for comparing two `Duration` values directly
  *
  * @category math
  * @since 4.0.0
@@ -2353,7 +2499,14 @@ export const ReducerSum: Reducer.Reducer<Duration> = Reducer.make(sum, zero)
 export const CombinerMax: Combiner.Combiner<Duration> = Combiner.max(Order)
 
 /**
- * A `Combiner` that returns the minimum `Duration`.
+ * Combiner that returns the minimum `Duration`.
+ *
+ * **When to use**
+ *
+ * Use to keep the shortest `Duration` through APIs that consume a `Combiner`.
+ *
+ * @see {@link CombinerMax} for keeping the longest `Duration`
+ * @see {@link min} for comparing two `Duration` values directly
  *
  * @category math
  * @since 4.0.0