Duration

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:

import { Duration } from "effect"

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

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

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

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:

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:

• numbers are treated as milliseconds
• bigints are treated as nanoseconds
• strings must be formatted as "${number} ${unit}"

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.infinity

Duration.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:

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:

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:

import { Duration } from "effect"

console.log(Duration.unsafeToNanos(Duration.millis(100)))
// Output: 100000000n

// throws "Cannot convert infinite duration to nanos"
console.log(Duration.unsafeToNanos(Duration.infinity))

Comparing Durations

You can compare two durations using the following functions:

API	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

import { Duration } from "effect"

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

console.log(Duration.lessThan(duration1, duration2))
// Output: true

console.log(Duration.lessThanOrEqualTo(duration1, duration2))
// Output: true

console.log(Duration.greaterThan(duration1, duration2))
// Output: false

console.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:

import { Duration } from "effect"

const duration1 = Duration.seconds(30)
const duration2 = 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
}
*/