feat(random): Adds a function that generates a random floating-point number between the minimum and maximum. (#53)

* feat(random): Add generating a random floating-point number between min and max

* test(random) : Add tests for random function

* feat : Add random function to math module

* test : Add benchmark for random function

* refactor : Change the words min, max to minimum, maximum

* docs(random) : Add docs about random function

* docs(random): Add docs about random function

* docs(random): Fix documentation typos

* docs(random): Fix documentation typos

* docs(random): Fix spacing

* docs(random): Fix spacing

* docs(random): Update interface heading

* docs(random): Update interface heading

* fix(random): Validate input parameters and throw error for invalid ranges

* test(random) : Update tests for new input validation logic

* docs(random) : Update documentation for new input validation logic

benchmarks/random.bench.ts

@@ -0,0 +1,13 @@
+import { bench, describe } from 'vitest';
+import { random as randomToolkit } from 'es-toolkit';
+import { random as randomLodash } from 'lodash';
+
+describe('random', () => {
+  bench('es-toolkit', () => {
+    randomToolkit(1, 10);
+  });
+
+  bench('lodash', () => {
+    randomLodash(1, 10, true);
+  });
+});

docs/ko/reference/math/random.md

@@ -0,0 +1,28 @@
+# random
+
+주어진 범위 내에서 무작위 부동 소수점 숫자를 생성하는 함수에요.
+
+이 함수는 최솟값과 최댓값을 받아서, 해당 범위 내에서 무작위 부동 소수점 숫자를 반환해요.
+
+## 인터페이스
+
+```typescript
+function random(minimum: number, maximum: number): number;
+```
+
+### 파라미터
+
+- `minimum` (`number`): 무작위 숫자를 생성할 최솟값(포함)이에요.
+- `maximum` (`number`): 무작위 숫자를 생성할 최댓값(미포함)이에요.
+
+### 반환 값
+
+- (`number`): 지정된 범위 내에서 무작위 부동 소수점 숫자를 반환해요.
+
+## 예시
+
+```typescript
+const result1 = random(0, 5); // 0과 5사이의 무작위 부동 소수점 숫자를 반환해요.
+const result2 = random(5, 0); // 최솟값이 최댓값보다 크면 오류가 발생해요.
+const result3 = random(5, 5); // 최솟값이 최댓값과 같으면 오류가 발생해요.
+```

docs/reference/math/random.md

@@ -0,0 +1,28 @@
+# random
+
+Generates a random floating-point number within a given range.
+
+This function takes a minimum and maximum value, and returns a random floating-point number within that range.
+
+## Signature
+
+```typescript
+function random(minimum: number, maximum: number): number;
+```
+
+### Parameters
+
+- `minimum` (`number`): The lower bound for the random number (inclusive).
+- `maximum` (`number`): The upper bound for the random number (exclusive).
+
+### Returns
+
+- (`number`): A random floating-point number within the specified range.
+
+## Examples
+
+```typescript
+const result1 = random(0, 5); // Returns a random floating-point number between 0 and 5.
+const result2 = random(5, 0); // If the minimum is greater than the maximum, an error is thrown
+const result3 = random(5, 5); // If the minimum is equal to the maximum, an error is thrown.
+```

src/math/index.ts

@@ -1,3 +1,4 @@
 export { clamp } from './clamp';
+export { random } from './random';
 export { round } from './round';
 export { sum } from './sum';

src/math/random.spec.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import { random } from './random';
+
+describe('random function', () => {
+  it('generates a random floating-point number between min (inclusive) and max (exclusive)', () => {
+    const min = 0;
+    const max = 5;
+    for (let i = 0; i < 100; i++) {
+      const result = random(min, max);
+      expect(result).toBeGreaterThanOrEqual(min);
+      expect(result).toBeLessThan(max);
+    }
+  });
+
+  it('throws an error if min is greater than max', () => {
+    const min = 5;
+    const max = 0;
+    expect(() => random(min, max)).toThrow('Invalid input: The maximum value must be greater than the minimum value.');
+  });
+
+  it('handles edge cases where min and max are the same', () => {
+    const min = 5;
+    const max = 5;
+    expect(() => random(min, max)).toThrow('Invalid input: The maximum value must be greater than the minimum value.');
+  });
+
+  it('works with negative ranges', () => {
+    const min = -10;
+    const max = -1;
+    for (let i = 0; i < 100; i++) {
+      const result = random(min, max);
+      expect(result).toBeGreaterThanOrEqual(min);
+      expect(result).toBeLessThan(max);
+    }
+  });
+
+  it('works with a mix of negative and positive ranges', () => {
+    const min = -5;
+    const max = 5;
+    for (let i = 0; i < 100; i++) {
+      const result = random(min, max);
+      expect(result).toBeGreaterThanOrEqual(min);
+      expect(result).toBeLessThan(max);
+    }
+  });
+});

src/math/random.ts

@@ -0,0 +1,19 @@
+/**
+ * Generates a random floating-point number between minimum (inclusive) and maximum (exclusive).
+ * If min is greater than maximum, the values are swapped.
+ *
+ * @param {number} minimum - The lower bound (inclusive).
+ * @param {number} maximum - The upper bound (exclusive).
+ * @returns {number} A random integer between minimum (inclusive) and maximum (exclusive).
+ *
+ * @example
+ * const result = random(0, 5); // result will be a random floating-point number between 0 (inclusive) and 5 (exclusive)
+ * const result2 = random(5, 0); // This will throw an error
+ */
+export function random(minimum: number, maximum: number): number {
+  if (minimum >= maximum) {
+    throw new Error('Invalid input: The maximum value must be greater than the minimum value.');
+  }
+
+  return Math.random() * (maximum - minimum) + minimum;
+}