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.
npm install pandemoniumVerified import paths — ran on the pinned version, not inferred.
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.
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.
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.
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.Always review the official release notes and changelog on the GitHub repository before upgrading major versions to anticipate and address any necessary code adjustments.
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';`.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.
Import 'create' functions from their dedicated subpaths, e.g., `import { createChoice } from 'pandemonium/choice';`.