01 · Problem
What is it for?
Reproducible experiments need state controlled by a seed; security-sensitive output needs an operating-system generator.
02 · Mental model
How should you think about it?
A pseudorandom generator is a deterministic state transition. A weighted selector maps one uniform value onto cumulative intervals.
Provides reproducible seeded generators and normalized weighted selection. Fortuna is a compatibility name backed by node:crypto, not the Fortuna algorithm. Seeded strategies are simulation generators; the Redis sketch is an explicitly unsupported integration.
03 · Control flow
What happens in which order?
- Normalize seed bytes without information loss.
- Advance generator state.
- Convert the output to a bounded float or integer.
- Select an item using normalized positive weights.
04 · Building blocks
The important contracts
Seed / PseudoRandomNumberGeneratorRepresent seed bytes and reproducible number streams.LinearCongruential / XORShift / MersenneTwister / WichmannHill / LaggedFibonacciChoose a simulation generator strategy.Fortuna / PseudoRandomItemSelectorUse OS randomness through a compatibility facade or select weighted items.05 · Build it yourself
Implement a small core
Start with this small independent implementation, then use the steps below to make its contract explicit.
- Normalize seed bytes without information loss.
- Advance generator state.
- Convert the output to a bounded float or integer.
- Select an item using normalized positive weights.
class XorShift32 {
private state: number;
constructor(seed: number) { this.state = seed >>> 0 || 0x9e3779b9; }
nextUint32() {
let value = this.state;
value ^= value << 13;
value ^= value >>> 17;
value ^= value << 5;
return (this.state = value >>> 0);
}
nextFloat() { return this.nextUint32() / 0x1_0000_0000; }
}06 · Verify
What should you test?
- Compare complete sequences for equal seeds.
- Check float and integer boundaries.
- Test non-normalized weights and zero-weight items.
Try it yourself
Turn the first verification claim into a failing test, implement the smallest fix, then add a boundary case.
Compare complete sequences for equal seeds.
Compare your approach
Your check should fail when the stated invariant is deliberately broken, and pass again after the fix. Keep setup deterministic and assert an observable result.
07 · Limits
Trade-offs and failure modes
- Statistical quality differs from cryptographic security.
- Use node:crypto or crypto.getRandomValues for secrets.
- Redis-backed state requires an explicit integration contract.
Fortuna is a compatibility name backed by node:crypto, not the Fortuna algorithm. Seeded strategies are simulation generators; the Redis sketch is an explicitly unsupported integration.
08 · Keep exploring
Source code and related ideas
yarn tsx packages/random/examples/basic.ts