Time Zone Day Planner

Utility for re-timing scheduled moments across time zones while respecting local-day boundaries and daylight-saving quirks.

Capabilities

Preserve instant across zones

• Converting 2024-11-03T05:30:00-04:00[America/New_York] to Europe/London reports 2024-11-03T09:30:00+00:00[Europe/London] while representing the same moment in time @test

Replace local clock time on the same date

• Replacing the clock time of 2024-11-03T12:00:00-04:00[America/New_York] with 01:30 keeps the date and zone, yielding 2024-11-03T01:30:00-04:00[America/New_York] @test

Identify start of local day

• The start of day for 2024-03-10T12:00:00-05:00[America/New_York] is 2024-03-10T00:00:00-05:00[America/New_York] @test

Report day length in hours

• The local day containing 2024-03-10T12:00:00-05:00[America/New_York] spans 23 hours because of daylight saving changes @test

Implementation

@generates

API

export type IsoZonedDateTimeString = string;

/**
 * Expresses the same absolute moment in a target time zone, returning an ISO string whose local date/time reflect that zone's offset rules.
 */
export function changeTimeZone(input: IsoZonedDateTimeString, targetTimeZone: string): IsoZonedDateTimeString;

/**
 * Replaces the clock time on the same calendar date and zone as the input using a `HH:mm[:ss]` 24-hour string, preserving offset rules for that zone.
 */
export function replaceLocalTime(input: IsoZonedDateTimeString, newLocalTime: string): IsoZonedDateTimeString;

/**
 * Returns the start-of-day instant for the calendar date and zone of the input.
 */
export function startOfLocalDay(input: IsoZonedDateTimeString): IsoZonedDateTimeString;

/**
 * Reports how many hours exist in the calendar day of the input, accounting for daylight-saving transitions.
 */
export function hoursInLocalDay(input: IsoZonedDateTimeString): number;

Dependencies { .dependencies }

temporal-polyfill { .dependency }

Provides rich date-time and time-zone aware primitives to manipulate zoned date-times, day boundaries, and daylight-saving aware calculations. @satisfied-by