Mathematically Correct Random Number Generation

Common errors

• TypeError: (0, random_js_1.MersenneTwister19937) is not a constructor

  cause Attempting to use `MersenneTwister19937` directly as a constructor without first calling its static `seed()` method, or incorrectly importing it with CommonJS `require`.
  fix Ensure `MersenneTwister19937` is imported via named ES module syntax and that you call `.seed()` on it to get an engine instance: `import { MersenneTwister19937 } from 'random-js'; const engine = MersenneTwister19937.seed(123);`

• TypeError: Cannot read properties of undefined (reading 'integer')

  cause This usually happens when `new Random()` is called without providing a valid engine, or when the `Random` class itself was not correctly imported (e.g., trying to use `Random` as a default import instead of a named import).
  fix Make sure to import `Random` as a named export (`import { Random } from 'random-js';`) and instantiate it with a valid engine (`new Random(MersenneTwister19937.seed(123))`).

• ReferenceError: crypto is not defined

  cause Attempting to use `browserCrypto` or `nodeCrypto` engines in an unsupported environment (e.g., `browserCrypto` in Node.js, or `nodeCrypto` in a browser) or in an older browser lacking the `crypto` API.
  fix Use the appropriate engine for your environment (`nodeCrypto` in Node.js, `browserCrypto` in modern browsers). For cross-platform or older browser compatibility, `MersenneTwister19937` is a better choice.

Warnings

• breaking Upgrading from random-js v1.0 to v2.0 constitutes a major breaking change. The export structure was refactored from static properties on a single class-like function to individual named exports for each binding, aligning with modern ECMAScript module standards.
  Fix: Rewrite CommonJS `require` statements and adjust object property access to use named `import` statements (e.g., `import { MersenneTwister19937, Random } from 'random-js';`).
• gotcha Commonly used `Math.random()` has inconsistencies across JavaScript engines (e.g., 32-bit vs 53-bit randomness in Chrome/Node.js vs. Firefox/IE) and is non-deterministic. Relying solely on `Math.random()` can lead to non-repeatable results and insufficient entropy for critical applications.
  Fix: For deterministic or higher-quality randomness, use random-js engines like `MersenneTwister19937` (seeded) for repeatability, or `nodeCrypto`/`browserCrypto` for cryptographically secure, non-deterministic values where available.
• gotcha Most naive implementations of generating random integers within a range (e.g., `Math.floor(Math.random() * (max - min)) + min`) introduce subtle biases, leading to non-uniform distributions where some numbers are more likely to appear than others. This can silently break simulations or games.
  Fix: Always use random-js's provided distribution methods, such as `random.integer(min, max)`, which correctly handle bias elimination by potentially drawing multiple times from the underlying engine.
• gotcha The `MersenneTwister19937` engine, while excellent for deterministic and repeatable sequences, is NOT cryptographically secure. Do not use it for generating keys, tokens, or any security-sensitive data.
  Fix: For cryptographically secure random numbers, prefer `browserCrypto` (in browsers) or `nodeCrypto` (in Node.js) engines. Ensure your environment supports these APIs.
• gotcha The `nativeMath` engine, which wraps `Math.random()`, may have a shorter period than expected, meaning its sequence of random numbers might repeat sooner. It's also non-deterministic.
  Fix: If determinism or a long period is required, use `MersenneTwister19937`. For cryptographically secure numbers, use `browserCrypto` or `nodeCrypto`. Only use `nativeMath` when simple, non-critical, non-deterministic randomness is acceptable.

Install

• npm install random-js npm
• yarn add random-js yarn
• pnpm add random-js pnpm

Imports

• MersenneTwister19937
  wrong:

  const MersenneTwister19937 = require('random-js').MersenneTwister19937;

  correct:

  import { MersenneTwister19937 } from 'random-js';

  Since v2.0, random-js uses named exports. CommonJS 'require' style will not work as expected for individual exports.
• Random
  wrong:

  import Random from 'random-js';

  correct:

  import { Random } from 'random-js';

  The primary 'Random' class is a named export, not a default export. Attempting a default import will result in 'undefined'.
• integer
  wrong:

  import { int } from 'random-js';

  correct:

  import { integer } from 'random-js';

  Distributions like 'integer' are also named exports. Ensure correct spelling as the library does not provide aliases.

Quickstart

This quickstart demonstrates importing and initializing a `Random` instance with a `MersenneTwister19937` engine, seeding it for deterministic results, and generating a uniform random integer using the `integer` distribution. It also briefly mentions other engine options.

import { Random, MersenneTwister19937, integer } from 'random-js';

// Initialize a deterministic engine with a seed
const engine = MersenneTwister19937.seed(123);

// Create a Random instance with the engine
const random = new Random(engine);

// Generate a random integer between 1 and 100 (inclusive)
const randomNumber = random.integer(1, 100);
console.log(`Deterministic random number: ${randomNumber}`);

// Demonstrate using a non-deterministic engine (e.g., nodeCrypto in Node.js)
// In a browser, you might use browserCrypto; nativeMath is also an option.
// Note: nodeCrypto and browserCrypto are only available in their respective environments.
// For cross-platform or tests, MersenneTwister19937 is often preferred.

// Example with nodeCrypto (only works in Node.js environment)
// import { nodeCrypto } from 'random-js';
// const cryptoEngine = nodeCrypto;
// const randomCrypto = new Random(cryptoEngine);
// const cryptoNumber = randomCrypto.integer(1, 100);
// console.log(`Cryptographically random number: ${cryptoNumber}`);

// Generate 5 more deterministic numbers
for (let i = 0; i < 5; i++) {
  console.log(`Next deterministic number: ${random.integer(1, 100)}`);
}