effect 4.0.0-beta.65 → 4.0.0-beta.67

package/dist/Duration.js

@@ -36,7 +36,8 @@ const DURATION_REGEXP = /^(-?\d+(?:\.\d+)?)\s+(nanos?|micros?|millis?|seconds?|m
  *
  * If the input is not a valid `Duration.Input`, it throws an error.
  *
- * @example
+ * **Example** (Decoding duration inputs)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -46,8 +47,8 @@ const DURATION_REGEXP = /^(-?\d+(?:\.\d+)?)\s+(nanos?|micros?|millis?|seconds?|m
  * const duration4 = Duration.fromInputUnsafe([2, 500_000_000]) // 2 seconds and 500ms
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromInputUnsafe = input => {
   switch (typeof input) {
@@ -139,7 +140,7 @@ const invalid = input => {
  * 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"
@@ -247,7 +248,8 @@ const make = input => {
 /**
  * Checks if a value is a Duration.
  *
- * @example
+ * **Example** (Checking for durations)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -255,14 +257,15 @@ const make = input => {
  * console.log(Duration.isDuration(1000)) // false
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 2.0.0
  */
 export const isDuration = u => hasProperty(u, TypeId);
 /**
  * Checks if a Duration is finite (not infinite).
  *
- * @example
+ * **Example** (Checking finite durations)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -270,14 +273,15 @@ export const isDuration = u => hasProperty(u, TypeId);
  * console.log(Duration.isFinite(Duration.infinity)) // false
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 2.0.0
  */
 export const isFinite = self => self.value._tag !== "Infinity" && self.value._tag !== "NegativeInfinity";
 /**
  * Checks if a Duration is zero.
  *
- * @example
+ * **Example** (Checking for zero durations)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -285,8 +289,8 @@ export const isFinite = self => self.value._tag !== "Infinity" && self.value._ta
  * console.log(Duration.isZero(Duration.seconds(1))) // false
  * ```
  *
- * @since 3.5.0
  * @category guards
+ * @since 3.5.0
  */
 export const isZero = self => {
   switch (self.value._tag) {
@@ -302,7 +306,8 @@ export const isZero = self => {
 /**
  * Returns `true` if the duration is negative (strictly less than zero).
  *
- * @example
+ * **Example** (Checking for negative durations)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -311,8 +316,8 @@ export const isZero = self => {
  * console.log(Duration.isNegative(Duration.negativeInfinity)) // true
  * ```
  *
- * @since 4.0.0
  * @category guards
+ * @since 4.0.0
  */
 export const isNegative = self => {
   switch (self.value._tag) {
@@ -329,7 +334,8 @@ export const isNegative = self => {
 /**
  * Returns `true` if the duration is positive (strictly greater than zero).
  *
- * @example
+ * **Example** (Checking for positive durations)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -338,8 +344,8 @@ export const isNegative = self => {
  * console.log(Duration.isPositive(Duration.infinity)) // true
  * ```
  *
- * @since 4.0.0
  * @category guards
+ * @since 4.0.0
  */
 export const isPositive = self => {
   switch (self.value._tag) {
@@ -356,7 +362,8 @@ export const isPositive = self => {
 /**
  * Returns the absolute value of the duration.
  *
- * @example
+ * **Example** (Taking absolute duration values)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -364,8 +371,8 @@ export const isPositive = self => {
  * Duration.abs(Duration.negativeInfinity) === Duration.infinity // true
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export const abs = self => {
   switch (self.value._tag) {
@@ -381,7 +388,8 @@ export const abs = self => {
 /**
  * Negates the duration.
  *
- * @example
+ * **Example** (Negating durations)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -389,8 +397,8 @@ export const abs = self => {
  * Duration.negate(Duration.infinity) === Duration.negativeInfinity // true
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export const negate = self => {
   switch (self.value._tag) {
@@ -407,49 +415,53 @@ export const negate = self => {
 /**
  * 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 const zero = /*#__PURE__*/make(0);
 /**
  * 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 const infinity = /*#__PURE__*/make(Infinity);
 /**
  * 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 const negativeInfinity = /*#__PURE__*/make(-Infinity);
 /**
  * Creates a Duration from nanoseconds.
  *
- * @example
+ * **Example** (Creating durations from nanoseconds)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -457,14 +469,15 @@ export const negativeInfinity = /*#__PURE__*/make(-Infinity);
  * console.log(Duration.toMillis(duration)) // 500
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const nanos = nanos => make(nanos);
 /**
  * Creates a Duration from microseconds.
  *
- * @example
+ * **Example** (Creating durations from microseconds)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -472,14 +485,15 @@ export const nanos = nanos => make(nanos);
  * console.log(Duration.toMillis(duration)) // 500
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const micros = micros => make(micros * bigint1e3);
 /**
  * Creates a Duration from milliseconds.
  *
- * @example
+ * **Example** (Creating durations from milliseconds)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -487,14 +501,15 @@ export const micros = micros => make(micros * bigint1e3);
  * console.log(Duration.toMillis(duration)) // 1000
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const millis = millis => make(millis);
 /**
  * Creates a Duration from seconds.
  *
- * @example
+ * **Example** (Creating durations from seconds)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -502,14 +517,15 @@ export const millis = millis => make(millis);
  * console.log(Duration.toMillis(duration)) // 30000
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const seconds = seconds => make(seconds * 1000);
 /**
  * Creates a Duration from minutes.
  *
- * @example
+ * **Example** (Creating durations from minutes)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -517,14 +533,15 @@ export const seconds = seconds => make(seconds * 1000);
  * console.log(Duration.toMillis(duration)) // 300000
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const minutes = minutes => make(minutes * 60_000);
 /**
  * Creates a Duration from hours.
  *
- * @example
+ * **Example** (Creating durations from hours)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -532,14 +549,15 @@ export const minutes = minutes => make(minutes * 60_000);
  * console.log(Duration.toMillis(duration)) // 7200000
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const hours = hours => make(hours * 3_600_000);
 /**
  * Creates a Duration from days.
  *
- * @example
+ * **Example** (Creating durations from days)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -547,14 +565,15 @@ export const hours = hours => make(hours * 3_600_000);
  * console.log(Duration.toMillis(duration)) // 86400000
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const days = days => make(days * 86_400_000);
 /**
  * Creates a Duration from weeks.
  *
- * @example
+ * **Example** (Creating durations from weeks)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -562,14 +581,15 @@ export const days = days => make(days * 86_400_000);
  * console.log(Duration.toMillis(duration)) // 604800000
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const weeks = weeks => make(weeks * 604_800_000);
 /**
  * Converts a Duration to milliseconds.
  *
- * @example
+ * **Example** (Converting durations to milliseconds)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -577,8 +597,8 @@ export const weeks = weeks => make(weeks * 604_800_000);
  * console.log(Duration.toMillis(Duration.minutes(2))) // 120000
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const toMillis = self => match(fromInputUnsafe(self), {
   onMillis: identity,
@@ -589,7 +609,8 @@ export const toMillis = self => match(fromInputUnsafe(self), {
 /**
  * Converts a Duration to seconds.
  *
- * @example
+ * **Example** (Converting durations to seconds)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -597,8 +618,8 @@ export const toMillis = self => match(fromInputUnsafe(self), {
  * console.log(Duration.toSeconds(Duration.minutes(2))) // 120
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const toSeconds = self => match(fromInputUnsafe(self), {
   onMillis: millis => millis / 1_000,
@@ -609,7 +630,8 @@ export const toSeconds = self => match(fromInputUnsafe(self), {
 /**
  * Converts a Duration to minutes.
  *
- * @example
+ * **Example** (Converting durations to minutes)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -617,8 +639,8 @@ export const toSeconds = self => match(fromInputUnsafe(self), {
  * console.log(Duration.toMinutes(Duration.hours(1))) // 60
  * ```
  *
- * @since 3.8.0
  * @category getters
+ * @since 3.8.0
  */
 export const toMinutes = self => match(fromInputUnsafe(self), {
   onMillis: millis => millis / 60_000,
@@ -629,7 +651,8 @@ export const toMinutes = self => match(fromInputUnsafe(self), {
 /**
  * Converts a Duration to hours.
  *
- * @example
+ * **Example** (Converting durations to hours)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -637,8 +660,8 @@ export const toMinutes = self => match(fromInputUnsafe(self), {
  * console.log(Duration.toHours(Duration.days(1))) // 24
  * ```
  *
- * @since 3.8.0
  * @category getters
+ * @since 3.8.0
  */
 export const toHours = self => match(fromInputUnsafe(self), {
   onMillis: millis => millis / 3_600_000,
@@ -649,7 +672,8 @@ export const toHours = self => match(fromInputUnsafe(self), {
 /**
  * Converts a Duration to days.
  *
- * @example
+ * **Example** (Converting durations to days)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -657,8 +681,8 @@ export const toHours = self => match(fromInputUnsafe(self), {
  * console.log(Duration.toDays(Duration.weeks(1))) // 7
  * ```
  *
- * @since 3.8.0
  * @category getters
+ * @since 3.8.0
  */
 export const toDays = self => match(fromInputUnsafe(self), {
   onMillis: millis => millis / 86_400_000,
@@ -669,7 +693,8 @@ export const toDays = self => match(fromInputUnsafe(self), {
 /**
  * Converts a Duration to weeks.
  *
- * @example
+ * **Example** (Converting durations to weeks)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -677,8 +702,8 @@ export const toDays = self => match(fromInputUnsafe(self), {
  * console.log(Duration.toWeeks(Duration.days(7))) // 1
  * ```
  *
- * @since 3.8.0
  * @category getters
+ * @since 3.8.0
  */
 export const toWeeks = self => match(fromInputUnsafe(self), {
   onMillis: millis => millis / 604_800_000,
@@ -691,7 +716,8 @@ export const toWeeks = self => match(fromInputUnsafe(self), {
  *
  * If the duration is infinite, it throws an error.
  *
- * @example
+ * **Example** (Reading nanoseconds unsafely)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -699,16 +725,12 @@ export const toWeeks = self => match(fromInputUnsafe(self), {
  * 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 const toNanosUnsafe = input => {
   const self = fromInputUnsafe(input);
@@ -727,7 +749,7 @@ export const toNanosUnsafe = input => {
  *
  * If the duration is infinite, returns `Option.none()`.
  *
- * **Example**
+ * **Example** (Safely reading nanoseconds)
  *
  * ```ts
  * import { Duration, Option } from "effect"
@@ -745,7 +767,8 @@ export const toNanos = /*#__PURE__*/Option.liftThrowable(toNanosUnsafe);
 /**
  * Converts a Duration to high-resolution time format [seconds, nanoseconds].
  *
- * @example
+ * **Example** (Converting durations to high-resolution time)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -754,8 +777,8 @@ export const toNanos = /*#__PURE__*/Option.liftThrowable(toNanosUnsafe);
  * console.log(hrtime) // [1, 500000000]
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const toHrTime = input => {
   const self = fromInputUnsafe(input);
@@ -781,9 +804,14 @@ export const toHrTime = input => {
   }
 };
 /**
- * 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"
  *
@@ -795,8 +823,8 @@ export const toHrTime = input => {
  * console.log(result) // "5000 milliseconds"
  * ```
  *
- * @since 2.0.0
  * @category pattern matching
+ * @since 2.0.0
  */
 export const match = /*#__PURE__*/dual(2, (self, options) => {
   switch (self.value._tag) {
@@ -813,7 +841,8 @@ export const match = /*#__PURE__*/dual(2, (self, options) => {
 /**
  * Pattern matches on two `Duration`s, providing handlers that receive both values.
  *
- * @example
+ * **Example** (Pattern matching on duration pairs)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -825,8 +854,8 @@ export const match = /*#__PURE__*/dual(2, (self, options) => {
  * console.log(sum) // 5000
  * ```
  *
- * @since 2.0.0
  * @category pattern matching
+ * @since 2.0.0
  */
 export const matchPair = /*#__PURE__*/dual(3, (self, that, options) => {
   if (self.value._tag === "Infinity" || self.value._tag === "NegativeInfinity" || that.value._tag === "Infinity" || that.value._tag === "NegativeInfinity") return options.onInfinity(self, that);
@@ -841,7 +870,8 @@ export const matchPair = /*#__PURE__*/dual(3, (self, that, options) => {
  *
  * `NegativeInfinity` < any finite value < `Infinity`.
  *
- * @example
+ * **Example** (Sorting durations)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -871,9 +901,11 @@ export const Order = /*#__PURE__*/order.make((self, that) => matchPair(self, tha
   }
 }));
 /**
- * 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"
  *
@@ -891,7 +923,8 @@ export const between = /*#__PURE__*/order.isBetween(Order);
 /**
  * Equivalence instance for `Duration`, allowing equality comparisons.
  *
- * @example
+ * **Example** (Comparing durations for equivalence)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -910,7 +943,8 @@ export const Equivalence = (self, that) => matchPair(self, that, {
 /**
  * Returns the smaller of two Durations.
  *
- * @example
+ * **Example** (Selecting the shorter duration)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -918,14 +952,15 @@ export const Equivalence = (self, that) => matchPair(self, that, {
  * console.log(Duration.toSeconds(shorter)) // 3
  * ```
  *
- * @since 2.0.0
  * @category order
+ * @since 2.0.0
  */
 export const min = /*#__PURE__*/order.min(Order);
 /**
  * Returns the larger of two Durations.
  *
- * @example
+ * **Example** (Selecting the longer duration)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -933,14 +968,15 @@ export const min = /*#__PURE__*/order.min(Order);
  * console.log(Duration.toSeconds(longer)) // 5
  * ```
  *
- * @since 2.0.0
  * @category order
+ * @since 2.0.0
  */
 export const max = /*#__PURE__*/order.max(Order);
 /**
  * Clamps a Duration between a minimum and maximum value.
  *
- * @example
+ * **Example** (Clamping durations to a range)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -951,14 +987,18 @@ export const max = /*#__PURE__*/order.max(Order);
  * console.log(Duration.toSeconds(clamped)) // 5
  * ```
  *
- * @since 2.0.0
  * @category order
+ * @since 2.0.0
  */
 export const clamp = /*#__PURE__*/order.clamp(Order);
 /**
- * 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,8 +1009,8 @@ export const clamp = /*#__PURE__*/order.clamp(Order);
  * Duration.divide(Duration.seconds(10), 0) // None
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export const divide = /*#__PURE__*/dual(2, (self, by) => {
   if (!Number.isFinite(by)) return Option.none();
@@ -989,9 +1029,17 @@ export const divide = /*#__PURE__*/dual(2, (self, by) => {
   });
 });
 /**
- * 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"
  *
@@ -1002,8 +1050,8 @@ export const divide = /*#__PURE__*/dual(2, (self, by) => {
  * console.log(Duration.toMillis(infinite)) // Infinity
  * ```
  *
- * @since 2.4.19
  * @category math
+ * @since 2.4.19
  */
 export const divideUnsafe = /*#__PURE__*/dual(2, (self, by) => {
   if (!Number.isFinite(by)) return zero;
@@ -1028,9 +1076,15 @@ export const divideUnsafe = /*#__PURE__*/dual(2, (self, by) => {
   });
 });
 /**
- * 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"
  *
@@ -1038,8 +1092,8 @@ export const divideUnsafe = /*#__PURE__*/dual(2, (self, by) => {
  * console.log(Duration.toSeconds(doubled)) // 10
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const times = /*#__PURE__*/dual(2, (self, times) => match(self, {
   onMillis: millis => make(millis * times),
@@ -1060,7 +1114,8 @@ export const times = /*#__PURE__*/dual(2, (self, times) => match(self, {
  * - finite - infinity = negativeInfinity
  * - finite - negativeInfinity = infinity
  *
- * @example
+ * **Example** (Subtracting durations)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -1068,8 +1123,8 @@ export const times = /*#__PURE__*/dual(2, (self, times) => match(self, {
  * console.log(Duration.toSeconds(result)) // 7
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const subtract = /*#__PURE__*/dual(2, (self, that) => matchPair(self, that, {
   onMillis: (self, that) => make(self - that),
@@ -1092,7 +1147,8 @@ export const subtract = /*#__PURE__*/dual(2, (self, that) => matchPair(self, tha
  * - negativeInfinity + negativeInfinity = negativeInfinity
  * - negativeInfinity + finite = negativeInfinity
  *
- * @example
+ * **Example** (Adding durations)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -1100,8 +1156,8 @@ export const subtract = /*#__PURE__*/dual(2, (self, that) => matchPair(self, tha
  * console.log(Duration.toSeconds(total)) // 8
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const sum = /*#__PURE__*/dual(2, (self, that) => matchPair(self, that, {
   onMillis: (self, that) => make(self + that),
@@ -1120,7 +1176,8 @@ export const sum = /*#__PURE__*/dual(2, (self, that) => matchPair(self, that, {
 /**
  * Checks if the first Duration is less than the second.
  *
- * @example
+ * **Example** (Comparing durations with less than)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -1128,14 +1185,15 @@ export const sum = /*#__PURE__*/dual(2, (self, that) => matchPair(self, that, {
  * console.log(isLess) // true
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const isLessThan = /*#__PURE__*/order.isLessThan(Order);
 /**
  * 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"
  *
@@ -1146,14 +1204,15 @@ export const isLessThan = /*#__PURE__*/order.isLessThan(Order);
  * console.log(isLessOrEqual) // true
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const isLessThanOrEqualTo = /*#__PURE__*/order.isLessThanOrEqualTo(Order);
 /**
  * Checks if the first Duration is greater than the second.
  *
- * @example
+ * **Example** (Comparing durations with greater than)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -1161,14 +1220,15 @@ export const isLessThanOrEqualTo = /*#__PURE__*/order.isLessThanOrEqualTo(Order)
  * console.log(isGreater) // true
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const isGreaterThan = /*#__PURE__*/order.isGreaterThan(Order);
 /**
  * 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"
  *
@@ -1179,14 +1239,15 @@ export const isGreaterThan = /*#__PURE__*/order.isGreaterThan(Order);
  * console.log(isGreaterOrEqual) // true
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const isGreaterThanOrEqualTo = /*#__PURE__*/order.isGreaterThanOrEqualTo(Order);
 /**
  * Checks if two Durations are equal.
  *
- * @example
+ * **Example** (Checking duration equality)
+ *
  * ```ts
  * import { Duration } from "effect"
  *
@@ -1194,14 +1255,19 @@ export const isGreaterThanOrEqualTo = /*#__PURE__*/order.isGreaterThanOrEqualTo(
  * console.log(isEqual) // true
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const equals = /*#__PURE__*/dual(2, (self, that) => Equivalence(self, that));
 /**
- * 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"
  *
@@ -1237,8 +1303,8 @@ export const equals = /*#__PURE__*/dual(2, (self, that) => Equivalence(self, tha
  * // }
  * ```
  *
- * @since 3.8.0
  * @category conversions
+ * @since 3.8.0
  */
 export const parts = self => {
   if (self.value._tag === "Infinity") {
@@ -1282,15 +1348,17 @@ export const parts = self => {
 /**
  * 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 const format = self => {
   if (self.value._tag === "Infinity") {