feat(at): at should support negative indices

benchmarks/performance/at.bench.ts

@@ -0,0 +1,13 @@
+import { bench, describe } from 'vitest';
+import { at as atToolkit } from 'es-toolkit';
+import { at as atLodash } from 'lodash';
+
+describe('at', () => {
+  bench('es-toolkit/at', () => {
+    atToolkit(['a', 'b', 'c', 'd', 'e'], [0, 2, 4]);
+  });
+
+  bench('lodash/at', () => {
+    atLodash(['a', 'b', 'c', 'd', 'e'], [0, 2, 4]);
+  });
+});

docs/ja/reference/array/at.md

@@ -2,6 +2,8 @@
 
 指定したインデックスの位置から配列の要素を取得します。
 
+この関数は負のインデックスをサポートしており、配列の末尾からカウントします。
+
 ## インターフェース
 
 ```typescript
@@ -15,7 +17,7 @@ function at<T>(arr: T[], indices: number[]): T[];
 
 ### 戻り値
 
-(`T[]`): 指定されたインデックスの位置にある要素を含む新しい配列。
+(`Array<T | undefined>`): 指定されたインデックスの位置にある要素を含む新しい配列。
 
 ## 例
 

docs/ko/reference/array/at.md

@@ -2,6 +2,8 @@
 
 배열에서 주어진 인덱스에 있는 요소들을 선택해서, 새 배열을 반환해요.
 
+이 함수는 음수 인덱스를 지원해요. 인덱스가 음수일 경우, 배열의 마지막부터 계산해요.
+
 ## 인터페이스
 
 ```typescript
@@ -15,7 +17,7 @@ function at<T>(arr: T[], indices: number[]): T[];
 
 ### 반환 값
 
-(`T[]`): 주어진 인덱스에 있는 요소들을 가지는 새 배열.
+(`Array<T | undefined>`): 주어진 인덱스에 있는 요소들을 가지는 새 배열.
 
 ## 예시
 

docs/reference/array/at.md

@@ -2,6 +2,8 @@
 
 Retrieves elements from an array at the specified indices.
 
+This function supports negative indices, which count from the end of the array.
+
 ## Signature
 
 ```typescript
@@ -15,7 +17,7 @@ function at<T>(arr: T[], indices: number[]): T[];
 
 ### Returns
 
-(`T[]`): A new array containing the elements at the specified indices.
+(`Array<T | undefined>`): A new array containing the elements at the specified indices.
 
 ## Examples
 

docs/zh_hans/reference/array/at.md

@@ -2,6 +2,8 @@
 
 从数组中检索指定索引处的元素。
 
+这个函数支持负索引，负索引从数组的末尾开始计算。
+
 ## 签名
 
 ```typescript
@@ -15,7 +17,7 @@ function at<T>(arr: T[], indices: number[]): T[];
 
 ### 返回值
 
-(`T[]`): 一个新数组，包含在指定索引处的元素。
+(`Array<T | undefined>`): 一个新数组，包含在指定索引处的元素。
 
 ## 示例
 

src/array/at.ts

@@ -1,23 +1,25 @@
 /**
  * Retrieves elements from an array at the specified indices.
  *
+ * This function supports negative indices, which count from the end of the array.
+ *
  * @template T
  * @param {readonly T[]} arr - The array to retrieve elements from.
  * @param {number[]} indices - An array of indices specifying the positions of elements to retrieve.
- * @returns {T[]} A new array containing the elements at the specified indices.
+ * @returns {Array<T | undefined>} A new array containing the elements at the specified indices.
  *
  * @example
  * const numbers = [10, 20, 30, 40, 50];
  * const result = at(numbers, [1, 3, 4]);
  * console.log(result); // [20, 40, 50]
  */
-export function at<T>(arr: readonly T[], indices: number[]) {
-  const result: T[] = [];
+export function at<T>(arr: readonly T[], indices: number[]): Array<T | undefined> {
+  const result: Array<T | undefined> = [];
 
   for (let i = 0; i < indices.length; i++) {
     const index = indices[i];
 
-    result.push(arr[index]);
+    result.push(arr.at(index));
   }
 
   return result;

src/array/index.ts

@@ -1,3 +1,4 @@
+export { at } from './at.ts';
 export { chunk } from './chunk.ts';
 export { compact } from './compact.ts';
 export { countBy } from './countBy.ts';