Random

Defined in: src/random.ts:86

An independent stream of randomness: new Random(42).integer(1, 6).

Method names match the ransu namespace exactly, for the numbers, collections and strings it covers. Libraries should own a Random rather than call the global, which an application may re-seed.

The modules that take an { engine } option — uuid, the distributions, dice, geometry, color — reach the same stream through rng.engine.

Example

const rng = new Random(42);
rng.integer(1, 6);         // 3
rng.pick(["a", "b", "c"]); // "c"
rng.shuffle([1, 2, 3]);    // [ 3, 1, 2 ]

// The same seed always replays the same stream.
new Random(42).integer(1, 6); // 3 again

// Any engine, by factory or by instance.
new Random(42, { engine: engines.pcg32 });
new Random(engines.chacha20(42));

Constructors

Constructor

new Random(seedOrEngine?, options?): Random

Defined in: src/random.ts:90

Parameters

seedOrEngine?

Seed | EngineLike

options?

RandomOptions = {}

Returns

Random

Accessors

engine

Get Signature

get engine(): Engine

Defined in: src/random.ts:119

The underlying engine. Hand this to { engine } options elsewhere.

Example

const rng = new Random(42);
uuid.v4({ engine: rng.engine }); // a UUID from this stream

Returns

Engine

Methods

below()

below(n): number

Defined in: src/random.ts:251

An integer in [0, n). The form array indices want.

Parameters

n

number

Returns

number

---

bigBits()

bigBits(n): bigint

Defined in: src/random.ts:289

An integer built from n random bits, with no width limit.

Parameters

n

number

Returns

bigint

---

bigint()

bigint(min, max): bigint

Defined in: src/random.ts:261

A bigint in [min, max] — both ends included.

Parameters

min

bigint

max

bigint

Returns

bigint

---

bits()

bits(n): number

Defined in: src/random.ts:284

An integer built from n random bits (up to 53).

Parameters

n

number

Returns

number

---

bool()

bool(): boolean

Defined in: src/random.ts:266

true or false, evenly.

Returns

boolean

---

bytes()

bytes(n): Uint8Array

Defined in: src/random.ts:293

Parameters

n

number

Returns

Uint8Array

---

chance()

chance(p): boolean

Defined in: src/random.ts:270

Parameters

p

number

Returns

boolean

---

char()

char(options?): string

Defined in: src/random.ts:450

A uniformly chosen character, as a string of one code point.

Parameters

options?

UnicodeOptions | CodePointSet

Returns

string

---

chars()

chars(length, options?): string

Defined in: src/random.ts:455

A random string of length code points, not UTF-16 units.

Parameters

length

number

options?

UnicodeOptions | CodePointSet

Returns

string

---

choices()

choices<T>(items, k): T[]

Defined in: src/random.ts:363

k elements with replacement.

Type Parameters

T

T

Parameters

items

Collection<T>

k

number

Returns

T[]

---

clone()

clone(): Random

Defined in: src/random.ts:157

An independent copy positioned exactly where this one is.

Returns

Random

Example

const rng = new Random(42);
const copy = rng.clone();
rng.random() === copy.random(); // true, then they diverge

---

codePoint()

codePoint(options?): number

Defined in: src/random.ts:445

A uniformly chosen Unicode code point.

Parameters

options?

UnicodeOptions | CodePointSet

Returns

number

---

combination()

combination<T>(items, k): T[]

Defined in: src/random.ts:373

k distinct elements, kept in their original order.

Type Parameters

T

T

Parameters

items

Collection<T>

k

number

Returns

T[]

---

fillBytes()

fillBytes(out): void

Defined in: src/random.ts:298

Fill an existing buffer, with no allocation.

Parameters

out

Uint8Array

Returns

void

---

float()

float(min?, max?): number

Defined in: src/random.ts:241

A double in [min, max), or [0, 1) with no arguments.

Parameters

min?

number

max?

number

Returns

number

---

floats()

floats(n): Float64Array

Defined in: src/random.ts:303

n doubles in [0, 1).

Parameters

n

number

Returns

Float64Array

---

getState()

getState(): EngineState

Defined in: src/random.ts:201

A JSON-serialisable snapshot. Restore it with Random.setState.

Returns

EngineState

Example

const rng = new Random(42);
const saved = rng.getState();
const first = rng.random();
rng.setState(saved);
rng.random() === first; // true

---

hex()

hex(length): string

Defined in: src/random.ts:440

A random lowercase hexadecimal string.

Parameters

length

number

Returns

string

---

integer()

integer(min, max): number

Defined in: src/random.ts:246

An integer in [min, max] — both ends included.

Parameters

min

number

max

number

Returns

number

---

integers()

integers(n, min, max): Float64Array

Defined in: src/random.ts:308

n integers in [min, max], validated once rather than per element.

Parameters

n

number

min

number

max

number

Returns

Float64Array

---

oneIn()

oneIn(n): boolean

Defined in: src/random.ts:274

Parameters

n

number

Returns

boolean

---

permutation()

permutation(n): number[]

Defined in: src/random.ts:406

Parameters

n

number

Returns

number[]

---

pick()

pick<T>(items): T

Defined in: src/random.ts:320

One element. Throws when the collection is empty.

Type Parameters

T

T

Parameters

items

Collection<T>

Returns

T

---

pickEntry()

pickEntry<K, V>(target): [K, V]

Defined in: src/random.ts:339

Type Parameters

K

K extends string | number | symbol

V

V

Parameters

target

Record<K, V> | Map<K, V>

Returns

[K, V]

---

pickIndex()

pickIndex<T>(items): number

Defined in: src/random.ts:329

Type Parameters

T

T

Parameters

items

Collection<T>

Returns

number

---

pickKey()

pickKey<K, V>(target): K

Defined in: src/random.ts:333

Type Parameters

K

K extends string | number | symbol

V

V

Parameters

target

Record<K, V> | Map<K, V>

Returns

K

---

pickValue()

pickValue<K, V>(target): V

Defined in: src/random.ts:346

One value of a plain object or Map.

Type Parameters

K

K extends string | number | symbol

V

V

Parameters

target

Record<K, V> | Map<K, V>

Returns

V

---

random()

random(): number

Defined in: src/random.ts:236

A double in [0, 1). The Math.random() drop-in.

Returns

number

---

range()

range(start, stop?, step?): number

Defined in: src/random.ts:256

Python’s randrange: a member of [start, stop) stepping by step.

Parameters

start

number

stop?

number

step?

number

Returns

number

---

reservoir()

reservoir<T>(items, k): T[]

Defined in: src/random.ts:392

k elements from an iterable of unknown length, in one pass.

Type Parameters

T

T

Parameters

items

Iterable<T>

k

number

Returns

T[]

---

sample()

sample<T>(items, k): T[]

Defined in: src/random.ts:368

k distinct elements, without replacement.

Type Parameters

T

T

Parameters

items

Collection<T>

k

number

Returns

T[]

---

sampleIntegers()

sampleIntegers(count, min, max): number[]

Defined in: src/random.ts:358

count distinct integers in [min, max], without building the range.

Parameters

count

number

min

number

max

number

Returns

number[]

---

seed()

seed(seed): this

Defined in: src/random.ts:133

Restart from new seed material. A seedable engine restarts in place; an unseedable one is replaced by the default deterministic engine.

Parameters

seed

Seed

Returns

this

Example

const rng = new Random();
rng.seed(42).integer(1, 6); // 3, and chainable

---

setState()

setState(state): this

Defined in: src/random.ts:221

Rewind or fast-forward this stream to a saved snapshot.

Parameters

state

EngineState

Returns

this

Example

const rng = new Random(42);
rng.setState(rng.getState()); // chainable

---

shuffle()

shuffle<T>(items): T[]

Defined in: src/random.ts:397

A shuffled copy. The input is untouched.

Type Parameters

T

T

Parameters

items

Collection<T>

Returns

T[]

---

shuffleInPlace()

shuffleInPlace<T>(items): T[]

Defined in: src/random.ts:402

Fisher–Yates in place — the only mutating shuffle.

Type Parameters

T

T

Parameters

items

T[]

Returns

T[]

---

shuffleString()

shuffleString(value): string

Defined in: src/random.ts:410

Parameters

value

string

Returns

string

---

sign()

sign(): number

Defined in: src/random.ts:279

-1 or 1.

Returns

number

---

split()

split(n): Random[]

Defined in: src/random.ts:178

n streams that will not overlap, for parallel work.

Parameters

n

number

Returns

Random[]

Example

const [a, b, c] = new Random(42, { engine: engines.pcg32 }).split(3);
a.random(); // each worker draws from its own stream

---

stream()

stream(): Generator<number, never, unknown>

Defined in: src/random.ts:313

An endless stream of doubles in [0, 1).

Returns

Generator<number, never, unknown>

---

string()

string(length, alphabet?): string

Defined in: src/random.ts:435

A random string over alphabet (default alphanumeric).

Parameters

length

number

alphabet?

string | ArrayLike<string>

Returns

string

---

subset()

subset<T>(items, p): T[]

Defined in: src/random.ts:353

Each element kept independently with probability p.

Type Parameters

T

T

Parameters

items

Collection<T>

p

number

Returns

T[]

---

takeOut()

takeOut<T>(items): T

Defined in: src/random.ts:378

Remove one random element and return it. Mutates the array.

Type Parameters

T

T

Parameters

items

T[]

Returns

T

---

tryPick()

tryPick<T>(items): T | undefined

Defined in: src/random.ts:325

One element, or undefined when the collection is empty.

Type Parameters

T

T

Parameters

items

Collection<T>

Returns

T | undefined

---

weightedPick()

weightedPick<T>(items, weights): T

Defined in: src/random.ts:415

One element, with probability proportional to its weight.

Type Parameters

T

T

Parameters

items

Collection<T>

weights

ArrayLike<number>

Returns

T

---

weightedSample()

weightedSample<T>(items, weights, k): T[]

Defined in: src/random.ts:383

k distinct elements, weightedPick.

Type Parameters

T

T

Parameters

items

Collection<T>

weights

ArrayLike<number>

k

number

Returns

T[]

---

weightedTable()

weightedTable<T>(items, weights): object

Defined in: src/random.ts:423

A reusable weightedPick sampler, O(1) per draw. Build it once when the same weights are sampled repeatedly.

Type Parameters

T

T

Parameters

items

Collection<T>

weights

ArrayLike<number>

Returns

object

pick()

pick(): T

Returns

T