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 Added in v3.6.0 Source

Accessors

nowInCurrentZone

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v3.6.0 Source

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

Added in v4.0.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v3.6.0 Source

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

Added in v4.0.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v4.0.0 Source

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

Added in v3.6.0 Source

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

Added in v3.14.0 Source

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

Added in v4.0.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v4.0.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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.

Signature

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

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

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

toDateUtc

Added in v3.6.0 Source

Gets the UTC Date of a DateTime.

Details

This always returns the UTC representation, ignoring 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

Added in v3.6.0 Source

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

Added in v4.0.0 Source

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

Added in v3.13.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Signature

type DateTime = Utc | Zoned

Disambiguation type

Added in v3.18.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

TimeZone

Added in v3.6.0 Source

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

Providing Services

withCurrentZone

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.11.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v4.0.0 Source

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

Added in v3.6.0 Source

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"