pick-me-too 1.1.1 → 1.3.0

package/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog
 
+## 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*
+- some efficiency improvements in edge cases
 ## v1.1.1 *2022-4-16*
 - fixed some project configuration
-- ## v1.1.0 *2022-4-16*
+## v1.1.0 *2022-4-16*
 - factored `pickMeToo` out of `pickMe`

package/README.md

@@ -180,7 +180,7 @@ Generates a random number sequence generator.
 
 This is a demonstration generator useful for testing and documentation. Any zero-argument function that returns
 numbers will suffice for `pickMe`. If it returns 0 or less, the first item
-given to `pickMe` will be picked. If it is 1 or less, the last item will be.
+given to `pickMe` will be picked. If it is 1 or more, the last item will be.
 
 The implementation of `rando` is taken from [this Stack Overflow comment](https://stackoverflow.com/a/47593316/15060051).
 There are many others if you don't find this suitable.
@@ -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;
 /**
@@ -74,7 +75,10 @@ exports.pickMe = pickMe;
  * @returns {(rng: Rng) => () => T} - a function from random number generators to pickers of things in the frequency list
  */
 function pickMeToo(frequencies) {
-    frequencies = sanitize(normalize(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}`);
@@ -82,15 +86,7 @@ function pickMeToo(frequencies) {
         const [t] = frequencies[0];
         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`);
-        }
-    }
+    dupChecker(frequencies, (item) => item[0]);
     let total = 0, acc = 0;
     for (const [, n] of frequencies)
         total += n;
@@ -108,14 +104,39 @@ function pickMeToo(frequencies) {
     return (rng) => () => items[f(rng())];
 }
 exports.pickMeToo = pickMeToo;
-// take in an array of ambiguous type and return a list of pairs, T and frequency
-function normalize(frequencies) {
+// 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) {
@@ -143,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'
@@ -152,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.1.1",
+  "version": "1.3.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,11 @@ 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()
-    console.log(saying)
     test('polynesianish', () => expect(saying).toEqual("rekātū pe'ide kēpe 'ātēdapidapi kaha"))
   })
 })
@@ -128,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

@@ -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)
 }
 
 /**
@@ -71,21 +72,18 @@ export function pickMe<T>(frequencies: [T, number][] | T[], rando?: Rng): () =>
  * @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 {
-  frequencies = sanitize(normalize(frequencies))
+  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 (_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`)
-    }
-  }
+  dupChecker(frequencies, (item: [T, number] | T) => (item as [T, number])[0])
   let total = 0,
     acc = 0
   for (const [, n] of frequencies) total += n
@@ -111,13 +109,37 @@ export function pickMeToo<T>(frequencies: [T, number][] | T[]): (rng: Rng) => ()
  */
 export type Rng = () => number
 
-// 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][]
+// 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`)
+    }
+  }
+}
+
+// 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
@@ -150,6 +172,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
@@ -160,13 +186,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)