net.latency-summary

export function summariseLatency(samplesUs: readonly (number | null)[]): LatencySummary

/** What a run of probes says about a link, as ping prints it. */
export interface LatencySummary {
  readonly sent: number;
  readonly received: number;
  readonly lost: number;
  /** lost / sent, rounded half-up; 10000 = every probe lost */
  readonly lossBasisPoints: number;
  /** null when nothing was received */
  readonly minUs: number | null;
  /** mean, rounded half-up to a whole microsecond */
  readonly avgUs: number | null;
  readonly maxUs: number | null;
  /** nearest-rank 95th percentile, a sample that was really seen */
  readonly p95Us: number | null;
  /** mean absolute difference of consecutive received samples, half-up; null under two */
  readonly jitterUs: number | null;
}

import { summariseLatency } from "#fune/net.latency-summary@^1";

import { roundDiv } from "./math_round_div.ts";  ← from math.round-div ^1.0.0 · built alongside by fune
import { percentile } from "./stats_percentile.ts";  ← from stats.percentile ^2.0.0 · built alongside by fune
import { type LatencySummary } from "./net_latency_summary_types.ts";

/**
 * Summarise a run of probes the way ping does, in whole microseconds.
 *
 * Integer microseconds rather than float milliseconds, so every language
 * gives the same answer and a vector can compare exactly. A lost probe counts
 * towards loss and is skipped (not a break) when measuring jitter.
 */
export function summariseLatency(samplesUs: readonly (number | null)[]): LatencySummary {
  if (!Array.isArray(samplesUs)) throw new TypeError("samplesUs must be a list");
  if (samplesUs.length === 0) throw new RangeError("samplesUs must not be empty");
  const got: number[] = [];
  for (const s of samplesUs) {
    if (s === null || s === undefined) continue;
    if (typeof s !== "number" || !Number.isInteger(s)) {
      throw new TypeError(`each sample must be a whole number of microseconds or null, received ${s}`);
    }
    if (s < 0) throw new RangeError(`samples must not be negative, received ${s}`);
    got.push(s);
  }
  const sent = samplesUs.length;
  const received = got.length;
  const lost = sent - received;
  const lossBasisPoints = roundDiv(lost * 10000, sent, "half-up");
  if (received === 0) {
    return { sent, received, lost, lossBasisPoints, minUs: null, avgUs: null, maxUs: null, p95Us: null, jitterUs: null };
  }
  let min = got[0];
  let max = got[0];
  let sum = 0;
  for (const v of got) {
    if (v < min) min = v;
    if (v > max) max = v;
    sum += v;
  }
  let jitterUs: number | null = null;
  if (received >= 2) {
    let diffs = 0;
    for (let i = 1; i < received; i++) diffs += Math.abs(got[i] - got[i - 1]);
    jitterUs = roundDiv(diffs, received - 1, "half-up");
  }
  // Nearest-rank returns a sample that was really seen, so it is a whole number.
  const p95Us = percentile(got, 95, "nearest-rank", 0);
  return {
    sent,
    received,
    lost,
    lossBasisPoints,
    minUs: min,
    avgUs: roundDiv(sum, received, "half-up"),
    maxUs: max,
    p95Us,
    jitterUs,
  };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 2 dependencies, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add net.latency-summary

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./net.latency-summary-1.0.0-typescript.fune, or fetch it from a terminal with fune pull net.latency-summary@1.0.0:typescript.

The whole function, every language, is one file too: net.latency-summary-1.0.0.fune, 16,995 bytes, sha256 c5e4c99d628f4ef623dfefae12ed3b64b1ec4e9e410a83d09c0d2247bd5d9cb0. It installs into a project of any language.

// fune: before net.latency-summary

// fune: after net.latency-summary

// fune: replace math.round-div in net.latency-summary
// fune: replace stats.percentile in net.latency-summary

// fune: step net.latency-summary after <n|label>

More from the author

- **Input is whole microseconds, `null` for a lost probe**, in the order the probes were sent. Integers keep all three languages identical and let the vectors compare exactly; a caller timing with a monotonic clock converts once (`elapsed.as_micros()`). - **Loss** is `lost / sent` in basis points, rounded half-up (`math.round-div`): 1 of 3 lost is 3333, 2 of 3 is 6667, all lost is 10000. - **avg** is the mean of the received samples, rounded half-up to a whole microsecond. - **p95** is the nearest-rank 95th percentile (`stats.percentile`, `nearest-rank`): the smallest sample with at least 95% of samples at or below it. It is always a sample that was really seen; for 20 samples it is the 19th smallest, not the maximum. - **jitter** is the mean absolute difference between consecutive *received* samples, in send order, rounded half-up. A lost probe is skipped, not a break, so `[1000, null, 3000, 2000]` compares 1000 with 3000 and 3000 with 2000. This is the simple "mean deviation of successive round trips", not RFC 3550's exponentially smoothed interarrival jitter (which needs one-way transit times and weights recent packets); it is `null` with fewer than two replies. - With no replies, min/avg/max/p95/jitter are all `null` and loss is 10000.

## Errors

An empty list (`samplesUs must not be empty`), a negative sample (`samples must not be negative`), and a sample that is not a whole number or null (`each sample must be a whole number of microseconds or null`).

Rust callers building on this can use `latency_summary_to_value` and `latency_summary_from_value`.

Files