pick-me-too 1.0.0

package/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "printWidth": 120,
+  "trailingComma": "all",
+  "semi": false,
+  "singleQuote": true
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 David F. Houghton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,183 @@
+# pick-me
+Generate functions that pick things from lists with specified frequencies.
+
+## Synopsis
+
+```ts
+// Let's make a generator of quasi-Polynesian lorem ipsum!
+
+import { pickMe, rando } from 'pick-me-too'
+
+// we want our text reproducible, so we use a seeded random number generator
+const rng = rando(1)
+
+// now we specify the frequency of various patterns in our invented language
+
+const vowels = pickMe(
+  [
+    ['a', 2],
+    ['e', 1],
+    ['i', 1.5],
+    ['o', 1],
+    ['u', 1.5],
+    ['ā', 0.75],
+    ['ē', 0.5],
+    ['ī', 0.75],
+    ['ō', 0.5],
+    ['ū', 0.75],
+  ],
+  rng,
+)
+const consonants = pickMe(
+  [
+    ["'", 5],
+    ['h', 1],
+    ['p', 3],
+    ['t', 3],
+    ['k', 3],
+    ['b', 1],
+    ['d', 1],
+    ['g', 1],
+    ['n', 3],
+    ['r', 1],
+  ],
+  rng,
+)
+// our language as simple CV syllables
+const syllable = () => `${consonants()}${vowels()}`
+const morphemeLength = pickMe(
+  [
+    [1, 1],
+    [2, 3],
+    [3, 1],
+  ],
+  rng,
+)
+const morpheme = () => {
+  let m = ''
+  for (let i = 0, lim = morphemeLength(); i < lim; i++) m += syllable()
+  return m
+}
+const reduplication = () => {
+  const r = morpheme()
+  return `${r}${r}`
+}
+// we can pick functions, too!
+const segment = pickMe(
+  [
+    [morpheme, 5],
+    [reduplication, 1],
+  ],
+  rng,
+)
+const wordLength = pickMe(
+  [
+    [1, 5],
+    [2, 3],
+    [3, 2],
+    [4, 1],
+    [5, 1],
+  ],
+  rng,
+)
+const word = () => {
+  let w = ''
+  for (let i = 0, lim = wordLength(); i < lim; i++) w = w + segment()()
+  return w
+}
+const clauseLength = pickMe(
+  [
+    [1, 1],
+    [2, 3],
+    [3, 4],
+    [4, 4],
+    [5, 5],
+    [6, 6],
+  ],
+  rng,
+)
+const clause = () => {
+  let s = []
+  for (let i = 0, lim = clauseLength(); i < lim; i++) s.push(word())
+  return s.join(' ')
+}
+
+const saying = clause()
+// => "rekātū pe'ide kēpe 'ātēdapidapi kaha"
+```
+
+## API
+
+### `function pickMe<T>(frequencies: [T, number][] | T[], rando?: () => number): () => T`
+
+Generates a zero-argument function that returns an item from the frequency list
+parameter with a probability concordant with its specified frequency.
+
+The required parameter is a list of pairs: an item to pick and its frequency. The "frequency"
+is simply a positive number which determines the probability of picking one item relative to another.
+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 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.
+
+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-too'
+
+// 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[] = []
+for (let i = 0; i < 10; i++) ar.push(fooBarBaz())
+// => [ 'baz', 'foo', 'baz', 'baz', 'baz', 'bar', 'baz', 'baz', 'bar', 'baz' ]
+```
+
+### `function rando(seed: number): () => number`
+
+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.
+
+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.
+
+@example
+```ts
+import { rando } from 'pick-me-too'
+
+// make a random number generator with a seed of 1
+const rng = rando(1)
+const ar: number[] = []
+for (let i = 0; i < 3; i++) ar.push(rng())
+// => [ 0.6270739405881613, 0.002735721180215478, 0.5274470399599522 ]
+```
+
+## Acknowledgements
+
+It is possible this package is a duplicate. I didn't try very hard to find out. I just felt like writing
+this code and, having written it, I felt like publishing it. It may behoove you to check npmjs carefully
+and compare packages.
+
+That being said, `pickMe` should be near optimally fast (if the frequences are strongly skewed, it is
+possible to compile a picker that uses fewer numerical comparisons in the typical case). Its unit and
+documentation tests are thorough.

package/jestconfig.json

@@ -0,0 +1,14 @@
+{
+    "transform": {
+        "^.+\\.(t|j)sx?$": "ts-jest"
+    },
+    "testRegex": "(/__tests__/.*|(\\.|/)(test|spec))\\.(jsx?|tsx?)$",
+    "moduleFileExtensions": [
+        "ts",
+        "tsx",
+        "js",
+        "jsx",
+        "json",
+        "node"
+    ]
+}

package/lib/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Generates a zero-argument function that returns an item from the frequency list
+ * parameter with a probability concordant with its specified frequency.
+ *
+ * The required parameter is a list of pairs: an item to pick and its frequency. The "frequency"
+ * is simply a positive number which determines the probability of picking one item relative to another.
+ * 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]]`.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * @example
+ * ```ts
+ * 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[] = [];
+ * 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
+ * @returns {() => T} a picker of T's
+ */
+export declare function pickMe<T>(frequencies: [T, number][] | T[], rando?: () => number): () => T;
+/**
+ * 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`.
+ *
+ * The implementation of `rando` is taken from https://stackoverflow.com/a/47593316/15060051.
+ * It is the Mulberry32 algorithm.
+ *
+ * @example
+ * ```ts
+ * import { rando } from 'pick-me';
+ *
+ * // make a random number generator with a seed of 1
+ * 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
+ */
+export declare function rando(seed: number): () => number;

package/lib/index.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rando = 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.
+ *
+ * The required parameter is a list of pairs: an item to pick and its frequency. The "frequency"
+ * is simply a positive number which determines the probability of picking one item relative to another.
+ * 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]]`.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * @example
+ * ```ts
+ * 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[] = [];
+ * 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
+ * @returns {() => T} a picker of T's
+ */
+function pickMe(frequencies, rando) {
+    frequencies = sanitize(normalize(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;
+    }
+    // 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());
+    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 () => items[f(rando())];
+}
+exports.pickMe = pickMe;
+// take in an array of ambiguous type and return a list of pairs, T and frequency
+function normalize(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;
+}
+// remove impossible frequencies
+function sanitize(frequencies) {
+    return frequencies.map(([t, n]) => [t, Number(n)]).filter(([, n]) => Number.isFinite(n) && n > 0);
+}
+// 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)}`);
+}
+// 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)})`;
+}
+// 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
+ * numbers will suffice for `pickMe`.
+ *
+ * The implementation of `rando` is taken from https://stackoverflow.com/a/47593316/15060051.
+ * It is the Mulberry32 algorithm.
+ *
+ * @example
+ * ```ts
+ * import { rando } from 'pick-me';
+ *
+ * // make a random number generator with a seed of 1
+ * 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
+ */
+function rando(seed) {
+    return () => {
+        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;
+    };
+}
+exports.rando = rando;

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "pick-me-too",
+  "version": "1.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",
+  "scripts": {
+    "test": "jest --config jestconfig.json",
+    "build": "tsc"
+  },
+  "keywords": [
+    "frequency",
+    "random",
+    "list",
+    "pick"
+  ],
+  "author": {
+    "name": "David F. Houghton",
+    "url": "https://github.com/dfhoughton"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/dfhoughton/pick-me",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dfhoughton/pick-me"
+  },
+  "devDependencies": {
+    "@types/jest": "^27.4.1",
+    "eslint": "^8.13.0",
+    "eslint-config-prettier": "^8.5.0",
+    "jest": "^27.5.1",
+    "prettier": "^2.6.2",
+    "ts-jest": "^27.1.4",
+    "typescript": "^4.6.3"
+  }
+}

package/src/__tests__/documentation.test.ts

@@ -0,0 +1,123 @@
+/** tests for all the code shown in documentation */
+
+import { rando, pickMe } from '..'
+
+describe('README', () => {
+  describe('Synopsis', () => {
+    const rng = rando(1)
+    const vowels = pickMe(
+      [
+        ['a', 2],
+        ['e', 1],
+        ['i', 1.5],
+        ['o', 1],
+        ['u', 1.5],
+        ['ā', 0.75],
+        ['ē', 0.5],
+        ['ī', 0.75],
+        ['ō', 0.5],
+        ['ū', 0.75],
+      ],
+      rng,
+    )
+    const consonants = pickMe(
+      [
+        ["'", 5],
+        ['h', 1],
+        ['p', 3],
+        ['t', 3],
+        ['k', 3],
+        ['b', 1],
+        ['d', 1],
+        ['g', 1],
+        ['n', 3],
+        ['r', 1],
+      ],
+      rng,
+    )
+    const syllable = () => `${consonants()}${vowels()}`
+    const morphemeLength = pickMe(
+      [
+        [1, 1],
+        [2, 3],
+        [3, 1],
+      ],
+      rng,
+    )
+    const morpheme = () => {
+      let m = ''
+      for (let i = 0, lim = morphemeLength(); i < lim; i++) m += syllable()
+      return m
+    }
+    const reduplication = () => {
+      const r = morpheme()
+      return `${r}${r}`
+    }
+    const segment = pickMe(
+      [
+        [morpheme, 5],
+        [reduplication, 1],
+      ],
+      rng,
+    )
+    const wordLength = pickMe(
+      [
+        [1, 5],
+        [2, 3],
+        [3, 2],
+        [4, 1],
+        [5, 1],
+      ],
+      rng,
+    )
+    const word = () => {
+      let w = ''
+      for (let i = 0, lim = wordLength(); i < lim; i++) w = w + segment()()
+      return w
+    }
+    const clauseLength = pickMe(
+      [
+        [1, 1],
+        [2, 3],
+        [3, 4],
+        [4, 4],
+        [5, 5],
+        [6, 6],
+      ],
+      rng,
+    )
+    const clause = () => {
+      let s = []
+      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"))
+  })
+})
+
+describe('index.ts', () => {
+  describe('pickMe', () => {
+    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())
+    test('pickMe', () => expect(ar).toEqual(['baz', 'foo', 'baz', 'baz', 'baz', 'bar', 'baz', 'baz', 'bar', 'baz']))
+  })
+  describe('rando', () => {
+    const rng = rando(1)
+    const ar: number[] = []
+    for (let i = 0; i < 3; i++) ar.push(rng())
+    test('rando', () => {
+      expect(ar).toEqual([0.6270739405881613, 0.002735721180215478, 0.5274470399599522])
+    })
+  })
+})

package/src/__tests__/functionality.test.ts

@@ -0,0 +1,106 @@
+import { pickMe, rando } from '..'
+
+// we need a fixed random number sequence for testing
+const rng = rando(1)
+
+describe('rando', () => {
+  const bins: number[] = []
+  for (let i = 0; i < 100; i++) {
+    bins[i] = 0
+  }
+  for (let i = 0, lim = bins.length * 1000; i < lim; i++) {
+    let idx = Math.floor(rng() * 100)
+    if (idx === 100) idx = 99
+    bins[idx] += 1
+  }
+  for (let i = 0; i < bins.length; i++) {
+    test('even distribution', () => expect(Math.round(bins[i] / 1000)).toEqual(1))
+  }
+})
+
+describe('pickMe', () => {
+  const trueFalse = pickMe(
+    [
+      ['true', 1],
+      ['false', 1],
+    ],
+    rng,
+  )
+  for (let i = 0; i < 10; i++) {
+    test('returns either "true" or "false"', () => expect(['true', 'false'].indexOf(trueFalse())).toBeGreaterThan(-1))
+  }
+  test('requires some items', () =>
+    expect(() => {
+      pickMe([])
+    }).toThrowError())
+  test('we allow no duplicates', () =>
+    expect(() => {
+      pickMe([
+        ['foo', 1],
+        ['foo', 1],
+      ])
+    }).toThrowError())
+  let f = pickMe([['foo', 1]], rng)
+  let ar: string[] = []
+  for (let i = 0; i < 100; i++) ar.push(f())
+  test("we always get the same thing if there's just one item", () =>
+    expect(ar.every((s) => s === 'foo')).toEqual(true))
+  f = pickMe([
+    ['foo', 1],
+    ['bar', 0],
+    ['baz', -1],
+  ])
+  ar.length = 0
+  for (let i = 0; i < 100; i++) ar.push(f())
+  test('we always get the same thing if only one item has a positive frequency', () =>
+    expect(ar.every((s) => s === 'foo')).toEqual(true))
+  f = pickMe(
+    [
+      ['foo', 2],
+      ['bar', 1],
+    ],
+    rng,
+  )
+  const counts1: Record<string, number> = { foo: 0, bar: 0 }
+  for (let i = 0; i < 1000; i++) counts1[f()] += 1
+  test('we expect some foos', () => expect(counts1.foo).toBeGreaterThan(0))
+  test('we expect some bars', () => expect(counts1.bar).toBeGreaterThan(0))
+  test('we get roughly as many of each thing as we expect', () =>
+    expect(Math.round(counts1.foo / counts1.bar)).toEqual(2))
+  // do this with a bit more rigor
+  const letters = 'abcdefghijklmnopqrstuvwxyz'.split('')
+  const frequencies: [string, number][] = []
+  for (let i = 0; i < letters.length; i++) {
+    frequencies.push([letters[i], i + 1])
+  }
+  const segment = (letters.length * (letters.length + 1)) / 2
+  f = pickMe(frequencies, rng)
+  let counts2: Record<string, number> = {}
+  for (const l of letters) counts2[l] = 0
+  for (let i = 0, lim = segment * 1000; i < lim; i++) counts2[f()] += 1
+  for (const [l, f] of frequencies) {
+    const c = Number(counts2[l])
+    test(`we got something for ${l}`, () => expect(c).toBeGreaterThan(0))
+    const expectation = f * 1000
+    test(`we got roughly as many as we expected for ${l}, with frequency ${f}`, () =>
+      expect(Math.round(c / expectation)).toEqual(1))
+  }
+  const f1 = pickMe(
+    [
+      ['foo', 1],
+      ['bar', 1],
+      ['baz', 1],
+    ],
+    rando(1),
+  )
+  const f2 = pickMe(['foo', 'bar', 'baz'], rando(1))
+  const ar1: string[] = []
+  const ar2: string[] = []
+  for (let i = 0; i < 100; i++) {
+    ar1.push(f1())
+    ar2.push(f2())
+  }
+  test('frequencies are optional if all are the same', () => {
+    expect(ar1).toEqual(ar2)
+  })
+})

package/src/index.ts

@@ -0,0 +1,142 @@
+/**
+ * Generates a zero-argument function that returns an item from the frequency list
+ * parameter with a probability concordant with its specified frequency.
+ *
+ * The required parameter is a list of pairs: an item to pick and its frequency. The "frequency"
+ * is simply a positive number which determines the probability of picking one item relative to another.
+ * 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 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.
+ * 
+ * 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'
+ *
+ * // 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[] = []
+ * 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
+ * @returns {() => T} a picker of T's
+ */
+export function pickMe<T>(frequencies: [T, number][] | T[], rando?: () => number): () => T {
+  frequencies = sanitize(normalize(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
+  }
+  // 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()
+  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: T[] = [],
+    thresholds: number[] = []
+  for (const [t, n] of frequencies) {
+    items.push(t)
+    thresholds.push(n)
+  }
+  const f = thresholder(thresholds)
+  return () => items[f(rando!())]!
+}
+
+// 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][]
+}
+
+// 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,
+  ][]
+}
+
+// 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
+ * numbers will suffice for `pickMe`.
+ *
+ * The implementation of `rando` is taken from https://stackoverflow.com/a/47593316/15060051.
+ * It is the Mulberry32 algorithm.
+ *
+ * @example
+ * ```ts
+ * import { rando } from 'pick-me'
+ *
+ * // make a random number generator with a seed of 1
+ * 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
+ */
+export function rando(seed: number): () => number {
+  return () => {
+    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
+  }
+}

package/tsconfig.json

@@ -0,0 +1,103 @@
+{
+  "compilerOptions": {
+    /* Visit https://aka.ms/tsconfig.json to read more about this file */
+
+    /* Projects */
+    // "incremental": true,                              /* Enable incremental compilation */
+    // "composite": true,                                /* Enable constraints that allow a TypeScript project to be used with project references. */
+    // "tsBuildInfoFile": "./",                          /* Specify the folder for .tsbuildinfo incremental compilation files. */
+    // "disableSourceOfProjectReferenceRedirect": true,  /* Disable preferring source files instead of declaration files when referencing composite projects */
+    // "disableSolutionSearching": true,                 /* Opt a project out of multi-project reference checking when editing. */
+    // "disableReferencedProjectLoad": true,             /* Reduce the number of projects loaded automatically by TypeScript. */
+
+    /* Language and Environment */
+    "target": "es2016",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
+    // "lib": [],                                        /* Specify a set of bundled library declaration files that describe the target runtime environment. */
+    // "jsx": "preserve",                                /* Specify what JSX code is generated. */
+    // "experimentalDecorators": true,                   /* Enable experimental support for TC39 stage 2 draft decorators. */
+    // "emitDecoratorMetadata": true,                    /* Emit design-type metadata for decorated declarations in source files. */
+    // "jsxFactory": "",                                 /* Specify the JSX factory function used when targeting React JSX emit, e.g. 'React.createElement' or 'h' */
+    // "jsxFragmentFactory": "",                         /* Specify the JSX Fragment reference used for fragments when targeting React JSX emit e.g. 'React.Fragment' or 'Fragment'. */
+    // "jsxImportSource": "",                            /* Specify module specifier used to import the JSX factory functions when using `jsx: react-jsx*`.` */
+    // "reactNamespace": "",                             /* Specify the object invoked for `createElement`. This only applies when targeting `react` JSX emit. */
+    // "noLib": true,                                    /* Disable including any library files, including the default lib.d.ts. */
+    // "useDefineForClassFields": true,                  /* Emit ECMAScript-standard-compliant class fields. */
+
+    /* Modules */
+    "module": "commonjs",                                /* Specify what module code is generated. */
+    // "rootDir": "./",                                  /* Specify the root folder within your source files. */
+    // "moduleResolution": "node",                       /* Specify how TypeScript looks up a file from a given module specifier. */
+    // "baseUrl": "./",                                  /* Specify the base directory to resolve non-relative module names. */
+    // "paths": {},                                      /* Specify a set of entries that re-map imports to additional lookup locations. */
+    // "rootDirs": [],                                   /* Allow multiple folders to be treated as one when resolving modules. */
+    // "typeRoots": [],                                  /* Specify multiple folders that act like `./node_modules/@types`. */
+    // "types": [],                                      /* Specify type package names to be included without being referenced in a source file. */
+    // "allowUmdGlobalAccess": true,                     /* Allow accessing UMD globals from modules. */
+    // "resolveJsonModule": true,                        /* Enable importing .json files */
+    // "noResolve": true,                                /* Disallow `import`s, `require`s or `<reference>`s from expanding the number of files TypeScript should add to a project. */
+
+    /* JavaScript Support */
+    // "allowJs": true,                                  /* Allow JavaScript files to be a part of your program. Use the `checkJS` option to get errors from these files. */
+    // "checkJs": true,                                  /* Enable error reporting in type-checked JavaScript files. */
+    // "maxNodeModuleJsDepth": 1,                        /* Specify the maximum folder depth used for checking JavaScript files from `node_modules`. Only applicable with `allowJs`. */
+
+    /* Emit */
+    "declaration": true,                                 /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
+    // "declarationMap": true,                           /* Create sourcemaps for d.ts files. */
+    // "emitDeclarationOnly": true,                      /* Only output d.ts files and not JavaScript files. */
+    // "sourceMap": true,                                /* Create source map files for emitted JavaScript files. */
+    // "outFile": "./",                                  /* Specify a file that bundles all outputs into one JavaScript file. If `declaration` is true, also designates a file that bundles all .d.ts output. */
+    "outDir": "./lib",                                  /* Specify an output folder for all emitted files. */
+    // "removeComments": true,                           /* Disable emitting comments. */
+    // "noEmit": true,                                   /* Disable emitting files from a compilation. */
+    // "importHelpers": true,                            /* Allow importing helper functions from tslib once per project, instead of including them per-file. */
+    // "importsNotUsedAsValues": "remove",               /* Specify emit/checking behavior for imports that are only used for types */
+    // "downlevelIteration": true,                       /* Emit more compliant, but verbose and less performant JavaScript for iteration. */
+    // "sourceRoot": "",                                 /* Specify the root path for debuggers to find the reference source code. */
+    // "mapRoot": "",                                    /* Specify the location where debugger should locate map files instead of generated locations. */
+    // "inlineSourceMap": true,                          /* Include sourcemap files inside the emitted JavaScript. */
+    // "inlineSources": true,                            /* Include source code in the sourcemaps inside the emitted JavaScript. */
+    // "emitBOM": true,                                  /* Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files. */
+    // "newLine": "crlf",                                /* Set the newline character for emitting files. */
+    // "stripInternal": true,                            /* Disable emitting declarations that have `@internal` in their JSDoc comments. */
+    // "noEmitHelpers": true,                            /* Disable generating custom helper functions like `__extends` in compiled output. */
+    // "noEmitOnError": true,                            /* Disable emitting files if any type checking errors are reported. */
+    // "preserveConstEnums": true,                       /* Disable erasing `const enum` declarations in generated code. */
+    // "declarationDir": "./",                           /* Specify the output directory for generated declaration files. */
+    // "preserveValueImports": true,                     /* Preserve unused imported values in the JavaScript output that would otherwise be removed. */
+
+    /* Interop Constraints */
+    // "isolatedModules": true,                          /* Ensure that each file can be safely transpiled without relying on other imports. */
+    // "allowSyntheticDefaultImports": true,             /* Allow 'import x from y' when a module doesn't have a default export. */
+    "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables `allowSyntheticDefaultImports` for type compatibility. */
+    // "preserveSymlinks": true,                         /* Disable resolving symlinks to their realpath. This correlates to the same flag in node. */
+    "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
+
+    /* Type Checking */
+    "strict": true,                                      /* Enable all strict type-checking options. */
+    // "noImplicitAny": true,                            /* Enable error reporting for expressions and declarations with an implied `any` type.. */
+    // "strictNullChecks": true,                         /* When type checking, take into account `null` and `undefined`. */
+    // "strictFunctionTypes": true,                      /* When assigning functions, check to ensure parameters and the return values are subtype-compatible. */
+    // "strictBindCallApply": true,                      /* Check that the arguments for `bind`, `call`, and `apply` methods match the original function. */
+    // "strictPropertyInitialization": true,             /* Check for class properties that are declared but not set in the constructor. */
+    // "noImplicitThis": true,                           /* Enable error reporting when `this` is given the type `any`. */
+    // "useUnknownInCatchVariables": true,               /* Type catch clause variables as 'unknown' instead of 'any'. */
+    // "alwaysStrict": true,                             /* Ensure 'use strict' is always emitted. */
+    // "noUnusedLocals": true,                           /* Enable error reporting when a local variables aren't read. */
+    // "noUnusedParameters": true,                       /* Raise an error when a function parameter isn't read */
+    // "exactOptionalPropertyTypes": true,               /* Interpret optional property types as written, rather than adding 'undefined'. */
+    // "noImplicitReturns": true,                        /* Enable error reporting for codepaths that do not explicitly return in a function. */
+    // "noFallthroughCasesInSwitch": true,               /* Enable error reporting for fallthrough cases in switch statements. */
+    // "noUncheckedIndexedAccess": true,                 /* Include 'undefined' in index signature results */
+    // "noImplicitOverride": true,                       /* Ensure overriding members in derived classes are marked with an override modifier. */
+    // "noPropertyAccessFromIndexSignature": true,       /* Enforces using indexed accessors for keys declared using an indexed type */
+    // "allowUnusedLabels": true,                        /* Disable error reporting for unused labels. */
+    // "allowUnreachableCode": true,                     /* Disable error reporting for unreachable code. */
+
+    /* Completeness */
+    // "skipDefaultLibCheck": true,                      /* Skip type checking .d.ts files that are included with TypeScript. */
+    "skipLibCheck": true                                 /* Skip type checking all .d.ts files. */
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "**/__tests__/*"]
+}