Timeseries Downsample

Type-aware downsampling for metrics that keeps the peak instead of averaging it away: gauges and counters aggregated by their own correct rules, gaps kept distinct from real zeros, and epoch-aligned buckets so two people looking at the same data see the same shape.

THE SILENT FAILURE. Downsampling is treated as a display concern -- 'just draw fewer points' -- until the reduction itself throws away the evidence, and the chart that comes out the other end still looks fine. Nobody gets an error. The line is smooth, it fits the axis, it tells a story. The story is wrong.

AVERAGING HIDES PEAKS. A 30-second spike to 100% CPU inside a 5-minute average bucket barely moves the average -- noticeable, but on a chart scaled to 100 it reads as 'slightly warm,' not 'saturated.' The system was pegged and the graph shows a healthy service. Gauge buckets here return min, max, avg, count and last, so the peak survives next to the mean instead of being buried inside it.

AVERAGING A COUNTER. A monotonically increasing counter's average over a window is a number with no physical meaning, dominated by the counter's absolute magnitude rather than the traffic rate -- yet it plots as a smooth, entirely plausible line. Counter buckets here structurally carry no raw-value average, min or max field at all, only rated deltas; a test asserts the exact key set to keep this true.

COUNTER RESETS. A process restarts and its counter returns to zero. A naive current-minus-previous is then hugely negative, and code that clamps negatives to zero silently discards the entire interval's real traffic. This library detects the reset and estimates the true increase as previous-plus-current, and states plainly what it still cannot know: a reset that lands above the previously observed value is undetectable from two samples alone.

GAPS RENDERED AS ZERO. No data is not zero. A scrape that failed plots as a drop to the floor, indistinguishable from a total outage -- or a real drop to zero gets waved away as 'must be a gap.' Buckets here are a discriminated union: a gap bucket carries no numeric fields at all, structurally distinct from a bucket whose samples were genuinely zero.

VERIFIED: 61 tests, re-measured by running the suite, 9 deliberate defects applied to the real source, 7 caught and 2 proved to change no observable behaviour (one guard is unreachable; the other is an optimization, not a rule) — both proofs ship in mutations.json after closing two gaps a first pass missed: an all-negative-value bucket where max stayed frozen at zero, a value never actually observed, and a raw sample interval spanning a bucket boundary that credited its full increase to every bucket it touched instead of splitting it by time overlap, a real double-counting bug.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function bucketStartFor(t: number, bucketMs: number): number;
  export function resolveRange(samples: readonly Sample[], options: DownsampleOptions): ResolvedRange;
  export function rateSegments(samples: readonly Sample[]): RateSegment[];
  export function downsampleCounter( samples: readonly Sample[], options: DownsampleOptions ): CounterBucketResult[];
  export function downsample( seriesType: "GAUGE", samples: readonly Sample[], options: DownsampleOptions ): GaugeBucketResult[];
  export function downsample( seriesType: "COUNTER", samples: readonly Sample[], options: DownsampleOptions ): CounterBucketResult[];
  export function downsample( seriesType: SeriesType, samples: readonly Sample[], options: DownsampleOptions ): GaugeBucketResult[] | CounterBucketResult[];
  export function downsampleGauge( samples: readonly Sample[], options: DownsampleOptions ): GaugeBucketResult[];
  export function lttb(points: readonly Sample[], threshold: number): Sample[];
  export function validateSamples(samples: readonly Sample[]): void;
  export function validateBucketMs(bucketMs: number): void;
  export function validateBucketCount(count: number): void;

  export type SeriesType = "GAUGE" | "COUNTER";
  export type GaugeBucketResult = GaugeDataBucket | GapBucket;
  export type CounterBucketResult = CounterDataBucket | GapBucket;