effect 4.0.0-beta.66 → 4.0.0-beta.67

package/dist/Duration.d.ts

@@ -26,18 +26,21 @@ declare const TypeId = "~effect/time/Duration";
  * Represents a span of time with high precision, supporting operations from
  * nanoseconds to weeks.
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface Duration extends Equal.Equal, Pipeable, Inspectable.Inspectable {
     readonly [TypeId]: typeof TypeId;
     readonly value: DurationValue;
 }
 /**
- * The internal representation of a `Duration` value.
+ * Tagged representation of a `Duration` value.
+ *
+ * A duration is represented as milliseconds, nanoseconds, positive infinity,
+ * or negative infinity.
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export type DurationValue = {
     _tag: "Millis";
@@ -53,8 +56,8 @@ export type DurationValue = {
 /**
  * Valid time units that can be used in duration string representations.
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export type Unit = "nano" | "nanos" | "micro" | "micros" | "milli" | "millis" | "second" | "seconds" | "minute" | "minutes" | "hour" | "hours" | "day" | "days" | "week" | "weeks";
 /**
@@ -63,8 +66,8 @@ export type Unit = "nano" | "nanos" | "micro" | "micros" | "milli" | "millis" |
  * String inputs accept values like `"10 seconds"`, `"500 millis"`,
  * `"Infinity"`, and `"-Infinity"`.
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export type Input = Duration | number | bigint | readonly [seconds: number, nanos: number] | `${number} ${Unit}` | "Infinity" | "-Infinity" | DurationObject;
 /**
@@ -73,7 +76,8 @@ export type Input = Duration | number | bigint | readonly [seconds: number, nano
  *
  * Compatible with Temporal.Duration-like objects.
  *
- * @example
+ * **Example** (Combining duration object fields)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -82,8 +86,8 @@ export type Input = Duration | number | bigint | readonly [seconds: number, nano
  * Duration.fromInputUnsafe({ seconds: 1, nanoseconds: 500 })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface DurationObject {
     readonly weeks?: number | undefined;
@@ -100,7 +104,8 @@ export interface DurationObject {
  *
  * If the input is not a valid `Duration.Input`, it throws an error.
  *
- * @example
+ * **Example** (Decoding duration inputs)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -110,15 +115,15 @@ export interface DurationObject {
  * const duration4 = Duration.fromInputUnsafe([2, 500_000_000]) // 2 seconds and 500ms
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const fromInputUnsafe: (input: Input) => Duration;
 /**
  * Safely decodes a `Input` value into a `Duration`, returning
  * `Option.none()` if decoding fails.
  *
- * **Example**
+ * **Example** (Safely decoding duration inputs)
  *
  * ```ts
  * import { Duration, Option } from "effect"
@@ -135,7 +140,8 @@ export declare const fromInput: (u: Input) => Option.Option<Duration>;
 /**
  * Checks if a value is a Duration.
  *
- * @example
+ * **Example** (Checking for durations)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -143,14 +149,15 @@ export declare const fromInput: (u: Input) => Option.Option<Duration>;
  * console.log(Duration.isDuration(1000)) // false
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 2.0.0
  */
 export declare const isDuration: (u: unknown) => u is Duration;
 /**
  * Checks if a Duration is finite (not infinite).
  *
- * @example
+ * **Example** (Checking finite durations)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -158,14 +165,15 @@ export declare const isDuration: (u: unknown) => u is Duration;
  * console.log(Duration.isFinite(Duration.infinity)) // false
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 2.0.0
  */
 export declare const isFinite: (self: Duration) => boolean;
 /**
  * Checks if a Duration is zero.
  *
- * @example
+ * **Example** (Checking for zero durations)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -173,14 +181,15 @@ export declare const isFinite: (self: Duration) => boolean;
  * console.log(Duration.isZero(Duration.seconds(1))) // false
  * ```
  *
- * @since 3.5.0
  * @category guards
+ * @since 3.5.0
  */
 export declare const isZero: (self: Duration) => boolean;
 /**
  * Returns `true` if the duration is negative (strictly less than zero).
  *
- * @example
+ * **Example** (Checking for negative durations)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -189,14 +198,15 @@ export declare const isZero: (self: Duration) => boolean;
  * console.log(Duration.isNegative(Duration.negativeInfinity)) // true
  * ```
  *
- * @since 4.0.0
  * @category guards
+ * @since 4.0.0
  */
 export declare const isNegative: (self: Duration) => boolean;
 /**
  * Returns `true` if the duration is positive (strictly greater than zero).
  *
- * @example
+ * **Example** (Checking for positive durations)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -205,14 +215,15 @@ export declare const isNegative: (self: Duration) => boolean;
  * console.log(Duration.isPositive(Duration.infinity)) // true
  * ```
  *
- * @since 4.0.0
  * @category guards
+ * @since 4.0.0
  */
 export declare const isPositive: (self: Duration) => boolean;
 /**
  * Returns the absolute value of the duration.
  *
- * @example
+ * **Example** (Taking absolute duration values)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -220,14 +231,15 @@ export declare const isPositive: (self: Duration) => boolean;
  * Duration.abs(Duration.negativeInfinity) === Duration.infinity // true
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export declare const abs: (self: Duration) => Duration;
 /**
  * Negates the duration.
  *
- * @example
+ * **Example** (Negating durations)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -235,56 +247,60 @@ export declare const abs: (self: Duration) => Duration;
  * Duration.negate(Duration.infinity) === Duration.negativeInfinity // true
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export declare const negate: (self: Duration) => Duration;
 /**
  * A Duration representing zero time.
  *
- * @example
+ * **Example** (Using the zero duration)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
  * console.log(Duration.toMillis(Duration.zero)) // 0
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const zero: Duration;
 /**
  * A Duration representing infinite time.
  *
- * @example
+ * **Example** (Using infinite duration)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
  * console.log(Duration.toMillis(Duration.infinity)) // Infinity
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const infinity: Duration;
 /**
  * A Duration representing negative infinite time.
  *
- * @example
+ * **Example** (Using negative infinite duration)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
  * console.log(Duration.toMillis(Duration.negativeInfinity)) // -Infinity
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const negativeInfinity: Duration;
 /**
  * Creates a Duration from nanoseconds.
  *
- * @example
+ * **Example** (Creating durations from nanoseconds)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -292,14 +308,15 @@ export declare const negativeInfinity: Duration;
  * console.log(Duration.toMillis(duration)) // 500
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const nanos: (nanos: bigint) => Duration;
 /**
  * Creates a Duration from microseconds.
  *
- * @example
+ * **Example** (Creating durations from microseconds)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -307,14 +324,15 @@ export declare const nanos: (nanos: bigint) => Duration;
  * console.log(Duration.toMillis(duration)) // 500
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const micros: (micros: bigint) => Duration;
 /**
  * Creates a Duration from milliseconds.
  *
- * @example
+ * **Example** (Creating durations from milliseconds)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -322,14 +340,15 @@ export declare const micros: (micros: bigint) => Duration;
  * console.log(Duration.toMillis(duration)) // 1000
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const millis: (millis: number) => Duration;
 /**
  * Creates a Duration from seconds.
  *
- * @example
+ * **Example** (Creating durations from seconds)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -337,14 +356,15 @@ export declare const millis: (millis: number) => Duration;
  * console.log(Duration.toMillis(duration)) // 30000
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const seconds: (seconds: number) => Duration;
 /**
  * Creates a Duration from minutes.
  *
- * @example
+ * **Example** (Creating durations from minutes)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -352,14 +372,15 @@ export declare const seconds: (seconds: number) => Duration;
  * console.log(Duration.toMillis(duration)) // 300000
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const minutes: (minutes: number) => Duration;
 /**
  * Creates a Duration from hours.
  *
- * @example
+ * **Example** (Creating durations from hours)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -367,14 +388,15 @@ export declare const minutes: (minutes: number) => Duration;
  * console.log(Duration.toMillis(duration)) // 7200000
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const hours: (hours: number) => Duration;
 /**
  * Creates a Duration from days.
  *
- * @example
+ * **Example** (Creating durations from days)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -382,14 +404,15 @@ export declare const hours: (hours: number) => Duration;
  * console.log(Duration.toMillis(duration)) // 86400000
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const days: (days: number) => Duration;
 /**
  * Creates a Duration from weeks.
  *
- * @example
+ * **Example** (Creating durations from weeks)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -397,14 +420,15 @@ export declare const days: (days: number) => Duration;
  * console.log(Duration.toMillis(duration)) // 604800000
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const weeks: (weeks: number) => Duration;
 /**
  * Converts a Duration to milliseconds.
  *
- * @example
+ * **Example** (Converting durations to milliseconds)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -412,14 +436,15 @@ export declare const weeks: (weeks: number) => Duration;
  * console.log(Duration.toMillis(Duration.minutes(2))) // 120000
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare const toMillis: (self: Input) => number;
 /**
  * Converts a Duration to seconds.
  *
- * @example
+ * **Example** (Converting durations to seconds)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -427,14 +452,15 @@ export declare const toMillis: (self: Input) => number;
  * console.log(Duration.toSeconds(Duration.minutes(2))) // 120
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare const toSeconds: (self: Input) => number;
 /**
  * Converts a Duration to minutes.
  *
- * @example
+ * **Example** (Converting durations to minutes)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -442,14 +468,15 @@ export declare const toSeconds: (self: Input) => number;
  * console.log(Duration.toMinutes(Duration.hours(1))) // 60
  * ```
  *
- * @since 3.8.0
  * @category getters
+ * @since 3.8.0
  */
 export declare const toMinutes: (self: Input) => number;
 /**
  * Converts a Duration to hours.
  *
- * @example
+ * **Example** (Converting durations to hours)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -457,14 +484,15 @@ export declare const toMinutes: (self: Input) => number;
  * console.log(Duration.toHours(Duration.days(1))) // 24
  * ```
  *
- * @since 3.8.0
  * @category getters
+ * @since 3.8.0
  */
 export declare const toHours: (self: Input) => number;
 /**
  * Converts a Duration to days.
  *
- * @example
+ * **Example** (Converting durations to days)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -472,14 +500,15 @@ export declare const toHours: (self: Input) => number;
  * console.log(Duration.toDays(Duration.weeks(1))) // 7
  * ```
  *
- * @since 3.8.0
  * @category getters
+ * @since 3.8.0
  */
 export declare const toDays: (self: Input) => number;
 /**
  * Converts a Duration to weeks.
  *
- * @example
+ * **Example** (Converting durations to weeks)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -487,8 +516,8 @@ export declare const toDays: (self: Input) => number;
  * console.log(Duration.toWeeks(Duration.days(7))) // 1
  * ```
  *
- * @since 3.8.0
  * @category getters
+ * @since 3.8.0
  */
 export declare const toWeeks: (self: Input) => number;
 /**
@@ -496,7 +525,8 @@ export declare const toWeeks: (self: Input) => number;
  *
  * If the duration is infinite, it throws an error.
  *
- * @example
+ * **Example** (Reading nanoseconds unsafely)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -504,16 +534,12 @@ export declare const toWeeks: (self: Input) => number;
  * const nanos = Duration.toNanosUnsafe(duration)
  * console.log(nanos) // 2000000000n
  *
- * // This will throw an error
- * try {
- *   Duration.toNanosUnsafe(Duration.infinity)
- * } catch (error) {
- *   console.log((error as Error).message) // "Cannot convert infinite duration to nanos"
- * }
+ * // Duration.toNanosUnsafe(Duration.infinity)
+ * // throws Error: "Cannot convert infinite duration to nanos"
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare const toNanosUnsafe: (input: Input) => bigint;
 /**
@@ -521,7 +547,7 @@ export declare const toNanosUnsafe: (input: Input) => bigint;
  *
  * If the duration is infinite, returns `Option.none()`.
  *
- * **Example**
+ * **Example** (Safely reading nanoseconds)
  *
  * ```ts
  * import { Duration, Option } from "effect"
@@ -539,7 +565,8 @@ export declare const toNanos: (self: Input) => Option.Option<bigint>;
 /**
  * Converts a Duration to high-resolution time format [seconds, nanoseconds].
  *
- * @example
+ * **Example** (Converting durations to high-resolution time)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -548,14 +575,19 @@ export declare const toNanos: (self: Input) => Option.Option<bigint>;
  * console.log(hrtime) // [1, 500000000]
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare const toHrTime: (input: Input) => [seconds: number, nanos: number];
 /**
- * Pattern matches on a Duration, providing different handlers for millis and nanos.
+ * Pattern matches on the representation of a `Duration`.
+ *
+ * Provide handlers for millisecond-backed values, nanosecond-backed values,
+ * and positive infinity. Use `onNegativeInfinity` to handle negative infinity
+ * separately; otherwise negative infinity is handled by `onInfinity`.
+ *
+ * **Example** (Pattern matching on duration representations)
  *
- * @example
  * ```ts
  * import { Duration } from "effect"
  *
@@ -567,14 +599,19 @@ export declare const toHrTime: (input: Input) => [seconds: number, nanos: number
  * console.log(result) // "5000 milliseconds"
  * ```
  *
- * @since 2.0.0
  * @category pattern matching
+ * @since 2.0.0
  */
 export declare const match: {
     /**
-     * Pattern matches on a Duration, providing different handlers for millis and nanos.
+     * Pattern matches on the representation of a `Duration`.
+     *
+     * Provide handlers for millisecond-backed values, nanosecond-backed values,
+     * and positive infinity. Use `onNegativeInfinity` to handle negative infinity
+     * separately; otherwise negative infinity is handled by `onInfinity`.
+     *
+     * **Example** (Pattern matching on duration representations)
      *
-     * @example
      * ```ts
      * import { Duration } from "effect"
      *
@@ -586,8 +623,8 @@ export declare const match: {
      * console.log(result) // "5000 milliseconds"
      * ```
      *
-     * @since 2.0.0
      * @category pattern matching
+     * @since 2.0.0
      */
     <A, B, C, D = C>(options: {
         readonly onMillis: (millis: number) => A;
@@ -596,9 +633,14 @@ export declare const match: {
         readonly onNegativeInfinity?: () => D;
     }): (self: Duration) => A | B | C | D;
     /**
-     * Pattern matches on a Duration, providing different handlers for millis and nanos.
+     * Pattern matches on the representation of a `Duration`.
+     *
+     * Provide handlers for millisecond-backed values, nanosecond-backed values,
+     * and positive infinity. Use `onNegativeInfinity` to handle negative infinity
+     * separately; otherwise negative infinity is handled by `onInfinity`.
+     *
+     * **Example** (Pattern matching on duration representations)
      *
-     * @example
      * ```ts
      * import { Duration } from "effect"
      *
@@ -610,8 +652,8 @@ export declare const match: {
      * console.log(result) // "5000 milliseconds"
      * ```
      *
-     * @since 2.0.0
      * @category pattern matching
+     * @since 2.0.0
      */
     <A, B, C, D = C>(self: Duration, options: {
         readonly onMillis: (millis: number) => A;
@@ -623,7 +665,8 @@ export declare const match: {
 /**
  * Pattern matches on two `Duration`s, providing handlers that receive both values.
  *
- * @example
+ * **Example** (Pattern matching on duration pairs)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -635,14 +678,15 @@ export declare const match: {
  * console.log(sum) // 5000
  * ```
  *
- * @since 2.0.0
  * @category pattern matching
+ * @since 2.0.0
  */
 export declare const matchPair: {
     /**
      * Pattern matches on two `Duration`s, providing handlers that receive both values.
      *
-     * @example
+     * **Example** (Pattern matching on duration pairs)
+     *
      * ```ts
      * import { Duration } from "effect"
      *
@@ -654,8 +698,8 @@ export declare const matchPair: {
      * console.log(sum) // 5000
      * ```
      *
-     * @since 2.0.0
      * @category pattern matching
+     * @since 2.0.0
      */
     <A, B, C>(that: Duration, options: {
         readonly onMillis: (self: number, that: number) => A;
@@ -665,7 +709,8 @@ export declare const matchPair: {
     /**
      * Pattern matches on two `Duration`s, providing handlers that receive both values.
      *
-     * @example
+     * **Example** (Pattern matching on duration pairs)
+     *
      * ```ts
      * import { Duration } from "effect"
      *
@@ -677,8 +722,8 @@ export declare const matchPair: {
      * console.log(sum) // 5000
      * ```
      *
-     * @since 2.0.0
      * @category pattern matching
+     * @since 2.0.0
      */
     <A, B, C>(self: Duration, that: Duration, options: {
         readonly onMillis: (self: number, that: number) => A;
@@ -691,7 +736,8 @@ export declare const matchPair: {
  *
  * `NegativeInfinity` < any finite value < `Infinity`.
  *
- * @example
+ * **Example** (Sorting durations)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -709,9 +755,11 @@ export declare const matchPair: {
  */
 export declare const Order: order.Order<Duration>;
 /**
- * Checks if a `Duration` is between a `minimum` and `maximum` value.
+ * Returns `true` if a `Duration` is greater than or equal to `minimum` and
+ * less than or equal to `maximum`, according to `Duration.Order`.
+ *
+ * **Example** (Checking duration ranges)
  *
- * @example
  * ```ts
  * import { Duration } from "effect"
  *
@@ -727,9 +775,11 @@ export declare const Order: order.Order<Duration>;
  */
 export declare const between: {
     /**
-     * Checks if a `Duration` is between a `minimum` and `maximum` value.
+     * Returns `true` if a `Duration` is greater than or equal to `minimum` and
+     * less than or equal to `maximum`, according to `Duration.Order`.
+     *
+     * **Example** (Checking duration ranges)
      *
-     * @example
      * ```ts
      * import { Duration } from "effect"
      *
@@ -748,9 +798,11 @@ export declare const between: {
         maximum: Duration;
     }): (self: Duration) => boolean;
     /**
-     * Checks if a `Duration` is between a `minimum` and `maximum` value.
+     * Returns `true` if a `Duration` is greater than or equal to `minimum` and
+     * less than or equal to `maximum`, according to `Duration.Order`.
+     *
+     * **Example** (Checking duration ranges)
      *
-     * @example
      * ```ts
      * import { Duration } from "effect"
      *
@@ -772,7 +824,8 @@ export declare const between: {
 /**
  * Equivalence instance for `Duration`, allowing equality comparisons.
  *
- * @example
+ * **Example** (Comparing durations for equivalence)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -787,7 +840,8 @@ export declare const Equivalence: Equ.Equivalence<Duration>;
 /**
  * Returns the smaller of two Durations.
  *
- * @example
+ * **Example** (Selecting the shorter duration)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -795,14 +849,15 @@ export declare const Equivalence: Equ.Equivalence<Duration>;
  * console.log(Duration.toSeconds(shorter)) // 3
  * ```
  *
- * @since 2.0.0
  * @category order
+ * @since 2.0.0
  */
 export declare const min: {
     /**
      * Returns the smaller of two Durations.
      *
-     * @example
+     * **Example** (Selecting the shorter duration)
+     *
      * ```ts
      * import { Duration } from "effect"
      *
@@ -810,14 +865,15 @@ export declare const min: {
      * console.log(Duration.toSeconds(shorter)) // 3
      * ```
      *
-     * @since 2.0.0
      * @category order
+     * @since 2.0.0
      */
     (that: Duration): (self: Duration) => Duration;
     /**
      * Returns the smaller of two Durations.
      *
-     * @example
+     * **Example** (Selecting the shorter duration)
+     *
      * ```ts
      * import { Duration } from "effect"
      *
@@ -825,15 +881,16 @@ export declare const min: {
      * console.log(Duration.toSeconds(shorter)) // 3
      * ```
      *
-     * @since 2.0.0
      * @category order
+     * @since 2.0.0
      */
     (self: Duration, that: Duration): Duration;
 };
 /**
  * Returns the larger of two Durations.
  *
- * @example
+ * **Example** (Selecting the longer duration)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -841,14 +898,15 @@ export declare const min: {
  * console.log(Duration.toSeconds(longer)) // 5
  * ```
  *
- * @since 2.0.0
  * @category order
+ * @since 2.0.0
  */
 export declare const max: {
     /**
      * Returns the larger of two Durations.
      *
-     * @example
+     * **Example** (Selecting the longer duration)
+     *
      * ```ts
      * import { Duration } from "effect"
      *
@@ -856,14 +914,15 @@ export declare const max: {
      * console.log(Duration.toSeconds(longer)) // 5
      * ```
      *
-     * @since 2.0.0
      * @category order
+     * @since 2.0.0
      */
     (that: Duration): (self: Duration) => Duration;
     /**
      * Returns the larger of two Durations.
      *
-     * @example
+     * **Example** (Selecting the longer duration)
+     *
      * ```ts
      * import { Duration } from "effect"
      *
@@ -871,15 +930,16 @@ export declare const max: {
      * console.log(Duration.toSeconds(longer)) // 5
      * ```
      *
-     * @since 2.0.0
      * @category order
+     * @since 2.0.0
      */
     (self: Duration, that: Duration): Duration;
 };
 /**
  * Clamps a Duration between a minimum and maximum value.
  *
- * @example
+ * **Example** (Clamping durations to a range)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -890,14 +950,15 @@ export declare const max: {
  * console.log(Duration.toSeconds(clamped)) // 5
  * ```
  *
- * @since 2.0.0
  * @category order
+ * @since 2.0.0
  */
 export declare const clamp: {
     /**
      * Clamps a Duration between a minimum and maximum value.
      *
-     * @example
+     * **Example** (Clamping durations to a range)
+     *
      * ```ts
      * import { Duration } from "effect"
      *
@@ -908,8 +969,8 @@ export declare const clamp: {
      * console.log(Duration.toSeconds(clamped)) // 5
      * ```
      *
-     * @since 2.0.0
      * @category order
+     * @since 2.0.0
      */
     (options: {
         minimum: Duration;
@@ -918,7 +979,8 @@ export declare const clamp: {
     /**
      * Clamps a Duration between a minimum and maximum value.
      *
-     * @example
+     * **Example** (Clamping durations to a range)
+     *
      * ```ts
      * import { Duration } from "effect"
      *
@@ -929,8 +991,8 @@ export declare const clamp: {
      * console.log(Duration.toSeconds(clamped)) // 5
      * ```
      *
-     * @since 2.0.0
      * @category order
+     * @since 2.0.0
      */
     (self: Duration, options: {
         minimum: Duration;
@@ -938,9 +1000,13 @@ export declare const clamp: {
     }): Duration;
 };
 /**
- * Divides a Duration by a number, returning `Option.none()` if division is invalid.
+ * Safely divides a `Duration` by a finite, non-zero number.
  *
- * **Example**
+ * Returns `Option.none()` for zero, negative zero, or non-finite divisors. For
+ * nanosecond-backed durations, also returns `Option.none()` when the divisor
+ * cannot be converted to a `bigint`, such as a fractional divisor.
+ *
+ * **Example** (Safely dividing durations)
  *
  * ```ts
  * import { Duration, Option } from "effect"
@@ -951,14 +1017,18 @@ export declare const clamp: {
  * Duration.divide(Duration.seconds(10), 0) // None
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export declare const divide: {
     /**
-     * Divides a Duration by a number, returning `Option.none()` if division is invalid.
+     * Safely divides a `Duration` by a finite, non-zero number.
+     *
+     * Returns `Option.none()` for zero, negative zero, or non-finite divisors. For
+     * nanosecond-backed durations, also returns `Option.none()` when the divisor
+     * cannot be converted to a `bigint`, such as a fractional divisor.
      *
-     * **Example**
+     * **Example** (Safely dividing durations)
      *
      * ```ts
      * import { Duration, Option } from "effect"
@@ -969,14 +1039,18 @@ export declare const divide: {
      * Duration.divide(Duration.seconds(10), 0) // None
      * ```
      *
-     * @since 4.0.0
      * @category math
+     * @since 4.0.0
      */
     (by: number): (self: Duration) => Option.Option<Duration>;
     /**
-     * Divides a Duration by a number, returning `Option.none()` if division is invalid.
+     * Safely divides a `Duration` by a finite, non-zero number.
      *
-     * **Example**
+     * Returns `Option.none()` for zero, negative zero, or non-finite divisors. For
+     * nanosecond-backed durations, also returns `Option.none()` when the divisor
+     * cannot be converted to a `bigint`, such as a fractional divisor.
+     *
+     * **Example** (Safely dividing durations)
      *
      * ```ts
      * import { Duration, Option } from "effect"
@@ -987,15 +1061,23 @@ export declare const divide: {
      * Duration.divide(Duration.seconds(10), 0) // None
      * ```
      *
-     * @since 4.0.0
      * @category math
+     * @since 4.0.0
      */
     (self: Duration, by: number): Option.Option<Duration>;
 };
 /**
- * Divides a Duration by a number, potentially returning infinity or zero.
+ * Divides a `Duration` by a number using fallback rules instead of returning
+ * an `Option`.
+ *
+ * Non-finite divisors return `Duration.zero`. Division by positive or negative
+ * zero can produce signed infinity for non-zero finite durations, while zero
+ * or infinite durations divided by zero produce `Duration.zero`.
+ * Nanosecond-backed durations return `Duration.zero` when the divisor cannot
+ * be converted to a `bigint`.
+ *
+ * **Example** (Dividing durations unsafely)
  *
- * @example
  * ```ts
  * import { Duration } from "effect"
  *
@@ -1006,14 +1088,22 @@ export declare const divide: {
  * console.log(Duration.toMillis(infinite)) // Infinity
  * ```
  *
- * @since 2.4.19
  * @category math
+ * @since 2.4.19
  */
 export declare const divideUnsafe: {
     /**
-     * Divides a Duration by a number, potentially returning infinity or zero.
+     * Divides a `Duration` by a number using fallback rules instead of returning
+     * an `Option`.
+     *
+     * Non-finite divisors return `Duration.zero`. Division by positive or negative
+     * zero can produce signed infinity for non-zero finite durations, while zero
+     * or infinite durations divided by zero produce `Duration.zero`.
+     * Nanosecond-backed durations return `Duration.zero` when the divisor cannot
+     * be converted to a `bigint`.
+     *
+     * **Example** (Dividing durations unsafely)
      *
-     * @example
      * ```ts
      * import { Duration } from "effect"
      *
@@ -1024,14 +1114,22 @@ export declare const divideUnsafe: {
      * console.log(Duration.toMillis(infinite)) // Infinity
      * ```
      *
-     * @since 2.4.19
      * @category math
+     * @since 2.4.19
      */
     (by: number): (self: Duration) => Duration;
     /**
-     * Divides a Duration by a number, potentially returning infinity or zero.
+     * Divides a `Duration` by a number using fallback rules instead of returning
+     * an `Option`.
+     *
+     * Non-finite divisors return `Duration.zero`. Division by positive or negative
+     * zero can produce signed infinity for non-zero finite durations, while zero
+     * or infinite durations divided by zero produce `Duration.zero`.
+     * Nanosecond-backed durations return `Duration.zero` when the divisor cannot
+     * be converted to a `bigint`.
+     *
+     * **Example** (Dividing durations unsafely)
      *
-     * @example
      * ```ts
      * import { Duration } from "effect"
      *
@@ -1042,15 +1140,21 @@ export declare const divideUnsafe: {
      * console.log(Duration.toMillis(infinite)) // Infinity
      * ```
      *
-     * @since 2.4.19
      * @category math
+     * @since 2.4.19
      */
     (self: Duration, by: number): Duration;
 };
 /**
- * Multiplies a Duration by a number.
+ * Multiplies a `Duration` by a number.
+ *
+ * For nanosecond-backed durations, the multiplier must be convertible to a
+ * `bigint`; fractional or non-finite multipliers can throw. Infinite
+ * durations return positive infinity, negative infinity, or zero depending on
+ * the multiplier sign.
+ *
+ * **Example** (Multiplying durations)
  *
- * @example
  * ```ts
  * import { Duration } from "effect"
  *
@@ -1058,14 +1162,20 @@ export declare const divideUnsafe: {
  * console.log(Duration.toSeconds(doubled)) // 10
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export declare const times: {
     /**
-     * Multiplies a Duration by a number.
+     * Multiplies a `Duration` by a number.
+     *
+     * For nanosecond-backed durations, the multiplier must be convertible to a
+     * `bigint`; fractional or non-finite multipliers can throw. Infinite
+     * durations return positive infinity, negative infinity, or zero depending on
+     * the multiplier sign.
+     *
+     * **Example** (Multiplying durations)
      *
-     * @example
      * ```ts
      * import { Duration } from "effect"
      *
@@ -1073,14 +1183,20 @@ export declare const times: {
      * console.log(Duration.toSeconds(doubled)) // 10
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (times: number): (self: Duration) => Duration;
     /**
-     * Multiplies a Duration by a number.
+     * Multiplies a `Duration` by a number.
+     *
+     * For nanosecond-backed durations, the multiplier must be convertible to a
+     * `bigint`; fractional or non-finite multipliers can throw. Infinite
+     * durations return positive infinity, negative infinity, or zero depending on
+     * the multiplier sign.
+     *
+     * **Example** (Multiplying durations)
      *
-     * @example
      * ```ts
      * import { Duration } from "effect"
      *
@@ -1088,8 +1204,8 @@ export declare const times: {
      * console.log(Duration.toSeconds(doubled)) // 10
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (self: Duration, times: number): Duration;
 };
@@ -1106,7 +1222,8 @@ export declare const times: {
  * - finite - infinity = negativeInfinity
  * - finite - negativeInfinity = infinity
  *
- * @example
+ * **Example** (Subtracting durations)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -1114,8 +1231,8 @@ export declare const times: {
  * console.log(Duration.toSeconds(result)) // 7
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export declare const subtract: {
     /**
@@ -1131,7 +1248,8 @@ export declare const subtract: {
      * - finite - infinity = negativeInfinity
      * - finite - negativeInfinity = infinity
      *
-     * @example
+     * **Example** (Subtracting durations)
+     *
      * ```ts
      * import { Duration } from "effect"
      *
@@ -1139,8 +1257,8 @@ export declare const subtract: {
      * console.log(Duration.toSeconds(result)) // 7
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (that: Duration): (self: Duration) => Duration;
     /**
@@ -1156,7 +1274,8 @@ export declare const subtract: {
      * - finite - infinity = negativeInfinity
      * - finite - negativeInfinity = infinity
      *
-     * @example
+     * **Example** (Subtracting durations)
+     *
      * ```ts
      * import { Duration } from "effect"
      *
@@ -1164,8 +1283,8 @@ export declare const subtract: {
      * console.log(Duration.toSeconds(result)) // 7
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (self: Duration, that: Duration): Duration;
 };
@@ -1179,7 +1298,8 @@ export declare const subtract: {
  * - negativeInfinity + negativeInfinity = negativeInfinity
  * - negativeInfinity + finite = negativeInfinity
  *
- * @example
+ * **Example** (Adding durations)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -1187,8 +1307,8 @@ export declare const subtract: {
  * console.log(Duration.toSeconds(total)) // 8
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export declare const sum: {
     /**
@@ -1201,7 +1321,8 @@ export declare const sum: {
      * - negativeInfinity + negativeInfinity = negativeInfinity
      * - negativeInfinity + finite = negativeInfinity
      *
-     * @example
+     * **Example** (Adding durations)
+     *
      * ```ts
      * import { Duration } from "effect"
      *
@@ -1209,8 +1330,8 @@ export declare const sum: {
      * console.log(Duration.toSeconds(total)) // 8
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (that: Duration): (self: Duration) => Duration;
     /**
@@ -1223,7 +1344,8 @@ export declare const sum: {
      * - negativeInfinity + negativeInfinity = negativeInfinity
      * - negativeInfinity + finite = negativeInfinity
      *
-     * @example
+     * **Example** (Adding durations)
+     *
      * ```ts
      * import { Duration } from "effect"
      *
@@ -1231,15 +1353,16 @@ export declare const sum: {
      * console.log(Duration.toSeconds(total)) // 8
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (self: Duration, that: Duration): Duration;
 };
 /**
  * Checks if the first Duration is less than the second.
  *
- * @example
+ * **Example** (Comparing durations with less than)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -1247,14 +1370,15 @@ export declare const sum: {
  * console.log(isLess) // true
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export declare const isLessThan: {
     /**
      * Checks if the first Duration is less than the second.
      *
-     * @example
+     * **Example** (Comparing durations with less than)
+     *
      * ```ts
      * import { Duration } from "effect"
      *
@@ -1262,14 +1386,15 @@ export declare const isLessThan: {
      * console.log(isLess) // true
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (that: Duration): (self: Duration) => boolean;
     /**
      * Checks if the first Duration is less than the second.
      *
-     * @example
+     * **Example** (Comparing durations with less than)
+     *
      * ```ts
      * import { Duration } from "effect"
      *
@@ -1277,15 +1402,16 @@ export declare const isLessThan: {
      * console.log(isLess) // true
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (self: Duration, that: Duration): boolean;
 };
 /**
  * Checks if the first Duration is less than or equal to the second.
  *
- * @example
+ * **Example** (Comparing durations with less than or equal)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -1296,14 +1422,15 @@ export declare const isLessThan: {
  * console.log(isLessOrEqual) // true
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export declare const isLessThanOrEqualTo: {
     /**
      * Checks if the first Duration is less than or equal to the second.
      *
-     * @example
+     * **Example** (Comparing durations with less than or equal)
+     *
      * ```ts
      * import { Duration } from "effect"
      *
@@ -1314,14 +1441,15 @@ export declare const isLessThanOrEqualTo: {
      * console.log(isLessOrEqual) // true
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (that: Duration): (self: Duration) => boolean;
     /**
      * Checks if the first Duration is less than or equal to the second.
      *
-     * @example
+     * **Example** (Comparing durations with less than or equal)
+     *
      * ```ts
      * import { Duration } from "effect"
      *
@@ -1332,15 +1460,16 @@ export declare const isLessThanOrEqualTo: {
      * console.log(isLessOrEqual) // true
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (self: Duration, that: Duration): boolean;
 };
 /**
  * Checks if the first Duration is greater than the second.
  *
- * @example
+ * **Example** (Comparing durations with greater than)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -1348,14 +1477,15 @@ export declare const isLessThanOrEqualTo: {
  * console.log(isGreater) // true
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export declare const isGreaterThan: {
     /**
      * Checks if the first Duration is greater than the second.
      *
-     * @example
+     * **Example** (Comparing durations with greater than)
+     *
      * ```ts
      * import { Duration } from "effect"
      *
@@ -1363,14 +1493,15 @@ export declare const isGreaterThan: {
      * console.log(isGreater) // true
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (that: Duration): (self: Duration) => boolean;
     /**
      * Checks if the first Duration is greater than the second.
      *
-     * @example
+     * **Example** (Comparing durations with greater than)
+     *
      * ```ts
      * import { Duration } from "effect"
      *
@@ -1378,15 +1509,16 @@ export declare const isGreaterThan: {
      * console.log(isGreater) // true
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (self: Duration, that: Duration): boolean;
 };
 /**
  * Checks if the first Duration is greater than or equal to the second.
  *
- * @example
+ * **Example** (Comparing durations with greater than or equal)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -1397,14 +1529,15 @@ export declare const isGreaterThan: {
  * console.log(isGreaterOrEqual) // true
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export declare const isGreaterThanOrEqualTo: {
     /**
      * Checks if the first Duration is greater than or equal to the second.
      *
-     * @example
+     * **Example** (Comparing durations with greater than or equal)
+     *
      * ```ts
      * import { Duration } from "effect"
      *
@@ -1415,14 +1548,15 @@ export declare const isGreaterThanOrEqualTo: {
      * console.log(isGreaterOrEqual) // true
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (that: Duration): (self: Duration) => boolean;
     /**
      * Checks if the first Duration is greater than or equal to the second.
      *
-     * @example
+     * **Example** (Comparing durations with greater than or equal)
+     *
      * ```ts
      * import { Duration } from "effect"
      *
@@ -1433,15 +1567,16 @@ export declare const isGreaterThanOrEqualTo: {
      * console.log(isGreaterOrEqual) // true
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (self: Duration, that: Duration): boolean;
 };
 /**
  * Checks if two Durations are equal.
  *
- * @example
+ * **Example** (Checking duration equality)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -1449,14 +1584,15 @@ export declare const isGreaterThanOrEqualTo: {
  * console.log(isEqual) // true
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export declare const equals: {
     /**
      * Checks if two Durations are equal.
      *
-     * @example
+     * **Example** (Checking duration equality)
+     *
      * ```ts
      * import { Duration } from "effect"
      *
@@ -1464,14 +1600,15 @@ export declare const equals: {
      * console.log(isEqual) // true
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (that: Duration): (self: Duration) => boolean;
     /**
      * Checks if two Durations are equal.
      *
-     * @example
+     * **Example** (Checking duration equality)
+     *
      * ```ts
      * import { Duration } from "effect"
      *
@@ -1479,15 +1616,20 @@ export declare const equals: {
      * console.log(isEqual) // true
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (self: Duration, that: Duration): boolean;
 };
 /**
- * Converts a `Duration` to its parts.
+ * Decomposes a `Duration` into normalized signed components.
+ *
+ * Finite durations are returned as `{ days, hours, minutes, seconds, millis,
+ * nanos }`. Infinite durations return every component as `Infinity` or
+ * `-Infinity`.
+ *
+ * **Example** (Decomposing durations into parts)
  *
- * @example
  * ```ts
  * import { Duration } from "effect"
  *
@@ -1523,8 +1665,8 @@ export declare const equals: {
  * // }
  * ```
  *
- * @since 3.8.0
  * @category conversions
+ * @since 3.8.0
  */
 export declare const parts: (self: Duration) => {
     days: number;
@@ -1537,15 +1679,17 @@ export declare const parts: (self: Duration) => {
 /**
  * Converts a `Duration` to a human readable string.
  *
- * @since 2.0.0
- * @category conversions
- * @example
+ * **Example** (Formatting durations)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
  * Duration.format(Duration.millis(1000)) // "1s"
  * Duration.format(Duration.millis(1001)) // "1s 1ms"
  * ```
+ *
+ * @category conversions
+ * @since 2.0.0
  */
 export declare const format: (self: Duration) => string;
 /**