xxHash JavaScript Implementation

Common errors

• ReferenceError: XXH is not defined (when using 'import XXH from \'xxhashjs\'')

  cause Attempting to use ES module import syntax for a CommonJS-only package in Node.js.
  fix Change your import statement to `const XXH = require('xxhashjs');` for Node.js.

• TypeError: H.update is not a function (when H = XXH.h32('data', seed))

  cause You are trying to call `.update()` on a result from a one-step hash calculation. The `update()` method is available only on a hasher instance created for multi-step operations.
  fix To use `.update()`, first instantiate a hasher: `const H = XXH.h32(seed);` (without data), then call `H.update(data);`.

• TypeError: Cannot read property 'toString' of undefined (after H.update('data'))

  cause After calling `update()`, you need to call `digest()` on the hasher instance to finalize the calculation and get the hash value before attempting to convert it.
  fix Ensure you call `.digest()`: `const hashResult = H.digest(); console.log(hashResult.toString(16));`

• ReferenceError: _XXH_ is not defined (in browser, after <script src=...></script>)

  cause The script file for xxhashjs was either not loaded correctly, the path was wrong, or it was loaded after the code trying to access `_XXH_`.
  fix Verify the script path in your HTML `<script>` tag is correct and that the script loads before any JavaScript code that attempts to use the `_XXH_` global variable.

Warnings

• gotcha Performance of xxhashjs is inherently slower than native C/C++ xxHash implementations due to JavaScript's limitations in handling unsigned 32-bit integers and overall execution speed. Do not expect native performance levels.
  Fix: Be aware of performance characteristics for high-throughput applications. Consider native add-ons if absolute maximum speed is critical.
• gotcha The package currently only supports CommonJS modules in Node.js environments. There is no official ES module (`import`) support, which can lead to errors in modern JavaScript projects configured for ESM.
  Fix: Ensure you use `const XXH = require('xxhashjs');` for Node.js. If you need to use it in an ESM context, consider using a CommonJS wrapper or a bundler that handles CJS modules.
• gotcha In browser environments, `xxhashjs` exposes a global variable `_XXH_`. This can potentially conflict with other scripts or libraries that also define a global variable with the same name, leading to unexpected behavior.
  Fix: If conflicts arise, load `xxhashjs` in an isolated scope (e.g., an IIFE if possible) or consider manually mapping the global `_XXH_` to another variable immediately after loading.
• gotcha The project appears to be in a maintenance-only mode with infrequent updates. The last version (0.2.2) was released some time ago, and there may not be active development for new features or prompt bug fixes.
  Fix: Evaluate the project's suitability for long-term critical applications. For actively maintained alternatives, explore other hashing libraries or actively developed xxHash ports.

Install

• npm install xxhashjs npm
• yarn add xxhashjs yarn
• pnpm add xxhashjs pnpm

Imports

• XXH
  wrong:

  import XXH from 'xxhashjs';

  correct:

  const XXH = require('xxhashjs');

  This package is CommonJS-only for Node.js environments. Attempting to use ES module import syntax will fail.
• XXH.h32
  wrong:

  import { h32 } from 'xxhashjs';

  correct:

  const XXH = require('xxhashjs');
  const hash32 = XXH.h32('data', 0);

  `h32` is a method on the default CommonJS export `XXH`, not a named export. It can be used in a single step or to instantiate a hasher.
• _XXH_
  wrong:

  const _XXH_ = require('xxhashjs');

  correct:

  // Accessible globally after <script src="/your/path/to/xxhash.js"></script>

  In browser environments, the library exposes itself as a global variable `_XXH_` when loaded via a script tag. No explicit import or require is needed.

Quickstart

Demonstrates both 32-bit and 64-bit xxHash calculations, including multi-step hashing with object reuse, suitable for Node.js CommonJS or browser global usage.

// For Node.js
const XXH = require('xxhashjs');

// For browser, XXH is available as _XXH_
// const XXH = _XXH_;

// Instantiate a 32-bit hasher with a seed in multiple steps
const H32 = XXH.h32(0xABCD); // seed = 0xABCD

// Update with data (can be string, ArrayBuffer, or Buffer)
H32.update('abcd');

// Digest and get the hash value as a hexadecimal string
const hashValue32 = H32.digest().toString(16);

console.log('32-bit hash:', hashValue32); // Expected: cda8fae4

// The hasher object can be reused with a new or the same seed
H32.init(0x1234).update('some new data example').digest();
console.log('32-bit hash (reused):', H32.digest().toString(16));

// Example of 64-bit hash in one step
const h64Result = XXH.h64('another string example', 0x12345678).toString(16);
console.log('64-bit hash:', h64Result);