# combos

> Generate all possible permutations of an object's key-value pairs

Latest version **0.2.0** (published 2016-08-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install combos
pnpm add combos
yarn add combos
bun add combos
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.0 |
| Published | 2016-08-15 |
| First published | 2016-08-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 27 |
| Author | Jeremy Fairbank |
| Maintainers | elpapapollo |
| Keywords | testing, test, object, combo, combinations, combos, values, shapes |

## Links

- npm: https://www.npmjs.com/package/combos
- Repository: https://github.com/jfairbank/combos
- Homepage: https://github.com/jfairbank/combos#readme
- Issues: https://github.com/jfairbank/combos/issues
- npm.io page: https://npm.io/package/combos

## Alternatives

- [duck](https://npm.io/package/duck.md) — 4.2M weekly downloads
- [ava](https://npm.io/package/ava.md) — 560.2K weekly downloads
- [storybook-addon-module-mock](https://npm.io/package/storybook-addon-module-mock.md) — 71.7K weekly downloads
- [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads
- [@ethereum-waffle/mock-contract](https://npm.io/package/@ethereum-waffle/mock-contract.md) — 40.0K weekly downloads

## Recent versions

- 0.2.0 (latest) — 2016-08-15
- 0.1.0 — 2016-08-03

## README

# combos

[![Travis branch](https://img.shields.io/travis/jfairbank/combos/master.svg?style=flat-square)](https://travis-ci.org/jfairbank/combos)
[![npm](https://img.shields.io/npm/v/combos.svg?style=flat-square)](https://www.npmjs.com/package/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:

```js
// Simple example
// ES2015
import combos from 'combos';

// ES5
const combos = require('combos');

// Given an object shape of
// {
//   greeting: string,
//   name: string,
// }

// Generate all possible combinations.
// (Note: you don't have to restrict each
// array of values to all have the same type.)
const permutations = combos({
  greeting: ['Hello', 'Hi'],
  name: ['Jeremy', 'Jet'],
});

// 'greeting' has 2 possible values
// 'name' has 2 possible values
// Therefore, the final array will have 2*2 = 4 possible objects.

// Output with 4 different objects:
// =================================
// [ { greeting: 'Hello', name: 'Jeremy' },
//   { greeting: 'Hi',    name: 'Jeremy' },
//   { greeting: 'Hello', name: 'Jet'    },
//   { greeting: 'Hi',    name: 'Jet'    } ]
```

More complex example:

```js
import combos from 'combos';

const permutations = combos({
  greeting: ['Hello', 'Hi'],
  isChecked: [true, false],
  flag: [1, 2, 4],
});

// 'greeting' has 2 possible values
// 'isChecked' has 2 possible values
// 'flag' has 3 possible values
// Therefore, the final array will have 2*2*3 = 12 possible objects.

// Output with 12 different objects:
// =================================
// [ { greeting: 'Hello', isChecked: true,  flag: 1 },
//   { greeting: 'Hi',    isChecked: true,  flag: 1 },
//   { greeting: 'Hello', isChecked: false, flag: 1 },
//   { greeting: 'Hi',    isChecked: false, flag: 1 },
//   { greeting: 'Hello', isChecked: true,  flag: 2 },
//   { greeting: 'Hi',    isChecked: true,  flag: 2 },
//   { greeting: 'Hello', isChecked: false, flag: 2 },
//   { greeting: 'Hi',    isChecked: false, flag: 2 },
//   { greeting: 'Hello', isChecked: true,  flag: 4 },
//   { greeting: 'Hi',    isChecked: true,  flag: 4 },
//   { greeting: 'Hello', isChecked: false, flag: 4 },
//   { greeting: 'Hi',    isChecked: false, flag: 4 } ]
```

Keeping a value constant:

```js
import combos from 'combos';

const permutations = combos({
  greeting: ['Hello', 'Hi'],
  name: ['Jeremy'],
});

// 'greeting' has 2 possible values
// 'name' has 1 possible value
// Therefore, the final array will have 2*1 = 2 possible objects.

// Output with 2 different objects:
// =================================
// [ { greeting: 'Hello', name: 'Jeremy' },
//   { greeting: 'Hi',    name: 'Jeremy' } ]
```

Making a value optional:

```js
import combos from 'combos';

const permutations = combos({
  greeting: ['Hello', 'Hi'],
  name: ['Jeremy', combos.UNDEF],
});

// 'greeting' has 2 possible values
// 'name' has 2 possible values where one state is being absent
// Therefore, the final array will have 2*2 = 4 possible objects.

// Output with 4 different objects:
// =================================
// [ { greeting: 'Hello', name: 'Jeremy' },
//   { greeting: 'Hi',    name: 'Jeremy' },
//   { greeting: 'Hello'                 },
//   { greeting: 'Hi'                    } ]
```

---
_Source: https://npm.io/package/combos · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._