pure-random-number

A module for generating cryptographically secure pseudo-random numbers.

Zero dependencies ~56LOC, pure es6/esm, runs on browser + node without transpilation.

This module is based on code originally written by Scott Arciszewski, (WTFPL / CC0 / ZAP)

Usage

Basic:

1import { randomNumber } from 'pure-random-number'
2
3const n = await randomNumber(1, 20) // defaults to crypto:subtle getRandomValues()
4console.log('Cryptographically Secure Random Number', n)

Bring your own generator:

1let prevHash = await sha256('Hello World')
2const prng = async (nBytes) => {
3    if (nBytes > 32) throw new Error('Entropy unsupported')
4    prevHash = await sha256(prevHash)
5    return prevHash
6}
7
8const n = await randomNumber(1, 20, prng)
9
10console.log('Deterministic Random Number', n)

API

see JSdoc annotations for accurate descriptions.

await randomNumber(minimum: number, maximum: number, generator = randomBytes)

Returns a stable random positive integer within the specified range.

Note that the range is inclusive, and both numbers must be positive integer values.

It is not possible to securely generate a random value for floating point numbers, so if you are working with fractional numbers (eg. 1.24), you will have to decide on a fixed 'precision' and turn them into integer values (eg. 124).

bytesNeeded(min: number, max: number)

Returns amount of bytes required for a given range

randomSeedNumber(seed: Uint8Array, minimum: number, maximum: number)

Returns a stable random positive integer extracted from seed within the specified range.

Changelog

• 3.2.0 (July 7, 2024) Removed obsolete validators, exported sync randomSeedNumber() & bytesNeeded()
• 3.0.0 (July 7, 2024): Converted to ESM, removed sync version
• 2.1.0 (June 12, 2020): Added sync version.
• 2.0.0 (May 3, 2020): Removed dependencies and ported to standardjs
• 1.0.2 (March 8, 2016): Security release! Patched handling of large numbers; input values are now checked for MIN_SAFE_INTEGER and MAX_SAFE_INTEGER, and the correct bitwise operator is used (>>> rather than >>).
• 1.0.1 (March 8, 2016): Unimportant file cleanup.
• 1.0.0 (March 8, 2016): Initial release.

License

Apache 2.0 - Decent Labs