Add shuffle and random utility functions to ArrayUtils

USAGE.md

@@ -7,7 +7,9 @@ Here are some of the utility functions and classes available in this library:
 
 - [ArrayUtils](#arrayutils)
   - [sample](#sample)
+  - [shuffle](#shuffle)
   - [chunk](#chunk)
+  - [random](#random)
   - [unique](#unique)
   - [range](#range)
   - [flatten](#flatten)
@@ -94,6 +96,18 @@ the following utility functions are available in the `ArrayUtils` class, they ca
 ```
 
 
+### shuffle
+```typescript
+/**
+ * Shuffles the elements of an array in place.
+ *
+ * @param arr - The array to be shuffled.
+ * @returns A new array with the elements shuffled.
+ * @template T - The type of elements in the array.
+*/
+```
+
+
 ### chunk
 ```typescript
 /**
@@ -107,6 +121,16 @@ the following utility functions are available in the `ArrayUtils` class, they ca
 ```
 
 
+### random
+```typescript
+/**
+ * Returns a random element from the given array.
+ * @param arr The array from which to select a random element.
+ * @returns A random element from the array.
+*/
+```
+
+
 ### unique
 ```typescript
 /**

package.json

@@ -1,6 +1,6 @@
 {
   "name": "typelegend",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "module": "dist/index.mjs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/array/index.ts

@@ -1,20 +1,26 @@
 
 import { sample } from "./sample";
+import { shuffle } from "./shuffle";
 import { chunk } from "./chunk";
+import { random } from "./random";
 import { unique } from "./unique";
 import { range } from "./range";
 import { flatten } from "./flatten";
 
 export class ArrayUtils {
   static sample: typeof sample = sample;
+  static shuffle: typeof shuffle = shuffle;
   static chunk: typeof chunk = chunk;
+  static random: typeof random = random;
   static unique: typeof unique = unique;
   static range: typeof range = range;
   static flatten: typeof flatten = flatten;
 }
 
 export { sample } from "./sample";
+export { shuffle } from "./shuffle";
 export { chunk } from "./chunk";
+export { random } from "./random";
 export { unique } from "./unique";
 export { range } from "./range";
 export { flatten } from "./flatten";

src/array/random.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns a random element from the given array.
+ * @param arr The array from which to select a random element.
+ * @returns A random element from the array.
+ */
+export function random<T>(arr: T[]): T {
+  return arr[Math.floor(Math.random() * arr.length)];
+}

src/array/shuffle.ts

@@ -0,0 +1,15 @@
+/**
+ * Shuffles the elements of an array in place.
+ *
+ * @param arr - The array to be shuffled.
+ * @returns A new array with the elements shuffled.
+ * @template T - The type of elements in the array.
+ */
+export function shuffle<T>(arr: T[]): T[] {
+  const result = [...arr];
+  for (let i = 0; i < result.length; i++) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [result[i], result[j]] = [result[j], result[i]];
+  }
+  return result;
+}

test/array/random.test.ts

@@ -0,0 +1,16 @@
+import { expect, describe, it } from "bun:test";
+import { random } from "../../src/array/random";
+
+describe("random", () => {
+  it("should return a random element from the array", () => {
+    const arr = [1, 2, 3, 4, 5];
+    const result = random(arr);
+    expect(arr.includes(result)).toBe(true);
+  });
+
+  it("should return undefined if the array is empty", () => {
+    const arr: number[] = [];
+    const result = random(arr);
+    expect(result).toBeUndefined();
+  });
+});

test/array/shuffle.test.ts

@@ -0,0 +1,29 @@
+import { expect, describe, it } from "bun:test";
+import { shuffle } from "../../src/array/shuffle";
+
+describe("shuffle", () => {
+  it("should shuffle the elements in the array", () => {
+    const arr = [1, 2, 3, 4, 5];
+    const result = shuffle(arr);
+    expect(result).not.toEqual(arr);
+    expect(result).toHaveLength(arr.length);
+    expect(result).toContain(1);
+    expect(result).toContain(2);
+    expect(result).toContain(3);
+    expect(result).toContain(4);
+    expect(result).toContain(5);
+  });
+
+  it("should return an empty array if the input array is empty", () => {
+    const arr: number[] = [];
+    const result = shuffle(arr);
+    expect(result).toEqual([]);
+  });
+
+  it("should not modify the original array", () => {
+    const arr = [1, 2, 3, 4, 5];
+    const originalArr = [...arr];
+    shuffle(arr);
+    expect(arr).toEqual(originalArr);
+  });
+});