Duration

The Duration data type represents non-negative spans of time. It is commonly used for timeouts, delays, and scheduling, and provides operations for working with different time units.

Creating Durations

The Duration module includes several constructors to create durations in different units.

Example (Creating Durations in Various Units)

1
import { Duration } from "effect"
2

3
// Create a duration of 100 milliseconds
4
const duration1 = Duration.millis(100)
5

6
// Create a duration of 2 seconds
7
const duration2 = Duration.seconds(2)
8

9
// Create a duration of 5 minutes
10
const duration3 = Duration.minutes(5)
11

12
Duration.toMillis(duration3) // => 300000

You can create durations using units such as nanoseconds, microsecond, milliseconds, seconds, minutes, hours, days, and weeks.

For an infinite duration, use Duration.infinity.

Example (Creating an Infinite Duration)

1
import { Duration } from "effect"
2

3
console.log(String(Duration.infinity))
4
String(Duration.infinity) // => "Infinity"

Another option for creating durations is using the Duration.fromInputUnsafe helper:

number values are treated as milliseconds.
bigint values are treated as nanoseconds.
Strings must follow the format "${number} ${unit}".

Example (Decoding Values into Durations)

1
import { Duration } from "effect"
2

3
Duration.fromInputUnsafe(10n) // => Duration.nanos(10n)
4
Duration.fromInputUnsafe(100) // => Duration.millis(100)
5
Duration.fromInputUnsafe(Infinity) // => Duration.infinity
6

7
Duration.fromInputUnsafe("10 nanos") // => Duration.nanos(10n)
8
Duration.fromInputUnsafe("20 micros") // => Duration.micros(20n)
9
Duration.fromInputUnsafe("100 millis") // => Duration.millis(100)
10
Duration.fromInputUnsafe("2 seconds") // => Duration.seconds(2)
11
Duration.fromInputUnsafe("5 minutes") // => Duration.minutes(5)
12
Duration.fromInputUnsafe("7 hours") // => Duration.hours(7)
13
Duration.fromInputUnsafe("3 weeks") // => Duration.weeks(3)

Getting the Duration Value

You can retrieve the value of a duration in milliseconds using Duration.toMillis.

Example (Getting Duration in Milliseconds)

1
import { Duration } from "effect"
2

3
console.log(Duration.toMillis(Duration.seconds(30)))
4
Duration.toMillis(Duration.seconds(30)) // => 30000

To get the value of a duration in nanoseconds, use Duration.toNanos. Note that toNanos returns an Option<bigint> because the duration might be infinite.

Example (Getting Duration in Nanoseconds)

1
import { Duration, Option } from "effect"
2

3
console.log(Duration.toNanos(Duration.millis(100)))
4
Duration.toNanos(Duration.millis(100)) // => Option.some(100000000n)

To get a bigint value without Option, use Duration.toNanosUnsafe. However, it will throw an error for infinite durations.

Example (Retrieving Nanoseconds Unsafely)

1
import { Duration } from "effect"
2

3
console.log(Duration.toNanosUnsafe(Duration.millis(100)))
4
// Output: 100000000n
5

6
console.log(Duration.toNanosUnsafe(Duration.infinity))
7
/*
8
throws:
9
Error: Cannot convert infinite duration to nanos
10
  ...stack trace...
11
*/

Comparing Durations

Use the following functions to compare two durations:

API	Description
`isLessThan`	Returns `true` if the first duration is less than the second.
`isLessThanOrEqualTo`	Returns `true` if the first duration is less than or equal to the second.
`isGreaterThan`	Returns `true` if the first duration is greater than the second.
`isGreaterThanOrEqualTo`	Returns `true` if the first duration is greater than or equal to the second.

Example (Comparing Two Durations)

1
import { Duration } from "effect"
2

3
const duration1 = Duration.seconds(30)
4
const duration2 = Duration.minutes(1)
5

6
console.log(Duration.isLessThan(duration1, duration2))
7
Duration.isLessThan(duration1, duration2) // => true
8

9
console.log(Duration.isLessThanOrEqualTo(duration1, duration2))
10
Duration.isLessThanOrEqualTo(duration1, duration2) // => true
11

12
console.log(Duration.isGreaterThan(duration1, duration2))
13
Duration.isGreaterThan(duration1, duration2) // => false
14

15
console.log(Duration.isGreaterThanOrEqualTo(duration1, duration2))
16
Duration.isGreaterThanOrEqualTo(duration1, duration2) // => false

Performing Arithmetic Operations

You can perform arithmetic operations on durations, like addition and multiplication.

Example (Adding and Multiplying Durations)

1
import { Duration } from "effect"
2

3
const duration1 = Duration.seconds(30)
4
const duration2 = Duration.minutes(1)
5

6
// Add two durations
7
console.log(String(Duration.sum(duration1, duration2)))
8
String(Duration.sum(duration1, duration2)) // => "90000 millis"
9

10
// Multiply a duration by a factor
11
console.log(String(Duration.times(duration1, 2)))
12
String(Duration.times(duration1, 2)) // => "60000 millis"

Conversions

Converts a Duration to a human readable string.

Example

1
import { Duration } from "effect"
2

3
Duration.format(Duration.millis(1000)) // => "1s"
4
Duration.format(Duration.millis(1001)) // => "1s 1ms"