DateTime

在 JavaScript 中处理日期和时间可能具有挑战性。内置的 Date 对象会改变其内部状态，时区处理可能令人困惑。这些设计选择可能在依赖日期时间准确性的应用程序中导致错误，例如调度系统、时间戳服务或日志记录实用程序。

DateTime 模块旨在通过提供以下功能来解决这些限制：

• 不可变数据：每个 DateTime 都是不可变结构，减少与就地变更相关的错误。
• 时区支持：DateTime 提供强大的时区支持，包括自动夏令时调整。
• 算术运算：您可以对 DateTime 实例执行算术运算，例如添加或减去持续时间。

DateTime 类型

DateTime 表示时间中的一个时刻。它可以存储为简单的 UTC 值或与关联时区的值。以这种方式存储时间有助于您管理精确的时间戳和该时间应如何显示或解释的上下文。

DateTime 有两个主要变体：

1. Utc：一个不可变结构，使用 epochMillis（自 Unix 纪元以来的毫秒数）来表示协调世界时 (UTC) 中的时间点。

2. Zoned：包括 epochMillis 以及 TimeZone，允许您将偏移量或命名区域（如 “America/New_York”）附加到时间戳。

为什么有两个变体？

• Utc 如果您只需要通用引用而不依赖本地时区，则很简单。
• Zoned 当您需要跟踪时区信息以执行诸如转换为本地时间或调整夏令时等任务时很有用。

TimeZone 变体

TimeZone 可以是：

• Offset：表示与 UTC 的固定偏移量（例如，UTC+2 或 UTC-5）。
• Named：使用命名区域（例如，“Europe/London” 或 “America/New_York”），自动考虑特定区域的规则，如夏令时变化。

TypeScript 定义

以下是 DateTime 类型的 TypeScript 定义：

type DateTime = Utc | Zoned

interface Utc {
  readonly _tag: "Utc"
  readonly epochMillis: number
}

interface Zoned {
  readonly _tag: "Zoned"
  readonly epochMillis: number
  readonly zone: TimeZone
}

type TimeZone = TimeZone.Offset | TimeZone.Named

declare namespace TimeZone {
  interface Offset {
    readonly _tag: "Offset"
    readonly offset: number
  }

  interface Named {
    readonly _tag: "Named"
    readonly id: string
  }
}

DateTime.Parts 类型

DateTime.Parts 类型定义了日期的主要组件，例如年、月、日、小时、分钟和秒。

namespace DateTime {
  interface Parts {
    readonly millis: number
    readonly seconds: number
    readonly minutes: number
    readonly hours: number
    readonly day: number
    readonly month: number
    readonly year: number
  }

  interface PartsWithWeekday extends Parts {
    readonly weekDay: number
  }
}

DateTime.Input 类型

DateTime.Input 类型是一个灵活的输入类型，可用于创建 DateTime 实例。它可以是以下之一：

• DateTime 实例
• JavaScript Date 对象
• 表示自 Unix 纪元以来毫秒数的数值
• 具有部分日期组件的对象（例如，{ year: 2024, month: 1, day: 1 }）
• 可以由 JavaScript 的 Date.parse 解析的字符串

namespace DateTime {
  type Input = DateTime | Partial<Parts> | Date | number | string
}

Utc 构造函数

Utc 是一个不可变结构，使用 epochMillis（自 Unix 纪元以来的毫秒数）来表示协调世界时 (UTC) 中的时间点。

unsafeFromDate

从 JavaScript Date 创建 Utc。 如果提供的 Date 无效，则抛出 IllegalArgumentException。

当传递 Date 对象时，它会转换为 Utc 实例。时间被解释为执行代码的系统的本地时间，然后调整为 UTC。这确保了日期和时间的一致、与时区无关的表示。

示例（在意大利将本地时间转换为 UTC）

以下示例假设代码在意大利（CET 时区）的系统上执行：

import { DateTime } from "effect"

// 从本地 JavaScript Date 创建 Utc 实例
//
//     ┌─── Utc
//     ▼
const utc = DateTime.unsafeFromDate(new Date("2025-01-01 04:00:00"))

console.log(utc)
// 输出: DateTime.Utc(2025-01-01T03:00:00.000Z)

console.log(utc.epochMillis)
// 输出: 1735700400000

解释：

• 本地时间 2025-01-01 04:00:00（在意大利，CET）通过减去时区偏移量（1月份为 UTC+1）转换为 UTC。
• 结果，UTC 时间变为 2025-01-01 03:00:00.000Z。
• epochMillis 提供自 Unix 纪元以来的毫秒数形式的相同时间，确保 UTC 时间戳的精确数值表示。

unsafeMake

从 DateTime.Input 创建 Utc。

示例（使用 unsafeMake 创建 DateTime）

以下示例假设代码在意大利（CET 时区）的系统上执行：

import { DateTime } from "effect"

// 从 JavaScript Date
const utc1 = DateTime.unsafeMake(new Date("2025-01-01 04:00:00"))
console.log(utc1)
// 输出: DateTime.Utc(2025-01-01T03:00:00.000Z)

// 从部分日期组件
const utc2 = DateTime.unsafeMake({ year: 2025 })
console.log(utc2)
// 输出: DateTime.Utc(2025-01-01T00:00:00.000Z)

// 从字符串
const utc3 = DateTime.unsafeMake("2025-01-01")
console.log(utc3)
// 输出: DateTime.Utc(2025-01-01T00:00:00.000Z)

解释：

• 本地时间 2025-01-01 04:00:00（在意大利，CET）通过减去时区偏移量（1月份为 UTC+1）转换为 UTC。
• 结果，UTC 时间变为 2025-01-01 03:00:00.000Z。

make

类似于 unsafeMake，但如果输入无效，则返回 Option 而不是抛出错误。 如果输入无效，则返回 None。如果有效，则返回包含 Utc 的 Some。

示例（安全地创建 DateTime）

以下示例假设代码在意大利（CET 时区）的系统上执行：

import { DateTime } from "effect"

// 从 JavaScript Date
const maybeUtc1 = DateTime.make(new Date("2025-01-01 04:00:00"))
console.log(maybeUtc1)
/*
输出:
{ _id: 'Option', _tag: 'Some', value: '2025-01-01T03:00:00.000Z' }
*/

// 从部分日期组件
const maybeUtc2 = DateTime.make({ year: 2025 })
console.log(maybeUtc2)
/*
输出:
{ _id: 'Option', _tag: 'Some', value: '2025-01-01T00:00:00.000Z' }
*/

// 从字符串
const maybeUtc3 = DateTime.make("2025-01-01")
console.log(maybeUtc3)
/*
输出:
{ _id: 'Option', _tag: 'Some', value: '2025-01-01T00:00:00.000Z' }
*/

解释：

• 本地时间 2025-01-01 04:00:00（在意大利，CET）通过减去时区偏移量（1月份为 UTC+1）转换为 UTC。
• 结果，UTC 时间变为 2025-01-01 03:00:00.000Z。

Zoned 构造函数

Zoned 包括 epochMillis 以及 TimeZone，允许您将偏移量或命名区域（如 “America/New_York”）附加到时间戳。

unsafeMakeZoned

通过将 DateTime.Input 与可选的 TimeZone 组合来创建 Zoned。 这允许您表示具有关联时区的特定时间点。

时区可以通过几种方式提供：

• 作为 TimeZone 对象
• 字符串标识符（例如，"Europe/London"）
• 以毫秒为单位的数字偏移量

如果输入或时区无效，则抛出 IllegalArgumentException。

示例（创建不指定时区的 Zoned DateTime）

以下示例假设代码在意大利（CET 时区）的系统上执行：

import { DateTime } from "effect"

// 基于系统本地时区创建 Zoned DateTime
const zoned = DateTime.unsafeMakeZoned(new Date("2025-01-01 04:00:00"))

console.log(zoned)
// 输出: DateTime.Zoned(2025-01-01T04:00:00.000+01:00)

console.log(zoned.zone)
// 输出: TimeZone.Offset(+01:00)

在这里，系统的时区（CET，1月份为 UTC+1）用于创建 Zoned 实例。

示例（指定命名时区）

以下示例假设代码在意大利（CET 时区）的系统上执行：

import { DateTime } from "effect"

// 使用指定的命名时区创建 Zoned DateTime
const zoned = DateTime.unsafeMakeZoned(new Date("2025-01-01 04:00:00"), {
  timeZone: "Europe/Rome"
})

console.log(zoned)
// 输出: DateTime.Zoned(2025-01-01T04:00:00.000+01:00[Europe/Rome])

console.log(zoned.zone)
// 输出: TimeZone.Named(Europe/Rome)

在这种情况下，明确提供了 "Europe/Rome" 时区，导致 Zoned 实例绑定到此命名时区。

默认情况下，输入日期被视为 UTC 值，然后针对指定时区进行调整。要将输入日期解释为在指定时区中，您可以使用 adjustForTimeZone 选项。

示例（调整时区解释）

以下示例假设代码在意大利（CET 时区）的系统上执行：

import { DateTime } from "effect"

// 将输入日期解释为在指定时区中
const zoned = DateTime.unsafeMakeZoned(new Date("2025-01-01 04:00:00"), {
  timeZone: "Europe/Rome",
  adjustForTimeZone: true
})

console.log(zoned)
// 输出: DateTime.Zoned(2025-01-01T03:00:00.000+01:00[Europe/Rome])

console.log(zoned.zone)
// 输出: TimeZone.Named(Europe/Rome)

解释

• 不使用 adjustForTimeZone：输入日期被解释为 UTC，然后调整到指定时区。例如，UTC 中的 2025-01-01 04:00:00 在 CET（UTC+1）中变为 2025-01-01T04:00:00.000+01:00。
• 使用 adjustForTimeZone: true：输入日期被解释为在指定时区中。例如，“Europe/Rome”（CET）中的 2025-01-01 04:00:00 被调整为其对应的 UTC 时间，结果为 2025-01-01T03:00:00.000+01:00。

makeZoned

makeZoned 函数的工作方式类似于 unsafeMakeZoned，但提供了更安全的方法。当输入无效时，它不会抛出错误，而是返回 Option<Zoned>。 如果输入无效，则返回 None。如果有效，则返回包含 Zoned 的 Some。

示例（安全地创建 Zoned DateTime）

import { DateTime, Option } from "effect"

//      ┌─── Option<Zoned>
//      ▼
const zoned = DateTime.makeZoned(new Date("2025-01-01 04:00:00"), {
  timeZone: "Europe/Rome"
})

if (Option.isSome(zoned)) {
  console.log("DateTime 是有效的")
}

makeZonedFromString

通过解析格式为 YYYY-MM-DDTHH:mm:ss.sss+HH:MM[IANA timezone identifier] 的字符串来创建 Zoned。

如果输入字符串有效，函数返回包含 Zoned 的 Some。如果输入无效，则返回 None。

示例（从字符串解析 Zoned DateTime）

import { DateTime, Option } from "effect"

//      ┌─── Option<Zoned>
//      ▼
const zoned = DateTime.makeZonedFromString(
  "2025-01-01T03:00:00.000+01:00[Europe/Rome]"
)

if (Option.isSome(zoned)) {
  console.log("DateTime 是有效的")
}

当前时间

now

使用 Clock 服务提供当前 UTC 时间作为 Effect<Utc>。

示例（获取当前 UTC 时间）

import { DateTime, Effect } from "effect"

const program = Effect.gen(function* () {
  //      ┌─── Utc
  //      ▼
  const currentTime = yield* DateTime.now
})

为什么使用 Clock 服务？

使用 Clock 服务确保时间在您的应用程序中保持一致， 这在测试环境中特别有用，您可能需要控制或模拟当前时间。

unsafeNow

使用 Date.now() 立即获取当前 UTC 时间，不使用 Clock 服务。

示例（立即获取当前 UTC 时间）

import { DateTime } from "effect"

//      ┌─── Utc
//      ▼
const currentTime = DateTime.unsafeNow()

守卫

函数	描述
isDateTime	检查值是否为 DateTime。
isTimeZone	检查值是否为 TimeZone。
isTimeZoneOffset	检查值是否为 TimeZone.Offset。
isTimeZoneNamed	检查值是否为 TimeZone.Named。
isUtc	检查 DateTime 是否为 Utc 变体。
isZoned	检查 DateTime 是否为 Zoned 变体。

示例（验证 DateTime）

import { DateTime } from "effect"

function printDateTimeInfo(x: unknown) {
  if (DateTime.isDateTime(x)) {
    console.log("This is a valid DateTime")
  } else {
    console.log("Not a DateTime")
  }
}

Time Zone Management

Function	Description
setZone	Creates a Zoned from DateTime by applying the given TimeZone.
setZoneOffset	Creates a Zoned from DateTime using a fixed offset (in ms).
setZoneNamed	Creates a Zoned from DateTime from an IANA time zone identifier or returns None if invalid.
unsafeSetZoneNamed	Creates a Zoned from DateTime from an IANA time zone identifier or throws if invalid.
zoneUnsafeMakeNamed	Creates a TimeZone.Named from a IANA time zone identifier or throws if the identifier is invalid.
zoneMakeNamed	Creates a TimeZone.Named from a IANA time zone identifier or returns None if invalid.
zoneMakeNamedEffect	Creates a Effect<TimeZone.Named, IllegalArgumentException> from a IANA time zone identifier failing with IllegalArgumentException if invalid
zoneMakeOffset	Creates a TimeZone.Offset from a numeric offset in milliseconds.
zoneMakeLocal	Creates a TimeZone.Named from the system’s local time zone.
zoneFromString	Attempts to parse a time zone from a string, returning None if invalid.
zoneToString	Returns a string representation of a TimeZone.

Example (Applying a Time Zone to a DateTime)

import { DateTime } from "effect"

// Create a UTC DateTime
//
//     ┌─── Utc
//     ▼
const utc = DateTime.unsafeMake("2024-01-01")

// Create a named time zone for New York
//
//      ┌─── TimeZone.Named
//      ▼
const zoneNY = DateTime.zoneUnsafeMakeNamed("America/New_York")

// Apply it to the DateTime
//
//      ┌─── Zoned
//      ▼
const zoned = DateTime.setZone(utc, zoneNY)

console.log(zoned)
// Output: DateTime.Zoned(2023-12-31T19:00:00.000-05:00[America/New_York])

zoneFromString

Parses a string to create a DateTime.TimeZone.

This function attempts to interpret the input string as either:

• A numeric time zone offset (e.g., “GMT”, “+01:00”)
• An IANA time zone identifier (e.g., “Europe/London”)

If the string matches an offset format, it is converted into a TimeZone.Offset. Otherwise, it attempts to create a TimeZone.Named using the input.

If the input string is invalid, Option.none() is returned.

Example (Parsing a Time Zone from a String)

import { DateTime, Option } from "effect"

// Attempt to parse a numeric offset
const offsetZone = DateTime.zoneFromString("+01:00")
console.log(Option.isSome(offsetZone))
// Output: true

// Attempt to parse an IANA time zone
const namedZone = DateTime.zoneFromString("Europe/London")
console.log(Option.isSome(namedZone))
// Output: true

// Invalid input
const invalidZone = DateTime.zoneFromString("Invalid/Zone")
console.log(Option.isSome(invalidZone))
// Output: false

Comparisons

Function	Description
distance	Returns the difference (in ms) between two DateTimes.
distanceDurationEither	Returns a Left or Right Duration depending on order.
distanceDuration	Returns a Duration indicating how far apart two times are.
min	Returns the earlier of two DateTime values.
max	Returns the later of two DateTime values.
greaterThan, greaterThanOrEqualTo, etc.	Checks ordering between two DateTime values.
between	Checks if a DateTime lies within the given bounds.
isFuture, isPast, unsafeIsFuture, etc.	Checks if a DateTime is in the future or past.

Example (Finding the Distance Between Two DateTimes)

import { DateTime } from "effect"

const utc1 = DateTime.unsafeMake("2025-01-01T00:00:00Z")
const utc2 = DateTime.add(utc1, { days: 1 })

console.log(DateTime.distance(utc1, utc2))
// Output: 86400000 (one day)

console.log(DateTime.distanceDurationEither(utc1, utc2))
/*
Output:
{
  _id: 'Either',
  _tag: 'Right',
  right: { _id: 'Duration', _tag: 'Millis', millis: 86400000 }
}
*/

console.log(DateTime.distanceDuration(utc1, utc2))
// Output: { _id: 'Duration', _tag: 'Millis', millis: 86400000 }

Conversions

Function	Description
toDateUtc	Returns a JavaScript Date in UTC.
toDate	Applies the time zone (if present) and converts to a JavaScript Date.
zonedOffset	For a Zoned DateTime, returns the time zone offset in ms.
zonedOffsetIso	For a Zoned DateTime, returns an ISO offset string like “+01:00”.
toEpochMillis	Returns the Unix epoch time in milliseconds.
removeTime	Returns a Utc with the time cleared (only date remains).

Parts

Function	Description
toParts	Returns time zone adjusted date parts (including weekday).
toPartsUtc	Returns UTC date parts (including weekday).
getPart / getPartUtc	Retrieves a specific part (e.g., "year" or "month") from the date.
setParts / setPartsUtc	Updates certain parts of a date, preserving or ignoring the time zone.

Example (Extracting Parts from a DateTime)

import { DateTime } from "effect"

const zoned = DateTime.setZone(
  DateTime.unsafeMake("2024-01-01"),
  DateTime.zoneUnsafeMakeNamed("Europe/Rome")
)

console.log(DateTime.getPart(zoned, "month"))
// Output: 1

Math

Function	Description
addDuration	Adds the given Duration to a DateTime.
subtractDuration	Subtracts the given Duration from a DateTime.
add	Adds numeric parts (e.g., { hours: 2 }) to a DateTime.
subtract	Subtracts numeric parts.
startOf	Moves a DateTime to the start of the given unit (e.g., the beginning of a day or month).
endOf	Moves a DateTime to the end of the given unit.
nearest	Rounds a DateTime to the nearest specified unit.

Formatting

Function	Description
format	Formats a DateTime as a string using the DateTimeFormat API.
formatLocal	Uses the system’s local time zone and locale for formatting.
formatUtc	Forces UTC formatting.
formatIntl	Uses a provided Intl.DateTimeFormat.
formatIso	Returns an ISO 8601 string in UTC.
formatIsoDate	Returns an ISO date string, adjusted for the time zone.
formatIsoDateUtc	Returns an ISO date string in UTC.
formatIsoOffset	Formats a Zoned as a string with an offset like “+01:00”.
formatIsoZoned	Formats a Zoned in the form YYYY-MM-DDTHH:mm:ss.sss+HH:MM[Zone].

Layers for Current Time Zone

Function	Description
CurrentTimeZone	A service tag for the current time zone.
setZoneCurrent	Sets a DateTime to use the current time zone.
withCurrentZone	Provides an effect with a specified time zone.
withCurrentZoneLocal	Uses the system’s local time zone for the effect.
withCurrentZoneOffset	Uses a fixed offset (in ms) for the effect.
withCurrentZoneNamed	Uses a named time zone identifier (e.g., “Europe/London”).
nowInCurrentZone	Retrieves the current time as a Zoned in the configured time zone.
layerCurrentZone	Creates a Layer providing the CurrentTimeZone service.
layerCurrentZoneOffset	Creates a Layer from a fixed offset.
layerCurrentZoneNamed	Creates a Layer from a named time zone, failing if invalid.
layerCurrentZoneLocal	Creates a Layer from the system’s local time zone.

Example (Using the Current Time Zone in an Effect)

import { DateTime, Effect } from "effect"

// Retrieve the current time in the "Europe/London" time zone
const program = Effect.gen(function* () {
  const zonedNow = yield* DateTime.nowInCurrentZone
  console.log(zonedNow)
}).pipe(DateTime.withCurrentZoneNamed("Europe/London"))

Effect.runFork(program)
/*
Example Output:
DateTime.Zoned(2025-01-06T18:36:38.573+00:00[Europe/London])
*/