feat(initial): add initial (#188)

* add initial function

* add initial test case

* add initial bench mark

* add initial docs

benchmarks/initial.bench.ts

@@ -0,0 +1,20 @@
+import { bench, describe } from 'vitest';
+import { initial as lodashInitial } from 'lodash';
+import { initial as esToolkitInitial } from 'es-toolkit'; // hypothetical library
+
+// Helper function to generate a large array
+function generateLargeArray(size) {
+  return Array.from({ length: size }, (_, index) => index);
+}
+
+describe('initial function performance', () => {
+  const largeArray = generateLargeArray(1000000); // 1 million elements
+
+  bench('es-toolkit/initial', () => {
+    esToolkitInitial(largeArray);
+  });
+
+  bench('lodash/initial', () => {
+    lodashInitial(largeArray);
+  });
+});

docs/.vitepress/en.mts

@@ -96,6 +96,7 @@ function sidebar(): DefaultTheme.Sidebar {
             { text: 'head', link: '/reference/array/head' },
             { text: 'tail', link: '/reference/array/tail' },
             { text: 'last', link: '/reference/array/last' },
+            { text: 'initial', link: '/reference/array/initial' },
           ],
         },
         {

docs/.vitepress/ko.mts

@@ -95,6 +95,7 @@ function sidebar(): DefaultTheme.Sidebar {
             { text: 'head', link: '/ko/reference/array/head' },
             { text: 'tail', link: '/ko/reference/array/tail' },
             { text: 'last', link: '/ko/reference/array/last' },
+            { text: 'initial', link: '/ko/reference/array/initial' },
           ],
         },
         {

docs/.vitepress/zh_hans.mts

@@ -2,8 +2,7 @@ import { defineConfig, type DefaultTheme } from 'vitepress';
 
 export const zh_hans = defineConfig({
   lang: 'zh_hans',
-  description:
-    '一款先进的高性能 JavaScript 实用库，具有小巧的包体积和强大的类型注解。',
+  description: '一款先进的高性能 JavaScript 实用库，具有小巧的包体积和强大的类型注解。',
 
   themeConfig: {
     nav: nav(),
@@ -95,6 +94,7 @@ function sidebar(): DefaultTheme.Sidebar {
             { text: 'head', link: '/zh_hans/reference/array/head' },
             { text: 'tail', link: '/zh_hans/reference/array/tail' },
             { text: 'last', link: '/zh_hans/reference/array/last' },
+            { text: 'initial', link: '/zh_hans/reference/array/initial' },
           ],
         },
         {

docs/ko/reference/array/initial.md

@@ -0,0 +1,49 @@
+# initial
+
+배열의 마지막 요소를 제외한 나머지 요소들로 구성된 새로운 배열을 반환해요.
+
+빈 배열이나 길이가 1인 배열의 경우, 빈 배열(`[]`)을 반환해요.
+
+## 인터페이스
+
+```typescript
+function initial<T>(arr: T[]): T[];
+```
+
+### 파라미터
+
+- `arr`(`T[]`): 마지막 요소를 제외한 나머지 요소들로 구성된 새로운 배열을 반환할 배열.
+
+### 반환 값
+
+(`T[]`): 배열의 마지막 요소를 제외한 나머지 배열. 빈 배열이나 길이가 1인 배열의 경우, 빈 배열(`[]`)을 반환해요.
+
+## 예시
+
+```typescript
+const arr1 = [1, 2, 3];
+const result = initial(arr1);
+// result는 [1, 2]에요.
+
+const arr2: number[] = [];
+const result = initial(arr2);
+// result는 []에요.
+
+const arr3: number[] = [1];
+const result = initial(arr3);
+// result는 []에요.
+
+const largeArray = Array(1000)
+  .fill(0)
+  .map((_, i) => i);
+const result = initial(largeArray);
+// result는 [0, 1, 2 ..., 998]에요.
+
+const nestedArray = [
+  [3, 1],
+  [3, 2],
+  [3, 3],
+];
+const result = initial(nestedArray);
+// result는 [[3, 1], [3, 2]]에요.
+```

docs/reference/array/initial.md

@@ -0,0 +1,49 @@
+# initial
+
+Returns a new array containing all elements except the last one from the input array.
+
+For an empty array or an array with a length of 1, it returns an empty array (`[]`).
+
+## Signature
+
+```typescript
+function initial<T>(arr: T[]): T[];
+```
+
+### Parameters
+
+- `arr` (`T[]`): The array from which to return all elements except the last one.
+
+### Returns
+
+(T[]): A new array containing all elements except the last one from the input array. For an empty array or an array with a length of 1, it returns an empty array ([]).
+
+## Examples
+
+```typescript
+const arr1 = [1, 2, 3];
+const result = initial(arr1);
+// result is [1, 2].
+
+const arr2: number[] = [];
+const result = initial(arr2);
+// result is [].
+
+const arr3: number[] = [1];
+const result = initial(arr3);
+// result is [].
+
+const largeArray = Array(1000)
+  .fill(0)
+  .map((_, i) => i);
+const result = initial(largeArray);
+// result is [0, 1, 2 ..., 998].
+
+const nestedArray = [
+  [3, 1],
+  [3, 2],
+  [3, 3],
+];
+const result = initial(nestedArray);
+// result is [[3, 1], [3, 2]].
+```

docs/zh_hans/reference/array/initial.md

@@ -0,0 +1,49 @@
+# initial
+
+返回一个新数组，包含输入数组中除最后一个元素外的所有元素。
+
+对于空数组或长度为1的数组，它返回一个空数组(`[]`)。
+
+## 签名
+
+```typescript
+function initial<T>(arr: T[]): T[];
+```
+
+### 参数
+
+- `arr` (`T[]`): 要从中返回除最后一个元素外所有元素的数组。
+
+### 返回值
+
+(`T[]`): 一个新数组，包含输入数组中除最后一个元素外的所有元素。对于空数组或长度为1的数组，它返回一个空数组(`[]`)。
+
+## 示例
+
+```typescript
+const arr1 = [1, 2, 3];
+const result = initial(arr1);
+// result 是 [1, 2]
+
+const arr2: number[] = [];
+const result = initial(arr2);
+// result 是 []
+
+const arr3: number[] = [1];
+const result = initial(arr3);
+// result 是 []
+
+const largeArray = Array(1000)
+.fill(0)
+.map((\_, i) => i);
+const result = initial(largeArray);
+// result 是 [0, 1, 2 ..., 998]
+
+const nestedArray = [
+[3, 1],
+[3, 2],
+[3, 3],
+];
+const result = initial(nestedArray);
+// result 是 [[3, 1], [3, 2]]
+```

src/array/index.ts

@@ -47,3 +47,4 @@ export { head } from './head.ts';
 export { tail } from './tail.ts';
 export { toFilled } from './toFilled.ts';
 export { last } from './last.ts';
+export { initial } from './initial.ts';

src/array/initial.spec.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { initial } from './initial';
+
+describe('initial', () => {
+  it('returns a new array containing all elements except the last one from the input array', () => {
+    expect(initial([1, 2, 3])).toEqual([1, 2]);
+    expect(initial(['a', 'b', 'c'])).toEqual(['a', 'b']);
+    expect(initial([1, true, 'string'])).toEqual([1, true]);
+    expect(initial([])).toEqual([]);
+  });
+
+  // Edge cases
+  it('returns an empty array for a single-element array', () => {
+    expect(initial(['one'])).toEqual([]);
+  });
+
+  it('returns all elements except the last one for a large array', () => {
+    const largeArray = Array(1000)
+      .fill(0)
+      .map((_, i) => i);
+    const expectedArray = Array(999)
+      .fill(0)
+      .map((_, i) => i);
+    expect(initial(largeArray)).toEqual(expectedArray);
+  });
+
+  it('returns all elements except the last one for a nested array', () => {
+    const nestedArray = [
+      [3, 1],
+      [3, 2],
+      [3, 3],
+    ];
+    expect(initial(nestedArray)).toEqual([
+      [3, 1],
+      [3, 2],
+    ]);
+  });
+});

src/array/initial.ts

@@ -0,0 +1,29 @@
+/**
+ * Returns a new array containing all elements except the last one from the input array.
+ * If the input array is empty or has only one element, the function returns an empty array.
+ *
+ * @template T The type of elements in the array.
+ * @param {T[]} arr - The input array to query.
+ * @returns {T[]} A new array containing all but the last element of the input array.
+ *
+ * @example
+ * const arr = [1, 2, 3, 4];
+ * const newArr = initial(arr);
+ * // newArr will be [1, 2, 3]
+ *
+ * @example
+ * const emptyArr: number[] = [];
+ * const newEmptyArr = initial(emptyArr);
+ * // newEmptyArr will be []
+ *
+ * @example
+ * const singleElementArr = ['only one'];
+ * const newSingleElementArr = initial(singleElementArr);
+ * // newSingleElementArr will be []
+ */
+export function initial<T>(arr: T[]): T[] {
+  if (arr.length <= 1) {
+    return [];
+  }
+  return arr.slice(0, -1);
+}