@fimbul-works/hash

An ultra-lightweight, ESM-first mathematical toolkit for high-performance hashing, bijective integer mixing, coordinate pairing, and stream serialization.

Key Differentiators

• Strict Unix Philosophy: Deconstructs hashing into raw, composable building blocks. Decouples byte serialization (getBytes), multi-dimensional mapping (cantorPair, szudzikPair), scrambling mixers (fastMix, wangHash), and floating-point normalizers (intToFloat, int64ToDouble).
• Ultra-Lightweight & Tree-Shakeable: Modularly bundled so that you only pay for what you import. Individual 32-bit algorithms like fnv1a, crc32, and wangHash compile to under 1KB minified, with the entire suite weighing just 4.25KB when compressed with Brotli.
• Zero Dependencies & High Portability: Implemented in clean, modern TypeScript utilizing native bitwise operators, Math.imul, and DataViews, running flawlessly in Node.js, browsers, Bun, and edge environments.
• Bijective (Invertible) Mixers: Includes fully reversible 32-bit and 64-bit integer mixers (fastMix & fastMix64), enabling diagnostic un-mixing and validation of procedural generation pipeline chains.

Installation

pnpm add @fimbul-works/hash
# or
npm install @fimbul-works/hash
# or
yarn add @fimbul-works/hash

Features

1. Integer Hashing & Scrambling Mixers (Single Pass)

Ultra-fast bitwise scrambling for integer keys (entity IDs, seeds, grid offsets):

• 32-bit Mixers: fastMix, pcgMix, wangHash, splitMix, squirrel3, squirrel5, mulberry, jenkinsMix.
• 64-bit Mixers: fastMix64, splitMix64, wangHash64.

2. Stream & Buffer Hashing (Multi-Byte)

Highly optimized multi-byte block and stream hashing for strings and raw byte arrays:

• Classic & Fast: crc32, crc64, fnv1a, fnv1a64, jenkinsHash, fxHash, fastHash, fastMixHash, jenkinsMixHash.
• Modern & Robust: xxHash, xxHash64, murmur3, murmur3Hash128, sipHash13, wyHash.

3. Coordinate Pairing Functions

Bijectively map multidimensional coordinates (2D and 3D grids) into a single unique integer, and back:

• Cantor Pairing: cantorPair(), reverseCantorPair().
• Szudzik Pairing: szudzikPair(), reverseSzudzikPair(), szudzikPair3D(), reverseSzudzikPair3D().

4. Normalization & Conversion Utilities

• Float Normalizers: Map 32-bit integers uniformly to [0, 1] via intToFloat() and 64-bit integers to [0, 1] via int64ToDouble().
• Float Bitwise Extraction: High-speed, non-allocating conversion of raw IEEE-754 bit patterns with floatToBits32() and floatToBits64().
• 64-to-32-bit Folding: Collapse 64-bit BigInt hashes into standard 32-bit unsigned integers preserving maximum entropy with fold64To32().
• Signed Integer Mapping: Bijectively project signed integer boundaries ($(-\infty, \infty)$) onto non-negative coordinates ($[0, \infty)$) with mapSignedInt() and unmapSignedInt().
• Byte Normalizers: Standardized, zero-overhead input serialization with getBytes().

Usage

Composing a Seeded 2D Grid Noise Generator

By combining pairing, hashing, and float conversion, you can build custom, non-allocating grid noise in a few lines of code:

import { szudzikPair, wangHash, intToFloat } from "@fimbul-works/hash";

/**
 * Get a deterministic pseudo-random float in range [0, 1] for 2D coordinates.
 * Perfect for zero-allocation procedural terrain generation loops.
 */
export function get2DGridNoise(x: number, y: number, seed: number = 0): number {
  // 1. Map 2D grid coordinates to a unique single unsigned integer
  const pairId = szudzikPair(x, y);

  // 2. Scramble the combined integer with the seed
  const scrambled = wangHash(pairId ^ seed);

  // 3. Convert the unsigned 32-bit hash to a uniform float [0, 1]
  return intToFloat(scrambled);
}

console.log(get2DGridNoise(10, 20)); // 0.38472911...

Composing a Seeded 3D Noise Generator (with Negative Coordinates)

For infinite volumetric voxel chunk terrain generation that spans positive and negative quadrants:

import { szudzikPair3D, wangHash, intToFloat, mapSignedInt } from "@fimbul-works/hash";

/**
 * Get a deterministic pseudo-random float for 3D coordinates.
 * Supports the entire signed 32-bit integer range natively.
 */
export function get3DGridNoise(x: number, y: number, z: number, seed: number = 0): number {
  // 1. Map signed integers bijectively to non-negative coordinates
  const ux = mapSignedInt(x);
  const uy = mapSignedInt(y);
  const uz = mapSignedInt(z);

  // 2. Map the 3D coordinates to a unique single non-negative integer
  const pairId = szudzikPair3D(ux, uy, uz);

  // 3. Scramble and convert to float in range [0, 1]
  return intToFloat(wangHash(pairId ^ seed));
}

console.log(get3DGridNoise(-10, -20, 30)); // 0.81239487...

Invertible Integer Mixing for Pipeline Diagnostics

Bijective integer mixers allow you to step backward through coordinate mappings, making them highly powerful for path verification and procgen seed auditing:

import { fastMix, fastUnmix, verifyFastMix } from "@fimbul-works/hash";

const originalSeed = 1337;
const parentSeed = 9999;

// Mix the seed with a hierarchical parent
const mixed = fastMix(originalSeed, parentSeed);

// Verify hierarchy without fully unmixing
const isValid = verifyFastMix(mixed, originalSeed, parentSeed); // true

// Step backward to recover the original seed
const unmixed = fastUnmix(mixed); // 1337

Performance & Bundle Size Leaderboard

Benchmarks are run on a standard runtime environment. Integer mixing algorithms are measured with numeric keys, stream hashes are benchmarked against typical string keys/UUIDs, and pairing functions map coordinate fields.

1. Integer Hashing & Mixing (Numeric Keys)

Ideal for seed expansion, grid maps, and PRNG state transitions.

| Algorithm | Gen Speed (ops/s) | Entropy | Collision Rate | Bundle Size (Minified & Brotli) | | :--- | :---: | :---: | :---: | :---: | | pcg | 141,431,293 | 13.288 | 0.00% | 102B / 100B | | wangHash | 120,451,554 | 13.288 | 0.00% | 116B / 99B | | splitMix | 74,587,507 | 13.288 | 0.00% | 150B / 109B | | squirrel5 | 57,921,521 | 13.288 | 0.00% | 233B / 156B | | mulberry | 41,400,674 | 13.262 | 1.31% | 138B / 121B | | squirrel3 | 39,262,467 | 13.288 | 0.00% | 159B / 131B | | fastMix | 202,004,491 | 13.288 | 0.00% | 328B / 174B | | jenkinsMix | 34,284,984 | 13.288 | 0.00% | 207B / 120B | | splitMix64 | 7,428,126 | 13.288 | 0.00% | 156B / 131B (BigInt) | | fastMix64 | 6,502,475 | 13.288 | 0.00% | 379B / 202B (BigInt) | | wangHash64 | 4,578,228 | 13.288 | 0.00% | 177B / 122B (BigInt) |

[!NOTE] 64-bit integer algorithms (splitMix64, fastMix64, wangHash64) use native JavaScript bigint which has significantly higher VM overhead than 32-bit double-precision numbers. For high-frequency loops, 32-bit mixers are recommended.

2. Stream & Buffer Hashing (String Keys / UUIDs)

Best for arbitrary object hashing, cache keys, and asset paths.

| Algorithm | Gen Speed (ops/s) | Entropy | Collision Rate | Bundle Size (Minified & Brotli) | | :--- | :---: | :---: | :---: | :---: | | jenkinsHash | 1,913,135 | 13.288 | 0.00% | 688B / 339B | | fnv1aHash | 1,654,602 | 13.288 | 0.00% | 704B / 349B | | fnv1a64Hash| 550,573 | 13.288 | 0.00% | 709B / 386B (BigInt) | | fxHash | 2,127,756 | 13.288 | 0.00% | 789B / 378B | | crc32 | 1,951,884 | 13.288 | 0.00% | 794B / 403B | | mash | 845,016 | 13.288 | 0.00% | 806B / 409B | | crc64 | 412,227 | 13.288 | 0.00% | 837B / 438B (BigInt) | | fastHash | 1,047,493 | 13.288 | 0.00% | 913B / 432B | | mash64 | 174,856 | 13.288 | 0.00% | 1000B / 474B (BigInt) | | fastMixHash| 1,997,700 | 13.288 | 0.00% | 1.01KB / 474B | | murmur3Hash| 1,866,905 | 13.288 | 0.00% | 1.10KB / 514B | | xxHash | 715,223 | 13.288 | 0.00% | 1.20KB / 581B | | wyHash | 367,221 | 13.288 | 0.00% | 1.23KB / 630B | | sipHash13 | 164,824 | 13.288 | 0.00% | 1.37KB / 640B | | xxHash64 | 228,030 | 13.288 | 0.00% | 1.40KB / 682B (BigInt) | | jenkinsMixHash | 1,864,775 | 13.288 | 0.00% | 1.47KB / 532B | | murmur3Hash128| 310,626 | 13.288 | 0.00% | 1.73KB / 743B |

3. Pairing Functions (2D/3D Grid Coordinates)

| Algorithm | Gen Speed (ops/s) | Collision Rate | Bundle Size (Minified & Brotli) | | :--- | :---: | :---: | :---: | | cantorPair | 49,689,871 | 0.00% | 395B / 216B | | szudzikPair| 96,845,369 | 0.00% | 511B / 249B (Includes 3D pair) |

4. Normalization, Adaptation & Bitwise Utilities

High-speed, zero-allocation adapters to bridge coordinates, floats, and hash representations.

| Utility | Description | Speed (ops/s) | Bundle Size (Minified & Brotli) | | :--- | :--- | :---: | :---: | | mapSignedInt | Projects negative coordinates to non-negative bounds | ~150,000,000+ | < 100B / < 70B | | fold64To32 | XOR-collapses 64-bit BigInt to 32-bit uint preserving entropy | ~80,000,000+ | < 100B / < 70B | | floatToBits32 | Extracts IEEE-754 bit pattern from 32-bit float | ~60,000,000+ | < 150B / < 100B |

Documentation

For full type signatures and module documentation, refer to the co-located /docs folder.

License

MIT License - See LICENSE file for details.

Built with ⚡ by FimbulWorks