Duration

Duration 数据类型用于表示特定的非负时间跨度。它常用于在各种操作中表示时间间隔或持续时间，例如超时、延迟或调度。Duration 类型提供了一种便捷的方式来处理时间单位，并对时长进行计算。

创建 Duration

Duration 模块提供了若干构造函数，用于以不同的单位创建时长。

示例（以各种单位创建时长）

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)

你可以使用纳秒、微秒、毫秒、秒、分钟、小时、天和周等单位来创建时长。

若要创建无限的时长，请使用 Duration.infinity。

示例（创建无限时长）

import { Duration } from "effect"

console.log(String(Duration.infinity))
/*
Output:
Duration(Infinity)
*/

另一种创建时长的方式是使用 Duration.decode 辅助函数：

• number 值会被视为毫秒。
• bigint 值会被视为纳秒。
• 字符串必须遵循 "${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)

获取 Duration 的值

你可以使用 Duration.toMillis 以毫秒为单位获取时长的值。

示例（以毫秒获取时长）

import { Duration } from "effect"

console.log(Duration.toMillis(Duration.seconds(30)))
// Output: 30000

若要以纳秒为单位获取时长的值，请使用 Duration.toNanos。注意，toNanos 返回 Option<bigint>，因为时长可能是无限的。

示例（以纳秒获取时长）

import { Duration } from "effect"

console.log(Duration.toNanos(Duration.millis(100)))
/*
Output:
{ _id: 'Option', _tag: 'Some', value: 100000000n }
*/

若要直接得到 bigint 值而不经过 Option，请使用 Duration.unsafeToNanos。不过，对于无限时长它会抛出错误。

示例（不安全的纳秒获取方式）

import { Duration } from "effect"

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

console.log(Duration.unsafeToNanos(Duration.infinity))
/*
throws:
Error: Cannot convert infinite duration to nanos
  ...stack trace...
*/

比较 Duration

使用以下函数来比较两个时长：

API	说明
lessThan	如果第一个时长小于第二个，则返回 true。
lessThanOrEqualTo	如果第一个时长小于或等于第二个，则返回 true。
greaterThan	如果第一个时长大于第二个，则返回 true。
greaterThanOrEqualTo	如果第一个时长大于或等于第二个，则返回 true。

示例（比较两个时长）

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

执行算术运算

你可以对时长执行算术运算，例如加法和乘法。

示例（时长相加与相乘）

import { Duration } from "effect"

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

// Add two durations
console.log(String(Duration.sum(duration1, duration2)))
/*
Output:
Duration(1m 30s)
*/

// Multiply a duration by a factor
console.log(String(Duration.times(duration1, 2)))
/*
Output:
Duration(1m)
*/

转换

把 Duration 转换为人类可读的字符串。

示例

import { Duration } from "effect"

Duration.format(Duration.millis(1000)) // "1s"
Duration.format(Duration.millis(1001)) // "1s 1ms"