feat(head): add head (#131)

benchmarks/head.bench.ts

@@ -0,0 +1,13 @@
+import { bench, describe } from 'vitest';
+import { head as headToolkit } from 'es-toolkit';
+import { head as headLodash } from 'lodash';
+
+describe('head', () => {
+  bench('es-toolkit/head', () => {
+    headToolkit([1, 2, 3, 4]);
+  });
+
+  bench('lodash/head', () => {
+    headLodash([1, 2, 3, 4]);
+  });
+});

docs/.vitepress/en.mts

@@ -89,6 +89,7 @@ function sidebar(): DefaultTheme.Sidebar {
             { text: 'zip', link: '/reference/array/zip' },
             { text: 'zipObject', link: '/reference/array/zipObject' },
             { text: 'zipWith', link: '/reference/array/zipWith' },
+            { text: 'head', link: '/reference/array/head' },
           ],
         },
         {

docs/.vitepress/ko.mts

@@ -88,6 +88,7 @@ function sidebar(): DefaultTheme.Sidebar {
             { text: 'zip', link: '/ko/reference/array/zip' },
             { text: 'zipObject', link: '/ko/reference/array/zipObject' },
             { text: 'zipWith', link: '/ko/reference/array/zipWith' },
+            { text: 'head', link: '/ko/reference/array/head' },
           ],
         },
         {

docs/ko/reference/array/head.md

@@ -0,0 +1,44 @@
+# head
+
+배열의 첫 번째 요소를 반환해요.
+
+이 함수는 배열을 입력받아 배열의 첫 번째 요소를 반환해요. 배열이 비어 있는 경우, 함수는 `undefined`를 반환해요.
+
+## 인터페이스
+
+```typescript
+export function head<T>(arr: readonly [T, ...T[]]): T;
+export function head<T>(arr: readonly T[]): T | undefined;
+```
+
+### 파라미터
+
+- `arr` (`T[]`): 첫 번째 요소를 가져올 배열이에요.
+
+### 반환 값
+
+(`T | undefined`): 배열의 첫 번째 요소, 배열이 비어 있는 경우 `undefined`를 반환해요.
+
+## 예시
+
+```typescript
+const arr1 = [1, 2, 3];
+const firstElement1 = head(arr1);
+// firstElement1은 1이에요.
+
+const arr2: string[] = [];
+const firstElement2 = head(arr2);
+// firstElement2는 undefined에요.
+
+const arr3 = ['a', 'b', 'c'];
+const firstElement3 = head(arr3);
+// firstElement3는 'a'이에요.
+
+const arr4 = [true, false, true];
+const firstElement4 = head(arr4);
+// firstElement4는 true에요.
+
+const arr5: [number, string, boolean] = [1, 'a', true];
+const firstElement5 = head(arr5);
+// firstElement5는 1이에요.
+```

docs/reference/array/head.md

@@ -0,0 +1,44 @@
+# head
+
+Returns the first element of an array.
+
+This function takes an array and returns the first element of the array. If the array is empty, the function returns `undefined`.
+
+## Signature
+
+```typescript
+export function head<T>(arr: readonly [T, ...T[]]): T;
+export function head<T>(arr: readonly T[]): T | undefined;
+```
+
+### Parameters
+
+- `arr` (`T[]`): The array from which to get the first element.
+
+### Returns
+
+(`T | undefined`): The first element of the array, or `undefined` if the array is empty.
+
+## Examples
+
+```typescript
+const arr1 = [1, 2, 3];
+const firstElement1 = head(arr1);
+// firstElement1 will be 1
+
+const arr2: string[] = [];
+const firstElement2 = head(arr2);
+// firstElement2 will be undefined
+
+const arr3 = ['a', 'b', 'c'];
+const firstElement3 = head(arr3);
+// firstElement3 will be 'a'
+
+const arr4 = [true, false, true];
+const firstElement4 = head(arr4);
+// firstElement4 will be true
+
+const arr5: [number, string, boolean] = [1, 'a', true];
+const firstElement5 = head(arr5);
+// firstElement5 will be 1
+```

src/array/head.spec.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+import { head } from './head';
+
+describe('head', () => {
+  it('returns the first element of an array or undefined for empty arrays', () => {
+    expect(head([1, 2, 3])).toBe(1);
+
+    expect(head(['a', 'b', 'c'])).toBe('a');
+
+    expect(head([true, false, true])).toBe(true);
+
+    expect(head([])).toBeUndefined();
+  });
+});

src/array/head.ts

@@ -0,0 +1,23 @@
+/**
+ * Returns the first element of an array.
+ *
+ * This function takes an array and returns the first element of the array.
+ * If the array is empty, the function returns `undefined`.
+ *
+ * @param {T[]} arr - The array from which to get the first element.
+ * @returns {T | undefined} The first element of the array, or `undefined` if the array is empty.
+ *
+ * @example
+ * const arr = [1, 2, 3];
+ * const firstElement = head(arr);
+ * // firstElement will be 1
+ *
+ * const emptyArr: number[] = [];
+ * const noElement = head(emptyArr);
+ * // noElement will be undefined
+ */
+export function head<T>(arr: readonly [T, ...T[]]): T;
+export function head<T>(arr: readonly T[]): T | undefined;
+export function head<T>(arr: readonly T[]): T | undefined {
+  return arr[0];
+}

src/array/index.ts

@@ -40,3 +40,4 @@ export { zip } from './zip.ts';
 export { zipObject } from './zipObject.ts';
 export { zipWith } from './zipWith.ts';
 export { without } from './without.ts';
+export { head } from './head.ts';