effect 4.0.0-beta.70 → 4.0.0-beta.71

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
  */
@@ -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
    */
@@ -2339,6 +2465,19 @@ export const format = (self: Duration): string => {
 /**
  * A `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
  */
@@ -2347,6 +2486,13 @@ export const ReducerSum: Reducer.Reducer<Duration> = Reducer.make(sum, zero)
 /**
  * A `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
  */
@@ -2355,6 +2501,13 @@ export const CombinerMax: Combiner.Combiner<Duration> = Combiner.max(Order)
 /**
  * A `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
  */