feat(array): cartesianProduct

benchmarks/array/product.bench.ts

@@ -0,0 +1,30 @@
+import * as _ from 'radashi'
+
+describe('product', () => {
+  bench('with no arguments', () => {
+    _.product([])
+  })
+
+  bench('with single empty array', () => {
+    _.product([[]])
+  })
+
+  bench('with one non-empty array (n=1)', () => {
+    _.product([['a', 'b', 'c']])
+  })
+
+  bench('with two small arrays (n=2)', () => {
+    _.product([
+      ['red', 'blue'],
+      ['fast', 'slow'],
+    ])
+  })
+
+  bench('with three small arrays (n=3)', () => {
+    _.product([
+      ['red', 'blue'],
+      ['fast', 'slow'],
+      ['big', 'small'],
+    ])
+  })
+})

docs/array/product.mdx

@@ -0,0 +1,31 @@
+---
+title: product
+description: Perform a Cartesian product of arrays
+---
+
+### Usage
+
+Creates an [n-ary Cartesian product](https://en.wikipedia.org/wiki/Cartesian_product#n-ary_Cartesian_product) from the given arrays.
+The input is an array of arrays, and the output is an array of arrays representing all
+possible combinations where the first element is from the first array, the second element
+is from the second array, and so on.
+
+```ts
+import * as _ from 'radashi'
+
+const colors = ['red', 'blue']
+const sizes = ['big', 'small']
+const compliments = ['nice', 'great']
+
+_.product([colors, sizes, compliments])
+// => [
+//   ['red', 'big', 'nice'],
+//   ['red', 'big', 'great'],
+//   ['red', 'small', 'nice'],
+//   ['red', 'small', 'great'],
+//   ['blue', 'big', 'nice'],
+//   ['blue', 'big', 'great'],
+//   ['blue', 'small', 'nice'],
+//   ['blue', 'small', 'great']
+// ]
+```

src/array/product.ts

@@ -0,0 +1,39 @@
+import { castArray } from 'radashi'
+
+/**
+ * Create an [n-ary Cartesian product](https://en.wikipedia.org/wiki/Cartesian_product#n-ary_Cartesian_product) from the given arrays.
+ *
+ * @see https://radashi.js.org/reference/array/product
+ * @example
+ * ```ts
+ * product([['red', 'blue'], ['big', 'small'], ['fast', 'slow']])
+ * // [
+ * //   ['red', 'big', 'fast'],
+ * //   ['red', 'big', 'slow'],
+ * //   ['red', 'small', 'fast'],
+ * //   ['red', 'small', 'slow'],
+ * //   ['blue', 'big', 'fast'],
+ * //   ['blue', 'big', 'slow'],
+ * //   ['blue', 'small', 'fast'],
+ * //   ['blue', 'small', 'slow']
+ * // ]
+ * ```
+ */
+export function product<T extends any[]>(
+  ...arrays: [...T]
+): Array<{ [K in keyof T]: T[K][number] }>
+export function product<T extends any[][]>(...arrays: T): T[][] {
+  let out: T[][] = [[]]
+  for (const array of arrays) {
+    const result = []
+    for (const currentArray of out) {
+      for (const item of array) {
+        const currentArrayCopy = castArray(currentArray)
+        currentArrayCopy.push(item)
+        result.push(currentArrayCopy)
+      }
+    }
+    out = result
+  }
+  return out
+}

src/mod.ts

@@ -16,6 +16,7 @@ export * from './array/list.ts'
 export * from './array/mapify.ts'
 export * from './array/merge.ts'
 export * from './array/objectify.ts'
+export * from './array/product.ts'
 export * from './array/replace.ts'
 export * from './array/replaceOrAppend.ts'
 export * from './array/select.ts'
@@ -28,7 +29,6 @@ export * from './array/unique.ts'
 export * from './array/unzip.ts'
 export * from './array/zip.ts'
 export * from './array/zipToObject.ts'
-
 export * from './async/AggregateError.ts'
 export * from './async/all.ts'
 export * from './async/defer.ts'

tests/array/product.test.ts

@@ -0,0 +1,47 @@
+import * as _ from 'radashi'
+
+describe('product', () => {
+  test('returns an empty array when given an array containing an empty array (n=1)', () => {
+    expect(_.product([])).toEqual([])
+  })
+  test('returns an empty array when given multiple empty arrays (n>1)', () => {
+    expect(_.product([], [], [])).toEqual([])
+  })
+  test('returns an empty array when one of the arrays in the input is empty (n>1)', () => {
+    expect(_.product(['1', '2', '3'], [])).toEqual([])
+  })
+  test('returns an array of singletons when given a single array (n=1)', () => {
+    expect(_.product(['1', '2', '3'])).toEqual([['1'], ['2'], ['3']])
+  })
+  test('performs a correct Cartesian product for two arrays (n=2)', () => {
+    expect(
+      _.product(
+        ['red', 'blue'],
+        ['fast', 'slow'],
+      ),
+    ).toEqual([
+      ['red', 'fast'],
+      ['red', 'slow'],
+      ['blue', 'fast'],
+      ['blue', 'slow'],
+    ])
+  })
+  test('performs a correct Cartesian product for more than two arrays (n>2)', () => {
+    expect(
+      _.product(
+        ['red', 'blue'],
+        ['fast', 'slow'],
+        ['big', 'small'],
+      ),
+    ).toEqual([
+      ['red', 'fast', 'big'],
+      ['red', 'fast', 'small'],
+      ['red', 'slow', 'big'],
+      ['red', 'slow', 'small'],
+      ['blue', 'fast', 'big'],
+      ['blue', 'fast', 'small'],
+      ['blue', 'slow', 'big'],
+      ['blue', 'slow', 'small'],
+    ])  
+  })
+})