tdigest

What the library provides

tdigest is a JavaScript implementation of the T-Digest, a data structure and algorithm for building an approximate distribution of a stream of real numbers. The readme notes that the algorithm makes no strict guarantees but behaves well enough in practice that implementations have been included in Apache Mahout and Elasticsearch for computing summaries and approximate order statistics. This JavaScript version is based on a reading of the original paper, with some boundary and performance tweaks rather than a direct copy of the reference Java code. The package is meant to be used both in Node.js and in the browser. In Node, a developer installs it with npm install tdigest and then requires the TDigest constructor. In the browser, a grunt dist task produces a self contained UMD wrapped file under dist/tdigest.js that can be embedded with a script tag. The library depends on bintrees for its internal tree storage. A typical session creates a digest, pushes a large array of samples into it, compresses the result, and then reads percentiles such as the median. The readme shows pushing one hundred thousand random values, compressing, and printing the 0.5 percentile. A separate browser example pushes one million values and writes the summary to the document. The implementation targets engineers who need quantile estimates without holding every observation in memory.

Discrete mode and API history

The digest starts in an exact histogram mode for a reasonable number of distinct values and then automatically switches to T-Digest mode as sample size grows and the data looks continuous. Version 0.1.0 introduced a discrete mode: when a TDigest is created with delta set to false, the sample distribution is treated as discrete, so differing samples are never merged and need not even be numeric, and percentiles are reported as the nearest exact data value instead of an interpolated one. Around that release the project renamed quantile to prank for percentile rank, and made percentile and prank accept either arrays or singleton arguments. Earlier releases went through an API overhaul. Version 0.0.5 renamed asArray to toArray, redigest to compress, and digest to push, and stopped triggering compression when an array was pushed. Version 0.0.7 added a grunt dist task to create the UMD wrapped build for client side use. Smaller point releases fixed behavior at the boundaries. Version 0.1.1 made percentile on an empty digest return undefined or an array of undefined instead of NaN, upgraded bintrees to pick up a bugfix, and corrected discrete percentile and prank boundary conditions to match the standard definition. Version 0.1.2 updated the bintree dependency to 1.0.2 to capture its licensing declaration. Version 0.1.3 carried no code changes and only fixed documentation, switching the npm version and download badges to load over https and removing a dead Travis CI badge. The project is small and stable.

Usage and positioning

Compared with pulling in a full statistics library, tdigest aims to stay narrow and focused on one job. The readme points readers to a blog post by Davidson-Pilon for an overview of T-Digest behavior in Python, and to the original paper and the reference Java implementation for deeper detail. The JavaScript port is explicitly based on the paper rather than the Java source, which keeps it lightweight but means users should consult the paper for the underlying theory. The package ships an example.js and an example.html in the repository so newcomers can run a quick demonstration outside of a larger application. For continuous distributions the digest compresses neighboring samples into centroids whose sizes grow near the extremes, which is what gives good accuracy at the tails where quantile estimates are often hardest. For discrete data the histogram mode preserves exact values. The maintainer's changelog shows a steady cadence of small fixes rather than churn, which suits a utility that other projects may embed. The library reports 72 stars and 12 forks on GitHub. It remains a practical choice when a Node service or a browser page must report p50, p95, or p99 latencies from a firehose of numbers without storing them all.

Editorial conclusion

The code is published under the MIT license and its most recent update was on 2026-08-26.