pick-me-too 1.2.1 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 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*
 - fixed typo in README
 ## v1.2.0 *2022-4-17*

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
@@ -194,6 +194,10 @@ const rng = rando(1)
 const ar: number[] = []
 for (let i = 0; i < 3; i++) ar.push(rng())
 // => [ 0.6270739405881613, 0.002735721180215478, 0.5274470399599522 ]
+
+// reseed the generator
+(rng as any)(Math.random())
+// => ??? the random number sequence is still deterministic, but at a completely different place
 ```
 
 ## Acknowledgements

package/lib/index.d.ts

@@ -82,6 +82,10 @@ export declare type Rng = () => number;
  * 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.
+ *
  * @example
  * ```ts
  * import { rando } from 'pick-me'
@@ -91,6 +95,16 @@ export declare type Rng = () => number;
  * 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

package/lib/index.js

@@ -47,7 +47,8 @@ exports.rando = exports.pickMeToo = exports.pickMe = void 0;
  * @returns {() => T} a picker of T's
  */
 function pickMe(frequencies, rando) {
-    return pickMeToo(frequencies)(rando !== null && rando !== void 0 ? rando : (() => Math.random()));
+    const rng = rando !== null && rando !== void 0 ? rando : (() => Math.random());
+    return pickMeToo(frequencies)(rng);
 }
 exports.pickMe = pickMe;
 /**
@@ -163,6 +164,10 @@ function portion(thresholds, start, end) {
  * 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.
+ *
  * @example
  * ```ts
  * import { rando } from 'pick-me'
@@ -172,13 +177,25 @@ function portion(thresholds, start, end) {
  * 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
  */
 function rando(seed) {
-    return () => {
+    return (reseed) => {
+        if (reseed !== undefined)
+            seed = reseed;
         let t = (seed += 0x6d2b79f5);
         t = Math.imul(t ^ (t >>> 15), t | 1);
         t ^= t + Math.imul(t ^ (t >>> 7), t | 61);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pick-me-too",
-  "version": "1.2.1",
+  "version": "2.0.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

@@ -87,12 +87,12 @@ describe('README', () => {
       rng,
     )
     const clause = () => {
-      let s = []
+      let s: string[] = []
       for (let i = 0, lim = clauseLength(); i < lim; i++) s.push(word())
       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', () => {
@@ -127,5 +127,7 @@ describe('index.ts', () => {
     test('rando', () => {
       expect(ar).toEqual([0.6270739405881613, 0.002735721180215478, 0.5274470399599522])
     })
+    test('rando(1)()', () => expect(rando(1)()).toEqual(0.6270739405881613))
+    test('(rando(1) as any)(2)', () => expect((rando(1) as any)(2)).toEqual(0.7342509443406016))
   })
 })

package/src/__tests__/functionality.test.ts

@@ -16,6 +16,19 @@ describe('rando', () => {
   for (let i = 0; i < bins.length; i++) {
     test('even distribution', () => expect(Math.round(bins[i] / 1000)).toEqual(1))
   }
+  for (let i = 0; i < 10; i++) {
+    const seed = Math.random()
+    const rng1 = rando(seed),
+      rng2 = rando(seed)
+    const ar1: number[] = [],
+      ar2: number[] = []
+    for (let j = 0; j < 10; j++) {
+      ar1.push(rng1())
+      ar2.push(rng2())
+    }
+    test(`two randos with seed ${seed} produce the same sequence of random values`, () => expect(ar1).toEqual(ar2))
+    test(`randos can be reseeded`, () => expect(rng1()).not.toEqual((rng2 as any)(Math.random())))
+  }
 })
 
 describe('pickMe', () => {

package/src/index.ts

@@ -36,7 +36,7 @@
  * 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
@@ -44,7 +44,8 @@
  * @returns {() => T} a picker of T's
  */
 export function pickMe<T>(frequencies: [T, number][] | T[], rando?: Rng): () => T {
-  return pickMeToo(frequencies)(rando ?? (() => Math.random()))
+  const rng = rando ?? (() => Math.random())
+  return pickMeToo(frequencies)(rng)
 }
 
 /**
@@ -57,11 +58,11 @@ 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 probablility generator; this will always return the same thing, which happens to be "foo"
  * fooBarBaz(() => 0)()
- * // => "foo"
+ * // => "bar"
  *
- * // maximum probability generator just returns "baz"
+ * // maximum probability generator; this will always return the same thing, which happens to be  "baz"
  * fooBarBaz(() => 1)()
  * // => "baz"
  * ```
@@ -83,22 +84,96 @@ export function pickMeToo<T>(frequencies: [T, number][] | T[]): (rng: Rng) => ()
     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
+  const [objects, nodes] = prepare(frequencies)
+  const root = buildBranch(nodes)
+  addThresholds(root, 0)
+  const exp = ternarize(root)
+  const picker: (n: number) => number = eval(`(p) => ${exp}`)
+  return (rng: Rng) => () => objects[picker(rng())]
+}
+
+// convert a Node search tree into a nested ternary expression
+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()
+  }
+}
+
+// convert the list of frequencies into Nodes (see below) and a list
+// of things to pick
+function prepare<T>(frequencies: [T, number][]): [T[], Node[]] {
+  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]
+}
+
+// a temporary data structure used for converting the list of frequencies
+// into a tree structure we can search efficiently
+type Node = {
+  index: number,
+  interval: number,
+  sum?: number,
+  leftThreshold?: number
+  rightThreshold?: number
+  left?: Node
+  right?: Node
+}
+
+// given a search tree, add the probability thresholds for each node
+function addThresholds(n: Node, acc: number) {
+  if (n.left) {
+    addThresholds(n.left, acc)
+    acc += n.left.sum!
+    n.leftThreshold = acc
   }
-  const items: T[] = [],
-    thresholds: number[] = []
-  for (const [t, n] of frequencies) {
-    items.push(t)
-    thresholds.push(n)
+  if (n.right) {
+    acc += n.interval
+    n.rightThreshold = acc
+    addThresholds(n.right, acc)
   }
-  const f = thresholder(thresholds)
-  return (rng: Rng) => () => items[f(rng())]!
+}
+
+// convert a list of sorted nodes into an efficiently searchable 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 a linear search is more efficient than a binary search
+    n.right = buildBranch(nodes)
+  } else {
+    // perform a binary search, considering wide intervals before narrow ones
+    const [left, right] = nodes.reduce(([left, right, idx], n) => {
+      if (belongsToLeftBranch(idx)) left.push(n)
+      else right.push(n)
+      return [left, right, idx + 1]
+    }, [[], [], 1] as [Node[], Node[], number])
+    n.left = buildBranch(left)
+    if (right.length > 0) n.right = buildBranch(right)
+  }
+  return n
+}
+
+// treating our sorted list of intervals as a heap, use the heap parent identification rules
+// to determine whether the index in question is under the left or the right branch under the
+// root node
+function belongsToLeftBranch(i: number): boolean {
+  if (i === 0) return true
+  if (i < 0) return false
+  return belongsToLeftBranch(Math.floor((i - 1) / 2))
 }
 
 /**
@@ -149,21 +224,6 @@ function sanitize<T>(frequencies: [T, number][]): [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)}`)
-}
-
-// 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)})`
-}
-
 /**
  * Generates a random number sequence generator. This is a demonstration generator
  * useful for testing and documentation. Any zero-argument function that returns
@@ -171,6 +231,10 @@ 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.
  *
  * @example
  * ```ts
@@ -181,13 +245,24 @@ 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
  */
 export function rando(seed: number): Rng {
-  return () => {
+  return (reseed?: number) => {
+    if (reseed !== undefined) seed = reseed
     let t = (seed += 0x6d2b79f5)
     t = Math.imul(t ^ (t >>> 15), t | 1)
     t ^= t + Math.imul(t ^ (t >>> 7), t | 61)