imurmurhash

What is imurmurhash?

The imurmurhash npm package is a JavaScript implementation of the MurmurHash3 hashing algorithm. It's designed for efficiently generating 32-bit hashes from strings. This package is useful for tasks such as generating hash keys for data caching, creating compact unique identifiers for objects, and implementing hash-based data structures like bloom filters.

What are imurmurhash's main functionalities?

Hash Initialization and Update

This feature demonstrates initializing a new hash instance and updating it with a string. The `result` method is then used to get the hash value.

const MurmurHash3 = require('imurmurhash');
const hash = new MurmurHash3();
hash.hash('Hello, world!');
console.log(hash.result());

Incremental Hash Updates

This feature shows how to incrementally update the hash with multiple pieces of data. This is useful for hashing data streams or large datasets in chunks.

const MurmurHash3 = require('imurmurhash');
const hash = new MurmurHash3();
hash.hash('Hello, ');
hash.hash('world!');
console.log(hash.result());

Resetting Hash State

This feature illustrates how to reset the hash to its initial state after computing a hash value, allowing the same hash instance to be reused for hashing new data.

const MurmurHash3 = require('imurmurhash');
const hash = new MurmurHash3().hash('Hello, world!');
console.log(hash.result());
hash.reset();
hash.hash('Another string');
console.log(hash.result());

Other packages similar to imurmurhash

murmurhash-js

This package provides a pure JavaScript implementation of the MurmurHash algorithms. It's similar to imurmurhash but offers both MurmurHash2 and MurmurHash3 algorithms. The API is slightly different, and it may not support incremental updates like imurmurhash.

murmurhash3js

murmurhash3js is another implementation of the MurmurHash3 algorithm. It differs from imurmurhash by providing both 32-bit and 128-bit hash functions. This package might be preferred when a wider range of hash sizes is needed.

hash-wasm

While not limited to MurmurHash, hash-wasm offers a wide range of hashing algorithms implemented in WebAssembly for high performance. It includes MurmurHash3 among its supported algorithms. This package is suitable for applications requiring high-speed hashing or support for multiple hash algorithms.

README

iMurmurHash.js

An incremental implementation of the MurmurHash3 (32-bit) hashing algorithm for JavaScript based on Gary Court's implementation with kazuyukitanimura's modifications.

This version works significantly faster than the non-incremental version if you need to hash many small strings into a single hash, since string concatenation (to build the single string to pass the non-incremental version) is fairly costly. In one case tested, using the incremental version was about 50% faster than concatenating 5-10 strings and then hashing.

Installation

To use iMurmurHash in the browser, download the latest version and include it as a script on your site.

<script type="text/javascript" src="/scripts/imurmurhash.min.js"></script>
<script>
// Your code here, access iMurmurHash using the global object MurmurHash3
</script>

To use iMurmurHash in Node.js, install the module using NPM:

npm install imurmurhash

Then simply include it in your scripts:

MurmurHash3 = require('imurmurhash');

Quick Example

// Create the initial hash
var hashState = MurmurHash3('string');

// Incrementally add text
hashState.hash('more strings');
hashState.hash('even more strings');

// All calls can be chained if desired
hashState.hash('and').hash('some').hash('more');

// Get a result
hashState.result();
// returns 0xe4ccfe6b

Functions

MurmurHash3 ([string], [seed])

Get a hash state object, optionally initialized with the given string and seed. Seed must be a positive integer if provided. Calling this function without the new keyword will return a cached state object that has been reset. This is safe to use as long as the object is only used from a single thread and no other hashes are created while operating on this one. If this constraint cannot be met, you can use new to create a new state object. For example:

// Use the cached object, calling the function again will return the same
// object (but reset, so the current state would be lost)
hashState = MurmurHash3();
...

// Create a new object that can be safely used however you wish. Calling the
// function again will simply return a new state object, and no state loss
// will occur, at the cost of creating more objects.
hashState = new MurmurHash3();

Both methods can be mixed however you like if you have different use cases.

MurmurHash3.prototype.hash (string)

Incrementally add string to the hash. This can be called as many times as you want for the hash state object, including after a call to result(). Returns this so calls can be chained.

MurmurHash3.prototype.result ()

Get the result of the hash as a 32-bit positive integer. This performs the tail and finalizer portions of the algorithm, but does not store the result in the state object. This means that it is perfectly safe to get results and then continue adding strings via hash.

// Do the whole string at once
MurmurHash3('this is a test string').result();
// 0x70529328

// Do part of the string, get a result, then the other part
var m = MurmurHash3('this is a');
m.result();
// 0xbfc4f834
m.hash(' test string').result();
// 0x70529328 (same as above)

MurmurHash3.prototype.reset ([seed])

Reset the state object for reuse, optionally using the given seed (defaults to 0 like the constructor). Returns this so calls can be chained.

License (MIT)

Copyright (c) 2013 Gary Court, Jens Taylor

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.