DateTime API Reference

Comparisons

between

Since v3.6.0

Signature

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

distance

Since v3.6.0

Calulate the difference between two DateTime values, returning the number of milliseconds the other DateTime is from self.

If other is after self, the result will be a positive number.

Signature

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

Example

import { DateTime, Effect } from "effect"

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

  // returns 60000
  DateTime.distance(now, other)
})

distanceDuration

Since v3.6.0

Calulate the distance between two DateTime values.

Signature

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

Example

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.distanceDuration(now, other)
})

distanceDurationEither

Since v3.6.0

Calulate the difference between two DateTime values.

If the other DateTime is before self, the result will be a negative Duration, returned as a Left.

If the other DateTime is after self, the result will be a positive Duration, returned as a Right.

Signature

declare const distanceDurationEither: {
  (other: DateTime): (self: DateTime) => Either<Duration, Duration>;
  (self: DateTime, other: DateTime): Either<Duration, Duration>;
}

Example

import { DateTime, Effect } from "effect"

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

  // returns Either.right(Duration.minutes(1))
  DateTime.distanceDurationEither(now, other)

  // returns Either.left(Duration.minutes(1))
  DateTime.distanceDurationEither(other, now)
})

greaterThan

Since v3.6.0

Signature

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

greaterThanOrEqualTo

Since v3.6.0

Signature

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

isFuture

Since v3.6.0

Signature

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

isPast

Since v3.6.0

Signature

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

lessThan

Since v3.6.0

Signature

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

lessThanOrEqualTo

Since v3.6.0

Signature

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

max

Since v3.6.0

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

min

Since v3.6.0

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

unsafeIsFuture

Since v3.6.0

Signature

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

unsafeIsPast

Since v3.6.0

Signature

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

Constructors

make

Since v3.6.0

Create a DateTime from one of the following:

A DateTime
A Date instance (invalid dates will throw an IllegalArgumentException)
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

If the input is invalid, None will be returned.

Signature

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

Example

import { DateTime } from "effect"

// from Date
DateTime.make(new Date())

// from parts
DateTime.make({ year: 2024 })

// from string
DateTime.make("2024-01-01")

makeZoned

Since v3.6.0

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

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

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

Signature

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

Example

import { DateTime } from "effect"

DateTime.makeZoned(new Date(), { timeZone: "Europe/London" })

makeZonedFromString

Since v3.6.0

Create a DateTime.Zoned from a string.

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

Signature

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

now

Since v3.6.0

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

Signature

declare const now: Effect.Effect<Utc>

Example

import { DateTime, Effect } from "effect"

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

nowAsDate

Since v3.14.0

Get the current time using the Clock service.

Signature

declare const nowAsDate: Effect.Effect<Date>

Example

import { DateTime, Effect } from "effect"

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

unsafeFromDate

Since v3.6.0

Create a DateTime from a Date.

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

Signature

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

unsafeMake

Since v3.6.0

Create a DateTime from one of the following:

A DateTime
A Date instance (invalid dates will throw an IllegalArgumentException)
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 unsafeMake: <A extends DateTime.Input>(input: A) => DateTime.PreserveZone<A>

Example

import { DateTime } from "effect"

// from Date
DateTime.unsafeMake(new Date())

// from parts
DateTime.unsafeMake({ year: 2024 })

// from string
DateTime.unsafeMake("2024-01-01")

unsafeMakeZoned

Since v3.6.0

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

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 unsafeMakeZoned: (input: DateTime.Input, options?: {
  readonly adjustForTimeZone?: boolean;
  readonly disambiguation?: Disambiguation;
  readonly timeZone?: number | string | TimeZone;
}) => Zoned

Example

import { DateTime } from "effect"

DateTime.unsafeMakeZoned(new Date(), { timeZone: "Europe/London" })

unsafeNow

Since v3.6.0

Get the current time using Date.now.

Signature

declare const unsafeNow: LazyArg<Utc>

Conversions

removeTime

Since v3.6.0

Remove 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

import { DateTime } from "effect"

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

toDate

Since v3.6.0

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

Signature

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

toDateUtc

Since v3.6.0

Get the UTC Date of a DateTime.

Signature

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

toEpochMillis

Since v3.6.0

Get the milliseconds since the Unix epoch of a DateTime.

Signature

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

zonedOffset

Since v3.6.0

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

Signature

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

zonedOffsetIso

Since v3.6.0

Calculate the time zone offset of a DateTime in milliseconds.

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

Signature

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

Current Time Zone

CurrentTimeZone

Since v3.11.0

Signature

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

layerCurrentZone

Since v3.6.0

Create a Layer from the given time zone.

Signature

declare function layerCurrentZone(zone: TimeZone): Layer<CurrentTimeZone>

layerCurrentZoneLocal

Since v3.6.0

Create a Layer from the systems local time zone.

Signature

declare const layerCurrentZoneLocal: Layer.Layer<CurrentTimeZone>

layerCurrentZoneNamed

Since v3.6.0

Create a Layer from the given IANA time zone identifier.

Signature

declare function layerCurrentZoneNamed(zoneId: string): Layer<CurrentTimeZone, IllegalArgumentException>

layerCurrentZoneOffset

Since v3.6.0

Create a Layer from the given time zone offset.

Signature

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

nowInCurrentZone

Since v3.6.0

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

Signature

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

Example

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

setZoneCurrent

Since v3.6.0

Set 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

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

withCurrentZone

Since v3.6.0

Provide the CurrentTimeZone to an effect.

Signature

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

Example

import { DateTime, Effect } from "effect"

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

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

withCurrentZoneLocal

Since v3.6.0

Provide 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

import { DateTime, Effect } from "effect"

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

withCurrentZoneNamed

Since v3.6.0

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

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

Signature

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

Example

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

withCurrentZoneOffset

Since v3.6.0

Provide the CurrentTimeZone to an effect, using a 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

import { DateTime, Effect } from "effect"

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

Formatting

format

Since v3.6.0

Format a DateTime as a string using the DateTimeFormat API.

The timeZone option is set to the offset of the time zone.

Note: On Node versions < 22, fixed "Offset" zones will set the time zone to "UTC" and use the adjusted Date.

Signature

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

formatIntl

Since v3.6.0

Format a DateTime as a string using the DateTimeFormat API.

Signature

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

formatIso

Since v3.6.0

Format a DateTime as a UTC ISO string.

Signature

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

formatIsoDate

Since v3.6.0

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

Signature

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

formatIsoDateUtc

Since v3.6.0

Format a DateTime as a UTC ISO date string.

Signature

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

formatIsoOffset

Since v3.6.0

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

Signature

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

formatIsoZoned

Since v3.6.0

Format a DateTime.Zoned as a string.

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

Signature

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

formatLocal

Since v3.6.0

Format a DateTime as a string using the DateTimeFormat API.

It will use the system's local time zone & locale.

Signature

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

formatUtc

Since v3.6.0

Format a DateTime as a string using the DateTimeFormat API.

This forces the time zone to be UTC.

Signature

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

Guards

isDateTime

Since v3.6.0

Signature

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

isTimeZone

Since v3.6.0

Signature

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

isTimeZoneNamed

Since v3.6.0

Signature

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

isTimeZoneOffset

Since v3.6.0

Signature

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

isUtc

Since v3.6.0

Signature

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

isZoned

Since v3.6.0

Signature

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

Instances

Equivalence

Since v3.6.0

Signature

declare const Equivalence: equivalence.Equivalence<DateTime>

Order

Since v3.6.0

Signature

declare const Order: order.Order<DateTime>

Mapping

mapEpochMillis

Since v3.6.0

Transform 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

import { DateTime } from "effect"

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

match

Since v3.6.0

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

mutate

Since v3.6.0

Modify a DateTime by applying a function to a cloned Date instance.

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

mutateUtc

Since v3.6.0

Modify a DateTime by applying a function to a cloned UTC Date instance.

Signature

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

withDate

Since v3.6.0

Using the time zone adjusted Date, apply a function to the Date and return the result.

Signature

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

Example

import { DateTime } from "effect"

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

withDateUtc

Since v3.6.0

Using the time zone adjusted Date, apply a function to the Date and return the result.

Signature

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

Example

import { DateTime } from "effect"

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

Math

add

Since v3.6.0

Add the given amount of unit's to a DateTime.

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

import { DateTime } from "effect"

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

addDuration

Since v3.6.0

Add the given Duration to a DateTime.

Signature

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

Example

import { DateTime } from "effect"

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

endOf

Since v3.6.0

Converts a DateTime to the end of the given part.

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

import { DateTime } from "effect"

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

nearest

Since v3.6.0

Converts a DateTime to the nearest given part.

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

import { DateTime } from "effect"

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

startOf

Since v3.6.0

Converts a DateTime to the start of the given part.

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

import { DateTime } from "effect"

// returns "2024-01-01T00:00:00Z"
DateTime.unsafeMake("2024-01-01T12:00:00Z").pipe(
  DateTime.startOf("day"),
  DateTime.formatIso
)

subtract

Since v3.6.0

Subtract the given amount of unit's 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

import { DateTime } from "effect"

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

subtractDuration

Since v3.6.0

Subtract the given Duration from a DateTime.

Signature

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

Example

import { DateTime } from "effect"

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

Models

DateTime

Since v3.6.0

DateTime

type

Since v3.6.0

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

Signature

type DateTime = Utc | Zoned

Disambiguation

type

Since v3.18.0

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

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

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.zoneUnsafeMakeNamed("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)

TimeZone

Since v3.6.0

TimeZone

type

Since v3.6.0

Signature

type TimeZone = TimeZone.Offset | TimeZone.Named

Utc

interface

Since v3.6.0

Signature

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

Zoned

interface

Since v3.6.0

Signature

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

Other

clamp

Since v3.6.0

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

Parts

getPart

Since v3.6.0

Get a part of a DateTime as a number.

The part will be time zone adjusted.

Signature

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

Example

import * as assert from "node:assert"
import { DateTime } from "effect"

const now = DateTime.unsafeMakeZoned({ year: 2024 }, { timeZone: "Europe/London" })
const year = DateTime.getPart(now, "year")
assert.strictEqual(year, 2024)

getPartUtc

Since v3.6.0

Get a part of a DateTime as a number.

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

import * as assert from "node:assert"
import { DateTime } from "effect"

const now = DateTime.unsafeMake({ year: 2024 })
const year = DateTime.getPartUtc(now, "year")
assert.strictEqual(year, 2024)

setParts

Since v3.6.0

Set the different parts of a DateTime as an object.

The Date will be time zone adjusted.

Signature

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

setPartsUtc

Since v3.6.0

Set the different parts of a DateTime as an object.

Signature

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

toParts

Since v3.6.0

Get the different parts of a DateTime as an object.

The parts will be time zone adjusted.

Signature

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

toPartsUtc

Since v3.6.0

Get the different parts of a DateTime as an object.

The parts will be in UTC.

Signature

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

Time Zones

setZone

Since v3.6.0

Set 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

import { DateTime, Effect } from "effect"

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

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

setZoneNamed

Since v3.6.0

Set the time zone of a DateTime 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

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

setZoneOffset

Since v3.6.0

Add a fixed offset time zone to a DateTime.

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

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

toUtc

Since v3.13.0

For a DateTime returns a new DateTime.Utc.

Signature

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

Example

import { DateTime } from "effect"

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

// set as UTC
const utc: DateTime.Utc = DateTime.toUtc(now)

unsafeSetZoneNamed

Since v3.6.0

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

Signature

declare const unsafeSetZoneNamed: {
  (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

import { DateTime, Effect } from "effect"

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

zoneFromString

Since v3.6.0

Try parse a TimeZone from a string

Signature

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

zoneMakeLocal

Since v3.6.0

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

Signature

declare const zoneMakeLocal: () => TimeZone.Named

zoneMakeNamed

Since v3.6.0

Create a named time zone from a IANA time zone identifier. If the time zone is invalid, None will be returned.

Signature

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

zoneMakeNamedEffect

Since v3.6.0

Create a named time zone from a IANA time zone identifier. If the time zone is invalid, it will fail with an IllegalArgumentException.

Signature

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

zoneMakeOffset

Since v3.6.0

Create a fixed offset time zone.

Signature

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

zoneToString

Since v3.6.0

Format a TimeZone as a string.

Signature

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

Example

import { DateTime, Effect } from "effect"

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

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

zoneUnsafeMakeNamed

Since v3.6.0

Attempt to create a named time zone from a IANA time zone identifier.

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

Signature

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

Type Ids

TimeZoneTypeId

Since v3.6.0

Signature

declare const TimeZoneTypeId: unique symbol

TimeZoneTypeId

type

Since v3.6.0

Signature

type TimeZoneTypeId = typeof TimeZoneTypeId

TypeId

Since v3.6.0

Signature

declare const TypeId: unique symbol

TypeId

type

Since v3.6.0

Signature

type TypeId = typeof TypeId