contingent

Create cryptographically-strong random numbers in node.js or the browser

Usage no npm install needed!

<script type="module">
  import contingent from 'https://cdn.skypack.dev/contingent';
</script>

README

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

$ npm install contingent

Usage

Import functions individulally:

import { randomFloat, randomBit, randomIn } from 'contingent'

randomFloat() // 0.2344958782196045
randomBit() // true
randomIn(1, 10) // 7

Import container:

import contingent from 'contingent'

contingent.randomByte() // 113
contingent.randomOf([1, 2, 3, 4, 5]) // 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:

import { randomBytes } from 'contingent'

const bytes = randomBytes(10)
console.log(bytes)

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:

import { randomBytes } from 'contingent/lib/browser'

const bytes = randomBytes(10)
console.log(bytes)

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:

<script src="node_modules/contingent/dist/contingent.min.js"></script>

All contingent library functions, including the toArray utility function, are available via the contingent global:

<script>
  var randomFloat = contingent.randomFloat
  var randomBytes = contingent.randomBytes
  var toArray = contingent.toArray

  // Generate a random float.
  console.log(randomFloat()) // 0.5113708488643169

  // Generate an array of eight random bytes.
  var bytes = toArray(randomBytes(8))
  console.log(bytes) // [219, 93, 255, 210, 128, 148, 128, 76]
</script>

Library Functions

randomBytes

Return n random bytes as a Buffer or DataView, depending on how contingent is imported.

Signature:

export function randomBytes(n: number): Buffer|DataView

Usage:

randomBytes(10)

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

const bytes = randomBytes(4)
const array = Array.from(bytes)

console.log(array) // [ 132, 5, 38, 222 ]

DataView (browser):

const bytes = randomBytes(4)
const array = Array.from(new Uint8Array(bytes.buffer))

console.log(array) // [ 108, 183, 120, 227 ]

The toArray helper can also be used, which works for either Buffer or DataView:

import { toArray } from 'contingent/lib/utils'

const bytes = randomBytes(4)
const array = toArray(bytes)

console.log(array) // [2, 191, 57, 66]

randomBit

Return a random boolean.

Signature:

export function randomBit(): boolean

Usage:

randomBit() // true

randomByte

Return a random unsigned integer in the range [0, 255] (8 bits).

Signature:

export function randomByte(): number

Usage:

randomByte() // 223

randomInt

Return a random signed integer in the range [-2147483648, 2147483647] (32 bits).

Signature:

export function randomInt(): number

Usage:

randomInt() // -656291091

randomUInt

Return a random unsigned integer in the range [0, 4294967295] (32 bits).

Signature:

export function randomUInt(): number

Usage:

randomUInt() // 2444387034

randomFloat

Return a random unsigned float in the range [0, 1).

Signature:

export function randomFloat(): number

Usage:

randomFloat() // 0.14995522797107697

randomIn

Return an integer in the range [min, max), where max >= min.

Signature:

export function randomIn(min: number, max: number): number

Usage:

randomIn(1, 100) // 41

randomOf

Return an element of the given list at random.

Signature:

export function randomOf<T>(list: T[]): T

Usage:

randomOf(['r', 'a', 'n', 'd', 'o', 'm']) // 'a'
randomOf([...'contingent']) // 'g'

roll

Simulate the roll of a die with n sides.

Signature:

export function roll(n: number)

Usage:

roll(6) // 2
roll(20) // 17

shuffle

Shuffle an array in place.

Signature:

export function shuffle<T>(list: T[]): T[]

Usage:

shuffle([1, 2, 3, 4, 5]) // [ 3, 5, 4, 2, 1 ]

pick

Pick n values from an array at random (no duplicates).

Signature:

export function pick<T>(num: number, list: T[]): T[]

Usage:

// Create an array of characters.
const charList = [...'contingent']

// Pick three random characters from the list.
pick(3, 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:

export function select<T>(num: number, list: T[]): T[]

Usage:

// Create an array of characters.
const charList = [...'0123456789abcdef']

// Pick ten random characters from the list.
select(10, charList) // [ '1', 'a', '5', 'a', '9', 'e', '7', 'a', '8', '2' ]

replace

Replace a random element in an array with a given value.

Signature:

export function replace<T>(list: T[], value: T): T[]

Usage:

const array = [1, 2, 3, 4, 5]

replace(array, 999) // [ 1, 2, 3, 999, 5 ]

generate

Generate an array of arbitrary values.

Signature:

export function generate<T>(len: number, create: () => T): T[]

Usage:

// Generate 5 random bits.
generate(5, randomBit) // [ true, true, false, true, false ]

// Generate 3 signed floats.
generate(3, () => randomBit() ? -randomFloat() : randomFloat())
// [ 0.32383300201036036, -0.5866664333734661, 0.47603789367713034 ]