Registry / data / pandemonium

pandemonium

JSON →
library0.1jsnpmunverified

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 pandemonium
INSTALL
IMPORT
SIG · PANDEMONIUM
P
pandemonium
datajavascriptv0.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

choice
import choice from 'pandemonium/choice';
const choice = require('pandemonium/choice');
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.
choice
import { choice } from 'pandemonium';
import choice from 'pandemonium'; // The main 'pandemonium' entry point does not offer a default export.
Many core utilities, including `choice`, are conveniently re-exported as named exports from the main 'pandemonium' package for easier bundling and usage.
createRandom
import { createRandom } from 'pandemonium/random';
import { createRandom } from 'pandemonium'; // Creator functions are specific to their utility's subpath.
Functions designed to create custom-RNG versions of utilities (e.g., `createRandom` for `random`) are typically found alongside their base function via subpath imports.
shuffle
import { shuffle } from 'pandemonium';
import shuffle from 'pandemonium/shuffle'; // While valid for direct subpath default import, named from main is often preferred.
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.
RandomBooleanFunction
import type { RandomBooleanFunction } from 'pandemonium/random-boolean';
When only the TypeScript type signature for a specific function is needed, it can be imported from its respective subpath using a type import.

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.

import { choice, random, shuffle } from 'pandemonium'; import { createRandom } from 'pandemonium/random'; import seedrandom from 'seedrandom'; // Ensure 'seedrandom' is installed: npm install seedrandom // Basic usage of random utilities const fruits = ['apple', 'banana', 'cherry', 'date']; console.log('Random fruit:', choice(fruits)); const randomNumber = random(10, 20); // Integer between 10 and 20 (inclusive) console.log('Random number (10-20):', randomNumber); const numbersToShuffle = [1, 2, 3, 4, 5]; const shuffledNumbers = shuffle(numbersToShuffle); // Returns a new shuffled array console.log('Shuffled numbers:', shuffledNumbers); // Demonstrating custom RNG for reproducible results const seed = 'my_secret_seed'; const seededRNG = seedrandom(seed); // Create a seeded RNG function // Create a custom random function using the injected seeded RNG const reproducibleRandom = createRandom(seededRNG); console.log(`\nReproducible random numbers with seed "${seed}":`); for (let i = 0; i < 3; i++) { console.log(` Run ${i + 1}:`, reproducibleRandom(1, 100)); } // Verify reproducibility by creating another instance with the same seed const anotherSeededRNG = seedrandom(seed); const anotherReproducibleRandom = createRandom(anotherSeededRNG); console.log(`Reproducible random numbers (second run with same seed "${seed}"):`); for (let i = 0; i < 3; i++) { console.log(` Run ${i + 1}:`, anotherReproducibleRandom(1, 100)); }
Debug
Known issues
gotchaThe `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.
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.
affects: >=1.0
gotchaThe `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.
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.
affects: >=1.0
gotchaWhile 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.
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.
affects: >=2.0
gotchaThe 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.
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.
affects: >=1.0
Errors
Common errors & fixes
TypeError: (0 , _pandemonium_choice__WEBPACK_IMPORTED_MODULE_0__.default) is not a function
Attempting to import a named export as a default export, or vice-versa, especially when importing from the main `pandemonium` package.
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';`.
SyntaxError: Cannot use import statement outside a module
Trying to use ES Module `import` syntax in a CommonJS (`.js` without `"type": "module"` in `package.json`) Node.js environment.
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.
Property 'createChoice' does not exist on type 'typeof import("pandemonium")'.
Incorrectly trying to import a 'create' function (e.g., `createChoice`) directly from the main `pandemonium` entry point instead of its specific subpath.
fix
Import 'create' functions from their dedicated subpaths, e.g., `import { createChoice } from 'pandemonium/choice';`.
Upgrade
Version history
0.1latest on npm
Audit
Dependencies
mnemonistrequiredUsed internally for certain data structures and optimizations, likely for efficient sampling algorithms.
Agent activity
2 hits · last 30 days
node
2
Resources