@suaveplan/pseudo-random - Deterministic seeded PRNG implementations (Mulberry32, SFC32, Xoshiro256++, CounterRng) with offset/fork/checkpoint/restore semantics
Summary
Deterministic, seeded pseudo-random number generators (PRNGs) conforming to the Rng interface from @suaveplan/types. Ships four algorithms — Mulberry32, SFC32, Xoshiro256++, and CounterRng — with a unified SeededRng surface that includes nextUint32, nextFloat, skip, at, fork, checkpoint, and restore. Use this package when you need reproducible randomness (procedural generation, game simulations, property tests) or seek O(1) access to arbitrary positions in the sequence. For cryptographically secure randomness use @suaveplan/random (CSPRNG-backed) or @suaveplan/crypto (raw bytes). Utility functions shuffle, sample, choice, and weightedChoice accept any Rng and work with both seeded and crypto-backed sources.
Documentation tree
- counter-rng —
CounterRngis a hash-based PRNG: its output at logical positioniissplitmix64(seed XOR i). Because the output d… - mulberry32 —
Mulberry32Rngimplements the Mulberry32 PRNG — a compact 32-bit linear-congruential-plus-mix generator with a period… - sfc32 —
Sfc32Rngis a 128-bit SFC32 (Small Fast Counting) generator by Chris Doty-Humphrey. It carries four uint32 state word… - xoshiro256 —
Xoshiro256PlusPlusRngimplements Blackman and Vigna's Xoshiro256++ PRNG — 256 bits of state, period 2^256 − 1, with a… - errors — (no submodules)
- pseudo-random-error — (no submodules)
- seed — (no submodules)
- normalize — (no submodules)
- sample — The
samplemodule covers the two sampling primitives that sit aboveshuffle: unique-without-replacementsamplefo… - shuffle — The
shufflemodule provides deterministic Fisher-Yates shuffling and single-elementchoicedrawn from a user-suppli…
- shuffle — The
shufflemodule provides deterministic Fisher-Yates shuffling and single-elementchoicedrawn from a user-suppli… - pseudo-random-error — (no submodules)- seed — (no submodules)- normalize — (no submodules)- sample — The
samplemodule covers the two sampling primitives that sit aboveshuffle: unique-without-replacementsamplefo… - shuffle — The
shufflemodule provides deterministic Fisher-Yates shuffling and single-elementchoicedrawn from a user-suppli… - pseudo-random-error — (no submodules)- seed — (no submodules)- normalize — (no submodules)- sample — The
samplemodule covers the two sampling primitives that sit aboveshuffle: unique-without-replacementsamplefo… - shuffle — The
shufflemodule provides deterministic Fisher-Yates shuffling and single-elementchoicedrawn from a user-suppli… - pseudo-random-error — (no submodules)- seed — (no submodules) - normalize — (no submodules)- sample — The
samplemodule covers the two sampling primitives that sit aboveshuffle: unique-without-replacementsamplefo… - shuffle — The
shufflemodule provides deterministic Fisher-Yates shuffling and single-elementchoicedrawn from a user-suppli…
Packages
Four algorithms with identical SeededRng surface:
| Algorithm | State | Period | Best for |
|---|---|---|---|
Mulberry32Rng |
32 bit | ~2^32 | Tiny, per-UI seeding |
Sfc32Rng |
128bit | ≥2^32 | High-quality default |
Xoshiro256PlusPlusRng |
256bit | 2^256 − 1 | Simulations + parallel streams |
CounterRng |
64 bit | — | O(1) seek, procedural tiles |
Each implements nextUint32, nextFloat, skip, at, fork, checkpoint, restore, plus Xoshiro256PlusPlusRng.jump() for jumping by 2^128 steps.
Install
bun add @suaveplan/pseudo-random
Quick start
import { Sfc32Rng, shuffle } from "@suaveplan/pseudo-random";
const rng = new Sfc32Rng("game-42");
const deck = shuffle(["A", "K", "Q", "J"], rng);
Subpath exports
@suaveplan/pseudo-random/algorithms— the four generators@suaveplan/pseudo-random/seed—normalizeSeed,splitmix32/64,expandSeed@suaveplan/pseudo-random/utils—shuffle,sample,choice,weightedChoice@suaveplan/pseudo-random/errors—PseudoRandomError,PSEUDO_RANDOM_CODES@suaveplan/pseudo-random/schemas— Zod schemas for serialised state