effect 4.0.0 → 4.0.2

package/src/Duration.ts

@@ -7,6 +7,7 @@
  * from common input shapes, unit conversions, comparisons, arithmetic,
  * formatting, and reusable reducer or combiner helpers.
  *
+ * @stability stable
  * @since 2.0.0
  */
 import * as Combiner from "./Combiner.ts"
@@ -78,6 +79,7 @@ const nanosToHrTime = (nanos: bigint): [seconds: number, nanos: number] => {
  * @see {@link DurationValue} for the tagged representation exposed by the
  * `value` field
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -104,6 +106,7 @@ export interface Duration extends Equal.Equal, Pipeable, Inspectable.Inspectable
  * representation
  * @see {@link match} for pattern matching without reading `value` directly
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -123,6 +126,7 @@ export type DurationValue =
  *
  * @see {@link Input} for the full duration input union
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -166,6 +170,7 @@ export type Unit =
  * @see {@link DurationObject} for object-shaped duration input
  * @see {@link Unit} for supported string units
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -197,6 +202,7 @@ export type Input =
  * Duration.fromInputUnsafe({ seconds: 1, nanoseconds: 500 }) // => Duration.nanos(1_000_000_500n)
  * ```
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -236,6 +242,7 @@ const DURATION_REGEXP = /^(-?\d+(?:\.\d+)?)\s+(nanos?|micros?|millis?|seconds?|m
  * Duration.fromInputUnsafe([2, 500_000_000]) // => Duration.nanos(2_500_000_000n)
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -337,6 +344,7 @@ const invalid = (input: unknown): never => {
  * Duration.fromInput("invalid" as any) // => Option.none()
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -431,6 +439,7 @@ const make = (input: number | bigint): Duration => {
  * Duration.isDuration(1000) // => false
  * ```
  *
+ * @stability stable
  * @category guards
  * @since 2.0.0
  */
@@ -448,6 +457,7 @@ export const isDuration = (u: unknown): u is Duration => hasProperty(u, TypeId)
  * Duration.isFinite(Duration.infinity) // => false
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 2.0.0
  */
@@ -466,6 +476,7 @@ export const isFinite = (self: Duration): boolean =>
  * Duration.isZero(Duration.seconds(1)) // => false
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 3.5.0
  */
@@ -494,6 +505,7 @@ export const isZero = (self: Duration): boolean => {
  * Duration.isNegative(Duration.negativeInfinity) // => true
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 4.0.0
  */
@@ -523,6 +535,7 @@ export const isNegative = (self: Duration): boolean => {
  * Duration.isPositive(Duration.infinity) // => true
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 4.0.0
  */
@@ -551,6 +564,7 @@ export const isPositive = (self: Duration): boolean => {
  * Duration.abs(Duration.negativeInfinity) // => Duration.infinity
  * ```
  *
+ * @stability stable
  * @category math
  * @since 4.0.0
  */
@@ -578,6 +592,7 @@ export const abs = (self: Duration): Duration => {
  * Duration.negate(Duration.infinity) // => Duration.negativeInfinity
  * ```
  *
+ * @stability stable
  * @category math
  * @since 4.0.0
  */
@@ -605,6 +620,7 @@ export const negate = (self: Duration): Duration => {
  * Duration.toMillis(Duration.zero) // => 0
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -621,6 +637,7 @@ export const zero: Duration = make(0)
  * Duration.toMillis(Duration.infinity) // => Infinity
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -637,6 +654,7 @@ export const infinity: Duration = make(Infinity)
  * Duration.toMillis(Duration.negativeInfinity) // => -Infinity
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -653,6 +671,7 @@ export const negativeInfinity: Duration = make(-Infinity)
  * Duration.nanos(500_000_000n) // => Duration.nanos(500_000_000n)
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -669,6 +688,7 @@ export const nanos = (nanos: bigint): Duration => make(nanos)
  * Duration.micros(500_000n) // => Duration.nanos(500_000_000n)
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -685,6 +705,7 @@ export const micros = (micros: bigint): Duration => make(micros * bigint1e3)
  * Duration.toMillis(Duration.millis(1000)) // => 1000
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -701,6 +722,7 @@ export const millis = (millis: number): Duration => make(millis)
  * Duration.toMillis(Duration.seconds(30)) // => 30_000
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -717,6 +739,7 @@ export const seconds = (seconds: number): Duration => make(seconds * 1000)
  * Duration.toMillis(Duration.minutes(5)) // => 300_000
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -733,6 +756,7 @@ export const minutes = (minutes: number): Duration => make(minutes * 60_000)
  * Duration.toMillis(Duration.hours(2)) // => 7_200_000
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -749,6 +773,7 @@ export const hours = (hours: number): Duration => make(hours * 3_600_000)
  * Duration.toMillis(Duration.days(1)) // => 86_400_000
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -765,6 +790,7 @@ export const days = (days: number): Duration => make(days * 86_400_000)
  * Duration.toMillis(Duration.weeks(1)) // => 604_800_000
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -782,6 +808,7 @@ export const weeks = (weeks: number): Duration => make(weeks * 604_800_000)
  * Duration.toMillis(Duration.minutes(2)) // => 120_000
  * ```
  *
+ * @stability stable
  * @category getters
  * @since 2.0.0
  */
@@ -805,6 +832,7 @@ export const toMillis = (self: Input): number =>
  * Duration.toSeconds(Duration.minutes(2)) // => 120
  * ```
  *
+ * @stability stable
  * @category getters
  * @since 2.0.0
  */
@@ -828,6 +856,7 @@ export const toSeconds = (self: Input): number =>
  * Duration.toMinutes(Duration.hours(1)) // => 60
  * ```
  *
+ * @stability stable
  * @category getters
  * @since 3.8.0
  */
@@ -851,6 +880,7 @@ export const toMinutes = (self: Input): number =>
  * Duration.toHours(Duration.days(1)) // => 24
  * ```
  *
+ * @stability stable
  * @category getters
  * @since 3.8.0
  */
@@ -874,6 +904,7 @@ export const toHours = (self: Input): number =>
  * Duration.toDays(Duration.weeks(1)) // => 7
  * ```
  *
+ * @stability stable
  * @category getters
  * @since 3.8.0
  */
@@ -897,6 +928,7 @@ export const toDays = (self: Input): number =>
  * Duration.toWeeks(Duration.days(7)) // => 1
  * ```
  *
+ * @stability stable
  * @category getters
  * @since 3.8.0
  */
@@ -936,6 +968,7 @@ export const toWeeks = (self: Input): number =>
  * // throws Error: "Cannot convert infinite duration to nanos"
  * ```
  *
+ * @stability stable
  * @category getters
  * @since 4.0.0
  */
@@ -968,6 +1001,7 @@ export const toNanosUnsafe = (input: Input): bigint => {
  * Duration.toNanos(Duration.infinity) // => Option.none()
  * ```
  *
+ * @stability stable
  * @category getters
  * @since 2.0.0
  */
@@ -984,6 +1018,7 @@ export const toNanos: (self: Input) => Option.Option<bigint> = Option.liftThrowa
  * Duration.toHrTime(Duration.millis(1500)) // => [1, 500_000_000]
  * ```
  *
+ * @stability stable
  * @category getters
  * @since 2.0.0
  */
@@ -1022,6 +1057,7 @@ export const toHrTime = (input: Input): [seconds: number, nanos: number] => {
  * }) // => "5000 milliseconds"
  * ```
  *
+ * @stability stable
  * @category pattern matching
  * @since 2.0.0
  */
@@ -1047,6 +1083,7 @@ export const match: {
    * }) // => "5000 milliseconds"
    * ```
    *
+   * @stability stable
    * @category pattern matching
    * @since 2.0.0
    */
@@ -1079,6 +1116,7 @@ export const match: {
    * }) // => "5000 milliseconds"
    * ```
    *
+   * @stability stable
    * @category pattern matching
    * @since 2.0.0
    */
@@ -1127,6 +1165,7 @@ export const match: {
  * }) // => 5000
  * ```
  *
+ * @stability stable
  * @category pattern matching
  * @since 4.0.0
  */
@@ -1146,6 +1185,7 @@ export const matchPair: {
    * }) // => 5000
    * ```
    *
+   * @stability stable
    * @category pattern matching
    * @since 4.0.0
    */
@@ -1172,6 +1212,7 @@ export const matchPair: {
    * }) // => 5000
    * ```
    *
+   * @stability stable
    * @category pattern matching
    * @since 4.0.0
    */
@@ -1226,6 +1267,7 @@ export const matchPair: {
  * durations.sort((a, b) => Duration.Order(a, b)).map(Duration.toSeconds) // => [1, 2, 3]
  * ```
  *
+ * @stability stable
  * @category instances
  * @since 2.0.0
  */
@@ -1277,6 +1319,7 @@ export const Order: order.Order<Duration> = order.make((self, that) =>
  * @see {@link isGreaterThanOrEqualTo} for checking only the lower bound
  * @see {@link isLessThanOrEqualTo} for checking only the upper bound
  *
+ * @stability stable
  * @category predicates
  * @since 2.0.0
  */
@@ -1313,6 +1356,7 @@ export const between: {
    * @see {@link isGreaterThanOrEqualTo} for checking only the lower bound
    * @see {@link isLessThanOrEqualTo} for checking only the upper bound
    *
+   * @stability stable
    * @category predicates
    * @since 2.0.0
    */
@@ -1349,6 +1393,7 @@ export const between: {
    * @see {@link isGreaterThanOrEqualTo} for checking only the lower bound
    * @see {@link isLessThanOrEqualTo} for checking only the upper bound
    *
+   * @stability stable
    * @category predicates
    * @since 2.0.0
    */
@@ -1366,6 +1411,7 @@ export const between: {
  * Duration.Equivalence(Duration.seconds(5), Duration.millis(5000)) // => true
  * ```
  *
+ * @stability stable
  * @category instances
  * @since 2.0.0
  */
@@ -1387,6 +1433,7 @@ export const Equivalence: Equ.Equivalence<Duration> = (self, that) =>
  * Duration.min(Duration.seconds(5), Duration.seconds(3)) // => Duration.seconds(3)
  * ```
  *
+ * @stability stable
  * @category ordering
  * @since 2.0.0
  */
@@ -1402,6 +1449,7 @@ export const min: {
    * Duration.min(Duration.seconds(5), Duration.seconds(3)) // => Duration.seconds(3)
    * ```
    *
+   * @stability stable
    * @category ordering
    * @since 2.0.0
    */
@@ -1417,6 +1465,7 @@ export const min: {
    * Duration.min(Duration.seconds(5), Duration.seconds(3)) // => Duration.seconds(3)
    * ```
    *
+   * @stability stable
    * @category ordering
    * @since 2.0.0
    */
@@ -1434,6 +1483,7 @@ export const min: {
  * Duration.max(Duration.seconds(5), Duration.seconds(3)) // => Duration.seconds(5)
  * ```
  *
+ * @stability stable
  * @category ordering
  * @since 2.0.0
  */
@@ -1449,6 +1499,7 @@ export const max: {
    * Duration.max(Duration.seconds(5), Duration.seconds(3)) // => Duration.seconds(5)
    * ```
    *
+   * @stability stable
    * @category ordering
    * @since 2.0.0
    */
@@ -1464,6 +1515,7 @@ export const max: {
    * Duration.max(Duration.seconds(5), Duration.seconds(3)) // => Duration.seconds(5)
    * ```
    *
+   * @stability stable
    * @category ordering
    * @since 2.0.0
    */
@@ -1484,6 +1536,7 @@ export const max: {
  * }) // => Duration.seconds(5)
  * ```
  *
+ * @stability stable
  * @category ordering
  * @since 2.0.0
  */
@@ -1502,6 +1555,7 @@ export const clamp: {
    * }) // => Duration.seconds(5)
    * ```
    *
+   * @stability stable
    * @category ordering
    * @since 2.0.0
    */
@@ -1520,6 +1574,7 @@ export const clamp: {
    * }) // => Duration.seconds(5)
    * ```
    *
+   * @stability stable
    * @category ordering
    * @since 2.0.0
    */
@@ -1544,6 +1599,7 @@ export const clamp: {
  * Duration.divide(Duration.seconds(10), 0) // => Option.none()
  * ```
  *
+ * @stability stable
  * @category math
  * @since 2.4.19
  */
@@ -1566,6 +1622,7 @@ export const divide: {
    * Duration.divide(Duration.seconds(10), 0) // => Option.none()
    * ```
    *
+   * @stability stable
    * @category math
    * @since 2.4.19
    */
@@ -1588,6 +1645,7 @@ export const divide: {
    * Duration.divide(Duration.seconds(10), 0) // => Option.none()
    * ```
    *
+   * @stability stable
    * @category math
    * @since 2.4.19
    */
@@ -1638,6 +1696,7 @@ export const divide: {
  * Duration.divideUnsafe(Duration.seconds(10), 0) // => Duration.infinity
  * ```
  *
+ * @stability stable
  * @category math
  * @since 4.0.0
  */
@@ -1668,6 +1727,7 @@ export const divideUnsafe: {
    * Duration.divideUnsafe(Duration.seconds(10), 0) // => Duration.infinity
    * ```
    *
+   * @stability stable
    * @category math
    * @since 4.0.0
    */
@@ -1698,6 +1758,7 @@ export const divideUnsafe: {
    * Duration.divideUnsafe(Duration.seconds(10), 0) // => Duration.infinity
    * ```
    *
+   * @stability stable
    * @category math
    * @since 4.0.0
    */
@@ -1746,6 +1807,7 @@ export const divideUnsafe: {
  * Duration.times(Duration.seconds(5), 2) // => Duration.seconds(10)
  * ```
  *
+ * @stability stable
  * @category math
  * @since 2.0.0
  */
@@ -1768,6 +1830,7 @@ export const times: {
    * Duration.times(Duration.seconds(5), 2) // => Duration.seconds(10)
    * ```
    *
+   * @stability stable
    * @category math
    * @since 2.0.0
    */
@@ -1790,6 +1853,7 @@ export const times: {
    * Duration.times(Duration.seconds(5), 2) // => Duration.seconds(10)
    * ```
    *
+   * @stability stable
    * @category math
    * @since 2.0.0
    */
@@ -1825,6 +1889,7 @@ export const times: {
  * Duration.subtract(Duration.seconds(10), Duration.seconds(3)) // => Duration.seconds(7)
  * ```
  *
+ * @stability stable
  * @category math
  * @since 2.0.0
  */
@@ -1849,6 +1914,7 @@ export const subtract: {
    * Duration.subtract(Duration.seconds(10), Duration.seconds(3)) // => Duration.seconds(7)
    * ```
    *
+   * @stability stable
    * @category math
    * @since 2.0.0
    */
@@ -1873,6 +1939,7 @@ export const subtract: {
    * Duration.subtract(Duration.seconds(10), Duration.seconds(3)) // => Duration.seconds(7)
    * ```
    *
+   * @stability stable
    * @category math
    * @since 2.0.0
    */
@@ -1914,6 +1981,7 @@ export const subtract: {
  * Duration.sum(Duration.seconds(5), Duration.seconds(3)) // => Duration.seconds(8)
  * ```
  *
+ * @stability stable
  * @category math
  * @since 2.0.0
  */
@@ -1939,6 +2007,7 @@ export const sum: {
    * Duration.sum(Duration.seconds(5), Duration.seconds(3)) // => Duration.seconds(8)
    * ```
    *
+   * @stability stable
    * @category math
    * @since 2.0.0
    */
@@ -1964,6 +2033,7 @@ export const sum: {
    * Duration.sum(Duration.seconds(5), Duration.seconds(3)) // => Duration.seconds(8)
    * ```
    *
+   * @stability stable
    * @category math
    * @since 2.0.0
    */
@@ -1998,6 +2068,7 @@ export const sum: {
  * Duration.isLessThan(Duration.seconds(3), Duration.seconds(5)) // => true
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 4.0.0
  */
@@ -2013,6 +2084,7 @@ export const isLessThan: {
    * Duration.isLessThan(Duration.seconds(3), Duration.seconds(5)) // => true
    * ```
    *
+   * @stability stable
    * @category predicates
    * @since 4.0.0
    */
@@ -2028,6 +2100,7 @@ export const isLessThan: {
    * Duration.isLessThan(Duration.seconds(3), Duration.seconds(5)) // => true
    * ```
    *
+   * @stability stable
    * @category predicates
    * @since 4.0.0
    */
@@ -2048,6 +2121,7 @@ export const isLessThan: {
  * ) // => true
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 4.0.0
  */
@@ -2066,6 +2140,7 @@ export const isLessThanOrEqualTo: {
    * ) // => true
    * ```
    *
+   * @stability stable
    * @category predicates
    * @since 4.0.0
    */
@@ -2084,6 +2159,7 @@ export const isLessThanOrEqualTo: {
    * ) // => true
    * ```
    *
+   * @stability stable
    * @category predicates
    * @since 4.0.0
    */
@@ -2101,6 +2177,7 @@ export const isLessThanOrEqualTo: {
  * Duration.isGreaterThan(Duration.seconds(5), Duration.seconds(3)) // => true
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 4.0.0
  */
@@ -2116,6 +2193,7 @@ export const isGreaterThan: {
    * Duration.isGreaterThan(Duration.seconds(5), Duration.seconds(3)) // => true
    * ```
    *
+   * @stability stable
    * @category predicates
    * @since 4.0.0
    */
@@ -2131,6 +2209,7 @@ export const isGreaterThan: {
    * Duration.isGreaterThan(Duration.seconds(5), Duration.seconds(3)) // => true
    * ```
    *
+   * @stability stable
    * @category predicates
    * @since 4.0.0
    */
@@ -2151,6 +2230,7 @@ export const isGreaterThan: {
  * ) // => true
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 4.0.0
  */
@@ -2169,6 +2249,7 @@ export const isGreaterThanOrEqualTo: {
    * ) // => true
    * ```
    *
+   * @stability stable
    * @category predicates
    * @since 4.0.0
    */
@@ -2187,6 +2268,7 @@ export const isGreaterThanOrEqualTo: {
    * ) // => true
    * ```
    *
+   * @stability stable
    * @category predicates
    * @since 4.0.0
    */
@@ -2204,6 +2286,7 @@ export const isGreaterThanOrEqualTo: {
  * Duration.equals(Duration.seconds(5), Duration.millis(5000)) // => true
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 2.0.0
  */
@@ -2219,6 +2302,7 @@ export const equals: {
    * Duration.equals(Duration.seconds(5), Duration.millis(5000)) // => true
    * ```
    *
+   * @stability stable
    * @category predicates
    * @since 2.0.0
    */
@@ -2234,6 +2318,7 @@ export const equals: {
    * Duration.equals(Duration.seconds(5), Duration.millis(5000)) // => true
    * ```
    *
+   * @stability stable
    * @category predicates
    * @since 2.0.0
    */
@@ -2268,6 +2353,7 @@ export const equals: {
  * Duration.parts(complex) // => ({ days: 1, hours: 2, minutes: 30, seconds: 0, millis: 0, nanos: 0 })
  * ```
  *
+ * @stability stable
  * @category converting
  * @since 3.8.0
  */
@@ -2332,6 +2418,7 @@ export const parts = (self: Duration): {
  * Duration.format(Duration.millis(1001)) // => "1s 1ms"
  * ```
  *
+ * @stability stable
  * @category converting
  * @since 2.0.0
  */
@@ -2394,6 +2481,7 @@ export const format = (self: Duration): string => {
  * @see {@link CombinerMax} for keeping the longest duration instead of summing
  * @see {@link CombinerMin} for keeping the shortest duration instead of summing
  *
+ * @stability stable
  * @category math
  * @since 4.0.0
  */
@@ -2409,6 +2497,7 @@ export const ReducerSum: Reducer.Reducer<Duration> = Reducer.make(sum, zero)
  * @see {@link CombinerMin} for keeping the shortest `Duration`
  * @see {@link max} for comparing two `Duration` values directly
  *
+ * @stability stable
  * @category math
  * @since 4.0.0
  */
@@ -2424,6 +2513,7 @@ export const CombinerMax: Combiner.Combiner<Duration> = Combiner.max(Order)
  * @see {@link CombinerMax} for keeping the longest `Duration`
  * @see {@link min} for comparing two `Duration` values directly
  *
+ * @stability stable
  * @category math
  * @since 4.0.0
  */