{"id":16188,"library":"random-js","title":"Mathematically Correct Random Number Generation","description":"Random.js is a JavaScript library designed to provide mathematically correct and consistent random number generation, addressing the shortcomings of `Math.random()` and common biased implementations. It offers various 'engines' like `nativeMath` (using `Math.random`), `browserCrypto` (using `crypto.getRandomValues`), `nodeCrypto` (using `crypto.randomBytes`), and `MersenneTwister19937` for deterministic, repeatable sequences. The library focuses on providing 32 bits of randomness consistently and includes distributions to prevent common biases in integer generation. The current stable version is 2.1.0, and while a specific release cadence isn't stated, it generally follows semver for major breaking changes. Its key differentiators include platform-specific cryptographic engines and a robust, bias-free API for various distributions, making it suitable for simulations, games, and other applications where high-quality randomness is crucial.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":"git://github.com/ckknight/random-js","tags":["javascript","random","typescript"],"install":[{"cmd":"npm install random-js","lang":"bash","label":"npm"},{"cmd":"yarn add random-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add random-js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since v2.0, random-js uses named exports. CommonJS 'require' style will not work as expected for individual exports.","wrong":"const MersenneTwister19937 = require('random-js').MersenneTwister19937;","symbol":"MersenneTwister19937","correct":"import { MersenneTwister19937 } from 'random-js';"},{"note":"The primary 'Random' class is a named export, not a default export. Attempting a default import will result in 'undefined'.","wrong":"import Random from 'random-js';","symbol":"Random","correct":"import { Random } from 'random-js';"},{"note":"Distributions like 'integer' are also named exports. Ensure correct spelling as the library does not provide aliases.","wrong":"import { int } from 'random-js';","symbol":"integer","correct":"import { integer } from 'random-js';"}],"quickstart":{"code":"import { Random, MersenneTwister19937, integer } from 'random-js';\n\n// Initialize a deterministic engine with a seed\nconst engine = MersenneTwister19937.seed(123);\n\n// Create a Random instance with the engine\nconst random = new Random(engine);\n\n// Generate a random integer between 1 and 100 (inclusive)\nconst randomNumber = random.integer(1, 100);\nconsole.log(`Deterministic random number: ${randomNumber}`);\n\n// Demonstrate using a non-deterministic engine (e.g., nodeCrypto in Node.js)\n// In a browser, you might use browserCrypto; nativeMath is also an option.\n// Note: nodeCrypto and browserCrypto are only available in their respective environments.\n// For cross-platform or tests, MersenneTwister19937 is often preferred.\n\n// Example with nodeCrypto (only works in Node.js environment)\n// import { nodeCrypto } from 'random-js';\n// const cryptoEngine = nodeCrypto;\n// const randomCrypto = new Random(cryptoEngine);\n// const cryptoNumber = randomCrypto.integer(1, 100);\n// console.log(`Cryptographically random number: ${cryptoNumber}`);\n\n// Generate 5 more deterministic numbers\nfor (let i = 0; i < 5; i++) {\n  console.log(`Next deterministic number: ${random.integer(1, 100)}`);\n}","lang":"typescript","description":"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."},"warnings":[{"fix":"Rewrite CommonJS `require` statements and adjust object property access to use named `import` statements (e.g., `import { MersenneTwister19937, Random } from 'random-js';`).","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For cryptographically secure random numbers, prefer `browserCrypto` (in browsers) or `nodeCrypto` (in Node.js) engines. Ensure your environment supports these APIs.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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);`","cause":"Attempting to use `MersenneTwister19937` directly as a constructor without first calling its static `seed()` method, or incorrectly importing it with CommonJS `require`.","error":"TypeError: (0, random_js_1.MersenneTwister19937) is not a constructor"},{"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))`).","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).","error":"TypeError: Cannot read properties of undefined (reading 'integer')"},{"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.","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.","error":"ReferenceError: crypto is not defined"}],"ecosystem":"npm"}