feat(unzipWith): add unzipWith (#113)

* feat(array): add unzipWith

* docs(array): add unzipWith reference

* perf: refactoring unzipWith bench

* docs(array): add vitepress

* Apply suggestions from code review

* Update unzipWith.ts

* Update src/array/unzipWith.ts

* Update benchmarks/unzipWith.bench.ts

* Update benchmarks/unzipWith.bench.ts

* Update src/array/unzipWith.spec.ts

* Update src/array/unzipWith.spec.ts

---------

Co-authored-by: Sojin Park <raon0211@gmail.com>
Co-authored-by: Sojin Park <raon0211@toss.im>

benchmarks/unzipWith.bench.ts

@@ -0,0 +1,27 @@
+import { unzipWith as unzipWithToolkit } from 'es-toolkit';
+import { unzipWith as unzipWithLodash } from 'lodash';
+import { bench, describe } from 'vitest';
+
+describe('unzipWith', () => {
+  bench('es-toolkit/unzipWith', () => {
+    unzipWithToolkit(
+      [
+        [1000, 2000],
+        [3000, 4000],
+        [50000, 60000],
+      ],
+      (a, b, c) => a + b + c
+    );
+  });
+
+  bench('lodash/unzipWith', () => {
+    unzipWithLodash(
+      [
+        [1000, 2000],
+        [3000, 4000],
+        [50000, 60000],
+      ],
+      (a, b, c) => a + b + c
+    );
+  });
+});

docs/.vitepress/en.mts

@@ -79,6 +79,7 @@ function sidebar(): DefaultTheme.Sidebar {
             { text: 'uniq', link: '/reference/array/uniq' },
             { text: 'uniqBy', link: '/reference/array/uniqBy' },
             { text: 'uniqWith', link: '/reference/array/uniqWith' },
+            { text: 'unzipWith', link: '/reference/array/unzipWith' },
             { text: 'without', link: '/reference/array/without' },
             { text: 'xor', link: '/reference/array/xor' },
             { text: 'xorBy', link: '/reference/array/xorBy' },

docs/.vitepress/ko.mts

@@ -75,6 +75,7 @@ function sidebar(): DefaultTheme.Sidebar {
             { text: 'union', link: '/ko/reference/array/union' },
             { text: 'unionBy', link: '/ko/reference/array/unionBy' },
             { text: 'unionWith', link: '/ko/reference/array/unionWith' },
+            { text: 'unzipWith', link: '/reference/array/unzipWith' },
             { text: 'uniq', link: '/ko/reference/array/uniq' },
             { text: 'uniqBy', link: '/ko/reference/array/uniqBy' },
             { text: 'uniqWith', link: '/ko/reference/array/uniqWith' },

docs/ko/reference/array/unzipWith.md

@@ -0,0 +1,30 @@
+# unzipWith
+
+결합되어 있는 2차원 배열을 1차원 배열로 풀고, `iteratee` 함수로 값을 변환해서 새로운 배열을 반환해요.
+
+## 인터페이스
+
+```typescript
+function unzipWith<T, R>(target: readonly T[][], iteratee: (...args: T[]) => R): R[];
+```
+
+### 파라미터
+
+- `target` (`T[][]`): 결합을 풀고 변환할 배열이에요.
+- `iteratee` (`(...args: T[]) => R`): 결합이 풀린 배열을 변환할 함수예요.
+
+### 반환 값
+
+(`R[]`): 결합을 풀고 변환된 값들로 만들어진 새로운 배열이에요.
+
+## 예시
+
+```typescript
+const nestedArray = [
+  [1, 2],
+  [3, 4],
+  [5, 6],
+];
+const result = unzipWith(nestedArray, (item, item2, item3) => item + item2 + item3);
+// [9, 12]
+```

docs/reference/array/unzipWith.md

@@ -0,0 +1,30 @@
+# unzipWith
+
+Unzips an array of arrays, applying an `iteratee` function to regrouped elements.
+
+## Signature
+
+```typescript
+function unzipWith<T, R>(target: T[][], iteratee: (...args: T[]) => R): R[];
+```
+
+### Parameters
+
+- `target`(`T[][]`): The nested array to unzip. This is an array of arrays, where each inner array contains elements to be unzipped.
+- `iteratee` (`(...args: T[]) => R`): A function to transform the unzipped elements.
+
+### Returns
+
+(`R[]`): A new array of unzipped and transformed elements. 
+
+## Examples
+
+```typescript
+const nestedArray = [
+  [1, 2],
+  [3, 4],
+  [5, 6],
+];
+const result = unzipWith(nestedArray, (item, item2, item3) => item + item2 + item3);
+// [9, 12]
+```

src/array/index.ts

@@ -8,6 +8,7 @@ export { drop } from './drop.ts';
 export { dropRight } from './dropRight.ts';
 export { dropRightWhile } from './dropRightWhile.ts';
 export { dropWhile } from './dropWhile.ts';
+export { fill } from './fill.ts';
 export { groupBy } from './groupBy.ts';
 export { intersection } from './intersection.ts';
 export { intersectionBy } from './intersectionBy.ts';
@@ -29,11 +30,11 @@ export { unionWith } from './unionWith.ts';
 export { uniq } from './uniq.ts';
 export { uniqBy } from './uniqBy.ts';
 export { uniqWith } from './uniqWith.ts';
-export { without } from './without.ts';
+export { unzipWith } from './unzipWith.ts';
 export { xor } from './xor.ts';
 export { xorBy } from './xorBy.ts';
 export { xorWith } from './xorWith.ts';
 export { zip } from './zip.ts';
-export { zipWith } from './zipWith.ts';
 export { zipObject } from './zipObject.ts';
-export { fill } from './fill.ts';
+export { zipWith } from './zipWith.ts';
+export { without } from './without.ts';

src/array/unzipWith.spec.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { unzipWith } from './unzipWith';
+import { zip } from './zip';
+
+describe('unzipWith', () => {
+  it('should unzip arrays correctly with an iteratee', () => {
+    const zipped = zip([10, 20, 30], [40, 50, 60], [70, 80, 90]);
+    const result = unzipWith(zipped, (item, item2, item3) => item + item2 + item3);
+
+    expect(result).toEqual([60, 150, 240]);
+  });
+
+  it('should handle arrays of different lengths', () => {
+    const zipped = zip([1, 20, 300, 4000], [100, 200, 300]);
+    const result = unzipWith(zipped, (item, item2, item3, item4) => item + item2 + item3 + item4);
+
+    expect(result).toEqual([4321, NaN]);
+  });
+});

src/array/unzipWith.ts

@@ -0,0 +1,30 @@
+/**
+ * Unzips an array of arrays, applying an `iteratee` function to regrouped elements.
+ *
+ * @template T, R
+ * @param {T[][]} target - The nested array to unzip. This is an array of arrays,
+ * where each inner array contains elements to be unzipped.
+ * @param {(...args: T[]) => R} iteratee - A function to transform the unzipped elements.
+ * @returns {R[]} A new array of unzipped and transformed elements. 
+ *
+ * @example
+ * const nestedArray = [[1, 2], [3, 4], [5, 6]];
+ * const result = unzipWith(nestedArray, (item, item2, item3) => item + item2 + item3);
+ * // result will be [9, 12]
+ */
+export function unzipWith<T, R>(target: readonly T[][], iteratee: (...args: T[]) => R): R[] {
+  const maxLength = Math.max(...target.map(innerArray => innerArray.length));
+  const result: R[] = new Array(maxLength);
+
+  for (let i = 0; i < maxLength; i++) {
+    const group = new Array(target.length);
+
+    for (let j = 0; j < target.length; j++) {
+      group[j] = target[j][i];
+    }
+
+    result[i] = iteratee(...group);
+  }
+
+  return result;
+}