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"
 
const duration1 = Duration.millis(100) // Create a duration of 100 milliseconds
const duration2 = Duration.seconds(2) // Create a duration of 2 seconds
const duration3 = 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:

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

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
}
*/

Data Either