Have ideas to improve npm?Join in the discussion! »

    number-generator
    TypeScript icon, indicating that this package has built-in type declarations

    4.0.5 • Public • Published

    Number Generator

    npm Build Status Coverage Status Commitizen friendly Standard Version styled with prettier

    Generate repeatable pseudo random numbers and non-cryptographic hash numbers for usage in Node.js (>= 8) and browser environments (major browsers and IE >= 10).

    Contents


    Update to version 4

    • Change murmurHash to murmurhash2_x86_32 (same function since v2, alias now removed).
    • Non ASCII characters (e.g. chinese or emoji) are now handled properly. This can produce different results if these characters where used before inside an input hash for all murmur hash functions.

    Usage

    This library (7.55 KB, gzipped size: 2.84 KB) contains the following methods: one PRNG (pseudo random number generator) called Alea and four number hash generators, MurmurHash2 and MurmurHash3 for 32 and 128 bit (x86 and x64) hash strings.

    More about the hash function MurmurHash can be found here on wikipedia.

    Install

    Based on your package manager you can install it via:

    # NPM
    npm install number-generator
    
    # Yarn
    yarn add number-generator
    
    # pnpm
    pnpm add number-generator

    After that you can import it either as a library, e.g.:

    // ESM
    import * as numberGenerator from "number-generator";
    
    // CJS
    const numberGenerator = require("number-generator");

    Or as single functions:

    // ESM
    import aleaRNGFactory from "number-generator/lib/aleaRNGFactory";
    import murmurhash2_x86_32 from "number-generator/lib/murmurhash2_x86_32";
    import murmurhash3_x86_32 from "number-generator/lib/murmurhash3_x86_32";
    import murmurhash3_x86_128 from "number-generator/lib/murmurhash3_x86_128";
    import murmurhash3_x64_128 from "number-generator/lib/murmurhash3_x64_128";
    
    // CJS
    const aleaRNGFactory = require("number-generator/lib/aleaRNGFactory");
    const murmurhash2_x86_32 = require("number-generator/lib/murmurhash2_x86_32");
    const murmurhash3_x86_32 = require("number-generator/lib/murmurhash3_x86_32");
    const murmurhash3_x86_128 = require("number-generator/lib/murmurhash3_x86_128");
    const murmurhash3_x64_128 = require("number-generator/lib/murmurhash3_x64_128");

    Also the library can safely be tree shaked. If tree shaking is used in e.g. Rollup or Webpack this will only put the used function with helpers in your bundle:

    import { aleaRNGFactory } from "number-generator";

    For use with TypeScript take a look at the usage with typescript section of this document.

    Remark: For direct browser usage you can use the exposed numberGenerator global, e.g.:

    // Direct browser usage e.g.:
    numberGenerator.murmurhash2_x86_32("something");

    All supported environments are listed under the support section.

    Random numbers

    You can use the aleaRNGFactory method to generate (pseudo) random numbers based an a seed (default seed is 1). Every seed produces the same result for the created getter method.

    ⚠️ Attention: The default seed 1 should not be used! It produces one duplicate at 4370 calls. This can be avoided by using a seed larger or equal to 2. Nevertheless, this is still included in the library to not break applications using the default behavior.

    Create a new random number generator

    First step is to include the library functions you want to use in your application. If you only want to use the Alea implementation you can import it directly:

    const aleaRNGFactory = require("number-generator/lib/aleaRNGFactory");

    Now you can create a new generator by calling the function with a seed equal or larger to 2. The number 0, float or negative numbers are not valid and will throw a TypeError. See the remark at the beginning of this section on why to avoid 1 as a seed.

    // Valid:
    const generator1 = aleaRNGFactory(2);
    const generator2 = aleaRNGFactory(4836325);
    
    // Invalid:
    const notValidGen1 = aleaRNGFactory(0);
    const notValidGen2 = aleaRNGFactory(0.47);
    const notValidGen3 = aleaRNGFactory(-1);

    Create an unsigned integer

    If you have a valid generator object you can use the uInt32 method to get a random unsigned integer. Call it multiple times to get new numbers.

    const { uInt32 } = aleaRNGFactory(10);
    uInt32(); // 20916391
    uInt32(); // 1567221093

    This will create the exact same result on your machine! You will always get the same value for the same seed.

    This means if you create multiple generators with the same seed, you get the same result for the n-th call:

    const generator1 = aleaRNGFactory(2);
    const generator2 = aleaRNGFactory(2);
    
    const value1 = generator1.uInt32();
    const 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.

    const { uFloat32 } = aleaRNGFactory(5);
    uFloat32(); // 0.0024349885061383247
    uFloat32(); // 0.1826920467428863

    Again, this will create the exact same result on your machine!

    If you create multiple generators with the same seed, you get the same result for the n-th call:

    const generator1 = aleaRNGFactory(4);
    const generator2 = aleaRNGFactory(4);
    
    const value1 = generator1.uFloat32();
    const value2 = generator2.uFloat32();
    
    value1 === value2; // true

    Change the seed

    You can change the seed used by the generator object with the setSeed method.

    const generator = aleaRNGFactory(2);
    
    // Get some random numbers
    generator.uInt32();
    generator.uInt32();
    
    // Change seed
    generator.setSeed(3);
    
    // Get some more random numbers
    generator.uInt32();
    generator.uInt32();

    Get and restore the state

    You can get and restore the internal state with getState and setState.

    const generator = aleaRNGFactory(42);
    generator.uInt32();
    generator.uInt32();
    const state = generator.getState(); // Get the generator state
    const value1 = generator.uInt32();
    generator.uInt32();
    generator.uInt32();
    generator.setState(state); // Restore the previous state
    const value2 = generator.uInt32();
    
    value1 === value2; // true

    For TypeScript the state interface is NumberGeneratorState.

    import { aleaRNGFactory, NumberGeneratorState } from "number-generator";
    
    const generator = aleaRNGFactory(2);
    generator.uInt32();
    
    const state: NumberGeneratorState = generator.getState();

    You can set the state with setState on two ways. Either you don't pass any parameter to the state function, where it will reset the state to the initial state. Or you can pass a state object to restore a previous state:

    const generator = aleaRNGFactory(2);
    generator.uInt32();
    
    const state = generator.getState();
    generator.setState(); // Reset the state
    generator.uInt32(); // Get a new value
    
    generator.setState(state); // Restore saved state

    Something like Math.random?

    If you want something similar to Math.random() (without generating duplicated values) you can use the JavaScript Date API with a timestamp and combine it with the uFloat32 method from the aleaRNGFactory e.g.:

    const { uFloat32: random } = aleaRNGFactory(Date.now());
    
    // Get a random float number
    random();

    Murmur hash

    To generate a hash there are four functions, murmurhash2_x86_32, murmurhash3_x86_32, murmurhash3_x86_128 and murmurhash3_x64_128. The "murmur hash" functions implement the MurmurHash algorithm for 32 and 128 bit in JavaScript (murmurhash2 and 3) for x86 and x64. They take a string and generate a non-cryptographic hash number as unsigned integer with 32 bit or a string hash with 128 bit.

    You can import the functions directly:

    const murmurhash2_x86_32 = require("number-generator/lib/murmurhash2_x86_32");
    const murmurhash3_x86_32 = require("number-generator/lib/murmurhash3_x86_32");
    const murmurhash3_x86_128 = require("number-generator/lib/murmurhash3_x86_128");
    const murmurhash3_x64_128 = require("number-generator/lib/murmurhash3_x64_128");

    Both murmurhash2_x86_32 and murmurhash3_x86_32 will generate a unsigned 32 bit number. The murmurhash3_x86_128 and murmurhash3_x64_128 functions will generate a 128 bit string. To showcase the difference:

    murmurhash2_x86_32("Hello"); // 1826530862
    murmurhash3_x86_32("Hello"); // 316307400
    murmurhash3_x86_128("Hello"); // "2360ae465e6336c6ad45b3f4ad45b3f4"
    murmurhash3_x64_128("Hello"); // "35b974ff55d4c41ca000eacf29125544"

    Basic hash generation

    All murmur hash functions work the same. So the following examples will take the murmur hash 2 function to demonstrate the usage. To use it pass a string to generate the hash number. The default seed used is 0.

    const hash1 = murmurhash2_x86_32("My string.");
    const hash2 = murmurhash2_x86_32("My string.", 0);
    
    hash1; // 1836966117
    hash1 === hash2; // true

    This will create the exact same result on your machine!

    Hash based on different seeds

    Different seeds generate different results for the same input string. Only whole numbers are valid seeds for any murmur hash function!

    const hash1 = murmurhash2_x86_32("My string.", 1);
    const hash2 = murmurhash2_x86_32("My string.", 2);
    
    hash1 === hash2; // false

    A float number as a seed throws a TypeError:

    const hash = murmurhash2_x86_32("My string.", 0.7); // TypeError!

    TypeScript

    This package contains all the type definitions for TypeScript. Every murmur hash function implements the NumberHashGenerator interface.

    import {
      NumberGenerator,
      NumberHashGenerator,
      aleaRNGFactory,
      murmurhash2_x86_32,
      murmurhash3_x86_32,
    } from "number-generator";
    
    const generator: NumberGenerator = aleaRNGFactory(2);
    // const factory: () => NumberGenerator = aleaRNGFactory;
    
    const hashFn1: NumberHashGenerator = murmurhash2_x86_32;
    const hashFn2: NumberHashGenerator = murmurhash3_x86_32;
    
    generator.uInt32();
    hashFn1("What?", 42);
    hashFn2("something", 14);

    Support

    This library was tested on the following environments:

    • Node >= 8
    • All major browsers and IE >= 10

    Benchmarks

    Disclaimer: The following benchmarks were created on a MacBook Pro, Processor 2,7 GHz Intel Core i5 with 8 GB 1867 MHz DDR3 memory and run under Node v12.14.1.

    aleaRNGFactory

    Comparison between uInt32 and uFloat32 methods:

    // v4.0.1
    aleaRNGFactory#uInt32()   x 23,094,220 ops/sec
    aleaRNGFactory#uFloat32() x 20,571,821 ops/sec
    

    murmurhash

    Comparison between murmurhash2_x86_32, murmurhash3_x86_32, murmurhash3_x86_128 and murmurhash3_x64_128 function:

    // v4.0.1
    murmurhash2_x86_32  x 834,241 ops/sec
    murmurhash3_x86_32  x 827,462 ops/sec
    murmurhash3_x86_128 x 300,153 ops/sec
    murmurhash3_x64_128 x 188,581 ops/sec
    

    To run them on your machine execute pnpm run test:benchmark.

    Development

    If you want to contribute see the CONTRIBUTING.md

    Disclaimer

    "Why pseudo random number generators and number hash functions" 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. Also thanks to Karan Lyons for the MurmurHash3 implementation.

    Resources used to tests against implementations in other languages are:

    Big thanks as well to Alex Ciminian for raising the issue with non ASCII characters: https://cimi.io/murmurhash3js-revisited/

    Install

    npm i number-generator

    DownloadsWeekly Downloads

    111

    Version

    4.0.5

    License

    MIT

    Unpacked Size

    245 kB

    Total Files

    24

    Last publish

    Collaborators

    • avatar