big-cartesian

Cartesian product for big inputs.

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

• can handle an infinite number of combinations
• requires almost no memory

This module is perfect when you combine hundreds of arrays or when those arrays produce millions of combinations. Otherwise you should use fast-cartesian instead as it is much faster.

Example

import bigCartesian from 'big-cartesian'

for (const values of bigCartesian([
  ['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 big-cartesian

This package works in both Node.js >=14.18.0 and browsers. It is an ES module and must be loaded using an import or import() statement, not require().

API

bigCartesian(inputs)

inputs: Array<Array | Iterable | GeneratorFunction>
Return value: Iterable<Array>

Iterates over each combination of inputs.

Limits

This works with an infinite number of combinations.

Arrays in JavaScript have a size limit of 4 trillions of elements. You can bypass this limit by using iterables or generator functions instead.

import bigCartesian from 'big-cartesian'

const generator = function* () {
  // This generator can generate an infinite number of elements
}

// Notice we pass the function itself: `generator` not `generator()`
for (const values of bigCartesian([['red', 'blue'], generator])) {
  console.log(values)
}

Benchmarks

See the following benchmarks.

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

Changelog

4.5.0

Internal

• Rewrite codebase in TypeScript