Pandemonium

Common errors

• TypeError: (0 , _pandemonium_choice__WEBPACK_IMPORTED_MODULE_0__.default) is not a function

  cause 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

  cause 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")'.

  cause 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';`.

Warnings

• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install pandemonium npm
• yarn add pandemonium yarn
• pnpm add pandemonium pnpm

Imports

• choice
  wrong:

  const choice = require('pandemonium/choice');

  correct:

  import choice from '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
  wrong:

  import choice from 'pandemonium'; // The main 'pandemonium' entry point does not offer a default export.

  correct:

  import { choice } from 'pandemonium';

  Many core utilities, including `choice`, are conveniently re-exported as named exports from the main 'pandemonium' package for easier bundling and usage.
• createRandom
  wrong:

  import { createRandom } from 'pandemonium'; // Creator functions are specific to their utility's subpath.

  correct:

  import { createRandom } from 'pandemonium/random';

  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
  wrong:

  import shuffle from 'pandemonium/shuffle'; // While valid for direct subpath default import, named from main is often preferred.

  correct:

  import { shuffle } from 'pandemonium';

  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.

Quickstart

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));
}