feat: adding a shuffle function to randomly sort arrays

Author: chrisprobably

README.md

@@ -26,6 +26,7 @@ yarn add randm
 - `randm.int.between(2, 10)` - returns a random integer between 2 and 10
 - `randm.oneIn(10)` - one in 10 chance that this returns true, otherwise it returns false
 - `randm.from(['foo', 'bar', 'qux'])` - returns a random value from an array, in this case 'foo', 'bar' or 'qux'
+- `randm.shuffle([1, 2, 3, 4])` - returns a randomly sorted copy of the passed array e.g. [3, 2, 4, 1]. (Immutable - the passed array will not be changed)
 - `randm.happens(2).outOf(5)` - returns true 2 out of 5 times
 - `randm.percentageChance(95)` - returns true 95% of the time
 - `randm.coinFlip()` - returns `heads` or `tails`

randm.d.ts

@@ -38,74 +38,34 @@ declare module "randm" {
     happens(times: number): { outOf(total: number): boolean };
     percentageChance(percentage: number): boolean;
     customDiceRoll(die: string): number;
-    int: {
-      between(x: number, y: number): number;
-    };
-    date: {
-      between(x: Date, y: Date): Date;
-    };
+    int: { between(x: number, y: number): number };
+    date: { between(x: Date, y: Date): Date };
     bag(contents?: any[]): Bag;
+    shuffle<T>(arry: T[]): T[];
     next: {
-      int: {
-        between: {
-          returns(...vals: number[]): void;
-        };
-      };
-      any: {
-        returns(...vals: number[]): void;
-      };
-      bool: {
-        returns(...vals: boolean[]): void;
-      };
-      coinFlip: {
-        returns(...vals: ("heads" | "tails")[]): void;
-      };
-      dateTime: {
-        returns(...vals: Date[]): void;
-      };
-      diceRoll: {
-        returns(...vals: number[]): void;
-      };
-      diceRollBeats: {
-        returns(...vals: boolean[]): void;
-      };
-      diceRollOf: {
-        returns(...vals: DiceRollDetails[]): void;
-      };
-      artilleryDie: {
-        returns(...vals: (number | "MISS")[]): void;
-      };
+      int: { between: { returns(...vals: number[]): void } };
+      any: { returns(...vals: number[]): void };
+      bool: { returns(...vals: boolean[]): void };
+      coinFlip: { returns(...vals: ("heads" | "tails")[]): void };
+      dateTime: { returns(...vals: Date[]): void };
+      diceRoll: { returns(...vals: number[]): void };
+      diceRollBeats: { returns(...vals: boolean[]): void };
+      diceRollOf: { returns(...vals: DiceRollDetails[]): void };
+      artilleryDie: { returns(...vals: (number | "MISS")[]): void };
       scatterDie: {
         returns(...vals: { direction: number; isHit: boolean }[]): void;
       };
-      between: {
-        returns(...vals: number[]): void;
-      };
-      oneIn: {
-        returns(...vals: boolean[]): void;
-      };
-      from: {
-        returns<T>(...vals: T[]): void;
-      };
-      happens: {
-        returns(...vals: boolean[]): void;
-      };
-      percentageChance: {
-        returns(...vals: boolean[]): void;
-      };
-      customDiceRoll: {
-        returns(...vals: number[]): void;
-      };
+      between: { returns(...vals: number[]): void };
+      oneIn: { returns(...vals: boolean[]): void };
+      from: { returns<T>(...vals: T[]): void };
+      shuffle: { returns<T>(...vals: T[]): void };
+      happens: { returns(...vals: boolean[]): void };
+      percentageChance: { returns(...vals: boolean[]): void };
+      customDiceRoll: { returns(...vals: number[]): void };
       bag: {
-        pick: {
-          returns(...vals: any[]): void;
-        };
-        contents: {
-          returns(...vals: ReadonlyArray<any>[]): void;
-        };
-        isEmpty: {
-          returns(...vals: boolean[]): void;
-        };
+        pick: { returns(...vals: any[]): void };
+        contents: { returns(...vals: ReadonlyArray<any>[]): void };
+        isEmpty: { returns(...vals: boolean[]): void };
       };
       reset(): void;
     };

randm.js

@@ -80,11 +80,22 @@ const randm = {
     randm.happens(Math.abs(percentage)).outOf(100),
   customDiceRoll: (die) => randm.diceRollOf(die).rolls().total,
   bag: (contents) => new Bag(contents),
+  shuffle: (arry) => {
+    let cpy;
+    try {
+      cpy = [...arry];
+    } catch (e) {
+      return arry;
+    }
+    for (let i = cpy.length - 1; i > 0; i--) {
+      const j = randm.int.between(0, i);
+      [cpy[i], cpy[j]] = [cpy[j], cpy[i]];
+    }
+    return cpy;
+  },
 };
 
-randm.int = {
-  between: (x, y) => Math.round(randm.any() * (y - x)) + x,
-};
+randm.int = { between: (x, y) => Math.round(randm.any() * (y - x)) + x };
 
 randm.date = {
   between: (x, y) => new Date(randm.int.between(x.getTime(), y.getTime())),

test/shuffle.test.js

@@ -0,0 +1,89 @@
+var randm = require("../randm");
+var t = require("tap");
+
+t.beforeEach(() => {
+  randm.next.reset();
+});
+
+t.test("randm.shuffle randomly re-orders an array of numbers", function (t) {
+  const orig = [1, 2, 3, 4];
+  const shuffled = randm.shuffle(orig);
+  console.log("randm.shuffle([1, 2, 3, 4])", shuffled);
+  t.notSame(orig, shuffled);
+  t.end();
+});
+
+t.test("randm.shuffle randomly re-orders an array of strings", function (t) {
+  const orig = ["a", "b", "c", "d"];
+  const shuffled = randm.shuffle(orig);
+  console.log('randm.shuffle(["a", "b", "c", "d"])', shuffled);
+  t.notSame(orig, shuffled);
+  t.end();
+});
+
+t.test("randm.shuffle randomly re-orders an array of objects", function (t) {
+  const orig = [
+    { a: 1, b: "so" },
+    { a: 2, b: "huh" },
+    { a: 3, b: "wo" },
+  ];
+  const shuffled = randm.shuffle(orig);
+  console.log(
+    'randm.shuffle([{ a: 1, b: "so" }, { a: 2, b: "huh" }, { a: 3, b: "wo" }])',
+    shuffled
+  );
+  t.notSame(orig, shuffled);
+  t.end();
+});
+
+t.test("randm.shuffle randomly re-orders a string", function (t) {
+  const orig = "Hello";
+  const shuffled = randm.shuffle(orig);
+  console.log("randm.shuffle('Hello')", shuffled);
+  t.notSame(orig, shuffled);
+  t.end();
+});
+
+t.test(
+  "randm.shuffle returns the original number argument when not passed an iterable",
+  function (t) {
+    const orig = 1234;
+    const shuffled = randm.shuffle(orig);
+    console.log("randm.shuffle(1234)", shuffled);
+    t.same(orig, shuffled);
+    t.equal(shuffled, 1234);
+    t.end();
+  }
+);
+
+t.test("randm.shuffle does not mutate the passed array", function (t) {
+  const orig = [1, 2, 3, 4];
+  const shuffled = randm.shuffle(orig);
+  t.notSame(orig, shuffled);
+  t.same(orig, [1, 2, 3, 4]);
+  t.end();
+});
+
+t.test(
+  "should be able to mock the array returned from randm.shuffle",
+  function (t) {
+    const originalArray = ["original", "items"];
+    randm.next.shuffle.returns(["mocked", "items"]);
+    const shuffled = randm.shuffle(originalArray);
+    t.same(shuffled, ["mocked", "items"]);
+    t.end();
+  }
+);
+
+t.test(
+  "should be able to mock the subsequent calls to randm.shuffle",
+  function (t) {
+    const originalArray = ["original", "items"];
+    randm.next.shuffle.returns(["mocked", "items1"], ["mocked", "items2"]);
+    const shuffled1 = randm.shuffle(originalArray);
+    const shuffled2 = randm.shuffle(originalArray);
+    t.same(shuffled1, ["mocked", "items1"]);
+    t.same(shuffled2, ["mocked", "items2"]);
+    t.end();
+  }
+);