Multi-Form Temporal Conversion

Build a utility that normalizes a single point in time across multiple calendar and time-zone views and supports moving scheduled times between zones while keeping their underlying instant intact.

Capabilities

Instant snapshot across representations

• Given an ISO 8601 UTC timestamp and a target IANA time zone, return aligned representations for that same moment: the original instant string, a zone-aware timestamp string that includes numeric offset and bracketed zone id, a local date-time string, a date-only string, a time-only string, a year-month string, and a month-day string. Example input 2024-11-05T12:30:00Z with America/New_York yields instantIso: "2024-11-05T12:30:00Z", zonedIso: "2024-11-05T07:30:00-05:00[America/New_York]", plainDateTimeIso: "2024-11-05T07:30:00", plainDateIso: "2024-11-05", plainTimeIso: "07:30:00", yearMonthIso: "2024-11", monthDayIso: "11-05". @test

Shift scheduled time to a new zone

• Given a zone-aware timestamp string, a destination IANA zone, and optional preference for handling gaps/overlaps, produce a new zone-aware timestamp string that represents the same instant in the target zone. Example input 2024-06-01T12:00:00+01:00[Europe/London] to America/Los_Angeles yields 2024-06-01T04:00:00-07:00[America/Los_Angeles] while preserving the original instant. @test

Resolve ambiguous local time into an instant

• Given a date string, a wall-clock time string, an IANA time zone, and a disambiguation hint (earlier, later, or default-compatible), produce both the resolved instant string and the resulting zone-aware timestamp string. Example input date 2021-11-07, time 01:30:00, zone America/New_York, hint later yields instantIso: "2021-11-07T06:30:00Z" and zonedIso: "2021-11-07T01:30:00-05:00[America/New_York]". @test

Implementation

@generates

API

export interface ConversionBundle {
  instantIso: string;
  zonedIso: string;
  plainDateTimeIso: string;
  plainDateIso: string;
  plainTimeIso: string;
  yearMonthIso: string;
  monthDayIso: string;
}

/**
 * Normalizes a point in time given either an instant string or a zone-aware timestamp string plus a time zone to resolve local components.
 * When both inputs are present, prefer the instant string and use the zone-aware value only as a fallback.
 */
export function snapshotMoment(input: {
  instantIso?: string;
  zonedIso?: string;
  timeZone: string;
}): ConversionBundle;

/**
 * Converts a scheduled time from one zone to another while keeping the instant constant.
 */
export function shiftScheduledTime(options: {
  zonedIso: string;
  targetZone: string;
  disambiguation?: "earlier" | "later" | "compatible";
}): ConversionBundle;

/**
 * Resolves a wall-clock date and time into a precise instant and zone-aware timestamp using the provided disambiguation strategy when overlaps or gaps occur.
 */
export function resolveLocalInstant(options: {
  dateIso: string;
  timeIso: string;
  timeZone: string;
  disambiguation?: "earlier" | "later" | "compatible";
}): {
  instantIso: string;
  zonedIso: string;
};

Dependencies { .dependencies }

temporal-polyfill { .dependency }

Modern date/time toolkit providing timezone-aware instants and calendar-aware conversions.