feat(utils): take 유틸함수 작업 완료 (#471)

* feat(utils): take 유틸함수 작업 완료

* Update packages/utils/src/array/take/index.ts

* Update docs/docs/utils/array/take.md

* Create warm-trains-think.md

---------

Co-authored-by: Gromit (전민재) <[email protected]>

.changeset/warm-trains-think.md

@@ -0,0 +1,5 @@
+---
+"@modern-kit/utils": minor
+---
+
+feat(utils): take 유틸함수 작업 완료 - @Sangminnn

docs/docs/utils/array/take.md

@@ -0,0 +1,41 @@
+# take
+
+배열의 첫 요소부터 n개의 요소를 가져온 새로운 배열을 반환합니다.
+
+배열 외에 별도의 인자가 없는 경우 첫 번째 요소만 가져온 새로운 배열을 반환합니다.
+
+배열의 길이보다 가져오고자 하는 index값이 더 큰 경우 전체 배열을 반환합니다.
+
+가져오고자 하는 index가 음수인 경우에는 빈 배열을 반환합니다.
+
+## Code
+[🔗 실제 구현 코드 확인](https://github.com/modern-agile-team/modern-kit/blob/main/packages/utils/src/array/take/index.ts)
+
+## Benchmark
+- `hz`: 초당 작업 수
+- `mean`: 평균 응답 시간(ms)
+
+|이름|hz|mean|성능|
+|------|---|---|---|
+|modern-kit/take|6,771,043.43|0.0001|`fastest`|
+|lodash/take|2,601,105.35|0.0004|`slowest`|
+
+- **modern-kit/take**
+  - `2.60x` faster than lodash/take
+
+
+## Interface
+```ts title="typescript"
+function take<T>(arr: T[] | readonly T[], count: number = 1): T[]
+```
+
+## Usage
+```ts title="typescript"
+import { take } from '@modern-kit/utils';
+
+const arr = [1, 2, 3, 4, 5];
+console.log(take(arr)); // [1]
+console.log(take(arr, 0)); // []
+console.log(take(arr, 2);); // [1, 2]
+console.log(take(arr, 7)); // [1, 2, 3, 4, 5]
+```

packages/utils/src/array/index.ts

@@ -18,5 +18,6 @@ export * from './mapRight';
 export * from './partition';
 export * from './shuffle';
 export * from './swap';
+export * from './take';
 export * from './union';
 export * from './uniq';

packages/utils/src/array/take/index.ts

@@ -0,0 +1,29 @@
+/**
+ * @description 배열의 첫 요소부터 n개의 요소를 가져온 새로운 배열을 반환합니다.
+ *
+ * 배열 외에 별도의 인자가 없는 경우 첫 번째 요소만 가져온 새로운 배열을 반환합니다.
+ *
+ * 배열의 길이보다 가져오고자 하는 index값이 더 큰 경우 전체 배열을 반환합니다.
+ *
+ * 가져오고자 하는 index가 음수인 경우에는 빈 배열을 반환합니다.
+ *
+ * @param {T[] | readonly T[]} arr - 요소를 가져올 배열입니다.
+ * @param {number} [count=1] - 가져올 요소의 개수입니다.
+ * @returns {T[]} - 가져온 요소가 포함된 새로운 배열을 반환합니다.
+ *
+ * @example
+ * take([1, 2, 3, 4, 5]);
+ * // [1]
+ *
+ * take([1, 2, 3, 4, 5], 0)
+ * // []
+ *
+ * take([1, 2, 3, 4, 5], 2)
+ * // [1, 2]
+ *
+ * take([1, 2, 3, 4, 5], 7)
+ * // [1, 2, 3, 4, 5]
+ */
+export function take<T>(arr: T[] | readonly T[], count: number = 1): T[] {
+  return arr.slice(0, Math.max(count, 0));
+}

packages/utils/src/array/take/take.bench.ts

@@ -0,0 +1,19 @@
+import { bench, describe } from 'vitest';
+import { take as takeLodash } from 'lodash-es';
+import { take } from '.';
+
+describe('take', () => {
+  bench('modern-kit/take', () => {
+    take([1, 2, 3]);
+    take([1, 2, 3], 0);
+    take([1, 2, 3], 2);
+    take([1, 2, 3], 4);
+  });
+
+  bench('lodash/take', () => {
+    takeLodash([1, 2, 3]);
+    takeLodash([1, 2, 3], 0);
+    takeLodash([1, 2, 3], 2);
+    takeLodash([1, 2, 3], 4);
+  });
+});

packages/utils/src/array/take/take.spec.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest';
+import { take } from '.';
+
+describe('take', () => {
+  it('should return first index when count is default', () => {
+    const arr = [1, 2, 3];
+
+    expect(take(arr)).toEqual([1]);
+  });
+
+  it('should return empty array when count is 0', () => {
+    const arr = [1, 2, 3];
+
+    expect(take(arr, 0)).toEqual([]);
+  });
+
+  it('should return correct array when count is positive number', () => {
+    const arr = [1, 2, 3];
+
+    expect(take(arr, 2)).toEqual([1, 2]);
+  });
+
+  it('should return empty array when count is negative number', () => {
+    const arr = [1, 2, 3];
+
+    expect(take(arr, -2)).toEqual([]);
+  });
+
+  it('should return origin array when count is greater than the length of array', () => {
+    const arr = [1, 2, 3];
+
+    expect(take(arr, 5)).toEqual([1, 2, 3]);
+  });
+});