skills/plugins/document-navigator/docs/foundation/random/random/README.md

@suaveplan/random - High-level CSPRNG-backed randomness: strings, UUID/ULID/Nanoid, collections, objects, game primitives, and a full statistical-distribution suite

Summary

High-level cryptographically secure randomness for application use. This is the everyday random package — it wraps the CSPRNG with ergonomic helpers for every common randomness task: unique IDs (randomUUID v4, randomUUIDv7, randomULID, randomNanoid), random strings with eight charset presets, collection utilities (shuffle, choice, sample, weightedChoice), object utilities (randomKey, randomEntry, randomSubset), game primitives (coin, dice, roll), and a full suite of continuous and discrete statistical distributions (Normal, LogNormal, Binomial, Poisson, and eight more). Every function accepts an optional rng?: Rng — omit it for crypto-backed defaults, or pass a SeededRng from @suaveplan/pseudo-random for deterministic tests. Do not confuse with @suaveplan/pseudo-random (seeded, deterministic, for procedural generation) or @suaveplan/crypto (raw cryptographic byte generation).

Documentation tree

• collections — (no submodules)
  • collections — (no submodules)
• continuous — (no submodules)
  • continuous — (no submodules)
• discrete — (no submodules)
  • discrete — (no submodules)
• sampler — (no submodules)
  • sampler — (no submodules)
• errors — (no submodules)
  • random-error — (no submodules)
• game — (no submodules)
  • dice — (no submodules)
• nanoid — The nanoid module implements the Nano ID scheme: a configurable-length, URL-safe random string using a 64-character a…
• ulid — The ulid module implements the Universally Unique Lexicographically Sortable Identifier per the original Alizain Feer…
• uuid — The uuid module produces RFC 9562-compliant UUIDv4 and UUIDv7 identifiers. UUIDv4 is 122 bits of pure randomness with…
• random-float — The random-float module produces a uniformly distributed double in a user-specified half-open interval [min, max).…
• random-int — The random-int module provides an unbiased, inclusive-range integer sampler. Unlike the common `Math.floor(Math.rando…
• objects — (no submodules)
  • objects — (no submodules)
• crypto-rng — The crypto-rng module is the single authoritative binding between @suaveplan/random and the platform's cryptographi…
• default-rng — The default-rng module holds the process-wide default Rng that every helper in @suaveplan/random falls back to wh…
• strings — (no submodules)
  • random-string — (no submodules)

- [collections](./src/collections/collections.md) — _(no submodules)_- [continuous](./src/distributions/continuous/continuous.md) — _(no submodules)_- [continuous](./src/distributions/continuous/continuous.md) — _(no submodules)_- [discrete](./src/distributions/discrete/discrete.md) — _(no submodules)_- [discrete](./src/distributions/discrete/discrete.md) — _(no submodules)_- [sampler](./src/distributions/sampler/sampler.md) — _(no submodules)_- [sampler](./src/distributions/sampler/sampler.md) — _(no submodules)_- [errors](./src/errors/random-error.md) — _(no submodules)_- [random-error](./src/errors/random-error.md) — _(no submodules)_- [game](./src/game/dice.md) — _(no submodules)_- [dice](./src/game/dice.md) — _(no submodules)_- [nanoid](./src/ids/nanoid.md) — The `nanoid` module implements the Nano ID scheme: a configurable-length, URL-safe random string using a 64-character a…

• ulid — The ulid module implements the Universally Unique Lexicographically Sortable Identifier per the original Alizain Feer…
• uuid — The uuid module produces RFC 9562-compliant UUIDv4 and UUIDv7 identifiers. UUIDv4 is 122 bits of pure randomness with…
• random-float — The random-float module produces a uniformly distributed double in a user-specified half-open interval [min, max).…
• random-int — The random-int module provides an unbiased, inclusive-range integer sampler. Unlike the common `Math.floor(Math.rando…
• objects — (no submodules)- objects — (no submodules)- crypto-rng — The crypto-rng module is the single authoritative binding between @suaveplan/random and the platform's cryptographi…
• default-rng — The default-rng module holds the process-wide default Rng that every helper in @suaveplan/random falls back to wh…
• strings — (no submodules)- random-string — (no submodules)- collections — (no submodules)- continuous — (no submodules)- continuous — (no submodules)- discrete — (no submodules)- discrete — (no submodules)- sampler — (no submodules)- sampler — (no submodules)- errors — (no submodules)- random-error — (no submodules)- game — (no submodules)- dice — (no submodules)- nanoid — The nanoid module implements the Nano ID scheme: a configurable-length, URL-safe random string using a 64-character a…
• ulid — The ulid module implements the Universally Unique Lexicographically Sortable Identifier per the original Alizain Feer…
• uuid — The uuid module produces RFC 9562-compliant UUIDv4 and UUIDv7 identifiers. UUIDv4 is 122 bits of pure randomness with…
• random-float — The random-float module produces a uniformly distributed double in a user-specified half-open interval [min, max).…
• random-int — The random-int module provides an unbiased, inclusive-range integer sampler. Unlike the common `Math.floor(Math.rando…
• objects — (no submodules)- objects — (no submodules)- crypto-rng — The crypto-rng module is the single authoritative binding between @suaveplan/random and the platform's cryptographi…
• default-rng — The default-rng module holds the process-wide default Rng that every helper in @suaveplan/random falls back to wh…
• strings — (no submodules)- random-string — (no submodules)- collections — (no submodules)- continuous — (no submodules)- continuous — (no submodules)- discrete — (no submodules)- discrete — (no submodules)- sampler — (no submodules)- sampler — (no submodules)- errors — (no submodules)- random-error — (no submodules)- game — (no submodules)- dice — (no submodules)- nanoid — The nanoid module implements the Nano ID scheme: a configurable-length, URL-safe random string using a 64-character a…
• ulid — The ulid module implements the Universally Unique Lexicographically Sortable Identifier per the original Alizain Feer…
• uuid — The uuid module produces RFC 9562-compliant UUIDv4 and UUIDv7 identifiers. UUIDv4 is 122 bits of pure randomness with…
• random-float — The random-float module produces a uniformly distributed double in a user-specified half-open interval [min, max).…
• random-int — The random-int module provides an unbiased, inclusive-range integer sampler. Unlike the common `Math.floor(Math.rando…
• objects — (no submodules)- objects — (no submodules)- crypto-rng — The crypto-rng module is the single authoritative binding between @suaveplan/random and the platform's cryptographi…
• default-rng — The default-rng module holds the process-wide default Rng that every helper in @suaveplan/random falls back to wh…
• strings — (no submodules)- random-string — (no submodules)- collections — (no submodules)- continuous — (no submodules) - continuous — (no submodules)- discrete — (no submodules) - discrete — (no submodules)- sampler — (no submodules) - sampler — (no submodules)- errors — (no submodules) - random-error — (no submodules)- game — (no submodules) - dice — (no submodules)- nanoid — The nanoid module implements the Nano ID scheme: a configurable-length, URL-safe random string using a 64-character a…
• ulid — The ulid module implements the Universally Unique Lexicographically Sortable Identifier per the original Alizain Feer…
• uuid — The uuid module produces RFC 9562-compliant UUIDv4 and UUIDv7 identifiers. UUIDv4 is 122 bits of pure randomness with…
• random-float — The random-float module produces a uniformly distributed double in a user-specified half-open interval [min, max).…
• random-int — The random-int module provides an unbiased, inclusive-range integer sampler. Unlike the common `Math.floor(Math.rando…
• objects — (no submodules) - objects — (no submodules)- crypto-rng — The crypto-rng module is the single authoritative binding between @suaveplan/random and the platform's cryptographi…
• default-rng — The default-rng module holds the process-wide default Rng that every helper in @suaveplan/random falls back to wh…
• strings — (no submodules) - random-string — (no submodules)

Install

bun add @suaveplan/random

Features

• Pluggable default source (getDefaultRng/setDefaultRng) — defaults to cryptoRng()
• Unbiased randomInt / randomFloat
• Strings: randomString with 8 charset presets + custom alphabets
• IDs: randomUUID (v4), randomUUIDv7, randomULID, randomNanoid
• Collections: shuffle, shuffleInPlace, choice, sample, weightedChoice, weightedSample
• Objects: randomKey, randomValue, randomEntry, randomSubset
• Games: coin, dice, roll
• Continuous distributions: Normal, LogNormal, Exponential, Gamma, Beta, Pareto, Weibull, Cauchy, Logistic
• Discrete distributions: Bernoulli, Geometric, Binomial, Poisson
• Tagged-union DistributionConfig with createSampler dispatcher — JSON-serialisable

Every function accepts an optional rng?: Rng; omit to use the crypto-backed default, pass a SeededRng for deterministic tests.

Quick start

import { randomUUIDv7, shuffle, sampleDistribution } from "@suaveplan/random";

const id = randomUUIDv7();
const deck = shuffle(["A", "K", "Q", "J"]);
const draws = Array.from({ length: 1000 }, () =>
  sampleDistribution({ type: "normal", mean: 0, stddev: 1 })
);

Subpath exports

• @suaveplan/random/source — cryptoRng, getDefaultRng, setDefaultRng, randomBytes
• @suaveplan/random/strings — randomString, CHARSETS
• @suaveplan/random/ids — randomUUID, randomUUIDv7, randomULID, randomNanoid
• @suaveplan/random/collections — shuffle, choice, sample, weightedChoice, …
• @suaveplan/random/objects — randomKey, randomValue, randomEntry, randomSubset
• @suaveplan/random/game — coin, dice, roll
• @suaveplan/random/numbers — randomInt, randomFloat
• @suaveplan/random/distributions — all distributions + DistributionConfig/createSampler
• @suaveplan/random/errors — RandomError, RANDOM_CODES

Module docs

See the co-located .md next to each implementation.