pdrng

Pseudo Deterministic Random Number Generator — seed-based deterministic number generation.

A JavaScript library for generating deterministic outputs based on a numeric seed. Given the same seed, every function produces the same result every time. Useful for testing, simulations, reproducible demos, and seeded content generation.

Default seed: 814

Install

npm install pdrng

Quick Start

import pdrng from 'pdrng';

pdrng()        // 814
pdrng(1)       // 8
pdrng(6)       // 814814
pdrng.coin()   // "tails"
pdrng.dice()   // 4
pdrng.card()   // "8 of Diamonds"

API

Core

pdrng(digits?, options?)

Generate a deterministic number with the specified number of digits.

pdrng()           // 814 (default: 3 digits)
pdrng(1)          // 8
pdrng(2)          // 14
pdrng(4)          // 8148
pdrng(5)          // 81414
pdrng(6)          // 814814

Utilities

float(precision?, options?)

float()           // 0.814814
float(3)          // 0.814

range(min, max, options?)

range(1, 100)     // 14

array(count, digits?, options?)

array(3, 2)       // [14, 46, 78] (sub-seeds per element)

uuid(options?)

uuid()            // deterministic UUID v4 format

oddOrEven(options?)

oddOrEven()       // "even"

redOrBlack(options?)

redOrBlack()      // "red"

randomSeed()

Generate a random seed using crypto.getRandomValues (with Math.random fallback).

randomSeed()      // e.g. 3847291056 (different each call)

Simulation Functions

coin(options?)

Deterministic coin flip.

coin()            // "tails"

dice(sides?, options?)

Deterministic die result.

dice()            // 4 (6-sided)
dice(20)          // 14

card(options?)

Deterministic playing card draw.

card()            // "8 of Diamonds"

rps(options?)

Deterministic rock-paper-scissors.

rps()             // "scissors"

magic8(options?)

Deterministic 8-ball response.

magic8()          // "Reply hazy, try again."

zodiac(options?)

Deterministic zodiac sign.

zodiac()          // "Gemini"

tarot(options?)

Deterministic tarot card.

tarot()           // "The Magician"

fortune(options?)

Deterministic fortune message.

fortune()         // "The answer you seek was never in doubt."

spin(array, options?)

Deterministic selection from an array.

spin(['a', 'b', 'c', 'd'])  // "c"

roll(notation, options?)

Deterministic dice notation result (tabletop RPG style).

roll('2d6+3')     // { rolls: [5, 1], modifier: 3, total: 9 }

bingo(options?)

Deterministic bingo call.

bingo()           // "B-14"

color(options?)

Deterministic hex color.

color()           // "#a81414"

roulette(options?)

Deterministic number with color and parity.

roulette()        // { number: 14, color: "red", parity: "even" }

Custom Seeds

Every function accepts an options object with a seed property:

import { coin, dice, card } from 'pdrng';

coin({ seed: 42 })        // "heads"
dice(6, { seed: 42 })     // 4
card({ seed: 'brian' })   // deterministic card from text seed

Text seeds are converted using a rolling XOR hash, designed so that "brian" maps to seed 814:

pdrng(3, { seed: 'brian' })  // 814 (same as default!)
pdrng(4, { seed: 'brian' })  // 8148

Random Seeds

While pdrng is deterministic by design, you can use random input to get non-deterministic behavior. Pass Math.random(), crypto.getRandomValues(), or use the built-in randomSeed() helper:

import { coin, dice, randomSeed } from 'pdrng';

// Built-in helper (uses crypto.getRandomValues for real entropy)
coin({ seed: randomSeed() })      // different each call

// Math.random() works directly as a seed
dice(6, { seed: Math.random() })  // different each call

Imports

// Default import (with all methods attached)
import pdrng from 'pdrng';
pdrng.coin();

// Named imports
import { coin, dice, card, roll } from 'pdrng';
coin();

Requirements

• Node.js 18+
• ESM only (import/export)

License

MIT