(
input: DateTime.Input,
options?: {
readonly timeZone?: number | string | TimeZone | undefined
readonly adjustForTimeZone?: boolean | undefined
readonly disambiguation?: Disambiguation | undefined
}
): ZonedCreate 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 gapsearlier: Always choose the earlier of two possible timeslater: Always choose the later of two possible timesreject: Throw an error when ambiguous times are encountered
Example (Creating zoned DateTime values unsafely)
import { DateTime } from "effect"
const zoned = DateTime.makeZonedUnsafe("2024-06-15T14:30:00Z", {
timeZone: "Europe/London"
})
console.log(DateTime.formatIsoZoned(zoned)) // "2024-06-15T15:30:00.000+01:00[Europe/London]"export const const makeZonedUnsafe: (
input: DateTime.Input,
options?: {
readonly timeZone?:
| number
| string
| TimeZone
| undefined
readonly adjustForTimeZone?:
| boolean
| undefined
readonly disambiguation?:
| Disambiguation
| undefined
}
) => Zoned
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 gapsearlier: Always choose the earlier of two possible timeslater: Always choose the later of two possible timesreject: Throw an error when ambiguous times are encountered
Example (Creating zoned DateTime values unsafely)
import { DateTime } from "effect"
const zoned = DateTime.makeZonedUnsafe("2024-06-15T14:30:00Z", {
timeZone: "Europe/London"
})
console.log(DateTime.formatIsoZoned(zoned)) // "2024-06-15T15:30:00.000+01:00[Europe/London]"
makeZonedUnsafe: (input: DateTime.Inputinput: DateTime.type DateTime.Input = string | number | DateTime | Partial<DateTime.Parts> | DateTime.Instant | DateTime.InstantWithZone | DateInput accepted by DateTime.make, DateTime.makeUnsafe, and the zoned
constructors.
Details
Includes existing DateTime values, partial date parts, epoch-millisecond
objects, epoch milliseconds, JavaScript Date instances, and parseable date
strings.
Input, options: {
readonly timeZone?:
| number
| string
| TimeZone
| undefined
readonly adjustForTimeZone?: boolean | undefined
readonly disambiguation?:
| Disambiguation
| undefined
}
timeZone?: number | string | TimeZone | undefinedtimeZone?: number | string | type TimeZone = TimeZone.Offset | TimeZone.NamedRepresents a time zone used by DateTime.Zoned.
Details
A TimeZone is either a fixed offset from UTC or a named IANA time zone.
Companion namespace containing the public variant and protocol types for
TimeZone.
TimeZone | undefined
readonly adjustForTimeZone?: boolean | undefinedadjustForTimeZone?: boolean | undefined
readonly disambiguation?: Disambiguation | undefineddisambiguation?: type Disambiguation =
| "compatible"
| "earlier"
| "later"
| "reject"
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
-
"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.
Example (Resolving ambiguous local times)
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.zoneMakeNamedUnsafe("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)
Disambiguation | undefined
}) => Zoned = import InternalInternal.const makeZonedUnsafe: (
input: DateTime.DateTime.Input,
options?: {
readonly timeZone?:
| number
| string
| DateTime.TimeZone
| undefined
readonly adjustForTimeZone?:
| boolean
| undefined
readonly disambiguation?:
| DateTime.Disambiguation
| undefined
}
) => DateTime.Zoned