combos

Generate all possible permutations of an object's key-value pairs. Combos takes all the possible values an object's keys can have and creates all possible combinations of those values for each key.

This is perfect for reducing duplication in tests when multiple versions of an object should produce the same test results. This could be especially useful with React components and nontrivial prop combinations.

Install

$ npm install combos

Usage

Import/require the combos function and provide it with an object. The keys of the object are the keys you desire to have in your final objects. The values are an array, containing all possible values that given key can have. The return value is an array containing every version of the object with all possible combinations of the values.

A simple example helps explain:

1// Simple example
2// ES2015
3import combos from 'combos';
4
5// ES5
6const combos = require('combos');
7
8// Given an object shape of
9// {
10//   greeting: string,
11//   name: string,
12// }
13
14// Generate all possible combinations.
15// (Note: you don't have to restrict each
16// array of values to all have the same type.)
17const permutations = combos({
18  greeting: ['Hello', 'Hi'],
19  name: ['Jeremy', 'Jet'],
20});
21
22// 'greeting' has 2 possible values
23// 'name' has 2 possible values
24// Therefore, the final array will have 2*2 = 4 possible objects.
25
26// Output with 4 different objects:
27// =================================
28// [ { greeting: 'Hello', name: 'Jeremy' },
29//   { greeting: 'Hi',    name: 'Jeremy' },
30//   { greeting: 'Hello', name: 'Jet'    },
31//   { greeting: 'Hi',    name: 'Jet'    } ]

More complex example:

1import combos from 'combos';
2
3const permutations = combos({
4  greeting: ['Hello', 'Hi'],
5  isChecked: [true, false],
6  flag: [1, 2, 4],
7});
8
9// 'greeting' has 2 possible values
10// 'isChecked' has 2 possible values
11// 'flag' has 3 possible values
12// Therefore, the final array will have 2*2*3 = 12 possible objects.
13
14// Output with 12 different objects:
15// =================================
16// [ { greeting: 'Hello', isChecked: true,  flag: 1 },
17//   { greeting: 'Hi',    isChecked: true,  flag: 1 },
18//   { greeting: 'Hello', isChecked: false, flag: 1 },
19//   { greeting: 'Hi',    isChecked: false, flag: 1 },
20//   { greeting: 'Hello', isChecked: true,  flag: 2 },
21//   { greeting: 'Hi',    isChecked: true,  flag: 2 },
22//   { greeting: 'Hello', isChecked: false, flag: 2 },
23//   { greeting: 'Hi',    isChecked: false, flag: 2 },
24//   { greeting: 'Hello', isChecked: true,  flag: 4 },
25//   { greeting: 'Hi',    isChecked: true,  flag: 4 },
26//   { greeting: 'Hello', isChecked: false, flag: 4 },
27//   { greeting: 'Hi',    isChecked: false, flag: 4 } ]

Keeping a value constant:

1import combos from 'combos';
2
3const permutations = combos({
4  greeting: ['Hello', 'Hi'],
5  name: ['Jeremy'],
6});
7
8// 'greeting' has 2 possible values
9// 'name' has 1 possible value
10// Therefore, the final array will have 2*1 = 2 possible objects.
11
12// Output with 2 different objects:
13// =================================
14// [ { greeting: 'Hello', name: 'Jeremy' },
15//   { greeting: 'Hi',    name: 'Jeremy' } ]

Making a value optional:

1import combos from 'combos';
2
3const permutations = combos({
4  greeting: ['Hello', 'Hi'],
5  name: ['Jeremy', combos.UNDEF],
6});
7
8// 'greeting' has 2 possible values
9// 'name' has 2 possible values where one state is being absent
10// Therefore, the final array will have 2*2 = 4 possible objects.
11
12// Output with 4 different objects:
13// =================================
14// [ { greeting: 'Hello', name: 'Jeremy' },
15//   { greeting: 'Hi',    name: 'Jeremy' },
16//   { greeting: 'Hello'                 },
17//   { greeting: 'Hi'                    } ]