feat(utils): mapRight 유틸 함수 추가 (#342)

* feat(utils): mapRight 유틸 함수 추가

* fix: mapRight 유틸 함수 thisArg 제거 및 함수 선언문으로 변경

* fix: mapRight 유틸 함수 문서 thisArg 제거

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

---------

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

.changeset/seven-grapes-greet.md

@@ -0,0 +1,5 @@
+---
+'@modern-kit/utils': minor
+---
+
+feat(utils): mapRight 유틸 함수 추가 - @Gaic4o

docs/docs/utils/array/mapRight.md

@@ -0,0 +1,27 @@
+# mapRight 
+
+주어진 배열의 각 요소에 대해 `오른쪽에서 왼쪽으로` 순회하며 제공된 `콜백 함수`를 호출하고, 결과를 새로운 배열로 반환하는 함수입니다.
+
+<br />
+
+## Code 
+
+[🔗 실제 구현 코드 확인](https://github.com/modern-agile-team/modern-kit/blob/main/packages/utils/src/array/mapRight/index.ts)
+
+## Interface 
+
+```ts title="typescript"
+function mapRight<T, U>(
+  array: T[] | readonly T[],
+  callback: (currentValue: T, index: number, array: T[] | readonly T[]) => U,
+): U[];
+```
+
+## Usage 
+
+```ts title="typescript"
+import { mapRight } from '@modern-kit/utils';
+
+mapRight([1, 2, 3], (item, index) => item + index);
+// [5, 3, 1]
+```

packages/utils/src/array/index.ts

@@ -9,6 +9,7 @@ export * from './flattenDeepThenMap';
 export * from './forEachRight';
 export * from './intersection';
 export * from './intersectionWithDuplicates';
+export * from './mapRight';
 export * from './partition';
 export * from './shuffle';
 export * from './union';

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

@@ -0,0 +1,22 @@
+/**
+ * @description 주어진 배열의 각 요소에 대해 `오른쪽에서 왼쪽으로` 순회하며 제공된 `콜백 함수`를 호출하고, 결과를 새로운 배열로 반환하는 함수입니다.
+ *
+ * @template T - 배열 요소의 유형입니다.
+ * @template U - 반환 배열 요소의 유형입니다.
+ * @param {T[] | readonly T[]} array - 순회할 배열입니다. 변경 가능한 배열 또는 읽기 전용 배열일 수 있습니다.
+ * @param {(currentValue: T, index: number, array: T[] | readonly T[]) => U} callback - 배열의 각 요소에 대해 호출할 함수입니다.
+ * - `currentValue` - 현재 처리 중인 배열 요소입니다.
+ * - `index` - 현재 요소의 인덱스입니다.
+ * - `array` - 순회 중인 배열 자체입니다.
+ * @returns {U[]} 새로운 배열을 반환합니다. 각 요소는 `callback`의 반환 값입니다.
+ */
+export function mapRight<T, U>(
+  array: T[] | readonly T[],
+  callback: (currentValue: T, index: number, array: T[] | readonly T[]) => U
+): U[] {
+  const result: U[] = [];
+  for (let i = array.length - 1; i >= 0; i--) {
+    result.push(callback(array[i], i, array));
+  }
+  return result;
+}

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

@@ -0,0 +1,55 @@
+import { mapRight } from '.';
+
+type CallbackResult<T, U> = {
+  value: T;
+  index: number;
+  array: T[] | readonly T[];
+  result: U;
+};
+describe('mapRight', () => {
+  it('should map values from right to left in an array', () => {
+    const arr = [1, 2, 3];
+    const callbackResults: CallbackResult<number, number>[] = [];
+    const result = mapRight(arr, (value, index = 0, array = []) => {
+      callbackResults.push({ value, index, array, result: value });
+      return value;
+    });
+
+    const expectedResults = [
+      { value: 3, index: 2, array: arr, result: 3 },
+      { value: 2, index: 1, array: arr, result: 2 },
+      { value: 1, index: 0, array: arr, result: 1 },
+    ];
+    const expectedMappedArray = [3, 2, 1];
+
+    expect(callbackResults).toEqual(expectedResults);
+    expect(result).toEqual(expectedMappedArray);
+  });
+
+  it('should handle empty arrays correctly', () => {
+    const emptyArray: number[] = [];
+    const callbackResults: CallbackResult<number, number>[] = [];
+    const result = mapRight(emptyArray, (value, index = 0, array = []) => {
+      callbackResults.push({ value, index, array, result: value });
+      return value;
+    });
+
+    expect(callbackResults).toEqual([]);
+    expect(result).toEqual([]);
+  });
+
+  it('should handle arrays with one element correctly', () => {
+    const arr = [1];
+    const callbackResults: CallbackResult<number, number>[] = [];
+    const result = mapRight(arr, (value, index = 0, array = []) => {
+      callbackResults.push({ value, index, array, result: value });
+      return value;
+    });
+
+    const expectedResults = [{ value: 1, index: 0, array: arr, result: 1 }];
+    const expectedMappedArray = [1];
+
+    expect(callbackResults).toEqual(expectedResults);
+    expect(result).toEqual(expectedMappedArray);
+  });
+});