random-lib

A library that wraps the Node.js crypto functions to create random floats and bounded integers with ease.

Warning: I am not a cryptographer, or any sort of random number expert. An audit would be greatly appreciated.

Version 3.0 of this module brings a new API and very different performance characteristics for integers; however it also removes bias which existed in older versions of this module.

• Version 3 Update Notes
• Version 2 Docs

Installation

To install the module for use in your projects:

npm install random-lib

Usage

var rand = require('random-lib')
var opts = {
  min: 1,
  max: 10,
  num: 10
}

// get 10 random integers, between 1 and 10
rand.ints(opts, function(err, results) {
  console.log(results) // [ 1, 1, 8, 9, 1, 4, 1, 6, 3, 8 ]
})

// or, with promises
rand.ints(opts).then(function(results) {
  console.log(results) // [ 2, 8, 4, 5, 2, 1, 7, 7, 8, 9 ]
})

// or synchronously
var results = rand.intsSync(opts)
console.log(results) // [ 2, 1, 3, 8, 9, 7, 2, 4, 4, 7 ]

Options are accepted, but are different if you're asking for floats or integers.

Options

Options are passed via an object; what's shown below are the defaults, and nothing is required.

// for integers; what's shown are the defaults.
var options = {
  num: 10,  // number of ints to receive
  min: 0,  // minimum bound (inclusive)
  max: Number.MAX_SAFE_INT,  // maximum bound (exclusive),
  unique: false  // receive only unique ints; only supported when async
}
rand.ints(options, function(err, results) {
  console.log(results)
})

//for floats; what's shown are the defaults.
var options = {
  num: 10,  // number of floats to receive
  unique: false  // receive only unique floats; only supported when async
}
rand.floats(options, function(err, results) {
  console.log(results)
})

API

When calling any function, omitting a callback will cause the function to return a Promise.

• ints([options], [callback (err, results)]): number[]
  Get an array of random integers.
• int([options], [callback (err, result)]): number
  Convenience function to get a single random integer.
• floats([options], [callback (err, results)]): number[]
  Get an array of random floats between 0 and 1.
• float([options], [callback (err, results)]): number
  Convenience function to get a single random float between 0 and 1.

Synchronous Methods

Synchronous methods take the same options as their async counterparts, except for the unique option which is not supported while synchronous.

• intsSync([options]): number[]
• intSync([options]): number
• floatsSync([options]): number[]
• floatSync([options]): number

Notes

• Using the synchronous interface calls crypto.randomBytes synchronously; please be sure to read the documentation for your Node.js version to understand the performance implications.

Contributing

Feel free to send pull requests! I'm not picky, but would like the following:

1. Write tests for any new features, and do not break existing tests.
2. Follow existing code style.
3. Be sure to point out any changes that break API.
4. Do not bump package.json version or add new dependencies without discussing in an issue first.

History

See CHANGELOG for details.

License

MIT. See LICENSE for details.