DateTime

Works with absolute instants, UTC date-times, zoned date-times, and time zones.

A DateTime always represents an absolute point in time with epoch milliseconds. It may also carry a TimeZone for calendar parts, formatting, and zone-aware transformations. This module includes constructors, time-zone helpers, comparisons, date arithmetic, current-time effects, and formatting functions.

96 exports Since v3.6.0 Source

Accessors

nowInCurrentZone

Since v3.6.0

Gets the current time as a DateTime.Zoned, using the CurrentTimeZone.

Signature

declare const nowInCurrentZone: Effect.Effect<Zoned, never, CurrentTimeZone>

Example Getting the current time in the current zone

import { DateTime, Effect } from "effect"

await Effect.runPromise(Effect.gen(function*() {
  return DateTime.zoneToString((yield* DateTime.nowInCurrentZone).zone)
}).pipe(DateTime.withCurrentZoneNamed("Europe/London"))) // => "Europe/London"

setZoneCurrent

Since v3.6.0

Sets the time zone of a DateTime to the current time zone, which is determined by the CurrentTimeZone service.

Signature

declare function setZoneCurrent(self: DateTime): Effect<Zoned, never, CurrentTimeZone>

Example Setting the current time zone

import { DateTime, Effect } from "effect"

await Effect.runPromise(Effect.gen(function*() {
  const zoned = yield* DateTime.setZoneCurrent(DateTime.makeUnsafe("2024-01-01"))
  return DateTime.zoneToString(zoned.zone)
}).pipe(DateTime.withCurrentZoneNamed("Europe/London"))) // => "Europe/London"

Comparisons

between

Since v3.6.0

Checks whether a DateTime is between two other DateTime values (inclusive).

Signature

declare const between: {
  (options: {
    maximum: DateTime;
    minimum: DateTime;
  }): (self: DateTime) => boolean;
  (self: DateTime, options: {
    maximum: DateTime;
    minimum: DateTime;
  }): boolean;
}

Example Checking whether a DateTime is within bounds

import { DateTime } from "effect"

const min = DateTime.makeUnsafe("2024-01-01")
const max = DateTime.makeUnsafe("2024-12-31")
const date = DateTime.makeUnsafe("2024-06-15")

DateTime.between(date, { minimum: min, maximum: max }) // => true

distance

Since v3.6.0

Computes the difference between two DateTime values, returning a Duration representing the amount of time between them.

Details

If other is after self, the result will be a positive Duration. If other is before self, the result will be a negative Duration. If they are equal, the result will be a Duration of zero.

Signature

declare const distance: {
  (other: DateTime): (self: DateTime) => Duration;
  (self: DateTime, other: DateTime): Duration;
}

Example Measuring distance between DateTime values

import { DateTime, Duration } from "effect"

const start = DateTime.makeUnsafe("2024-01-01T00:00:00Z")
const end = DateTime.add(start, { minutes: 1 })

DateTime.distance(start, end) // => Duration.minutes(1)

isFuture

Since v3.6.0

Checks effectfully if a DateTime is in the future compared to the current time.

Details

This is an effectful operation that uses the current time from the Clock service.

Signature

declare const isFuture: (self: DateTime) => Effect.Effect<boolean>

Example Checking future DateTime values effectfully

import { DateTime, Effect } from "effect"
import { TestClock } from "effect/testing"

const futureDate = DateTime.makeUnsafe(1)
await Effect.runPromise(Effect.provide(DateTime.isFuture(futureDate), TestClock.layer())) // => true

isFutureUnsafe

Since v4.0.0

Checks synchronously if a DateTime is in the future compared to the current time.

When to use

Use when checking whether a DateTime is in the future with a synchronous live-clock read and Clock-based testability is not needed.

Details

This is a synchronous version that uses Date.now() directly.

Signature

declare const isFutureUnsafe: (self: DateTime) => boolean

Example Checking future DateTime values unsafely

import { DateTime } from "effect"

const oneHourFromNow = DateTime.add(DateTime.nowUnsafe(), { hours: 1 })
DateTime.isFutureUnsafe(oneHourFromNow)

isGreaterThan

Since v4.0.0

Checks whether the first DateTime is after the second DateTime.

Signature

declare const isGreaterThan: {
  (that: DateTime): (self: DateTime) => boolean;
  (self: DateTime, that: DateTime): boolean;
}

Example Checking whether a DateTime is later

import { DateTime } from "effect"

const date1 = DateTime.makeUnsafe("2024-02-01")
const date2 = DateTime.makeUnsafe("2024-01-01")

DateTime.isGreaterThan(date1, date2) // => true
DateTime.isGreaterThan(date2, date1) // => false

isGreaterThanOrEqualTo

Since v4.0.0

Checks whether the first DateTime is after or equal to the second DateTime.

Signature

declare const isGreaterThanOrEqualTo: {
  (that: DateTime): (self: DateTime) => boolean;
  (self: DateTime, that: DateTime): boolean;
}

Example Checking whether a DateTime is later or equal

import { DateTime } from "effect"

const date1 = DateTime.makeUnsafe("2024-01-01")
const date2 = DateTime.makeUnsafe("2024-01-01")
const date3 = DateTime.makeUnsafe("2024-02-01")

DateTime.isGreaterThanOrEqualTo(date1, date2) // => true
DateTime.isGreaterThanOrEqualTo(date3, date1) // => true
DateTime.isGreaterThanOrEqualTo(date1, date3) // => false

isLessThan

Since v4.0.0

Checks whether the first DateTime is before the second DateTime.

Signature

declare const isLessThan: {
  (that: DateTime): (self: DateTime) => boolean;
  (self: DateTime, that: DateTime): boolean;
}

Example Checking whether a DateTime is earlier

import { DateTime } from "effect"

const date1 = DateTime.makeUnsafe("2024-01-01")
const date2 = DateTime.makeUnsafe("2024-02-01")

DateTime.isLessThan(date1, date2) // => true
DateTime.isLessThan(date2, date1) // => false

isLessThanOrEqualTo

Since v4.0.0

Checks whether the first DateTime is before or equal to the second DateTime.

Signature

declare const isLessThanOrEqualTo: {
  (that: DateTime): (self: DateTime) => boolean;
  (self: DateTime, that: DateTime): boolean;
}

Example Checking whether a DateTime is earlier or equal

import { DateTime } from "effect"

const date1 = DateTime.makeUnsafe("2024-01-01")
const date2 = DateTime.makeUnsafe("2024-01-01")
const date3 = DateTime.makeUnsafe("2024-02-01")

DateTime.isLessThanOrEqualTo(date1, date2) // => true
DateTime.isLessThanOrEqualTo(date1, date3) // => true
DateTime.isLessThanOrEqualTo(date3, date1) // => false

isPast

Since v3.6.0

Checks effectfully if a DateTime is in the past compared to the current time.

Details

This is an effectful operation that uses the current time from the Clock service.

Signature

declare const isPast: (self: DateTime) => Effect.Effect<boolean>

Example Checking past DateTime values effectfully

import { DateTime, Effect } from "effect"
import { TestClock } from "effect/testing"

const pastDate = DateTime.makeUnsafe(-1)
await Effect.runPromise(Effect.provide(DateTime.isPast(pastDate), TestClock.layer())) // => true

isPastUnsafe

Since v4.0.0

Checks synchronously if a DateTime is in the past compared to the current time.

When to use

Use when checking whether a DateTime is in the past with a synchronous live-clock read and Clock-based testability is not needed.

Details

This is a synchronous version that uses Date.now() directly.

Signature

declare const isPastUnsafe: (self: DateTime) => boolean

Example Checking past DateTime values unsafely

import { DateTime } from "effect"

const oneHourAgo = DateTime.subtract(DateTime.nowUnsafe(), { hours: 1 })
DateTime.isPastUnsafe(oneHourAgo)

max

Since v3.6.0

Returns the later of two DateTime values.

Signature

declare const max: {
  <That extends DateTime>(that: That): <Self extends DateTime>(self: Self) => That | Self;
  <Self extends DateTime, That extends DateTime>(self: Self, that: That): Self | That;
}

Example Selecting the later DateTime

import { DateTime } from "effect"

const date1 = DateTime.makeUnsafe("2024-01-01")
const date2 = DateTime.makeUnsafe("2024-02-01")

DateTime.max(date1, date2) // => DateTime.makeUnsafe("2024-02-01")

min

Since v3.6.0

Returns the earlier of two DateTime values.

Signature

declare const min: {
  <That extends DateTime>(that: That): <Self extends DateTime>(self: Self) => That | Self;
  <Self extends DateTime, That extends DateTime>(self: Self, that: That): Self | That;
}

Example Selecting the earlier DateTime

import { DateTime } from "effect"

const date1 = DateTime.makeUnsafe("2024-01-01")
const date2 = DateTime.makeUnsafe("2024-02-01")

DateTime.min(date1, date2) // => DateTime.makeUnsafe("2024-01-01")

Constructors

fromDateUnsafe

Since v4.0.0

Create a DateTime from a Date.

Details

If the Date is invalid, an IllegalArgumentError will be thrown.

Signature

declare const fromDateUnsafe: (date: Date) => Utc

Example Creating DateTime values from Dates

import { DateTime } from "effect"

DateTime.fromDateUnsafe(new Date("2024-01-01T12:00:00Z")) // => DateTime.makeUnsafe("2024-01-01T12:00:00Z")

fromEpochSeconds

Since v4.0.0

Creates a DateTime.Utc from the number of seconds since the Unix epoch.

Signature

declare const fromEpochSeconds: (seconds: number) => Utc

Example Creating from epoch seconds

import { DateTime } from "effect"

DateTime.fromEpochSeconds(1704067200).toJSON() // => "2024-01-01T00:00:00.000Z"

make

Since v3.6.0

Creates a DateTime safely from supported input values.

Details

A DateTime
A JavaScript Date
The number of milliseconds since the Unix epoch
An object with date and time parts
A string that can be parsed as a date

Returns Some with the constructed DateTime when the input is valid, or None when construction would fail, including invalid Date instances or unparseable strings.

Signature

declare const make: <A extends DateTime.Input>(input: A) => Option.Option<DateTime.PreserveZone<A>>

Example Creating optional DateTime values

import { DateTime, Option } from "effect"

// from Date
DateTime.make(new Date("2024-01-01T12:00:00Z")) // => Option.some(DateTime.makeUnsafe("2024-01-01T12:00:00Z"))

// from parts
DateTime.make({ year: 2024 }) // => Option.some(DateTime.makeUnsafe("2024-01-01T00:00:00Z"))

// from string
DateTime.make("2024-01-01") // => Option.some(DateTime.makeUnsafe("2024-01-01T00:00:00Z"))

DateTime.make("not a date") // => Option.none()

makeUnsafe

Since v4.0.0

Create a DateTime from supported input values.

When to use

Use when creating a DateTime from trusted input and construction failures should throw an IllegalArgumentError instead of returning Option.none.

Details

A DateTime
A Date instance (invalid dates will throw an IllegalArgumentError)
The number of milliseconds since the Unix epoch
An object with the parts of a date
A string that can be parsed by Date.parse

Signature

declare const makeUnsafe: <A extends DateTime.Input>(input: A) => DateTime.PreserveZone<A>

Example Creating DateTime values unsafely

import { DateTime } from "effect"

// from Date
DateTime.makeUnsafe(new Date("2024-01-01T12:00:00Z")) // => DateTime.makeUnsafe("2024-01-01T12:00:00Z")

// from parts
DateTime.makeUnsafe({ year: 2024 }) // => DateTime.makeUnsafe("2024-01-01T00:00:00Z")

// from string
DateTime.makeUnsafe("2024-01-01") // => DateTime.makeUnsafe("2024-01-01T00:00:00Z")

makeZoned

Since v3.6.0

Creates a DateTime.Zoned safely from an input and a time zone.

Details

By default, the input is interpreted as a UTC instant and the time zone is attached without changing that instant. When adjustForTimeZone is true, the input is interpreted as wall-clock time in the target zone.

When adjustForTimeZone is true, disambiguation controls daylight-saving gaps and repeated times:

"compatible" (default): chooses the earlier occurrence for repeated times and the later interpretation for gaps
"earlier": chooses the earlier possible instant
"later": chooses the later possible instant
"reject": rejects ambiguous or nonexistent wall-clock times

Returns Some when construction succeeds, or None when the input, time zone, or disambiguation cannot be resolved.

Signature

declare const makeZoned: (input: DateTime.Input, options?: {
  readonly adjustForTimeZone?: boolean;
  readonly disambiguation?: Disambiguation;
  readonly timeZone?: number | string | TimeZone;
}) => Option.Option<Zoned>

Example Creating optional zoned DateTime values

import { DateTime, Option } from "effect"

const result = DateTime.makeZoned("2024-06-15T14:30:00Z", {
  timeZone: "Europe/London"
})

result.pipe(Option.map(DateTime.formatIsoZoned)) // => Option.some("2024-06-15T15:30:00.000+01:00[Europe/London]")

makeZonedFromString

Since v3.6.0

Parses an ISO zoned date-time string into a DateTime.Zoned safely.

Details

Accepts named-zone strings such as YYYY-MM-DDTHH:mm:ss.sss+HH:MM[Time/Zone] and offset-only strings such as YYYY-MM-DDTHH:mm:ss.sss+HH:MM. Returns None when the input cannot be parsed.

Signature

declare const makeZonedFromString: (input: string) => Option.Option<Zoned>

Example Parsing zoned DateTime strings

import { DateTime, Option } from "effect"

DateTime.makeZonedFromString(
  "2024-01-01T12:00:00+02:00[Europe/Berlin]"
).pipe(Option.map(DateTime.formatIsoZoned)) // => Option.some("2024-01-01T11:00:00.000+01:00[Europe/Berlin]")

DateTime.makeZonedFromString("2024-01-01T12:00:00Z") // => Option.none()
DateTime.makeZonedFromString("invalid") // => Option.none()

makeZonedUnsafe

Since v4.0.0

Create a DateTime.Zoned using DateTime.makeUnsafe and a time zone.

When to use

Use when the date/time input and zone options are trusted and invalid or rejected ambiguous times should throw instead of returning Option.none.

Details

The input is treated as UTC and then the time zone is attached, unless adjustForTimeZone is set to true. In that case, the input is treated as already in the time zone.

When adjustForTimeZone is true and ambiguous times occur during DST transitions, the disambiguation option controls how to resolve the ambiguity:

compatible (default): Choose earlier time for repeated times, later for gaps
earlier: Always choose the earlier of two possible times
later: Always choose the later of two possible times
reject: Throw an error when ambiguous times are encountered

Signature

declare const makeZonedUnsafe: (input: DateTime.Input, options?: {
  readonly adjustForTimeZone?: boolean;
  readonly disambiguation?: Disambiguation;
  readonly timeZone?: number | string | TimeZone;
}) => Zoned

Example Creating zoned DateTime values unsafely

import { DateTime } from "effect"

const zoned = DateTime.makeZonedUnsafe("2024-06-15T14:30:00Z", {
  timeZone: "Europe/London"
})

DateTime.formatIsoZoned(zoned) // => "2024-06-15T15:30:00.000+01:00[Europe/London]"

now

Since v3.6.0

Gets the current time using the Clock service and converts it to a DateTime.

Signature

declare const now: Effect.Effect<Utc>

Example Getting the current DateTime

import { DateTime, Effect } from "effect"
import { TestClock } from "effect/testing"

await Effect.runPromise(Effect.map(DateTime.now, DateTime.isDateTime)) // => true

nowAsDate

Since v3.14.0

Gets the current time from the Clock service and returns it as a JavaScript Date.

Signature

declare const nowAsDate: Effect.Effect<Date>

Example Getting the current Date

import { DateTime, Effect } from "effect"
import { TestClock } from "effect/testing"

await Effect.runPromise(Effect.map(DateTime.nowAsDate, (now) => now instanceof Date)) // => true

nowUnsafe

Since v4.0.0

Gets the current time using Date.now.

When to use

Use when synchronous wall-clock access outside an Effect program is acceptable and testability through the Clock service is not needed.

Details

This is a synchronous version of now that directly uses Date.now() instead of the Effect Clock service.

Signature

declare const nowUnsafe: LazyArg<Utc>

Example Getting the current DateTime unsafely

import { DateTime } from "effect"

Number.isFinite(DateTime.toEpochMillis(DateTime.nowUnsafe())) // => true

zoneMakeLocal

Since v3.6.0

Create a named time zone from the system's local time zone.

Details

This uses the system's configured time zone, which may vary depending on the runtime environment.

Signature

declare const zoneMakeLocal: () => TimeZone.Named

Example Creating local time zones

import { DateTime } from "effect"

DateTime.isTimeZoneNamed(DateTime.zoneMakeLocal()) // => true

zoneMakeNamed

Since v3.6.0

Creates a named time zone safely from an IANA time zone identifier.

Details

If the time zone is invalid, None will be returned.

Signature

declare const zoneMakeNamed: (zoneId: string) => Option.Option<TimeZone.Named>

Example Creating optional named time zones

import { DateTime, Option } from "effect"

DateTime.zoneMakeNamed("Europe/London").pipe(Option.map(DateTime.zoneToString)) // => Option.some("Europe/London")
DateTime.zoneMakeNamed("Invalid/Zone") // => Option.none()

zoneMakeNamedEffect

Since v3.6.0

Creates a named time zone effectfully from an IANA time zone identifier.

When to use

Use when invalid IANA zone ids should fail in the Effect error channel instead of returning Option.none or throwing.

Signature

declare const zoneMakeNamedEffect: (zoneId: string) => Effect.Effect<TimeZone.Named, IllegalArgumentError>

Example Creating named time zones effectfully

import { DateTime, Effect } from "effect"

const program = Effect.gen(function*() {
  const zone = yield* DateTime.zoneMakeNamedEffect("Europe/London")
  const now = yield* DateTime.now
  return DateTime.setZone(now, zone)
})

DateTime.zoneToString((await Effect.runPromise(program)).zone) // => "Europe/London"

zoneMakeNamedUnsafe

Since v4.0.0

Attempts to create a named time zone from an IANA time zone identifier.

When to use

Use when the IANA zone id is trusted and invalid zones should throw instead of returning Option.none or failing in Effect.

Details

If the time zone is invalid, an IllegalArgumentError will be thrown.

Signature

declare const zoneMakeNamedUnsafe: (zoneId: string) => TimeZone.Named

Example Creating named time zones unsafely

import { DateTime } from "effect"

DateTime.zoneToString(DateTime.zoneMakeNamedUnsafe("Europe/London")) // => "Europe/London"
DateTime.zoneToString(DateTime.zoneMakeNamedUnsafe("Asia/Tokyo")) // => "Asia/Tokyo"

// This would throw an IllegalArgumentError:
// DateTime.zoneMakeNamedUnsafe("Invalid/Zone")

zoneMakeOffset

Since v3.6.0

Create a fixed offset time zone.

Details

The offset is specified in milliseconds from UTC. Positive values are ahead of UTC, negative values are behind UTC.

Signature

declare const zoneMakeOffset: (offset: number) => TimeZone.Offset

Example Creating fixed-offset time zones

import { DateTime } from "effect"

// Create a time zone with +3 hours offset
const zone = DateTime.zoneMakeOffset(3 * 60 * 60 * 1000)

const dt = DateTime.makeZonedUnsafe("2024-01-01T12:00:00Z", {
  timeZone: zone
})
DateTime.formatIsoZoned(dt) // => "2024-01-01T15:00:00.000+03:00"

Converting

removeTime

Since v3.6.0

Removes the time aspect of a DateTime, first adjusting for the time zone. It will return a DateTime.Utc only containing the date.

Signature

declare const removeTime: (self: DateTime) => Utc

Example Removing time components

import { DateTime } from "effect"

// returns "2024-01-01T00:00:00Z"
DateTime.makeZonedUnsafe("2024-01-01T05:00:00Z", {
  timeZone: "Pacific/Auckland",
  adjustForTimeZone: true
}).pipe(
  DateTime.removeTime,
  DateTime.formatIso
) // => "2024-01-01T00:00:00.000Z"

toDate

Since v3.6.0

Converts a DateTime to a Date, applying the time zone first.

Details

For DateTime.Zoned, this stores the zoned wall-clock time in the returned Date's UTC fields, rather than preserving the original instant. Use toDateUtc to preserve the instant. For DateTime.Utc, this is equivalent to toDateUtc.

Signature

declare const toDate: (self: DateTime) => Date

Example Converting DateTime values to Dates

import { DateTime } from "effect"

const utc = DateTime.makeUnsafe("2024-07-01T12:00:00Z")
const zoned = DateTime.makeZonedUnsafe("2024-07-01T12:00:00Z", {
  timeZone: "Europe/London"
})

DateTime.toDate(utc).toISOString() // => "2024-07-01T12:00:00.000Z"
DateTime.toDate(zoned).toISOString() // => "2024-07-01T13:00:00.000Z"
DateTime.toDateUtc(zoned).toISOString() // => "2024-07-01T12:00:00.000Z"

toDateUtc

Since v3.6.0

Gets the UTC Date of a DateTime.

Details

This preserves the original instant, regardless of any time zone information.

Signature

declare const toDateUtc: (self: DateTime) => Date

Example Converting DateTime values to UTC Dates

import { DateTime } from "effect"

const dt = DateTime.makeZonedUnsafe("2024-01-01T12:00:00Z", {
  timeZone: "Europe/London"
})

DateTime.toDateUtc(dt).toISOString() // => "2024-01-01T12:00:00.000Z"

toEpochMillis

Since v3.6.0

Gets the milliseconds since the Unix epoch of a DateTime.

Details

This returns the UTC timestamp regardless of any time zone information.

Signature

declare const toEpochMillis: (self: DateTime) => number

Example Reading epoch milliseconds

import { DateTime } from "effect"

const dt = DateTime.makeUnsafe("2024-01-01T00:00:00Z")
DateTime.toEpochMillis(dt) // => 1704067200000

toEpochSeconds

Since v4.0.0

Converts a DateTime to the number of seconds since the Unix epoch.

Details

This returns the UTC timestamp regardless of any time zone information. The result is floored to the nearest second.

Signature

declare const toEpochSeconds: (self: DateTime) => number

Example Reading epoch seconds

import { DateTime } from "effect"

const dt = DateTime.makeUnsafe("2024-01-01T00:00:00Z")
DateTime.toEpochSeconds(dt) // => 1704067200

toUtc

Since v3.13.0

Converts a DateTime to a UTC DateTime.

When to use

Use to represent the same instant in UTC instead of its current time zone.

Details

The returned value keeps the same epoch milliseconds and changes only the DateTime representation to UTC.

Signature

declare const toUtc: (self: DateTime) => Utc

Example Converting DateTime values to UTC

import { DateTime } from "effect"

const now = DateTime.makeZonedUnsafe({ year: 2024 }, {
  timeZone: "Europe/London"
})

// set as UTC
const utc: DateTime.Utc = DateTime.toUtc(now)
utc // => DateTime.makeUnsafe("2024-01-01T00:00:00Z")

zonedOffset

Since v3.6.0

Computes the time zone offset of a DateTime.Zoned in milliseconds.

Details

Returns the offset from UTC in milliseconds. Positive values indicate time zones ahead of UTC, negative values indicate time zones behind UTC.

Signature

declare const zonedOffset: (self: Zoned) => number

Example Reading zoned offsets

import { DateTime } from "effect"

const zoned = DateTime.makeZonedUnsafe("2024-01-01T12:00:00Z", {
  timeZone: "Europe/London"
})

DateTime.zonedOffset(zoned) // => 0

zonedOffsetIso

Since v3.6.0

Formats the time zone offset of a DateTime.Zoned as an ISO string.

Details

The offset is formatted as "±HH:MM".

Signature

declare const zonedOffsetIso: (self: Zoned) => string

Example Formatting zoned offsets

import { DateTime } from "effect"

const zoned = DateTime.makeZonedUnsafe("2024-01-01T12:00:00Z", {
  timeZone: DateTime.zoneMakeOffset(3 * 60 * 60 * 1000) // +3 hours
})

DateTime.zonedOffsetIso(zoned) // => "+03:00"

Decoding

zoneFromString

Since v3.6.0

Tries to parse a TimeZone from a string safely.

Details

Supports both IANA time zone identifiers and offset formats like "+03:00".

Signature

declare const zoneFromString: (zone: string) => Option.Option<TimeZone>

Example Parsing time zones

import { DateTime, Option } from "effect"

DateTime.zoneFromString("Europe/London").pipe(Option.map(DateTime.zoneToString)) // => Option.some("Europe/London")
DateTime.zoneFromString("+03:00").pipe(Option.map(DateTime.zoneToString)) // => Option.some("+03:00")
DateTime.zoneFromString("invalid") // => Option.none()

Encoding

zoneToString

Since v3.6.0

Formats a TimeZone as a string.

Signature

declare const zoneToString: (self: TimeZone) => string

Example Formatting time zones

import { DateTime } from "effect"

DateTime.zoneToString(DateTime.zoneMakeOffset(3 * 60 * 60 * 1000)) // => "+03:00"
DateTime.zoneToString(DateTime.zoneMakeNamedUnsafe("Europe/London")) // => "Europe/London"

Formatting

format

Since v3.6.0

Formats a DateTime with Intl.DateTimeFormat.

Details

Unless a timeZone option is supplied, UTC values are formatted in UTC and zoned values are formatted in their named zone or fixed-offset zone.

Fixed-offset zones depend on runtime support for offset timeZone identifiers. When unsupported, formatting falls back to UTC with the DateTime adjusted to the offset.

Signature

declare const format: {
  (options?: DateTimeFormatOptions & {
    readonly locale?: string;
  }): (self: DateTime) => string;
  (self: DateTime, options?: DateTimeFormatOptions & {
    readonly locale?: string;
  }): string;
}

Example Formatting DateTime values with Intl options

import { DateTime } from "effect"

const dt = DateTime.makeZonedUnsafe("2024-06-15T14:30:00Z", {
  timeZone: "Europe/London"
})

DateTime.format(dt, {
  dateStyle: "full",
  timeStyle: "short",
  locale: "en-US"
}) // => "Saturday, June 15, 2024 at 3:30 PM"

formatIntl

Since v3.6.0

Formats a DateTime as a string using the Intl.DateTimeFormat API.

When to use

Use when you already have an Intl.DateTimeFormat and want it to control the locale, time zone, and formatting options.

Details

The formatter receives the DateTime epoch milliseconds. Any time zone conversion comes from the supplied formatter.

See

formatUtc for formatting with options forced to UTC
formatIso for stable ISO formatting

Signature

declare const formatIntl: {
  (format: DateTimeFormat): (self: DateTime) => string;
  (self: DateTime, format: DateTimeFormat): string;
}

Example Formatting DateTime values with custom formatters

import { DateTime } from "effect"

const dt = DateTime.makeUnsafe("2024-06-15T14:30:00Z")

// Create a custom formatter
const formatter = new Intl.DateTimeFormat("de-DE", {
  year: "numeric",
  month: "long",
  day: "numeric",
  hour: "2-digit",
  minute: "2-digit",
  timeZone: "Europe/Berlin"
})

DateTime.formatIntl(dt, formatter).length > 0 // => true

formatIso

Since v3.6.0

Formats a DateTime as a UTC ISO string.

Details

Always returns the UTC representation in ISO 8601 format, ignoring any time zone.

Signature

declare const formatIso: (self: DateTime) => string

Example Formatting DateTime values as ISO strings

import { DateTime } from "effect"

DateTime.formatIso(DateTime.makeUnsafe("2024-01-01T12:30:45.123Z")) // => "2024-01-01T12:30:45.123Z"

const zoned = DateTime.makeZonedUnsafe("2024-01-01T12:30:45.123Z", {
  timeZone: "Europe/London"
})
DateTime.formatIso(zoned) // => "2024-01-01T12:30:45.123Z"

formatIsoDate

Since v3.6.0

Formats a DateTime as a time zone adjusted ISO date string.

Details

Returns only the date part (YYYY-MM-DD) after applying time zone adjustments.

Signature

declare const formatIsoDate: (self: DateTime) => string

Example Formatting DateTime values as ISO dates

import { DateTime } from "effect"

const dt = DateTime.makeUnsafe("2024-01-01T23:30:00Z")
DateTime.formatIsoDate(dt) // => "2024-01-01"

const zoned = DateTime.makeZonedUnsafe("2024-01-01T23:30:00Z", {
  timeZone: "Pacific/Auckland" // UTC+12/13
})
DateTime.formatIsoDate(zoned) // => "2024-01-02"

formatIsoDateUtc

Since v3.6.0

Formats a DateTime as a UTC ISO date string.

Details

Returns only the date part (YYYY-MM-DD) in UTC, ignoring any time zone.

Signature

declare const formatIsoDateUtc: (self: DateTime) => string

Example Formatting DateTime values as UTC ISO dates

import { DateTime } from "effect"

const dt = DateTime.makeUnsafe("2024-01-01T23:30:00Z")
DateTime.formatIsoDateUtc(dt) // => "2024-01-01"

const zoned = DateTime.makeZonedUnsafe("2024-01-01T23:30:00Z", {
  timeZone: "Pacific/Auckland"
})
DateTime.formatIsoDateUtc(zoned) // => "2024-01-01"

formatIsoOffset

Since v3.6.0

Formats a DateTime.Zoned as an ISO string with an offset.

Details

For DateTime.Utc, returns the same as formatIso. For DateTime.Zoned, includes the time zone offset in the format.

Signature

declare const formatIsoOffset: (self: DateTime) => string

Example Formatting DateTime values with offsets

import { DateTime } from "effect"

const utc = DateTime.makeUnsafe("2024-01-01T12:00:00Z")
DateTime.formatIsoOffset(utc) // => "2024-01-01T12:00:00.000Z"

const zoned = DateTime.makeZonedUnsafe("2024-01-01T12:00:00Z", {
  timeZone: DateTime.zoneMakeOffset(3 * 60 * 60 * 1000)
})
DateTime.formatIsoOffset(zoned) // => "2024-01-01T15:00:00.000+03:00"

formatIsoZoned

Since v3.6.0

Formats a DateTime.Zoned as a string.

Details

It uses the format: YYYY-MM-DDTHH:mm:ss.sss+HH:MM[Time/Zone].

Signature

declare const formatIsoZoned: (self: Zoned) => string

Example Formatting zoned DateTime values

import { DateTime } from "effect"

const zoned = DateTime.makeZonedUnsafe("2024-06-15T14:30:45.123Z", {
  timeZone: "Europe/London"
})

DateTime.formatIsoZoned(zoned) // => "2024-06-15T15:30:45.123+01:00[Europe/London]"

const offsetZone = DateTime.makeZonedUnsafe("2024-06-15T14:30:45.123Z", {
  timeZone: DateTime.zoneMakeOffset(3 * 60 * 60 * 1000)
})

DateTime.formatIsoZoned(offsetZone) // => "2024-06-15T17:30:45.123+03:00"

formatLocal

Since v3.6.0

Formats a DateTime with Intl.DateTimeFormat using the system local time zone and locale.

Signature

declare const formatLocal: {
  (options?: DateTimeFormatOptions & {
    readonly locale?: string;
  }): (self: DateTime) => string;
  (self: DateTime, options?: DateTimeFormatOptions & {
    readonly locale?: string;
  }): string;
}

Example Formatting DateTime values locally

import { DateTime } from "effect"

const dt = DateTime.makeUnsafe("2024-06-15T14:30:00Z")

// Uses system local time zone and locale
DateTime.formatLocal(dt, {
  year: "numeric",
  month: "long",
  day: "numeric",
  hour: "2-digit",
  minute: "2-digit"
})

formatUtc

Since v3.6.0

Formats a DateTime with Intl.DateTimeFormat using the UTC time zone.

Details

This forces the time zone to be UTC.

Signature

declare const formatUtc: {
  (options?: DateTimeFormatOptions & {
    readonly locale?: string;
  }): (self: DateTime) => string;
  (self: DateTime, options?: DateTimeFormatOptions & {
    readonly locale?: string;
  }): string;
}

Example Formatting DateTime values in UTC

import { DateTime } from "effect"

const dt = DateTime.makeZonedUnsafe("2024-06-15T14:30:00Z", {
  timeZone: "Europe/London"
})

// Force UTC formatting regardless of time zone
DateTime.formatUtc(dt, {
  year: "numeric",
  month: "2-digit",
  day: "2-digit",
  hour: "2-digit",
  minute: "2-digit",
  timeZoneName: "short"
})

Getters

getPart

Since v3.6.0

Gets one time-zone-adjusted part of a DateTime as a number.

Details

The part will be time zone adjusted.

Signature

declare const getPart: {
  (part: keyof PartsWithWeekday): (self: DateTime) => number;
  (self: DateTime, part: keyof PartsWithWeekday): number;
}

Example Reading DateTime parts by key

import { DateTime } from "effect"

const dateTime = DateTime.makeZonedUnsafe({ year: 2024 }, {
  timeZone: "Europe/London"
})
DateTime.getPart(dateTime, "year") // => 2024

getPartUtc

Since v3.6.0

Gets one UTC part of a DateTime as a number.

Details

The part will be in the UTC time zone.

Signature

declare const getPartUtc: {
  (part: keyof PartsWithWeekday): (self: DateTime) => number;
  (self: DateTime, part: keyof PartsWithWeekday): number;
}

Example Reading UTC DateTime parts by key

import { DateTime } from "effect"

const dateTime = DateTime.makeUnsafe({ year: 2024 })
DateTime.getPartUtc(dateTime, "year") // => 2024

toParts

Since v3.6.0

Gets the time-zone-adjusted parts of a DateTime as an object.

Details

The parts will be time zone adjusted if the DateTime is zoned.

Signature

declare const toParts: (self: DateTime) => DateTime.PartsWithWeekday

Example Reading DateTime parts

import { DateTime } from "effect"

const dt = DateTime.makeUnsafe("2024-01-01T12:30:45.123Z")
const parts = DateTime.toParts(dt)

const selectedParts = [parts.year, parts.month, parts.day, parts.hour] // => [2024, 1, 1, 12]

toPartsUtc

Since v3.6.0

Gets the UTC parts of a DateTime as an object.

Details

The parts will always be in UTC, ignoring any time zone information.

Signature

declare const toPartsUtc: (self: DateTime) => DateTime.PartsWithWeekday

Example Reading UTC DateTime parts

import { DateTime } from "effect"

const zoned = DateTime.makeZonedUnsafe("2024-01-01T12:30:45.123Z", {
  timeZone: "Europe/London"
})
const parts = DateTime.toPartsUtc(zoned)

const selectedParts = [parts.year, parts.month, parts.day, parts.hour] // => [2024, 1, 1, 12]

Guards

isDateTime

Since v3.6.0

Checks whether a value is a DateTime.

When to use

Use to narrow an unknown value before treating it as a DateTime.

See

isUtc for narrowing a known DateTime to UTC
isZoned for narrowing a known DateTime to zoned

Signature

declare const isDateTime: (u: unknown) => u is DateTime

isTimeZone

Since v3.6.0

Checks whether a value is a TimeZone.

When to use

Use to narrow unknown input to any TimeZone before passing it to APIs that accept either fixed-offset or named time zones.

See

isTimeZoneOffset for narrowing to fixed-offset time zones
isTimeZoneNamed for narrowing to named time zones

Signature

declare const isTimeZone: (u: unknown) => u is TimeZone

isTimeZoneNamed

Since v3.6.0

Checks whether a value is a named TimeZone (IANA time zone).

When to use

Use to narrow an unknown value to the TimeZone.Named variant before reading named-zone fields such as id.

See

isTimeZone for checking either time zone variant
isTimeZoneOffset for narrowing to fixed-offset time zones

Signature

declare const isTimeZoneNamed: (u: unknown) => u is TimeZone.Named

isTimeZoneOffset

Since v3.6.0

Checks whether a value is an offset-based TimeZone.

When to use

Use when you need to narrow an unknown or union TimeZone value to the fixed-offset variant before reading its offset in milliseconds.

See

isTimeZone for checking either time zone variant
isTimeZoneNamed for narrowing to named time zones

Signature

declare const isTimeZoneOffset: (u: unknown) => u is TimeZone.Offset

isUtc

Since v3.6.0

Checks whether a DateTime is a UTC DateTime (no time zone information).

When to use

Use to narrow a DateTime before passing it to code that requires a UTC value without an associated time zone.

See

isZoned for narrowing to zoned date-times
match for handling both UTC and zoned cases

Signature

declare const isUtc: (self: DateTime) => self is Utc

isZoned

Since v3.6.0

Checks whether a DateTime is a zoned DateTime (has time zone information).

When to use

Use to narrow a known DateTime before reading its zone or passing it to APIs that require DateTime.Zoned.

See

isUtc for narrowing to UTC date-times
match for handling both UTC and zoned cases

Signature

declare const isZoned: (self: DateTime) => self is Zoned

Instances

Equivalence

Since v3.6.0

Provides an Equivalence for comparing two DateTime values for equality.

Details

Two DateTime values are considered equivalent if they represent the same point in time, regardless of their time zone.

Signature

declare const Equivalence: Equ.Equivalence<DateTime>

Example Comparing DateTime values for equivalence

import { DateTime } from "effect"

const utc = DateTime.makeUnsafe("2024-01-01T12:00:00Z")
const zoned = DateTime.makeZonedUnsafe("2024-01-01T12:00:00Z", {
  timeZone: "Europe/London"
})

DateTime.Equivalence(utc, zoned) // => true

Order

Since v3.6.0

Provides an Order for comparing and sorting DateTime values.

Details

DateTime values are ordered by their epoch milliseconds, so earlier times come before later times regardless of time zone.

Signature

declare const Order: order.Order<DateTime>

Example Sorting DateTime values chronologically

import { Array, DateTime } from "effect"

const dates = [
  DateTime.makeUnsafe("2024-03-01"),
  DateTime.makeUnsafe("2024-01-01"),
  DateTime.makeUnsafe("2024-02-01")
]

Array.sort(dates, DateTime.Order).map(DateTime.formatIsoDateUtc) // => ["2024-01-01", "2024-02-01", "2024-03-01"]

Layers

layerCurrentZone

Since v3.6.0

Create a Layer from the given time zone.

Details

This layer provides the CurrentTimeZone service with the specified time zone.

Signature

declare const layerCurrentZone: (resource: NoInfer<TimeZone>) => Layer.Layer<CurrentTimeZone>

Example Providing current time zone layers

import { DateTime, Effect } from "effect"

const zone = DateTime.zoneMakeNamedUnsafe("Europe/London")
const layer = DateTime.layerCurrentZone(zone)

const program = Effect.gen(function*() {
  const now = yield* DateTime.nowInCurrentZone
  return DateTime.zoneToString(now.zone)
})

// Use the layer to provide the time zone
await Effect.runPromise(Effect.provide(program, layer)) // => "Europe/London"

layerCurrentZoneLocal

Since v3.6.0

Create a Layer from the system's local time zone.

Details

This layer provides the CurrentTimeZone service using the system's configured local time zone.

Signature

declare const layerCurrentZoneLocal: Layer.Layer<CurrentTimeZone>

Example Providing local time zone layers

import { DateTime, Effect } from "effect"

const program = Effect.gen(function*() {
  const now = yield* DateTime.nowInCurrentZone
  return DateTime.isZoned(now)
})

// Use the system's local time zone
await Effect.runPromise(Effect.provide(program, DateTime.layerCurrentZoneLocal)) // => true

layerCurrentZoneNamed

Since v3.6.0

Create a Layer from the given IANA time zone identifier.

Details

This layer provides the CurrentTimeZone service with a named time zone. If the time zone identifier is invalid, the layer will fail.

Signature

declare const layerCurrentZoneNamed: (zoneId: string) => Layer.Layer<CurrentTimeZone, IllegalArgumentError>

Example Providing named time zone layers

import { DateTime, Effect } from "effect"

const layer = DateTime.layerCurrentZoneNamed("Europe/London")

const program = Effect.gen(function*() {
  const now = yield* DateTime.nowInCurrentZone
  return DateTime.zoneToString(now.zone)
})

await Effect.runPromise(Effect.provide(program, layer)) // => "Europe/London"

layerCurrentZoneOffset

Since v3.6.0

Create a Layer from the given time zone offset.

Details

This layer provides the CurrentTimeZone service with a fixed offset time zone.

Signature

declare function layerCurrentZoneOffset(offset: number): Layer<CurrentTimeZone>

Example Providing fixed-offset time zone layers

import { DateTime, Effect } from "effect"

// Create a layer for UTC+3
const layer = DateTime.layerCurrentZoneOffset(3 * 60 * 60 * 1000)

const program = Effect.gen(function*() {
  const now = yield* DateTime.nowInCurrentZone
  return DateTime.zoneToString(now.zone)
})

await Effect.runPromise(Effect.provide(program, layer)) // => "+03:00"

Mapping

mapEpochMillis

Since v3.6.0

Transforms a DateTime by applying a function to the number of milliseconds since the Unix epoch.

Signature

declare const mapEpochMillis: {
  (f: (millis: number) => number): <A extends DateTime>(self: A) => A;
  <A extends DateTime>(self: A, f: (millis: number) => number): A;
}

Example Mapping epoch milliseconds

import { DateTime } from "effect"

// add 10 milliseconds
const result = DateTime.makeUnsafe(0).pipe(
  DateTime.mapEpochMillis((millis) => millis + 10)
)
result // => DateTime.makeUnsafe(10)

match

Since v3.6.0

Pattern match on a DateTime to handle Utc and Zoned cases differently.

Signature

declare const match: {
  <A, B>(options: {
    readonly onUtc: (_: Utc) => A;
    readonly onZoned: (_: Zoned) => B;
  }): (self: DateTime) => A | B;
  <A, B>(self: DateTime, options: {
    readonly onUtc: (_: Utc) => A;
    readonly onZoned: (_: Zoned) => B;
  }): A | B;
}

Example Pattern matching DateTime variants

import { DateTime } from "effect"

const dt1 = DateTime.makeUnsafe("2024-01-01T12:00:00Z") // Utc
const dt2 = DateTime.makeZonedUnsafe("2024-06-15T14:30:00Z", {
  timeZone: "Europe/London"
}) // Zoned

const result1 = DateTime.match(dt1, {
  onUtc: (utc) => `UTC: ${DateTime.formatIso(utc)}`,
  onZoned: (zoned) => `Zoned: ${DateTime.formatIsoZoned(zoned)}`
})

const result2 = DateTime.match(dt2, {
  onUtc: (utc) => `UTC: ${DateTime.formatIso(utc)}`,
  onZoned: (zoned) => `Zoned: ${DateTime.formatIsoZoned(zoned)}`
})

result1 // => "UTC: 2024-01-01T12:00:00.000Z"
result2 // => "Zoned: 2024-06-15T15:30:00.000+01:00[Europe/London]"

mutate

Since v3.6.0

Modifies a DateTime with a mutable local Date copy.

When to use

Use to adjust calendar fields in the DateTime's own time zone with an existing Date mutation API.

Details

The Date will first have the time zone applied if possible, and then be converted back to a DateTime within the same time zone.

Supports disambiguation when the new wall clock time is ambiguous.

Signature

declare const mutate: {
  (f: (date: Date) => void, options?: {
    readonly disambiguation?: Disambiguation;
  }): <A extends DateTime>(self: A) => A;
  <A extends DateTime>(self: A, f: (date: Date) => void, options?: {
    readonly disambiguation?: Disambiguation;
  }): A;
}

Example Mutating DateTime values with Dates

import { DateTime } from "effect"

const dt = DateTime.makeUnsafe("2024-01-01T12:00:00Z")

DateTime.mutate(dt, (date) => {
  date.setHours(15) // Set to 3 PM
  date.setMinutes(30) // Set to 30 minutes
})

mutateUtc

Since v3.6.0

Modifies a DateTime with a mutable UTC Date copy.

When to use

Use to adjust the instant with an existing Date mutation API that works on UTC calendar fields.

Signature

declare const mutateUtc: {
  (f: (date: Date) => void): <A extends DateTime>(self: A) => A;
  <A extends DateTime>(self: A, f: (date: Date) => void): A;
}

Example Mutating DateTime values with UTC Dates

import { DateTime } from "effect"

const dt = DateTime.makeZonedUnsafe("2024-01-01T12:00:00Z", {
  timeZone: "Europe/London"
})

const modified = DateTime.mutateUtc(dt, (date) => {
  date.setUTCHours(18) // Set UTC time to 6 PM
})

modified // => DateTime.makeZonedUnsafe("2024-01-01T18:00:00Z", { timeZone: "Europe/London" })

withDate

Since v3.6.0

Applies a function to a JavaScript Date representing the DateTime and returns the function's result.

Details

The callback receives the time-zone-adjusted wall-clock date for DateTime.Zoned values. Use DateTime.withDateUtc when the callback should receive the UTC instant.

Signature

declare const withDate: {
  <A>(f: (date: Date) => A): (self: DateTime) => A;
  <A>(self: DateTime, f: (date: Date) => A): A;
}

Example Applying time zone adjusted Dates

import { DateTime } from "effect"

// get the time zone adjusted date in milliseconds
DateTime.makeZonedUnsafe(0, { timeZone: "Europe/London" }).pipe(
  DateTime.withDate((date) => date.getTime())
) // => 3600000

withDateUtc

Since v3.6.0

Applies a function to a JavaScript Date representing the DateTime's UTC instant and returns the function's result.

Details

This ignores any associated time zone. Use DateTime.withDate when the callback should receive the time-zone-adjusted wall-clock date.

Signature

declare const withDateUtc: {
  <A>(f: (date: Date) => A): (self: DateTime) => A;
  <A>(self: DateTime, f: (date: Date) => A): A;
}

Example Applying UTC Dates

import { DateTime } from "effect"

// get the date in milliseconds
DateTime.makeUnsafe(0).pipe(
  DateTime.withDateUtc((date) => date.getTime())
) // => 0

Math

add

Since v3.6.0

Adds the given amount of unit to a DateTime.

Details

The time zone is taken into account when adding days, weeks, months, and years.

Signature

declare const add: {
  (parts: Partial<DateTime.PartsForMath>): <A extends DateTime>(self: A) => A;
  <A extends DateTime>(self: A, parts: Partial<DateTime.PartsForMath>): A;
}

Example Adding date and time parts

import { DateTime } from "effect"

// add 5 minutes
DateTime.makeUnsafe(0).pipe(
  DateTime.add({ minutes: 5 })
) // => DateTime.makeUnsafe(300000)

addDuration

Since v3.6.0

Adds the given Duration to a DateTime.

When to use

Use to move a DateTime by an elapsed duration such as minutes, seconds, or milliseconds.

Details

The duration is converted to milliseconds and added to the epoch milliseconds. Zoned values keep their original time zone.

Gotchas

This is elapsed-time arithmetic, not calendar-aware local date arithmetic. Use add when adding days, weeks, months, or years should account for the date/time zone rules.

See

add for calendar-aware date/time part arithmetic
subtractDuration for subtracting an elapsed duration

Signature

declare const addDuration: {
  (duration: Input): <A extends DateTime>(self: A) => A;
  <A extends DateTime>(self: A, duration: Input): A;
}

Example Adding durations

import { DateTime } from "effect"

// add 5 minutes
DateTime.makeUnsafe(0).pipe(
  DateTime.addDuration("5 minutes")
) // => DateTime.makeUnsafe(300000)

endOf

Since v3.6.0

Converts a DateTime to the end of the given part.

Details

If the part is week, the weekStartsOn option can be used to specify the day of the week that the week starts on. The default is 0 (Sunday).

Signature

declare const endOf: {
  (part: UnitSingular, options?: {
    readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
  }): <A extends DateTime>(self: A) => A;
  <A extends DateTime>(self: A, part: UnitSingular, options?: {
    readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
  }): A;
}

Example Rounding up DateTime values

import { DateTime } from "effect"

// returns "2024-01-01T23:59:59.999Z"
DateTime.makeUnsafe("2024-01-01T12:00:00Z").pipe(
  DateTime.endOf("day"),
) // => DateTime.makeUnsafe("2024-01-01T23:59:59.999Z")

nearest

Since v3.6.0

Converts a DateTime to the nearest given part.

Details

If the part is week, the weekStartsOn option can be used to specify the day of the week that the week starts on. The default is 0 (Sunday).

Signature

declare const nearest: {
  (part: UnitSingular, options?: {
    readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
  }): <A extends DateTime>(self: A) => A;
  <A extends DateTime>(self: A, part: UnitSingular, options?: {
    readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
  }): A;
}

Example Rounding DateTime values to nearest units

import { DateTime } from "effect"

// returns "2024-01-02T00:00:00Z"
DateTime.makeUnsafe("2024-01-01T12:01:00Z").pipe(
  DateTime.nearest("day"),
) // => DateTime.makeUnsafe("2024-01-02T00:00:00Z")

startOf

Since v3.6.0

Converts a DateTime to the start of the given part.

Details

If the part is week, the weekStartsOn option can be used to specify the day of the week that the week starts on. The default is 0 (Sunday).

Signature

declare const startOf: {
  (part: UnitSingular, options?: {
    readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
  }): <A extends DateTime>(self: A) => A;
  <A extends DateTime>(self: A, part: UnitSingular, options?: {
    readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
  }): A;
}

Example Rounding down DateTime values

import { DateTime } from "effect"

// returns "2024-01-01T00:00:00Z"
DateTime.makeUnsafe("2024-01-01T12:00:00Z").pipe(
  DateTime.startOf("day"),
) // => DateTime.makeUnsafe("2024-01-01T00:00:00Z")

subtract

Since v3.6.0

Subtracts the given amount of unit from a DateTime.

Signature

declare const subtract: {
  (parts: Partial<DateTime.PartsForMath>): <A extends DateTime>(self: A) => A;
  <A extends DateTime>(self: A, parts: Partial<DateTime.PartsForMath>): A;
}

Example Subtracting date and time parts

import { DateTime } from "effect"

// subtract 5 minutes
DateTime.makeUnsafe(0).pipe(
  DateTime.subtract({ minutes: 5 })
) // => DateTime.makeUnsafe(-300000)

subtractDuration

Since v3.6.0

Subtracts the given Duration from a DateTime.

Signature

declare const subtractDuration: {
  (duration: Input): <A extends DateTime>(self: A) => A;
  <A extends DateTime>(self: A, duration: Input): A;
}

Example Subtracting durations

import { DateTime } from "effect"

// subtract 5 minutes
DateTime.makeUnsafe(0).pipe(
  DateTime.subtractDuration("5 minutes")
) // => DateTime.makeUnsafe(-300000)

Models

DateTime

type

Since v3.6.0

A DateTime represents a point in time. It can optionally have a time zone associated with it.

Signature

type DateTime = Utc | Zoned

Disambiguation

type

Since v3.18.0

A Disambiguation is used to resolve ambiguities when a DateTime is ambiguous, such as during a daylight saving time transition.

Details

For more information, see the Temporal documentation

"compatible": (default) Behavior matching Temporal API and legacy JavaScript Date and moment.js. For repeated times, chooses the earlier occurrence. For gap times, chooses the later interpretation.
"earlier": For repeated times, always choose the earlier occurrence. For gap times, choose the time before the gap.
"later": For repeated times, always choose the later occurrence. For gap times, choose the time after the gap.
"reject": Throw an RangeError when encountering ambiguous or non-existent times.

Signature

type Disambiguation = "compatible" | "earlier" | "later" | "reject"

Example Resolving ambiguous local times

import { DateTime, Option } from "effect"

// Fall-back example: 01:30 on Nov 2, 2025 in New York happens twice
const ambiguousTime = { year: 2025, month: 11, day: 2, hour: 1, minute: 30 }
const timeZone = DateTime.zoneMakeNamedUnsafe("America/New_York")

const earlier = DateTime.makeZoned(ambiguousTime, {
  timeZone,
  adjustForTimeZone: true,
  disambiguation: "earlier"
})
// Earlier occurrence (DST time): 2025-11-02T05:30:00.000Z

const later = DateTime.makeZoned(ambiguousTime, {
  timeZone,
  adjustForTimeZone: true,
  disambiguation: "later"
})
// Later occurrence (standard time): 2025-11-02T06:30:00.000Z

// Gap example: 02:30 on Mar 9, 2025 in New York doesn't exist
const gapTime = { year: 2025, month: 3, day: 9, hour: 2, minute: 30 }

const beforeGap = DateTime.makeZoned(gapTime, {
  timeZone,
  adjustForTimeZone: true,
  disambiguation: "earlier"
})
// Time before gap: 2025-03-09T06:30:00.000Z (01:30 EST)

const afterGap = DateTime.makeZoned(gapTime, {
  timeZone,
  adjustForTimeZone: true,
  disambiguation: "later"
})
// Time after gap: 2025-03-09T07:30:00.000Z (03:30 EDT)

earlier.pipe(Option.getOrThrow, DateTime.formatIso) // => "2025-11-02T05:30:00.000Z"
later.pipe(Option.getOrThrow, DateTime.formatIso) // => "2025-11-02T06:30:00.000Z"
beforeGap.pipe(Option.getOrThrow, DateTime.formatIso) // => "2025-03-09T06:30:00.000Z"
afterGap.pipe(Option.getOrThrow, DateTime.formatIso) // => "2025-03-09T07:30:00.000Z"

TimeZone

type

Since v3.6.0

Represents a time zone used by DateTime.Zoned.

Details

A TimeZone is either a fixed offset from UTC or a named IANA time zone.

Signature

type TimeZone = TimeZone.Offset | TimeZone.Named

Utc

interface

Since v3.6.0

Represents a DateTime stored as an absolute UTC instant with no associated time zone.

Details

Use DateTime.isUtc to narrow a DateTime to this variant.

Signature

interface Utc extends Proto {
  readonly _tag: "Utc";
  readonly epochMilliseconds: number;
  partsUtc: PartsWithWeekday | undefined;
}

Zoned

interface

Since v3.6.0

Represents a DateTime with an associated TimeZone.

Details

A zoned value still represents an absolute instant through epochMilliseconds, while the time zone is used for wall-clock parts, formatting, and zone-aware transformations.

Signature

interface Zoned extends Proto {
  readonly _tag: "Zoned";
  adjustedEpochMilliseconds: number | undefined;
  readonly epochMilliseconds: number;
  partsAdjusted: PartsWithWeekday | undefined;
  partsUtc: PartsWithWeekday | undefined;
  readonly zone: TimeZone;
}

Ordering

clamp

Since v3.6.0

Returns a DateTime constrained between a minimum and maximum value.

Details

If the DateTime is before the minimum, the minimum is returned. If the DateTime is after the maximum, the maximum is returned. Otherwise, the original DateTime is returned.

Signature

declare const clamp: {
  <Min extends DateTime, Max extends DateTime>(options: {
    readonly maximum: Max;
    readonly minimum: Min;
  }): <A extends DateTime>(self: A) => Min | Max | A;
  <A extends DateTime, Min extends DateTime, Max extends DateTime>(self: A, options: {
    readonly maximum: Max;
    readonly minimum: Min;
  }): A | Min | Max;
}

Example Clamping DateTime values

import { DateTime } from "effect"

const min = DateTime.makeUnsafe("2024-01-01")
const max = DateTime.makeUnsafe("2024-12-31")
const date = DateTime.makeUnsafe("2025-06-15")

DateTime.clamp(date, { minimum: min, maximum: max }) // => DateTime.makeUnsafe("2024-12-31")

Other

DateTime

Since v3.6.0

Companion namespace containing the public helper types used by DateTime constructors, parts APIs, formatting, and date/time arithmetic.

TimeZone

Since v3.6.0

Companion namespace containing the public variant and protocol types for TimeZone.

Providing Services

withCurrentZone

Since v3.6.0

Provides the CurrentTimeZone to an effect.

Signature

declare const withCurrentZone: {
  (value: TimeZone): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, Exclude<R, CurrentTimeZone>>;
  <A, E, R>(self: Effect<A, E, R>, value: TimeZone): Effect<A, E, Exclude<R, CurrentTimeZone>>;
}

Example Providing the current time zone

import { DateTime, Effect } from "effect"

const zone = DateTime.zoneMakeNamedUnsafe("Europe/London")

await Effect.runPromise(Effect.gen(function*() {
  const zoned = yield* DateTime.setZoneCurrent(DateTime.makeUnsafe("2024-01-01"))
  return DateTime.zoneToString(zoned.zone)
}).pipe(DateTime.withCurrentZone(zone))) // => "Europe/London"

withCurrentZoneLocal

Since v3.6.0

Provides the CurrentTimeZone to an effect, using the system's local time zone.

Signature

declare function withCurrentZoneLocal<A, E, R>(effect: Effect<A, E, R>): Effect<A, E, Exclude<R, CurrentTimeZone>>

Example Providing the local time zone

import { DateTime, Effect } from "effect"

await Effect.runPromise(Effect.gen(function*() {
  return DateTime.isZoned(yield* DateTime.nowInCurrentZone)
}).pipe(DateTime.withCurrentZoneLocal)) // => true

withCurrentZoneNamed

Since v3.6.0

Provides the CurrentTimeZone to an effect using an IANA time zone identifier.

Details

If the time zone is invalid, it will fail with an IllegalArgumentError.

Signature

declare const withCurrentZoneNamed: {
  (zone: string): <A, E, R>(effect: Effect<A, E, R>) => Effect<A, IllegalArgumentError | E, Exclude<R, CurrentTimeZone>>;
  <A, E, R>(effect: Effect<A, E, R>, zone: string): Effect<A, IllegalArgumentError | E, Exclude<R, CurrentTimeZone>>;
}

Example Providing a named time zone

import { DateTime, Effect } from "effect"

await Effect.runPromise(Effect.gen(function*() {
  const zoned = yield* DateTime.setZoneCurrent(DateTime.makeUnsafe("2024-01-01"))
  return DateTime.zoneToString(zoned.zone)
}).pipe(DateTime.withCurrentZoneNamed("Europe/London"))) // => "Europe/London"

withCurrentZoneOffset

Since v3.6.0

Provides the CurrentTimeZone to an effect, using an offset.

Signature

declare const withCurrentZoneOffset: {
  (offset: number): <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, Exclude<R, CurrentTimeZone>>;
  <A, E, R>(effect: Effect<A, E, R>, offset: number): Effect<A, E, Exclude<R, CurrentTimeZone>>;
}

Example Providing a fixed-offset time zone

import { DateTime, Effect } from "effect"

const program = Effect.gen(function*() {
  return DateTime.zoneToString(yield* DateTime.CurrentTimeZone)
}).pipe(DateTime.withCurrentZoneOffset(3 * 60 * 60 * 1000))

await Effect.runPromise(program) // => "+03:00"

Services

CurrentTimeZone

Since v3.11.0

Context service that supplies the ambient TimeZone for APIs that work in the current zone, such as DateTime.setZoneCurrent and DateTime.nowInCurrentZone.

Details

Provide it with DateTime.withCurrentZone, one of the withCurrentZone* helpers, or one of the layerCurrentZone* layers.

Signature

declare class CurrentTimeZone extends Shape<"effect/DateTime/CurrentTimeZone", TimeZone, this> {
  constructor(_: never);
}

Example Accessing the current time zone service

import { DateTime, Effect } from "effect"

const program = Effect.gen(function*() {
  return DateTime.zoneToString(yield* DateTime.CurrentTimeZone)
})

// Provide a time zone
const layer = DateTime.layerCurrentZoneNamed("Europe/London")
await Effect.runPromise(Effect.provide(program, layer)) // => "Europe/London"

Transforming

setParts

Since v3.6.0

Sets time-zone-adjusted parts on a DateTime.

Details

The date will be time zone adjusted for DateTime.Zoned.

Signature

declare const setParts: {
  (parts: Partial<DateTime.PartsWithWeekday>): <A extends DateTime>(self: A) => A;
  <A extends DateTime>(self: A, parts: Partial<DateTime.PartsWithWeekday>): A;
}

Example Updating DateTime parts

import { DateTime } from "effect"

const dt = DateTime.makeZonedUnsafe("2024-01-01T12:00:00Z", { timeZone: "UTC" })
const updated = DateTime.setParts(dt, {
  year: 2025,
  month: 6,
  day: 15
})

updated // => DateTime.makeZonedUnsafe("2025-06-15T12:00:00Z", { timeZone: "UTC" })

setPartsUtc

Since v3.6.0

Sets UTC parts on a DateTime.

Details

The parts are always interpreted as UTC, ignoring any time zone information.

Signature

declare const setPartsUtc: {
  (parts: Partial<DateTime.PartsWithWeekday>): <A extends DateTime>(self: A) => A;
  <A extends DateTime>(self: A, parts: Partial<DateTime.PartsWithWeekday>): A;
}

Example Updating UTC DateTime parts

import { DateTime } from "effect"

const dt = DateTime.makeUnsafe("2024-01-01T12:00:00Z")
const updated = DateTime.setPartsUtc(dt, {
  year: 2025,
  hour: 18
})

updated // => DateTime.makeUnsafe("2025-01-01T18:00:00Z")

setZone

Since v3.6.0

Sets the time zone of a DateTime, returning a new DateTime.Zoned.

Signature

declare const setZone: {
  (zone: TimeZone, options?: {
    readonly adjustForTimeZone?: boolean;
    readonly disambiguation?: Disambiguation;
  }): (self: DateTime) => Zoned;
  (self: DateTime, zone: TimeZone, options?: {
    readonly adjustForTimeZone?: boolean;
    readonly disambiguation?: Disambiguation;
  }): Zoned;
}

Example Setting time zones

import { DateTime } from "effect"

const zone = DateTime.zoneMakeNamedUnsafe("Europe/London")
const zoned: DateTime.Zoned = DateTime.setZone(DateTime.makeUnsafe("2024-01-01"), zone)

DateTime.isZoned(zoned) // => true

setZoneNamed

Since v3.6.0

Sets the time zone of a DateTime safely from an IANA time zone identifier. If the time zone is invalid, None will be returned.

Signature

declare const setZoneNamed: {
  (zoneId: string, options?: {
    readonly adjustForTimeZone?: boolean;
    readonly disambiguation?: Disambiguation;
  }): (self: DateTime) => Option<Zoned>;
  (self: DateTime, zoneId: string, options?: {
    readonly adjustForTimeZone?: boolean;
    readonly disambiguation?: Disambiguation;
  }): Option<Zoned>;
}

Example Setting named time zones safely

import { DateTime, Option } from "effect"

const dateTime = DateTime.makeUnsafe("2024-01-01")
const result = DateTime.setZoneNamed(dateTime, "Europe/London").pipe(Option.map(DateTime.formatIsoZoned))

result // => Option.some("2024-01-01T00:00:00.000+00:00[Europe/London]")

setZoneNamedUnsafe

Since v4.0.0

Sets the time zone of a DateTime from an IANA time zone identifier. If the time zone is invalid, an IllegalArgumentError will be thrown.

Signature

declare const setZoneNamedUnsafe: {
  (zoneId: string, options?: {
    readonly adjustForTimeZone?: boolean;
    readonly disambiguation?: Disambiguation;
  }): (self: DateTime) => Zoned;
  (self: DateTime, zoneId: string, options?: {
    readonly adjustForTimeZone?: boolean;
    readonly disambiguation?: Disambiguation;
  }): Zoned;
}

Example Setting named time zones unsafely

import { DateTime } from "effect"

const dateTime = DateTime.makeUnsafe("2024-01-01")
const zoned = DateTime.setZoneNamedUnsafe(dateTime, "Europe/London")

DateTime.zoneToString(zoned.zone) // => "Europe/London"

setZoneOffset

Since v3.6.0

Adds a fixed offset time zone to a DateTime.

Details

The offset is in milliseconds.

Signature

declare const setZoneOffset: {
  (offset: number, options?: {
    readonly adjustForTimeZone?: boolean;
    readonly disambiguation?: Disambiguation;
  }): (self: DateTime) => Zoned;
  (self: DateTime, offset: number, options?: {
    readonly adjustForTimeZone?: boolean;
    readonly disambiguation?: Disambiguation;
  }): Zoned;
}

Example Setting fixed-offset time zones

import { DateTime } from "effect"

const dateTime = DateTime.makeUnsafe("2024-01-01")
const zoned: DateTime.Zoned = DateTime.setZoneOffset(dateTime, 3 * 60 * 60 * 1000)

DateTime.zoneToString(zoned.zone) // => "+03:00"