random-js

• Version 2.1.0
• Published
• 279 kB
• No dependencies

npm i random-js

Overview

A mathematically correct random number generator library for JavaScript.

Variables

variablebrowserCrypto

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().

variablenativeMath

const nativeMath: Engine;
• An int32-producing Engine that uses Math.random()

variablenodeCrypto

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

functionbool

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

functioncreateEntropy

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

functiondate

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

functiondice

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

functiondie

die: (sideCount: number) => Distribution<number>;
• Returns a Distribution to return a value within [1, sideCount]

Parameter sideCount

The number of sides of the die

functionhex

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

functionint32

int32: (engine: Engine) => number;
• Returns a value within [-0x80000000, 0x7fffffff]

functionint53

int53: (engine: Engine) => number;
• Returns a value within [-0x20000000000000, 0x1fffffffffffff]

functionint53Full

int53Full: (engine: Engine) => number;
• Returns a value within [-0x20000000000000, 0x20000000000000]

functioninteger

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.

functionpick

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)

functionpicker

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)

functionreal

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.

functionrealZeroToOneExclusive

realZeroToOneExclusive: (engine: Engine) => number;
• Returns a floating-point value within [0.0, 1.0)

functionrealZeroToOneInclusive

realZeroToOneInclusive: (engine: Engine) => number;
• Returns a floating-point value within [0.0, 1.0]

functionsample

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

functionshuffle

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.

functionstring

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

functionuint32

uint32: (engine: Engine) => number;
• Returns a value within [0, 0xffffffff]

functionuint53

uint53: (engine: Engine) => number;
• Returns a value within [0, 0x1fffffffffffff]

functionuint53Full

uint53Full: (engine: Engine) => number;
• Returns a value within [0, 0x20000000000000]

functionuuid4

uuid4: (engine: Engine) => string;
• Returns a Universally Unique Identifier Version 4.

See http://en.wikipedia.org/wiki/Universally_unique_identifier

Classes

classMersenneTwister19937

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

methodautoSeed

static autoSeed: () => MersenneTwister19937;
• Returns a MersenneTwister19937 seeded with the current time and a series of natively-generated random values

• Discards one or more items from the engine

Parameter count

The count of items to discard

methodgetUseCount

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.

methodnext

next: () => number;
• Returns the next int32 value of the sequence

methodseed

static seed: (initial: number) => MersenneTwister19937;
• Returns a MersenneTwister19937 seeded with an initial int32 value

Parameter initial

the initial seed value

methodseedWithArray

static seedWithArray: (source: ArrayLike<number>) => MersenneTwister19937;
• Returns a MersenneTwister19937 seeded with zero or more int32 values

Parameter source

A series of int32 values

classRandom

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)

methodbool

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

methoddate

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

methoddice

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

methoddie

die: (sideCount: number) => number;
• Returns a value within [1, sideCount]

Parameter sideCount

The number of sides of the die

methodhex

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

methodint32

int32: () => number;
• Returns a value within [-0x80000000, 0x7fffffff]

methodint53

int53: () => number;
• Returns a value within [-0x20000000000000, 0x1fffffffffffff]

methodint53Full

int53Full: () => number;
• Returns a value within [-0x20000000000000, 0x20000000000000]

methodinteger

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.

methodpick

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)

methodreal

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.

methodrealZeroToOneExclusive

realZeroToOneExclusive: () => number;
• Returns a floating-point value within [0.0, 1.0)

methodrealZeroToOneInclusive

realZeroToOneInclusive: () => number;
• Returns a floating-point value within [0.0, 1.0]

methodsample

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

methodshuffle

shuffle: <T>(array: T[]) => T[];
• Shuffles an array in-place

Parameter array

The array to shuffle

methodstring

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

methoduint32

uint32: () => number;
• Returns a value within [0, 0xffffffff]

methoduint53

uint53: () => number;
• Returns a value within [0, 0x1fffffffffffff]

methoduint53Full

uint53Full: () => number;
• Returns a value within [0, 0x20000000000000]

methoduuid4

uuid4: () => string;
• Returns a Universally Unique Identifier Version 4.

See http://en.wikipedia.org/wiki/Universally_unique_identifier

Interfaces

interfaceEngine

interface Engine {}
• A mechanism to retrieve random int32 values

methodnext

next: () => number;

Type Aliases

typeDistribution

type Distribution<T = number> = (engine: Engine) => T;
• A function to use an Engine to produce a value

typeStringDistribution

type StringDistribution = (engine: Engine, length: number) => string;
• A function to use an Engine to produce a string of a requested length

Dependencies (0)

No dependencies.

Peer Dependencies (0)

No peer dependencies.

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