fix(range): Add docs for range, and match its behavior with python's range

docs/.vitepress/en.mts

@@ -94,6 +94,7 @@ function sidebar(): DefaultTheme.Sidebar {
             { text: 'clamp', link: '/reference/math/clamp' },
             { text: 'random', link: '/reference/math/random' },
             { text: 'randomInt', link: '/reference/math/randomInt' },
+            { text: 'range', link: '/reference/math/range' },
             { text: 'round', link: '/reference/math/round' },
             { text: 'sum', link: '/reference/math/sum' },
           ],

docs/.vitepress/ko.mts

@@ -94,6 +94,7 @@ function sidebar(): DefaultTheme.Sidebar {
             { text: 'random', link: '/ko/reference/math/random' },
             { text: 'randomInt', link: '/ko/reference/math/randomInt' },
             { text: 'round', link: '/ko/reference/math/round' },
+            { text: 'range', link: '/ko/reference/math/range' },
             { text: 'sum', link: '/ko/reference/math/sum' },
           ],
         },

docs/ko/reference/math/range.md

@@ -0,0 +1,39 @@
+# range
+
+`start`에서 시작해서 `end` 전에 끝나는 숫자의 배열을 반환해요. 연속한 숫자는 `step` 만큼 차이가 나요.
+
+`step`이 기본값은 1이고, 0일 수 없어요.
+
+## 인터페이스
+
+```typescript
+function range(end: number): number[];
+function range(start: number, end: number): number[];
+function range(start: number, end: number, step: number): number[];
+```
+
+### 파라미터
+
+- `start` (`number`): 시작할 숫자. 배열은 이 숫자를 포함해요.
+- `end` (`number`): 끝날 숫자. 배열은 이 숫자를 포함하지 않아요.
+- `step` (`number`): 배열에서 연속한 숫자의 차이. 기본값은 `1`이에요.
+
+### 반환 값
+
+- (`number[]`): `start`에서 시작해서 `end` 전에 끝나는, 연속한 숫자가 `step` 만큼 차이나는 배열.
+
+## 예시
+
+```typescript
+// Returns [0, 1, 2, 3]
+range(4);
+
+// Returns [0, 5, 10, 15]
+range(0, 20, 5);
+
+// Returns []
+range(0, -4, -1);
+
+// Throws an error: The step value must be a non-zero integer.
+range(1, 4, 0);
+```

docs/reference/math/range.md

@@ -0,0 +1,42 @@
+# range
+
+Returns an array of numbers from `start` to `end`, incrementing by `step`.
+
+If `step` is not provided, it defaults to `1`. Note that `step` must be a non-zero integer.
+
+## Signature
+
+```typescript
+function range(end: number): number[];
+function range(start: number, end: number): number[];
+function range(start: number, end: number, step: number): number[];
+```
+
+### Parameters
+
+- `start` (`number`): The starting number of the range (inclusive).
+- `end` (`number`): The end number of the range (exclusive).
+- `step` (`number`): The step value for the range. (default: `1`)
+
+### Returns
+
+- (`number[]`): An array of numbers from `start` to `end` with the specified `step`.
+
+## Examples
+
+```typescript
+// Returns [0, 1, 2, 3]
+range(4);
+
+// Returns [0, 5, 10, 15]
+range(0, 20, 5);
+
+// Returns [0, 5, 10, 15, 20]
+range(0, 21, 5);
+
+// Returns []
+range(0, -4, -1);
+
+// Throws an error: The step value must be a non-zero integer.
+range(1, 4, 0);
+```

src/array/range.spec.ts

@@ -1,28 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { range } from './range';
-
-describe('range', () => {
-  it('handles positive range with default step', () => {
-    expect(range(4)).toEqual([0, 1, 2, 3]);
-  });
-
-  it('handles negative range with default step', () => {
-    expect(range(-4)).toEqual([0, -1, -2, -3]);
-  });
-
-  it('handles custom positive step', () => {
-    expect(range(0, 20, 5)).toEqual([0, 5, 10, 15]);
-  });
-
-  it('handles custom negative step', () => {
-    expect(range(0, -4, -1)).toEqual([0, -1, -2, -3]);
-  });
-
-  it('handles zero step', () => {
-    expect(range(1, 4, 0)).toEqual([1, 1, 1]);
-  });
-
-  it('handles zero range', () => {
-    expect(range(0)).toEqual([]);
-  });
-});

src/math/index.ts

@@ -5,3 +5,4 @@ export { round } from './round';
 export { sum } from './sum';
 export { maxBy } from './maxBy';
 export { minBy } from './minBy';
+export { range } from './range';

src/math/range.spec.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { range } from './range';
+
+describe('range', () => {
+  it('returns 0, 1, 2, 3 for range 0 to 4', () => {
+    expect(range(4)).toEqual([0, 1, 2, 3]);
+    expect(range(0, 4)).toEqual([0, 1, 2, 3]);
+  });
+
+  it('returns an empty array for range 0 to -4', () => {
+    expect(range(-4)).toEqual([]);
+    expect(range(0, -4)).toEqual([]);
+  });
+
+  it('can have positive step', () => {
+    expect(range(0, 20, 5)).toEqual([0, 5, 10, 15]);
+  });
+
+  it('returns an empty array when the step is negative', () => {
+    expect(range(0, 4, -1)).toEqual([]);
+  });
+
+  it('throws an error when step is zero', () => {
+    expect(() => range(1, 4, 0)).toThrowErrorMatchingInlineSnapshot(
+      `[Error: The step value must be a non-zero integer.]`
+    );
+  });
+
+  it('returns an empty array when for range 0 to 0', () => {
+    expect(range(0)).toEqual([]);
+  });
+});

src/math/range.ts

@@ -1,8 +1,7 @@
 /**
- * Returns an array of numbers from `start` to `end` with the specified `step` value.
+ * Returns an array of numbers from `start` to `end`, incrementing by `step`.
  *
- * This function generates a range of numbers, starting from `start`, ending before `end`,
- * and incrementing by `step`. If `step` is not provided, it defaults to `1` for an
+ * If `step` is not provided, it defaults to `1` for an
  * ascending range and `-1` for a descending range.
  *
  * @param {number} start - The starting number of the range.
@@ -19,22 +18,28 @@
  * range(0, 20, 5);
  *
  * @example
- * // Returns [0, -1, -2, -3]
+ * // Returns []
  * range(0, -4, -1);
  *
  * @example
- * // Returns [1, 1, 1]
+ * // Throws an error: The step value must be a non-zero integer.
  * range(1, 4, 0);
  */
-
+export function range(end: number): number[];
+export function range(start: number, end: number): number[];
+export function range(start: number, end: number, step: number): number[];
 export function range(start: number, end?: number, step?: number): number[] {
-  if (end === undefined) {
+  if (end == null) {
     end = start;
     start = 0;
   }
 
-  if (step === undefined) {
-    step = start <= end ? 1 : -1;
+  if (step == null) {
+    step = 1;
+  }
+
+  if (!Number.isInteger(step) || step === 0) {
+    throw new Error(`The step value must be a non-zero integer.`);
   }
 
   const length = Math.max(Math.ceil((end - start) / (step || 1)), 0);