{"id":11605,"library":"pure-rand","title":"Pure Random Number Generators","description":"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.","status":"active","version":"8.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/dubzzz/pure-rand","tags":["javascript","seed","random","prng","generator","pure","rand","mersenne","random number generator"],"install":[{"cmd":"npm install pure-rand","lang":"bash","label":"npm"},{"cmd":"yarn add pure-rand","lang":"bash","label":"yarn"},{"cmd":"pnpm add pure-rand","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Use named imports from specific subpaths for PRNG algorithms. CommonJS require will fail due to ESM exports.","wrong":"const { xoroshiro128plus } = require('pure-rand/generator/xoroshiro128plus');","symbol":"xoroshiro128plus","correct":"import { xoroshiro128plus } from 'pure-rand/generator/xoroshiro128plus';"},{"note":"Distribution functions are named exports from their respective subpaths, not default exports. Named import is crucial.","wrong":"import uniformInt from 'pure-rand/distribution/uniformInt';","symbol":"uniformInt","correct":"import { uniformInt } from 'pure-rand/distribution/uniformInt';"},{"note":"The `purify` utility is a named export for transforming impure distributions into pure ones.","wrong":"import * as purify from 'pure-rand/utils/purify';","symbol":"purify","correct":"import { purify } from 'pure-rand/utils/purify';"},{"note":"Type imports for interfaces like IRandomGenerator are available directly from the main package entry point.","symbol":"IRandomGenerator","correct":"import type { IRandomGenerator } from 'pure-rand';"}],"quickstart":{"code":"import { uniformIntDistribution } from 'pure-rand/distribution/UniformIntDistribution';\nimport { xoroshiro128plus } from 'pure-rand/generator/xoroshiro128plus';\nimport { purify } from 'pure-rand/utils/purify';\n\nconst uniformIntDistributionPure = purify(uniformIntDistribution);\n\n// A seed for reproducibility\nconst seed = 42;\n// Initialize the PRNG. This creates an 'impure' generator.\nconst rng1 = xoroshiro128plus(seed);\n\n// Use the purified distribution. It returns both the value and the *next* generator state.\nconst [firstDiceValue, rng2] = uniformIntDistributionPure(rng1, 1, 6);\nconsole.log(`First roll: ${firstDiceValue}, Next RNG state hash: ${rng2.min()}`); // Example: 2\n\nconst [secondDiceValue, rng3] = uniformIntDistributionPure(rng2, 1, 6);\nconsole.log(`Second roll: ${secondDiceValue}, Next RNG state hash: ${rng3.min()}`); // Example: 4\n\nconst [thirdDiceValue, rng4] = uniformIntDistributionPure(rng3, 1, 6);\nconsole.log(`Third roll: ${thirdDiceValue}, Next RNG state hash: ${rng4.min()}`); // Example: 6\n\n// Demonstrating purity: Calling with rng1 again produces the same result\nconst [replayedFirstValue, _] = uniformIntDistributionPure(rng1, 1, 6);\nconsole.log(`Replayed first roll (from rng1): ${replayedFirstValue}`); // Example: 2\n\n// Example of directly using an impure generator (less common in pure-rand's philosophy)\nconst impureRng = xoroshiro128plus(100);\nconst val1 = uniformInt(impureRng, 1, 10);\nconst val2 = uniformInt(impureRng, 1, 10);\nconsole.log(`Impure sequence: ${val1}, ${val2}`);","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Pure-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.","severity":"breaking","affected_versions":">=3.0.0"},{"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`.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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';`.","message":"Import 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"TypeError: (0 , pure_rand_generator_xoroshiro128plus__WEBPACK_IMPORTED_MODULE_1__.xoroshiro128plus) is not a function"},{"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.","cause":"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.","error":"Error: Cannot find module 'pure-rand/distribution/uniformInt' or its corresponding type declarations."}],"ecosystem":"npm"}