DateTime
Works with absolute instants, UTC date-times, zoned date-times, and time zones.
A DateTime always represents an absolute point in time with epoch milliseconds. It may also carry a TimeZone for calendar parts, formatting, and zone-aware transformations. This module includes constructors, time-zone helpers, comparisons, date arithmetic, current-time effects, and formatting functions.
Accessors
nowInCurrentZone
Signature
declare const nowInCurrentZone: Effect.Effect<Zoned, never, CurrentTimeZone>;setZoneCurrent
Sets the time zone of a DateTime to the current time zone, which is determined by the CurrentTimeZone service.
Signature
declare function setZoneCurrent(self: DateTime): Effect<Zoned, never, CurrentTimeZone>;Comparisons
Checks whether a DateTime is between two other DateTime values (inclusive).
Signature
declare const between: {
(options: { maximum: DateTime; minimum: DateTime }): (self: DateTime) => boolean;
(
self: DateTime,
options: {
maximum: DateTime;
minimum: DateTime;
},
): boolean;
};Computes the difference between two DateTime values, returning a Duration representing the amount of time between them.
Details
If other is *after* self, the result will be a positive Duration. If other is *before* self, the result will be a negative Duration. If they are equal, the result will be a Duration of zero.
Signature
declare const distance: {
(other: DateTime): (self: DateTime) => Duration;
(self: DateTime, other: DateTime): Duration;
};Checks effectfully if a DateTime is in the future compared to the current time.
Details
This is an effectful operation that uses the current time from the Clock service.
Signature
declare const isFuture: (self: DateTime) => Effect.Effect<boolean>;isFutureUnsafe
Checks synchronously if a DateTime is in the future compared to the current time.
When to use
Use when checking whether a DateTime is in the future with a synchronous live-clock read and Clock-based testability is not needed.
Details
This is a synchronous version that uses Date.now() directly.
Signature
declare const isFutureUnsafe: (self: DateTime) => boolean;Example
(Checking future DateTime values unsafely)
import { DateTime } from "effect"
const oneHourFromNow = DateTime.add(DateTime.nowUnsafe(), { hours: 1 })
DateTime.isFutureUnsafe(oneHourFromNow)isGreaterThan
Checks whether the first DateTime is after the second DateTime.
Signature
declare const isGreaterThan: {
(that: DateTime): (self: DateTime) => boolean;
(self: DateTime, that: DateTime): boolean;
};isGreaterThanOrEqualTo
Checks whether the first DateTime is after or equal to the second DateTime.
Signature
declare const isGreaterThanOrEqualTo: {
(that: DateTime): (self: DateTime) => boolean;
(self: DateTime, that: DateTime): boolean;
};isLessThan
Checks whether the first DateTime is before the second DateTime.
Signature
declare const isLessThan: {
(that: DateTime): (self: DateTime) => boolean;
(self: DateTime, that: DateTime): boolean;
};isLessThanOrEqualTo
Checks whether the first DateTime is before or equal to the second DateTime.
Signature
declare const isLessThanOrEqualTo: {
(that: DateTime): (self: DateTime) => boolean;
(self: DateTime, that: DateTime): boolean;
};Checks effectfully if a DateTime is in the past compared to the current time.
Details
This is an effectful operation that uses the current time from the Clock service.
Signature
declare const isPast: (self: DateTime) => Effect.Effect<boolean>;isPastUnsafe
Checks synchronously if a DateTime is in the past compared to the current time.
When to use
Use when checking whether a DateTime is in the past with a synchronous live-clock read and Clock-based testability is not needed.
Details
This is a synchronous version that uses Date.now() directly.
Signature
declare const isPastUnsafe: (self: DateTime) => boolean;Example
(Checking past DateTime values unsafely)
import { DateTime } from "effect"
const oneHourAgo = DateTime.subtract(DateTime.nowUnsafe(), { hours: 1 })
DateTime.isPastUnsafe(oneHourAgo)Returns the later of two DateTime values.
Signature
declare const max: {
<That extends DateTime>(that: That): <Self extends DateTime>(self: Self) => That | Self;
<Self extends DateTime, That extends DateTime>(self: Self, that: That): Self | That;
};Returns the earlier of two DateTime values.
Signature
declare const min: {
<That extends DateTime>(that: That): <Self extends DateTime>(self: Self) => That | Self;
<Self extends DateTime, That extends DateTime>(self: Self, that: That): Self | That;
};Constructors
fromDateUnsafe
Create a DateTime from a Date.
Details
If the Date is invalid, an IllegalArgumentError will be thrown.
Signature
declare const fromDateUnsafe: (date: Date) => Utc;fromEpochSeconds
Creates a DateTime.Utc from the number of seconds since the Unix epoch.
Signature
declare const fromEpochSeconds: (seconds: number) => Utc;Creates a DateTime safely from supported input values.
Details
- A DateTime - A JavaScript Date - The number of milliseconds since the Unix epoch - An object with date and time parts - A string that can be parsed as a date
Returns Some with the constructed DateTime when the input is valid, or None when construction would fail, including invalid Date instances or unparseable strings.
Signature
declare const make: <A extends DateTime.Input>(input: A) => Option.Option<DateTime.PreserveZone<A>>;makeUnsafe
Create a DateTime from supported input values.
When to use
Use when creating a DateTime from trusted input and construction failures should throw an IllegalArgumentError instead of returning Option.none.
Details
- A DateTime - A Date instance (invalid dates will throw an IllegalArgumentError) - The number of milliseconds since the Unix epoch - An object with the parts of a date - A string that can be parsed by Date.parse
Signature
declare const makeUnsafe: <A extends DateTime.Input>(input: A) => DateTime.PreserveZone<A>;Creates a DateTime.Zoned safely from an input and a time zone.
Details
By default, the input is interpreted as a UTC instant and the time zone is attached without changing that instant. When adjustForTimeZone is true, the input is interpreted as wall-clock time in the target zone.
When adjustForTimeZone is true, disambiguation controls daylight-saving gaps and repeated times:
- "compatible" (default): chooses the earlier occurrence for repeated times and the later interpretation for gaps - "earlier": chooses the earlier possible instant - "later": chooses the later possible instant - "reject": rejects ambiguous or nonexistent wall-clock times
Returns Some when construction succeeds, or None when the input, time zone, or disambiguation cannot be resolved.
Signature
declare const makeZoned: (
input: DateTime.Input,
options?: {
readonly adjustForTimeZone?: boolean;
readonly disambiguation?: Disambiguation;
readonly timeZone?: number | string | TimeZone;
},
) => Option.Option<Zoned>;makeZonedFromString
Parses an ISO zoned date-time string into a DateTime.Zoned safely.
Details
Accepts named-zone strings such as YYYY-MM-DDTHH:mm:ss.sss+HH:MM[Time/Zone] and offset-only strings such as YYYY-MM-DDTHH:mm:ss.sss+HH:MM. Returns None when the input cannot be parsed.
Signature
declare const makeZonedFromString: (input: string) => Option.Option<Zoned>;makeZonedUnsafe
Create a DateTime.Zoned using DateTime.makeUnsafe and a time zone.
When to use
Use when the date/time input and zone options are trusted and invalid or rejected ambiguous times should throw instead of returning Option.none.
Details
The input is treated as UTC and then the time zone is attached, unless adjustForTimeZone is set to true. In that case, the input is treated as already in the time zone.
When adjustForTimeZone is true and ambiguous times occur during DST transitions, the disambiguation option controls how to resolve the ambiguity: - compatible (default): Choose earlier time for repeated times, later for gaps - earlier: Always choose the earlier of two possible times - later: Always choose the later of two possible times - reject: Throw an error when ambiguous times are encountered
Signature
declare const makeZonedUnsafe: (
input: DateTime.Input,
options?: {
readonly adjustForTimeZone?: boolean;
readonly disambiguation?: Disambiguation;
readonly timeZone?: number | string | TimeZone;
},
) => Zoned;Gets the current time using the Clock service and converts it to a DateTime.
Signature
declare const now: Effect.Effect<Utc>;Gets the current time from the Clock service and returns it as a JavaScript Date.
Signature
declare const nowAsDate: Effect.Effect<Date>;Gets the current time using Date.now.
When to use
Use when synchronous wall-clock access outside an Effect program is acceptable and testability through the Clock service is not needed.
Details
This is a synchronous version of now that directly uses Date.now() instead of the Effect Clock service.
Signature
declare const nowUnsafe: LazyArg<Utc>;zoneMakeLocal
Create a named time zone from the system's local time zone.
Details
This uses the system's configured time zone, which may vary depending on the runtime environment.
Signature
declare const zoneMakeLocal: () => TimeZone.Named;zoneMakeNamed
Creates a named time zone safely from an IANA time zone identifier.
Details
If the time zone is invalid, None will be returned.
Signature
declare const zoneMakeNamed: (zoneId: string) => Option.Option<TimeZone.Named>;zoneMakeNamedEffect
Creates a named time zone effectfully from an IANA time zone identifier.
When to use
Use when invalid IANA zone ids should fail in the Effect error channel instead of returning Option.none or throwing.
Signature
declare const zoneMakeNamedEffect: (
zoneId: string,
) => Effect.Effect<TimeZone.Named, IllegalArgumentError>;zoneMakeNamedUnsafe
Attempts to create a named time zone from an IANA time zone identifier.
When to use
Use when the IANA zone id is trusted and invalid zones should throw instead of returning Option.none or failing in Effect.
Details
If the time zone is invalid, an IllegalArgumentError will be thrown.
Signature
declare const zoneMakeNamedUnsafe: (zoneId: string) => TimeZone.Named;zoneMakeOffset
Create a fixed offset time zone.
Details
The offset is specified in milliseconds from UTC. Positive values are ahead of UTC, negative values are behind UTC.
Signature
declare const zoneMakeOffset: (offset: number) => TimeZone.Offset;Converting
removeTime
Removes the time aspect of a DateTime, first adjusting for the time zone. It will return a DateTime.Utc only containing the date.
Signature
declare const removeTime: (self: DateTime) => Utc;Converts a DateTime to a Date, applying the time zone first.
Details
For DateTime.Zoned, this adjusts for the time zone before converting. For DateTime.Utc, this is equivalent to toDateUtc.
Signature
declare const toDate: (self: DateTime) => Date;Gets the UTC Date of a DateTime.
Details
This always returns the UTC representation, ignoring any time zone information.
Signature
declare const toDateUtc: (self: DateTime) => Date;toEpochMillis
Gets the milliseconds since the Unix epoch of a DateTime.
Details
This returns the UTC timestamp regardless of any time zone information.
Signature
declare const toEpochMillis: (self: DateTime) => number;toEpochSeconds
Converts a DateTime to the number of seconds since the Unix epoch.
Details
This returns the UTC timestamp regardless of any time zone information. The result is floored to the nearest second.
Signature
declare const toEpochSeconds: (self: DateTime) => number;Converts a DateTime to a UTC DateTime.
When to use
Use to represent the same instant in UTC instead of its current time zone.
Details
The returned value keeps the same epoch milliseconds and changes only the DateTime representation to UTC.
Signature
declare const toUtc: (self: DateTime) => Utc;zonedOffset
Computes the time zone offset of a DateTime.Zoned in milliseconds.
Details
Returns the offset from UTC in milliseconds. Positive values indicate time zones ahead of UTC, negative values indicate time zones behind UTC.
Signature
declare const zonedOffset: (self: Zoned) => number;zonedOffsetIso
Formats the time zone offset of a DateTime.Zoned as an ISO string.
Details
The offset is formatted as "±HH:MM".
Signature
declare const zonedOffsetIso: (self: Zoned) => string;Decoding
zoneFromString
Tries to parse a TimeZone from a string safely.
Details
Supports both IANA time zone identifiers and offset formats like "+03:00".
Signature
declare const zoneFromString: (zone: string) => Option.Option<TimeZone>;Encoding
zoneToString
Formats a TimeZone as a string.
Signature
declare const zoneToString: (self: TimeZone) => string;Formatting
Formats a DateTime with Intl.DateTimeFormat.
Details
Unless a timeZone option is supplied, UTC values are formatted in UTC and zoned values are formatted in their named zone or fixed-offset zone.
Fixed-offset zones depend on runtime support for offset timeZone identifiers. When unsupported, formatting falls back to UTC with the DateTime adjusted to the offset.
Signature
declare const format: {
(
options?: DateTimeFormatOptions & {
readonly locale?: string;
},
): (self: DateTime) => string;
(
self: DateTime,
options?: DateTimeFormatOptions & {
readonly locale?: string;
},
): string;
};formatIntl
Formats a DateTime as a string using the Intl.DateTimeFormat API.
When to use
Use when you already have an Intl.DateTimeFormat and want it to control the locale, time zone, and formatting options.
Details
The formatter receives the DateTime epoch milliseconds. Any time zone conversion comes from the supplied formatter.
See
Signature
declare const formatIntl: {
(format: DateTimeFormat): (self: DateTime) => string;
(self: DateTime, format: DateTimeFormat): string;
};Formats a DateTime as a UTC ISO string.
Details
Always returns the UTC representation in ISO 8601 format, ignoring any time zone.
Signature
declare const formatIso: (self: DateTime) => string;formatIsoDate
Formats a DateTime as a time zone adjusted ISO date string.
Details
Returns only the date part (YYYY-MM-DD) after applying time zone adjustments.
Signature
declare const formatIsoDate: (self: DateTime) => string;formatIsoDateUtc
Formats a DateTime as a UTC ISO date string.
Details
Returns only the date part (YYYY-MM-DD) in UTC, ignoring any time zone.
Signature
declare const formatIsoDateUtc: (self: DateTime) => string;formatIsoOffset
Formats a DateTime.Zoned as an ISO string with an offset.
Details
For DateTime.Utc, returns the same as formatIso. For DateTime.Zoned, includes the time zone offset in the format.
Signature
declare const formatIsoOffset: (self: DateTime) => string;formatIsoZoned
Formats a DateTime.Zoned as a string.
Details
It uses the format: YYYY-MM-DDTHH:mm:ss.sss+HH:MM[Time/Zone].
Signature
declare const formatIsoZoned: (self: Zoned) => string;formatLocal
Formats a DateTime with Intl.DateTimeFormat using the system local time zone and locale.
Signature
declare const formatLocal: {
(
options?: DateTimeFormatOptions & {
readonly locale?: string;
},
): (self: DateTime) => string;
(
self: DateTime,
options?: DateTimeFormatOptions & {
readonly locale?: string;
},
): string;
};Formats a DateTime with Intl.DateTimeFormat using the UTC time zone.
Details
This forces the time zone to be UTC.
Signature
declare const formatUtc: {
(
options?: DateTimeFormatOptions & {
readonly locale?: string;
},
): (self: DateTime) => string;
(
self: DateTime,
options?: DateTimeFormatOptions & {
readonly locale?: string;
},
): string;
};Getters
Gets one time-zone-adjusted part of a DateTime as a number.
Details
The part will be time zone adjusted.
Signature
declare const getPart: {
(part: keyof PartsWithWeekday): (self: DateTime) => number;
(self: DateTime, part: keyof PartsWithWeekday): number;
};getPartUtc
Gets one UTC part of a DateTime as a number.
Details
The part will be in the UTC time zone.
Signature
declare const getPartUtc: {
(part: keyof PartsWithWeekday): (self: DateTime) => number;
(self: DateTime, part: keyof PartsWithWeekday): number;
};Gets the time-zone-adjusted parts of a DateTime as an object.
Details
The parts will be time zone adjusted if the DateTime is zoned.
Signature
declare const toParts: (self: DateTime) => DateTime.PartsWithWeekday;toPartsUtc
Gets the UTC parts of a DateTime as an object.
Details
The parts will always be in UTC, ignoring any time zone information.
Signature
declare const toPartsUtc: (self: DateTime) => DateTime.PartsWithWeekday;Guards
isDateTime
Checks whether a value is a DateTime.
When to use
Use to narrow an unknown value before treating it as a DateTime.
See
Signature
declare const isDateTime: (u: unknown) => u is DateTime;isTimeZone
Checks whether a value is a TimeZone.
When to use
Use to narrow unknown input to any TimeZone before passing it to APIs that accept either fixed-offset or named time zones.
See
isTimeZoneOffsetfor narrowing to fixed-offset time zonesisTimeZoneNamedfor narrowing to named time zones
Signature
declare const isTimeZone: (u: unknown) => u is TimeZone;isTimeZoneNamed
Checks whether a value is a named TimeZone (IANA time zone).
When to use
Use to narrow an unknown value to the TimeZone.Named variant before reading named-zone fields such as id.
See
isTimeZonefor checking either time zone variantisTimeZoneOffsetfor narrowing to fixed-offset time zones
Signature
declare const isTimeZoneNamed: (u: unknown) => u is TimeZone.Named;isTimeZoneOffset
Checks whether a value is an offset-based TimeZone.
When to use
Use when you need to narrow an unknown or union TimeZone value to the fixed-offset variant before reading its offset in milliseconds.
See
isTimeZonefor checking either time zone variantisTimeZoneNamedfor narrowing to named time zones
Signature
declare const isTimeZoneOffset: (u: unknown) => u is TimeZone.Offset;Checks whether a DateTime is a UTC DateTime (no time zone information).
When to use
Use to narrow a DateTime before passing it to code that requires a UTC value without an associated time zone.
See
Signature
declare const isUtc: (self: DateTime) => self is Utc;Checks whether a DateTime is a zoned DateTime (has time zone information).
When to use
Use to narrow a known DateTime before reading its zone or passing it to APIs that require DateTime.Zoned.
See
Signature
declare const isZoned: (self: DateTime) => self is Zoned;Instances
Equivalence
Provides an Equivalence for comparing two DateTime values for equality.
Details
Two DateTime values are considered equivalent if they represent the same point in time, regardless of their time zone.
Signature
declare const Equivalence: Equ.Equivalence<DateTime>;Provides an Order for comparing and sorting DateTime values.
Details
DateTime values are ordered by their epoch milliseconds, so earlier times come before later times regardless of time zone.
Signature
declare const Order: order.Order<DateTime>;Layers
layerCurrentZone
Create a Layer from the given time zone.
Details
This layer provides the CurrentTimeZone service with the specified time zone.
Signature
declare const layerCurrentZone: (resource: NoInfer<TimeZone>) => Layer.Layer<CurrentTimeZone>;layerCurrentZoneLocal
Create a Layer from the system's local time zone.
Details
This layer provides the CurrentTimeZone service using the system's configured local time zone.
Signature
declare const layerCurrentZoneLocal: Layer.Layer<CurrentTimeZone>;layerCurrentZoneNamed
Create a Layer from the given IANA time zone identifier.
Details
This layer provides the CurrentTimeZone service with a named time zone. If the time zone identifier is invalid, the layer will fail.
Signature
declare const layerCurrentZoneNamed: (
zoneId: string,
) => Layer.Layer<CurrentTimeZone, IllegalArgumentError>;layerCurrentZoneOffset
Create a Layer from the given time zone offset.
Details
This layer provides the CurrentTimeZone service with a fixed offset time zone.
Signature
declare function layerCurrentZoneOffset(offset: number): Layer<CurrentTimeZone>;Mapping
mapEpochMillis
Transforms a DateTime by applying a function to the number of milliseconds since the Unix epoch.
Signature
declare const mapEpochMillis: {
(f: (millis: number) => number): <A extends DateTime>(self: A) => A;
<A extends DateTime>(self: A, f: (millis: number) => number): A;
};Pattern match on a DateTime to handle Utc and Zoned cases differently.
Signature
declare const match: {
<A, B>(options: {
readonly onUtc: (_: Utc) => A;
readonly onZoned: (_: Zoned) => B;
}): (self: DateTime) => A | B;
<A, B>(
self: DateTime,
options: {
readonly onUtc: (_: Utc) => A;
readonly onZoned: (_: Zoned) => B;
},
): A | B;
};Modifies a DateTime with a mutable local Date copy.
When to use
Use to adjust calendar fields in the DateTime's own time zone with an existing Date mutation API.
Details
The Date will first have the time zone applied if possible, and then be converted back to a DateTime within the same time zone.
Supports disambiguation when the new wall clock time is ambiguous.
Signature
declare const mutate: {
(
f: (date: Date) => void,
options?: {
readonly disambiguation?: Disambiguation;
},
): <A extends DateTime>(self: A) => A;
<A extends DateTime>(
self: A,
f: (date: Date) => void,
options?: {
readonly disambiguation?: Disambiguation;
},
): A;
};Modifies a DateTime with a mutable UTC Date copy.
When to use
Use to adjust the instant with an existing Date mutation API that works on UTC calendar fields.
Signature
declare const mutateUtc: {
(f: (date: Date) => void): <A extends DateTime>(self: A) => A;
<A extends DateTime>(self: A, f: (date: Date) => void): A;
};Applies a function to a JavaScript Date representing the DateTime and returns the function's result.
Details
The callback receives the time-zone-adjusted wall-clock date for DateTime.Zoned values. Use DateTime.withDateUtc when the callback should receive the UTC instant.
Signature
declare const withDate: {
<A>(f: (date: Date) => A): (self: DateTime) => A;
<A>(self: DateTime, f: (date: Date) => A): A;
};withDateUtc
Applies a function to a JavaScript Date representing the DateTime's UTC instant and returns the function's result.
Details
This ignores any associated time zone. Use DateTime.withDate when the callback should receive the time-zone-adjusted wall-clock date.
Signature
declare const withDateUtc: {
<A>(f: (date: Date) => A): (self: DateTime) => A;
<A>(self: DateTime, f: (date: Date) => A): A;
};Math
Adds the given amount of unit to a DateTime.
Details
The time zone is taken into account when adding days, weeks, months, and years.
Signature
declare const add: {
(parts: Partial<DateTime.PartsForMath>): <A extends DateTime>(self: A) => A;
<A extends DateTime>(self: A, parts: Partial<DateTime.PartsForMath>): A;
};addDuration
Adds the given Duration to a DateTime.
When to use
Use to move a DateTime by an elapsed duration such as minutes, seconds, or milliseconds.
Details
The duration is converted to milliseconds and added to the epoch milliseconds. Zoned values keep their original time zone.
Gotchas
This is elapsed-time arithmetic, not calendar-aware local date arithmetic. Use add when adding days, weeks, months, or years should account for the date/time zone rules.
See
addfor calendar-aware date/time part arithmeticsubtractDurationfor subtracting an elapsed duration
Signature
declare const addDuration: {
(duration: Input): <A extends DateTime>(self: A) => A;
<A extends DateTime>(self: A, duration: Input): A;
};Converts a DateTime to the end of the given part.
Details
If the part is week, the weekStartsOn option can be used to specify the day of the week that the week starts on. The default is 0 (Sunday).
Signature
declare const endOf: {
(
part: UnitSingular,
options?: {
readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
},
): <A extends DateTime>(self: A) => A;
<A extends DateTime>(
self: A,
part: UnitSingular,
options?: {
readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
},
): A;
};Converts a DateTime to the nearest given part.
Details
If the part is week, the weekStartsOn option can be used to specify the day of the week that the week starts on. The default is 0 (Sunday).
Signature
declare const nearest: {
(
part: UnitSingular,
options?: {
readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
},
): <A extends DateTime>(self: A) => A;
<A extends DateTime>(
self: A,
part: UnitSingular,
options?: {
readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
},
): A;
};Converts a DateTime to the start of the given part.
Details
If the part is week, the weekStartsOn option can be used to specify the day of the week that the week starts on. The default is 0 (Sunday).
Signature
declare const startOf: {
(
part: UnitSingular,
options?: {
readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
},
): <A extends DateTime>(self: A) => A;
<A extends DateTime>(
self: A,
part: UnitSingular,
options?: {
readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
},
): A;
};Subtracts the given amount of unit from a DateTime.
Signature
declare const subtract: {
(parts: Partial<DateTime.PartsForMath>): <A extends DateTime>(self: A) => A;
<A extends DateTime>(self: A, parts: Partial<DateTime.PartsForMath>): A;
};subtractDuration
Subtracts the given Duration from a DateTime.
Signature
declare const subtractDuration: {
(duration: Input): <A extends DateTime>(self: A) => A;
<A extends DateTime>(self: A, duration: Input): A;
};Models
A DateTime represents a point in time. It can optionally have a time zone associated with it.
Signature
type DateTime = Utc | Zoned;Disambiguation type
A Disambiguation is used to resolve ambiguities when a DateTime is ambiguous, such as during a daylight saving time transition.
Details
For more information, see the [Temporal documentation](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";Represents a time zone used by DateTime.Zoned.
Details
A TimeZone is either a fixed offset from UTC or a named IANA time zone.
Signature
type TimeZone = TimeZone.Offset | TimeZone.Named;Represents a DateTime stored as an absolute UTC instant with no associated time zone.
Details
Use DateTime.isUtc to narrow a DateTime to this variant.
Signature
interface Utc extends Proto {
readonly _tag: "Utc";
readonly epochMilliseconds: number;
partsUtc: PartsWithWeekday | undefined;
}Represents a DateTime with an associated TimeZone.
Details
A zoned value still represents an absolute instant through epochMilliseconds, while the time zone is used for wall-clock parts, formatting, and zone-aware transformations.
Signature
interface Zoned extends Proto {
readonly _tag: "Zoned";
adjustedEpochMilliseconds: number | undefined;
readonly epochMilliseconds: number;
partsAdjusted: PartsWithWeekday | undefined;
partsUtc: PartsWithWeekday | undefined;
readonly zone: TimeZone;
}Ordering
Returns a DateTime constrained between a minimum and maximum value.
Details
If the DateTime is before the minimum, the minimum is returned. If the DateTime is after the maximum, the maximum is returned. Otherwise, the original DateTime is returned.
Signature
declare const clamp: {
<Min extends DateTime, Max extends DateTime>(options: {
readonly maximum: Max;
readonly minimum: Min;
}): <A extends DateTime>(self: A) => Min | Max | A;
<A extends DateTime, Min extends DateTime, Max extends DateTime>(
self: A,
options: {
readonly maximum: Max;
readonly minimum: Min;
},
): A | Min | Max;
};Other
Providing Services
withCurrentZone
Provides the CurrentTimeZone to an effect.
Signature
declare const withCurrentZone: {
(value: TimeZone): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, Exclude<R, CurrentTimeZone>>;
<A, E, R>(self: Effect<A, E, R>, value: TimeZone): Effect<A, E, Exclude<R, CurrentTimeZone>>;
};withCurrentZoneLocal
Provides the CurrentTimeZone to an effect, using the system's local time zone.
Signature
declare function withCurrentZoneLocal<A, E, R>(
effect: Effect<A, E, R>,
): Effect<A, E, Exclude<R, CurrentTimeZone>>;withCurrentZoneNamed
Provides the CurrentTimeZone to an effect using an IANA time zone identifier.
Details
If the time zone is invalid, it will fail with an IllegalArgumentError.
Signature
declare const withCurrentZoneNamed: {
(
zone: string,
): <A, E, R>(
effect: Effect<A, E, R>,
) => Effect<A, IllegalArgumentError | E, Exclude<R, CurrentTimeZone>>;
<A, E, R>(
effect: Effect<A, E, R>,
zone: string,
): Effect<A, IllegalArgumentError | E, Exclude<R, CurrentTimeZone>>;
};withCurrentZoneOffset
Provides the CurrentTimeZone to an effect, using an offset.
Signature
declare const withCurrentZoneOffset: {
(offset: number): <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, Exclude<R, CurrentTimeZone>>;
<A, E, R>(effect: Effect<A, E, R>, offset: number): Effect<A, E, Exclude<R, CurrentTimeZone>>;
};Services
CurrentTimeZone
Context service that supplies the ambient TimeZone for APIs that work in the current zone, such as DateTime.setZoneCurrent and DateTime.nowInCurrentZone.
Details
Provide it with DateTime.withCurrentZone, one of the withCurrentZone* helpers, or one of the layerCurrentZone* layers.
Signature
declare class CurrentTimeZone extends Shape<"effect/DateTime/CurrentTimeZone", TimeZone, this> {
constructor(_: never);
}Transforming
Sets time-zone-adjusted parts on a DateTime.
Details
The date will be time zone adjusted for DateTime.Zoned.
Signature
declare const setParts: {
(parts: Partial<DateTime.PartsWithWeekday>): <A extends DateTime>(self: A) => A;
<A extends DateTime>(self: A, parts: Partial<DateTime.PartsWithWeekday>): A;
};setPartsUtc
Sets UTC parts on a DateTime.
Details
The parts are always interpreted as UTC, ignoring any time zone information.
Signature
declare const setPartsUtc: {
(parts: Partial<DateTime.PartsWithWeekday>): <A extends DateTime>(self: A) => A;
<A extends DateTime>(self: A, parts: Partial<DateTime.PartsWithWeekday>): A;
};Sets the time zone of a DateTime, returning a new DateTime.Zoned.
Signature
declare const setZone: {
(
zone: TimeZone,
options?: {
readonly adjustForTimeZone?: boolean;
readonly disambiguation?: Disambiguation;
},
): (self: DateTime) => Zoned;
(
self: DateTime,
zone: TimeZone,
options?: {
readonly adjustForTimeZone?: boolean;
readonly disambiguation?: Disambiguation;
},
): Zoned;
};setZoneNamed
Sets the time zone of a DateTime safely from an IANA time zone identifier. If the time zone is invalid, None will be returned.
Signature
declare const setZoneNamed: {
(
zoneId: string,
options?: {
readonly adjustForTimeZone?: boolean;
readonly disambiguation?: Disambiguation;
},
): (self: DateTime) => Option<Zoned>;
(
self: DateTime,
zoneId: string,
options?: {
readonly adjustForTimeZone?: boolean;
readonly disambiguation?: Disambiguation;
},
): Option<Zoned>;
};setZoneNamedUnsafe
Sets the time zone of a DateTime from an IANA time zone identifier. If the time zone is invalid, an IllegalArgumentError will be thrown.
Signature
declare const setZoneNamedUnsafe: {
(
zoneId: string,
options?: {
readonly adjustForTimeZone?: boolean;
readonly disambiguation?: Disambiguation;
},
): (self: DateTime) => Zoned;
(
self: DateTime,
zoneId: string,
options?: {
readonly adjustForTimeZone?: boolean;
readonly disambiguation?: Disambiguation;
},
): Zoned;
};setZoneOffset
Adds a fixed offset time zone to a DateTime.
Details
The offset is in milliseconds.
Signature
declare const setZoneOffset: {
(
offset: number,
options?: {
readonly adjustForTimeZone?: boolean;
readonly disambiguation?: Disambiguation;
},
): (self: DateTime) => Zoned;
(
self: DateTime,
offset: number,
options?: {
readonly adjustForTimeZone?: boolean;
readonly disambiguation?: Disambiguation;
},
): Zoned;
};
Gets the current time as a
DateTime.Zoned, using theCurrentTimeZone.