random-js

random-js

Version 2.1.0
Published 4 years ago
279 kB
No dependencies
MIT license

Install

npm i random-js

yarn add random-js

pnpm add random-js

Overview

A mathematically correct random number generator library for JavaScript.

Variables

variable browserCrypto

const browserCrypto: Engine;

An Engine that relies on the globally-available crypto.getRandomValues, which is typically available in modern browsers.
See https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues
If unavailable or otherwise non-functioning, then browserCrypto will likely throw on the first call to next().

variable nativeMath

const nativeMath: Engine;

An int32-producing Engine that uses Math.random()

variable nodeCrypto

const nodeCrypto: Engine;

An Engine that relies on the node-available require('crypto').randomBytes, which has been available since 0.58.
See https://nodejs.org/api/crypto.html#crypto_crypto_randombytes_size_callback
If unavailable or otherwise non-functioning, then nodeCrypto will likely throw on the first call to next().

Functions

function bool

bool: {
    (): Distribution<boolean>;
    (percentage: number): Distribution<boolean>;
    (numerator: number, denominator: number): Distribution<boolean>;
};

Returns a boolean Distribution with 50% probability of being true or false
Returns a boolean Distribution with the provided percentage of being true
Parameter percentage
A number within [0, 1] of how often the result should be true
Returns a boolean Distribution with a probability of numerator divided by denominator of being true
Parameter numerator
The numerator of the probability
Parameter denominator
The denominator of the probability

function createEntropy

createEntropy: (engine?: Engine, length?: number) => number[];

Returns an array of random int32 values, based on current time and a random number engine
Parameter engine
an Engine to pull random values from, default nativeMath
Parameter length
the length of the Array, minimum 1, default 16

function date

date: (start: Date, end: Date) => Distribution<Date>;

Returns a Distribution that returns a random Date within the inclusive range of [start, end].
Parameter start
The minimum Date
Parameter end
The maximum Date

function dice

dice: (sideCount: number, dieCount: number) => Distribution<number[]>;

Returns a distribution that returns an array of length dieCount of values within [1, sideCount]
Parameter sideCount
The number of sides of each die
Parameter dieCount
The number of dice

function die

die: (sideCount: number) => Distribution<number>;

Returns a Distribution to return a value within [1, sideCount]
Parameter sideCount
The number of sides of the die

function hex

hex: (uppercase?: boolean) => StringDistribution;

Returns a Distribution that returns a random string comprised of numbers or the characters abcdef (or ABCDEF) of length length.
Parameter length
Length of the result string
Parameter uppercase
Whether the string should use ABCDEF instead of abcdef

function int32

int32: (engine: Engine) => number;

Returns a value within [-0x80000000, 0x7fffffff]

function int53

int53: (engine: Engine) => number;

Returns a value within [-0x20000000000000, 0x1fffffffffffff]

function int53Full

int53Full: (engine: Engine) => number;

Returns a value within [-0x20000000000000, 0x20000000000000]

function integer

integer: (min: number, max: number) => Distribution;

Returns a Distribution to return a value within [min, max]
Parameter min
The minimum integer value, inclusive. No less than -0x20000000000000.
Parameter max
The maximum integer value, inclusive. No greater than 0x20000000000000.

function pick

pick: <T>(
    engine: Engine,
    source: ArrayLike<T>,
    begin?: number,
    end?: number
) => T;

Returns a random value within the provided source within the sliced bounds of begin and end.
Parameter source
an array of items to pick from
Parameter begin
the beginning slice index (defaults to 0)
Parameter end
the ending slice index (defaults to source.length)

function picker

picker: <T>(
    source: ArrayLike<T>,
    begin?: number,
    end?: number
) => Distribution<T>;

Returns a Distribution to random value within the provided source within the sliced bounds of begin and end.
Parameter source
an array of items to pick from
Parameter begin
the beginning slice index (defaults to 0)
Parameter end
the ending slice index (defaults to source.length)

function real

real: (min: number, max: number, inclusive?: boolean) => Distribution;

Returns a floating-point value within [min, max) or [min, max]
Parameter min
The minimum floating-point value, inclusive.
Parameter max
The maximum floating-point value.
Parameter inclusive
If true, max will be inclusive.

function realZeroToOneExclusive

realZeroToOneExclusive: (engine: Engine) => number;

Returns a floating-point value within [0.0, 1.0)

function realZeroToOneInclusive

realZeroToOneInclusive: (engine: Engine) => number;

Returns a floating-point value within [0.0, 1.0]

function sample

sample: <T>(engine: Engine, population: ArrayLike<T>, sampleSize: number) => T[];

From the population array, produce an array with sampleSize elements that are randomly chosen without repeats.
Parameter engine
The Engine to use when choosing random values
Parameter population
An array that has items to choose a sample from
Parameter sampleSize
The size of the result array

function shuffle

shuffle: <T>(engine: Engine, array: T[], downTo?: number) => T[];

Shuffles an array in-place
Parameter engine
The Engine to use when choosing random values
Parameter array
The array to shuffle
Parameter downTo
minimum index to shuffle. Only used internally.

function string

string: { (): StringDistribution; (pool: string): StringDistribution };

Returns a distribution that returns a random string using numbers, uppercase and lowercase letters, _, and - of length length.
Parameter length
Length of the result string
Returns a distribution that returns a random string using the provided string pool as the possible characters to choose from of length length.
Parameter length
Length of the result string

function uint32

uint32: (engine: Engine) => number;

Returns a value within [0, 0xffffffff]

function uint53

uint53: (engine: Engine) => number;

Returns a value within [0, 0x1fffffffffffff]

function uint53Full

uint53Full: (engine: Engine) => number;

Returns a value within [0, 0x20000000000000]

function uuid4

uuid4: (engine: Engine) => string;

Returns a Universally Unique Identifier Version 4.
See http://en.wikipedia.org/wiki/Universally_unique_identifier

Classes

class MersenneTwister19937

class MersenneTwister19937 implements Engine {}

An Engine that is a pseudorandom number generator using the Mersenne Twister algorithm based on the prime 2**19937 − 1
See http://en.wikipedia.org/wiki/Mersenne_twister

method autoSeed

static autoSeed: () => MersenneTwister19937;

Returns a MersenneTwister19937 seeded with the current time and a series of natively-generated random values

method discard

discard: (count: number) => this;

Discards one or more items from the engine
Parameter count
The count of items to discard

method getUseCount

getUseCount: () => number;

Returns the number of times that the Engine has been used.
This can be provided to an unused MersenneTwister19937 with the same seed, bringing it to the exact point that was left off.

method next

next: () => number;

Returns the next int32 value of the sequence

method seed

static seed: (initial: number) => MersenneTwister19937;

Returns a MersenneTwister19937 seeded with an initial int32 value
Parameter initial
the initial seed value

method seedWithArray

static seedWithArray: (source: ArrayLike<number>) => MersenneTwister19937;

Returns a MersenneTwister19937 seeded with zero or more int32 values
Parameter source
A series of int32 values

class Random

class Random {}

A wrapper around an Engine that provides easy-to-use methods for producing values based on known distributions

constructor

constructor(engine?: Engine);

Creates a new Random wrapper
Parameter engine
The engine to use (defaults to a Math.random-based implementation)

method bool

bool: {
    (): boolean;
    (percentage: number): boolean;
    (numerator: number, denominator: number): boolean;
};

Returns a boolean with 50% probability of being true or false
Returns a boolean with the provided percentage of being true
Parameter percentage
A number within [0, 1] of how often the result should be true
Returns a boolean with a probability of numerator/denominator of being true
Parameter numerator
The numerator of the probability
Parameter denominator
The denominator of the probability

method date

date: (start: Date, end: Date) => Date;

Returns a random Date within the inclusive range of [start, end].
Parameter start
The minimum Date
Parameter end
The maximum Date

method dice

dice: (sideCount: number, dieCount: number) => number[];

Returns an array of length dieCount of values within [1, sideCount]
Parameter sideCount
The number of sides of each die
Parameter dieCount
The number of dice

method die

die: (sideCount: number) => number;

Returns a value within [1, sideCount]
Parameter sideCount
The number of sides of the die

method hex

hex: (length: number, uppercase?: boolean) => string;

Returns a random string comprised of numbers or the characters abcdef (or ABCDEF) of length length.
Parameter length
Length of the result string
Parameter uppercase
Whether the string should use ABCDEF instead of abcdef

method int32

int32: () => number;

Returns a value within [-0x80000000, 0x7fffffff]

method int53

int53: () => number;

Returns a value within [-0x20000000000000, 0x1fffffffffffff]

method int53Full

int53Full: () => number;

Returns a value within [-0x20000000000000, 0x20000000000000]

method integer

integer: (min: number, max: number) => number;

Returns a value within [min, max]
Parameter min
The minimum integer value, inclusive. No less than -0x20000000000000.
Parameter max
The maximum integer value, inclusive. No greater than 0x20000000000000.

method pick

pick: <T>(source: ArrayLike<T>, begin?: number, end?: number) => T;

Return a random value within the provided source within the sliced bounds of begin and end.
Parameter source
an array of items to pick from
Parameter begin
the beginning slice index (defaults to 0)
Parameter end
the ending slice index (defaults to source.length)

method real

real: (min: number, max: number, inclusive?: boolean) => number;

Returns a floating-point value within [min, max) or [min, max]
Parameter min
The minimum floating-point value, inclusive.
Parameter max
The maximum floating-point value.
Parameter inclusive
If true, max will be inclusive.

method realZeroToOneExclusive

realZeroToOneExclusive: () => number;

Returns a floating-point value within [0.0, 1.0)

method realZeroToOneInclusive

realZeroToOneInclusive: () => number;

Returns a floating-point value within [0.0, 1.0]

method sample

sample: <T>(population: ArrayLike<T>, sampleSize: number) => T[];

From the population array, returns an array with sampleSize elements that are randomly chosen without repeats.
Parameter population
An array that has items to choose a sample from
Parameter sampleSize
The size of the result array

method shuffle

shuffle: <T>(array: T[]) => T[];

Shuffles an array in-place
Parameter array
The array to shuffle

method string

string: { (length: number): string; (length: number, pool: string): string };

Returns a random string using numbers, uppercase and lowercase letters, _, and - of length length.
Parameter length
Length of the result string
Returns a random string using the provided string pool as the possible characters to choose from of length length.
Parameter length
Length of the result string

method uint32

uint32: () => number;

Returns a value within [0, 0xffffffff]

method uint53

uint53: () => number;

Returns a value within [0, 0x1fffffffffffff]

method uint53Full

uint53Full: () => number;

Returns a value within [0, 0x20000000000000]

method uuid4

uuid4: () => string;

Returns a Universally Unique Identifier Version 4.
See http://en.wikipedia.org/wiki/Universally_unique_identifier

Interfaces

interface Engine

interface Engine {}

A mechanism to retrieve random int32 values

method next

next: () => number;

Type Aliases

type Distribution

type Distribution<T = number> = (engine: Engine) => T;

A function to use an Engine to produce a value

type StringDistribution

type StringDistribution = (engine: Engine, length: number) => string;

A function to use an Engine to produce a string of a requested length

Package Files (29)

Dependencies (0)

No dependencies.

Dev Dependencies (14)

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/random-js.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/random-js)

HTML

<a href="https://www.jsdocs.io/package/random-js"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated 1 year ago.
Package analyzed in 1487 ms.
Missing or incorrect documentation? Open an issue for this package.

random-js

Install

Overview

Index

Variables

Functions

Classes

Interfaces

Type Aliases

Variables

variable browserCrypto

variable nativeMath

variable nodeCrypto

Functions

function bool

Parameter percentage

Parameter numerator

Parameter denominator

function createEntropy

Parameter engine

Parameter length

function date

Parameter start

Parameter end

function dice

Parameter sideCount

Parameter dieCount

function die

Parameter sideCount

function hex

Parameter length

Parameter uppercase

function int32

function int53

function int53Full

function integer

Parameter min

Parameter max

function pick

Parameter source

Parameter begin

Parameter end

function picker

Parameter source

Parameter begin

Parameter end

function real

Parameter min

Parameter max

Parameter inclusive

function realZeroToOneExclusive

function realZeroToOneInclusive

function sample

Parameter engine

Parameter population

Parameter sampleSize

function shuffle

Parameter engine

Parameter array

Parameter downTo

function string

Parameter length

Parameter length

function uint32

function uint53

function uint53Full

function uuid4

Classes

class MersenneTwister19937

method autoSeed

method discard

Parameter count

method getUseCount

method next

method seed

Parameter initial

method seedWithArray

Parameter source

class Random

constructor