fast-random-factory

Yet another random number generator - Not!

It is a wrapper for your choice of random generator to cache and yield its results very fast when called repeatedly. Consider an array of cacheSize elements,

This factory is not limited to generating random numbers. Your customized generator may yeild any object.

Install

Using npm:

npm install fast-random-factory
 

Usage

const rngFactory = require('fast-random-factory');

The most basic usage is to use all defaults to generate random numbers between Number.MIN_SAFE_INTEGER and Number.MAX_SAFE_INTEGER

var rng = rngFactory.create();
var rand1 = rng.gen();
...
var randN = rng.gen();

More creative use cases pass the options object which is elaborated below.

var rng = rngFactory.create(options);
if (rng.err) {
    console.error('Error: ' + rng.err.message);
} else {
    var rand1 = rng.gen();
    ...
    var randN = rng.gen();
}

The return value of the create() method is an object:

{ 
    err,
    config,
    cache(),
    cacheIndex(),
    refreshCache(),
    gen()
}

In case of error, err is set to an instance of Error with its message field set to the reason.

In case of success,

• err is null

• the gen() method can be called repeatedly to yield random results

• the refreshCache() method can be called at any time to discard the old cash and recreate new one
  Useful for debugging:

• the config readonly property contains the configurations resulting from processing the options

• the cache() method returns the current cached randoms

• the cacheIndex() method returns the current index in the cache

Also see example.js in the module sources

Dependencies

This module depends on underscore.js referred to as '_' in the following.

The options Argument

The options object has the following fields and default values:

{        
    min: Number.MIN_SAFE_INTEGER,
    max: Number.MAX_SAFE_INTEGER,
    
    generator: {
        func: _.random(),                   // from the underscore package
        args: [min, max],
        argsValidator: (min, max) => min should be < max
    },
    
    cacheSize: 1,
    shuffle: truthy,
    debug: falsy,
    logger: console.log
}

Either the convenient syntax min, max should be used or the customizing generator object. The latter rules, i.e. If the customized generator object is used, the convenient syntax min, max are ignored. See example.js in the module sources

options.min

Ignored if the customized generator object is used. Otherwise, the resultant random number is between this number and options.max. If the default generator is used, the result could be equal to this number.

options.max

Ignored if the customized generator object is used. Otherwise, the resultant random number is between options.min and this number. If the default generator is used, the result could be equal to this number.

options.generator

If the default random number generator (i.e. _.random()) is not desirable, your choice can be used by customizing this object. Note: this generator is not limited to random numbers and can generate any random object.

options.generator.func

Your choice of random generator function which takes the options.generator.args array as arguments.

options.generator.args

The arguments array passed to options.generator.func.

options.generator.argsValidator

It validates the options.generator.args array;

     argsValidator(options.generator.args)

If all validations pass it should return null, otherwise it should return Error with its message field set to the cause of the error.

options.cacheSize

This integer must be >= 1.

options.shuffle

If set to truthy, the random array will be shuffled before it is doled out. Setting this to falsy will speed up cache refreshes.

options.debug

If set to truthy options.logger function is used to log debug messages.

options.logger

Your choice of logging function which takes only a String argument.

Seeding the Random Number Generator

The default random number generator ends up using Math.random which "selects the initial seed to the random number generation algorithm; it cannot be chosen or reset by the user". However, if it is desirable to explicitly seed the random number generator, use the custom options.generator object and seed it before its first usage.

License

The MIT License (MIT).

See the LICENSE file in this project for more details.