Repository: remeda/remeda
Pull request #827 (2024-08-12 17:37:41)

docs(randomInteger): Add warnings
I did some research on how exactly the Math.random() function works so that we can properly warn about its limitations.

Closes: #828

codesandbox-ci[bot]: This pull request is automatically built and testable in [CodeSandbox](https://codesandbox.io).

  To see build info of the built libraries, click [here](https://ci.codesandbox.io/status/remeda/remeda/pr/827/builds/531237) or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 952081728bc5bc9cd7b4f715b9c6a3495722fe27:

|Sandbox| Source |
|--|--|
|[remeda-example-vanilla](https://codesandbox.io/s/remeda-example-vanilla-x9qlhw)| Configuration |

codecov[bot]: ## [Codecov](https://app.codecov.io/gh/remeda/remeda/pull/827?dropdown=coverage&src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=remeda) Report
All modified and coverable lines are covered by tests :white_check_mark:
> Project coverage is 100.00%. Comparing base [(`8b6d8a0`)](https://app.codecov.io/gh/remeda/remeda/commit/8b6d8a03365b228eeb74476af8294a29247e7663?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=remeda) to head [(`9520817`)](https://app.codecov.io/gh/remeda/remeda/commit/952081728bc5bc9cd7b4f715b9c6a3495722fe27?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=remeda).

<details><summary>Additional details and impacted files</summary>


```diff
@@            Coverage Diff            @@
##              main      #827   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          311       311           
  Lines        10533     10533           
  Branches      2567      2567           
=========================================
  Hits         10533     10533           
```

</details>

[:umbrella: View full report in Codecov by Sentry](https://app.codecov.io/gh/remeda/remeda/pull/827?dropdown=coverage&src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=remeda).   
:loudspeaker: Have feedback on the report? [Share it here](https://about.codecov.io/codecov-pr-comment-feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=remeda).


Patch:
diff --git a/docs/src/content/mapping/lodash/random.md b/docs/src/content/mapping/lodash/random.md
index c0466da..3f5b815 100644
--- a/docs/src/content/mapping/lodash/random.md
+++ b/docs/src/content/mapping/lodash/random.md
@@ -19,7 +19,7 @@ remeda: randomInteger
 random(1, 10);
 
 // Remeda
-randomInt(1, 10);
+randomInteger(1, 10);
 ```
 
 ### Single integer param
@@ -29,7 +29,7 @@ randomInt(1, 10);
 random(10);
 
 // Remeda
-randomInt(0, 10);
+randomInteger(0, 10);
 ```
 
 ### No params
@@ -39,7 +39,7 @@ randomInt(0, 10);
 random();
 
 // Remeda
-randomInt(0, 1);
+randomInteger(0, 1);
 ```
 
 ### Not supported: floating-point numbers
diff --git a/src/randomInteger.ts b/src/randomInteger.ts
index 55f1f4d..87829b7 100644
--- a/src/randomInteger.ts
+++ b/src/randomInteger.ts
@@ -25,14 +25,21 @@ type RandomInteger<From extends number, To extends number> =
 /**
  * Generate a random integer between `from` and `to` (inclusive).
  *
+ * !Important: This function uses [`Math.random()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random) under-the-hood, which has two major limitations:
+ * 1. It generates 2^52 possible values, so the bigger the range, the less
+ * uniform the distribution of values would be, and at ranges larger than that
+ * some values would never come up.
+ * 2. It is not cryptographically secure and should not be used for security
+ * scenarios.
+ *
  * @param from - The minimum value.
  * @param to - The maximum value.
  * @returns The random integer.
  * @signature
- *   R.randomInt(from, to)
+ *   R.randomInteger(from, to)
  * @example
- *   R.randomInt(1, 10) // => 5
- *   R.randomInt(1.5, 2.6) // => 2
+ *   R.randomInteger(1, 10) // => 5
+ *   R.randomInteger(1.5, 2.6) // => 2
  * @dataFirst
  * @category Number
  */
@@ -45,7 +52,7 @@ export function randomInteger<From extends number, To extends number>(
 
   if (toFloored < fromCeiled) {
     throw new RangeError(
-      `randomInt: The range [${from},${to}] contains no integer`,
+      `randomInteger: The range [${from},${to}] contains no integer`,
     );
   }
 


Test patch:
diff --git a/src/randomInteger.test.ts b/src/randomInteger.test.ts
index 98cba33..8936587 100644
--- a/src/randomInteger.test.ts
+++ b/src/randomInteger.test.ts
@@ -4,51 +4,51 @@ const ITERATIONS = 1000;
 
 test("from is greater than to", () => {
   expect(() => randomInteger(10, 0)).toThrow(
-    new RangeError("randomInt: The range [10,0] contains no integer"),
+    new RangeError("randomInteger: The range [10,0] contains no integer"),
   );
 });
 
 test("from and to are decimals with same whole number", () => {
   expect(() => expect(randomInteger(1.5, 1.6))).toThrow(
-    new RangeError("randomInt: The range [1.5,1.6] contains no integer"),
+    new RangeError("randomInteger: The range [1.5,1.6] contains no integer"),
   );
 });
 
 test("non-negative integers", () => {
-  for (const v of randomInts(0, 10)) {
+  for (const v of randomIntegers(0, 10)) {
     expect(v).toBeGreaterThanOrEqual(0);
     expect(v).toBeLessThanOrEqual(10);
   }
 });
 
 test("negative integers", () => {
-  for (const v of randomInts(-10, -5)) {
+  for (const v of randomIntegers(-10, -5)) {
     expect(v).toBeGreaterThanOrEqual(-10);
     expect(v).toBeLessThanOrEqual(-5);
   }
 });
 
 test("positive decimals", () => {
-  for (const v of randomInts(0.1, 10.9)) {
+  for (const v of randomIntegers(0.1, 10.9)) {
     expect(v).toBeGreaterThanOrEqual(0.1);
     expect(v).toBeLessThanOrEqual(10.9);
   }
 });
 
 test("negative decimals", () => {
-  for (const v of randomInts(-10.9, -0.1)) {
+  for (const v of randomIntegers(-10.9, -0.1)) {
     expect(v).toBeGreaterThanOrEqual(-10.9);
     expect(v).toBeLessThanOrEqual(-0.1);
   }
 });
 
 test("integers with same value", () => {
-  for (const v of randomInts(10, 10)) {
+  for (const v of randomIntegers(10, 10)) {
     expect(v).toBe(10);
   }
 });
 
-function* randomInts(from: number, to: number): Generator<number> {
+function* randomIntegers(from: number, to: number): Generator<number> {
   for (let i = 0; i < ITERATIONS; i += 1) {
     yield randomInteger(from, to);
   }