datetime/timeseries_gap_utils library

Gap detection and grid filling for roughly-regular time series — roadmap #606.

For a series of samples that SHOULD arrive at a fixed cadence (a sensor every minute, a heartbeat every 30s), these helpers find where samples went missing, reconstruct the ideal regular grid so callers can see which slots were empty, and forward-fill a parallel value list across the holes.

Inputs are sorted defensively (the caller need not pre-sort). A "gap" is a delta between consecutive samples larger than the expected interval by more than tolerance (a fraction): with the default 0.5, a delta over 1.5x the expected interval is a gap, absorbing normal jitter without false positives.

Functions

fillMissing(List<DateTime> timestamps, Duration interval) → List<DateTime>

The complete regular grid of timestamps from the earliest to the latest of timestamps, stepping by interval; callers compare it against the input to see which slots were missing.

findGaps(List<DateTime> timestamps, Duration expectedInterval, {double tolerance = 0.5}) → List<({DateTime end, DateTime start})>

Gaps [start, end] (the inclusive bounding sample pair) where consecutive timestamps are spaced more than expectedInterval * (1 + tolerance) apart.

forwardFill(List<num?> values) → List<num?>

A copy of values with each null replaced by the most recent non-null value before it (last-observation-carried-forward). LEADING nulls have no prior value and stay null.