novac 2.1.1 → 2.2.0

package/kits/kitRNG/kitdef.js

@@ -0,0 +1,740 @@
+// kitdef.js — kitRandom
+// Comprehensive random number generation, sampling, shuffling, weighted
+// selection, seeded RNG, distributions, ID generation, geometry, and more.
+
+module.exports = {
+  kitdef: {
+
+    name: "kitRandom",
+    version: "1.0.0",
+    description: "Comprehensive random utilities: floats, ints, booleans, sampling, shuffling, weighted picks, seeded RNG, distributions, ID generation, geometry, and dice.",
+
+    // ──────────────────────────────────────────────────────────────────────
+    // BASIC FLOATS & INTS
+    // ──────────────────────────────────────────────────────────────────────
+
+    /** Random float in [0, 1) */
+    float01() {
+      return Math.random();
+    },
+
+    /**
+     * Random float in [min, max).
+     * If only one argument, returns float in [0, min).
+     */
+    float(min, max) {
+      if (min === undefined) return Math.random();
+      if (max === undefined) { max = min; min = 0; }
+      return min + Math.random() * (max - min);
+    },
+
+    /** Random float in [min, max], inclusive on both ends. */
+    floatInclusive(min, max) {
+      return min + Math.random() * (max - min + Number.EPSILON);
+    },
+
+    /**
+     * Random integer in [min, max], inclusive on both ends.
+     * If only one argument, returns int in [0, min].
+     */
+    int(min, max) {
+      if (max === undefined) { max = min; min = 0; }
+      min = Math.ceil(min);
+      max = Math.floor(max);
+      return Math.floor(Math.random() * (max - min + 1)) + min;
+    },
+
+    /**
+     * Random integer in [min, max), exclusive of max.
+     */
+    intExclusive(min, max) {
+      if (max === undefined) { max = min; min = 0; }
+      min = Math.ceil(min);
+      max = Math.floor(max);
+      return Math.floor(Math.random() * (max - min)) + min;
+    },
+
+    /** Random sign: returns 1 or -1. */
+    sign() {
+      return Math.random() < 0.5 ? 1 : -1;
+    },
+
+    /** Random number rounded to a given number of decimal places. */
+    floatRounded(min, max, decimals = 2) {
+      const f = this.float(min, max);
+      return parseFloat(f.toFixed(decimals));
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // BOOLEANS
+    // ──────────────────────────────────────────────────────────────────────
+
+    /** Random boolean, 50/50. */
+    bool() {
+      return Math.random() < 0.5;
+    },
+
+    /**
+     * Random boolean with a given probability of being true.
+     * @param {number} p - Probability in [0, 1]. Default 0.5.
+     */
+    chance(p = 0.5) {
+      return Math.random() < p;
+    },
+
+    /** Roll a 1-in-n chance. Returns true if it hits. */
+    oneIn(n) {
+      return Math.floor(Math.random() * n) === 0;
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // ARRAY SAMPLING & SHUFFLING
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Pick one random item from an array.
+     * Returns undefined for empty arrays.
+     */
+    pick(arr) {
+      if (!arr || arr.length === 0) return undefined;
+      return arr[Math.floor(Math.random() * arr.length)];
+    },
+
+    /**
+     * Pick k unique random items from an array (no replacement).
+     * Returns a new array of length min(k, arr.length).
+     */
+    sample(arr, k) {
+      if (!arr || arr.length === 0) return [];
+      k = Math.min(k, arr.length);
+      const copy = arr.slice();
+      const result = [];
+      for (let i = 0; i < k; i++) {
+        const j = Math.floor(Math.random() * (copy.length - i)) + i;
+        [copy[i], copy[j]] = [copy[j], copy[i]];
+        result.push(copy[i]);
+      }
+      return result;
+    },
+
+    /**
+     * Pick k items from an array with replacement (duplicates allowed).
+     */
+    sampleWithReplacement(arr, k) {
+      if (!arr || arr.length === 0) return [];
+      const result = [];
+      for (let i = 0; i < k; i++) {
+        result.push(arr[Math.floor(Math.random() * arr.length)]);
+      }
+      return result;
+    },
+
+    /**
+     * Shuffle an array in-place using Fisher-Yates.
+     * Returns the same array.
+     */
+    shuffle(arr) {
+      for (let i = arr.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [arr[i], arr[j]] = [arr[j], arr[i]];
+      }
+      return arr;
+    },
+
+    /**
+     * Return a shuffled copy of an array without mutating the original.
+     */
+    shuffled(arr) {
+      return this.shuffle(arr.slice());
+    },
+
+    /**
+     * Pick a random key from an object.
+     */
+    pickKey(obj) {
+      const keys = Object.keys(obj);
+      return keys[Math.floor(Math.random() * keys.length)];
+    },
+
+    /**
+     * Pick a random value from an object.
+     */
+    pickValue(obj) {
+      const values = Object.values(obj);
+      return values[Math.floor(Math.random() * values.length)];
+    },
+
+    /**
+     * Pick a random entry [key, value] from an object.
+     */
+    pickEntry(obj) {
+      const entries = Object.entries(obj);
+      return entries[Math.floor(Math.random() * entries.length)];
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // WEIGHTED SELECTION
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Pick an item by weight. Weights do not need to sum to 1.
+     * @param {Array} items   - Array of items to pick from.
+     * @param {Array} weights - Parallel array of numeric weights (>= 0).
+     *
+     * @example
+     *   weighted(["common","rare","legendary"], [100, 10, 1])
+     */
+    weighted(items, weights) {
+      if (items.length !== weights.length) throw new Error("items and weights must be the same length");
+      const total = weights.reduce((s, w) => s + w, 0);
+      if (total <= 0) throw new Error("weights must sum to a positive number");
+      let r = Math.random() * total;
+      for (let i = 0; i < items.length; i++) {
+        r -= weights[i];
+        if (r <= 0) return items[i];
+      }
+      return items[items.length - 1];
+    },
+
+    /**
+     * Pick from an array of { item, weight } objects.
+     * @example
+     *   weightedObjects([{ item: "sword", weight: 5 }, { item: "shield", weight: 3 }])
+     */
+    weightedObjects(entries) {
+      return this.weighted(entries.map(e => e.item), entries.map(e => e.weight));
+    },
+
+    /**
+     * Pick multiple items by weight, with replacement.
+     */
+    weightedSample(items, weights, k) {
+      const result = [];
+      for (let i = 0; i < k; i++) result.push(this.weighted(items, weights));
+      return result;
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // DISTRIBUTIONS
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Normal (Gaussian) distribution using Box-Muller transform.
+     * @param {number} mean   - Default 0.
+     * @param {number} stddev - Default 1.
+     */
+    gaussian(mean = 0, stddev = 1) {
+      let u, v;
+      do { u = Math.random(); } while (u === 0);
+      do { v = Math.random(); } while (v === 0);
+      return mean + Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * v) * stddev;
+    },
+
+    /**
+     * Gaussian clamped to [min, max] by resampling until in range.
+     */
+    gaussianClamped(mean, stddev, min, max) {
+      let v;
+      do { v = this.gaussian(mean, stddev); } while (v < min || v > max);
+      return v;
+    },
+
+    /**
+     * Exponential distribution: models time between events.
+     * @param {number} lambda - Rate parameter (default 1). Mean = 1/lambda.
+     */
+    exponential(lambda = 1) {
+      return -Math.log(1 - Math.random()) / lambda;
+    },
+
+    /**
+     * Triangular distribution between min and max with a peak at mode.
+     * Useful for estimates (optimistic/pessimistic/likely).
+     */
+    triangular(min, mode, max) {
+      const u = Math.random();
+      const fc = (mode - min) / (max - min);
+      if (u < fc) return min + Math.sqrt(u * (max - min) * (mode - min));
+      return max - Math.sqrt((1 - u) * (max - min) * (max - mode));
+    },
+
+    /**
+     * Bernoulli trial: returns 1 with probability p, else 0.
+     */
+    bernoulli(p = 0.5) {
+      return Math.random() < p ? 1 : 0;
+    },
+
+    /**
+     * Binomial: number of successes in n Bernoulli trials with probability p.
+     */
+    binomial(n, p) {
+      let s = 0;
+      for (let i = 0; i < n; i++) if (Math.random() < p) s++;
+      return s;
+    },
+
+    /**
+     * Poisson distribution: number of events in a fixed interval.
+     * @param {number} lambda - Expected number of events (mean).
+     */
+    poisson(lambda) {
+      const L = Math.exp(-lambda);
+      let k = 0, p = 1;
+      do { k++; p *= Math.random(); } while (p > L);
+      return k - 1;
+    },
+
+    /**
+     * Beta distribution via Johnk's method.
+     * Useful for modeling probabilities and proportions.
+     * @param {number} alpha
+     * @param {number} beta
+     */
+    beta(alpha, beta) {
+      const x = this.gamma(alpha, 1);
+      const y = this.gamma(beta, 1);
+      return x / (x + y);
+    },
+
+    /**
+     * Gamma distribution using Marsaglia-Tsang's method.
+     * @param {number} shape (k)
+     * @param {number} scale (theta) - Default 1.
+     */
+    gamma(shape, scale = 1) {
+      if (shape < 1) return this.gamma(1 + shape, scale) * Math.pow(Math.random(), 1 / shape);
+      const d = shape - 1 / 3;
+      const c = 1 / Math.sqrt(9 * d);
+      while (true) {
+        let x, v;
+        do { x = this.gaussian(); v = 1 + c * x; } while (v <= 0);
+        v = v * v * v;
+        const u = Math.random();
+        if (u < 1 - 0.0331 * (x * x) * (x * x)) return d * v * scale;
+        if (Math.log(u) < 0.5 * x * x + d * (1 - v + Math.log(v))) return d * v * scale;
+      }
+    },
+
+    /**
+     * Pareto distribution.
+     * @param {number} scale  - Minimum value (xm).
+     * @param {number} shape  - Shape parameter (alpha).
+     */
+    pareto(scale, shape) {
+      return scale / Math.pow(Math.random(), 1 / shape);
+    },
+
+    /**
+     * Log-normal distribution.
+     * @param {number} mean   - Mean of the underlying normal.
+     * @param {number} stddev - Std dev of the underlying normal.
+     */
+    logNormal(mean = 0, stddev = 1) {
+      return Math.exp(this.gaussian(mean, stddev));
+    },
+
+    /**
+     * Cauchy distribution (heavy-tailed).
+     * @param {number} location - Default 0.
+     * @param {number} scale    - Default 1.
+     */
+    cauchy(location = 0, scale = 1) {
+      return location + scale * Math.tan(Math.PI * (Math.random() - 0.5));
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // SEEDED RNG (Mulberry32)
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Create a seeded pseudo-random number generator (Mulberry32).
+     * Deterministic: same seed → same sequence every time.
+     * @param {number|string} seed
+     * @returns {object} A seeded RNG with the same API surface.
+     *
+     * @example
+     *   const rng = kitRandom.seeded(42);
+     *   rng.float(0, 10);
+     *   rng.pick(["a", "b", "c"]);
+     */
+    seeded(seed) {
+      if (typeof seed === "string") {
+        seed = Array.from(seed).reduce((h, c) => Math.imul(31, h) + c.charCodeAt(0) | 0, 0);
+      }
+      let s = seed >>> 0;
+
+      const next = () => {
+        s += 0x6d2b79f5;
+        let t = s;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+      };
+
+      return {
+        _seed: seed,
+        _next: next,
+        float01:   ()           => next(),
+        float:     (min, max)   => { if (max===undefined){max=min;min=0;} return min + next()*(max-min); },
+        int:       (min, max)   => { if (max===undefined){max=min;min=0;} return Math.floor(next()*(Math.floor(max)-Math.ceil(min)+1))+Math.ceil(min); },
+        bool:      ()           => next() < 0.5,
+        chance:    (p = 0.5)    => next() < p,
+        sign:      ()           => next() < 0.5 ? 1 : -1,
+        pick:      (arr)        => arr[Math.floor(next() * arr.length)],
+        shuffle(arr) {
+          for (let i = arr.length - 1; i > 0; i--) {
+            const j = Math.floor(next() * (i + 1));
+            [arr[i], arr[j]] = [arr[j], arr[i]];
+          }
+          return arr;
+        },
+        shuffled(arr) { return this.shuffle(arr.slice()); },
+        gaussian(mean = 0, stddev = 1) {
+          let u, v;
+          do { u = next(); } while (u === 0);
+          do { v = next(); } while (v === 0);
+          return mean + Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * v) * stddev;
+        },
+        weighted(items, weights) {
+          const total = weights.reduce((s, w) => s + w, 0);
+          let r = next() * total;
+          for (let i = 0; i < items.length; i++) { r -= weights[i]; if (r <= 0) return items[i]; }
+          return items[items.length - 1];
+        },
+        uuid() {
+          return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, c => {
+            const r = Math.floor(next() * 16);
+            return (c === "x" ? r : (r & 0x3 | 0x8)).toString(16);
+          });
+        },
+      };
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // ID & TOKEN GENERATION
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Generate a UUID v4 string.
+     * Uses crypto.randomUUID() if available, falls back to Math.random().
+     */
+    uuid() {
+      if (typeof crypto !== "undefined" && crypto.randomUUID) return crypto.randomUUID();
+      return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, c => {
+        const r = Math.random() * 16 | 0;
+        return (c === "x" ? r : (r & 0x3 | 0x8)).toString(16);
+      });
+    },
+
+    /**
+     * Generate a short random ID (base62, URL-safe).
+     * @param {number} length - Default 8.
+     * @example nanoid(12) => "aB3kZ9xQ2mLp"
+     */
+    nanoid(length = 8) {
+      const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+      let id = "";
+      for (let i = 0; i < length; i++) id += chars[Math.floor(Math.random() * chars.length)];
+      return id;
+    },
+
+    /**
+     * Generate a random hex string of a given byte length.
+     * @param {number} bytes - Default 16 (128-bit).
+     * @example hex(4) => "a3f2c1b0"
+     */
+    hex(bytes = 16) {
+      let h = "";
+      for (let i = 0; i < bytes; i++) h += Math.floor(Math.random() * 256).toString(16).padStart(2, "0");
+      return h;
+    },
+
+    /**
+     * Generate a random string from a custom alphabet.
+     * @param {number} length
+     * @param {string} [alphabet]
+     */
+    string(length, alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz") {
+      let s = "";
+      for (let i = 0; i < length; i++) s += alphabet[Math.floor(Math.random() * alphabet.length)];
+      return s;
+    },
+
+    /**
+     * Generate a random numeric PIN of a given length.
+     * @param {number} length - Default 4.
+     */
+    pin(length = 4) {
+      return this.string(length, "0123456789");
+    },
+
+    /**
+     * Generate a random color in hex format.
+     * @example color() => "#a3f2c1"
+     */
+    color() {
+      return `#${this.hex(3)}`;
+    },
+
+    /**
+     * Generate a random RGB color object.
+     * @returns {{ r, g, b }}
+     */
+    rgb() {
+      return { r: this.int(0, 255), g: this.int(0, 255), b: this.int(0, 255) };
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // GEOMETRY & SPATIAL
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Random point on the surface of a unit circle.
+     * Returns { x, y } with x²+y²=1.
+     */
+    onUnitCircle() {
+      const a = Math.random() * 2 * Math.PI;
+      return { x: Math.cos(a), y: Math.sin(a) };
+    },
+
+    /**
+     * Random point inside a unit disk (uniform, not center-biased).
+     * Returns { x, y }.
+     */
+    inUnitDisk() {
+      let x, y;
+      do { x = Math.random() * 2 - 1; y = Math.random() * 2 - 1; } while (x * x + y * y >= 1);
+      return { x, y };
+    },
+
+    /**
+     * Random point on the surface of a unit sphere.
+     * Returns { x, y, z } with x²+y²+z²=1.
+     */
+    onUnitSphere() {
+      const u = Math.random() * 2 - 1;
+      const t = Math.random() * 2 * Math.PI;
+      const r = Math.sqrt(1 - u * u);
+      return { x: r * Math.cos(t), y: r * Math.sin(t), z: u };
+    },
+
+    /**
+     * Random point uniformly inside an axis-aligned bounding box.
+     * @param {{ x?: number, y?: number, w: number, h: number }} rect
+     */
+    inRect({ x = 0, y = 0, w, h }) {
+      return { x: x + Math.random() * w, y: y + Math.random() * h };
+    },
+
+    /**
+     * Random point inside an axis-aligned bounding box in 3D.
+     * @param {{ x?: number, y?: number, z?: number, w: number, h: number, d: number }} box
+     */
+    inBox({ x = 0, y = 0, z = 0, w, h, d }) {
+      return { x: x + Math.random() * w, y: y + Math.random() * h, z: z + Math.random() * d };
+    },
+
+    /**
+     * Random angle in radians in [0, 2π).
+     */
+    angle() {
+      return Math.random() * 2 * Math.PI;
+    },
+
+    /**
+     * Random direction vector in 2D (unit length).
+     * @returns {{ x, y }}
+     */
+    direction2D() {
+      return this.onUnitCircle();
+    },
+
+    /**
+     * Random direction vector in 3D (unit length).
+     * @returns {{ x, y, z }}
+     */
+    direction3D() {
+      return this.onUnitSphere();
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // DICE & GAMES
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Roll dice.
+     * @param {number} count - Number of dice.
+     * @param {number} sides - Sides per die.
+     * @returns {{ rolls: number[], total: number }}
+     * @example dice(2, 6) => { rolls: [3, 5], total: 8 }
+     */
+    dice(count, sides) {
+      const rolls = Array.from({ length: count }, () => this.int(1, sides));
+      return { rolls, total: rolls.reduce((s, v) => s + v, 0) };
+    },
+
+    /**
+     * Parse and roll standard dice notation strings.
+     * Supports: "2d6", "1d20+5", "4d6k3" (keep highest 3), "2d8-1".
+     * @returns {{ rolls, kept, modifier, total }}
+     *
+     * @example
+     *   rollNotation("4d6k3")   // roll 4d6, keep highest 3
+     *   rollNotation("1d20+5")  // roll 1d20 and add 5
+     */
+    rollNotation(notation) {
+      const m = notation.toLowerCase().match(/^(\d+)d(\d+)(?:k(\d+))?([+-]\d+)?$/);
+      if (!m) throw new Error(`Invalid dice notation: "${notation}"`);
+      const [, count, sides, keep, mod] = m;
+      const { rolls } = this.dice(Number(count), Number(sides));
+      const sorted = rolls.slice().sort((a, b) => b - a);
+      const kept = keep ? sorted.slice(0, Number(keep)) : sorted;
+      const modifier = mod ? Number(mod) : 0;
+      return { rolls, kept, modifier, total: kept.reduce((s, v) => s + v, 0) + modifier };
+    },
+
+    /**
+     * Flip a coin. Returns "heads" or "tails".
+     */
+    coin() {
+      return Math.random() < 0.5 ? "heads" : "tails";
+    },
+
+    /**
+     * Draw a random card from a standard 52-card deck.
+     * @returns {{ suit, rank, value, card }}
+     */
+    drawCard() {
+      const suits = ["♠", "♥", "♦", "♣"];
+      const ranks = ["A", "2", "3", "4", "5", "6", "7", "8", "9", "10", "J", "Q", "K"];
+      const suit  = suits[Math.floor(Math.random() * 4)];
+      const rank  = ranks[Math.floor(Math.random() * 13)];
+      const value = rank === "A" ? 11 : ["J","Q","K"].includes(rank) ? 10 : parseInt(rank);
+      return { suit, rank, value, card: `${rank}${suit}` };
+    },
+
+    /**
+     * Shuffle and return a full 52-card deck.
+     * @returns {Array<{ suit, rank, value, card }>}
+     */
+    shuffleDeck() {
+      const suits = ["♠", "♥", "♦", "♣"];
+      const ranks = ["A", "2", "3", "4", "5", "6", "7", "8", "9", "10", "J", "Q", "K"];
+      const deck = [];
+      for (const suit of suits) {
+        for (const rank of ranks) {
+          const value = rank === "A" ? 11 : ["J","Q","K"].includes(rank) ? 10 : parseInt(rank);
+          deck.push({ suit, rank, value, card: `${rank}${suit}` });
+        }
+      }
+      return this.shuffle(deck);
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // UTILITIES
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Randomly split a value into n parts that sum to total.
+     * Returns an array of n non-negative floats.
+     * @example split(100, 3) => [42.1, 31.7, 26.2]
+     */
+    split(total, n) {
+      const cuts = Array.from({ length: n - 1 }, () => Math.random() * total).sort((a, b) => a - b);
+      const parts = [];
+      let prev = 0;
+      for (const c of cuts) { parts.push(c - prev); prev = c; }
+      parts.push(total - prev);
+      return parts;
+    },
+
+    /**
+     * Randomly split a value into n integer parts that sum to total.
+     */
+    splitInt(total, n) {
+      const parts = this.split(total, n).map(Math.round);
+      const diff  = total - parts.reduce((s, v) => s + v, 0);
+      parts[0] += diff;
+      return parts;
+    },
+
+    /**
+     * Jitter a value by up to ±amount.
+     * @example jitter(100, 5) => somewhere in [95, 105]
+     */
+    jitter(value, amount) {
+      return value + (Math.random() * 2 - 1) * amount;
+    },
+
+    /**
+     * Randomly perturb each element of an array by up to ±amount.
+     */
+    jitterArray(arr, amount) {
+      return arr.map(v => this.jitter(v, amount));
+    },
+
+    /**
+     * Choose a random date between two dates.
+     * @param {Date|string} start
+     * @param {Date|string} end
+     * @returns {Date}
+     */
+    date(start, end) {
+      const s = new Date(start).getTime();
+      const e = new Date(end).getTime();
+      return new Date(s + Math.random() * (e - s));
+    },
+
+    /**
+     * Pick a random element from a Set.
+     * @param {Set} set
+     */
+    pickFromSet(set) {
+      const arr = Array.from(set);
+      return arr[Math.floor(Math.random() * arr.length)];
+    },
+
+    /**
+     * Pick a random element from a Map (returns [key, value]).
+     * @param {Map} map
+     */
+    pickFromMap(map) {
+      const entries = Array.from(map.entries());
+      return entries[Math.floor(Math.random() * entries.length)];
+    },
+
+    /**
+     * Generate a random IPv4 address.
+     */
+    ipv4() {
+      return Array.from({ length: 4 }, () => this.int(0, 255)).join(".");
+    },
+
+    /**
+     * Generate a random MAC address.
+     */
+    mac() {
+      return Array.from({ length: 6 }, () => this.hex(1).padStart(2, "0")).join(":");
+    },
+
+    /**
+     * Randomly rotate an array by a random amount.
+     * @param {Array} arr
+     * @returns {Array}
+     */
+    rotate(arr) {
+      const n = this.int(0, arr.length - 1);
+      return [...arr.slice(n), ...arr.slice(0, n)];
+    },
+
+    /**
+     * Return true with probability 1/n, simulating a random event trigger.
+     * Alias for oneIn() with more semantic naming.
+     */
+    trigger(n) {
+      return this.oneIn(n);
+    },
+
+  }
+};