DateTime

100 exports Added in v3.6.0 Source

Comparisons

between

Added in v3.6.0 Source

Signature

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

distance

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

Signature

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

greaterThanOrEqualTo

Added in v3.6.0 Source

Signature

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

isFuture

Added in v3.6.0 Source

Signature

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

isPast

Added in v3.6.0 Source

Signature

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

lessThan

Added in v3.6.0 Source

Signature

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

lessThanOrEqualTo

Added in v3.6.0 Source

Signature

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

max

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

Signature

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

unsafeIsPast

Added in v3.6.0 Source

Signature

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

Constructors

make

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.14.0 Source

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

Added in v3.6.0 Source

Create a DateTime from a Date.

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

Signature

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

unsafeMake

Added in v3.6.0 Source

Create a DateTime from one of the following:

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

Added in v3.6.0 Source

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.

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

Added in v3.6.0 Source

Get the current time using Date.now.

Signature

declare const unsafeNow: LazyArg<Utc>;

Conversions

removeTime

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Signature

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

toDateUtc

Added in v3.6.0 Source

Get the UTC Date of a DateTime.

Signature

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

toEpochMillis

Added in v3.6.0 Source

Get the milliseconds since the Unix epoch of a DateTime.

Signature

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

zonedOffset

Added in v3.6.0 Source

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

Signature

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

zonedOffsetIso

Added in v3.6.0 Source

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

Added in v3.11.0 Source

Signature

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

layerCurrentZone

Added in v3.6.0 Source

Create a Layer from the given time zone.

Signature

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

layerCurrentZoneLocal

Added in v3.6.0 Source

Create a Layer from the systems local time zone.

Signature

declare const layerCurrentZoneLocal: Layer.Layer<CurrentTimeZone>;

layerCurrentZoneNamed

Added in v3.6.0 Source

Create a Layer from the given IANA time zone identifier.

Signature

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

layerCurrentZoneOffset

Added in v3.6.0 Source

Create a Layer from the given time zone offset.

Signature

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

nowInCurrentZone

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

withCurrentZone

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

withCurrentZoneNamed

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

Format a DateTime as a UTC ISO string.

Signature

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

formatIsoDate

Added in v3.6.0 Source

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

Signature

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

formatIsoDateUtc

Added in v3.6.0 Source

Format a DateTime as a UTC ISO date string.

Signature

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

formatIsoOffset

Added in v3.6.0 Source

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

Signature

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

formatIsoZoned

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

Signature

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

isTimeZone

Added in v3.6.0 Source

Signature

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

isTimeZoneNamed

Added in v3.6.0 Source

Signature

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

isTimeZoneOffset

Added in v3.6.0 Source

Signature

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

isUtc

Added in v3.6.0 Source

Signature

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

isZoned

Added in v3.6.0 Source

Signature

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

Instances

Equivalence

Added in v3.6.0 Source

Signature

declare const Equivalence: equivalence.Equivalence<DateTime>;

Order

Added in v3.6.0 Source

Signature

declare const Order: order.Order<DateTime>;

Mapping

mapEpochMillis

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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.

For more information, see the [Temporal documentation](https://tc39.es/proposal-temporal/docs/timezone.html#ambiguity-due-to-dst-or-other-time-zone-offset-changes)

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

Added in v3.6.0 Source

TimeZone type

Added in v3.6.0 Source

Signature

type TimeZone = TimeZone.Offset | TimeZone.Named;

Utc interface

Added in v3.6.0 Source

Signature

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

Zoned interface

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.13.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

Try parse a TimeZone from a string

Signature

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

zoneMakeLocal

Added in v3.6.0 Source

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

Signature

declare const zoneMakeLocal: () => TimeZone.Named;

zoneMakeNamed

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

Create a fixed offset time zone.

Signature

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

zoneToString

Added in v3.6.0 Source

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

Added in v3.6.0 Source

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

Added in v3.6.0 Source

Signature

declare const TimeZoneTypeId: unique symbol;

TimeZoneTypeId type

Added in v3.6.0 Source

Signature

type TimeZoneTypeId = typeof TimeZoneTypeId;

TypeId

Added in v3.6.0 Source

Signature

declare const TypeId: unique symbol;

TypeId type

Added in v3.6.0 Source

Signature

type TypeId = typeof TypeId;