Registry / testing / pure-rand

pure-rand

JSON →
library8.4.0jsnpmunverified

Pure-rand is a JavaScript and TypeScript library providing fast, pure pseudorandom number generators (PRNGs). Its core differentiator is the emphasis on purity: generator instances are immutable. This means each random number generation operation returns a new generator state alongside the generated value, enabling reproducible sequences and eliminating side effects, which is crucial for deterministic simulations, testing, and cryptographic applications where state integrity is paramount. The library offers various PRNG algorithms, such as Xoroshiro128+, and implements common statistical distributions like uniform integers. Currently at version 8.4.0, pure-rand maintains an active development and release cadence, providing reliable and performant random number generation. It aims to offer predictable and verifiable randomness, setting it apart from libraries that mutate generator state in place.

npm install pure-rand
INSTALL
IMPORT
SIG · PURE-RAND
P
pure-rand
testingjavascriptv8.4.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

xoroshiro128plus
import { xoroshiro128plus } from 'pure-rand/generator/xoroshiro128plus';
const { xoroshiro128plus } = require('pure-rand/generator/xoroshiro128plus');
Use named imports from specific subpaths for PRNG algorithms. CommonJS require will fail due to ESM exports.
uniformInt
import { uniformInt } from 'pure-rand/distribution/uniformInt';
import uniformInt from 'pure-rand/distribution/uniformInt';
Distribution functions are named exports from their respective subpaths, not default exports. Named import is crucial.
purify
import { purify } from 'pure-rand/utils/purify';
import * as purify from 'pure-rand/utils/purify';
The `purify` utility is a named export for transforming impure distributions into pure ones.
IRandomGenerator
import type { IRandomGenerator } from 'pure-rand';
Type imports for interfaces like IRandomGenerator are available directly from the main package entry point.

Demonstrates the library's core 'pure' usage model, where each random number generation returns a new generator state, ensuring immutability and reproducibility. It initializes a Xoroshiro128+ generator, purifies a uniform integer distribution, and shows how to generate a sequence of values while correctly managing the evolving immutable generator state.

import { uniformIntDistribution } from 'pure-rand/distribution/UniformIntDistribution'; import { xoroshiro128plus } from 'pure-rand/generator/xoroshiro128plus'; import { purify } from 'pure-rand/utils/purify'; const uniformIntDistributionPure = purify(uniformIntDistribution); // A seed for reproducibility const seed = 42; // Initialize the PRNG. This creates an 'impure' generator. const rng1 = xoroshiro128plus(seed); // Use the purified distribution. It returns both the value and the *next* generator state. const [firstDiceValue, rng2] = uniformIntDistributionPure(rng1, 1, 6); console.log(`First roll: ${firstDiceValue}, Next RNG state hash: ${rng2.min()}`); // Example: 2 const [secondDiceValue, rng3] = uniformIntDistributionPure(rng2, 1, 6); console.log(`Second roll: ${secondDiceValue}, Next RNG state hash: ${rng3.min()}`); // Example: 4 const [thirdDiceValue, rng4] = uniformIntDistributionPure(rng3, 1, 6); console.log(`Third roll: ${thirdDiceValue}, Next RNG state hash: ${rng4.min()}`); // Example: 6 // Demonstrating purity: Calling with rng1 again produces the same result const [replayedFirstValue, _] = uniformIntDistributionPure(rng1, 1, 6); console.log(`Replayed first roll (from rng1): ${replayedFirstValue}`); // Example: 2 // Example of directly using an impure generator (less common in pure-rand's philosophy) const impureRng = xoroshiro128plus(100); const val1 = uniformInt(impureRng, 1, 10); const val2 = uniformInt(impureRng, 1, 10); console.log(`Impure sequence: ${val1}, ${val2}`);
Debug
Known issues
breakingPure-rand is an ESM-first package. Direct `require()` statements for subpath exports (e.g., '/generator/xoroshiro128plus') will likely fail in Node.js environments that don't correctly resolve `package.json` 'exports' maps for CommonJS compatibility, or in older bundlers.
fix
Ensure your project is configured for ESM, use `import` statements, or configure bundlers (like Webpack/Rollup) to correctly handle 'exports' for dual-package hazards. For Node.js, ensure `type: module` in `package.json` or use `.mjs` files.
affects: >=3.0.0
gotchaThe core design principle of 'pure-rand' is immutability. Generator instances (e.g., from `xoroshiro128plus(seed)`) are *not* mutated in place when generating random numbers. Functions like `uniformInt` consume the current generator and return a new generator state. Failing to capture and use the new generator state will result in repetitive values.
fix
Always capture the returned generator when using pure distribution functions, e.g., `const [value, nextRng] = purify(distribution)(currentRng, ...args);`. If using impure functions like `uniformInt`, be aware they expect a mutable generator (which `pure-rand` doesn't directly provide as its primary API for distributions), or use the provided pure distribution functions with `purify`.
affects: >=1.0.0
gotchaImport paths for generators and distributions are specific subpaths (e.g., `pure-rand/generator/xoroshiro128plus`, `pure-rand/distribution/uniformInt`). Importing directly from `pure-rand` for these specific components is not supported and will lead to undefined symbols or runtime errors.
fix
Always use the full, explicit import path as shown in the documentation and examples for generators and distribution functions. For example, `import { xoroshiro128plus } from 'pure-rand/generator/xoroshiro128plus';`.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: (0 , pure_rand_generator_xoroshiro128plus__WEBPACK_IMPORTED_MODULE_1__.xoroshiro128plus) is not a function
This typically occurs in bundlers (like Webpack) when mixing CommonJS `require` with ESM `import` or when `exports` mapping in `package.json` is not correctly interpreted. It indicates a failure to correctly resolve the named export from an ESM module.
fix
Ensure your bundler is configured for ESM. If you're using CommonJS, explicitly switch to `import` syntax if possible. Verify that `package.json`'s `exports` field is being honored or that your build pipeline correctly transpiles ESM to CJS if targeting older environments.
Error: Cannot find module 'pure-rand/distribution/uniformInt' or its corresponding type declarations.
The module resolver (Node.js, bundler, or TypeScript) cannot locate the specified subpath. This could be due to incorrect spelling, an environment that doesn't support subpath exports, or a `node_modules` issue.
fix
Double-check the import path for typos. Ensure your Node.js version supports `package.json` `exports` (>=12.17.0 for basic support, >=14.13.0 for full conditional exports). If using TypeScript, ensure `moduleResolution` is set to `NodeNext` or `Bundler` in `tsconfig.json` for proper subpath resolution. Reinstall `node_modules` to resolve potential package corruption.
Upgrade
Version history
8.4.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
4 hits · last 30 days
node
4
Resources
pure-rand — npm install pure-rand · libregistry