From 503b076cebb3ca489ab09cc57753dc5816949ef1 Mon Sep 17 00:00:00 2001
From: marlonpassos <marlon.passos@cadastra.com>
Date: Sat, 23 Nov 2024 22:32:17 +0000
Subject: [PATCH] docs(shuffle): add document about optional random function

---
 docs/random/shuffle.mdx |  9 +++++++++
 src/random/shuffle.ts   | 17 +++++++++++++++++
 2 files changed, 26 insertions(+)

diff --git a/docs/random/shuffle.mdx b/docs/random/shuffle.mdx
index eb00165c..7ccd90b0 100644
--- a/docs/random/shuffle.mdx
+++ b/docs/random/shuffle.mdx
@@ -31,3 +31,12 @@ const fish = [
 
 _.shuffle(fish)
 ```
+
+You can provide a custom random function to make the shuffle more or less random. The custom random function takes minimum and maximum values and returns a random number between them.
+
+```ts
+const array = [1, 2, 3, 4, 5]
+const customRandom = (min, max) =>
+  Math.floor(Math.random() * (max - min + 1)) + min
+_.shuffle(array, customRandom)
+```
diff --git a/src/random/shuffle.ts b/src/random/shuffle.ts
index c65d206f..bf0b8ea0 100644
--- a/src/random/shuffle.ts
+++ b/src/random/shuffle.ts
@@ -17,7 +17,24 @@ import * as _ from 'radashi'
  * @version 12.1.0
  */
 export function shuffle<T>(
+  /**
+   * The array to shuffle.
+   */
   array: readonly T[],
+  /**
+   * You can provide a custom random function to make the shuffle more or less
+   * random. The custom random function takes minimum and maximum values and
+   * returns a random number between them.
+   *
+   * @default _.random
+   * @example
+   *
+   * ```ts
+   * const array = [1, 2, 3, 4, 5]
+   * const customRandom = (min, max) => Math.floor(Math.random() * (max - min + 1)) + min
+   * _.shuffle(array, customRandom)
+   * ```
+   */
   random: (min: number, max: number) => number = _.random,
 ): T[] {
   const newArray = array.slice()