Multi-zone Timeline Builder

Create a utility that normalizes a list of time-bound segments into a target time zone, preserving exact elapsed time and producing summaries that respect local calendar days. Inputs use ISO strings with explicit offsets and time zone annotations; outputs must keep that format at minute precision.

Capabilities

Normalize segment timestamps

• Given target zone Europe/London and a single segment { id: "flight", start: "2024-06-01T07:15-07:00[America/Los_Angeles]", end: "2024-06-01T15:05-04:00[America/New_York]" }, buildTimeline returns one entry with startInTarget = "2024-06-01T15:15:00+01:00[Europe/London]" and endInTarget = "2024-06-01T20:05:00+01:00[Europe/London]" while preserving the original order. @test

Compute durations across zones

• For the segment { id: "overnight", start: "2024-02-01T10:00+01:00[Europe/Berlin]", end: "2024-02-01T09:30-05:00[America/New_York]" } with target zone UTC, buildTimeline reports startInTarget = "2024-02-01T09:00:00+00:00[UTC]", endInTarget = "2024-02-01T14:30:00+00:00[UTC]", durationMinutes = 330, and durationISO = "PT5H30M". @test

Handle daylight shifts

• With target zone America/Los_Angeles and the segment { id: "dst-gap", start: "2024-03-10T01:50-08:00[America/Los_Angeles]", end: "2024-03-10T03:10-07:00[America/Los_Angeles]" }, normalization keeps offsets on each side of the daylight-saving jump and yields durationMinutes = 20 and durationISO = "PT20M". @test

Summarize by target day

• Using target zone America/Los_Angeles and segments { id: "tokyo", start: "2024-12-31T23:30+09:00[Asia/Tokyo]", end: "2025-01-01T01:00+09:00[Asia/Tokyo]" } and { id: "newyears-call", start: "2025-01-01T10:00+09:00[Asia/Tokyo]", end: "2025-01-01T11:00+09:00[Asia/Tokyo]" }, summarizeByDay emits a single summary { dateInTarget: "2024-12-31", totalMinutes: 150, earliestStart: "2024-12-31T06:30:00-08:00[America/Los_Angeles]", latestEnd: "2024-12-31T18:00:00-08:00[America/Los_Angeles]" }. @test

Implementation

@generates

API

export type TimelineSegmentInput = {
  id: string;
  start: string; // ISO string with offset and time zone, e.g. "2024-06-01T07:15-07:00[America/Los_Angeles]"
  end: string;   // ISO string with offset and time zone
};

export type TimelineSegment = {
  id: string;
  startInTarget: string; // ISO string with offset and time zone at minute precision for the target zone
  endInTarget: string;   // ISO string with offset and time zone at minute precision for the target zone
  durationMinutes: number;
  durationISO: string;   // ISO 8601 duration string at minute precision
};

export type DaySummary = {
  dateInTarget: string;  // YYYY-MM-DD for the target zone day
  totalMinutes: number;
  earliestStart: string; // ISO string with offset and time zone at minute precision
  latestEnd: string;     // ISO string with offset and time zone at minute precision
};

export function buildTimeline(
  segments: TimelineSegmentInput[],
  targetTimeZone: string
): TimelineSegment[];

export function summarizeByDay(
  segments: TimelineSegmentInput[],
  targetTimeZone: string
): DaySummary[];

Dependencies { .dependencies }

temporal-polyfill { .dependency }

Provides the Temporal namespace for parsing ISO inputs with time zones and performing precise time-zone-aware math.