feat(forEachRight): add forEachRight (#119)

* feat(forEachRight): Add forEachRight function

* feat(forEachRight): Add forEachRight test code

* feat(forEachRight): Add forEachRight function bench

* feat(forEachRight): Add forEachRight function docs

* Update docs/ko/reference/array/forEachRight.md

* Update docs/reference/array/forEachRight.md

---------

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

benchmarks/forEachRight.bench.ts

@@ -0,0 +1,13 @@
+import { bench, describe } from 'vitest';
+import { forEachRight as forEachRightTookit } from 'es-toolkit';
+import { forEachRight as forEachRightLodash } from 'lodash';
+
+describe('forEachRight', () => {
+  bench('es-toolkit/forEachRight', () => {
+    forEachRightTookit([1, 2, 3, 4, 5, 6], x => x + 3);
+  });
+
+  bench('lodash/forEachRight', () => {
+    forEachRightLodash([1, 2, 3, 4, 5, 6], x => x + 3);
+  });
+});

docs/.vitepress/en.mts

@@ -58,6 +58,7 @@ function sidebar(): DefaultTheme.Sidebar {
             { text: 'dropRight', link: '/reference/array/dropRight' },
             { text: 'dropRightWhile', link: '/reference/array/dropRightWhile' },
             { text: 'fill', link: '/reference/array/fill' },
+            { text: 'forEachRight', link: '/reference/array/forEachRight' },
             { text: 'groupBy', link: '/reference/array/groupBy' },
             { text: 'intersection', link: '/reference/array/intersection' },
             { text: 'intersectionBy', link: '/reference/array/intersectionBy' },

docs/.vitepress/ko.mts

@@ -57,6 +57,7 @@ function sidebar(): DefaultTheme.Sidebar {
             { text: 'dropRight', link: '/ko/reference/array/dropRight' },
             { text: 'dropRightWhile', link: '/ko/reference/array/dropRightWhile' },
             { text: 'fill', link: '/ko/reference/array/fill' },
+            { text: 'forEachRight', link: '/reference/array/forEachRight' },
             { text: 'groupBy', link: '/ko/reference/array/groupBy' },
             { text: 'intersection', link: '/ko/reference/array/intersection' },
             { text: 'intersectionBy', link: '/ko/reference/array/intersectionBy' },

docs/ko/reference/array/forEachRight.md

@@ -0,0 +1,37 @@
+# forEachRight
+
+배열 (`arr`)의 요소들을 오른쪽에서 왼쪽으로 순회하며 각 요소에 대해 `callback` 함수를 호출해요.
+
+## 인터페이스
+
+```ts
+function forEachRight<T>(arr: T[], callback: (value: T, index: number, arr: T[]) => void): void;
+```
+
+### 파라미터
+
+- `arr`: (`T[]`): 순회할 배열.
+- `callback`: (`(value: T, index: number, arr: T[])`): 각 반복마다 호출될 함수예요. 
+    - `value`: 배열에서 처리 중인 현재 요소.
+    - `index`: 배열에서 처리 중인 현재 요소의 인덱스.
+    - `arr`: `forEachRight` 함수가 호출된 배열.
+
+### 반환 값
+
+`void`
+
+## 예시
+
+```ts
+import { forEachRight } from 'es-toolkit/forEachRight';
+
+const array = [1, 2, 3];
+const result: number[] = [];
+
+// forEachRight 함수를 사용하여 배열을 순회하며 각 요소를 결과 배열에 추가해요.
+forEachRight(array, (value) => {
+  result.push(value);
+});
+
+console.log(result) // Output: [3, 2, 1];
+```

docs/reference/array/forEachRight.md

@@ -0,0 +1,38 @@
+# forEachRight
+
+Iterates over elements of `arr` from right to left and invokes `callback` for each element.
+
+
+## Signature
+
+```ts
+function forEachRight<T>(arr: T[], callback: (value: T, index: number, arr: T[]) => void): void;
+```
+
+### Parameters
+
+- `arr` (`T[]`): The array to iterate over.
+- `callback` (`(value: T, index: number, arr: T[])`): The function invoked per iteration.
+    - `value`: The current element being processed in the array.
+    - `index`: The index of the current element being processed in the array.
+    - `arr`: The array `forEachRight` was called upon.
+
+### Returns
+
+`void`
+
+## Examples
+
+```ts
+import { forEachRight } from 'es-toolkit/forEachRight';
+
+const array = [1, 2, 3];
+const result: number[] = [];
+
+// Use the forEachRight function to iterate through the array and add each element to the result array.
+forEachRight(array,  (value) => {
+  result.push(value);
+});
+
+console.log(result) // Output: [3, 2, 1];
+```

src/array/forEachRight.spec.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { forEachRight } from './forEachRight';
+
+describe('forEachRight', () => {
+  it('should iterate over elements from right to left', () => {
+    const array = [1, 2, 3];
+    const result: number[] = [];
+
+    forEachRight(array, value => {
+      result.push(value);
+    });
+
+    expect(result).toEqual([3, 2, 1]);
+  });
+
+  it('should provide correct index and array for arrays', () => {
+    const array = [1, 2, 3];
+    const indices: number[] = [];
+    const arrays: number[][] = [];
+
+    forEachRight(array, (_, index, arr) => {
+      indices.push(index);
+      arrays.push(arr);
+    });
+
+    expect(indices).toEqual([2, 1, 0]);
+    expect(arrays).toEqual([array, array, array]);
+  });
+
+  it('should handle an empty array', () => {
+    const array: number[] = [];
+    const result: number[] = [];
+
+    forEachRight(array, value => {
+      result.push(value);
+    });
+
+    expect(result).toEqual([]);
+  });
+});

src/array/forEachRight.ts

@@ -0,0 +1,29 @@
+/**
+ * Iterates over elements of 'arr' from right to left and invokes 'callback' for each element.
+ * 
+ * @template T - The type of elements in the array.
+ * @param {T[]} arr - The array to iterate over.
+ * @param {(value: T, index: number, arr: T[]) => void} callback - The function invoked per iteration.
+ * The callback function receives three arguments:
+ *  - 'value': The current element being processed in the array.
+ *  - 'index': The index of the current element being processed in the array.
+ *  - 'arr': The array 'forEachRight' was called upon.
+ * 
+ * @example
+ * const array = [1, 2, 3];
+ * const result: number[] = [];
+ * 
+ * // Use the forEachRight function to iterate through the array and add each element to the result array.
+ * forEachRight(array, (value) => {
+ *  result.push(value);
+ * })
+ * 
+ * console.log(result) // Output: [3, 2, 1]
+ */
+
+export function forEachRight<T>(arr: T[], callback: (value: T, index: number, arr: T[]) => void): void {
+  for (let i = arr.length - 1; i >= 0; i--) {
+    const element = arr[i];
+    callback(element, i, arr);
+  }
+}

src/array/index.ts

@@ -9,6 +9,7 @@ export { dropRight } from './dropRight.ts';
 export { dropRightWhile } from './dropRightWhile.ts';
 export { dropWhile } from './dropWhile.ts';
 export { fill } from './fill.ts';
+export { forEachRight } from './forEachRight.ts'
 export { groupBy } from './groupBy.ts';
 export { intersection } from './intersection.ts';
 export { intersectionBy } from './intersectionBy.ts';