RansuApi

Defined in: src/namespace/index.ts:86

The shape of the default export, derived from the object itself.

Extends

• Omit<typeof api, "default">

RansuApi(): number

Defined in: src/namespace/index.ts:88

Shorthand for RansuApi.random.

Returns

number

Properties

AliasTable

AliasTable: typeof AliasTable

Defined in: src/namespace/index.ts:57

Inherited from

Omit.AliasTable

---

alphabets

alphabets: object

Defined in: src/namespace/index.ts:45

The named alphabets string() accepts, for building your own.

alphanumeric

readonly alphanumeric: string

ascii

readonly ascii: “!"#$%&‘()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}” = “!"#$%&’()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}”

base32

readonly base32: "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567" = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"

base32hex

readonly base32hex: "0123456789ABCDEFGHIJKLMNOPQRSTUV" = "0123456789ABCDEFGHIJKLMNOPQRSTUV"

base58

readonly base58: "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz" = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"

base62

readonly base62: string

base64url

readonly base64url: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"

binary

readonly binary: "01" = "01"

digits

readonly digits: "0123456789" = DIGITS

hex

readonly hex: "0123456789abcdef" = "0123456789abcdef"

hexUpper

readonly hexUpper: "0123456789ABCDEF" = "0123456789ABCDEF"

letters

readonly letters: string

lower

readonly lower: "abcdefghijklmnopqrstuvwxyz" = LOWER

octal

readonly octal: "01234567" = "01234567"

unambiguous

readonly unambiguous: "23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz" = "23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"

upper

readonly upper: "ABCDEFGHIJKLMNOPQRSTUVWXYZ" = UPPER

Example

import { alphabets, string } from "ransu";

string(8, alphabets.lower);              // "qmzdfhbx"
string(8, alphabets.alphanumeric);       // the default
string(8, alphabets.hex + alphabets.upper); // combine them as strings

Inherited from

Omit.alphabets

---

angle

angle: () => number

Defined in: src/geometry.ts:142

A uniform angle in radians, in [0, 2pi).

Returns

number

Example

angle(); // 2.4913...

Inherited from

Omit.angle

---

angleDegrees

angleDegrees: () => number

Defined in: src/geometry.ts:154

A uniform angle in degrees, in [0, 360).

Returns

number

Example

angleDegrees(); // 142.74...

Inherited from

Omit.angleDegrees

---

backoff

backoff: (attempt, options) => number

Defined in: src/time.ts:128

How long to wait before retry number attempt, counting from 0.

Retrying on a fixed schedule makes every client in a fleet retry at the same instant; the jitter strategies exist to break that up.

Parameters

attempt

number

options?

BackoffOptions = {}

Returns

number

Example

backoff(0); // 87.3    around 100ms
backoff(1); // 213.9   around 200ms
backoff(4); // 1483.2  around 1.6s, capped by maxDelay

backoff(3, { base: 250, factor: 3, jitter: "equal" });

Inherited from

Omit.backoff

---

bates

bates: (n) => number

Defined in: src/global/distributions.ts:235

One draw: the mean of n uniforms.

Parameters

n

number

Returns

number

Example

bates(10); // 0.5127...

Inherited from

Omit.bates

---

below

below: (n) => number

Defined in: src/global/numbers.ts:52

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

Parameters

n

number

Returns

number

Example

const items = ["a", "b", "c"];
items[below(items.length)]; // "c"

Inherited from

Omit.below

---

bernoulli

bernoulli: (p) => number

Defined in: src/global/distributions.ts:276

1 with probability p, otherwise 0.

Parameters

p?

number = 0.5

Returns

number

Example

bernoulli();     // 1
bernoulli(0.25); // 0

Inherited from

Omit.bernoulli

---

beta

beta: (alpha, betaShape) => number

Defined in: src/global/distributions.ts:77

One draw in (0, 1), shaped by two positive parameters.

Parameters

alpha

number

betaShape

number

Returns

number

Example

beta(2, 5); // 0.2734...  skewed toward 0

Inherited from

Omit.beta

---

bigBits

bigBits: (n) => bigint

Defined in: src/global/numbers.ts:151

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

Parameters

n

number

Returns

bigint

Example

bigBits(256); // 8873184...n

Inherited from

Omit.bigBits

---

bigint

bigint: (min, max) => bigint

Defined in: src/global/numbers.ts:78

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

Parameters

min

bigint

max

bigint

Returns

bigint

Example

bigint(0n, 2n ** 128n); // 214703556478...n

Inherited from

Omit.bigint

---

binomial

binomial: (n, p) => number

Defined in: src/global/distributions.ts:301

The number of successes in n independent trials.

Parameters

n

number

p

number

Returns

number

Example

binomial(10, 0.5); // 6

Inherited from

Omit.binomial

---

bits

bits: (n) => number

Defined in: src/global/numbers.ts:139

An integer built from n random bits, up to 53.

Parameters

n

number

Returns

number

Example

bits(8);  // 173   an integer in [0, 256)
bits(53); // 6519085048561357

Inherited from

Omit.bits

---

bool

bool: () => boolean

Defined in: src/global/numbers.ts:90

true or false, evenly.

Returns

boolean

Example

bool(); // true

Inherited from

Omit.bool

---

bucket

bucket: (key, buckets, salt?) => number

Defined in: src/hash.ts:80

A stable bucket in [0, buckets) for key. Evenly spread across keys.

Parameters

key

Seed

buckets

number

salt?

Seed

Returns

number

Example

bucket("user-42", 16); // 11, the shard this user always lands in

Inherited from

Omit.bucket

---

bytes

bytes: (n) => Uint8Array

Defined in: src/global/numbers.ts:163

n random bytes.

Parameters

n

number

Returns

Uint8Array

Example

bytes(16); // Uint8Array(16) [ 57, 129, 123, ... ]

Inherited from

Omit.bytes

---

categorical

categorical: (weights) => number

Defined in: src/global/distributions.ts:289

An index in [0, weights.length), proportional to the weights.

Parameters

weights

ArrayLike<number>

Returns

number

Example

categorical([1, 3, 6]); // 2, most of the time

Inherited from

Omit.categorical

---

cauchy

cauchy: (location, scale) => number

Defined in: src/global/distributions.ts:125

One Cauchy draw. It has no mean, so expect extreme outliers.

Parameters

location?

number = 0

scale?

number = 1

Returns

number

Example

cauchy(); // -0.4142...  and occasionally something enormous

Inherited from

Omit.cauchy

---

chance

chance: (p) => boolean

Defined in: src/global/numbers.ts:102

true with probability p.

Parameters

p

number

Returns

boolean

Example

chance(0.25); // true a quarter of the time

Inherited from

Omit.chance

---

char

char: (options?) => string

Defined in: src/global/strings.ts:58

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

Parameters

options?

UnicodeOptions | CodePointSet

Returns

string

Example

char();                       // "符"
char({ blocks: "emoji" });    // an emoji
char({ blocks: ["hiragana", "katakana"] }); // "ネ"

Inherited from

Omit.char

---

chars

chars: (length, options?) => string

Defined in: src/global/strings.ts:74

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

An astral character costs two UTF-16 units, so chars(10) can return a string whose .length is more than ten. The count is of characters.

Parameters

length

number

options?

UnicodeOptions | CodePointSet

Returns

string

Example

chars(8, { blocks: "kana" }); // "へソむリあヴんケ"
chars(5, { blocks: "emoji" }).length; // 10, five astral characters

Inherited from

Omit.chars

---

chiSquared

chiSquared: (df) => number

Defined in: src/global/distributions.ts:89

One chi-squared draw with df degrees of freedom.

Parameters

df

number

Returns

number

Example

chiSquared(3); // 2.3661...

Inherited from

Omit.chiSquared

---

choices

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

Defined in: src/global/collections.ts:80

k elements with replacement, so k may exceed the collection size.

Type Parameters

T

T

Parameters

items

Collection<T>

k

number

Returns

T[]

Example

choices(["a", "b"], 5); // [ "b", "b", "a", "b", "a" ]

Inherited from

Omit.choices

---

codePoint

codePoint: (options?) => number

Defined in: src/global/strings.ts:44

A uniformly chosen Unicode code point. Defaults to the printable blocks.

Parameters

options?

UnicodeOptions | CodePointSet

Returns

number

Example

codePoint();                      // 12441
codePoint({ blocks: "hiragana" }); // 12395

Inherited from

Omit.codePoint

---

CodePointSet

CodePointSet: typeof CodePointSet

Defined in: src/namespace/index.ts:58

Inherited from

Omit.CodePointSet

---

coin

coin: () => "heads" | "tails"

Defined in: src/dice.ts:206

Heads or tails, for when a boolean would read worse at the call site.

Returns

"heads" | "tails"

Example

coin(); // "heads"

Inherited from

Omit.coin

---

color

color: (options) => string

Defined in: src/color.ts:147

A CSS colour string.

Hex by default. Opacity only appears when alpha was asked for, so the common case stays #rrggbb.

Parameters

options?

ColorOptions = {}

Returns

string

Example

color();                          // "#3e81d6"
color({ format: "rgb" });         // "rgb(62 129 214)"
color({ format: "hsl" });         // "hsl(214 62% 55%)"

color({ alpha: true });           // "#3e81d64f"  a random alpha
color({ alpha: 0.5 });            // "#3e81d680"  a fixed one
color({ format: "rgb", alpha: 0.4 }); // "rgb(62 129 214 / 0.4)"

// Constrain any channel to a value or an inclusive range.
color({ hue: [200, 240], saturation: 0.7, lightness: [0.3, 0.5] });

Inherited from

Omit.color

---

combination

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

Defined in: src/global/collections.ts:104

k distinct elements, kept in their original order.

Type Parameters

T

T

Parameters

items

Collection<T>

k

number

Returns

T[]

Example

combination([1, 2, 3, 4, 5], 3); // [ 1, 4, 5 ]

Inherited from

Omit.combination

---

d10

d10: (count?) => number

Defined in: src/dice.ts:165

A 10-sided die, or count of them summed.

Parameters

count?

number

Returns

number

Example

d10();  // 7
d10(2); // the sum of two

Inherited from

Omit.d10

---

d100

d100: (count?) => number

Defined in: src/dice.ts:196

A percentile die: 1 to 100.

Parameters

count?

number

Returns

number

Example

d100(); // 73

Inherited from

Omit.d100

---

d12

d12: (count?) => number

Defined in: src/dice.ts:175

A 12-sided die, or count of them summed.

Parameters

count?

number

Returns

number

Example

d12();  // 9
d12(2); // the sum of two

Inherited from

Omit.d12

---

d20

d20: (count?) => number

Defined in: src/dice.ts:187

A 20-sided die, or count of them summed.

The one a critical hit is measured against.

Parameters

count?

number

Returns

number

Example

d20();  // 17
d20(2); // the sum of two

Inherited from

Omit.d20

---

d4

d4: (count?) => number

Defined in: src/dice.ts:132

A four-sided die, or count of them summed.

Parameters

count?

number

Returns

number

Example

d4();   // 3
d6(3);  // 11, the sum of three d6
d20();  // 17

Inherited from

Omit.d4

---

d6

d6: (count?) => number

Defined in: src/dice.ts:145

A six-sided die, or count of them summed.

d4 through d100 are the same shape; reach for dice when the notation comes from data rather than from your own code.

Parameters

count?

number

Returns

number

Example

d6();  // 4
d6(3); // 11, the sum of three

Inherited from

Omit.d6

---

d8

d8: (count?) => number

Defined in: src/dice.ts:155

A 8-sided die, or count of them summed.

Parameters

count?

number

Returns

number

Example

d8();  // 5
d8(2); // the sum of two

Inherited from

Omit.d8

---

date

date: (from, to) => Date

Defined in: src/time.ts:24

A Date in [from, to).

Parameters

from

TimeInput

to

TimeInput

Returns

Date

Example

date(new Date("2020-01-01"), new Date("2030-01-01")); // 2026-08-23T09:12:44.019Z
date(0, Date.now());  // any moment since the epoch; numbers are epoch millis

Inherited from

Omit.date

---

default

default: RansuApi

Defined in: src/namespace/index.ts:90

Present so require('ransu').default also works.

---

dice

dice: DiceApi

Defined in: src/dice.ts:98

Roll dice written the way people already write them.

dice() gives the total; dice.detail() also reports what each die showed, for a log or an on-screen roll.

Example

dice("3d6");    // 11
dice("d20");    // 17
dice("2d10+3"); // 14
dice("1d4-1");  // 2

dice.detail("4d6+2"); // { total: 17, dice: [ 3, 6, 2, 4 ], modifier: 2 }

Inherited from

Omit.dice

---

dirichlet

dirichlet: (alpha) => number[]

Defined in: src/global/distributions.ts:262

One point on the simplex: values in (0, 1) that sum to 1.

Parameters

alpha

readonly number[]

Returns

number[]

Example

dirichlet([1, 1, 1]); // [ 0.24, 0.51, 0.25 ]

Inherited from

Omit.dirichlet

---

distributions

distributions: distribution

Defined in: src/namespace/index.ts:50

Inherited from

Omit.distributions

---

duration

duration: (min, max) => number

Defined in: src/time.ts:66

A duration in milliseconds, in [min, max).

Parameters

min

number

max

number

Returns

number

Example

duration(500, 2_000); // 1342

Inherited from

Omit.duration

---

engine

engine: () => Engine

Defined in: src/global/index.ts:5

The engine every top-level function currently draws from.

Returns

Engine

Example

engine().algorithm; // "Math.random" until you call seed()

Inherited from

Omit.engine

---

engines

engines: object

Defined in: src/namespace/index.ts:51

Every engine ransu ships, as seedable factories.

chacha20

chacha20: (seed?) => ChaCha20

ChaCha20 — a cryptographic stream cipher used as a generator.

The only engine that is both seedable and unpredictable: knowing any number of outputs does not reveal the rest. Use it when a stream must be reproducible and resistant to prediction; for secrets with no reproducibility requirement, ransu/secure is simpler.

Parameters

seed?

Seed

Returns

ChaCha20

Example

const source = chacha20(12345);
source.nextUint32(); // 1274611588

// Reproducible, unlike the platform CSPRNG.
chacha20(1).nextUint32() === chacha20(1).nextUint32(); // true

cryptoRandom

cryptoRandom: CryptoEngine

The platform CSPRNG, wrapped as an engine.

crypto.getRandomValues in browsers, workers and edge runtimes; node:crypto on Node. Unpredictable, and for that reason not seedable — which is what backs ransu/secure and the identifier functions.

Example

cryptoRandom.nextUint32(); // unpredictable
cryptoRandom.seedable;     // false

new Random(cryptoRandom).pick(["a", "b", "c"]);

mt19937

mt19937: typeof mt19937

mulberry32

mulberry32: (seed?) => Mulberry32

mulberry32 — 32 bits of state, a dozen lines of arithmetic.

The smallest engine here. Its 2^32 period is short enough to matter in a long run, so prefer it only where the state size is the constraint.

Parameters

seed?

Seed

Returns

Mulberry32

Example

const source = mulberry32(42);
source.nextUint32(); // 2744357186

nativeMath

nativeMath: NativeMathEngine

Math.random, wrapped as an engine.

Not seedable and not reproducible: the host owns the state. This is what the global functions draw from until you call seed().

Example

nativeMath.nextUint32();  // 2166136261
nativeMath.seedable;      // false

pcg32

pcg32: (seed?) => Pcg32

PCG32 — a 64-bit LCG whose output is permuted before it is returned.

Statistically excellent for its size, and it supports multiple independent streams from one seed.

Parameters

seed?

Seed

Returns

Pcg32

Example

const source = pcg32(42);
source.nextUint32(); // 2722782280

sfc32

sfc32: (seed?) => Sfc32

sfc32 — Small Fast Counting, 128 bits of state.

About as fast as anything here and very small. Chosen when speed matters more than a proven period.

Parameters

seed?

Seed

Returns

Sfc32

Example

const source = sfc32(42);
source.nextUint32(); // 261194151

xoshiro128pp

xoshiro128pp: (seed?) => Xoshiro128pp

xoshiro128++ — 128 bits of state, the default engine.

Fast, small, and passes BigCrush. Its period of 2^128-1 is far more than any single program will draw, but it is not cryptographic: a few outputs are enough to recover the state and predict the rest.

Parameters

seed?

Seed

Returns

Xoshiro128pp

Example

const source = xoshiro128pp(42);
source.nextUint32(); // 167929222

new Random(source).integer(1, 6); // 3

xoshiro256pp

xoshiro256pp: (seed?) => Xoshiro256pp

xoshiro256++ — 256 bits of state.

The same family as xoshiro128pp with a longer period, and the one to pick when you need jump() to hand disjoint streams to parallel workers.

Parameters

seed?

Seed

Returns

Xoshiro256pp

Example

const source = xoshiro256pp(42);
source.nextUint32(); // 1573169414

// Non-overlapping streams for parallel work.
const [a, b, c] = source.split(3);

Example

// Pick one for a Random, or for the global stream.
new Random(42, { engine: engines.pcg32 });

// Or build one directly and hand it around.
const source = engines.xoshiro256pp(42);
source.nextUint32(); // 1573169414

engines.mt19937(42);     // for reproducing another language's stream
engines.chacha20(42);    // cryptographic, and still reproducible
engines.cryptoRandom;    // the platform CSPRNG, not seedable
engines.nativeMath;      // Math.random, not seedable

Inherited from

Omit.engines

---

exponential

exponential: (rate) => number

Defined in: src/global/distributions.ts:38

One exponential draw: the wait until the next event.

Parameters

rate?

number = 1

Returns

number

Example

exponential();    // 0.6931...  rate 1
exponential(0.5); // 3.2188...  the mean is 1 / rate

Inherited from

Omit.exponential

---

fillBytes

fillBytes: (out) => void

Defined in: src/global/numbers.ts:176

Fill an existing buffer, with no allocation.

Parameters

out

Uint8Array

Returns

void

Example

const buffer = new Uint8Array(32);
fillBytes(buffer);

Inherited from

Omit.fillBytes

---

fisherF

fisherF: (d1, d2) => number

Defined in: src/global/distributions.ts:113

One F draw, the ratio of two chi-squared variables.

Parameters

d1

number

d2

number

Returns

number

Example

fisherF(3, 10); // 1.1274...

Inherited from

Omit.fisherF

---

float

float: (min?, max?) => number

Defined in: src/global/numbers.ts:26

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

Parameters

min?

number

max?

number

Returns

number

Example

float();          // 0.3964157...
float(10);        // 6.2831853...  one argument is the upper bound
float(-1.5, 1.5); // 0.4142135...

Inherited from

Omit.float

---

floats

floats: (n) => Float64Array

Defined in: src/global/numbers.ts:188

n doubles in [0, 1).

Parameters

n

number

Returns

Float64Array

Example

floats(1_000); // Float64Array(1000) [ 0.396..., 0.364..., ... ]

Inherited from

Omit.floats

---

futureDate

futureDate: (days) => Date

Defined in: src/time.ts:53

A Date within the next days (default 7).

Parameters

days?

number = 7

Returns

Date

Example

futureDate(30); // some time in the next month

Inherited from

Omit.futureDate

---

gamma

gamma: (shape, scale) => number

Defined in: src/global/distributions.ts:52

One gamma draw.

Parameters

shape

number

scale?

number = 1

Returns

number

Example

gamma(2);     // 1.4726...
gamma(2, 10); // 14.726...   shape 2, scale 10

Inherited from

Omit.gamma

---

geometric

geometric: (p) => number

Defined in: src/global/distributions.ts:326

The trial on which the first success lands, counting from 1.

Parameters

p

number

Returns

number

Example

geometric(0.1); // 7

Inherited from

Omit.geometric

---

getState

getState: () => EngineState

Defined in: src/global/index.ts:5

A JSON-serialisable snapshot of the global stream.

Returns

EngineState

Example

seed(1);
const saved = getState();
const first = random();
setState(saved);
random() === first; // true

Inherited from

Omit.getState

---

graphemes

graphemes: (value, locale?) => string[]

Defined in: src/namespace/index.ts:46

A random string of count grapheme clusters — what a reader calls “characters”.

A flag or an emoji with a skin-tone modifier is several code points that display as one glyph. chars counts code points and would split them; this counts what you see.

Parameters

value

string

locale?

string

Returns

string[]

Example

graphemes(3); // three visible characters, whatever they cost in code points

Inherited from

Omit.graphemes

---

gumbel

gumbel: (location, scale) => number

Defined in: src/global/distributions.ts:161

One Gumbel draw: the distribution of a maximum.

Parameters

location?

number = 0

scale?

number = 1

Returns

number

Example

gumbel(); // 0.4759...

Inherited from

Omit.gumbel

---

hashFloat

hashFloat: (key, salt?) => number

Defined in: src/hash.ts:39

A stable double in [0, 1) for key.

Parameters

key

Seed

salt?

Seed

Returns

number

Example

hashFloat("user-42");                 // 0.6031...  always this value
hashFloat("user-42", "experiment-b"); // 0.1187...  a different salt, a different answer

Inherited from

Omit.hashFloat

---

hashInteger

hashInteger: (key, min, max, salt?) => number

Defined in: src/hash.ts:51

A stable integer in [min, max] for key.

Parameters

key

Seed

min

number

max

number

salt?

Seed

Returns

number

Example

hashInteger("user-42", 1, 6); // 3, on every machine and every run

Inherited from

Omit.hashInteger

---

hashPick

hashPick: <T>(key, items, salt?) => T

Defined in: src/hash.ts:68

A stable choice from items for key.

Type Parameters

T

T

Parameters

key

Seed

items

Collection<T>

salt?

Seed

Returns

T

Example

hashPick("user-42", ["control", "blue", "green"]); // "blue"

Inherited from

Omit.hashPick

---

hashRandom

hashRandom: (key, salt?) => Random

Defined in: src/hash.ts:111

A whole Random seeded from key, when one value is not enough.

Parameters

key

Seed

salt?

Seed

Returns

Random

Example

const rng = hashRandom("user-42");
rng.integer(1, 6);            // 5
rng.pick(["red", "blue"]);    // "blue"
// Same key, same sequence, in any process.

Inherited from

Omit.hashRandom

---

hex

hex: (length) => string

Defined in: src/global/strings.ts:31

A random lowercase hexadecimal string.

Parameters

length

number

Returns

string

Example

hex(32); // "3f7a1c05e2b8..."

Inherited from

Omit.hex

---

hsl

hsl: (options) => [number, number, number, number]

Defined in: src/color.ts:68

[hue, saturation, lightness, alpha], with hue in degrees.

Alpha is 1 unless you ask for it, so the tuple is always four long.

Parameters

options?

ColorOptions = {}

Returns

[number, number, number, number]

Example

hsl();                              // [ 214, 0.62, 0.55, 1 ]
hsl({ hue: [200, 240] });           // blues only
hsl({ saturation: 0.8, lightness: [0.4, 0.6] });

Inherited from

Omit.hsl

---

hypergeometric

hypergeometric: (population, successes, draws) => number

Defined in: src/global/distributions.ts:350

Successes when drawing without replacement from a finite pool.

Parameters

population

number

successes

number

draws

number

Returns

number

Example

hypergeometric(50, 5, 10); // 1, drawing 10 from 50 that hold 5

Inherited from

Omit.hypergeometric

---

inCircle

inCircle: (radius) => Point

Defined in: src/geometry.ts:77

A uniform point inside a disc.

The square root matters: without it, points bunch up at the centre, because the area at radius r grows with r.

Parameters

radius?

number = 1

Returns

Point

Example

inCircle(50); // [ 12.4, -31.8 ]   evenly spread over the disc

Inherited from

Omit.inCircle

---

inRect

inRect: (rect) => Point

Defined in: src/geometry.ts:124

A uniform point inside a rectangle.

Parameters

rect

Rect

Returns

Point

Example

inRect({ x: 0, y: 0, width: 1920, height: 1080 }); // [ 842.1, 219.7 ]

Inherited from

Omit.inRect

---

inSphere

inSphere: (radius, dimensions) => Point

Defined in: src/geometry.ts:108

A uniform point inside a ball, by volume.

Parameters

radius?

number = 1

dimensions?

number = 3

Returns

Point

Example

inSphere(10); // [ 3.1, -5.7, 1.2 ]

Inherited from

Omit.inSphere

---

integer

integer: (min, max) => number

Defined in: src/global/numbers.ts:39

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

Parameters

min

number

max

number

Returns

number

Example

integer(1, 6);      // 4
integer(-10, 10);   // -3

Inherited from

Omit.integer

---

integers

integers: (n, min, max) => Float64Array

Defined in: src/global/numbers.ts:200

n integers in [min, max], with the bounds validated once.

Parameters

n

number

min

number

max

number

Returns

Float64Array

Example

integers(1_000, 1, 6); // Float64Array(1000) [ 3, 5, 3, 1, ... ]

Inherited from

Omit.integers

---

irwinHall

irwinHall: (n) => number

Defined in: src/global/distributions.ts:223

One draw: the sum of n uniforms.

Parameters

n

number

Returns

number

Example

irwinHall(12); // 6.1284...  a cheap normal approximation

Inherited from

Omit.irwinHall

---

jitter

jitter: (base, factor) => number

Defined in: src/time.ts:83

Spread a value by +/- factor so that things scheduled together stop arriving together. jitter(1000, 0.1) lands in [900, 1100).

Parameters

base

number

factor?

number = 0.1

Returns

number

Example

jitter(1_000);       // 964.27...   within 10%
jitter(1_000, 0.5);  // 1387.51...  within 50%

Inherited from

Omit.jitter

---

laplace

laplace: (location, scale) => number

Defined in: src/global/distributions.ts:137

One Laplace draw: two exponential tails back to back.

Parameters

location?

number = 0

scale?

number = 1

Returns

number

Example

laplace(0, 1); // 0.3819...

Inherited from

Omit.laplace

---

logistic

logistic: (location, scale) => number

Defined in: src/global/distributions.ts:149

One logistic draw, the distribution behind the sigmoid.

Parameters

location?

number = 0

scale?

number = 1

Returns

number

Example

logistic(); // -0.2231...

Inherited from

Omit.logistic

---

logNormal

logNormal: (mu, sigma) => number

Defined in: src/global/distributions.ts:65

One log-normal draw: a normal variable exponentiated.

Parameters

mu?

number = 0

sigma?

number = 1

Returns

number

Example

logNormal();       // 1.6221...
logNormal(0, 0.5); // 1.2840...

Inherited from

Omit.logNormal

---

multinomial

multinomial: (n, weights) => number[]

Defined in: src/global/distributions.ts:380

Counts per category, summing to n.

Parameters

n

number

weights

ArrayLike<number>

Returns

number[]

Example

multinomial(100, [1, 3, 6]); // [ 9, 31, 60 ]

Inherited from

Omit.multinomial

---

nanoid

nanoid: (size, options) => string

Defined in: src/namespace/index.ts:40

A nanoid: 21 URL-safe characters by default. Drop-in for the nanoid package.

Parameters

size?

number = 21

options?

NanoidOptions = {}

Returns

string

Example

nanoid();    // "V1StGXR8_Z5jdHi6B-myT"
nanoid(10);  // "IRFa-VaY2b"
nanoid(12, { alphabet: "0123456789abcdef" }); // "3f7a1c05e2b8"

Inherited from

Omit.nanoid

---

negativeBinomial

negativeBinomial: (r, p) => number

Defined in: src/global/distributions.ts:338

The number of failures before the r-th success.

Parameters

r

number

p

number

Returns

number

Example

negativeBinomial(3, 0.5); // 4

Inherited from

Omit.negativeBinomial

---

normal

normal: (mean, sd) => number

Defined in: src/global/distributions.ts:24

One Gaussian draw.

Parameters

mean?

number = 0

sd?

number = 1

Returns

number

Example

normal();        // 0.4837...   mean 0, sd 1
normal(100, 15); // 92.61...    an IQ-shaped draw

Inherited from

Omit.normal

---

onCircle

onCircle: (radius) => Point

Defined in: src/geometry.ts:60

A uniform point on the circumference of a circle.

Parameters

radius?

number = 1

Returns

Point

Example

onCircle(100); // [ -70.7, 70.7 ]   always exactly 100 from the origin

Inherited from

Omit.onCircle

---

oneIn

oneIn: (n) => boolean

Defined in: src/global/numbers.ts:114

true with probability 1 / n.

Parameters

n

number

Returns

boolean

Example

oneIn(20); // a critical hit on a d20

Inherited from

Omit.oneIn

---

onSphere

onSphere: (radius, dimensions) => Point

Defined in: src/geometry.ts:94

A uniform point on the surface of a sphere.

Parameters

radius?

number = 1

dimensions?

number = 3

Returns

Point

Example

onSphere(1);    // [ 0.267, -0.534, 0.801 ]
onSphere(2, 4); // a point on a 4-dimensional sphere of radius 2

Inherited from

Omit.onSphere

---

otp

otp: (digits, options) => string

Defined in: src/namespace/index.ts:43

A numeric one-time code. Leading zeros are preserved.

Parameters

digits?

number = 6

options?

TokenOptions = {}

Returns

string

Example

otp();   // "047215"  six digits, leading zero kept
otp(8);  // "90114862"

Inherited from

Omit.otp

---

pareto

pareto: (shape, scale) => number

Defined in: src/global/distributions.ts:173

One Pareto draw: the heavy-tailed shape behind the 80/20 rule.

Parameters

shape

number

scale?

number = 1

Returns

number

Example

pareto(1.16); // 1.8721...  scale 1 by default

Inherited from

Omit.pareto

---

password

password: (length, options) => string

Defined in: src/namespace/index.ts:44

A random password. With requireEach the result holds at least one character from every enabled class, then gets shuffled so their positions are random.

Parameters

length?

number = 16

options?

PasswordOptions = {}

Returns

string

Example

password();            // "vK8mQ2xL9pT4nR7c"
password(24, { symbols: true, requireEach: true });
password(12, { uppercase: false, symbols: false });

Inherited from

Omit.password

---

pastDate

pastDate: (days) => Date

Defined in: src/time.ts:40

A Date within the last days (default 7).

Parameters

days?

number = 7

Returns

Date

Example

pastDate();    // some time in the last week
pastDate(365); // some time in the last year

Inherited from

Omit.pastDate

---

permutation

permutation: (n) => number[]

Defined in: src/global/collections.ts:172

A shuffled [0, n), for permuting something you index yourself.

Parameters

n

number

Returns

number[]

Example

permutation(5); // [ 3, 0, 4, 1, 2 ]

Inherited from

Omit.permutation

---

pick

pick: <T>(items) => T

Defined in: src/global/collections.ts:15

One element. Throws when the collection is empty.

Type Parameters

T

T

Parameters

items

Collection<T>

Returns

T

Example

pick(["rock", "paper", "scissors"]); // "paper"
pick("abcdef");                      // "d"
pick(new Set([1, 2, 3]));            // 2

Inherited from

Omit.pick

---

pickEntry

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

Defined in: src/global/collections.ts:66

One [key, value] pair 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

[K, V]

Example

pickEntry({ a: 1, b: 2 }); // [ "b", 2 ]

Inherited from

Omit.pickEntry

---

pickIndex

pickIndex: <T>(items) => number

Defined in: src/global/collections.ts:40

The index of one element, rather than the element itself.

Type Parameters

T

T

Parameters

items

Collection<T>

Returns

number

Example

pickIndex(["a", "b", "c"]); // 2

Inherited from

Omit.pickIndex

---

pickKey

pickKey: <K, V>(target) => K

Defined in: src/global/collections.ts:52

One key 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

K

Example

pickKey({ small: 1, medium: 2, large: 3 }); // "medium"

Inherited from

Omit.pickKey

---

pickValue

pickValue: <K, V>(target) => V

Defined in: src/global/collections.ts:249

A uniformly chosen 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

Example

pickValue({ a: 1, b: 2, c: 3 }); // 3

Inherited from

Omit.pickValue

---

poisson

poisson: (lambda) => number

Defined in: src/global/distributions.ts:313

The number of events in one interval, given a mean rate.

Parameters

lambda

number

Returns

number

Example

poisson(4); // 3

Inherited from

Omit.poisson

---

random

random: () => number

Defined in: src/global/numbers.ts:12

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

Returns

number

Example

random(); // 0.7401962...

Inherited from

Omit.random

---

Random

Random: typeof Random

Defined in: src/namespace/index.ts:54

Inherited from

Omit.Random

---

range

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

Defined in: src/global/numbers.ts:66

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

Parameters

start

number

stop?

number

step?

number

Returns

number

Example

range(10);         // 7      one argument is the upper bound
range(5, 10);      // 8
range(0, 100, 5);  // 45     multiples of five only

Inherited from

Omit.range

---

RansuError

RansuError: typeof RansuError

Defined in: src/namespace/index.ts:56

Inherited from

Omit.RansuError

---

rayleigh

rayleigh: (scale) => number

Defined in: src/global/distributions.ts:198

One Rayleigh draw: the length of a 2D Gaussian vector.

Parameters

scale?

number = 1

Returns

number

Example

rayleigh(); // 1.1774...

Inherited from

Omit.rayleigh

---

reservoir

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

Defined in: src/global/collections.ts:122

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

Type Parameters

T

T

Parameters

items

Iterable<T>

k

number

Returns

T[]

Example

function* lines() {
  yield "first";
  yield "second";
  yield "third";
}
// Nothing is buffered, so the source may be far larger than memory.
reservoir(lines(), 2); // [ "third", "first" ]

Inherited from

Omit.reservoir

---

rgb

rgb: (options) => [number, number, number, number]

Defined in: src/color.ts:115

[red, green, blue, alpha], channels 0 to 255 and alpha 0 to 1.

Parameters

options?

ColorOptions = {}

Returns

[number, number, number, number]

Example

rgb();                        // [ 62, 129, 214, 1 ]
rgb({ alpha: [0.2, 0.8] });   // [ 200, 41, 96, 0.57 ]

Inherited from

Omit.rgb

---

rollout

rollout: (key, percent, salt?) => boolean

Defined in: src/hash.ts:95

Whether key falls inside a percent rollout, where percent is a fraction in [0, 1]. Growing the percentage only ever adds keys, never moves one out.

Parameters

key

Seed

percent

number

salt?

Seed

Returns

boolean

Example

rollout("user-42", 0.1);  // false, not in the first 10%
rollout("user-42", 0.5);  // true, and it stays true as the rollout widens

Inherited from

Omit.rollout

---

sample

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

Defined in: src/global/collections.ts:92

k distinct elements, in random order.

Type Parameters

T

T

Parameters

items

Collection<T>

k

number

Returns

T[]

Example

sample([1, 2, 3, 4, 5], 3); // [ 4, 1, 5 ]

Inherited from

Omit.sample

---

sampleIntegers

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

Defined in: src/global/numbers.ts:227

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

Parameters

count

number

min

number

max

number

Returns

number[]

Example

sampleIntegers(6, 1, 49);          // [ 12, 3, 41, 28, 7, 33 ]
sampleIntegers(3, 0, 1_000_000_000); // fine: the range is never built

Inherited from

Omit.sampleIntegers

---

seed

seed: (value) => void

Defined in: src/global/index.ts:5

Make every top-level function deterministic from here on.

Parameters

value

Seed

Returns

void

Example

seed(42);
integer(1, 6); // 3
seed(42);
integer(1, 6); // 3 again

Inherited from

Omit.seed

---

SeedSequence

SeedSequence: typeof SeedSequence

Defined in: src/namespace/index.ts:55

Inherited from

Omit.SeedSequence

---

setState

setState: (state) => void

Defined in: src/global/index.ts:5

Rewind or fast-forward the global stream to a saved snapshot.

Parameters

state

EngineState

Returns

void

Example

seed(1);
setState(getState()); // a no-op, but this is the shape

Inherited from

Omit.setState

---

shuffle

shuffle: <T>(items) => T[]

Defined in: src/global/collections.ts:147

A shuffled copy. The input is untouched.

Type Parameters

T

T

Parameters

items

Collection<T>

Returns

T[]

Example

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

Inherited from

Omit.shuffle

---

shuffleInPlace

shuffleInPlace: <T>(items) => T[]

Defined in: src/global/collections.ts:160

Fisher–Yates in place: the only mutating shuffle.

Type Parameters

T

T

Parameters

items

T[]

Returns

T[]

Example

const deck = [1, 2, 3, 4, 5];
shuffleInPlace(deck); // deck itself is reordered and returned

Inherited from

Omit.shuffleInPlace

---

shuffleString

shuffleString: (value) => string

Defined in: src/global/collections.ts:184

The characters of a string in random order, by code point.

Parameters

value

string

Returns

string

Example

shuffleString("ransu"); // "nusar"

Inherited from

Omit.shuffleString

---

sign

sign: () => number

Defined in: src/global/numbers.ts:126

-1 or 1.

Returns

number

Example

sign() * 5; // -5

Inherited from

Omit.sign

---

stream

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

Defined in: src/global/numbers.ts:214

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

Returns

Generator<number, never, unknown>

Example

for (const value of stream()) {
  if (value > 0.99) break;
}

Inherited from

Omit.stream

---

string

string: (length, alphabet?) => string

Defined in: src/global/strings.ts:16

A random string over alphabet (default alphanumeric).

Parameters

length

number

alphabet?

string | ArrayLike<string>

Returns

string

Example

string(12);                 // "yYwec14FcPKc"
string(6, "ABCDEF0123456789"); // "3E9A1C"
string(4, ["cat", "dog"]);  // "dogcatdogdog"

Inherited from

Omit.string

---

studentT

studentT: (df) => number

Defined in: src/global/distributions.ts:101

One Student’s t draw: a normal with heavier tails.

Parameters

df

number

Returns

number

Example

studentT(5); // -0.8412...

Inherited from

Omit.studentT

---

subset

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

Defined in: src/global/collections.ts:266

Each element kept independently with probability p.

The result has no fixed length: it is a coin flip per element, so the size varies around items.length * p. Order is preserved.

Type Parameters

T

T

Parameters

items

Collection<T>

p

number

Returns

T[]

Example

subset([1, 2, 3, 4, 5, 6], 0.5); // [ 1, 4, 5 ]

Inherited from

Omit.subset

---

takeOut

takeOut: <T>(items) => T

Defined in: src/global/collections.ts:135

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

Type Parameters

T

T

Parameters

items

T[]

Returns

T

Example

const deck = ["A", "K", "Q", "J"];
takeOut(deck); // "Q", and deck is now [ "A", "K", "J" ]

Inherited from

Omit.takeOut

---

token

token: (bytes, options) => string

Defined in: src/namespace/index.ts:42

A URL-safe secret token with bytes bytes of entropy. CSPRNG-backed.

Parameters

bytes?

number = 32

options?

TokenOptions = {}

Returns

string

Example

token();    // "xK3n_9QpZ..."  32 bytes as base64url
token(16);  // shorter, still from the platform CSPRNG

Inherited from

Omit.token

---

triangular

triangular: (min, max, mode?) => number

Defined in: src/global/distributions.ts:211

One draw from a triangle, with an optional peak.

Parameters

min

number

max

number

mode?

number

Returns

number

Example

triangular(0, 10);    // 4.7213...  peak at the midpoint
triangular(0, 10, 9); // 7.8102...  peak at 9

Inherited from

Omit.triangular

---

tryPick

tryPick: <T>(items) => T | undefined

Defined in: src/global/collections.ts:28

One element, or undefined when the collection is empty.

Type Parameters

T

T

Parameters

items

Collection<T>

Returns

T | undefined

Example

tryPick([]);           // undefined
tryPick(["a", "b"]);   // "a"

Inherited from

Omit.tryPick

---

ulid

ulid: UlidApi

Defined in: src/namespace/index.ts:41

A ULID: 26 characters of Crockford base32, time-ordered.

48 bits of millisecond timestamp then 80 bits of randomness, encoded so that lexicographic order is time order. Shorter than a UUID and case-insensitive, with no dashes to strip.

Example

const id = ulid(); // "01K39XQZP4W8YHN2VBTKD7A3RM"
ulid.timestamp(id); // 1756890764019

// Sorts in creation order as a plain string.
ulid() < ulid(); // true

Inherited from

Omit.ulid

---

unicodeRanges

unicodeRanges: object

Defined in: src/namespace/index.ts:47

The named Unicode blocks the string functions accept.

all

readonly all: readonly [readonly [0, 1114111]]

arabic

readonly arabic: readonly [readonly [1536, 1791]]

arrows

readonly arrows: readonly CodePointRange[] = ARROWS

ascii

readonly ascii: readonly CodePointRange[] = ASCII

blockElements

readonly blockElements: readonly CodePointRange[] = BLOCKS

bmp

readonly bmp: readonly [readonly [0, 65535]]

box

readonly box: readonly CodePointRange[] = BOX

braille

readonly braille: readonly CodePointRange[] = BRAILLE

cjk

readonly cjk: readonly CodePointRange[]

currency

readonly currency: readonly CodePointRange[] = CURRENCY

cyrillic

readonly cyrillic: readonly CodePointRange[] = CYRILLIC

devanagari

readonly devanagari: readonly [readonly [2304, 2431]]

emoji

readonly emoji: readonly CodePointRange[] = EMOJI

geometric

readonly geometric: readonly CodePointRange[] = GEOMETRIC

greek

readonly greek: readonly CodePointRange[] = GREEK

hangul

readonly hangul: readonly CodePointRange[] = HANGUL

hebrew

readonly hebrew: readonly [readonly [1424, 1535]]

hiragana

readonly hiragana: readonly CodePointRange[] = HIRAGANA

kana

readonly kana: readonly CodePointRange[]

kanji

readonly kanji: readonly CodePointRange[] = KANJI

katakana

readonly katakana: readonly CodePointRange[] = KATAKANA

latin

readonly latin: readonly CodePointRange[] = LATIN

latin1

readonly latin1: readonly [readonly [32, 126], readonly [160, 255]]

latinExtended

readonly latinExtended: readonly [readonly [256, 591]]

math

readonly math: readonly CodePointRange[] = MATH

printable

readonly printable: readonly CodePointRange[]

punctuation

readonly punctuation: readonly CodePointRange[] = PUNCTUATION

symbols

readonly symbols: readonly CodePointRange[]

thai

readonly thai: readonly [readonly [3584, 3711]]

Example

import { char, unicodeRanges } from "ransu";

Object.keys(unicodeRanges); // "printable", "latin", "hiragana", ...

char({ blocks: "hiragana" });
char({ blocks: ["hiragana", "katakana"] });

Inherited from

Omit.unicodeRanges

---

unitVector

unitVector: (dimensions) => Point

Defined in: src/geometry.ts:30

A uniform direction in dimensions dimensions, as a unit vector.

Normalised Gaussians, which is the only construction that stays uniform on the sphere in every dimension. Picking each coordinate uniformly and normalising concentrates points toward the corners of the cube.

Parameters

dimensions?

number = 2

Returns

Point

Example

unitVector();  // [ -0.6018, 0.7986 ]   length 1
unitVector(3); // [ 0.2673, -0.5345, 0.8018 ]

Inherited from

Omit.unitVector

---

uuid

uuid: UuidApi

Defined in: src/namespace/index.ts:39

A UUID, in every version RFC 9562 defines.

Calling it gives a v4; every version and helper hangs off it. Names and argument order match the uuid package, so it is a drop-in for that.

Example

uuid();    // "39817b65-27b9-45d0-9b51-315d530a3211"  a v4
uuid.v4(); // the same thing, spelled out

// Time-ordered, so it sorts by creation time in a database index.
uuid.v7(); // "0198f2a4-1c05-7e2b-8f31-9d4a7c0e15b3"

// Name-based: the same name always gives the same UUID.
uuid.v5("example.com", uuid.NAMESPACE.DNS);

uuid.validate(uuid());     // true
uuid.version(uuid.v7());   // 7
uuid.timestamp(uuid.v7()); // 1756890764019

uuid.NIL; // "00000000-0000-0000-0000-000000000000"
uuid.MAX; // "ffffffff-ffff-ffff-ffff-ffffffffffff"

Inherited from

Omit.uuid

---

vonMises

vonMises: (mu, kappa) => number

Defined in: src/global/distributions.ts:249

One angle in (-pi, pi]. The circular analogue of a normal.

Parameters

mu?

number = 0

kappa?

number = 1

Returns

number

Example

vonMises();      // 0.3218...
vonMises(0, 10); // 0.0782...  a larger kappa concentrates near mu

Inherited from

Omit.vonMises

---

weibull

weibull: (shape, scale) => number

Defined in: src/global/distributions.ts:186

One Weibull draw, used for time until failure.

Parameters

shape

number

scale?

number = 1

Returns

number

Example

weibull(1.5);      // 0.7943...
weibull(1.5, 100); // 79.43...

Inherited from

Omit.weibull

---

weightedPick

weightedPick: <T>(items, weights) => T

Defined in: src/global/collections.ts:197

One element, with probability proportional to its weight.

Type Parameters

T

T

Parameters

items

Collection<T>

weights

ArrayLike<number>

Returns

T

Example

// "common" ten times as often as "rare".
weightedPick(["common", "rare"], [10, 1]); // "common"

Inherited from

Omit.weightedPick

---

weightedSample

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

Defined in: src/global/collections.ts:212

k distinct elements, drawn in proportion to their weights.

Type Parameters

T

T

Parameters

items

Collection<T>

weights

ArrayLike<number>

k

number

Returns

T[]

Example

weightedSample(["a", "b", "c"], [1, 3, 6], 2); // [ "c", "b" ]

Inherited from

Omit.weightedSample

---

weightedTable

weightedTable: <T>(items, weights) => object

Defined in: src/global/collections.ts:233

A reusable weighted sampler, O(1) per draw.

Build one when the same weights are drawn from repeatedly; weightedPick is a linear scan and is the better choice for a one-off.

Type Parameters

T

T

Parameters

items

Collection<T>

weights

ArrayLike<number>

Returns

object

pick()

pick(): T

Returns

T

Example

const loot = weightedTable(["common", "rare", "epic"], [90, 9, 1]);
loot.pick(); // "common"
loot.pick(); // "common"

Inherited from

Omit.weightedTable

---

zipf

zipf: (s, n) => number

Defined in: src/global/distributions.ts:367

A rank in 1..n, following the power law behind word frequency.

Parameters

s

number

n

number

Returns

number

Example

zipf(1.2, 1000); // 3

Inherited from

Omit.zipf

Methods

clone()

clone(): Random

Defined in: src/namespace/index.ts:61

An independent copy of the global stream, positioned where it is now.

Returns

Random

Inherited from

Omit.clone

---

split()

split(n): Random[]

Defined in: src/namespace/index.ts:73

n independent generators derived from the global stream.

Parameters

n

number

Returns

Random[]

Inherited from

Omit.split