Fast cartesian product.

Retrieves every possible combination between several arrays (cartesian product):

• fastest available library in JavaScript
• can handle trillions of combinations without crashing your machine

Example

const { cartesianArray, cartesianIterate } = require('fast-cartesian')

console.log(cartesianArray(['red', 'blue'], ['circle', 'square']))
// [
//   [ 'red', 'circle' ],
//   [ 'red', 'square' ],
//   [ 'blue', 'circle' ],
//   [ 'blue', 'square' ]
// ]

// Return initial indexes
console.log(
  cartesianArray(
    Object.entries(['red', 'blue']),
    Object.entries(['circle', 'square']),
  ),
)
// [
//   [ [ '0', 'red' ], [ '0', 'circle' ] ],
//   [ [ '0', 'red' ], [ '1', 'square' ] ],
//   [ [ '1', 'blue' ], [ '0', 'circle' ] ],
//   [ [ '1', 'blue' ], [ '1', 'square' ] ]
// ]

// Iterate over each combination
for (const values of cartesianIterate(['red', 'blue'], ['circle', 'square'])) {
  console.log(values)
}
// [ 'red', 'circle' ]
// [ 'red', 'square' ]
// [ 'blue', 'circle' ]
// [ 'blue', 'square' ]

Demo

You can try this library:

• either directly in your browser.
• or by executing the examples files in a terminal.

Install

npm install fast-cartesian

Usage

const { cartesianArray, cartesianIterate } = require('fast-cartesian')

const inputs = [['red', 'blue'], ['circle', 'square']]

const combinations = cartesianArray(...inputs)

for (const combination of cartesianIterate(...inputs)) {
}

API

cartesianArray(...inputs)

inputs: Array (one or several)
Return value: array[]

Returns a two-dimensional array where each row is a combination of inputs.

cartesianIterate(...inputs)

inputs: Array (one or several)
Return value: Iterable

Iterates over each combination of inputs.

Slower than cartesianArray() but requires much less memory, which enables handling trillions of combinations.

Benchmarks

The following benchmarks compare the performance of this library against alternatives (cartesian-product, fast-cartesian-product, power-cartesian-product, cartesian and lodash.product).

## fast-cartesian ###########
1 array                0.93ms
2 arrays               1.41ms
4 arrays               1.57ms
8 arrays               1.69ms
16 arrays              3.88ms

## fast-cartesian-product ###
1 array                1.14ms
2 arrays               1.46ms
4 arrays               2.46ms
8 arrays               4.37ms
16 arrays             10.42ms

## power-cartesian-product ##
1 array                4.70ms
2 arrays               5.19ms
4 arrays               7.33ms
8 arrays              11.47ms
16 arrays             19.21ms

## cartesian-product ########
1 array                2.57ms
2 arrays               3.68ms
4 arrays              10.79ms
8 arrays              14.33ms
16 arrays             20.79ms

## cartesian ################
1 array                6.39ms
2 arrays              16.54ms
4 arrays              17.69ms
8 arrays              22.52ms
16 arrays             34.37ms

## lodash.product ###########
1 array               38.81ms
2 arrays              40.43ms
4 arrays              43.31ms
8 arrays              54.85ms
16 arrays             82.06ms

Support

If you found a bug or would like a new feature, don't hesitate to submit an issue on GitHub.

For other questions, feel free to chat with us on Gitter.

Everyone is welcome regardless of personal background. We enforce a Code of conduct in order to promote a positive and inclusive environment.

Contributing

This project was made with ❤️. The simplest way to give back is by starring and sharing it online.

If the documentation is unclear or has a typo, please click on the page's Edit button (pencil icon) and suggest a correction.

If you would like to help us fix a bug or add a new feature, please check our guidelines. Pull requests are welcome!

ehmicky 💻 🎨 🤔 📖