feat(fill): Improve fill to support negative indices (#222)

* feat: add imporve fill function

* feat: add test for fill

* feat: improved testing for toFilled

* feat: add docs for fill

* fix: toFilled Typo fix

* fix: type interface and docs

* fix: fill type docs

---------

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

docs/ko/reference/array/fill.md

@@ -5,24 +5,26 @@
 이 함수는 원본 배열을 변경하고, 제공된 값으로 시작 인덱스부터 끝 인덱스까지의 요소를 대체해요.
 시작 또는 끝 인덱스를 제공하지 않으면 배열 전체를 채워요.
 
+음수 인덱스를 사용할 수도 있어요. 이 경우 배열의 끝에서부터 인덱스를 계산해요.
+
 ## 인터페이스
 
 ```typescript
 function fill<T>(array: unknown[], value: T): T[];
-function fill<T, P>(array: T[], value: P, start: number): Array<T | P>;
-function fill<T, P>(array: T[], value: P, start: number, end: number): Array<T | P>;
+function fill<T, U>(array: T[], value: T, start: number): Array<T | U>;
+function fill<T, U>(array: T[], value: T, start: number, end: number): Array<T | U>;
 ```
 
 ### 파라미터
 
-- `array` (`Array<T | P>`): 채울 배열이에요.
-- `value` (`P`): 배열을 채울 값이에요.
+- `array` (`Array<T | U>`): 채울 배열이에요.
+- `value` (`U`): 배열을 채울 값이에요.
 - `start` (`number`, 기본값 = 0): 시작 위치에요. 기본값은 0이에요.
 - `end` (`number`, 기본값 = array.length): 끝 위치에요. 기본값은 배열의 길이에요.
 
 ### 반환 값
 
-(`Array<T | P>`): 채워진 값이 있는 배열을 반환해요.
+(`Array<T | U>`): 채워진 값이 있는 배열을 반환해요.
 
 ## 예시
 
@@ -38,4 +40,8 @@ const result2 = fill(array2, 2);
 const array3 = [4, 6, 8, 10];
 const result3 = fill(array3, '*', 1, 3);
 // result3는 [4, '*', '*', 10]가 돼요.
+
+const array4 = [1, 2, 3];
+const result4 = fill(array4, '*', -2, -1);
+// result4는 [1, '*', 3]가 돼요.
 ```

docs/ko/reference/array/toFilled.md

@@ -14,7 +14,7 @@ function toFilled<T, U>(arr: T[], value: U, start: number, end: number): Array<T
 
 ### 파라미터
 
-- `arr` (`Array<T>`): 채울 배얼이에요.
+- `arr` (`Array<T>`): 채울 배열이에요.
 - `value` (`U`): 배열을 채울 값이에요.
 - `start` (`number, 기본값 = 0`): 시작 위치예요. 기본값은 0이에요.
 - `end` (`number, 기본값 = array.length`): 끝 위치예요. 기본값은 배열의 길이예요.

docs/reference/array/fill.md

@@ -4,24 +4,26 @@ Fills elements of an array with a specified value from the start position up to,
 
 This function mutates the original array and replaces its elements with the provided value, starting from the specified start index up to the end index (non-inclusive). If the start or end indices are not provided, it defaults to filling the entire array.
 
+Negative indices can also be used, in which case they are calculated from the end of the array.
+
 ## Signature
 
 ```typescript
 function fill<T>(array: unknown[], value: T): T[];
-function fill<T, P>(array: T[], value: P, start: number): Array<T | P>;
-function fill<T, P>(array: T[], value: P, start: number, end: number): Array<T | P>;
+function fill<T, U>(array: T[], value: T, start: number): Array<T | U>;
+function fill<T, U>(array: T[], value: T, start: number, end: number): Array<T | U>;
 ```
 
 ### Parameters
 
-- `array` (`Array<T | P>`): The array to fill.
-- `value` (`P`): The value to fill the array with.
+- `array` (`Array<T | U>`): The array to fill.
+- `value` (`U`): The value to fill the array with.
 - `start` (`number`, default = 0): The start position. Defaults to 0.
 - `end` (`number`, default = array.length): The end position. Defaults to the array's length.
 
 ### Returns
 
-(`Array<T | P>`): The array with the filled values.
+(`Array<T | U>`): The array with the filled values.
 
 ## Examples
 
@@ -37,4 +39,8 @@ const result2 = fill(array2, 2);
 const array3 = [4, 6, 8, 10];
 const result3 = fill(array3, '*', 1, 3);
 // result3 => [4, '*', '*', 10]
+
+const array4 = [1, 2, 3];
+const result4 = fill(array4, '*', -2, -1);
+// result4 => [1, '*', 3]
 ```

src/array/fill.spec.ts

@@ -14,4 +14,29 @@ describe('fill', () => {
   it('fills part of an array from the start index to the end index', () => {
     expect(fill([4, 6, 8, 10], '*', 1, 3)).toEqual([4, '*', '*', 10]);
   });
+
+  it('fills middle values', () => {
+    const result = fill([1, 2, 3, 4, 5], '*', 1, 4);
+    expect(result).toEqual([1, '*', '*', '*', 5]);
+  });
+
+  it('fills from specified start position', () => {
+    const result = fill([1, 2, 3, 4, 5], '*', 2);
+    expect(result).toEqual([1, 2, '*', '*', '*']);
+  });
+
+  it('fills with negative start position', () => {
+    const result = fill([1, 2, 3, 4, 5], '*', -3);
+    expect(result).toEqual([1, 2, '*', '*', '*']);
+  });
+
+  it('fills with positive start and negative end positions', () => {
+    const result = fill([1, 2, 3, 4, 5], '*', 1, -1);
+    expect(result).toEqual([1, '*', '*', '*', 5]);
+  });
+
+  it('fills with both negative start and end positions', () => {
+    const result = fill([1, 2, 3, 4, 5], '*', -4, -1);
+    expect(result).toEqual([1, '*', '*', '*', 5]);
+  });
 });

src/array/fill.ts

@@ -5,11 +5,11 @@
  * start index up to the end index (non-inclusive). If the start or end indices are not provided, it defaults to filling the
  * entire array.
  *
- * @param {Array<T | P>} arr - The array to fill.
- * @param {P} value - The value to fill the array with.
+ * @param {Array<T | U>} array - The array to fill.
+ * @param {U} value - The value to fill the array with.
  * @param {number} [start=0] - The start position. Defaults to 0.
  * @param {number} [end=arr.length] - The end position. Defaults to the array's length.
- * @returns {Array<T | P>} The array with the filled values.
+ * @returns {Array<T | U>} The array with the filled values.
  *
  * @example
  * const array = [1, 2, 3];
@@ -21,18 +21,21 @@
  *
  * const result = fill([4, 6, 8, 10], '*', 1, 3);
  * // => [4, '*', '*', 10]
+ *
+ * const result = fill(array, '*', -2, -1);
+ * // => [1, '*', 3]
  */
+export function fill<T>(array: unknown[], value: T): T[];
+export function fill<T, U>(array: Array<T | U>, value: U, start: number): Array<T | U>;
+export function fill<T, U>(array: Array<T | U>, value: U, start: number, end: number): Array<T | U>;
+export function fill<T, U>(array: Array<T | U>, value: U, start = 0, end = array.length): Array<T | U> {
+  const length = array.length;
+  const finalStart = Math.max(start >= 0 ? start : length + start, 0);
+  const finalEnd = Math.min(end >= 0 ? end : length + end, length);
 
-export function fill<T>(arr: unknown[], value: T): T[];
-export function fill<T, P>(arr: Array<T | P>, value: P, start: number): Array<T | P>;
-export function fill<T, P>(arr: Array<T | P>, value: P, start: number, end: number): Array<T | P>;
-export function fill<T, P>(arr: Array<T | P>, value: P, start = 0, end = arr.length): Array<T | P> {
-  start = Math.max(start, 0);
-  end = Math.min(end, arr.length);
-
-  for (let i = start; i < end; i++) {
-    arr[i] = value;
+  for (let i = finalStart; i < finalEnd; i++) {
+    array[i] = value;
   }
 
-  return arr;
+  return array;
 }

src/array/toFilled.spec.ts

@@ -1,38 +1,38 @@
-import { describe, expect, test } from 'vitest';
+import { describe, expect, it } from 'vitest';
 import { toFilled } from './toFilled';
 
-describe('toFilled function tests', () => {
-  test('handles empty array', () => {
+describe('toFilled', () => {
+  it('fills empty array', () => {
     const result = toFilled([], '*');
     expect(result).toEqual([]);
   });
 
-  test('fills middle values', () => {
+  it('fills middle values', () => {
     const result = toFilled([1, 2, 3, 4, 5], '*', 1, 4);
     expect(result).toEqual([1, '*', '*', '*', 5]);
   });
 
-  test('fills entire array', () => {
+  it('fills entire array', () => {
     const result = toFilled([1, 2, 3, 4, 5], '*');
     expect(result).toEqual(['*', '*', '*', '*', '*']);
   });
 
-  test('fills from specified start position', () => {
+  it('fills from specified start position', () => {
     const result = toFilled([1, 2, 3, 4, 5], '*', 2);
     expect(result).toEqual([1, 2, '*', '*', '*']);
   });
 
-  test('handles negative start position', () => {
+  it('fills with negative start position', () => {
     const result = toFilled([1, 2, 3, 4, 5], '*', -3);
     expect(result).toEqual([1, 2, '*', '*', '*']);
   });
 
-  test('handles positive start and negative end positions', () => {
+  it('fills with positive start and negative end positions', () => {
     const result = toFilled([1, 2, 3, 4, 5], '*', 1, -1);
     expect(result).toEqual([1, '*', '*', '*', 5]);
   });
 
-  test('handles both negative start and end positions', () => {
+  it('fills with both negative start and end positions', () => {
     const result = toFilled([1, 2, 3, 4, 5], '*', -4, -1);
     expect(result).toEqual([1, '*', '*', '*', 5]);
   });