Pure Random Number Generators

Common errors

• TypeError: (0 , pure_rand_generator_xoroshiro128plus__WEBPACK_IMPORTED_MODULE_1__.xoroshiro128plus) is not a function

  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.
  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.

  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.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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`.
• gotcha 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.
  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';`.

Install

• npm install pure-rand npm
• yarn add pure-rand yarn
• pnpm add pure-rand pnpm

Imports

• xoroshiro128plus
  wrong:

  const { xoroshiro128plus } = require('pure-rand/generator/xoroshiro128plus');

  correct:

  import { xoroshiro128plus } from 'pure-rand/generator/xoroshiro128plus';

  Use named imports from specific subpaths for PRNG algorithms. CommonJS require will fail due to ESM exports.
• uniformInt
  wrong:

  import uniformInt from 'pure-rand/distribution/uniformInt';

  correct:

  import { uniformInt } from 'pure-rand/distribution/uniformInt';

  Distribution functions are named exports from their respective subpaths, not default exports. Named import is crucial.
• purify
  wrong:

  import * as purify from 'pure-rand/utils/purify';

  correct:

  import { 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.

Quickstart

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}`);