getDstTransitions

Signature

getDstTransitions(timeZone: string, year: number): DstTransition[]

List every DST transition instant for a time zone (an IANA name or a UTC offset) within a given year.

• A “transition” is any UTC offset change: a spring-forward gap (nonexistent local time) or a fall-back overlap (ambiguous local time) — see docs/dst-disambiguation.md for the gap/overlap terminology. This is distinct from hasDaylightSaving (whether a zone observes DST at all) and from the disambiguation/offset options (what to do when constructing a single instant that lands in a gap/overlap).
• Most zones have 0 or 2 transitions per year; some (e.g. Africa/Casablanca, which pauses DST for Ramadan) can have more.
• A transition landing exactly on local January 1 00:00 belongs to that year (e.g. Asia/Singapore moving to +08:00 at the start of 1982).
• Returns [] for an invalid timeZone, a non-integer year, or a valid zone with zero transitions in that year (not an error case), and when the scan exhausts its internal bound — never a partial list.
• A UTC offset, with or without seconds ("+05:30", "-00:44:30"), never changes, so it has no transitions and returns [] for every year.

Parameters

Parameter	Type	Description
timeZone	string	IANA name or UTC offset: a time zone identifier (+05:30, +0530, -08) or a stored offset (±HH:MM[:SS], what getTimeZoneOffset returns)
year	number	calendar year to scan (must be an integer)

Returns

array of { instant, offsetBefore, offsetAfter }, in chronological order

Types

DstTransition

A single DST transition instant: the UTC instant of an offset change plus the offset in effect immediately before and after it.

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

Member	Type	Description
instant	string	The UTC instant of the offset change, ISO 8601 ending in Z (e.g. 2024-03-10T07:00:00Z).
offsetBefore	string	The UTC offset in effect immediately before the transition (e.g. -05:00).
offsetAfter	string	The UTC offset in effect immediately after the transition (e.g. -04:00).

Examples

import { getDstTransitions } from "@northguild/gmt/zoned/get";

getDstTransitions("America/New_York", 2024)
// [
//   { instant: "2024-03-10T07:00:00Z", offsetBefore: "-05:00", offsetAfter: "-04:00" },
//   { instant: "2024-11-03T06:00:00Z", offsetBefore: "-04:00", offsetAfter: "-05:00" },
// ]

year

output

 

DST Transition Inspector

1. Find transitions

Year

Type	Local Date	Local Hour	UTC Instant	Offset Before → After

2. Probe a moment

A local hour that was skipped during spring-forward — requires disambiguation.

Disambiguation: compatible takes the later instant in a gap and the earlier one in an overlap. earlier and later take that instant. reject gives no result.

 

Source

zoned/get/getDstTransitions.ts