pick-me-too 1.0.2 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## v1.2.0 *2022-4-17*
+- some efficiency improvements in edge cases
+## v1.1.1 *2022-4-16*
+- fixed some project configuration
+## v1.1.0 *2022-4-16*
+- factored `pickMeToo` out of `pickMe`

package/README.md

@@ -150,6 +150,30 @@ for (let i = 0; i < 10; i++) ar.push(fooBarBaz())
 // => [ 'baz', 'foo', 'baz', 'baz', 'baz', 'bar', 'baz', 'baz', 'bar', 'baz' ]
 ```
 
+### `function pickMeToo<T>(frequencies: [T, number][] | T[]): (rng: () => number) => () => T`
+
+Generates a function from random number generators to generators of `T`.
+
+This is like `pickMe` -- in fact, `pickMe` delegates to this -- but it factors out the random
+number generator. It is useful in a situation where you want to incur the compilation of the
+picker only once but you want to plug in different random number sequences on different
+occasions.
+
+@example
+```ts
+import { pickMeToo } from 'pick-me-too'
+
+const fooBarBaz = pickMeToo([["foo", 1], ["bar", 1000], ["baz", 1]])
+
+// minimum probablility generator just returns "foo"
+fooBarBaz(() => 0)()
+// => "foo"
+
+// maximum probability generator just returns "baz"
+fooBarBaz(() => 1)()
+// => "baz"
+```
+
 ### `function rando(seed: number): () => number`
 
 Generates a random number sequence generator.

package/lib/index.d.ts

@@ -7,37 +7,73 @@
  * If the parameters are `[[1, 1], [2, 2]]`, you will get twice as many 2s as 1s. You will get the same
  * results with `[[1, 0.1], [2, 0.2]]`, `[[1, 10], [2, 20]]`, and `[[1, 0.13], [2, 0.26]]`.
  *
+ * The second, optional parameter is a random number sequence generator. Provide this if you want a reproducible
+ * sequence of selections from your frequency list. If this doesn't concern you, leave it off and take
+ * whatever `Math.random()` gives you.
+ *
  * If the frequency list is not a list of pairs but just a list of items, this is equivalent to a list of
- * 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 each the first member
- * of a frequency pair with the second value being some common positive number.
+ * 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. `[[1, 1], [1, 2]]` is
- * not good. `[[1, 1], [1,2]]` is no better.
+ * 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.
  *
- * The second, optional parameter is a random number sequence generator. Provide this if you want a reproducible
- * sequence of selections from your frequency list. If this doesn't concern you, leave it off and take
- * whatever `Math.random()` gives you.
+ * 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.
+ *
+ * Finally, `pickMe` compiles an efficient picker from the parameters provided. As with other compiled things, such
+ * as regular expressions, you want to do this one time in an initialization phase and then reuse it in loops.
+ * The compilation is not terribly expensive, but skipping it altogether is cheaper.
  *
  * @example
  * ```ts
- * import { rando, pickMe } from 'pick-me';
+ * import { rando, pickMe } from 'pick-me'
  *
  * // make a random number generator with a seed of 1
- * const rng = rando(1);
- * const fooBarBaz = pickMe([["foo", 1], ["bar", 2], ["baz", 3]], rng);
- * const ar: string[] = [];
+ * 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' ]
  * ```
  *
  * @param {[T, number][] | T[]} frequencies - phrases to match
- * @param {() => number} [rando=() => Math.random()] - random number generator
+ * @param {Rng} [rando=() => Math.random()] - random number generator
  * @returns {() => T} a picker of T's
  */
-export declare function pickMe<T>(frequencies: [T, number][] | T[], rando?: () => number): () => T;
+export declare function pickMe<T>(frequencies: [T, number][] | T[], rando?: Rng): () => T;
+/**
+ * Generates pickers of things. This separates the compilation step from frequencies so you
+ * can plug different random number generators in.
+ *
+ * @example
+ * ```ts
+ * import { pickMeToo } from 'pick-me'
+ *
+ * const fooBarBaz = pickMeToo([["foo", 1], ["bar", 1000], ["baz", 1]])
+ *
+ * // minimum probablility generator just returns "foo"
+ * fooBarBaz(() => 0)()
+ * // => "foo"
+ *
+ * // maximum probability generator just returns "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
+ */
+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.
+ */
+export declare type Rng = () => number;
 /**
  * Generates a random number sequence generator. This is a demonstration generator
  * useful for testing and documentation. Any zero-argument function that returns
@@ -48,16 +84,16 @@ export declare function pickMe<T>(frequencies: [T, number][] | T[], rando?: () =
  *
  * @example
  * ```ts
- * import { rando } from 'pick-me';
+ * import { rando } from 'pick-me'
  *
  * // make a random number generator with a seed of 1
- * const rng = rando(1);
- * const ar: number[] = [];
+ * const rng = rando(1)
+ * const ar: number[] = []
  * for (let i = 0; i < 3; i++) ar.push(rng())
  * // => [ 0.6270739405881613, 0.002735721180215478, 0.5274470399599522 ]
  * ```
  *
  * @param {number} seed - the seed for a random number sequence
- * @returns {() => number} a generator of random numbers
+ * @returns {Rng} a generator of random numbers
  */
-export declare function rando(seed: number): () => number;
+export declare function rando(seed: number): Rng;

package/lib/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.rando = exports.pickMe = void 0;
+exports.rando = exports.pickMeToo = exports.pickMe = void 0;
 /**
  * Generates a zero-argument function that returns an item from the frequency list
  * parameter with a probability concordant with its specified frequency.
@@ -10,55 +10,82 @@ exports.rando = exports.pickMe = void 0;
  * If the parameters are `[[1, 1], [2, 2]]`, you will get twice as many 2s as 1s. You will get the same
  * results with `[[1, 0.1], [2, 0.2]]`, `[[1, 10], [2, 20]]`, and `[[1, 0.13], [2, 0.26]]`.
  *
+ * The second, optional parameter is a random number sequence generator. Provide this if you want a reproducible
+ * sequence of selections from your frequency list. If this doesn't concern you, leave it off and take
+ * whatever `Math.random()` gives you.
+ *
  * If the frequency list is not a list of pairs but just a list of items, this is equivalent to a list of
- * 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 each the first member
- * of a frequency pair with the second value being some common positive number.
+ * 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. `[[1, 1], [1, 2]]` is
- * not good. `[[1, 1], [1,2]]` is no better.
+ * 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.
  *
- * The second, optional parameter is a random number sequence generator. Provide this if you want a reproducible
- * sequence of selections from your frequency list. If this doesn't concern you, leave it off and take
- * whatever `Math.random()` gives you.
+ * 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.
+ *
+ * Finally, `pickMe` compiles an efficient picker from the parameters provided. As with other compiled things, such
+ * as regular expressions, you want to do this one time in an initialization phase and then reuse it in loops.
+ * The compilation is not terribly expensive, but skipping it altogether is cheaper.
  *
  * @example
  * ```ts
- * import { rando, pickMe } from 'pick-me';
+ * import { rando, pickMe } from 'pick-me'
  *
  * // make a random number generator with a seed of 1
- * const rng = rando(1);
- * const fooBarBaz = pickMe([["foo", 1], ["bar", 2], ["baz", 3]], rng);
- * const ar: string[] = [];
+ * 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' ]
  * ```
  *
  * @param {[T, number][] | T[]} frequencies - phrases to match
- * @param {() => number} [rando=() => Math.random()] - random number generator
+ * @param {Rng} [rando=() => Math.random()] - random number generator
  * @returns {() => T} a picker of T's
  */
 function pickMe(frequencies, rando) {
-    frequencies = sanitize(normalize(frequencies));
+    return pickMeToo(frequencies)(rando !== null && rando !== void 0 ? rando : (() => Math.random()));
+}
+exports.pickMe = pickMe;
+/**
+ * Generates pickers of things. This separates the compilation step from frequencies so you
+ * can plug different random number generators in.
+ *
+ * @example
+ * ```ts
+ * import { pickMeToo } from 'pick-me'
+ *
+ * const fooBarBaz = pickMeToo([["foo", 1], ["bar", 1000], ["baz", 1]])
+ *
+ * // minimum probablility generator just returns "foo"
+ * fooBarBaz(() => 0)()
+ * // => "foo"
+ *
+ * // maximum probability generator just returns "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
+ */
+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];
-        return () => t;
+        return (_rng) => () => t;
     }
-    // throw an error in case of duplicates
-    // it is difficult to do this efficiently because we allow T to be anything
-    for (let i = 0, lim = frequencies.length - 1; i < lim; i++) {
-        const t = frequencies[i][0];
-        for (let j = i + 1; j < frequencies.length; j++) {
-            if (t === frequencies[j][0])
-                throw new Error(`${t} appears more than once among frequencies`);
-        }
-    }
-    rando !== null && rando !== void 0 ? rando : (rando = () => Math.random());
+    dupChecker(frequencies, (item) => item[0]);
     let total = 0, acc = 0;
     for (const [, n] of frequencies)
         total += n;
@@ -73,17 +100,42 @@ function pickMe(frequencies, rando) {
         thresholds.push(n);
     }
     const f = thresholder(thresholds);
-    return () => items[f(rando())];
+    return (rng) => () => items[f(rng())];
 }
-exports.pickMe = pickMe;
-// take in an array of ambiguous type and return a list of pairs, T and frequency
-function normalize(frequencies) {
+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`);
+        }
+    }
+}
+// if all frequencies are the same, we can make a simpler picker
+function simplePicker(frequencies) {
     if (frequencies.length === 0)
-        return frequencies;
-    if (frequencies.every((s) => Array.isArray(s) && s.length === 2 && typeof s[1] === 'number'))
-        return frequencies;
-    const ar = frequencies.map((t) => [t, 1]);
-    return ar;
+        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())];
+        }
+    }
+    else {
+        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())];
+    }
 }
 // remove impossible frequencies
 function sanitize(frequencies) {
@@ -103,8 +155,6 @@ function portion(thresholds, start, end) {
     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)})`;
 }
-// return a generator of a reproducible random number sequence
-// gotten from https://stackoverflow.com/a/47593316/15060051 -- this is Mulberry32
 /**
  * Generates a random number sequence generator. This is a demonstration generator
  * useful for testing and documentation. Any zero-argument function that returns
@@ -115,17 +165,17 @@ function portion(thresholds, start, end) {
  *
  * @example
  * ```ts
- * import { rando } from 'pick-me';
+ * import { rando } from 'pick-me'
  *
  * // make a random number generator with a seed of 1
- * const rng = rando(1);
- * const ar: number[] = [];
+ * const rng = rando(1)
+ * const ar: number[] = []
  * for (let i = 0; i < 3; i++) ar.push(rng())
  * // => [ 0.6270739405881613, 0.002735721180215478, 0.5274470399599522 ]
  * ```
  *
  * @param {number} seed - the seed for a random number sequence
- * @returns {() => number} a generator of random numbers
+ * @returns {Rng} a generator of random numbers
  */
 function rando(seed) {
     return () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pick-me-too",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "Generate a function that returns random items from a list with specified frequencies.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/src/__tests__/documentation.test.ts

@@ -1,6 +1,6 @@
 /** tests for all the code shown in documentation */
 
-import { rando, pickMe } from '..'
+import { rando, pickMe, pickMeToo } from '..'
 
 describe('README', () => {
   describe('Synopsis', () => {
@@ -92,7 +92,6 @@ describe('README', () => {
       return s.join(' ')
     }
     const saying = clause()
-    console.log(saying)
     test('polynesianish', () => expect(saying).toEqual("rekātū pe'ide kēpe 'ātēdapidapi kaha"))
   })
 })
@@ -112,6 +111,15 @@ describe('index.ts', () => {
     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']))
   })
+  describe('pickMeToo', () => {
+    const fooBarBaz = pickMeToo([
+      ['foo', 1],
+      ['bar', 1000],
+      ['baz', 1],
+    ])
+    test('low probability', () => expect(fooBarBaz(() => 0)()).toEqual('foo'))
+    test('high probability', () => expect(fooBarBaz(() => 1)()).toEqual('baz'))
+  })
   describe('rando', () => {
     const rng = rando(1)
     const ar: number[] = []

package/src/index.ts

@@ -19,10 +19,10 @@
  * 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.
- * 
+ *
  * Finally, `pickMe` compiles an efficient picker from the parameters provided. As with other compiled things, such
  * as regular expressions, you want to do this one time in an initialization phase and then reuse it in loops.
  * The compilation is not terribly expensive, but skipping it altogether is cheaper.
@@ -40,26 +40,49 @@
  * ```
  *
  * @param {[T, number][] | T[]} frequencies - phrases to match
- * @param {() => number} [rando=() => Math.random()] - random number generator
+ * @param {Rng} [rando=() => Math.random()] - random number generator
  * @returns {() => T} a picker of T's
  */
-export function pickMe<T>(frequencies: [T, number][] | T[], rando?: () => number): () => T {
-  frequencies = sanitize(normalize(frequencies))
+export function pickMe<T>(frequencies: [T, number][] | T[], rando?: Rng): () => T {
+  return pickMeToo(frequencies)(rando ?? (() => Math.random()))
+}
+
+/**
+ * Generates pickers of things. This separates the compilation step from frequencies so you
+ * can plug different random number generators in.
+ *
+ * @example
+ * ```ts
+ * import { pickMeToo } from 'pick-me'
+ *
+ * const fooBarBaz = pickMeToo([["foo", 1], ["bar", 1000], ["baz", 1]])
+ *
+ * // minimum probablility generator just returns "foo"
+ * fooBarBaz(() => 0)()
+ * // => "foo"
+ *
+ * // maximum probability generator just returns "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
+ */
+export function pickMeToo<T>(frequencies: [T, number][] | T[]): (rng: Rng) => () => T {
+  const simpleton = simplePicker(frequencies)
+  if (simpleton) return simpleton
+
+  frequencies = sanitize(frequencies as any as [T, number][])
+
   // 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 () => t
+    return (_rng: Rng) => () => t
   }
-  // throw an error in case of duplicates
-  // it is difficult to do this efficiently because we allow T to be anything
-  for (let i = 0, lim = frequencies.length - 1; i < lim; i++) {
-    const t = frequencies[i][0]
-    for (let j = i + 1; j < frequencies.length; j++) {
-      if (t === frequencies[j][0]) throw new Error(`${t} appears more than once among frequencies`)
-    }
-  }
-  rando ??= () => Math.random()
+  dupChecker(frequencies, (item: [T, number] | T) => (item as [T, number])[0])
   let total = 0,
     acc = 0
   for (const [, n] of frequencies) total += n
@@ -75,16 +98,47 @@ export function pickMe<T>(frequencies: [T, number][] | T[], rando?: () => number
     thresholds.push(n)
   }
   const f = thresholder(thresholds)
-  return () => items[f(rando!())]!
+  return (rng: Rng) => () => items[f(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.
+ */
+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`)
+    }
+  }
 }
 
-// take in an array of ambiguous type and return a list of pairs, T and frequency
-function normalize<T>(frequencies: [T, number][] | T[]): [T, number][] {
-  if (frequencies.length === 0) return frequencies as any as [T, number][]
-  if ((frequencies as any).every((s: any) => Array.isArray(s) && s.length === 2 && typeof s[1] === 'number'))
-    return frequencies as any as [T, number][]
-  const ar = frequencies.map((t) => [t, 1])
-  return ar as any as [T, number][]
+// 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())]
+    }
+  } else {
+    const items: T[] = [...frequencies] as any 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())]
+  }
 }
 
 // remove impossible frequencies
@@ -130,9 +184,9 @@ function portion(thresholds: number[], start: number, end: number): string {
  * ```
  *
  * @param {number} seed - the seed for a random number sequence
- * @returns {() => number} a generator of random numbers
+ * @returns {Rng} a generator of random numbers
  */
-export function rando(seed: number): () => number {
+export function rando(seed: number): Rng {
   return () => {
     let t = (seed += 0x6d2b79f5)
     t = Math.imul(t ^ (t >>> 15), t | 1)