feat(iterator): add cartesianProduct to es-toolkit/iterator

docs/iterator/intro.md

@@ -15,7 +15,7 @@ takeWhile(hugeArray.values(), x => x < 100)
 
 Every function takes an `Iterator` as its first argument — the value you get from `array.values()`, a generator function, a `Map`/`Set` iterator, and so on. Lazy functions return an `IteratorObject` whose prototype is the native `Iterator.prototype`, so the result carries every [native iterator helper](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator) (`map`, `filter`, `take`, `drop`, `flatMap`, `reduce`, `toArray`, ...) and chains with them seamlessly.
 
-The module only ships what the native helpers are missing. Count-based `take` and `drop`, `map`, `filter`, and friends already exist on `Iterator.prototype`; es-toolkit adds the predicate-based, stateful, and multi-source operations on top: [`chunk`](./reference/chunk.md), [`count`](./reference/count.md), [`dropWhile`](./reference/dropWhile.md), [`head`](./reference/head.md), [`iterate`](./reference/iterate.md), [`partition`](./reference/partition.md), [`range`](./reference/range.md), [`scan`](./reference/scan.md), [`takeWhile`](./reference/takeWhile.md), [`uniqBy`](./reference/uniqBy.md), and [`zip`](./reference/zip.md).
+The module only ships what the native helpers are missing. Count-based `take` and `drop`, `map`, `filter`, and friends already exist on `Iterator.prototype`; es-toolkit adds the predicate-based, stateful, and multi-source operations on top: [`cartesianProduct`](./reference/cartesianProduct.md), [`chunk`](./reference/chunk.md), [`count`](./reference/count.md), [`dropWhile`](./reference/dropWhile.md), [`head`](./reference/head.md), [`iterate`](./reference/iterate.md), [`partition`](./reference/partition.md), [`range`](./reference/range.md), [`scan`](./reference/scan.md), [`takeWhile`](./reference/takeWhile.md), [`uniqBy`](./reference/uniqBy.md), and [`zip`](./reference/zip.md).
 
 ## Lazy evaluation and infinite sequences
 

docs/iterator/reference/cartesianProduct.md

@@ -0,0 +1,53 @@
+# cartesianProduct (for `Iterator`s)
+
+Lazily computes the Cartesian product of the source iterators.
+
+```typescript
+const pairs = cartesianProduct(source1, source2);
+```
+
+## Usage
+
+### `cartesianProduct(...sources)`
+
+Use `cartesianProduct` when you want every possible combination of elements from several sequences — for example, pairing every user with every role, or generating test cases from parameter sets. Tuples are yielded in lexicographic order: the rightmost source advances fastest, like the digits of an odometer, just as in the array [`cartesianProduct`](../../reference/array/cartesianProduct.md).
+
+Because every source except the first is traversed many times, those sources are buffered into arrays when iteration starts. The first source is consumed lazily, one element at a time, so it may be infinite. When iteration ends — because the first source ran out, another source was empty, or the consumer stopped early — every source is closed via its `return` method.
+
+If no sources are passed, a single empty tuple is yielded. If any source is empty, nothing is yielded.
+
+```typescript
+import { cartesianProduct, range } from 'es-toolkit/iterator';
+
+// Pair every element of the first source with every element of the second.
+cartesianProduct([1, 2].values(), ['a', 'b'].values()).toArray();
+// Returns: [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]
+
+// The rightmost source advances fastest.
+cartesianProduct([0, 1].values(), [0, 1].values(), [0, 1].values()).toArray();
+// Returns: [[0, 0, 0], [0, 0, 1], [0, 1, 0], [0, 1, 1], [1, 0, 0], [1, 0, 1], [1, 1, 0], [1, 1, 1]]
+
+// The first source may be infinite; tuples are produced on demand.
+cartesianProduct(range(0, Infinity), ['a', 'b'].values()).take(3).toArray();
+// Returns: [[0, 'a'], [0, 'b'], [1, 'a']]
+```
+
+#### Parameters
+
+- `sources` (`Array<Iterator<unknown>>`): The iterators to take the product of.
+
+#### Returns
+
+(`IteratorObject<[...], undefined>`): A lazy iterator over tuples representing the Cartesian product, typed after the sources. It carries every native iterator helper (`map`, `take`, `toArray`, ...) for further chaining.
+
+### `cartesianProduct(other)` with `pipe`
+
+When composing transformations with [`pipe`](../../fp/reference/pipe.md), import the curried form from `es-toolkit/fp/iterator`. It takes one other iterator and pairs every element of the piped iterator with every element of it, with the other iterator advancing fastest.
+
+```typescript
+import { pipe } from 'es-toolkit/fp';
+import { cartesianProduct, toArray } from 'es-toolkit/fp/iterator';
+
+pipe([1, 2].values(), cartesianProduct(['a', 'b'].values()), toArray());
+// Returns: [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]
+```

docs/ja/iterator/intro.md

@@ -15,7 +15,7 @@ takeWhile(hugeArray.values(), x => x < 100)
 
 すべての関数は、最初の引数として `Iterator` を受け取ります。これは `array.values()` から得られる値、ジェネレータ関数、`Map`/`Set` のイテレータなどです。遅延評価の関数は、ネイティブの `Iterator.prototype` をプロトタイプに持つ `IteratorObject` を返すため、結果はすべての[ネイティブのイテレータヘルパー](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator)（`map`、`filter`、`take`、`drop`、`flatMap`、`reduce`、`toArray` など）を備えており、それらとシームレスにチェーンできます。
 
-このモジュールは、ネイティブのヘルパーに欠けているものだけを提供します。個数ベースの `take` と `drop`、`map`、`filter` などはすでに `Iterator.prototype` に存在します。es-toolkit はその上に、条件ベースの操作、状態を持つ操作、複数のソースを扱う操作を追加します。[`chunk`](./reference/chunk.md)、[`count`](./reference/count.md)、[`dropWhile`](./reference/dropWhile.md)、[`head`](./reference/head.md)、[`iterate`](./reference/iterate.md)、[`partition`](./reference/partition.md)、[`range`](./reference/range.md)、[`scan`](./reference/scan.md)、[`takeWhile`](./reference/takeWhile.md)、[`uniqBy`](./reference/uniqBy.md)、[`zip`](./reference/zip.md) です。
+このモジュールは、ネイティブのヘルパーに欠けているものだけを提供します。個数ベースの `take` と `drop`、`map`、`filter` などはすでに `Iterator.prototype` に存在します。es-toolkit はその上に、条件ベースの操作、状態を持つ操作、複数のソースを扱う操作を追加します。[`cartesianProduct`](./reference/cartesianProduct.md)、[`chunk`](./reference/chunk.md)、[`count`](./reference/count.md)、[`dropWhile`](./reference/dropWhile.md)、[`head`](./reference/head.md)、[`iterate`](./reference/iterate.md)、[`partition`](./reference/partition.md)、[`range`](./reference/range.md)、[`scan`](./reference/scan.md)、[`takeWhile`](./reference/takeWhile.md)、[`uniqBy`](./reference/uniqBy.md)、[`zip`](./reference/zip.md) です。
 
 ## 遅延評価と無限シーケンス
 

docs/ja/iterator/reference/cartesianProduct.md

@@ -0,0 +1,53 @@
+# cartesianProduct (`Iterator`)
+
+ソースイテレータのデカルト積を遅延的に計算します。
+
+```typescript
+const pairs = cartesianProduct(source1, source2);
+```
+
+## 使用法
+
+### `cartesianProduct(...sources)`
+
+複数のシーケンスから要素のすべての組み合わせが必要なときに `cartesianProduct` を使用してください。例えば、すべてのユーザーとすべてのロールを組み合わせたり、パラメータの集合からテストケースを生成したりする場合です。タプルは辞書式順序で生成されます。配列版の [`cartesianProduct`](../../reference/array/cartesianProduct.md) と同様に、最も右のソースがオドメーターの桁のように最も速く進みます。
+
+最初のソース以外は何度も走査されるため、反復の開始時に配列としてバッファリングされます。最初のソースは要素を 1 つずつ遅延的に消費するので、無限イテレータでも構いません。反復が終わると — 最初のソースが尽きた場合も、他のソースが空だった場合も、消費側が早く止まった場合も — すべてのソースが `return` メソッドを通じて閉じられます。
+
+ソースを渡さない場合は、空のタプルを 1 つだけ生成します。いずれかのソースが空の場合は、何も生成しません。
+
+```typescript
+import { cartesianProduct, range } from 'es-toolkit/iterator';
+
+// 最初のソースのすべての要素を、2 番目のソースのすべての要素と組み合わせます。
+cartesianProduct([1, 2].values(), ['a', 'b'].values()).toArray();
+// 戻り値: [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]
+
+// 最も右のソースが最も速く進みます。
+cartesianProduct([0, 1].values(), [0, 1].values(), [0, 1].values()).toArray();
+// 戻り値: [[0, 0, 0], [0, 0, 1], [0, 1, 0], [0, 1, 1], [1, 0, 0], [1, 0, 1], [1, 1, 0], [1, 1, 1]]
+
+// 最初のソースは無限でも構いません。タプルは必要になるたびに生成されます。
+cartesianProduct(range(0, Infinity), ['a', 'b'].values()).take(3).toArray();
+// 戻り値: [[0, 'a'], [0, 'b'], [1, 'a']]
+```
+
+#### パラメータ
+
+- `sources` (`Array<Iterator<unknown>>`): 積を計算するイテレータ。
+
+#### 戻り値
+
+(`IteratorObject<[...], undefined>`): デカルト積を表すタプルを生成する遅延イテレータ。型はソースに従って決まります。すべてのネイティブイテレータヘルパー(`map`、`take`、`toArray` など)を備えているため、続けてチェーンできます。
+
+### `pipe` と組み合わせる `cartesianProduct(other)`
+
+[`pipe`](../../fp/reference/pipe.md) で変換を合成する場合は、`es-toolkit/fp/iterator` からカリー化された形式をインポートしてください。他のイテレータを 1 つ受け取り、パイプで渡されたイテレータのすべての要素をそのイテレータのすべての要素と組み合わせます。他のイテレータ側がより速く進みます。
+
+```typescript
+import { pipe } from 'es-toolkit/fp';
+import { cartesianProduct, toArray } from 'es-toolkit/fp/iterator';
+
+pipe([1, 2].values(), cartesianProduct(['a', 'b'].values()), toArray());
+// 戻り値: [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]
+```

docs/ko/iterator/intro.md

@@ -15,7 +15,7 @@ takeWhile(hugeArray.values(), x => x < 100)
 
 모든 함수는 첫 번째 인자로 `Iterator`를 받아요 — `array.values()`로 얻는 값, 제너레이터 함수, `Map`/`Set` 이터레이터 등이요. 지연 평가 함수는 프로토타입이 네이티브 `Iterator.prototype`인 `IteratorObject`를 반환하기 때문에, 결과는 모든 [네이티브 이터레이터 헬퍼](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator)(`map`, `filter`, `take`, `drop`, `flatMap`, `reduce`, `toArray`, ...)를 갖추고 있고, 이들과 자연스럽게 이어서 체이닝할 수 있어요.
 
-이 모듈은 네이티브 헬퍼에 없는 것만 제공해요. 개수 기반의 `take`와 `drop`, `map`, `filter` 등은 이미 `Iterator.prototype`에 있어요. es-toolkit은 그 위에 조건 기반 연산, 상태를 가지는 연산, 여러 소스를 다루는 연산을 더해요: [`chunk`](./reference/chunk.md), [`count`](./reference/count.md), [`dropWhile`](./reference/dropWhile.md), [`head`](./reference/head.md), [`iterate`](./reference/iterate.md), [`partition`](./reference/partition.md), [`range`](./reference/range.md), [`scan`](./reference/scan.md), [`takeWhile`](./reference/takeWhile.md), [`uniqBy`](./reference/uniqBy.md), [`zip`](./reference/zip.md)이에요.
+이 모듈은 네이티브 헬퍼에 없는 것만 제공해요. 개수 기반의 `take`와 `drop`, `map`, `filter` 등은 이미 `Iterator.prototype`에 있어요. es-toolkit은 그 위에 조건 기반 연산, 상태를 가지는 연산, 여러 소스를 다루는 연산을 더해요: [`cartesianProduct`](./reference/cartesianProduct.md), [`chunk`](./reference/chunk.md), [`count`](./reference/count.md), [`dropWhile`](./reference/dropWhile.md), [`head`](./reference/head.md), [`iterate`](./reference/iterate.md), [`partition`](./reference/partition.md), [`range`](./reference/range.md), [`scan`](./reference/scan.md), [`takeWhile`](./reference/takeWhile.md), [`uniqBy`](./reference/uniqBy.md), [`zip`](./reference/zip.md)이에요.
 
 ## 지연 평가와 무한 시퀀스
 

docs/ko/iterator/reference/cartesianProduct.md

@@ -0,0 +1,53 @@
+# cartesianProduct (`Iterator`)
+
+소스 이터레이터들의 데카르트 곱을 지연 평가 방식으로 계산해요.
+
+```typescript
+const pairs = cartesianProduct(source1, source2);
+```
+
+## 사용법
+
+### `cartesianProduct(...sources)`
+
+여러 시퀀스에서 가능한 모든 요소 조합이 필요할 때 `cartesianProduct`를 사용하세요. 예를 들어 모든 사용자와 모든 역할을 짝짓거나, 파라미터 집합으로 테스트 케이스를 만들 때요. 튜플은 사전식 순서로 나와요. 배열 버전 [`cartesianProduct`](../../reference/array/cartesianProduct.md)와 마찬가지로, 가장 오른쪽 소스가 주행계 숫자처럼 가장 빠르게 넘어가요.
+
+첫 번째를 제외한 소스들은 여러 번 순회되기 때문에, 순회가 시작될 때 배열로 버퍼링돼요. 첫 번째 소스는 요소를 하나씩 지연 소비하므로 무한 이터레이터여도 괜찮아요. 순회가 끝나면 — 첫 번째 소스가 소진됐든, 다른 소스가 비어 있었든, 소비자가 일찍 멈췄든 — 모든 소스가 `return` 메서드를 통해 닫혀요.
+
+소스를 전달하지 않으면 빈 튜플 하나를 내보내요. 소스 중 하나라도 비어 있으면 아무것도 내보내지 않아요.
+
+```typescript
+import { cartesianProduct, range } from 'es-toolkit/iterator';
+
+// 첫 번째 소스의 모든 요소를 두 번째 소스의 모든 요소와 짝지어요.
+cartesianProduct([1, 2].values(), ['a', 'b'].values()).toArray();
+// 반환 값: [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]
+
+// 가장 오른쪽 소스가 가장 빠르게 넘어가요.
+cartesianProduct([0, 1].values(), [0, 1].values(), [0, 1].values()).toArray();
+// 반환 값: [[0, 0, 0], [0, 0, 1], [0, 1, 0], [0, 1, 1], [1, 0, 0], [1, 0, 1], [1, 1, 0], [1, 1, 1]]
+
+// 첫 번째 소스는 무한이어도 돼요. 튜플은 필요할 때마다 만들어져요.
+cartesianProduct(range(0, Infinity), ['a', 'b'].values()).take(3).toArray();
+// 반환 값: [[0, 'a'], [0, 'b'], [1, 'a']]
+```
+
+#### 파라미터
+
+- `sources` (`Array<Iterator<unknown>>`): 곱을 계산할 이터레이터들이에요.
+
+#### 반환 값
+
+(`IteratorObject<[...], undefined>`): 데카르트 곱의 튜플을 내보내는 지연 평가 이터레이터예요. 타입은 소스들을 따라 정해져요. 모든 네이티브 이터레이터 헬퍼(`map`, `take`, `toArray`, ...)를 갖추고 있어서 이어서 체이닝할 수 있어요.
+
+### `pipe`와 함께 쓰는 `cartesianProduct(other)`
+
+[`pipe`](../../fp/reference/pipe.md)로 변환을 조합할 때는 `es-toolkit/fp/iterator`에서 커링된 형태를 가져오세요. 다른 이터레이터 하나를 받아서, 파이프로 전달된 이터레이터의 모든 요소를 그 이터레이터의 모든 요소와 짝지어요. 다른 이터레이터 쪽이 더 빠르게 넘어가요.
+
+```typescript
+import { pipe } from 'es-toolkit/fp';
+import { cartesianProduct, toArray } from 'es-toolkit/fp/iterator';
+
+pipe([1, 2].values(), cartesianProduct(['a', 'b'].values()), toArray());
+// 반환 값: [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]
+```

docs/zh_hans/iterator/intro.md

@@ -15,7 +15,7 @@ takeWhile(hugeArray.values(), x => x < 100)
 
 每个函数都接收一个 `Iterator` 作为第一个参数——也就是 `array.values()`、生成器函数、`Map`/`Set` 迭代器等给出的值。惰性函数返回的 `IteratorObject` 以原生的 `Iterator.prototype` 为原型,因此结果带有所有[原生迭代器辅助方法](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator)(`map`、`filter`、`take`、`drop`、`flatMap`、`reduce`、`toArray` 等),可以与它们无缝地链式调用。
 
-这个模块只提供原生辅助方法缺少的部分。基于数量的 `take` 和 `drop`,以及 `map`、`filter` 等已经存在于 `Iterator.prototype` 上;es-toolkit 在此之上补充了基于谓词的、有状态的以及多数据源的操作:[`chunk`](./reference/chunk.md)、[`count`](./reference/count.md)、[`dropWhile`](./reference/dropWhile.md)、[`head`](./reference/head.md)、[`iterate`](./reference/iterate.md)、[`partition`](./reference/partition.md)、[`range`](./reference/range.md)、[`scan`](./reference/scan.md)、[`takeWhile`](./reference/takeWhile.md)、[`uniqBy`](./reference/uniqBy.md) 和 [`zip`](./reference/zip.md)。
+这个模块只提供原生辅助方法缺少的部分。基于数量的 `take` 和 `drop`,以及 `map`、`filter` 等已经存在于 `Iterator.prototype` 上;es-toolkit 在此之上补充了基于谓词的、有状态的以及多数据源的操作:[`cartesianProduct`](./reference/cartesianProduct.md)、[`chunk`](./reference/chunk.md)、[`count`](./reference/count.md)、[`dropWhile`](./reference/dropWhile.md)、[`head`](./reference/head.md)、[`iterate`](./reference/iterate.md)、[`partition`](./reference/partition.md)、[`range`](./reference/range.md)、[`scan`](./reference/scan.md)、[`takeWhile`](./reference/takeWhile.md)、[`uniqBy`](./reference/uniqBy.md) 和 [`zip`](./reference/zip.md)。
 
 ## 惰性求值与无限序列
 

docs/zh_hans/iterator/reference/cartesianProduct.md

@@ -0,0 +1,53 @@
+# cartesianProduct (`Iterator`)
+
+惰性地计算源迭代器的笛卡尔积。
+
+```typescript
+const pairs = cartesianProduct(source1, source2);
+```
+
+## 用法
+
+### `cartesianProduct(...sources)`
+
+当你需要多个序列中元素的所有可能组合时,请使用 `cartesianProduct`。例如,将每个用户与每个角色配对,或从参数集合生成测试用例。元组按字典序产生:与数组版 [`cartesianProduct`](../../reference/array/cartesianProduct.md) 一样,最右边的源推进得最快,就像里程表的数字一样。
+
+由于除第一个源之外的所有源都会被多次遍历,它们会在迭代开始时被缓冲为数组。第一个源逐个元素地惰性消费,因此可以是无限迭代器。当迭代结束时 — 无论是第一个源耗尽、其他源为空,还是消费者提前停止 — 每个源都会通过其 `return` 方法关闭。
+
+如果不传入任何源,则只产生一个空元组。如果任何一个源为空,则不产生任何内容。
+
+```typescript
+import { cartesianProduct, range } from 'es-toolkit/iterator';
+
+// 将第一个源的每个元素与第二个源的每个元素配对。
+cartesianProduct([1, 2].values(), ['a', 'b'].values()).toArray();
+// 返回值: [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]
+
+// 最右边的源推进得最快。
+cartesianProduct([0, 1].values(), [0, 1].values(), [0, 1].values()).toArray();
+// 返回值: [[0, 0, 0], [0, 0, 1], [0, 1, 0], [0, 1, 1], [1, 0, 0], [1, 0, 1], [1, 1, 0], [1, 1, 1]]
+
+// 第一个源可以是无限的;元组按需生成。
+cartesianProduct(range(0, Infinity), ['a', 'b'].values()).take(3).toArray();
+// 返回值: [[0, 'a'], [0, 'b'], [1, 'a']]
+```
+
+#### 参数
+
+- `sources` (`Array<Iterator<unknown>>`): 要计算笛卡尔积的迭代器。
+
+#### 返回值
+
+(`IteratorObject<[...], undefined>`): 产生笛卡尔积元组的惰性迭代器,类型由源决定。它带有所有原生迭代器辅助方法(`map`、`take`、`toArray` 等),可以继续链式调用。
+
+### 与 `pipe` 搭配使用的 `cartesianProduct(other)`
+
+使用 [`pipe`](../../fp/reference/pipe.md) 组合转换时,请从 `es-toolkit/fp/iterator` 导入柯里化形式。它接收另一个迭代器,并将管道传入的迭代器的每个元素与该迭代器的每个元素配对,其中另一个迭代器推进得更快。
+
+```typescript
+import { pipe } from 'es-toolkit/fp';
+import { cartesianProduct, toArray } from 'es-toolkit/fp/iterator';
+
+pipe([1, 2].values(), cartesianProduct(['a', 'b'].values()), toArray());
+// 返回值: [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]
+```