Fast cartesian product.

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

Fastest available library in JavaScript.

When producing millions of combinations or combining hundreds of arrays, big-cartesian should be used instead.

Testimonials

We are now using this library for ourworldindata.org and have seen an almost 50-fold performance increase from the naive method we used before!

@MarcelGerber

Example

import fastCartesian from 'fast-cartesian'

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

// Return initial indexes
console.log(
  fastCartesian(
    [
      ['red', 'blue'],
      ['circle', 'square'],
    ].map(Object.entries),
  ),
)
// [
//   [ [ '0', 'red' ], [ '0', 'circle' ] ],
//   [ [ '0', 'red' ], [ '1', 'square' ] ],
//   [ [ '1', 'blue' ], [ '0', 'circle' ] ],
//   [ [ '1', 'blue' ], [ '1', '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

This package is an ES module and must be loaded using an import or import() statement, not require().

API

fastCartesian(inputs)

inputs: Array<Array>
Return value: Array<Array>

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

Benchmarks

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

## fast-cartesian ######################
1 array                           1.08ms
2 arrays                          1.15ms
4 arrays                          2.81ms
8 arrays                          1.60ms
16 arrays                         4.28ms

## cartesian-product ###################
1 array                           3.56ms
2 arrays                          2.72ms
4 arrays                         11.21ms
8 arrays                         13.41ms
16 arrays                        19.29ms

## big-cartesian #######################
1 array                           7.73ms
2 arrays                          7.40ms
4 arrays                          8.70ms
8 arrays                          4.46ms
16 arrays                        17.28ms

## power-cartesian-product #############
1 array                           6.15ms
2 arrays                          7.96ms
4 arrays                         11.84ms
8 arrays                         17.37ms
16 arrays                        19.38ms

## cartesian ###########################
1 array                           6.63ms
2 arrays                         16.03ms
4 arrays                         17.82ms
8 arrays                         22.11ms
16 arrays                        33.21ms

## fast-cartesian-product ##############
1 array                          13.75ms
2 arrays                         17.22ms
4 arrays                         23.89ms
8 arrays                         39.08ms
16 arrays                        61.45ms

## lodash.product ######################
1 array                          36.66ms
2 arrays                         37.85ms
4 arrays                         41.69ms
8 arrays                         50.38ms
16 arrays                        73.87ms

Support

For any question, don't hesitate to submit an issue on GitHub.

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 💻 🎨 🤔 📖

Marcel Gerber 💻

Paul Heidenreich 💻