@cimi/murmurhash3js

JavaScript implementation of the MurmurHash3 algorithms.

Forked from pid/murmurhash3js, the original implementation only uses the first byte from multi-byte character codes, potentially causing collisions and yielding different results from the reference implementation.

The signature of all three variants of the hash function have been changed; now
they expect bytes instead of strings. This increases the flexibility of the
library as it can now operate on e.g. strings with arbitrary encodings, numbers etc.

This requires the caller to convert from string to bytes before hashing. If the conversion from string to bytes was done internally, the library would
need to include at least a TextEncoder polyfill for utf-8 support and other
polyfills / hacks in order to have cross-browser support for other encodings.

$3

> npm install murmurhash3js

``javascript
// browser

// server
var murmurHash3 = require("murmurhash3js");
// ES6 module
import murmurHash3 from "murmurHash3js";
`

$3

Strings need to be decoded to bytes before being passed to the hash function. Passing strings without first converting to bytes will make the hash function operate directly on characters and yield incorrect results (e.g. "a" << 8 !== 97 << 8).

You can encode strings to utf8 bytes using new TextEncoder().encode(str) in modern browsers or Buffer.from(str) in node. If you need to support older browsers you can include a polyfill for TextEncoder.

The hash functions take two parameters: the input bytes and an optional seed for the hash function (defaults to 0).

`javascript
> const bytes = str => Buffer.from(str); // or new TextEncoder().encode(str)

// Return a 32bit hash as a unsigned int:
> murmurHash3.x86.hash32(bytes("I will not buy this record, it is scratched."))
2832214938

> murmurHash3.x86.hash128(bytes("I will not buy this tobacconist's, it is scratched."))
"9b5b7ba2ef3f7866889adeaf00f3f98e"
> murmurHash3.x64.hash128(bytes("I will not buy this tobacconist's, it is scratched."))
"d30654abbd8227e367d73523f0079673"

// Specify a seed (defaults to 0):
> murmurHash3.x86.hash32(bytes("My hovercraft is full of eels."), 25)
2520298415

// strings containing multi-byte character codes are handled correctly
> murmurHash3.x86.hash128(bytes("utf-8 supported 🌈"))
"796479ed1bbff85b29e39731d1967a07"
`

$3

In order to maintain compatibility with the original JS library this variant was forked from, the encoding of the output has not been changed. The 32bit version returns an unsigned int, while the x86 and x64 128 bit variants return 32 character hex strings.

Here's how you could print the output from the reference C++ implementation to get the same hex string as the JS library:

`c
int ints = (int) bytes;
for (int i = 0; i < 4; i++) {
printf("%08x", ints[i]);
}
printf("\n");
`

For x64 this is different:

`c
uint64_t ints = (uint64_t) bytes;
for (int i = 0; i < 2; i++) {
printf("%016llx", ints[i]);
}
printf("\n");
`

$3

`
> somethingCompletelyDifferent = murmurHash3.noConflict()
> murmurHash3
undefined
> somethingCompletelyDifferent.version
"3.0.1"
``

Authors
-------

- Karan Lyons
- Sascha Droste
- Alex Ciminian

Changlog
--------

CHANGLELOG.md