{"id":11520,"library":"pandemonium","title":"Pandemonium","description":"Pandemonium is a lightweight JavaScript and TypeScript library providing a collection of common random-related utility functions. Currently stable at version 2.4.1, it offers functionalities such as `choice` for selecting random items, `random` for generating numbers within a range, `shuffle` for array randomization, and various specialized sampling algorithms like `reservoirSample` and `geometricReservoirSample`. A key differentiator is its modular design, allowing users to create custom versions of any function by injecting a specific random number generator (RNG) source, enabling seeded or otherwise controlled randomness. The library emphasizes performance for its sampling methods, offering detailed complexity analysis. Its release cadence is not explicitly stated in the provided documentation, but the package appears actively maintained with regular updates.","status":"active","version":"2.4.1","language":"javascript","source_language":"en","source_url":"https://github.com/yomguithereal/pandemonium","tags":["javascript","random","choice","sample","shuffle","typescript"],"install":[{"cmd":"npm install pandemonium","lang":"bash","label":"npm"},{"cmd":"yarn add pandemonium","lang":"bash","label":"yarn"},{"cmd":"pnpm add pandemonium","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally for certain data structures and optimizations, likely for efficient sampling algorithms.","package":"mnemonist","optional":false}],"imports":[{"note":"The library primarily uses ES Modules. While transpilers might handle CommonJS `require`, direct ESM imports from subpaths are the canonical way to access individual utilities as default exports.","wrong":"const choice = require('pandemonium/choice');","symbol":"choice","correct":"import choice from 'pandemonium/choice';"},{"note":"Many core utilities, including `choice`, are conveniently re-exported as named exports from the main 'pandemonium' package for easier bundling and usage.","wrong":"import choice from 'pandemonium'; // The main 'pandemonium' entry point does not offer a default export.","symbol":"choice","correct":"import { choice } from 'pandemonium';"},{"note":"Functions designed to create custom-RNG versions of utilities (e.g., `createRandom` for `random`) are typically found alongside their base function via subpath imports.","wrong":"import { createRandom } from 'pandemonium'; // Creator functions are specific to their utility's subpath.","symbol":"createRandom","correct":"import { createRandom } from 'pandemonium/random';"},{"note":"Pandemonium offers both named exports from its main entry and default exports from specific subpaths for most functions. The library ships with TypeScript types automatically.","wrong":"import shuffle from 'pandemonium/shuffle'; // While valid for direct subpath default import, named from main is often preferred.","symbol":"shuffle","correct":"import { shuffle } from 'pandemonium';"},{"note":"When only the TypeScript type signature for a specific function is needed, it can be imported from its respective subpath using a type import.","symbol":"RandomBooleanFunction","correct":"import type { RandomBooleanFunction } from 'pandemonium/random-boolean';"}],"quickstart":{"code":"import { choice, random, shuffle } from 'pandemonium';\nimport { createRandom } from 'pandemonium/random';\nimport seedrandom from 'seedrandom'; // Ensure 'seedrandom' is installed: npm install seedrandom\n\n// Basic usage of random utilities\nconst fruits = ['apple', 'banana', 'cherry', 'date'];\nconsole.log('Random fruit:', choice(fruits));\n\nconst randomNumber = random(10, 20); // Integer between 10 and 20 (inclusive)\nconsole.log('Random number (10-20):', randomNumber);\n\nconst numbersToShuffle = [1, 2, 3, 4, 5];\nconst shuffledNumbers = shuffle(numbersToShuffle); // Returns a new shuffled array\nconsole.log('Shuffled numbers:', shuffledNumbers);\n\n// Demonstrating custom RNG for reproducible results\nconst seed = 'my_secret_seed';\nconst seededRNG = seedrandom(seed); // Create a seeded RNG function\n\n// Create a custom random function using the injected seeded RNG\nconst reproducibleRandom = createRandom(seededRNG);\n\nconsole.log(`\\nReproducible random numbers with seed \"${seed}\":`);\nfor (let i = 0; i < 3; i++) {\n  console.log(`  Run ${i + 1}:`, reproducibleRandom(1, 100));\n}\n\n// Verify reproducibility by creating another instance with the same seed\nconst anotherSeededRNG = seedrandom(seed);\nconst anotherReproducibleRandom = createRandom(anotherSeededRNG);\nconsole.log(`Reproducible random numbers (second run with same seed \"${seed}\"):`);\nfor (let i = 0; i < 3; i++) {\n  console.log(`  Run ${i + 1}:`, anotherReproducibleRandom(1, 100));\n}","lang":"typescript","description":"This quickstart demonstrates basic random number and selection utilities like `choice`, `random`, and `shuffle` from Pandemonium. It also illustrates a key feature: how to integrate a custom random number generator (e.g., `seedrandom`) to create reproducible random sequences, which is essential for testing or specific application needs."},"warnings":[{"fix":"Use non-mutating sampling methods like `geometricReservoirSample` or `reservoirSample` if you need to preserve the original array. If mutation is acceptable, pass a shallow copy (e.g., `dangerouslyMutatingSample([...myArray], k)`) to explicitly indicate intent.","message":"The `dangerouslyMutatingSample` function modifies the input array directly for performance. This can lead to unexpected side effects if the original array is still needed or referenced elsewhere in your application.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Consult the library's sampling table and consider more optimized alternatives like `geometricReservoirSample` (for random access structures) or `reservoirSample` (for streams), which often provide better time and memory complexity.","message":"The `fisherYatesSample` method is explicitly noted in the documentation as 'Probably not a good idea.', indicating it may have performance or memory efficiency drawbacks compared to other sampling algorithms offered by the library.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Prefer ES Module `import` statements (e.g., `import { choice } from 'pandemonium';`). If CommonJS is strictly required, ensure your build setup correctly handles dual-package resolution or use a transpiler like Babel.","message":"While the package's `package.json` includes a `main` field pointing to a CommonJS entry, the documentation primarily showcases ES Module (`import`) syntax. Relying on `require()` directly may lead to unexpected behavior or require specific transpilation setups in modern Node.js environments.","severity":"gotcha","affected_versions":">=2.0"},{"fix":"Always review the official release notes and changelog on the GitHub repository before upgrading major versions to anticipate and address any necessary code adjustments.","message":"The library's documentation does not explicitly detail breaking changes between major versions. Developers upgrading Pandemonium should proactively consult the project's changelog or GitHub releases to identify potential breaking changes, especially when moving to a new major version.","severity":"gotcha","affected_versions":">=1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"If importing from `pandemonium`, use named imports: `import { choice } from 'pandemonium';`. If importing from a subpath (e.g., `pandemonium/choice`), check if it's a default export: `import choice from 'pandemonium/choice';`.","cause":"Attempting to import a named export as a default export, or vice-versa, especially when importing from the main `pandemonium` package.","error":"TypeError: (0 , _pandemonium_choice__WEBPACK_IMPORTED_MODULE_0__.default) is not a function"},{"fix":"Ensure your Node.js project is configured for ES Modules by adding `\"type\": \"module\"` to your `package.json`, or rename your file to `.mjs`. Alternatively, if targeting older Node.js or a specific CJS environment, you might need a bundler/transpiler like Babel or Webpack.","cause":"Trying to use ES Module `import` syntax in a CommonJS (`.js` without `\"type\": \"module\"` in `package.json`) Node.js environment.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Import 'create' functions from their dedicated subpaths, e.g., `import { createChoice } from 'pandemonium/choice';`.","cause":"Incorrectly trying to import a 'create' function (e.g., `createChoice`) directly from the main `pandemonium` entry point instead of its specific subpath.","error":"Property 'createChoice' does not exist on type 'typeof import(\"pandemonium\")'."}],"ecosystem":"npm"}