resolveLocal

Signature

resolveLocal(localDateTime: string, timeZone: string, optionsArg?: { disambiguation?: "compatible" | "earlier" | "later" | "reject" | undefined; }): string

Resolve a zoneless local wall time in a time zone and return the instant it names.

• Feeds deliver wall times with no offset all the time — “gate-out 08:00” — and turning one into an instant takes a zone the sender did not send plus a policy for the two days a year the mapping is not one-to-one. This states both.
• Call classifyLocal first to find out whether the wall time is ambiguous or nonexistent before a disambiguation policy is applied.
• Returns a UTC instant, exactly — no rounding, so a nanosecond wall time survives. Pass it to toOffsetInstant for the offset pair, or reach for convertPlainDateTimeToZoned when what you want is the bracketed zoned string (it defaults to millisecond precision).
• localDateTime is a PlainDateTime string, as isValidDateTime accepts: <date>T<time> with no offset (an offset means the wall time already resolved). Its RFC 9557 annotations are read as Temporal.PlainDateTime.from reads them, so a time zone annotation ([America/New_York]) is ignored and timeZone alone resolves the wall time.
• Returns "" on invalid input.
• timeZone may be a UTC offset, including one getTimeZoneOffset returned with seconds. A fixed offset names one instant for every wall time, so disambiguation has nothing to decide and "reject" does not reject.

Parameters

Parameter	Type	Description
localDateTime	string	zoneless ISO 8601 local datetime string (e.g. “2024-11-03T01:30:00”)
timeZone	string	IANA name or UTC offset the wall time is read in: a time zone identifier (+05:30, +0530, -08) or a stored offset (±HH:MM[:SS], what getTimeZoneOffset returns)

Options

optionsArg

How an ambiguous or nonexistent wall time is resolved

Option	Type	Default	Description
disambiguation?	"compatible" | "earlier" | "later" | "reject" (Disambiguation)	"compatible", Temporal’s default.	What happens when the wall time is ambiguous (a fall-back hour that happens twice) or nonexistent (a spring-forward hour that never happens). "compatible" takes the earlier instant of an ambiguous time and the later one of a nonexistent time, "earlier" and "later" take that side in both cases, and "reject" returns "" rather than resolving.

Returns

UTC instant string ending in “Z”, or "" on invalid input

Related types

• Disambiguation

Examples

import { resolveLocal } from "@northguild/gmt/instant/convert";

resolveLocal("2024-07-15T12:00:00", "America/New_York") // "2024-07-15T16:00:00Z"

localDateTime

output

 

Source

instant/convert/resolveLocal.ts