feat(meanBy): add meanBy (#104)

* feat: add meanBy

* chore: fix typo

* Update benchmarks/meanBy.bench.ts

---------

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

benchmarks/meanBy.bench.ts

@@ -0,0 +1,15 @@
+import { bench, describe } from 'vitest';
+import { meanBy as meanByToolkit } from 'es-toolkit';
+import { meanBy as meanByLodash } from 'lodash';
+
+describe('meanBy', () => {
+  bench('es-toolkit/meanBy', () => {
+    const items = [{ a: 1 }, { a: 2 }, { a: 3 }];
+    meanByToolkit(items, x => x.a);
+  });
+
+  bench('lodash/meanBy', () => {
+    const items = [{ a: 1 }, { a: 2 }, { a: 3 }];
+    meanByLodash(items, x => x.a);
+  });
+});

docs/.vitepress/en.mts

@@ -99,6 +99,7 @@ function sidebar(): DefaultTheme.Sidebar {
           items: [
             { text: 'clamp', link: '/reference/math/clamp' },
             { text: 'mean', link: '/reference/math/mean' },
+            { text: 'meanBy', link: '/reference/math/meanBy' },
             { text: 'random', link: '/reference/math/random' },
             { text: 'randomInt', link: '/reference/math/randomInt' },
             { text: 'range', link: '/reference/math/range' },

docs/.vitepress/ko.mts

@@ -98,6 +98,7 @@ function sidebar(): DefaultTheme.Sidebar {
           items: [
             { text: 'clamp', link: '/ko/reference/math/clamp' },
             { text: 'mean', link: '/ko/reference/math/mean' },
+            { text: 'meanBy', link: '/ko/reference/math/meanBy' },
             { text: 'random', link: '/ko/reference/math/random' },
             { text: 'randomInt', link: '/ko/reference/math/randomInt' },
             { text: 'round', link: '/ko/reference/math/round' },

docs/ko/reference/math/meanBy.md

@@ -0,0 +1,27 @@
+# meanBy
+
+`getValue` 함수가 반환하는 값을 기준으로, 숫자 배열의 평균을 계산하는 함수에요.
+
+빈 배열에 대해서는 `NaN`을 반환해요.
+
+## 인터페이스
+
+```typescript
+export function meanBy<T>(items: T[], getValue: (element: T) => number): number;
+```
+
+### 파라미터
+
+- `items` (`T[]`): 평균을 계산할 숫자 배열이에요.
+- `getValue` (`(item: T) => number`): 각 요소에서 숫자 값을 선택하는 함수에요.
+
+### 반환 값
+
+(`number`): `getValue` 함수를 기준으로, 배열에 있는 모든 숫자의 평균을 반환해요.
+
+## 예시
+
+```typescript
+meanBy([{ a: 1 }, { a: 2 }, { a: 3 }], x => x.a); // 2를 반환해요.
+meanBy([], x => x.a); // NaN을 반환해요.
+```

docs/reference/math/meanBy.md

@@ -0,0 +1,27 @@
+# meanBy
+
+Calculates the average of an array of numbers when applying the `getValue` function to each element.
+
+If the array is empty, this function returns `NaN`.
+
+## Signature
+
+```typescript
+export function meanBy<T>(items: T[], getValue: (element: T) => number): number;
+```
+
+### Parameters
+
+- `items` (`T[]`): An array to calculate the average.
+- `getValue` (`(item: T) => number`): A function that selects a numeric value from each element.
+
+### Returns
+
+(`number`): The average of all the numbers as determined by the `getValue` function.
+
+## Examples
+
+```typescript
+meanBy([{ a: 1 }, { a: 2 }, { a: 3 }], x => x.a); // Returns: 2
+meanBy([], x => x.a); // Returns: NaN
+```

src/math/index.ts

@@ -1,5 +1,6 @@
 export { clamp } from './clamp.ts';
 export { mean } from './mean.ts';
+export { meanBy } from './meanBy.ts';
 export { random } from './random.ts';
 export { randomInt } from './randomInt.ts';
 export { round } from './round.ts';

src/math/mean.ts

@@ -5,7 +5,7 @@ import { sum } from './sum.ts';
  *
  * If the array is empty, this function returns `NaN`.
  *
- * @param {number[]} nums - An array of numbers to calculate the avverage.
+ * @param {number[]} nums - An array of numbers to calculate the average.
  * @returns {number} The average of all the numbers in the array.
  *
  * @example

src/math/meanBy.spec.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+import { meanBy } from './meanBy';
+
+describe('meanBy', () => {
+  it('calculates the mean of values extracted from objects', () => {
+    const result = meanBy([{ a: 1 }, { a: 2 }, { a: 3 }], x => x.a);
+
+    expect(result).toEqual(2);
+  });
+
+  it('returns NaN for empty arrays', () => {
+    type Person = { name: string; age: number };
+    const people: Person[] = [];
+
+    expect(meanBy(people, x => x.age)).toEqual(NaN);
+  });
+});

src/math/meanBy.ts

@@ -0,0 +1,22 @@
+import { mean } from './mean';
+
+/**
+ * Calculates the average of an array of numbers when applying
+ * the `getValue` function to each element.
+ *
+ * If the array is empty, this function returns `NaN`.
+ *
+ * @param {T[]} items An array to calculate the average.
+ * @param {(element: T) => number} getValue A function that selects a numeric value from each element.
+ * @returns {number} The average of all the numbers as determined by the `getValue` function.
+ *
+ * @example
+ * meanBy([{ a: 1 }, { a: 2 }, { a: 3 }], x => x.a); // Returns: 2
+ * meanBy([], x => x.a); // Returns: NaN
+ */
+
+export function meanBy<T>(items: readonly T[], getValue: (element: T) => number): number {
+  const nums = items.map(x => getValue(x));
+
+  return mean(nums);
+}