Generate a series of tuples in lexicographical order
npm install @chocolatey/enumerator
- NAME
- FEATURES
- INSTALLATION
- SYNOPSIS
- DESCRIPTION
- Why?
- EXPORTS
- enumerate
- enumerator
- unfold
- EXAMPLES
- Generating passwords
- Combining options
- DEVELOPMENT
- COMPATIBILITY
- SEE ALSO
- VERSION
- AUTHOR
- COPYRIGHT AND LICENSE
enumerator - generate a series of tuples in lexicographical order
- no dependencies
- ~500 B minified + gzipped
- fully typed (TypeScript)
- CDN builds (UMD): [jsDelivr][], [unpkg][]
``
$ npm install @chocolatey/enumerator
`javascript
import { enumerate, enumerator } from '@chocolatey/enumerator'
const bits = [0, 1]
const words = ['foo', 'bar', 'baz', 'quux']
// generator
for (const value of enumerator([words, bits])) {
console.log(value) // ["foo", 0], ["foo", 1], ["bar", 0] ... ["quux", 1]
}
// array
enumerate(bits, 2) // [[0, 0], [0, 1], [1, 0], [1, 1]]
`
Enumerator generates a series of tuples in lexicographical order. Each tuple is
an array of values drawn from a custom alphabet for each position. Values can
be of any type.
The mechanism for generating the values is the same as an odometer, i.e. the
rightmost dial/column is incremented for each result, moving left each time a
dial rolls over, and halting when the leftmost dial rolls over, e.g.:
`javascript`
enumerate([[0, 1], [0, 1]]) // [[0, 0], [0, 1], [1, 0], [1, 1]]
In this example, the same alphabet is used for each position. As a shorthand, a
single alphabet can be repeated n times by supplying n as the second argument,
e.g.:
`javascript`
enumerate([0, 1], 2) // [[0, 0], [0, 1], [1, 0], [1, 1]]
> Because we often face problems in which an exhaustive examination of all
> cases is necessary or desirable.
— Donald Knuth, The Art of Computer Programming, Section 7.2.1.1, Generating All n-Tuples.
- Type:
-
-
- Alias:
`javascript
import { enumerate } from '@chocolatey/enumerator'
enumerate([0, 1], 2) // [[0, 0], [0, 1], [1, 0], [1, 1]]
`
Takes an array of alphabets, or a single alphabet and a length (number of times
to repeat the alphabet), and returns an array of all the permutations of
values from each alphabet in lexicographical order.
This is a wrapper around enumerator which gathers the generated
values into an array, i.e. the following are equivalent:
`javascript`
const array1 = enumerate(...args)
const array2 = Array.from(enumerator(...args))
- Type:
-
-
- Alias:
`javascript
import { enumerator } from '@chocolatey/enumerator'
for (const value of enumerator([0, 1], 2)) {
console.log(value) // [0, 0], [0, 1], [1, 0], [1, 1]
}
`
Takes an array of alphabets, or a single alphabet and a length (number of times
to repeat the alphabet), and yields all the permutations of values from each
alphabet in lexicographical order.
- Type:
`javascript
import { unfold } from '@chocolatey/enumerator'
const options = {
color: ['black', 'pink'],
size: ['small', 'large'],
discount: false,
}
const alphabets = unfold(options)
`
`javascript`
[
[["color", "black"], ["color", "pink"]], // 0
[["size", "small"], ["size", "large"]], // 1
[["discount", false]] // 2
]
Takes a plain object and flattens it into an array of arrays of key/value pairs
suitable for use as alphabets. The object is unchanged. The object's values are
coerced to arrays, so if a single value is already an array, it will need to be
wrapped in another array, e.g.:
`javascript
// before x
const data = {
loc: [x, y],
}
// after ✔
const data = {
loc: [[x, y]],
}
`
Suppose you've protected a Word document or zipfile with the password
"rosebud", but can't remember if any letters were uppercase, if it was one word
or two, or if there were any substitutions. A list of candidate passwords can
be generated by:
`javascript
const alphabets = [
['r', 'R'],
['o', 'O', '0'],
['s', 'S', '5'],
['e', 'E', '3'],
['', ' '],
['b', 'B'],
['u', 'U'],
['d', 'D'],
]
const passwords = enumerate(alphabets).map(it => it.join(''))
`
This generates 864 different candidates, including "rosebud", "r053buD",
"Rose Bud", and "ROSEBUD".
Although any types can be used as values, a specific task may require some
data munging to encode its choices as alphabets. To this end, a helper
function, unfold, is available which translates a plain object
into an array of alphabets of key/value pairs representing an option or
feature.
For example, if a product is available with the following options:
- color: red, black, pink
- size: small, medium, large
\- the permutations can be generated with:
`javascript
import { enumerate, unfold } from '@chocolatey/enumerator'
const options = {
color: ['red', 'black', 'pink'],
size: ['small', 'medium', 'large'],
}
const alphabets = unfold(options)
const products = enumerate(alphabets).map(Object.fromEntries)
`
\- which yields the following result:
`javascript``
[
{ color: 'red', size: 'small' },
{ color: 'red', size: 'medium' },
{ color: 'red', size: 'large' },
{ color: 'black', size: 'small' },
{ color: 'black', size: 'medium' },
{ color: 'black', size: 'large' },
{ color: 'pink', size: 'small' },
{ color: 'pink', size: 'medium' },
{ color: 'pink', size: 'large' }
]
The following NPM scripts are available:
- build - compile the library for testing and save to the target directory
- build:doc - generate the README's TOC (table of contents)
- build:release - compile the library for release and save to the target directory
- clean - remove the target directory and its contents
- rebuild - clean the target directory and recompile the library
- repl - launch a node REPL with the library loaded
- test - recompile the library and run the test suite
- test:run - run the test suite
- typecheck - sanity check the library's type definitions
- Maintained Node.js versions and compatible browsers
- @kingjs/enumerable.from-each
- @kingjs/odometer
1.1.1
Copyright © 2020-2021 by chocolateboy.
This is free software; you can redistribute it and/or modify it under the terms
of the MIT license.
[jsDelivr]: https://cdn.jsdelivr.net/npm/@chocolatey/enumerator
[unpkg]: https://unpkg.com/@chocolatey/enumerator