{"id":11026,"library":"hdr-histogram-js","title":"HdrHistogram.js","description":"HdrHistogram.js is a TypeScript port of the HdrHistogram library, designed for high-fidelity recording and analysis of latency and other value distributions in both Node.js and web browser environments. The library is currently stable at version 3.0.1, with a history of regular updates including significant architectural changes. A key differentiator since version 2 is the introduction of an optional WebAssembly (WASM) implementation, leveraging AssemblyScript to provide substantial performance gains for recording and processing histograms, though this is not enabled by default. It supports core HdrHistogram features such as regular and coordinated omission-corrected latency recording, resizable and memory-optimized 'packed' histograms, and the ability to add, subtract, encode, and decode compressed histograms. It also includes client-side data visualization tools for browser-based analysis. Release cadence appears to be driven by feature enhancements and performance optimizations, with major versions often introducing substantial improvements.","status":"active","version":"3.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/HdrHistogram/HdrHistogramJS","tags":["javascript","hdr-histogram","hdr-histogram-js","percentiles","monitoring","latency","performance","typescript"],"install":[{"cmd":"npm install hdr-histogram-js","lang":"bash","label":"npm"},{"cmd":"yarn add hdr-histogram-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add hdr-histogram-js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is the primary namespace import pattern shown in documentation for ES6+ environments.","wrong":"import hdr from 'hdr-histogram-js'","symbol":"hdr","correct":"import * as hdr from 'hdr-histogram-js'"},{"note":"The `build` function is a named export for creating histogram instances. Avoid default import syntax.","wrong":"import build from 'hdr-histogram-js'","symbol":"build","correct":"import { build } from 'hdr-histogram-js'"},{"note":"The `Histogram` class is a named export, primarily used for type annotation or direct class instantiation if not using the `build` factory.","wrong":"import Histogram from 'hdr-histogram-js'","symbol":"Histogram","correct":"import { Histogram } from 'hdr-histogram-js'"},{"note":"While the library supports CommonJS, modern Node.js projects (>=14) and bundlers typically favor ES Modules. Use direct `require` without `.default` for namespace import.","wrong":"const hdr = require('hdr-histogram-js').default","symbol":"CommonJS require","correct":"const hdr = require('hdr-histogram-js')"}],"quickstart":{"code":"import { build, Histogram } from 'hdr-histogram-js';\n\n// Build a default histogram with auto-resizing, tracking values from 1 to 2, and 3 significant digits.\n// WebAssembly is not enabled by default for maximum compatibility.\nconst histogram: Histogram = build({\n  lowestDiscernibleValue: 1,\n  highestTrackableValue: 10000000000, // 10 billion\n  numberOfSignificantValueDigits: 3,\n  useWebAssembly: false // Explicitly set to false, true for performance if available\n});\n\n// Record some values representing latencies in microseconds\nhistogram.recordValue(1000);\nhistogram.recordValue(5000);\nhistogram.recordValue(100);\nfor (let i = 0; i < 1000; i++) {\n  histogram.recordValue(Math.floor(Math.random() * 9000) + 1000);\n}\nhistogram.recordValue(9999);\n\nconsole.log(`Total count: ${histogram.totalCount}`);\nconsole.log(`90th percentile: ${histogram.getValueAtPercentile(90)} µs`);\nconsole.log(`99th percentile: ${histogram.getValueAtPercentile(99)} µs`);\nconsole.log(`Max value: ${histogram.maxValue} µs`);\n\n// Example of coordinated omission correction\nconst histogramWithCoordinatedOmissions = build({\n  lowestDiscernibleValue: 1,\n  highestTrackableValue: 10000000000,\n  numberOfSignificantValueDigits: 3\n});\n\nhistogramWithCoordinatedOmissions.recordValueWithExpectedInterval(100, 10); // Record a value of 100, expecting 10ms interval\nconsole.log(`\nHistogram with coordinated omissions (total count: ${histogramWithCoordinatedOmissions.totalCount}):`);\nconsole.log(`90th percentile (corrected): ${histogramWithCoordinatedOmissions.getValueAtPercentile(90)} µs`);","lang":"typescript","description":"Demonstrates how to build a histogram, record values, and retrieve basic percentile metrics, including an example of coordinated omission correction."},"warnings":[{"fix":"Review the WebAssembly section in the documentation (since hdrhistogramjs v2) to understand performance implications and how to opt-in to WASM. The `useWebAssembly` option on `build()` is `false` by default.","message":"Version 2.0.0 introduced significant architectural changes and the optional WebAssembly (WASM) implementation. While not strictly 'breaking' for API compatibility, performance characteristics and default behaviors changed.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"When building a histogram, set `useWebAssembly: true` in the options object passed to `hdr.build()`. Ensure your execution environment supports WebAssembly.","message":"The WebAssembly implementation, introduced in v2.0.0, offers significant performance benefits but is not enabled by default. Users must explicitly opt-in if they wish to use it.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Carefully evaluate your use case. For high-performance, higher-throughput scenarios, avoid `bitBucketSize: 'packed'`. For minimal memory usage with infrequent updates, 'packed' may be suitable. The default `bitBucketSize` is usually a good balance.","message":"Choosing the correct `bitBucketSize` or using the `'packed'` option influences both memory footprint and performance. 'packed' histograms use less memory but are significantly slower.","severity":"gotcha","affected_versions":">=1.2.0"},{"fix":"Ensure your Node.js environment is version 14 or higher to guarantee compatibility and access to modern JavaScript features and WebAssembly support.","message":"The library explicitly lists a Node.js engine requirement of `>=14`.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Convert `require('hdr-histogram-js')` to `import * as hdr from 'hdr-histogram-js'` or `import { build } from 'hdr-histogram-js'`.","cause":"Attempting to use CommonJS `require()` syntax in an ES Module context (e.g., a file with `\"type\": \"module\"` in `package.json` or `.mjs` extension).","error":"ReferenceError: require is not defined"},{"fix":"Use named import syntax: `import { build } from 'hdr-histogram-js'`.","cause":"Attempting to import the `build` function as a default import (e.g., `import build from 'hdr-histogram-js'`) when it is a named export.","error":"TypeError: build is not a function"},{"fix":"Either remove `useWebAssembly: true` to fall back to the TypeScript implementation, or ensure the execution environment fully supports WebAssembly (e.g., update browser, use a compatible Node.js version).","cause":"The `useWebAssembly: true` option was provided when building a histogram, but the current runtime environment (e.g., an older browser, specific Node.js configuration) does not support WebAssembly or has it disabled.","error":"WebAssembly is not available in this environment"}],"ecosystem":"npm"}