Number Generator

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.

Contents

• Usage
  • Install
  • Random numbers
    • Create a new random number generator
    • Create an unsigned integer
    • Create an unsigned float
    • Change the seed
    • Get the state
    • Something like Math.random?
  • Generate hash
  • TypeScript
• Development
  • Run tests
  • Build the library
• Disclaimer

---

Usage

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.

Install

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.

Random numbers

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.

Create a new random number generator

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);

Create an unsigned integer

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

Create an unsigned float

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

Change the seed

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();

Get the state

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

Something like Math.random?

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();

Generate hash

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!

TypeScript

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);

Development

If you want ot contribute see https://github.com/MartinHelmut/number-generator/blob/master/CONTRIBUTING.md

Disclaimer

"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.