DateTime

Working with dates and times in JavaScript can be challenging. The built-in Date object mutates its internal state, and time zone handling can be confusing. These design choices can lead to errors when working on applications that rely on date-time accuracy, such as scheduling systems, timestamping services, or logging utilities.

The DateTime module aims to address these limitations by offering:

Immutable Data: Each DateTime is an immutable structure, reducing mistakes related to in-place mutations.
Time Zone Support: DateTime provides robust support for time zones, including automatic daylight saving time adjustments.
Arithmetic Operations: You can perform arithmetic operations on DateTime instances, such as adding or subtracting durations.

The DateTime Type

A DateTime represents a moment in time. It can be stored as either a simple UTC value or as a value with an associated time zone. Storing time this way helps you manage both precise timestamps and the context for how that time should be displayed or interpreted.

There are two main variants of DateTime:

Utc: An immutable structure that uses epochMillis (milliseconds since the Unix epoch) to represent a point in time in Coordinated Universal Time (UTC).
Zoned: Includes epochMillis along with a TimeZone, allowing you to attach an offset or a named region (like “America/New_York”) to the timestamp.

Why Have Two Variants?

Utc is straightforward if you only need a universal reference without relying on local time zones.
Zoned is helpful when you need to keep track of time zone information for tasks such as converting to local times or adjusting for daylight saving time.

TimeZone Variants

A TimeZone can be either:

Offset: Represents a fixed offset from UTC (for example, UTC+2 or UTC-5).
Named: Uses a named region (e.g., “Europe/London” or “America/New_York”) that automatically accounts for region-specific rules like daylight saving time changes.

TypeScript Definition

Below is the TypeScript definition for the DateTime type:

type DateTime = Utc | Zoned

interface Utc {
  readonly _tag: "Utc"
  readonly epochMillis: number
}

interface Zoned {
  readonly _tag: "Zoned"
  readonly epochMillis: number
  readonly zone: TimeZone
}

type TimeZone = TimeZone.Offset | TimeZone.Named

declare namespace TimeZone {
  interface Offset {
    readonly _tag: "Offset"
    readonly offset: number
  }

  interface Named {
    readonly _tag: "Named"
    readonly id: string
  }
}

The DateTime.Parts Type

The DateTime.Parts type defines the main components of a date, such as the year, month, day, hours, minutes, and seconds.

namespace DateTime {
  interface Parts {
    readonly millis: number
    readonly seconds: number
    readonly minutes: number
    readonly hours: number
    readonly day: number
    readonly month: number
    readonly year: number
  }

  interface PartsWithWeekday extends Parts {
    readonly weekDay: number
  }
}

The DateTime.Input Type

The DateTime.Input type is a flexible input type that can be used to create a DateTime instance. It can be one of the following:

A DateTime instance
A JavaScript Date object
A numeric value representing milliseconds since the Unix epoch
An object with partial date parts (e.g., { year: 2024, month: 1, day: 1 })
A string that can be parsed by JavaScript’s Date.parse

namespace DateTime {
  type Input = DateTime | Partial<Parts> | Date | number | string
}

Utc Constructors

Utc is an immutable structure that uses epochMillis (milliseconds since the Unix epoch) to represent a point in time in Coordinated Universal Time (UTC).

unsafeFromDate

Creates a Utc from a JavaScript Date. Throws an IllegalArgumentException if the provided Date is invalid.

When a Date object is passed, it is converted to a Utc instance. The time is interpreted as the local time of the system executing the code and then adjusted to UTC. This ensures a consistent, timezone-independent representation of the date and time.

Example (Converting Local Time to UTC in Italy)

The following example assumes the code is executed on a system in Italy (CET timezone):

1
import { DateTime } from "effect"
2

3
// Create a Utc instance from a local JavaScript Date
4
//
5
//     ┌─── Utc
6
//     ▼
7
const utc = DateTime.unsafeFromDate(new Date("2025-01-01 04:00:00"))
8

9
console.log(utc)
10
// Output: DateTime.Utc(2025-01-01T03:00:00.000Z)
11

12
console.log(utc.epochMillis)
13
// Output: 1735700400000

Explanation:

The local time 2025-01-01 04:00:00 (in Italy, CET) is converted to UTC by subtracting the timezone offset (UTC+1 in January).
As a result, the UTC time becomes 2025-01-01 03:00:00.000Z.
epochMillis provides the same time as milliseconds since the Unix Epoch, ensuring a precise numeric representation of the UTC timestamp.

unsafeMake

Creates a Utc from a DateTime.Input.

Example (Creating a DateTime with unsafeMake)

The following example assumes the code is executed on a system in Italy (CET timezone):

1
import { DateTime } from "effect"
2

3
// From a JavaScript Date
4
const utc1 = DateTime.unsafeMake(new Date("2025-01-01 04:00:00"))
5
console.log(utc1)
6
// Output: DateTime.Utc(2025-01-01T03:00:00.000Z)
7

8
// From partial date parts
9
const utc2 = DateTime.unsafeMake({ year: 2025 })
10
console.log(utc2)
11
// Output: DateTime.Utc(2025-01-01T00:00:00.000Z)
12

13
// From a string
14
const utc3 = DateTime.unsafeMake("2025-01-01")
15
console.log(utc3)
16
// Output: DateTime.Utc(2025-01-01T00:00:00.000Z)

Explanation:

The local time 2025-01-01 04:00:00 (in Italy, CET) is converted to UTC by subtracting the timezone offset (UTC+1 in January).
As a result, the UTC time becomes 2025-01-01 03:00:00.000Z.

make

Similar to unsafeMake, but returns an Option instead of throwing an error if the input is invalid. If the input is invalid, it returns None. If valid, it returns Some containing the Utc.

Example (Creating a DateTime Safely)

The following example assumes the code is executed on a system in Italy (CET timezone):

1
import { DateTime } from "effect"
2

3
// From a JavaScript Date
4
const maybeUtc1 = DateTime.make(new Date("2025-01-01 04:00:00"))
5
console.log(maybeUtc1)
6
/*
7
Output:
8
{ _id: 'Option', _tag: 'Some', value: '2025-01-01T03:00:00.000Z' }
9
*/
10

11
// From partial date parts
12
const maybeUtc2 = DateTime.make({ year: 2025 })
13
console.log(maybeUtc2)
14
/*
15
Output:
16
{ _id: 'Option', _tag: 'Some', value: '2025-01-01T00:00:00.000Z' }
17
*/
18

19
// From a string
20
const maybeUtc3 = DateTime.make("2025-01-01")
21
console.log(maybeUtc3)
22
/*
23
Output:
24
{ _id: 'Option', _tag: 'Some', value: '2025-01-01T00:00:00.000Z' }
25
*/

Explanation:

The local time 2025-01-01 04:00:00 (in Italy, CET) is converted to UTC by subtracting the timezone offset (UTC+1 in January).
As a result, the UTC time becomes 2025-01-01 03:00:00.000Z.

Zoned Constructors

A Zoned includes epochMillis along with a TimeZone, allowing you to attach an offset or a named region (like “America/New_York”) to the timestamp.

unsafeMakeZoned

Creates a Zoned by combining a DateTime.Input with an optional TimeZone. This allows you to represent a specific point in time with an associated time zone.

The time zone can be provided in several ways:

As a TimeZone object
A string identifier (e.g., "Europe/London")
A numeric offset in milliseconds

If the input or time zone is invalid, an IllegalArgumentException is thrown.

Example (Creating a Zoned DateTime Without Specifying a Time Zone)

The following example assumes the code is executed on a system in Italy (CET timezone):

1
import { DateTime } from "effect"
2

3
// Create a Zoned DateTime based on the system's local time zone
4
const zoned = DateTime.unsafeMakeZoned(new Date("2025-01-01 04:00:00"))
5

6
console.log(zoned)
7
// Output: DateTime.Zoned(2025-01-01T04:00:00.000+01:00)
8

9
console.log(zoned.zone)
10
// Output: TimeZone.Offset(+01:00)

Here, the system’s time zone (CET, which is UTC+1 in January) is used to create the Zoned instance.

Example (Specifying a Named Time Zone)

The following example assumes the code is executed on a system in Italy (CET timezone):

1
import { DateTime } from "effect"
2

3
// Create a Zoned DateTime with a specified named time zone
4
const zoned = DateTime.unsafeMakeZoned(new Date("2025-01-01 04:00:00"), {
5
  timeZone: "Europe/Rome",
6
})
7

8
console.log(zoned)
9
// Output: DateTime.Zoned(2025-01-01T04:00:00.000+01:00[Europe/Rome])
10

11
console.log(zoned.zone)
12
// Output: TimeZone.Named(Europe/Rome)

In this case, the "Europe/Rome" time zone is explicitly provided, resulting in the Zoned instance being tied to this named time zone.

By default, the input date is treated as a UTC value and then adjusted for the specified time zone. To interpret the input date as being in the specified time zone, you can use the adjustForTimeZone option.

Example (Adjusting for Time Zone Interpretation)

The following example assumes the code is executed on a system in Italy (CET timezone):

1
import { DateTime } from "effect"
2

3
// Interpret the input date as being in the specified time zone
4
const zoned = DateTime.unsafeMakeZoned(new Date("2025-01-01 04:00:00"), {
5
  timeZone: "Europe/Rome",
6
  adjustForTimeZone: true,
7
})
8

9
console.log(zoned)
10
// Output: DateTime.Zoned(2025-01-01T03:00:00.000+01:00[Europe/Rome])
11

12
console.log(zoned.zone)
13
// Output: TimeZone.Named(Europe/Rome)

Explanation

Without adjustForTimeZone: The input date is interpreted as UTC and then adjusted to the specified time zone. For instance, 2025-01-01 04:00:00 in UTC becomes 2025-01-01T04:00:00.000+01:00 in CET (UTC+1).
With adjustForTimeZone: true: The input date is interpreted as being in the specified time zone. For example, 2025-01-01 04:00:00 in “Europe/Rome” (CET) is adjusted to its corresponding UTC time, resulting in 2025-01-01T03:00:00.000+01:00.

makeZoned

The makeZoned function works similarly to unsafeMakeZoned but provides a safer approach. Instead of throwing an error when the input is invalid, it returns an Option<Zoned>. If the input is invalid, it returns None. If valid, it returns Some containing the Zoned.

Example (Safely Creating a Zoned DateTime)

1
import { DateTime, Option } from "effect"
2

3
//      ┌─── Option<Zoned>
4
//      ▼
5
const zoned = DateTime.makeZoned(new Date("2025-01-01 04:00:00"), {
6
  timeZone: "Europe/Rome",
7
})
8

9
if (Option.isSome(zoned)) {
10
  console.log("The DateTime is valid")
11
}

makeZonedFromString

Creates a Zoned by parsing a string in the format YYYY-MM-DDTHH:mm:ss.sss+HH:MM[IANA timezone identifier].

If the input string is valid, the function returns a Some containing the Zoned. If the input is invalid, it returns None.

Example (Parsing a Zoned DateTime from a String)

1
import { DateTime, Option } from "effect"
2

3
//      ┌─── Option<Zoned>
4
//      ▼
5
const zoned = DateTime.makeZonedFromString("2025-01-01T03:00:00.000+01:00[Europe/Rome]")
6

7
if (Option.isSome(zoned)) {
8
  console.log("The DateTime is valid")
9
}

Current Time

now

Provides the current UTC time as a Effect<Utc>, using the Clock service.

Example (Retrieving the Current UTC Time)

1
import { DateTime, Effect } from "effect"
2

3
const program = Effect.gen(function* () {
4
  //      ┌─── Utc
5
  //      ▼
6
  const currentTime = yield* DateTime.now
7
})

unsafeNow

Retrieves the current UTC time immediately using Date.now(), without the Clock service.

Example (Getting the Current UTC Time Immediately)

1
import { DateTime } from "effect"
2

3
//      ┌─── Utc
4
//      ▼
5
const currentTime = DateTime.unsafeNow()

Guards

Function	Description
`isDateTime`	Checks if a value is a `DateTime`.
`isTimeZone`	Checks if a value is a `TimeZone`.
`isTimeZoneOffset`	Checks if a value is a `TimeZone.Offset`.
`isTimeZoneNamed`	Checks if a value is a `TimeZone.Named`.
`isUtc`	Checks if a `DateTime` is the `Utc` variant.
`isZoned`	Checks if a `DateTime` is the `Zoned` variant.

Example (Validating a DateTime)

1
import { DateTime } from "effect"
2

3
function printDateTimeInfo(x: unknown) {
4
  if (DateTime.isDateTime(x)) {
5
    console.log("This is a valid DateTime")
6
  } else {
7
    console.log("Not a DateTime")
8
  }
9
}

Time Zone Management

Function	Description
`setZone`	Creates a `Zoned` from `DateTime` by applying the given `TimeZone`.
`setZoneOffset`	Creates a `Zoned` from `DateTime` using a fixed offset (in ms).
`setZoneNamed`	Creates a `Zoned` from `DateTime` from an IANA time zone identifier or returns `None` if invalid.
`unsafeSetZoneNamed`	Creates a `Zoned` from `DateTime` from an IANA time zone identifier or throws if invalid.
`zoneUnsafeMakeNamed`	Creates a `TimeZone.Named` from a IANA time zone identifier or throws if the identifier is invalid.
`zoneMakeNamed`	Creates a `TimeZone.Named` from a IANA time zone identifier or returns `None` if invalid.
`zoneMakeNamedEffect`	Creates a `Effect<TimeZone.Named, IllegalArgumentException>` from a IANA time zone identifier failing with `IllegalArgumentException` if invalid
`zoneMakeOffset`	Creates a `TimeZone.Offset` from a numeric offset in milliseconds.
`zoneMakeLocal`	Creates a `TimeZone.Named` from the system’s local time zone.
`zoneFromString`	Attempts to parse a time zone from a string, returning `None` if invalid.
`zoneToString`	Returns a string representation of a `TimeZone`.

Example (Applying a Time Zone to a DateTime)

1
import { DateTime } from "effect"
2

3
// Create a UTC DateTime
4
//
5
//     ┌─── Utc
6
//     ▼
7
const utc = DateTime.unsafeMake("2024-01-01")
8

9
// Create a named time zone for New York
10
//
11
//      ┌─── TimeZone.Named
12
//      ▼
13
const zoneNY = DateTime.zoneUnsafeMakeNamed("America/New_York")
14

15
// Apply it to the DateTime
16
//
17
//      ┌─── Zoned
18
//      ▼
19
const zoned = DateTime.setZone(utc, zoneNY)
20

21
console.log(zoned)
22
// Output: DateTime.Zoned(2023-12-31T19:00:00.000-05:00[America/New_York])

zoneFromString

Parses a string to create a DateTime.TimeZone.

This function attempts to interpret the input string as either:

A numeric time zone offset (e.g., “GMT”, “+01:00”)
An IANA time zone identifier (e.g., “Europe/London”)

If the string matches an offset format, it is converted into a TimeZone.Offset. Otherwise, it attempts to create a TimeZone.Named using the input.

If the input string is invalid, Option.none() is returned.

Example (Parsing a Time Zone from a String)

1
import { DateTime, Option } from "effect"
2

3
// Attempt to parse a numeric offset
4
const offsetZone = DateTime.zoneFromString("+01:00")
5
console.log(Option.isSome(offsetZone))
6
// Output: true
7

8
// Attempt to parse an IANA time zone
9
const namedZone = DateTime.zoneFromString("Europe/London")
10
console.log(Option.isSome(namedZone))
11
// Output: true
12

13
// Invalid input
14
const invalidZone = DateTime.zoneFromString("Invalid/Zone")
15
console.log(Option.isSome(invalidZone))
16
// Output: false

Comparisons

Function	Description
`distance`	Returns the difference (in ms) between two `DateTime`s.
`distanceDurationEither`	Returns a `Left` or `Right` `Duration` depending on order.
`distanceDuration`	Returns a `Duration` indicating how far apart two times are.
`min`	Returns the earlier of two `DateTime` values.
`max`	Returns the later of two `DateTime` values.
`greaterThan`, `greaterThanOrEqualTo`, etc.	Checks ordering between two `DateTime` values.
`between`	Checks if a `DateTime` lies within the given bounds.
`isFuture`, `isPast`, `unsafeIsFuture`, etc.	Checks if a `DateTime` is in the future or past.

Example (Finding the Distance Between Two DateTimes)

1
import { DateTime } from "effect"
2

3
const utc1 = DateTime.unsafeMake("2025-01-01T00:00:00Z")
4
const utc2 = DateTime.add(utc1, { days: 1 })
5

6
console.log(DateTime.distance(utc1, utc2))
7
// Output: 86400000 (one day)
8

9
console.log(DateTime.distanceDurationEither(utc1, utc2))
10
/*
11
Output:
12
{
13
  _id: 'Either',
14
  _tag: 'Right',
15
  right: { _id: 'Duration', _tag: 'Millis', millis: 86400000 }
16
}
17
*/
18

19
console.log(DateTime.distanceDuration(utc1, utc2))
20
// Output: { _id: 'Duration', _tag: 'Millis', millis: 86400000 }

Conversions

Function	Description
`toDateUtc`	Returns a JavaScript `Date` in UTC.
`toDate`	Applies the time zone (if present) and converts to a JavaScript `Date`.
`zonedOffset`	For a `Zoned` DateTime, returns the time zone offset in ms.
`zonedOffsetIso`	For a `Zoned` DateTime, returns an ISO offset string like “+01:00”.
`toEpochMillis`	Returns the Unix epoch time in milliseconds.
`removeTime`	Returns a `Utc` with the time cleared (only date remains).

Parts

Function	Description
`toParts`	Returns time zone adjusted date parts (including weekday).
`toPartsUtc`	Returns UTC date parts (including weekday).
`getPart` / `getPartUtc`	Retrieves a specific part (e.g., `"year"` or `"month"`) from the date.
`setParts` / `setPartsUtc`	Updates certain parts of a date, preserving or ignoring the time zone.

Example (Extracting Parts from a DateTime)

1
import { DateTime } from "effect"
2

3
const zoned = DateTime.setZone(
4
  DateTime.unsafeMake("2024-01-01"),
5
  DateTime.zoneUnsafeMakeNamed("Europe/Rome"),
6
)
7

8
console.log(DateTime.getPart(zoned, "month"))
9
// Output: 1

Math

Function	Description
`addDuration`	Adds the given `Duration` to a `DateTime`.
`subtractDuration`	Subtracts the given `Duration` from a `DateTime`.
`add`	Adds numeric parts (e.g., `{ hours: 2 }`) to a `DateTime`.
`subtract`	Subtracts numeric parts.
`startOf`	Moves a `DateTime` to the start of the given unit (e.g., the beginning of a day or month).
`endOf`	Moves a `DateTime` to the end of the given unit.
`nearest`	Rounds a `DateTime` to the nearest specified unit.

Formatting

Function	Description
`format`	Formats a `DateTime` as a string using the `DateTimeFormat` API.
`formatLocal`	Uses the system’s local time zone and locale for formatting.
`formatUtc`	Forces UTC formatting.
`formatIntl`	Uses a provided `Intl.DateTimeFormat`.
`formatIso`	Returns an ISO 8601 string in UTC.
`formatIsoDate`	Returns an ISO date string, adjusted for the time zone.
`formatIsoDateUtc`	Returns an ISO date string in UTC.
`formatIsoOffset`	Formats a `Zoned` as a string with an offset like “+01:00”.
`formatIsoZoned`	Formats a `Zoned` in the form `YYYY-MM-DDTHH:mm:ss.sss+HH:MM[Zone]`.

Layers for Current Time Zone

Function	Description
`CurrentTimeZone`	A service tag for the current time zone.
`setZoneCurrent`	Sets a `DateTime` to use the current time zone.
`withCurrentZone`	Provides an effect with a specified time zone.
`withCurrentZoneLocal`	Uses the system’s local time zone for the effect.
`withCurrentZoneOffset`	Uses a fixed offset (in ms) for the effect.
`withCurrentZoneNamed`	Uses a named time zone identifier (e.g., “Europe/London”).
`nowInCurrentZone`	Retrieves the current time as a `Zoned` in the configured time zone.
`layerCurrentZone`	Creates a Layer providing the `CurrentTimeZone` service.
`layerCurrentZoneOffset`	Creates a Layer from a fixed offset.
`layerCurrentZoneNamed`	Creates a Layer from a named time zone, failing if invalid.
`layerCurrentZoneLocal`	Creates a Layer from the system’s local time zone.

Example (Using the Current Time Zone in an Effect)

1
import { DateTime, Effect } from "effect"
2

3
// Retrieve the current time in the "Europe/London" time zone
4
const program = Effect.gen(function* () {
5
  const zonedNow = yield* DateTime.nowInCurrentZone
6
  console.log(zonedNow)
7
}).pipe(DateTime.withCurrentZoneNamed("Europe/London"))
8

9
Effect.runFork(program)
10
/*
11
Example Output:
12
DateTime.Zoned(2025-01-06T18:36:38.573+00:00[Europe/London])
13
*/