feat(minBy): Add minBy function that select element that have min value by given condition in array (#71)

* feat(minBy): Add minBy function that return minimum of arrary

* feat(minBy): Add minBy bench test & export it

* feat(minBy): Add documents of minBy

* feat(minBy): Add unit test of minBy

* Update src/math/minBy.ts

---------

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

benchmarks/minBy.bench.ts

@@ -0,0 +1,23 @@
+import { bench, describe } from 'vitest';
+import { minBy as minByToolkit } from 'es-toolkit';
+import { minBy as minByLodash } from 'lodash';
+
+describe('minBy', () => {
+  bench('es-toolkit', () => {
+    const people = [
+      { name: 'Mark', age: 30 },
+      { name: 'Nunu', age: 20 },
+      { name: 'Overmars', age: 35 },
+    ];
+    minByToolkit(people, person => person.age);
+  });
+
+  bench('lodash', () => {
+    const people = [
+      { name: 'Mark', age: 30 },
+      { name: 'Nunu', age: 20 },
+      { name: 'Overmars', age: 35 },
+    ];
+    minByLodash(people, person => person.age);
+  });
+});

docs/ko/reference/math/minBy.md

@@ -0,0 +1,27 @@
+# maxBy
+
+주어진 배열 내의 요소들 중에서 조건에 따라 최솟값을 가지는 첫 번째 요소를 선택하는 함수에요.
+
+배열이 비어있지 않다면 조건에 따라 최솟값을 가지는 첫 번째 요소를 반환하고, 비어있다면 `undefined`를 반환해요.
+
+## 인터페이스
+
+```typescript
+function minBy<T>(elements: T[], selector: (element: T) => number): T
+```
+
+### 파라미터
+
+- `elements`: 검색할 요소들의 배열
+- `selector`: 요소를 받아서 객체의 속성을 반환하는 함수
+
+### 반환값
+
+함수의 최솟값을 가지는 배열의 첫 번째 요소. 만약 배열이 비어있다면 `undefined`를 반환해요.
+
+### 예시
+
+```typescript
+maxBy([{ a: 1 }, { a: 2 }, { a: 3 }], x => x.a) // 결과: { a: 3 }
+maxBy([], x => x.a) // 결과: undefined
+```

docs/reference/math/minBy.md

@@ -0,0 +1,27 @@
+# minBy
+
+Selects the first element of a list that has the minimum value of a function.
+
+If the list is empty, returns `undefined`.
+
+## Signature
+
+```typescript
+function minBy<T>(elements: T[], selector: (element: T) => number): T
+```
+
+### Parameters
+
+- `elements`: an array of elements to search through.
+- `selector`: a function that takes an element and returns a number that the property of the object.
+
+### Returns
+
+The first element of the list that has the minimum value of the function. If the list is empty, returns `undefined`.
+
+### Example
+
+```typescript
+minBy([{ a: 1 }, { a: 2 }, { a: 3 }], x => x.a) // Returns: { a: 1 }
+minBy([], x => x.a) // Returns: undefined
+```

src/math/index.ts

@@ -4,3 +4,4 @@ export { randomInt } from './randomInt';
 export { round } from './round';
 export { sum } from './sum';
 export { maxBy } from './maxBy';
+export { minBy } from './minBy';

src/math/minBy.spec.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { minBy } from './minBy';
+
+describe('minBy', () => {
+    it('minBy selects one max value in array', () => {
+        const people = [
+            { name: 'Mark', age: 30 },
+            { name: 'Nunu', age: 20 },
+            { name: 'Overmars', age: 35 },
+        ];
+        const result = minBy(people, person => person.age);
+        expect(result).toEqual({ name: 'Nunu', age: 20 });
+    });
+
+    it('if there are two max values, first one is selected', () => {
+        const people = [
+            { name: 'Mark', age: 30 },
+            { name: 'Nunu', age: 20 },
+            { name: 'Overmars', age: 20 },
+        ];
+        const result = minBy(people, person => person.age);
+        expect(result).toEqual({ name: 'Nunu', age: 20 });
+    });
+
+    it('if array is single-element, return unique element of array', () => {
+        const people = [
+            { name: 'Mark', age: 25 },
+        ];
+        const result = minBy(people, person => person.age);
+        expect(result).toEqual({ name: 'Mark', age: 25 });
+    });
+
+    it('if array is empty, return undefined', () => {
+        type Person = { name: string, age: number };
+        const people: Person[] = [];
+        const result = minBy(people, person => person.age);
+        expect(result).toBeUndefined();
+    });
+});

src/math/minBy.ts

@@ -0,0 +1,25 @@
+/**
+ * Returns the minimum value in an array of numbers.
+ *
+ * This function takes an array of elements and a selector function, and returns the element with the minimum value according to the selector.
+ *
+ * If the array is empty, the function returns `undefined`.
+ *
+ * @param elements An array of elements.
+ * @param selector A function that selects a number from an element.
+ */
+export function minBy<T>(elements: T[], selector: (element: T) => number): T {
+
+  let minElement = elements[0];
+  let min = Infinity;
+
+  for (const element of elements) {
+    const value = selector(element);
+    if (value < min) {
+      min = value;
+      minElement = element;
+    }
+  }
+
+  return minElement;
+}