contingent
contingent (kən-tĭnˈjənt) neither impossible nor necessary.
Create cryptographically-strong random numbers in node.js or the browser. Includes several helpers for random number generation and working with arrays.
Written in TypeScript and targets ES2015 JavaScript
Contents
- Installation
- Usage
- Usage in the Browser
- Library Functions
randomBytes
- return n random bytesrandomBit
- return a random booleanrandomByte
- return a random byterandomInt
- return a random signed integerrandomUInt
- return a random unsigned integerrandomFloat
- return a random floatrandomIn
- return a random number in a rangerandomOf
- return a random value from an arrayroll
- simulate a die rollshuffle
- shuffle an arraypick
- pick n values from an array (no duplicates)select
- pick n values from an array (with duplicates)replace
- replace an array element at randomgenerate
- generate an array of values
Installation
$ npm install contingent
Usage
Import functions individulally:
randomFloat // 0.2344958782196045randomBit // truerandomIn1, 10 // 7
Import container:
contingent.randomByte // 113contingent.randomOf // 4
Usage in the Browser
By default, contingent
uses Node.js crytpo
under the hood to generate random bytes, which serve the rest of the library functions:
console.logbytes
Output:
<Buffer e3 f2 87 3b bd 77 cf f2 cf ec>
This is fine if you're shimming the crypto
lib or using a build tool such as webpack
or browserify
which will shim it for you. If crypto
is not being shimmed, you can import the browser
version of contingent
like so:
console.logbytes
Output:
DataView {
byteLength: 10,
byteOffset: 0,
buffer: ArrayBuffer { byteLength: 10 } }
The browser
module uses window.crypto
with a fallback of window.msCrypto
. If neither are found, contingent
will throw an error for most function invocations, specifically functions which rely on de novo random value generation.
Browser Distribution File
A contingent
binary is available for use via a script
tag:
All contingent
library functions, including the toArray
utility function, are available via the contingent
global:
Library Functions
randomBytes
Return n random bytes as a Buffer
or DataView
, depending on how contingent
is imported.
Signature:
Usage:
randomBytes10
Output for node (Buffer):
<Buffer 75 0d d6 ad e4 82 9c 85 f7 90>
Output for browser (DataView):
DataView {
byteLength: 10,
byteOffset: 0,
buffer: ArrayBuffer { byteLength: 10 } }
Converting to Array
Buffer (node):
console.logarray // [ 132, 5, 38, 222 ]
DataView (browser):
console.logarray // [ 108, 183, 120, 227 ]
The toArray
helper can also be used, which works for either Buffer or DataView:
console.logarray // [2, 191, 57, 66]
randomBit
Return a random boolean
.
Signature:
Usage:
randomBit // true
randomByte
Return a random unsigned integer in the range [0, 255]
(8 bits).
Signature:
Usage:
randomByte // 223
randomInt
Return a random signed integer in the range [-2147483648, 2147483647]
(32 bits).
Signature:
Usage:
randomInt // -656291091
randomUInt
Return a random unsigned integer in the range [0, 4294967295]
(32 bits).
Signature:
Usage:
randomUInt // 2444387034
randomFloat
Return a random unsigned float in the range [0, 1)
.
Signature:
Usage:
randomFloat // 0.14995522797107697
randomIn
Return an integer in the range [min, max)
, where max >= min.
Signature:
Usage:
randomIn1, 100 // 41
randomOf
Return an element of the given list at random.
Signature:
Usage:
randomOf // 'a'randomOf // 'g'
roll
Simulate the roll of a die with n sides.
Signature:
Usage:
roll6 // 2roll20 // 17
shuffle
Shuffle an array in place.
Signature:
Usage:
shuffle // [ 3, 5, 4, 2, 1 ]
pick
Pick n values from an array at random (no duplicates).
Signature:
Usage:
// Create an array of characters. // Pick three random characters from the list.pick3, charList // [ 'i', 't', 'c' ]
Note: because no duplicates are allowed, n cannot be greater than the list length.
select
Select n values from an array at random (allows duplicates).
Signature:
Usage:
// Create an array of characters. // Pick ten random characters from the list.select10, charList // [ '1', 'a', '5', 'a', '9', 'e', '7', 'a', '8', '2' ]
replace
Replace a random element in an array with a given value.
Signature:
Usage:
replacearray, 999 // [ 1, 2, 3, 999, 5 ]
generate
Generate an array of arbitrary values.
Signature:
Usage:
// Generate 5 random bits.generate5, randomBit // [ true, true, false, true, false ]
// Generate 3 signed floats.generate3,randomBit ? -randomFloat : randomFloat// [ 0.32383300201036036, -0.5866664333734661, 0.47603789367713034 ]