Timeboxed Timeline Planner

Build a timezone-aware planner that stitches together work segments, reports gaps, rounds checkpoints, and picks the earliest moment using the provided modern date/time dependency. Inputs are ISO strings with explicit offsets or IANA time zone annotations; outputs must preserve zone information.

Capabilities

Build timeline from segments

• Starting at 2024-05-10T09:00-04:00[America/New_York] with segment lengths [90, 45, 30] (minutes), returns segment endpoints {"segments":["2024-05-10T10:30-04:00[America/New_York]","2024-05-10T11:15-04:00[America/New_York]","2024-05-10T11:45-04:00[America/New_York]"],"finalEnd":"2024-05-10T11:45-04:00[America/New_York]"} @test

Measure gap between sessions

• For currentEndIso="2024-05-10T17:00+01:00[Europe/London]" and nextStartIso="2024-05-10T12:15-04:00[America/New_York]", returns a whole-minute gap of 15 (next start is 15 minutes after current end) @test

Round checkpoints

• Rounds 2024-05-10T11:07:20-04:00[America/New_York] to the nearest 15-minute boundary in the same zone using half-up semantics (ties go to the later boundary), yielding 2024-05-10T11:15-04:00[America/New_York] @test

Find earliest moment

• From ["2024-05-10T09:00Z","2024-05-10T10:00+02:00","2024-05-10T05:05-04:00[America/New_York]"], returns 2024-05-10T10:00+02:00 because it represents the earliest instant when comparing across offsets @test

Implementation

@generates

API

export type TimelineResult = {
  segments: string[]; // ISO strings (with offset/zone) marking end of each segment
  finalEnd: string; // ISO string for end of the final segment
};

export function buildTimeline(startIso: string, segmentMinutes: number[]): TimelineResult;

export function gapInMinutes(currentEndIso: string, nextStartIso: string): number;

export function roundCheckpoint(checkpointIso: string, minuteIncrement: number): string;

export function earliestMoment(instants: string[]): string;

Dependencies { .dependencies }

temporal-polyfill { .dependency }

Provides modern timezone-aware date/time types and arithmetic utilities for ISO strings and IANA zones.

@satisfied-by