classifyLocal

Signature

classifyLocal(localDateTime: string, timeZone: string): LocalTimeClassification | null

Report whether a zoneless local wall time is unique, ambiguous or nonexistent in a zone — before any policy resolves it.

Ambiguous and nonexistent wall times are the single most common datetime bug there is: 01:30 happens twice on a fall-back day and never on a spring-forward one. resolveLocal will pick one for you; this exists so a demurrage clock, a medication window or a duty limit can refuse instead, or route the case to a human, rather than silently accepting whichever instant a default handed it.
Reads the zone’s own transition table via Temporal, so it is right for every IANA zone and every year, including 30- and 45-minute shifts and zones that skipped a whole calendar day changing sides of the date line.
localDateTime is a PlainDateTime string, as isValidDateTime accepts: <date>T<time> with no offset (a string with an offset has no ambiguity left to report). Its RFC 9557 annotations are read as Temporal.PlainDateTime.from reads them, so a time zone annotation is ignored and timeZone alone is the zone.
Returns null on invalid input — never "unique", which would read as a verdict.
timeZone may be a UTC offset, including one getTimeZoneOffset returned with seconds. A fixed offset names one instant for every wall time, so the classification is always "unique".

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)

“unique” | “ambiguous” | “nonexistent”, or null on invalid input

What a zoneless wall time turns out to be once a zone is attached to it.

import type { LocalTimeClassification } from "@northguild/gmt";

"unique" | "ambiguous" | "nonexistent"

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

classifyLocal("2024-07-15T12:00:00", "America/New_York") // "unique"

localDateTimetimeZone