Duration
On this page
The Duration
data type data type is used to represent specific non-negative spans of time. It is commonly used to represent time intervals or durations in various operations, such as timeouts, delays, or scheduling. The Duration
type provides a convenient way to work with time units and perform calculations on durations.
Creating Durations
The Duration
module provides several constructors to create durations of different units. Here are some examples:
ts
import {Duration } from "effect"constduration1 =Duration .millis (100) // Create a duration of 100 millisecondsconstduration2 =Duration .seconds (2) // Create a duration of 2 secondsconstduration3 =Duration .minutes (5) // Create a duration of 5 minutes
ts
import {Duration } from "effect"constduration1 =Duration .millis (100) // Create a duration of 100 millisecondsconstduration2 =Duration .seconds (2) // Create a duration of 2 secondsconstduration3 =Duration .minutes (5) // Create a duration of 5 minutes
You can create durations using units such as nanoseconds, microsecond, milliseconds, seconds, minutes, hours, days, and weeks.
If you want to create an infinite duration, you can use Duration.infinity
:
ts
import {Duration } from "effect"console .log (String (Duration .infinity ))/*Output:{"_id": "Duration","_tag": "Infinity"}*/
ts
import {Duration } from "effect"console .log (String (Duration .infinity ))/*Output:{"_id": "Duration","_tag": "Infinity"}*/
Another option for creating durations is using the Duration.decode
helper:
number
s are treated as millisecondsbigint
s are treated as nanoseconds- strings must be formatted as
"${number} ${unit}"
ts
import {Duration } from "effect"Duration .decode (10n) // same as Duration.nanos(10)Duration .decode (100) // same as Duration.millis(100)Duration .decode (Infinity ) // same as Duration.infinityDuration .decode ("10 nanos") // same as Duration.nanos(10)Duration .decode ("20 micros") // same as Duration.micros(20)Duration .decode ("100 millis") // same as Duration.millis(100)Duration .decode ("2 seconds") // same as Duration.seconds(2)Duration .decode ("5 minutes") // same as Duration.minutes(5)Duration .decode ("7 hours") // same as Duration.hours(7)Duration .decode ("3 weeks") // same as Duration.weeks(3)
ts
import {Duration } from "effect"Duration .decode (10n) // same as Duration.nanos(10)Duration .decode (100) // same as Duration.millis(100)Duration .decode (Infinity ) // same as Duration.infinityDuration .decode ("10 nanos") // same as Duration.nanos(10)Duration .decode ("20 micros") // same as Duration.micros(20)Duration .decode ("100 millis") // same as Duration.millis(100)Duration .decode ("2 seconds") // same as Duration.seconds(2)Duration .decode ("5 minutes") // same as Duration.minutes(5)Duration .decode ("7 hours") // same as Duration.hours(7)Duration .decode ("3 weeks") // same as Duration.weeks(3)
Getting the Duration Value
You can retrieve the value of a duration in milliseconds using the toMillis
function:
ts
import {Duration } from "effect"console .log (Duration .toMillis (Duration .seconds (30))) // Output: 30000
ts
import {Duration } from "effect"console .log (Duration .toMillis (Duration .seconds (30))) // Output: 30000
You can retrieve the value of a duration in nanoseconds using the toNanos
function:
ts
import {Duration } from "effect"console .log (Duration .toNanos (Duration .millis (100)))/*Output:{_id: "Option",_tag: "Some",value: 100000000n}*/
ts
import {Duration } from "effect"console .log (Duration .toNanos (Duration .millis (100)))/*Output:{_id: "Option",_tag: "Some",value: 100000000n}*/
Note that toNanos
returns an Option<bigint>
since the duration might be infinite. If you want a bigint
as a return type, you can use unsafeToNanos
. However, note that it will throw an error for infinite durations:
ts
import {Duration } from "effect"console .log (Duration .unsafeToNanos (Duration .millis (100))) // Output: 100000000nconsole .log (Duration .unsafeToNanos (Duration .infinity )) // throws "Cannot convert infinite duration to nanos"
ts
import {Duration } from "effect"console .log (Duration .unsafeToNanos (Duration .millis (100))) // Output: 100000000nconsole .log (Duration .unsafeToNanos (Duration .infinity )) // throws "Cannot convert infinite duration to nanos"
Comparing Durations
You can compare two durations using the following functions:
Function | Description |
---|---|
lessThan | returns true if the first duration is less than the second |
lessThanOrEqualTo | returns true if the first duration is less than or equal to the second |
greaterThan | returns true if the first duration is greater than the second |
greaterThanOrEqualTo | returns true if the first duration is greater than or equal to the second |
ts
import {Duration } from "effect"constduration1 =Duration .seconds (30)constduration2 =Duration .minutes (1)console .log (Duration .lessThan (duration1 ,duration2 )) // Output: trueconsole .log (Duration .lessThanOrEqualTo (duration1 ,duration2 )) // Output: trueconsole .log (Duration .greaterThan (duration1 ,duration2 )) // Output: falseconsole .log (Duration .greaterThanOrEqualTo (duration1 ,duration2 )) // Output: false
ts
import {Duration } from "effect"constduration1 =Duration .seconds (30)constduration2 =Duration .minutes (1)console .log (Duration .lessThan (duration1 ,duration2 )) // Output: trueconsole .log (Duration .lessThanOrEqualTo (duration1 ,duration2 )) // Output: trueconsole .log (Duration .greaterThan (duration1 ,duration2 )) // Output: falseconsole .log (Duration .greaterThanOrEqualTo (duration1 ,duration2 )) // Output: false
Performing Arithmetic Operations
You can perform arithmetic operations on durations, such as addition and multiplication. Here are some examples:
ts
import {Duration } from "effect"constduration1 =Duration .seconds (30)constduration2 =Duration .minutes (1)console .log (String (Duration .sum (duration1 ,duration2 )))/*Output:{"_id": "Duration","_tag": "Millis","millis": 90000}*/console .log (String (Duration .times (duration1 , 2))) // Output: Duration("60000 millis")/*Output:{"_id": "Duration","_tag": "Millis","millis": 60000}*/
ts
import {Duration } from "effect"constduration1 =Duration .seconds (30)constduration2 =Duration .minutes (1)console .log (String (Duration .sum (duration1 ,duration2 )))/*Output:{"_id": "Duration","_tag": "Millis","millis": 90000}*/console .log (String (Duration .times (duration1 , 2))) // Output: Duration("60000 millis")/*Output:{"_id": "Duration","_tag": "Millis","millis": 60000}*/