Skip to content

DateTime.ts

DateTime.ts overview

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.

Since v3.6.0

Exports Grouped by Category

comparisons
constructors
converting
current time zone
formatting
guards
instances
- Equivalence
- Order
mapping
- mapEpochMillis
- match
- mutate
- mutateUtc
- withDate
- withDateUtc
math
- add
- addDuration
- endOf
- nearest
- startOf
- subtract
- subtractDuration
models
ordering
- clamp
parts
- getPart
- getPartUtc
- setParts
- setPartsUtc
- toParts
- toPartsUtc
time zones
utils
- DateTime (namespace)
- TimeZone (namespace)

comparisons

between

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

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")

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

Signature

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

Since v3.6.0

distance

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.

Example (Measuring distance between DateTime values)

import { DateTime, Effect } from "effect"

Effect.gen(function* () {
  const now = yield* DateTime.now
  const other = DateTime.add(now, { minutes: 1 })

  // returns Duration.minutes(1)
  DateTime.distance(now, other)
})

Signature

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

Since v3.6.0

isFuture

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.

Example (Checking future DateTime values effectfully)

import { DateTime, Effect } from "effect"

const program = Effect.gen(function* () {
  const futureDate = DateTime.add(yield* DateTime.now, { hours: 1 })
  const isFuture = yield* DateTime.isFuture(futureDate)
  console.log(isFuture) // true
})

Signature

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

Since v3.6.0

isFutureUnsafe

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.

Example (Checking future DateTime values unsafely)

import { DateTime } from "effect"

const now = DateTime.nowUnsafe()
const futureDate = DateTime.add(now, { hours: 1 })

console.log(DateTime.isFutureUnsafe(futureDate)) // true
console.log(DateTime.isFutureUnsafe(now)) // false

Signature

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

Since v4.0.0

isGreaterThan

Checks whether the first DateTime is after the second DateTime.

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")

console.log(DateTime.isGreaterThan(date1, date2)) // true
console.log(DateTime.isGreaterThan(date2, date1)) // false

Signature

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

Since v4.0.0

isGreaterThanOrEqualTo

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

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")

console.log(DateTime.isGreaterThanOrEqualTo(date1, date2)) // true
console.log(DateTime.isGreaterThanOrEqualTo(date3, date1)) // true
console.log(DateTime.isGreaterThanOrEqualTo(date1, date3)) // false

Signature

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

Since v4.0.0

isLessThan

Checks whether the first DateTime is before the second DateTime.

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")

console.log(DateTime.isLessThan(date1, date2)) // true
console.log(DateTime.isLessThan(date2, date1)) // false

Signature

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

Since v4.0.0

isLessThanOrEqualTo

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

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")

console.log(DateTime.isLessThanOrEqualTo(date1, date2)) // true
console.log(DateTime.isLessThanOrEqualTo(date1, date3)) // true
console.log(DateTime.isLessThanOrEqualTo(date3, date1)) // false

Signature

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

Since v4.0.0

isPast

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.

Example (Checking past DateTime values effectfully)

import { DateTime, Effect } from "effect"

const program = Effect.gen(function* () {
  const pastDate = DateTime.subtract(yield* DateTime.now, { hours: 1 })
  const isPast = yield* DateTime.isPast(pastDate)
  console.log(isPast) // true
})

Signature

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

Since v3.6.0

isPastUnsafe

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.

Example (Checking past DateTime values unsafely)

import { DateTime } from "effect"

const now = DateTime.nowUnsafe()
const pastDate = DateTime.subtract(now, { hours: 1 })

console.log(DateTime.isPastUnsafe(pastDate)) // true
console.log(DateTime.isPastUnsafe(now)) // false

Signature

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

Since v4.0.0

max

Returns the later of two DateTime values.

Example (Selecting the later DateTime)

import { DateTime } from "effect"

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

const later = DateTime.max(date1, date2)
// later equals date2 (2024-02-01)

Signature

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

Since v3.6.0

min

Returns the earlier of two DateTime values.

Example (Selecting the earlier DateTime)

import { DateTime } from "effect"

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

const earlier = DateTime.min(date1, date2)
// earlier equals date1 (2024-01-01)

Signature

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

Since v3.6.0

constructors

fromDateUnsafe

Create a DateTime from a Date.

Details

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

Example (Creating DateTime values from Dates)

import { DateTime } from "effect"

const date = new Date("2024-01-01T12:00:00Z")
const dateTime = DateTime.fromDateUnsafe(date)

console.log(DateTime.formatIso(dateTime)) // "2024-01-01T12:00:00.000Z"

Signature

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

Since v4.0.0

make

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.

Example (Creating optional DateTime values)

import { DateTime } from "effect"

// from Date
const fromDate = DateTime.make(new Date("2024-01-01T12:00:00Z"))
console.log(fromDate._tag) // "Some"

// from parts
const fromParts = DateTime.make({ year: 2024 })
console.log(fromParts._tag) // "Some"

// from string
const fromString = DateTime.make("2024-01-01")
console.log(fromString._tag) // "Some"

const invalid = DateTime.make("not a date")
console.log(invalid._tag) // "None"

Signature

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

Since v3.6.0

makeUnsafe

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

Example (Creating DateTime values unsafely)

import { DateTime } from "effect"

// from Date
const fromDate = DateTime.makeUnsafe(new Date("2024-01-01T12:00:00Z"))
console.log(DateTime.formatIso(fromDate)) // "2024-01-01T12:00:00.000Z"

// from parts
const fromParts = DateTime.makeUnsafe({ year: 2024 })
console.log(DateTime.formatIso(fromParts)) // "2024-01-01T00:00:00.000Z"

// from string
const fromString = DateTime.makeUnsafe("2024-01-01")
console.log(DateTime.formatIso(fromString)) // "2024-01-01T00:00:00.000Z"

Signature

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

Since v4.0.0

makeZoned

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.

Example (Creating optional zoned DateTime values)

import { DateTime } from "effect"

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

console.log(result._tag) // "Some"
if (result._tag === "Some") {
  console.log(DateTime.formatIsoZoned(result.value)) // "2024-06-15T15:30:00.000+01:00[Europe/London]"
}

Signature

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

Since v3.6.0

makeZonedFromString

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.

Example (Parsing zoned DateTime strings)

import { DateTime } from "effect"

const result1 = DateTime.makeZonedFromString("2024-01-01T12:00:00+02:00[Europe/Berlin]")
console.log(result1._tag === "Some") // true

const result2 = DateTime.makeZonedFromString("2024-01-01T12:00:00Z")
console.log(result2._tag === "Some") // true

const invalid = DateTime.makeZonedFromString("invalid")
console.log(invalid._tag === "None") // true

Signature

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

Since v3.6.0

makeZonedUnsafe

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

Example (Creating zoned DateTime values unsafely)

import { DateTime } from "effect"

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

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

Signature

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

Since v4.0.0

now

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

Example (Getting the current DateTime)

import { DateTime, Effect } from "effect"

Effect.gen(function* () {
  const now = yield* DateTime.nowAsDate
  console.log(now instanceof Date) // true
})

Signature

declare const now: Effect.Effect<Utc, never, never>

Since v3.6.0

nowAsDate

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

Example (Getting the current Date)

import { DateTime, Effect } from "effect"

Effect.gen(function* () {
  const now = yield* DateTime.now
})

Signature

declare const nowAsDate: Effect.Effect<Date, never, never>

Since v3.14.0

nowUnsafe

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.

Example (Getting the current DateTime unsafely)

import { DateTime } from "effect"

const now = DateTime.nowUnsafe()
console.log(DateTime.formatIso(now))

Signature

declare const nowUnsafe: LazyArg<Utc>

Since v4.0.0

converting

removeTime

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

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)

Signature

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

Since v3.6.0

toDate

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

Details

For DateTime.Zoned, this adjusts for the time zone before converting. For DateTime.Utc, this is equivalent to toDateUtc.

Example (Converting DateTime values to Dates)

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"
})

console.log(DateTime.toDate(utc).toISOString())
console.log(DateTime.toDate(zoned).toISOString())

Signature

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

Since v3.6.0

toDateUtc

Gets the UTC Date of a DateTime.

Details

This always returns the UTC representation, ignoring any time zone information.

Example (Converting DateTime values to UTC Dates)

import { DateTime } from "effect"

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

const utcDate = DateTime.toDateUtc(dt)
console.log(utcDate.toISOString()) // "2024-01-01T12:00:00.000Z"

Signature

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

Since v3.6.0

toEpochMillis

Gets the milliseconds since the Unix epoch of a DateTime.

Details

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

Example (Reading epoch milliseconds)

import { DateTime } from "effect"

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

console.log(epochMillis) // 1704067200000

Signature

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

Since v3.6.0

zonedOffset

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.

Example (Reading zoned offsets)

import { DateTime } from "effect"

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

const offset = DateTime.zonedOffset(zoned)
console.log(offset) // 0 (London is UTC+0 in winter)

Signature

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

Since v3.6.0

zonedOffsetIso

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

Details

The offset is formatted as “±HH:MM”.

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
})

const offsetString = DateTime.zonedOffsetIso(zoned)
console.log(offsetString) // "+03:00"

Signature

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

Since v3.6.0

current time zone

CurrentTimeZone (class)

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.

Example (Accessing the current time zone service)

import { DateTime, Effect } from "effect"

const program = Effect.gen(function* () {
  // Access the current time zone service
  const zone = yield* DateTime.CurrentTimeZone
  console.log(DateTime.zoneToString(zone))
})

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

Signature

declare class CurrentTimeZone

Since v3.11.0

layerCurrentZone

Create a Layer from the given time zone.

Details

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

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.formatIsoZoned(now)
})

// Use the layer to provide the time zone
Effect.provide(program, layer)

Signature

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

Since v3.6.0

layerCurrentZoneLocal

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.

Example (Providing local time zone layers)

import { DateTime, Effect } from "effect"

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

// Use the system's local time zone
Effect.provide(program, DateTime.layerCurrentZoneLocal)

Signature

declare const layerCurrentZoneLocal: Layer.Layer<CurrentTimeZone, never, never>

Since v3.6.0

layerCurrentZoneNamed

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.

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.formatIsoZoned(now)
})

Effect.provide(program, layer)

Signature

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

Since v3.6.0

layerCurrentZoneOffset

Create a Layer from the given time zone offset.

Details

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

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.formatIsoZoned(now)
})

Effect.provide(program, layer)

Signature

declare const layerCurrentZoneOffset: (offset: number) => Layer.Layer<CurrentTimeZone>

Since v3.6.0

nowInCurrentZone

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

Example (Getting the current time in the current zone)

import { DateTime, Effect } from "effect"

Effect.gen(function* () {
  // will use the "Europe/London" time zone
  const now = yield* DateTime.nowInCurrentZone
}).pipe(DateTime.withCurrentZoneNamed("Europe/London"))

Signature

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

Since v3.6.0

setZoneCurrent

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

Example (Setting the current time zone)

import { DateTime, Effect } from "effect"

Effect.gen(function* () {
  const now = yield* DateTime.now

  // set the time zone to "Europe/London"
  const zoned = yield* DateTime.setZoneCurrent(now)
}).pipe(DateTime.withCurrentZoneNamed("Europe/London"))

Signature

declare const setZoneCurrent: (self: DateTime) => Effect.Effect<Zoned, never, CurrentTimeZone>

Since v3.6.0

withCurrentZone

Provides the CurrentTimeZone to an effect.

Example (Providing the current time zone)

import { DateTime, Effect } from "effect"

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

Effect.gen(function* () {
  const now = yield* DateTime.nowInCurrentZone
}).pipe(DateTime.withCurrentZone(zone))

Signature

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

Since v3.6.0

withCurrentZoneLocal

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

Example (Providing the local time zone)

import { DateTime, Effect } from "effect"

Effect.gen(function* () {
  // will use the system's local time zone
  const now = yield* DateTime.nowInCurrentZone
}).pipe(DateTime.withCurrentZoneLocal)

Signature

declare const withCurrentZoneLocal: <A, E, R>(
  effect: Effect.Effect<A, E, R>
) => Effect.Effect<A, E, Exclude<R, CurrentTimeZone>>

Since v3.6.0

withCurrentZoneNamed

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.

Example (Providing a named time zone)

import { DateTime, Effect } from "effect"

Effect.gen(function* () {
  // will use the "Europe/London" time zone
  const now = yield* DateTime.nowInCurrentZone
}).pipe(DateTime.withCurrentZoneNamed("Europe/London"))

Signature

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

Since v3.6.0

withCurrentZoneOffset

Provides the CurrentTimeZone to an effect, using an offset.

Example (Providing a fixed-offset time zone)

import { DateTime, Effect } from "effect"

Effect.gen(function* () {
  const zone = yield* DateTime.CurrentTimeZone
  console.log(DateTime.zoneToString(zone)) // "+03:00"
}).pipe(DateTime.withCurrentZoneOffset(3 * 60 * 60 * 1000))

Signature

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

Since v3.6.0

formatting

format

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.

Example (Formatting DateTime values with Intl options)

import { DateTime } from "effect"

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

const formatted = DateTime.format(dt, {
  dateStyle: "full",
  timeStyle: "short",
  locale: "en-US"
})

console.log(formatted) // "Saturday, June 15, 2024 at 3:30 PM"

Signature

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

Since v3.6.0

formatIntl

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.

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"
})

const formatted = DateTime.formatIntl(dt, formatter)
console.log(formatted.length > 0) // true

See

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

Signature

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

Since v3.6.0

formatIso

Formats a DateTime as a UTC ISO string.

Details

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

Example (Formatting DateTime values as ISO strings)

import { DateTime } from "effect"

const dt = DateTime.makeUnsafe("2024-01-01T12:30:45.123Z")
console.log(DateTime.formatIso(dt)) // "2024-01-01T12:30:45.123Z"

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

Signature

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

Since v3.6.0

formatIsoDate

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.

Example (Formatting DateTime values as ISO dates)

import { DateTime } from "effect"

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

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

Signature

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

Since v3.6.0

formatIsoDateUtc

Formats a DateTime as a UTC ISO date string.

Details

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

Example (Formatting DateTime values as UTC ISO dates)

import { DateTime } from "effect"

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

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

Signature

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

Since v3.6.0

formatIsoOffset

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.

Example (Formatting DateTime values with offsets)

import { DateTime } from "effect"

const utc = DateTime.makeUnsafe("2024-01-01T12:00:00Z")
console.log(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)
})
console.log(DateTime.formatIsoOffset(zoned)) // "2024-01-01T15:00:00.000+03:00"

Signature

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

Since v3.6.0

formatIsoZoned

Formats a DateTime.Zoned as a string.

Details

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

Example (Formatting zoned DateTime values)

import { DateTime } from "effect"

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

const formatted = DateTime.formatIsoZoned(zoned)
console.log(formatted) // "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)
})

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

Signature

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

Since v3.6.0

formatLocal

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

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
const local = DateTime.formatLocal(dt, {
  year: "numeric",
  month: "long",
  day: "numeric",
  hour: "2-digit",
  minute: "2-digit"
})

console.log(local) // Output depends on system locale/timezone

Signature

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

Since v3.6.0

formatUtc

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

Details

This forces the time zone to be UTC.

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
const utcFormatted = DateTime.formatUtc(dt, {
  year: "numeric",
  month: "2-digit",
  day: "2-digit",
  hour: "2-digit",
  minute: "2-digit",
  timeZoneName: "short"
})

console.log(utcFormatted) // "06/15/2024, 02:30 PM UTC"

Signature

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

Since v3.6.0

guards

isDateTime

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

Since v3.6.0

isTimeZone

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

Since v3.6.0

isTimeZoneNamed

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

Since v3.6.0

isTimeZoneOffset

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

Since v3.6.0

isUtc

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

Since v3.6.0

isZoned

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

Since v3.6.0

instances

Equivalence

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.

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"
})

console.log(DateTime.Equivalence(utc, zoned)) // true

Signature

declare const Equivalence: Equ.Equivalence<DateTime>

Since v3.6.0

Order

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.

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")]

const sorted = Array.sort(dates, DateTime.Order)
// Results in chronological order: 2024-01-01, 2024-02-01, 2024-03-01

Signature

declare const Order: order.Order<DateTime>

Since v3.6.0

mapping

mapEpochMillis

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

Example (Mapping epoch milliseconds)

import { DateTime } from "effect"

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

Signature

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

Since v3.6.0

match

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

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)}`
})

console.log(result1) // "UTC: 2024-01-01T12:00:00.000Z"
console.log(result2) // "Zoned: 2024-06-15T15:30:00.000+01:00[Europe/London]"

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
}

Since v3.6.0

mutate

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.

Example (Mutating DateTime values with Dates)

import { DateTime } from "effect"

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

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

console.log(DateTime.formatIso(modified)) // "2024-01-01T15:30:00.000Z"

Signature

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

Since v3.6.0

mutateUtc

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.

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
})

console.log(DateTime.formatIso(modified)) // "2024-01-01T18:00:00.000Z"

Signature

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

Since v3.6.0

withDate

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.

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()))

Signature

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

Since v3.6.0

withDateUtc

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.

Example (Applying UTC Dates)

import { DateTime } from "effect"

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

Signature

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

Since v3.6.0

math

add

Adds the given amount of unit to a DateTime.

Details

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

Example (Adding date and time parts)

import { DateTime } from "effect"

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

Signature

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

Since v3.6.0

addDuration

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.

Example (Adding durations)

import { DateTime } from "effect"

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

See

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

Signature

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

Since v3.6.0

endOf

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

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.formatIso)

Signature

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

Since v3.6.0

nearest

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

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.formatIso)

Signature

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

Since v3.6.0

startOf

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

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.formatIso)

Signature

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

Since v3.6.0

subtract

Subtracts the given amount of unit from a DateTime.

Example (Subtracting date and time parts)

import { DateTime } from "effect"

// subtract 5 minutes
DateTime.makeUnsafe(0).pipe(DateTime.subtract({ minutes: 5 }))

Signature

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

Since v3.6.0

subtractDuration

Subtracts the given Duration from a DateTime.

Example (Subtracting durations)

import { DateTime } from "effect"

// subtract 5 minutes
DateTime.makeUnsafe(0).pipe(DateTime.subtractDuration("5 minutes"))

Signature

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

Since v3.6.0

models

DateTime (type alias)

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

Signature

type DateTime = Utc | Zoned

Since v3.6.0

Disambiguation (type alias)

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.

Example (Resolving ambiguous local times)

import { DateTime } from "effect"

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

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

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, hours: 2, minutes: 30 }

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

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

Signature

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

Since v3.18.0

TimeZone (type alias)

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

Since v3.6.0

Utc (interface)

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

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

Since v3.6.0

Zoned (interface)

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

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

Since v3.6.0

ordering

clamp

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.

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")

const clamped = DateTime.clamp(date, { minimum: min, maximum: max })
// clamped equals max (2024-12-31)

Signature

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

Since v3.6.0

parts

getPart

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

Details

The part will be time zone adjusted.

Example (Reading DateTime parts by key)

import { DateTime } from "effect"

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

Signature

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

Since v3.6.0

getPartUtc

Gets one UTC part of a DateTime as a number.

Details

The part will be in the UTC time zone.

Example (Reading UTC DateTime parts by key)

import { DateTime } from "effect"

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

Signature

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

Since v3.6.0

setParts

Sets time-zone-adjusted parts on a DateTime.

Details

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

Example (Updating DateTime parts)

import { DateTime } from "effect"

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

console.log(DateTime.formatIso(updated)) // "2025-06-15T12:00:00.000Z"

Signature

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

Since v3.6.0

setPartsUtc

Sets UTC parts on a DateTime.

Details

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

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
})

console.log(DateTime.formatIso(updated)) // "2025-01-01T18:00:00.000Z"

Signature

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

Since v3.6.0

toParts

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.

Example (Reading DateTime parts)

import { DateTime } from "effect"

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

console.log(parts)
// {
//   year: 2024,
//   month: 1,
//   day: 1,
//   hours: 12,
//   minutes: 30,
//   seconds: 45,
//   millis: 123,
//   weekDay: 1 // Monday
// }

Signature

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

Since v3.6.0

toPartsUtc

Gets the UTC parts of a DateTime as an object.

Details

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

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)

console.log(parts)
// Always returns UTC parts regardless of time zone

Signature

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

Since v3.6.0

time zones

setZone

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

Example (Setting time zones)

import { DateTime, Effect } from "effect"

Effect.gen(function* () {
  const now = yield* DateTime.now
  const zone = DateTime.zoneMakeNamedUnsafe("Europe/London")

  // set the time zone
  const zoned: DateTime.Zoned = DateTime.setZone(now, zone)
})

Signature

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

Since v3.6.0

setZoneNamed

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

Example (Setting named time zones safely)

import { DateTime, Effect } from "effect"

Effect.gen(function* () {
  const now = yield* DateTime.now
  // set the time zone, returns an Option
  DateTime.setZoneNamed(now, "Europe/London")
})

Signature

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

Since v3.6.0

setZoneNamedUnsafe

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

Example (Setting named time zones unsafely)

import { DateTime, Effect } from "effect"

Effect.gen(function* () {
  const now = yield* DateTime.now
  // set the time zone
  DateTime.setZoneNamedUnsafe(now, "Europe/London")
})

Signature

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

Since v4.0.0

setZoneOffset

Adds a fixed offset time zone to a DateTime.

Details

The offset is in milliseconds.

Example (Setting fixed-offset time zones)

import { DateTime, Effect } from "effect"

Effect.gen(function* () {
  const now = yield* DateTime.now

  // set the offset time zone in milliseconds
  const zoned: DateTime.Zoned = DateTime.setZoneOffset(now, 3 * 60 * 60 * 1000)
})

Signature

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

Since v3.6.0

toUtc

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.

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)

Signature

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

Since v3.13.0

zoneFromString

Tries to parse a TimeZone from a string safely.

Details

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

Example (Parsing time zones)

import { DateTime } from "effect"

const namedZone = DateTime.zoneFromString("Europe/London")
const offsetZone = DateTime.zoneFromString("+03:00")
const invalid = DateTime.zoneFromString("invalid")

console.log(namedZone._tag === "Some") // true
console.log(offsetZone._tag === "Some") // true
console.log(invalid._tag === "None") // true

Signature

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

Since v3.6.0

zoneMakeLocal

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.

Example (Creating local time zones)

import { DateTime } from "effect"

const localZone = DateTime.zoneMakeLocal()
console.log(DateTime.zoneToString(localZone)) // Output depends on system time zone

Signature

declare const zoneMakeLocal: () => TimeZone.Named

Since v3.6.0

zoneMakeNamed

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

Details

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

Example (Creating optional named time zones)

import { DateTime } from "effect"

const validZone = DateTime.zoneMakeNamed("Europe/London")
console.log(validZone._tag === "Some") // true

const invalidZone = DateTime.zoneMakeNamed("Invalid/Zone")
console.log(invalidZone._tag === "None") // true

Signature

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

Since v3.6.0

zoneMakeNamedEffect

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.

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)
})

Signature

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

Since v3.6.0

zoneMakeNamedUnsafe

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.

Example (Creating named time zones unsafely)

import { DateTime } from "effect"

const londonZone = DateTime.zoneMakeNamedUnsafe("Europe/London")
console.log(DateTime.zoneToString(londonZone)) // "Europe/London"

const tokyoZone = DateTime.zoneMakeNamedUnsafe("Asia/Tokyo")
console.log(DateTime.zoneToString(tokyoZone)) // "Asia/Tokyo"

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

Signature

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

Since v4.0.0

zoneMakeOffset

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.

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
})

Signature

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

Since v3.6.0

zoneToString

Formats a TimeZone as a string.

Example (Formatting time zones)

import { DateTime } from "effect"

// Outputs "+03:00"
DateTime.zoneToString(DateTime.zoneMakeOffset(3 * 60 * 60 * 1000))

// Outputs "Europe/London"
DateTime.zoneToString(DateTime.zoneMakeNamedUnsafe("Europe/London"))

Signature

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

Since v3.6.0

utils

DateTime (namespace)

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

Since v3.6.0

PartsWithWeekday (interface)

Calendar and time components of a DateTime, including the weekday.

Details

month is one-based (1 for January through 12 for December), and weekDay follows JavaScript Date#getUTCDay numbering (0 for Sunday through 6 for Saturday).

Signature

export interface PartsWithWeekday {
  readonly millisecond: number
  readonly second: number
  readonly minute: number
  readonly hour: number
  readonly day: number
  readonly weekDay: number
  readonly month: number
  readonly year: number
}

Since v3.6.0

Parts (interface)

Calendar and time components of a DateTime, without weekday information.

Details

month is one-based (1 for January through 12 for December).

Signature

export interface Parts {
  readonly millisecond: number
  readonly second: number
  readonly minute: number
  readonly hour: number
  readonly day: number
  readonly month: number
  readonly year: number
}

Since v3.6.0

PartsForMath (interface)

Plural amount fields accepted by DateTime.add and DateTime.subtract.

Details

Each field represents the number of units to add or subtract for that part.

Signature

export interface PartsForMath {
  readonly milliseconds: number
  readonly seconds: number
  readonly minutes: number
  readonly hours: number
  readonly days: number
  readonly weeks: number
  readonly months: number
  readonly years: number
}

Since v3.6.0

Instant (interface)

Object input representing an absolute instant as milliseconds since the Unix epoch.

Signature

export interface Instant {
  readonly epochMilliseconds: number
}

Since v4.0.0

InstantWithZone (interface)

Object input representing an absolute instant plus a time zone identifier.

Details

DateTime.makeZoned and DateTime.makeZonedUnsafe use timeZoneId when no explicit timeZone option is supplied.

Signature

export interface InstantWithZone {
  readonly timeZoneId: string
  readonly epochMilliseconds: number
}

Since v4.0.0

Proto (interface)

Shared protocol implemented by all DateTime values.

Details

Provides the DateTime type identifier along with pipe and inspection support.

Signature

export interface Proto extends Pipeable, Inspectable {
  readonly [TypeId]: typeof TypeId
}

Since v3.6.0

Input (type alias)

Input accepted by DateTime.make, DateTime.makeUnsafe, and the zoned constructors.

Details

Includes existing DateTime values, partial date parts, epoch-millisecond objects, epoch milliseconds, JavaScript Date instances, and parseable date strings.

Signature

type Input = DateTime | Partial<Parts> | Instant | InstantWithZone | Date | number | string

Since v3.6.0

PreserveZone (type alias)

Type-level helper used by constructors to preserve a zoned input.

Details

When the input type is DateTime.Zoned, the result type is DateTime.Zoned; otherwise the result type is DateTime.Utc.

Signature

type PreserveZone<A> = A extends Zoned ? Zoned : Utc

Since v3.6.0

Unit (type alias)

Date and time unit name accepted by DateTime rounding and arithmetic APIs.

Details

Includes both singular units, such as "day", and plural units, such as "days".

Signature

type Unit = UnitSingular | UnitPlural

Since v3.6.0

UnitSingular (type alias)

Singular date and time unit names used by rounding APIs such as DateTime.startOf, DateTime.endOf, and DateTime.nearest.

Signature

type UnitSingular = "millisecond" | "second" | "minute" | "hour" | "day" | "week" | "month" | "year"

Since v3.6.0

UnitPlural (type alias)

Plural date and time unit names used by DateTime.PartsForMath for amount-based arithmetic.

Signature

type UnitPlural = "milliseconds" | "seconds" | "minutes" | "hours" | "days" | "weeks" | "months" | "years"

Since v3.6.0

TimeZone (namespace)

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

Since v3.6.0

Proto (interface)

Shared protocol implemented by all TimeZone values.

Details

Provides the TimeZone type identifier and inspection support.

Signature

export interface Proto extends Inspectable {
  readonly [TimeZoneTypeId]: typeof TimeZoneTypeId
}

Since v3.6.0

Offset (interface)

Fixed-offset time zone.

Details

The offset is measured in milliseconds from UTC. Positive offsets are ahead of UTC, and negative offsets are behind UTC.

Signature

export interface Offset extends Proto {
  readonly _tag: "Offset"
  readonly offset: number
}

Since v3.6.0

Named (interface)

Named IANA time zone.

Details

The id field contains the resolved time zone identifier, such as "Europe/London" or "America/New_York".

Signature

export interface Named extends Proto {
  readonly _tag: "Named"
  readonly id: string
  /** @internal */
  readonly format: Intl.DateTimeFormat
}

Since v3.6.0