xxhash-addon

Yet another xxhash addon for Node.js which can be x50 times faster than crypto MD5

IMPORTANT: xxhash-addon v2 is finally here. This is almost a re-work of this project with heavy focus on performance and consistency. FAQ has some very good info that you may not want to miss.

Overview

xxhash-addon is a native addon for Node.js (>=8.6.0) written using N-API. It 'thinly' wraps xxhash v0.8.3, which has support for a new algorithm XXH3 that has been showed to outperform its predecessor.

IMPORTANT: As of v0.8.0, XXH3 and XXH128 are now considered stable. Rush to the upstream CHANGELOG for the formal announcement! xxhash-addon v1.4.0 is the first iteration packed with stable XXH3 and XXH128.

Why v2?

• Greatly improved performance backed by benchmarks (see charts below.)
• Better consistency and smaller code size thanks to pure C-style wrapping.

CI Benchmarks

Benchmarks run automatically on every push to master and every pull request across multiple platforms, compilers, architectures, and Node.js versions. Results are published as a GitHub Actions Job Summary — click any workflow run to see the consolidated throughput table.

Coverage: Linux x86_64/ARM64 (GCC + Clang), macOS ARM64 (Clang), Windows x86_64/ARM64 (MSVC), Node.js 22 + 24.

The benchmark measures both streaming (update() + digest()) and one-shot (hash()) throughput across buffer sizes from 1 KB to 16 MB. Iterations are auto-tuned to ~1 s per measurement, with 2 warmup runs and 5 measured runs, reporting median throughput in GB/s. The headline table below shows streaming throughput at 64 KB chunks — the default fs.createReadStream buffer size.

To run locally:

npm run benchmark

To save results as JSON:

BENCHMARK_OUTPUT=results.json node benchmark.js

Benchmark Results

Streaming throughput in GB/s at 64 KB chunks (higher is better). Median of 5 runs.

Platform	Compiler	Node	XXH64	XXH3	XXH128	MD5	SHA1
macOS arm64	Apple Clang 17.0.0	v24	12.55	33.52	32.23	0.65	2.14
macOS x64	Apple Clang 17.0.0	v24	14.53	35.67	36.73	0.83	1.09
Linux arm64	GCC 13.3.0	v24	20.97	19.88	19.85	0.70	1.94
Linux arm64	Clang 18.1.3	v24	19.01	20.08	20.06	0.70	1.94
Linux x64	GCC 13.3.0	v24	11.61	40.58	40.57	0.66	1.58
Linux x64	Clang 18.1.3	v24	11.60	41.72	41.40	0.66	1.58
Windows arm64	MSVC 17.14.36811.4	v24	20.59	9.94	9.93	0.66	0.74
Windows x64	MSVC 17.14.37012.4	v24	11.42	38.47	38.26	0.66	1.57

Generated at 2026-03-01T16:53:33.255Z with xxHash v0.8.3

Features

• xxhash-addon exposes xxhash's API in a friendly way for downstream consumption (see the Example of Usage section).
• Covering all 4 variants of the algorithm: XXH32, XXH64, XXH3 64-bit, XXH3 128-bit.
• Supporting XXH3 secret.
• Consistently producing canonical (big-endian) form of hash values as per xxhash's recommendation.
• The addon is extensively sanity-checked againts xxhash's sanity test suite to ensure that generated hashes are correct and align with xxhsum's (xxhsum is the official utility of xxhash). Check the file xxhash-addon.test.js to see how xxhash-addon is being tested.
• Being seriously checked against memory safety and UB issues with ASan and UBSan. See the CI for how this is done.
• Benchmarks are publicly available.
• Minimal dependency: one tiny runtime dependency (node-gyp-build, 3 KB, zero transitive dependencies).
• TypeScript support. xxhash-addon is strongly recommended to be used with TypeScript. Definitely check FAQ before using the addon.

Installation

npm install xxhash-addon

Prebuilt binaries are included for the following platforms -- no C compiler required:

Platform	Architecture
Linux (glibc)	x64, arm64
Linux (musl/Alpine)	x64, arm64
macOS	x64 (Intel), arm64 (Apple Silicon)
Windows	x64, arm64

For other platforms, the addon falls back to compiling from source via node-gyp, which requires a C toolchain:

On a Windows machine

npm install --global --production windows-build-tools

On a Debian/Ubuntu machine

sudo apt-get update && sudo apt-get install python g++ make

On a RHEL/CentOS machine

If you are on RHEL 6 or 7, you would need to install GCC/G++ >= 6.3 via devtoolset- for the module to compile. See SCL.

On a Mac

Install Xcode command line tools

Example

const { XXHash32, XXHash3 } = require('xxhash-addon');

// Hash a string using the static one-shot method.
const salute = 'hello there';
const buf_salute = Buffer.from(salute);
console.log(XXHash32.hash(buf_salute).toString('hex'));

// Digest a byte-stream (hash a buffer piece by piece).
const hasher32 = new XXHash32(Buffer.from([0, 0, 0, 0]));
hasher32.update(buf_salute.slice(0, 3));
console.log(hasher32.digest().toString('hex'));
hasher32.update(buf_salute.slice(3));
console.log(hasher32.digest().toString('hex'));

// Reset the hasher for another hashing.
hasher32.reset();

// Using secret for XXH3
// Same constructor call syntax, but hasher switches to secret mode whenever
// it gets a buffer of at least 136 bytes.
const hasher3 = new XXHash3(require('fs').readFileSync('package-lock.json'));

FAQ

• Why TypeScript?

• Short answer: for much better performance and security.
• Long answer: Dynamic type check is so expensive that it can hurt performance. In the world with no TypeScript, the streaming update() method had to check whether the buffer passed to it was an actual Node's Buffer. Failing to detect Buffer type might cause v8 to CHECK and crashed Node process. Such dynamic type check could degrade performance of xxhash-addon by 10-15% per my onw benchmark on a low-end Intel Mac mini (on Apple Silicon, the difference is neglectable though.)

So how does TypeScript (TS) help? Static type check.

There is still a theoretical catch. TS' type system is structural so in a corner case where you have a class that is structurally like Buffer and you pass an instance of that class to update(). This is an extreme case that should never happen in practice. Nevertheless, there are official techniques to 'force' nominal typing. Check https://www.typescriptlang.org/play#example/nominal-typing for an in-depth.

If you don't use TS then you probably want to enable run-time type check of xxhash-addon. Uncomment the line # "defines": [ "ENABLE_RUNTIME_TYPE_CHECK" ] in binding.gyp and re-compile the addon. Use this at your own risk.

Development

This is for people who are interested in creating a PR.

How to clone?

git clone https://github.com/ktrongnhan/xxhash-addon
git submodule update --init
npm run debug:build
npm run benchmark
npm test

Note: debug:build compiles and links with Address Sanitizer (-fsanitze=address). npm test may not work out-of-the-box on macOS.

How to debug asan build?

You may have troubles running tests with asan build. Here is my snippet to get it running under lldb on macOS.

$ lldb node -- --test xxhash-addon.test.js
(lldb) env DYLD_INSERT_LIBRARIES=/Library/Developer/CommandLineTools/usr/lib/clang/13.1.6/lib/darwin/libclang_rt.asan_osx_dynamic.dylib
(lldb) env ASAN_OPTIONS=detect_leaks=1
(lldb) breakpoint set -f src/addon.c -l 100
(lldb) run
(lldb) next

OR

DYLD_INSERT_LIBRARIES=$(clang --print-file-name=libclang_rt.asan_osx_dynamic.dylib) ASAN_OPTIONS=detect_leaks=1 node --test xxhash-addon.test.js

Key takeaways:

• If you see an error saying ASan Interceptor is loaded too late, set the env DYLD_INSERT_LIBRARIES. You need to use absolute path to your Node.js binary as well. Curious why? An interesting article.
• ASan doesn't detect mem-leak on macOS by default. You may want to turn this on with the env ASAN_OPTIONS=detect_leaks=1.

If you are debugging on Linux with GCC as your default compiler, here is a helpful oneliner:

$ LD_PRELOAD=$(gcc -print-file-name=libasan.so) LSAN_OPTIONS=suppressions=suppr.lsan DEBUG=1 node --test xxhash-addon.test.js

How to upgrade xxHash?

Everything should be set up already. Just pull from the release branch of xxHash.

git submodule update --remote
git status
git add xxHash
git commit -m "Bump xxHash to..."
git push origin your_name/upgrade_deps

API reference

Streaming Interface

export interface XXHash {
  update(data: Buffer): void;
  digest(): Buffer;
  reset(): void;
}

XXHash32

export class XXHash32 implements XXHash {
  constructor(seed: Buffer); // Buffer must be 4-byte long.
  update(data: Buffer): void;
  digest(): Buffer;
  reset(): void;
  static hash(data: Buffer): Buffer; // One-shot with default seed (zero).
}

XXHash64

export class XXHash64 implements XXHash {
  constructor(seed: Buffer); // Buffer must be 4- or 8-byte long.
  update(data: Buffer): void;
  digest(): Buffer;
  reset(): void;
  static hash(data: Buffer): Buffer; // One-shot with default seed (zero).
}

XXHash3

export class XXHash3 implements XXHash {
  constructor(seed_or_secret: Buffer); // For using seed: Buffer must be 4- or 8-byte long; for using secret: must be at least 136-byte long.
  update(data: Buffer): void;
  digest(): Buffer;
  reset(): void;
  static hash(data: Buffer): Buffer; // One-shot with default seed (zero).
}

XXHash128

export class XXHash128 implements XXHash {
  constructor(seed_or_secret: Buffer); // For using seed: Buffer must be 4- or 8-byte long; for using secret: must be at least 136-byte long.
  update(data: Buffer): void;
  digest(): Buffer;
  reset(): void;
  static hash(data: Buffer): Buffer; // One-shot with default seed (zero).
}

Licence

The project is licensed under BSD-2-Clause.