Offset-Aware Schedule Toolkit

A module that resolves local schedule requests into precise instants across DST changes, with explicit disambiguation and transition queries.

Capabilities

Resolves ambiguous or skipped local start times

• Resolves 2021-11-07 01:30 in America/New_York with disambiguation "earlier" to an instant using offset -04:00. @test
• Rejects 2021-03-14 02:30 in America/New_York when disambiguation is "reject" because the local time does not exist. @test
• When the request includes an expected offset that differs from the resolved offset (e.g., expecting -05:00 for 2021-11-07 01:30 America/New_York), it throws a mismatch error. @test

Generates daily occurrences across DST boundaries

• For a daily 01:30 Europe/London schedule from 2021-10-30 through 2021-11-01 with disambiguation "earlier", it returns three occurrences with ISO instants and offsets [+01:00,+01:00,+00:00] and marks the day where the offset changes with a transitionNote. @test

Queries the next offset transition

• Returns the next offset change for Europe/London after 2021-10-30T00:00:00Z, including the exact instant and before/after offsets; returns null when no transition occurs within 365 days. @test

Implementation

@generates

API

export type Disambiguation = "earlier" | "later" | "reject";

export interface LocalScheduleRequest {
  date: string;        // ISO date, e.g., "2021-11-07"
  time: string;        // 24h local time, e.g., "01:30"
  timeZone: string;    // IANA zone id
  offset?: string;     // Optional expected offset like "-04:00"
  disambiguation?: Disambiguation;
}

export interface Occurrence {
  instant: string;         // ISO instant (UTC) string
  localDateTime: string;   // Local date-time string in the target zone
  offset: string;          // Offset used for the occurrence
  transitionNote?: string; // Present when a DST/offset boundary was crossed
}

export interface TransitionInfo {
  at: string;           // ISO instant when the next transition occurs
  offsetBefore: string; // Offset before the transition
  offsetAfter: string;  // Offset after the transition
}

export function resolveStart(request: LocalScheduleRequest): Occurrence;

export function buildDailySchedule(
  request: LocalScheduleRequest,
  throughDate: string
): Occurrence[];

export function nextTransition(
  timeZone: string,
  afterInstant?: string
): TransitionInfo | null;

Dependencies { .dependencies }

temporal-polyfill { .dependency }

Provides time-zone aware date-time math with explicit disambiguation and offset transition queries.