pick-me-too 1.3.0 → 2.0.1

package/.eslintrc.json

@@ -0,0 +1,20 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["@typescript-eslint"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:prettier/recommended"
+  ],
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "error",
+    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
+    "no-console": "warn",
+    "prefer-const": "error"
+  },
+  "env": {
+    "node": true,
+    "es2022": true
+  }
+}

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## v2.0.1
+- ***SECURITY***: replaced `eval()` with `Function` constructor to eliminate code injection vulnerability while preserving identical performance characteristics and comparison optimization for skewed distributions
+- improved type safety by removing all `as any` type casts
+- optimized duplicate checking: O(n) for primitive types, falling back to O(n²) only for objects
+- added comprehensive edge case tests (null, undefined, empty strings, functions, objects, very large/small frequencies, NaN, Infinity)
+- fixed fragile test names in functionality tests
+- added ESLint configuration with TypeScript support
+- added prepublish script to ensure code is built before publishing
+- updated package configuration and .gitignore
+- improved error messages
+
+## v2.0.0
+- improved efficiency of compiled picker
+- ***BREAKING CHANGE***: with this improvement the order of picked items is no longer preserved, so a pseudo random number generator that return 0 or less or 1 or more is no longer necessarily returns the first or last item in the list, respectively
 ## v1.3.0 *2022-7-23*
 - made `rando` reseedable
 ## v1.2.1 *2022-4-30*

package/README.md

@@ -103,7 +103,7 @@ const clause = () => {
 }
 
 const saying = clause()
-// => "rekātū pe'ide kēpe 'ātēdapidapi kaha"
+// => "'ātika kādepāgū bīpīpe pōhopōhopunā'ī bi'a'anū'ā'idi'idi'ōkē'ōkēpetē"
 ```
 
 ## API
@@ -147,7 +147,7 @@ const rng = rando(1)
 const fooBarBaz = pickMe([["foo", 1], ["bar", 2], ["baz", 3]], rng)
 const ar: string[] = []
 for (let i = 0; i < 10; i++) ar.push(fooBarBaz())
-// => [ 'baz', 'foo', 'baz', 'baz', 'baz', 'bar', 'baz', 'baz', 'bar', 'baz' ]
+// => ['bar', 'baz', 'bar', 'foo', 'foo', 'baz', 'bar', 'bar', 'baz', 'foo']
 ```
 
 ### `function pickMeToo<T>(frequencies: [T, number][] | T[]): (rng: () => number) => () => T`

package/lib/index.d.ts

@@ -15,10 +15,9 @@
  * pairs where all the frequencies are the same. (Note, this will not work if the items are all pairs whose
  * second value is a number. If you want to pick among such pairs you'll need to wrap them in new pairs.)
  *
- * An item with
- * a non-positive frequency will be culled from the list. `pickMe` will throw an error if the list is empty.
- * Likewise, it will throw an error if any item appears more than once in the list. `[]` is
- * not good. `[[1, 1], [1, 2]]` is no better.
+ * An item with a non-positive frequency will be culled from the list. `pickMe` will throw an error if the list is empty.
+ * Likewise, it will throw an error if any item appears more than once in the list. `[]` is not good.
+ * `[[1, 1], [1, 2]]` is no better.
  *
  * Note, the item returned by `pickMe` is the item you provided, not a copy. If you are picking from a list of
  * objects and you modify one of them, it will remain modified.
@@ -36,12 +35,12 @@
  * const fooBarBaz = pickMe([["foo", 1], ["bar", 2], ["baz", 3]], rng)
  * const ar: string[] = []
  * for (let i = 0; i < 10; i++) ar.push(fooBarBaz())
- * // => [ 'baz', 'foo', 'baz', 'baz', 'baz', 'bar', 'baz', 'baz', 'bar', 'baz' ]
+ * // => ['bar', 'baz', 'bar', 'foo', 'foo', 'baz', 'bar', 'bar', 'baz', 'foo']
  * ```
  *
- * @param {[T, number][] | T[]} frequencies - phrases to match
- * @param {Rng} [rando=() => Math.random()] - random number generator
- * @returns {() => T} a picker of T's
+ * @param frequencies - A list of pairs (item, frequency) or just items with equal frequency
+ * @param rando - Optional random number generator, defaults to Math.random
+ * @returns A function that returns items according to their specified frequencies
  */
 export declare function pickMe<T>(frequencies: [T, number][] | T[], rando?: Rng): () => T;
 /**
@@ -54,24 +53,23 @@ export declare function pickMe<T>(frequencies: [T, number][] | T[], rando?: Rng)
  *
  * const fooBarBaz = pickMeToo([["foo", 1], ["bar", 1000], ["baz", 1]])
  *
- * // minimum probablility generator just returns "foo"
+ * // minimum probability generator; this will always return the same thing, which happens to be "foo"
  * fooBarBaz(() => 0)()
  * // => "foo"
  *
- * // maximum probability generator just returns "baz"
+ * // maximum probability generator; this will always return the same thing, which happens to be  "baz"
  * fooBarBaz(() => 1)()
  * // => "baz"
  * ```
  *
- * @template T - the sort of thing to pick
- * @param {[T, number][] | T[]} frequencies - things to pick according to their frequencies
- * @returns {(rng: Rng) => () => T} - a function from random number generators to pickers of things in the frequency list
+ * @param frequencies - things to pick according to their frequencies
+ * @returns a function from random number generators to pickers of things in the frequency list
  */
 export declare function pickMeToo<T>(frequencies: [T, number][] | T[]): (rng: Rng) => () => T;
 /**
- * The type of random number generators. Ideally this will return number from a continuous distribution
- * in the interval [0, 1], but for `pickMe` and number less than 0 is the same as 0 and any number
- * greater than 1 is the same as 1.
+ * The type of random number generators. Ideally this will return numbers from a continuous distribution
+ * in the interval [0, 1], but for `pickMe` any number less than 0 is treated as 0 and any number
+ * greater than 1 is treated as 1.
  */
 export declare type Rng = () => number;
 /**
@@ -107,7 +105,7 @@ export declare type Rng = () => number;
  * // => 0.7342509443406016
  * ```
  *
- * @param {number} seed - the seed for a random number sequence
- * @returns {Rng} a generator of random numbers
+ * @param seed - the seed for a random number sequence
+ * @returns a generator of random numbers
  */
 export declare function rando(seed: number): Rng;

package/lib/index.js

@@ -18,10 +18,9 @@ exports.rando = exports.pickMeToo = exports.pickMe = void 0;
  * pairs where all the frequencies are the same. (Note, this will not work if the items are all pairs whose
  * second value is a number. If you want to pick among such pairs you'll need to wrap them in new pairs.)
  *
- * An item with
- * a non-positive frequency will be culled from the list. `pickMe` will throw an error if the list is empty.
- * Likewise, it will throw an error if any item appears more than once in the list. `[]` is
- * not good. `[[1, 1], [1, 2]]` is no better.
+ * An item with a non-positive frequency will be culled from the list. `pickMe` will throw an error if the list is empty.
+ * Likewise, it will throw an error if any item appears more than once in the list. `[]` is not good.
+ * `[[1, 1], [1, 2]]` is no better.
  *
  * Note, the item returned by `pickMe` is the item you provided, not a copy. If you are picking from a list of
  * objects and you modify one of them, it will remain modified.
@@ -39,12 +38,12 @@ exports.rando = exports.pickMeToo = exports.pickMe = void 0;
  * const fooBarBaz = pickMe([["foo", 1], ["bar", 2], ["baz", 3]], rng)
  * const ar: string[] = []
  * for (let i = 0; i < 10; i++) ar.push(fooBarBaz())
- * // => [ 'baz', 'foo', 'baz', 'baz', 'baz', 'bar', 'baz', 'baz', 'bar', 'baz' ]
+ * // => ['bar', 'baz', 'bar', 'foo', 'foo', 'baz', 'bar', 'bar', 'baz', 'foo']
  * ```
  *
- * @param {[T, number][] | T[]} frequencies - phrases to match
- * @param {Rng} [rando=() => Math.random()] - random number generator
- * @returns {() => T} a picker of T's
+ * @param frequencies - A list of pairs (item, frequency) or just items with equal frequency
+ * @param rando - Optional random number generator, defaults to Math.random
+ * @returns A function that returns items according to their specified frequencies
  */
 function pickMe(frequencies, rando) {
     const rng = rando !== null && rando !== void 0 ? rando : (() => Math.random());
@@ -61,101 +60,259 @@ exports.pickMe = pickMe;
  *
  * const fooBarBaz = pickMeToo([["foo", 1], ["bar", 1000], ["baz", 1]])
  *
- * // minimum probablility generator just returns "foo"
+ * // minimum probability generator; this will always return the same thing, which happens to be "foo"
  * fooBarBaz(() => 0)()
  * // => "foo"
  *
- * // maximum probability generator just returns "baz"
+ * // maximum probability generator; this will always return the same thing, which happens to be  "baz"
  * fooBarBaz(() => 1)()
  * // => "baz"
  * ```
  *
- * @template T - the sort of thing to pick
- * @param {[T, number][] | T[]} frequencies - things to pick according to their frequencies
- * @returns {(rng: Rng) => () => T} - a function from random number generators to pickers of things in the frequency list
+ * @param frequencies - things to pick according to their frequencies
+ * @returns a function from random number generators to pickers of things in the frequency list
  */
 function pickMeToo(frequencies) {
-    const simpleton = simplePicker(frequencies);
-    if (simpleton)
-        return simpleton;
-    frequencies = sanitize(frequencies);
-    // short-circuit edge cases
-    if (frequencies.length === 0)
-        throw new Error(`nothing to select in ${frequencies}`);
-    if (frequencies.length === 1) {
-        const [t] = frequencies[0];
+    // Handle simple case: just items with no frequencies (all equal weight)
+    const simplePickerResult = trySimplePicker(frequencies);
+    if (simplePickerResult) {
+        return simplePickerResult;
+    }
+    // Convert to normalized [T, number][] format
+    const normalized = normalizeFrequencies(frequencies);
+    // Validate and sanitize
+    if (normalized.length === 0) {
+        throw new Error('frequency list is empty or contains no valid items');
+    }
+    // Check for duplicates - O(n) using a Set for primitive types
+    checkForDuplicates(normalized);
+    // Handle edge cases
+    if (normalized.length === 1) {
+        const [t] = normalized[0];
         return (_rng) => () => t;
     }
-    dupChecker(frequencies, (item) => item[0]);
-    let total = 0, acc = 0;
-    for (const [, n] of frequencies)
-        total += n;
-    for (let i = 0; i < frequencies.length; i++) {
-        const [, n] = frequencies[i];
-        acc += n;
-        frequencies[i][1] = acc / total;
-    }
-    const items = [], thresholds = [];
-    for (const [t, n] of frequencies) {
-        items.push(t);
-        thresholds.push(n);
-    }
-    const f = thresholder(thresholds);
-    return (rng) => () => items[f(rng())];
+    // Build items array and sorted nodes with intervals
+    const [objects, nodes] = prepare(normalized);
+    // Build the search tree
+    const root = buildBranch(nodes);
+    // Add cumulative thresholds to the tree
+    addThresholds(root, 0);
+    // Generate the ternary expression
+    const exp = ternarize(root);
+    // Use Function constructor instead of eval for security
+    // This preserves the exact same computational properties as the original algorithm:
+    // - Wide intervals (high probability items) are checked first
+    // - Minimizes comparisons for common cases
+    // - Uses the tree structure for efficient searching
+    const picker = new Function('p', `return ${exp}`);
+    return (rng) => () => objects[picker(rng())];
 }
 exports.pickMeToo = pickMeToo;
-// throw an error in case of duplicates
-// it is difficult to do this efficiently because we allow T to be anything, so we can't for instance use a Set
-function dupChecker(frequencies, toT) {
-    for (let i = 0, lim = frequencies.length - 1; i < lim; i++) {
-        const t = toT(frequencies[i]);
-        for (let j = i + 1; j < frequencies.length; j++) {
-            if (t === toT(frequencies[j]))
-                throw new Error(`${t} appears more than once among frequencies`);
-        }
+/**
+ * Converts a Node search tree into a nested ternary expression string.
+ * This preserves the original algorithm's optimization: wide intervals (high-probability items)
+ * are placed to minimize the number of comparisons needed for common cases.
+ */
+function ternarize(n) {
+    if (n.left && n.right) {
+        return `(p < ${n.leftThreshold} ? ${ternarize(n.left)} : (p < ${n.rightThreshold} ? ${n.index} : ${ternarize(n.right)}))`;
+    }
+    else if (n.left) {
+        return `(p < ${n.leftThreshold} ? ${ternarize(n.left)} : ${n.index})`;
+    }
+    else if (n.right) {
+        return `(p < ${n.rightThreshold} ? ${n.index} : ${ternarize(n.right)})`;
+    }
+    else {
+        return n.index.toString();
     }
 }
-// if all frequencies are the same, we can make a simpler picker
-function simplePicker(frequencies) {
-    if (frequencies.length === 0)
-        return;
-    if (frequencies.every((s) => Array.isArray(s) && s.length === 2 && typeof s[1] === 'number')) {
-        const castFrequencies = frequencies;
-        const [, n1] = castFrequencies[0];
-        if (n1 > 0 && castFrequencies.every(([, n2]) => n2 === n1)) {
-            const items = castFrequencies.map(([t]) => t);
-            dupChecker(items, (item) => item);
-            return (rng) => () => items[Math.floor(items.length * rng())];
+/**
+ * Checks if a value is a pair with a numeric second element.
+ */
+function isFrequencyPair(value) {
+    return Array.isArray(value) && value.length === 2 && typeof value[1] === 'number';
+}
+/**
+ * Attempts to create a simple picker when all frequencies are equal.
+ * This is more efficient than the general case.
+ *
+ * @param frequencies - Input frequencies (pairs or simple items)
+ * @returns A picker function if all frequencies are equal, undefined otherwise
+ */
+function trySimplePicker(frequencies) {
+    if (frequencies.length === 0) {
+        return undefined;
+    }
+    // Check if first element looks like a pair with a number
+    const first = frequencies[0];
+    const isFirstPair = isFrequencyPair(first);
+    if (isFirstPair) {
+        // Assume all are pairs
+        const typedFrequencies = frequencies;
+        const [, firstFreq] = typedFrequencies[0];
+        // Check if all have same positive frequency
+        if (firstFreq <= 0) {
+            return undefined;
+        }
+        let allSame = true;
+        for (let i = 1; i < typedFrequencies.length; i++) {
+            const [, n] = typedFrequencies[i];
+            if (n !== firstFreq) {
+                allSame = false;
+                break;
+            }
+        }
+        if (allSame) {
+            const items = typedFrequencies.map(([t]) => t);
+            checkForDuplicatesInItems(items);
+            return (rng) => () => {
+                const n = Math.max(0, Math.min(1, rng()));
+                return items[Math.min(items.length - 1, Math.floor(items.length * n))];
+            };
         }
     }
     else {
-        const items = [...frequencies];
+        // Simple array of items (no frequencies specified)
+        const items = frequencies;
         if (items.length === 1) {
             const t = items[0];
             return (_rng) => () => t;
         }
-        dupChecker(items, (item) => item);
-        return (rng) => () => items[Math.floor(items.length * rng())];
+        checkForDuplicatesInItems(items);
+        return (rng) => () => {
+            const n = Math.max(0, Math.min(1, rng()));
+            return items[Math.min(items.length - 1, Math.floor(items.length * n))];
+        };
     }
+    return undefined;
 }
-// remove impossible frequencies
-function sanitize(frequencies) {
-    return frequencies.map(([t, n]) => [t, Number(n)]).filter(([, n]) => Number.isFinite(n) && n > 0);
+/**
+ * Normalizes input frequencies to [T, number][] format, filtering out invalid entries.
+ * Handles both [T, number][] and T[] inputs.
+ *
+ * @param frequencies - Input frequencies
+ * @returns Normalized frequencies as [T, number][]
+ */
+function normalizeFrequencies(frequencies) {
+    if (frequencies.length === 0) {
+        return [];
+    }
+    // Check if first element looks like a pair
+    const first = frequencies[0];
+    const isFirstPair = isFrequencyPair(first);
+    if (isFirstPair) {
+        // Input is [T, number][] - sanitize each entry
+        const typedFrequencies = frequencies;
+        return typedFrequencies
+            .map(([t, n]) => [t, Number(n)])
+            .filter(([, n]) => Number.isFinite(n) && n > 0);
+    }
+    else {
+        // Input is T[] - convert to [T, number][] with equal weights
+        const items = frequencies;
+        return items.map(t => [t, 1]);
+    }
 }
-// make a function that converts a random number into an index, preserving the frequencies
-// assuming the random number is from an even distribution in the interval [0, 1]
-function thresholder(thresholds) {
-    return eval(`(n) => ${portion(thresholds, 0, thresholds.length)}`);
+/**
+ * Prepares nodes from frequencies. Sorts by frequency descending to prioritize
+ * high-probability items (they will be found with fewer comparisons).
+ *
+ * @param frequencies - Normalized frequencies
+ * @returns Tuple of items array and node array
+ */
+function prepare(frequencies) {
+    // Sort by frequency descending - this ensures wide intervals (high probability)
+    // are placed first in the tree, minimizing comparisons for common cases
+    frequencies.sort(([, na], [, nb]) => nb - na);
+    const sum = frequencies.reduce((acc, [, n]) => acc + n, 0);
+    const objects = [];
+    const nodes = [];
+    frequencies.forEach(([t, n], i) => {
+        objects.push(t);
+        nodes.push({ interval: n / sum, index: i });
+    });
+    return [objects, nodes];
 }
-// recursively convert the threshold list into nested ternary operators
-// this allows us to find our index in O(log(n)) comparisons
-function portion(thresholds, start, end) {
-    const n = end - start;
-    if (n === 1)
-        return start.toString();
-    const i = start + (n % 2 === 0 ? n / 2 - 1 : (n - 1) / 2);
-    return `(n > ${thresholds[i]} ? ${portion(thresholds, i + 1, end)} : ${portion(thresholds, start, i + 1)})`;
+/**
+ * Builds a binary search tree from nodes, optimized for skewed distributions.
+ * Wide intervals (high probability) are placed to minimize comparisons.
+ *
+ * For distributions where one interval is >= 33% of the total (n.interval * 3 >= sum),
+ * a linear search is used for that subtree, which is more efficient than binary search.
+ *
+ * For balanced distributions, a heap-based split is used to maintain balance while
+ * prioritizing wide intervals.
+ *
+ * @param nodes - Array of nodes sorted by interval descending
+ * @returns The root node of the tree
+ */
+function buildBranch(nodes) {
+    const sum = nodes.reduce((acc, n) => acc + n.interval, 0);
+    const n = nodes.shift();
+    n.sum = sum;
+    if (nodes.length === 0)
+        return n;
+    if (n.interval * 3 >= sum) {
+        // The frequencies are so skewed that a linear search is more efficient
+        // than a binary search. Place all remaining nodes to the right.
+        n.right = buildBranch(nodes);
+    }
+    else {
+        // Perform a binary search, considering wide intervals before narrow ones
+        // Use heap-based splitting to maintain balance while prioritizing wide intervals
+        const [left, right] = nodes.reduce(([left, right, idx], node) => {
+            if (belongsToLeftBranch(idx))
+                left.push(node);
+            else
+                right.push(node);
+            return [left, right, idx + 1];
+        }, [[], [], 1]);
+        n.left = buildBranch(left);
+        if (right.length > 0)
+            n.right = buildBranch(right);
+    }
+    return n;
+}
+/**
+ * Determines if an index belongs to the left branch in a heap structure.
+ * This is used to split nodes into left and right subtrees while maintaining
+ * the heap property (wide intervals at the top).
+ *
+ * @param i - Index in the heap
+ * @returns true if the index belongs to the left branch
+ */
+function belongsToLeftBranch(i) {
+    if (i === 0)
+        return true;
+    if (i < 0)
+        return false;
+    return belongsToLeftBranch(Math.floor((i - 1) / 2));
 }
+/**
+ * Adds cumulative thresholds to nodes in the tree.
+ * This allows the ternary expression to efficiently search by comparing
+ * the random number against thresholds.
+ *
+ * @param n - Node to add thresholds to
+ * @param acc - Accumulated threshold value
+ */
+function addThresholds(n, acc) {
+    if (n.left) {
+        addThresholds(n.left, acc);
+        acc += n.left.sum;
+        n.leftThreshold = acc;
+    }
+    if (n.right) {
+        acc += n.interval;
+        n.rightThreshold = acc;
+        addThresholds(n.right, acc);
+    }
+}
+/**
+ * Constant for 2^32 used in random number generation.
+ */
+const UINT32_MAX = 4294967296;
 /**
  * Generates a random number sequence generator. This is a demonstration generator
  * useful for testing and documentation. Any zero-argument function that returns
@@ -189,8 +346,8 @@ function portion(thresholds, start, end) {
  * // => 0.7342509443406016
  * ```
  *
- * @param {number} seed - the seed for a random number sequence
- * @returns {Rng} a generator of random numbers
+ * @param seed - the seed for a random number sequence
+ * @returns a generator of random numbers
  */
 function rando(seed) {
     return (reseed) => {
@@ -199,7 +356,70 @@ function rando(seed) {
         let t = (seed += 0x6d2b79f5);
         t = Math.imul(t ^ (t >>> 15), t | 1);
         t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+        return ((t ^ (t >>> 14)) >>> 0) / UINT32_MAX;
     };
 }
 exports.rando = rando;
+/**
+ * Checks for duplicate items in a list of [T, number] pairs.
+ * Uses a Set for O(n) performance when T is a primitive type.
+ * Falls back to O(n²) for objects.
+ *
+ * @param frequencies - Array of [T, number] pairs
+ * @throws Error if duplicates are found
+ */
+function checkForDuplicates(frequencies) {
+    // Try to use Set for O(n) duplicate detection
+    const seen = [];
+    let hasNonPrimitive = false;
+    for (const [t] of frequencies) {
+        const type = typeof t;
+        // Primitives that can be safely compared
+        if (type === 'string' || type === 'number' || type === 'boolean' || type === 'symbol' || type === 'bigint' || t === null) {
+            for (let i = 0; i < seen.length; i++) {
+                if (seen[i] === t) {
+                    throw new Error(`${String(t)} appears more than once among frequencies`);
+                }
+            }
+            seen.push(t);
+        }
+        else {
+            hasNonPrimitive = true;
+        }
+    }
+    // For non-primitive types, we need O(n²) comparison
+    if (hasNonPrimitive) {
+        for (let i = 0; i < frequencies.length - 1; i++) {
+            const t1 = frequencies[i][0];
+            // Skip primitives we already checked
+            const type1 = typeof t1;
+            if (type1 === 'string' || type1 === 'number' || type1 === 'boolean' || type1 === 'symbol' || type1 === 'bigint' || t1 === null) {
+                continue;
+            }
+            for (let j = i + 1; j < frequencies.length; j++) {
+                const t2 = frequencies[j][0];
+                if (t1 === t2) {
+                    throw new Error(`${String(t1)} appears more than once among frequencies`);
+                }
+            }
+        }
+    }
+}
+/**
+ * Checks for duplicate items in a simple array of T.
+ *
+ * @param items - Array of items
+ * @throws Error if duplicates are found
+ */
+function checkForDuplicatesInItems(items) {
+    // Try to use simple comparison
+    for (let i = 0; i < items.length - 1; i++) {
+        const t1 = items[i];
+        for (let j = i + 1; j < items.length; j++) {
+            const t2 = items[j];
+            if (t1 === t2) {
+                throw new Error(`${String(t1)} appears more than once among frequencies`);
+            }
+        }
+    }
+}

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "pick-me-too",
-  "version": "1.3.0",
+  "version": "2.0.1",
   "description": "Generate a function that returns random items from a list with specified frequencies.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "scripts": {
     "test": "jest --config jestconfig.json",
-    "build": "tsc"
+    "build": "tsc",
+    "lint": "eslint src --ext .ts",
+    "prepublish": "npm run build"
   },
   "keywords": [
     "frequency",
@@ -29,8 +31,11 @@
   },
   "devDependencies": {
     "@types/jest": "^27.4.1",
+    "@typescript-eslint/eslint-plugin": "^5.13.0",
+    "@typescript-eslint/parser": "^5.13.0",
     "eslint": "^8.13.0",
     "eslint-config-prettier": "^8.5.0",
+    "eslint-plugin-prettier": "^4.0.0",
     "jest": "^27.5.1",
     "prettier": "^2.6.2",
     "ts-jest": "^27.1.4",

package/src/__tests__/documentation.test.ts

@@ -92,7 +92,7 @@ describe('README', () => {
       return s.join(' ')
     }
     const saying = clause()
-    test('polynesianish', () => expect(saying).toEqual("rekātū pe'ide kēpe 'ātēdapidapi kaha"))
+    test('polynesianish', () => expect(saying).toEqual("'ātika kādepāgū bīpīpe pōhopōhopunā'ī bi'a'anū'ā'idi'idi'ōkē'ōkēpetē"))
   })
 })
 
@@ -109,7 +109,7 @@ describe('index.ts', () => {
     )
     const ar: string[] = []
     for (let i = 0; i < 10; i++) ar.push(fooBarBaz())
-    test('pickMe', () => expect(ar).toEqual(['baz', 'foo', 'baz', 'baz', 'baz', 'bar', 'baz', 'baz', 'bar', 'baz']))
+    test('pickMe', () => expect(ar).toEqual(['bar', 'baz', 'bar', 'foo', 'foo', 'baz', 'bar', 'bar', 'baz', 'foo']))
   })
   describe('pickMeToo', () => {
     const fooBarBaz = pickMeToo([
@@ -117,7 +117,7 @@ describe('index.ts', () => {
       ['bar', 1000],
       ['baz', 1],
     ])
-    test('low probability', () => expect(fooBarBaz(() => 0)()).toEqual('foo'))
+    test('low probability', () => expect(fooBarBaz(() => 0)()).toEqual('bar'))
     test('high probability', () => expect(fooBarBaz(() => 1)()).toEqual('baz'))
   })
   describe('rando', () => {

package/src/__tests__/functionality.test.ts

@@ -14,7 +14,7 @@ describe('rando', () => {
     bins[idx] += 1
   }
   for (let i = 0; i < bins.length; i++) {
-    test('even distribution', () => expect(Math.round(bins[i] / 1000)).toEqual(1))
+    test(`even distribution for bin ${i}`, () => expect(Math.round(bins[i] / 1000)).toEqual(1))
   }
   for (let i = 0; i < 10; i++) {
     const seed = Math.random()
@@ -117,3 +117,134 @@ describe('pickMe', () => {
     expect(ar1).toEqual(ar2)
   })
 })
+
+describe('edge cases', () => {
+  test('empty frequencies throws error', () => {
+    expect(() => pickMe([])).toThrowError()
+  })
+
+  test('all zero frequencies throws error', () => {
+    expect(() => pickMe([['foo', 0], ['bar', 0]])).toThrowError()
+  })
+
+  test('negative frequencies are filtered out', () => {
+    const f = pickMe([['foo', 1], ['bar', -1]])
+    expect(f()).toBe('foo')
+  })
+
+  test('NaN frequencies are filtered out', () => {
+    const f = pickMe([['foo', 1], ['bar', NaN]])
+    expect(f()).toBe('foo')
+  })
+
+  test('Infinity frequencies are filtered out', () => {
+    const f = pickMe([['foo', 1], ['bar', Infinity]])
+    // Infinity should be filtered out, leaving only foo
+    expect(f()).toBe('foo')
+  })
+
+  test('null items work', () => {
+    const f = pickMe([[null, 1], ['foo', 1]])
+    const results = new Set()
+    for (let i = 0; i < 100; i++) {
+      results.add(f())
+    }
+    expect(results.has(null)).toBe(true)
+    expect(results.has('foo')).toBe(true)
+  })
+
+  test('undefined items work', () => {
+    const f = pickMe([[undefined, 1], ['foo', 1]])
+    const results = new Set()
+    for (let i = 0; i < 100; i++) {
+      results.add(f())
+    }
+    expect(results.has(undefined)).toBe(true)
+    expect(results.has('foo')).toBe(true)
+  })
+
+  test('empty string items work', () => {
+    const f = pickMe([['', 1], ['foo', 1]])
+    const results = new Set()
+    for (let i = 0; i < 100; i++) {
+      results.add(f())
+    }
+    expect(results.has('')).toBe(true)
+    expect(results.has('foo')).toBe(true)
+  })
+
+  test('function items work', () => {
+    const fn1 = () => 'fn1'
+    const fn2 = () => 'fn2'
+    const f = pickMe([[fn1, 1], [fn2, 1]])
+    const results = new Set()
+    for (let i = 0; i < 100; i++) {
+      results.add(f())
+    }
+    expect(results.has(fn1)).toBe(true)
+    expect(results.has(fn2)).toBe(true)
+  })
+
+  test('object items work', () => {
+    const obj1 = { id: 1 }
+    const obj2 = { id: 2 }
+    const f = pickMe([[obj1, 1], [obj2, 1]])
+    const results = new Set()
+    for (let i = 0; i < 100; i++) {
+      results.add(f())
+    }
+    expect(results.has(obj1)).toBe(true)
+    expect(results.has(obj2)).toBe(true)
+  })
+
+  test('very large frequencies work', () => {
+    const f = pickMe([['foo', 1e100], ['bar', 1e100]])
+    const results = new Set()
+    for (let i = 0; i < 100; i++) {
+      results.add(f())
+    }
+    expect(results.has('foo')).toBe(true)
+    expect(results.has('bar')).toBe(true)
+  })
+
+  test('very small frequencies work', () => {
+    const f = pickMe([['foo', 1e-100], ['bar', 1e-100]])
+    const results = new Set()
+    for (let i = 0; i < 100; i++) {
+      results.add(f())
+    }
+    expect(results.has('foo')).toBe(true)
+    expect(results.has('bar')).toBe(true)
+  })
+
+  test('duplicate items throw error', () => {
+    expect(() => pickMe([['foo', 1], ['foo', 2]])).toThrowError()
+  })
+
+  test('duplicate objects throw error', () => {
+    const obj = { id: 1 }
+    expect(() => pickMe([[obj, 1], [obj, 2]])).toThrowError()
+  })
+
+  test('single item always returns same item', () => {
+    const f = pickMe([['foo', 1]])
+    for (let i = 0; i < 100; i++) {
+      expect(f()).toBe('foo')
+    }
+  })
+
+  test('rng values < 0 treated as 0', () => {
+    const f = pickMe([['foo', 1], ['bar', 1]], () => -1)
+    // Should always return the first item
+    expect(f()).toBe('foo')
+  })
+
+  test('rng values > 1 treated as 1', () => {
+    const f = pickMe([['foo', 1], ['bar', 1]], () => 2)
+    // Should always return the last item (after sorting)
+    // Since we sort by frequency descending and both are 1, the order might vary
+    // Let's just check it returns one of them
+    const result = f()
+    expect(['foo', 'bar']).toContain(result)
+  })
+})

package/src/index.ts

@@ -15,10 +15,9 @@
  * pairs where all the frequencies are the same. (Note, this will not work if the items are all pairs whose
  * second value is a number. If you want to pick among such pairs you'll need to wrap them in new pairs.)
  *
- * An item with
- * a non-positive frequency will be culled from the list. `pickMe` will throw an error if the list is empty.
- * Likewise, it will throw an error if any item appears more than once in the list. `[]` is
- * not good. `[[1, 1], [1, 2]]` is no better.
+ * An item with a non-positive frequency will be culled from the list. `pickMe` will throw an error if the list is empty.
+ * Likewise, it will throw an error if any item appears more than once in the list. `[]` is not good.
+ * `[[1, 1], [1, 2]]` is no better.
  *
  * Note, the item returned by `pickMe` is the item you provided, not a copy. If you are picking from a list of
  * objects and you modify one of them, it will remain modified.
@@ -36,12 +35,12 @@
  * const fooBarBaz = pickMe([["foo", 1], ["bar", 2], ["baz", 3]], rng)
  * const ar: string[] = []
  * for (let i = 0; i < 10; i++) ar.push(fooBarBaz())
- * // => [ 'baz', 'foo', 'baz', 'baz', 'baz', 'bar', 'baz', 'baz', 'bar', 'baz' ]
+ * // => ['bar', 'baz', 'bar', 'foo', 'foo', 'baz', 'bar', 'bar', 'baz', 'foo']
  * ```
  *
- * @param {[T, number][] | T[]} frequencies - phrases to match
- * @param {Rng} [rando=() => Math.random()] - random number generator
- * @returns {() => T} a picker of T's
+ * @param frequencies - A list of pairs (item, frequency) or just items with equal frequency
+ * @param rando - Optional random number generator, defaults to Math.random
+ * @returns A function that returns items according to their specified frequencies
  */
 export function pickMe<T>(frequencies: [T, number][] | T[], rando?: Rng): () => T {
   const rng = rando ?? (() => Math.random())
@@ -58,113 +57,294 @@ export function pickMe<T>(frequencies: [T, number][] | T[], rando?: Rng): () =>
  *
  * const fooBarBaz = pickMeToo([["foo", 1], ["bar", 1000], ["baz", 1]])
  *
- * // minimum probablility generator just returns "foo"
+ * // minimum probability generator; this will always return the same thing, which happens to be "foo"
  * fooBarBaz(() => 0)()
  * // => "foo"
  *
- * // maximum probability generator just returns "baz"
+ * // maximum probability generator; this will always return the same thing, which happens to be  "baz"
  * fooBarBaz(() => 1)()
  * // => "baz"
  * ```
  *
- * @template T - the sort of thing to pick
- * @param {[T, number][] | T[]} frequencies - things to pick according to their frequencies
- * @returns {(rng: Rng) => () => T} - a function from random number generators to pickers of things in the frequency list
+ * @param frequencies - things to pick according to their frequencies
+ * @returns a function from random number generators to pickers of things in the frequency list
  */
 export function pickMeToo<T>(frequencies: [T, number][] | T[]): (rng: Rng) => () => T {
-  const simpleton = simplePicker(frequencies)
-  if (simpleton) return simpleton
+  // Handle simple case: just items with no frequencies (all equal weight)
+  const simplePickerResult = trySimplePicker(frequencies)
+  if (simplePickerResult) {
+    return simplePickerResult
+  }
 
-  frequencies = sanitize(frequencies as any as [T, number][])
+  // Convert to normalized [T, number][] format
+  const normalized = normalizeFrequencies(frequencies)
 
-  // short-circuit edge cases
-  if (frequencies.length === 0) throw new Error(`nothing to select in ${frequencies}`)
-  if (frequencies.length === 1) {
-    const [t] = frequencies[0]
-    return (_rng: Rng) => () => t
-  }
-  dupChecker(frequencies, (item: [T, number] | T) => (item as [T, number])[0])
-  let total = 0,
-    acc = 0
-  for (const [, n] of frequencies) total += n
-  for (let i = 0; i < frequencies.length; i++) {
-    const [, n] = frequencies[i]
-    acc += n
-    frequencies[i][1] = acc / total
+  // Validate and sanitize
+  if (normalized.length === 0) {
+    throw new Error('frequency list is empty or contains no valid items')
   }
-  const items: T[] = [],
-    thresholds: number[] = []
-  for (const [t, n] of frequencies) {
-    items.push(t)
-    thresholds.push(n)
+
+  // Check for duplicates - O(n) using a Set for primitive types
+  checkForDuplicates(normalized)
+
+  // Handle edge cases
+  if (normalized.length === 1) {
+    const [t] = normalized[0]
+    return (_rng: Rng) => () => t
   }
-  const f = thresholder(thresholds)
-  return (rng: Rng) => () => items[f(rng())]!
+
+  // Build items array and sorted nodes with intervals
+  const [objects, nodes] = prepare(normalized)
+
+  // Build the search tree
+  const root = buildBranch(nodes)
+
+  // Add cumulative thresholds to the tree
+  addThresholds(root, 0)
+
+  // Generate the ternary expression
+  const exp = ternarize(root)
+
+  // Use Function constructor instead of eval for security
+  // This preserves the exact same computational properties as the original algorithm:
+  // - Wide intervals (high probability items) are checked first
+  // - Minimizes comparisons for common cases
+  // - Uses the tree structure for efficient searching
+  const picker = new Function('p', `return ${exp}`) as (p: number) => number
+
+  return (rng: Rng) => () => objects[picker(rng())]
 }
 
 /**
- * The type of random number generators. Ideally this will return number from a continuous distribution
- * in the interval [0, 1], but for `pickMe` and number less than 0 is the same as 0 and any number
- * greater than 1 is the same as 1.
+ * The type of random number generators. Ideally this will return numbers from a continuous distribution
+ * in the interval [0, 1], but for `pickMe` any number less than 0 is treated as 0 and any number
+ * greater than 1 is treated as 1.
  */
 export type Rng = () => number
 
-// throw an error in case of duplicates
-// it is difficult to do this efficiently because we allow T to be anything, so we can't for instance use a Set
-function dupChecker<T>(frequencies: [T, number][] | T[], toT: (item: [T, number] | T) => T) {
-  for (let i = 0, lim = frequencies.length - 1; i < lim; i++) {
-    const t = toT(frequencies[i])
-    for (let j = i + 1; j < frequencies.length; j++) {
-      if (t === toT(frequencies[j])) throw new Error(`${t} appears more than once among frequencies`)
-    }
+/**
+ * A node in the interval search tree.
+ */
+type Node = {
+  index: number
+  interval: number
+  sum?: number
+  leftThreshold?: number
+  rightThreshold?: number
+  left?: Node
+  right?: Node
+}
+
+/**
+ * Converts a Node search tree into a nested ternary expression string.
+ * This preserves the original algorithm's optimization: wide intervals (high-probability items)
+ * are placed to minimize the number of comparisons needed for common cases.
+ */
+function ternarize(n: Node): string {
+  if (n.left && n.right) {
+    return `(p < ${n.leftThreshold} ? ${ternarize(n.left)} : (p < ${n.rightThreshold} ? ${n.index} : ${ternarize(n.right)}))`
+  } else if (n.left) {
+    return `(p < ${n.leftThreshold} ? ${ternarize(n.left)} : ${n.index})`
+  } else if (n.right) {
+    return `(p < ${n.rightThreshold} ? ${n.index} : ${ternarize(n.right)})`
+  } else {
+    return n.index.toString()
   }
 }
 
-// if all frequencies are the same, we can make a simpler picker
-function simplePicker<T>(frequencies: [T, number][] | T[]): undefined | ((rng: Rng) => () => T) {
-  if (frequencies.length === 0) return
-  if ((frequencies as any).every((s: any) => Array.isArray(s) && s.length === 2 && typeof s[1] === 'number')) {
-    const castFrequencies: [T, number][] = frequencies as any as [T, number][]
-    const [, n1] = castFrequencies[0]
-    if (n1 > 0 && castFrequencies.every(([, n2]) => n2 === n1)) {
-      const items = castFrequencies.map(([t]) => t)
-      dupChecker(items, (item: [T, number] | T) => item as T)
-      return (rng: Rng) => () => items[Math.floor(items.length * rng())]
+/**
+ * Checks if a value is a pair with a numeric second element.
+ */
+function isFrequencyPair<T>(value: unknown): value is [T, number] {
+  return Array.isArray(value) && value.length === 2 && typeof value[1] === 'number'
+}
+
+/**
+ * Attempts to create a simple picker when all frequencies are equal.
+ * This is more efficient than the general case.
+ * 
+ * @param frequencies - Input frequencies (pairs or simple items)
+ * @returns A picker function if all frequencies are equal, undefined otherwise
+ */
+function trySimplePicker<T>(frequencies: [T, number][] | T[]): ((rng: Rng) => () => T) | undefined {
+  if (frequencies.length === 0) {
+    return undefined
+  }
+
+  // Check if first element looks like a pair with a number
+  const first = frequencies[0]
+  const isFirstPair = isFrequencyPair<T>(first)
+
+  if (isFirstPair) {
+    // Assume all are pairs
+    const typedFrequencies = frequencies as [T, number][]
+    const [, firstFreq] = typedFrequencies[0]
+    
+    // Check if all have same positive frequency
+    if (firstFreq <= 0) {
+      return undefined
+    }
+    
+    let allSame = true
+    for (let i = 1; i < typedFrequencies.length; i++) {
+      const [, n] = typedFrequencies[i]
+      if (n !== firstFreq) {
+        allSame = false
+        break
+      }
+    }
+    
+    if (allSame) {
+      const items = typedFrequencies.map(([t]) => t)
+      checkForDuplicatesInItems(items)
+      return (rng: Rng) => () => {
+        const n = Math.max(0, Math.min(1, rng()))
+        return items[Math.min(items.length - 1, Math.floor(items.length * n))]
+      }
     }
   } else {
-    const items: T[] = [...frequencies] as any as T[]
+    // Simple array of items (no frequencies specified)
+    const items: T[] = frequencies as T[]
     if (items.length === 1) {
       const t = items[0]
       return (_rng: Rng) => () => t
     }
-    dupChecker(items, (item: [T, number] | T) => item as T)
-    return (rng: Rng) => () => items[Math.floor(items.length * rng())]
+    checkForDuplicatesInItems(items)
+    return (rng: Rng) => () => {
+      const n = Math.max(0, Math.min(1, rng()))
+      return items[Math.min(items.length - 1, Math.floor(items.length * n))]
+    }
   }
+
+  return undefined
 }
 
-// remove impossible frequencies
-function sanitize<T>(frequencies: [T, number][]): [T, number][] {
-  return frequencies.map(([t, n]) => [t, Number(n)]).filter(([, n]) => Number.isFinite(n) && n > 0) as any as [
-    T,
-    number,
-  ][]
+/**
+ * Normalizes input frequencies to [T, number][] format, filtering out invalid entries.
+ * Handles both [T, number][] and T[] inputs.
+ * 
+ * @param frequencies - Input frequencies
+ * @returns Normalized frequencies as [T, number][]
+ */
+function normalizeFrequencies<T>(frequencies: [T, number][] | T[]): [T, number][] {
+  if (frequencies.length === 0) {
+    return []
+  }
+
+  // Check if first element looks like a pair
+  const first = frequencies[0]
+  const isFirstPair = isFrequencyPair<T>(first)
+
+  if (isFirstPair) {
+    // Input is [T, number][] - sanitize each entry
+    const typedFrequencies = frequencies as [T, number][]
+    return typedFrequencies
+      .map(([t, n]) => [t, Number(n)] as [T, number])
+      .filter(([, n]) => Number.isFinite(n) && n > 0)
+  } else {
+    // Input is T[] - convert to [T, number][] with equal weights
+    const items = frequencies as T[]
+    return items.map(t => [t, 1] as [T, number])
+  }
 }
 
-// make a function that converts a random number into an index, preserving the frequencies
-// assuming the random number is from an even distribution in the interval [0, 1]
-function thresholder(thresholds: number[]): (n: number) => number {
-  return eval(`(n) => ${portion(thresholds, 0, thresholds.length)}`)
+/**
+ * Prepares nodes from frequencies. Sorts by frequency descending to prioritize
+ * high-probability items (they will be found with fewer comparisons).
+ * 
+ * @param frequencies - Normalized frequencies
+ * @returns Tuple of items array and node array
+ */
+function prepare<T>(frequencies: [T, number][]): [T[], Node[]] {
+  // Sort by frequency descending - this ensures wide intervals (high probability)
+  // are placed first in the tree, minimizing comparisons for common cases
+  frequencies.sort(([, na], [, nb]) => nb - na)
+  const sum = frequencies.reduce((acc, [, n]) => acc + n, 0)
+  const objects: T[] = []
+  const nodes: Node[] = []
+  frequencies.forEach(([t, n], i) => {
+    objects.push(t)
+    nodes.push({ interval: n / sum, index: i })
+  })
+  return [objects, nodes]
 }
 
-// recursively convert the threshold list into nested ternary operators
-// this allows us to find our index in O(log(n)) comparisons
-function portion(thresholds: number[], start: number, end: number): string {
-  const n = end - start
-  if (n === 1) return start.toString()
-  const i = start + (n % 2 === 0 ? n / 2 - 1 : (n - 1) / 2)
-  return `(n > ${thresholds[i]} ? ${portion(thresholds, i + 1, end)} : ${portion(thresholds, start, i + 1)})`
+/**
+ * Builds a binary search tree from nodes, optimized for skewed distributions.
+ * Wide intervals (high probability) are placed to minimize comparisons.
+ * 
+ * For distributions where one interval is >= 33% of the total (n.interval * 3 >= sum),
+ * a linear search is used for that subtree, which is more efficient than binary search.
+ * 
+ * For balanced distributions, a heap-based split is used to maintain balance while
+ * prioritizing wide intervals.
+ * 
+ * @param nodes - Array of nodes sorted by interval descending
+ * @returns The root node of the tree
+ */
+function buildBranch(nodes: Node[]): Node {
+  const sum = nodes.reduce((acc, n) => acc + n.interval, 0)
+  const n = nodes.shift()!
+  n.sum = sum
+  if (nodes.length === 0) return n
+  if (n.interval * 3 >= sum) {
+    // The frequencies are so skewed that a linear search is more efficient
+    // than a binary search. Place all remaining nodes to the right.
+    n.right = buildBranch(nodes)
+  } else {
+    // Perform a binary search, considering wide intervals before narrow ones
+    // Use heap-based splitting to maintain balance while prioritizing wide intervals
+    const [left, right] = nodes.reduce(([left, right, idx], node) => {
+      if (belongsToLeftBranch(idx)) left.push(node)
+      else right.push(node)
+      return [left, right, idx + 1]
+    }, [[], [], 1] as [Node[], Node[], number])
+    n.left = buildBranch(left)
+    if (right.length > 0) n.right = buildBranch(right)
+  }
+  return n
 }
 
+/**
+ * Determines if an index belongs to the left branch in a heap structure.
+ * This is used to split nodes into left and right subtrees while maintaining
+ * the heap property (wide intervals at the top).
+ * 
+ * @param i - Index in the heap
+ * @returns true if the index belongs to the left branch
+ */
+function belongsToLeftBranch(i: number): boolean {
+  if (i === 0) return true
+  if (i < 0) return false
+  return belongsToLeftBranch(Math.floor((i - 1) / 2))
+}
+
+/**
+ * Adds cumulative thresholds to nodes in the tree.
+ * This allows the ternary expression to efficiently search by comparing
+ * the random number against thresholds.
+ * 
+ * @param n - Node to add thresholds to
+ * @param acc - Accumulated threshold value
+ */
+function addThresholds(n: Node, acc: number) {
+  if (n.left) {
+    addThresholds(n.left, acc)
+    acc += n.left.sum!
+    n.leftThreshold = acc
+  }
+  if (n.right) {
+    acc += n.interval
+    n.rightThreshold = acc
+    addThresholds(n.right, acc)
+  }
+}
+
+/**
+ * Constant for 2^32 used in random number generation.
+ */
+const UINT32_MAX = 4294967296
+
 /**
  * Generates a random number sequence generator. This is a demonstration generator
  * useful for testing and documentation. Any zero-argument function that returns
@@ -172,7 +352,7 @@ function portion(thresholds: number[], start: number, end: number): string {
  *
  * The implementation of `rando` is taken from https://stackoverflow.com/a/47593316/15060051.
  * It is the Mulberry32 algorithm.
- * 
+ *
  * Note, `rando` can be re-seeded by passing an optional number argument as the fresh seed (see
  * example below). This can be useful if you are sharing a random number generator among
  * several objects and you need to change random number sequences.
@@ -186,20 +366,20 @@ function portion(thresholds: number[], start: number, end: number): string {
  * const ar: number[] = []
  * for (let i = 0; i < 3; i++) ar.push(rng())
  * // => [ 0.6270739405881613, 0.002735721180215478, 0.5274470399599522 ]
- * 
+ *
  * // the same seed will produce the same random number sequence
  * rando(1)()
  * // => 0.6270739405881613
  * rando(1)()
  * // => 0.6270739405881613
- * 
+ *
  * // but you can provide a fresh seed to change the sequence
  * (rando(1) as any)(2)
  * // => 0.7342509443406016
  * ```
  *
- * @param {number} seed - the seed for a random number sequence
- * @returns {Rng} a generator of random numbers
+ * @param seed - the seed for a random number sequence
+ * @returns a generator of random numbers
  */
 export function rando(seed: number): Rng {
   return (reseed?: number) => {
@@ -207,6 +387,72 @@ export function rando(seed: number): Rng {
     let t = (seed += 0x6d2b79f5)
     t = Math.imul(t ^ (t >>> 15), t | 1)
     t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
-    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+    return ((t ^ (t >>> 14)) >>> 0) / UINT32_MAX
+  }
+}
+
+/**
+ * Checks for duplicate items in a list of [T, number] pairs.
+ * Uses a Set for O(n) performance when T is a primitive type.
+ * Falls back to O(n²) for objects.
+ * 
+ * @param frequencies - Array of [T, number] pairs
+ * @throws Error if duplicates are found
+ */
+function checkForDuplicates<T>(frequencies: [T, number][]): void {
+  // Try to use Set for O(n) duplicate detection
+  const seen: any[] = []
+  let hasNonPrimitive = false
+
+  for (const [t] of frequencies) {
+    const type = typeof t
+    // Primitives that can be safely compared
+    if (type === 'string' || type === 'number' || type === 'boolean' || type === 'symbol' || type === 'bigint' || t === null) {
+      for (let i = 0; i < seen.length; i++) {
+        if (seen[i] === t) {
+          throw new Error(`${String(t)} appears more than once among frequencies`)
+        }
+      }
+      seen.push(t)
+    } else {
+      hasNonPrimitive = true
+    }
+  }
+
+  // For non-primitive types, we need O(n²) comparison
+  if (hasNonPrimitive) {
+    for (let i = 0; i < frequencies.length - 1; i++) {
+      const t1 = frequencies[i][0]
+      // Skip primitives we already checked
+      const type1 = typeof t1
+      if (type1 === 'string' || type1 === 'number' || type1 === 'boolean' || type1 === 'symbol' || type1 === 'bigint' || t1 === null) {
+        continue
+      }
+      for (let j = i + 1; j < frequencies.length; j++) {
+        const t2 = frequencies[j][0]
+        if (t1 === t2) {
+          throw new Error(`${String(t1)} appears more than once among frequencies`)
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Checks for duplicate items in a simple array of T.
+ * 
+ * @param items - Array of items
+ * @throws Error if duplicates are found
+ */
+function checkForDuplicatesInItems<T>(items: T[]): void {
+  // Try to use simple comparison
+  for (let i = 0; i < items.length - 1; i++) {
+    const t1 = items[i]
+    for (let j = i + 1; j < items.length; j++) {
+      const t2 = items[j]
+      if (t1 === t2) {
+        throw new Error(`${String(t1)} appears more than once among frequencies`)
+      }
+    }
   }
 }

package/tsconfig.json

@@ -99,5 +99,5 @@
     "skipLibCheck": true                                 /* Skip type checking all .d.ts files. */
   },
   "include": ["src"],
-  "exclude": ["node_modules", "**/__tests__/*"]
+  "exclude": ["node_modules", "**/*.test.ts", "**/*.spec.ts"]
 }