Generate repeatable pseudo random numbers and non-cryptographic hash numbers with Node.js and browser.
This library is not yet suitable for production! Wait until major release v1.0.0 for a stable API.
This small library contains two methods, the random number generator called Alea and a number hash generator named MurmurHash2. The Alea implementation is originally from Johannes Baagøe and ported to TypeScript from me. Johannes Baagøe site is offline but here is a Web Archive Link. You can read more about the hash function MurmurHash2 here.
Just use NPM or Yarn to install the package:
npm install --save number-generator
# or
yarn add number-generator
After that you can import it how you like, e.g.:
// ES2015
import { aleaRNGFactory, murmurHash } from 'number-generator';
// Node.js < 6.0.0
var prng = require('number-generator'); // => prng.murmurHash(...)
// Node.js >= 6.0.0
const { aleaRNGFactory, murmurHash } = require('number-generator');
For use with TypeScript take a look at this readme chapter.
Remark: There is no global namespace exposed for the browser! You have to bundle your dependencies to use the library in current browser environments.
You can use the aleaRNGFactory
method to generate (pseudo) random numbers
based an a seed (default seed is 1
). Every seed let you produce the
same result for the number getter methods.
First step is to include the library functions you want use in your application the way you want.
Now you can create a new generator with the random seed 1
or a custom
one as "unsigned integer". The number 0
is not valid and will throw
an exception as TypeError
.
// Valid:
var generator1 = aleaRNGFactory(); // Default seed: 1
var generator2 = aleaRNGFactory(4836325);
// Invalid:
var notValidGen1 = aleaRNGFactory(0);
var notValidGen2 = aleaRNGFactory(0.47);
var notValidGen3 = aleaRNGFactory(-1);
If you have an valid generator object you can use the uInt32
method to
get a random unsigned integer. Call it multiple times to get new numbers.
var generator = aleaRNGFactory(10);
generator.uInt32(); // 20916391
generator.uInt32(); // 1567221093
This should create the exact same result on your machine! You get always the same values for the same seed used.
This means if you create multiple generators with the same seed, you get the same result for the n-th call:
var generator1 = aleaRNGFactory(2);
var generator2 = aleaRNGFactory(2);
var value1 = generator1.uInt32();
var value2 = generator2.uInt32();
value1 === value2; // true
The same that works for the uInt32 method
applies to the uFloat32
method. But this time you get an unsigned float
value.
var generator = aleaRNGFactory(5);
generator.uFloat32(); // 0.0024349885061383247
generator.uFloat32(); // 0.1826920467428863
Again, this should create the exact same result on your machine!
So, also if you create multiple generators with the same seed, you get the same result for the n-th call:
var generator1 = aleaRNGFactory(4);
var generator2 = aleaRNGFactory(4);
var value1 = generator1.uFloat32();
var value2 = generator2.uFloat32();
value1 === value2; // true
You can change the seed used by the generator object with the setSeed
method.
var generator = aleaRNGFactory(1);
// Get some random numbers
generator.uInt32();
generator.uInt32();
// Change seed
generator.setSeed(2);
// Get some more random numbers
generator.uInt32();
generator.uInt32();
You can get and restore the internal state with getState
and setState
.
var generator = aleaRNGFactory();
generator.uInt32();
generator.uInt32();
var state = generator.getState(); // Get the generator state
var value1 = generator.uInt32();
generator.uInt32();
generator.uInt32();
generator.setState(state); // Set the previouse state
var value2 = generator.uInt32();
value1 === value2; // true
If you want something similar to Math.random()
you can use the JavaScript
Date API with a timestamp, e.g.:
var generator = aleaRNGFactory(Date.now());
var random = generator.uFloat32;
// Get a random float number
random();
The murmurHash
functions implements the MurmurHash2 algorithm
in JavaScript. It takes an string and generates a non-cryptographic hash
number as unsigned integer.
The simplest way to use it is by passing a string to generate the hash
number. The default seed is 0
.
var hash1 = murmurHash('My string.');
var hash2 = murmurHash('My string.', 0);
hash1; // 1836966117
hash1 === hash2; // true
This should create the exact same result on your machine!
Different seeds generate different results for the same input string.
Only whole numbers are valid seed values for the murmurHash
function!
var hash1 = murmurHash('My string.', 1);
var hash2 = murmurHash('My string.', 2);
hash1 === hash2; // false
Float numbers as seed value throw a TypeError
:
var hash = murmurHash('My string.', 0.7); // TypeError!
This package contains all the type definitions for TypeScript needed:
import {
NumberGenerator, NumberHashGenerator,
aleaRNGFactory, murmurHash
} from 'number-generator';
const generator: NumberGenerator = aleaRNGFactory();
// const factory: () => NumberGenerator = aleaRNGFactory;
const hashFn: NumberHashGenerator = murmurHash;
generator.uInt32();
hashFn('What?', 42);
If you want ot contribute see https://github.com/MartinHelmut/number-generator/blob/master/CONTRIBUTING.md
"Why one pseudo random number generator and one number hash function" you may ask? Read more in this fantastic blog post about "A primer on repeatable random numbers" from Rune Skovbo Johansen.
Thanks to Johannes Baagøe for the Alea port and Ray Morgan for the MurmurHash2 algorithm implementation in JavaScript.