Skip to main content Link Search Menu Expand Document (external link)
effect

DateTime overview

Added in v3.6.0

Table of contents

comparisons

between

Signature

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

Added in v3.6.0

distance

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

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

Added in v3.6.0

distanceDuration

Calulate the distance between two DateTime values.

Signature

export declare const distanceDuration: {
  (other: DateTime): (self: DateTime) => Duration.Duration
  (self: DateTime, other: DateTime): Duration.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)
})

Added in v3.6.0

distanceDurationEither

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

export declare const distanceDurationEither: {
  (other: DateTime): (self: DateTime) => Either.Either<Duration.Duration, Duration.Duration>
  (self: DateTime, other: DateTime): Either.Either<Duration.Duration, 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)
})

Added in v3.6.0

greaterThan

Signature

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

Added in v3.6.0

greaterThanOrEqualTo

Signature

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

Added in v3.6.0

isFuture

Signature

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

Added in v3.6.0

isPast

Signature

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

Added in v3.6.0

lessThan

Signature

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

Added in v3.6.0

lessThanOrEqualTo

Signature

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

Added in v3.6.0

max

Signature

export declare const max: { (that: DateTime): (self: DateTime) => DateTime; (self: DateTime, that: DateTime): DateTime }

Added in v3.6.0

min

Signature

export declare const min: { (that: DateTime): (self: DateTime) => DateTime; (self: DateTime, that: DateTime): DateTime }

Added in v3.6.0

unsafeIsFuture

Signature

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

Added in v3.6.0

unsafeIsPast

Signature

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

Added in v3.6.0

constructors

make

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

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

Added in v3.6.0

makeZoned

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

The input is treated as UTC and then the time zone is attached.

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

Signature

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

Example

import { DateTime } from "effect"

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

Added in v3.6.0

makeZonedFromString

Create a DateTime.Zoned from a string.

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

Signature

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

Added in v3.6.0

now

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

Signature

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

Example

import { DateTime, Effect } from "effect"

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

Added in v3.6.0

unsafeFromDate

Create a DateTime from a Date.

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

Signature

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

Added in v3.6.0

unsafeMake

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

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

Added in v3.6.0

unsafeMakeZoned

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

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

Example

import { DateTime } from "effect"

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

Added in v3.6.0

unsafeNow

Get the current time using Date.now.

Signature

export declare const unsafeNow: LazyArg<Utc>

Added in v3.6.0

conversions

removeTime

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

Signature

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

Added in v3.6.0

toDate

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

Signature

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

Added in v3.6.0

toDateUtc

Get the UTC Date of a DateTime.

Signature

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

Added in v3.6.0

toEpochMillis

Get the milliseconds since the Unix epoch of a DateTime.

Signature

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

Added in v3.6.0

zonedOffset

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

Signature

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

Added in v3.6.0

zonedOffsetIso

Calculate the time zone offset of a DateTime in milliseconds.

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

Signature

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

Added in v3.6.0

current time zone

CurrentTimeZone (class)

Signature

export declare class CurrentTimeZone

Added in v3.6.0

layerCurrentZone

Create a Layer from the given time zone.

Signature

export declare const layerCurrentZone: (zone: TimeZone) => Layer.Layer<CurrentTimeZone>

Added in v3.6.0

layerCurrentZoneLocal

Create a Layer from the systems local time zone.

Signature

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

Added in v3.6.0

layerCurrentZoneNamed

Create a Layer from the given IANA time zone identifier.

Signature

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

Added in v3.6.0

layerCurrentZoneOffset

Create a Layer from the given time zone offset.

Signature

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

Added in v3.6.0

nowInCurrentZone

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

Signature

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

Added in v3.6.0

setZoneCurrent

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

Signature

export declare const setZoneCurrent: (self: DateTime) => Effect.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"))

Added in v3.6.0

withCurrentZone

Provide the CurrentTimeZone to an effect.

Signature

export declare const withCurrentZone: {
  (zone: TimeZone): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, CurrentTimeZone>>
  <A, E, R>(effect: Effect.Effect<A, E, R>, zone: TimeZone): Effect.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))

Added in v3.6.0

withCurrentZoneLocal

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

Signature

export declare const withCurrentZoneLocal: <A, E, R>(
  effect: Effect.Effect<A, E, R>
) => Effect.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)

Added in v3.6.0

withCurrentZoneNamed

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

export declare const withCurrentZoneNamed: {
  (
    zone: string
  ): <A, E, R>(
    effect: Effect.Effect<A, E, R>
  ) => Effect.Effect<A, E | IllegalArgumentException, Exclude<R, CurrentTimeZone>>
  <A, E, R>(
    effect: Effect.Effect<A, E, R>,
    zone: string
  ): Effect.Effect<A, E | IllegalArgumentException, 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"))

Added in v3.6.0

withCurrentZoneOffset

Provide the CurrentTimeZone to an effect, using a offset.

Signature

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

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

Added in v3.6.0

formatting

format

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

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

Added in v3.6.0

formatIntl

Format a DateTime as a string using the DateTimeFormat API.

Signature

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

Added in v3.6.0

formatIso

Format a DateTime as a UTC ISO string.

Signature

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

Added in v3.6.0

formatIsoDate

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

Signature

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

Added in v3.6.0

formatIsoDateUtc

Format a DateTime as a UTC ISO date string.

Signature

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

Added in v3.6.0

formatIsoOffset

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

Signature

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

Added in v3.6.0

formatIsoZoned

Format a DateTime.Zoned as a string.

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

Signature

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

Added in v3.6.0

formatLocal

Format a DateTime as a string using the DateTimeFormat API.

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

Signature

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

Added in v3.6.0

formatUtc

Format a DateTime as a string using the DateTimeFormat API.

This forces the time zone to be UTC.

Signature

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

Added in v3.6.0

guards

isDateTime

Signature

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

Added in v3.6.0

isTimeZone

Signature

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

Added in v3.6.0

isTimeZoneNamed

Signature

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

Added in v3.6.0

isTimeZoneOffset

Signature

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

Added in v3.6.0

isUtc

Signature

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

Added in v3.6.0

isZoned

Signature

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

Added in v3.6.0

instances

Equivalence

Signature

export declare const Equivalence: Equivalence_.Equivalence<DateTime>

Added in v3.6.0

Order

Signature

export declare const Order: order.Order<DateTime>

Added in v3.6.0

mapping

mapEpochMillis

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

Signature

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

Example

import { DateTime } from "effect"

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

Added in v3.6.0

match

Signature

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

Added in v3.6.0

mutate

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.

Signature

export declare const mutate: {
  (f: (date: Date) => void): <A extends DateTime>(self: A) => DateTime.PreserveZone<A>
  <A extends DateTime>(self: A, f: (date: Date) => void): DateTime.PreserveZone<A>
}

Added in v3.6.0

mutateUtc

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

Signature

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

Added in v3.6.0

withDate

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

Signature

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

Added in v3.6.0

withDateUtc

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

Signature

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

Added in v3.6.0

math

add

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

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

Example

import { DateTime } from "effect"

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

Added in v3.6.0

addDuration

Add the given Duration to a DateTime.

Signature

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

Example

import { DateTime } from "effect"

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

Added in v3.6.0

endOf

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

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

Added in v3.6.0

nearest

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

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

Added in v3.6.0

startOf

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

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

Added in v3.6.0

subtract

Subtract the given amount of unit’s from a DateTime.

Signature

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

Example

import { DateTime } from "effect"

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

Added in v3.6.0

subtractDuration

Subtract the given Duration from a DateTime.

Signature

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

Example

import { DateTime } from "effect"

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

Added in v3.6.0

models

DateTime (type alias)

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

Signature

export type DateTime = Utc | Zoned

Added in v3.6.0

DateTime (namespace)

Added in v3.6.0

Parts (interface)

Signature

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

Added in v3.6.0

PartsForMath (interface)

Signature

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

Added in v3.6.0

PartsWithWeekday (interface)

Signature

export interface PartsWithWeekday {
  readonly millis: number
  readonly seconds: number
  readonly minutes: number
  readonly hours: number
  readonly day: number
  readonly weekDay: number
  readonly month: number
  readonly year: number
}

Added in v3.6.0

Proto (interface)

Signature

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

Added in v3.6.0

Input (type alias)

Signature

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

Added in v3.6.0

PreserveZone (type alias)

Signature

export type PreserveZone<A extends DateTime.Input> = A extends Zoned ? Zoned : Utc

Added in v3.6.0

Unit (type alias)

Signature

export type Unit = UnitSingular | UnitPlural

Added in v3.6.0

UnitPlural (type alias)

Signature

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

Added in v3.6.0

UnitSingular (type alias)

Signature

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

Added in v3.6.0

TimeZone (type alias)

Signature

export type TimeZone = TimeZone.Offset | TimeZone.Named

Added in v3.6.0

TimeZone (namespace)

Added in v3.6.0

Named (interface)

Signature

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

Added in v3.6.0

Offset (interface)

Signature

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

Added in v3.6.0

Proto (interface)

Signature

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

Added in v3.6.0

Utc (interface)

Signature

export interface Utc extends DateTime.Proto {
  readonly _tag: "Utc"
  readonly epochMillis: number
  /** @internal */
  partsUtc: DateTime.PartsWithWeekday
}

Added in v3.6.0

Zoned (interface)

Signature

export interface Zoned extends DateTime.Proto {
  readonly _tag: "Zoned"
  readonly epochMillis: number
  readonly zone: TimeZone
  /** @internal */
  adjustedEpochMillis?: number
  /** @internal */
  partsAdjusted?: DateTime.PartsWithWeekday
  /** @internal */
  partsUtc?: DateTime.PartsWithWeekday
}

Added in v3.6.0

parts

getPart

Get a part of a DateTime as a number.

The part will be time zone adjusted.

Signature

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

Example

import { DateTime } from "effect"

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

Added in v3.6.0

getPartUtc

Get a part of a DateTime as a number.

The part will be in the UTC time zone.

Signature

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

Example

import { DateTime } from "effect"

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

Added in v3.6.0

setParts

Set the different parts of a DateTime as an object.

The Date will be time zone adjusted.

Signature

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

Added in v3.6.0

setPartsUtc

Set the different parts of a DateTime as an object.

Signature

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

Added in v3.6.0

toParts

Get the different parts of a DateTime as an object.

The parts will be time zone adjusted.

Signature

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

Added in v3.6.0

toPartsUtc

Get the different parts of a DateTime as an object.

The parts will be in UTC.

Signature

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

Added in v3.6.0

time zones

setZone

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

Signature

export declare const setZone: {
  (zone: TimeZone, options?: { readonly adjustForTimeZone?: boolean | undefined }): (self: DateTime) => Zoned
  (self: DateTime, zone: TimeZone, options?: { readonly adjustForTimeZone?: boolean | undefined }): 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)
})

Added in v3.6.0

setZoneNamed

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

Signature

export declare const setZoneNamed: {
  (
    zoneId: string,
    options?: { readonly adjustForTimeZone?: boolean | undefined }
  ): (self: DateTime) => Option.Option<Zoned>
  (self: DateTime, zoneId: string, options?: { readonly adjustForTimeZone?: boolean | undefined }): Option.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")
})

Added in v3.6.0

setZoneOffset

Add a fixed offset time zone to a DateTime.

The offset is in milliseconds.

Signature

export declare const setZoneOffset: {
  (offset: number, options?: { readonly adjustForTimeZone?: boolean | undefined }): (self: DateTime) => Zoned
  (self: DateTime, offset: number, options?: { readonly adjustForTimeZone?: boolean | undefined }): 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)
})

Added in v3.6.0

unsafeSetZoneNamed

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

export declare const unsafeSetZoneNamed: {
  (zoneId: string, options?: { readonly adjustForTimeZone?: boolean | undefined }): (self: DateTime) => Zoned
  (self: DateTime, zoneId: string, options?: { readonly adjustForTimeZone?: boolean | undefined }): Zoned
}

Example

import { DateTime, Effect } from "effect"

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

Added in v3.6.0

zoneFromString

Try parse a TimeZone from a string

Signature

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

Added in v3.6.0

zoneMakeLocal

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

Signature

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

Added in v3.6.0

zoneMakeNamed

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

Signature

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

Added in v3.6.0

zoneMakeNamedEffect

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

Signature

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

Added in v3.6.0

zoneMakeOffset

Create a fixed offset time zone.

Signature

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

Added in v3.6.0

zoneToString

Format a TimeZone as a string.

Signature

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

Added in v3.6.0

zoneUnsafeMakeNamed

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

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

Added in v3.6.0

type ids

TimeZoneTypeId

Signature

export declare const TimeZoneTypeId: typeof TimeZoneTypeId

Added in v3.6.0

TimeZoneTypeId (type alias)

Signature

export type TimeZoneTypeId = typeof TimeZoneTypeId

Added in v3.6.0

TypeId

Signature

export declare const TypeId: typeof TypeId

Added in v3.6.0

TypeId (type alias)

Signature

export type TypeId = typeof TypeId

Added in v3.6.0

utils

clamp

Signature

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

Added in v3.6.0