Added array shuffle extension method

Author: jamesmcroft

MADE.Collections/package-lock.json

@@ -37,9 +37,9 @@
   },
   "homepage": "https://github.com/MADE-Apps/MADE.js#readme",
   "devDependencies": {
-    "@types/jest": "^27.4.0",
-    "jest": "^27.4.7",
-    "ts-jest": "^27.1.2",
-    "typescript": "^4.5.4"
+    "@types/jest": "^27.4.1",
+    "jest": "^27.5.1",
+    "ts-jest": "^27.1.4",
+    "typescript": "^4.6.3"
   }
 }

MADE.Collections/package.json

@@ -124,7 +124,7 @@ export function potentialIndexOf<T>(array: T[], value: T, predicate: (value: T,
 }
 
 /**
- *Inserts an item to the specified array at the potential index determined by the predicate.
+ * Inserts an item to the specified array at the potential index determined by the predicate.
  * @param {T[]} array - The array of items the item should be inserted into.
  * @param {T} value - The object to insert into the array.
  * @param {(value: T, item: T) => boolean} predicate - The function to determine the position of the item based on the provided value.
@@ -137,3 +137,17 @@ export function insertAtPotentialIndex<T>(array: T[], value: T, predicate: (valu
     }
     return potentialIndex;
 }
+
+/**
+ * Creates a new array from the specified and shuffles the elements randomly.
+ * @param {T[]} array - The array of items to shuffle.
+ * @return {T[]} The new shuffled array of items.
+ */
+export function shuffle<T>(array: T[]): T[] {
+    const result = array.slice();
+    for (let i = result.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [result[i], result[j]] = [result[j], result[i]];
+    }
+    return result;
+}

MADE.Collections/src/array/index.ts

@@ -0,0 +1,29 @@
+import { shuffle } from "../../src";
+
+describe("when shuffling items", () => {
+    it("should shuffle item order randomly", () => {
+        // Arrange
+        const items = [1, 2, 3, 4, 5];
+
+        // Act
+        var shuffled = shuffle(items);
+
+        // Assert
+        expect(shuffled).not.toEqual([1, 2, 3, 4, 5]);
+    });
+
+    it("should contain same items after shuffle", () => {
+        // Arrange
+        const items = [1, 2, 3, 4, 5];
+
+        // Act
+        var shuffled = shuffle(items);
+
+        // Assert
+        expect(shuffled).toContain(1);
+        expect(shuffled).toContain(2);
+        expect(shuffled).toContain(3);
+        expect(shuffled).toContain(4);
+        expect(shuffled).toContain(5);
+    });
+});