From 996066680e5520b171a9c7b790b4af337752dddd Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 8 Sep 2025 17:01:32 +0000
Subject: [PATCH 1/2] Initial plan


From 7e7c031d8bfee49ded573e1ff8ba2bd44804d798 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 8 Sep 2025 17:07:56 +0000
Subject: [PATCH 2/2] Implement shuffle() and shuffled() methods for
 collections

Co-authored-by: ngarbezza <519947+ngarbezza@users.noreply.github.com>
---
 src/extensions/collections.js                 | 24 ++++++
 tests/extensions/collection_extension_test.js | 81 +++++++++++++++++++
 2 files changed, 105 insertions(+)

diff --git a/src/extensions/collections.js b/src/extensions/collections.js
index 193f8ea..f006606 100644
--- a/src/extensions/collections.js
+++ b/src/extensions/collections.js
@@ -101,6 +101,21 @@ const SequenceableCollection = {
     allButLast() {
       return this.take(this.dimension() - 1);
     },
+
+    shuffled() {
+      const copy = this.asArray();
+      // Fisher-Yates shuffle algorithm
+      for (let i = copy.dimension() - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [copy[i], copy[j]] = [copy[j], copy[i]];
+      }
+      
+      // Return the appropriate type based on the original
+      if (this.isString && this.isString()) {
+        return copy.join('');
+      }
+      return copy;
+    },
   },
 };
 
@@ -162,6 +177,15 @@ const ArrayExtensions = {
     clear() {
       this.length = 0;
     },
+
+    shuffle() {
+      // Fisher-Yates shuffle algorithm
+      for (let i = this.dimension() - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [this[i], this[j]] = [this[j], this[i]];
+      }
+      return this;
+    },
   },
 };
 
diff --git a/tests/extensions/collection_extension_test.js b/tests/extensions/collection_extension_test.js
index bcfe236..5f1bf1d 100644
--- a/tests/extensions/collection_extension_test.js
+++ b/tests/extensions/collection_extension_test.js
@@ -315,4 +315,85 @@ suite('messages added to Array, String and Set', () => {
 
     assert.that(array).isEmpty();
   });
+
+  test('shuffle() mutates the original array', () => {
+    const originalArray = [1, 2, 3, 4, 5];
+    const array = [...originalArray]; // create a copy
+    const result = array.shuffle();
+
+    // shuffle() should return the same array instance
+    assert.areEqual(result, array);
+    
+    // the array should still have the same elements
+    assert.that(array).includesExactly(...originalArray);
+    
+    // the array should have the same length
+    assert.areEqual(array.dimension(), originalArray.length);
+  });
+
+  test('shuffle() with single element array', () => {
+    const array = [1];
+    array.shuffle();
+    assert.areEqual(array, [1]);
+  });
+
+  test('shuffle() with empty array', () => {
+    const array = [];
+    array.shuffle();
+    assert.areEqual(array, []);
+  });
+
+  test('shuffled() returns a new shuffled array without modifying original', () => {
+    const originalArray = [1, 2, 3, 4, 5];
+    const shuffledArray = originalArray.shuffled();
+
+    // original should be unchanged
+    assert.areEqual(originalArray, [1, 2, 3, 4, 5]);
+    
+    // shuffled should have the same elements
+    assert.that(shuffledArray).includesExactly(...originalArray);
+    
+    // shuffled should have the same length
+    assert.areEqual(shuffledArray.dimension(), originalArray.length);
+  });
+
+  test('shuffled() with single element array', () => {
+    const array = [1];
+    const shuffled = array.shuffled();
+    assert.areEqual(shuffled, [1]);
+    assert.areEqual(array, [1]); // original unchanged
+  });
+
+  test('shuffled() with empty array', () => {
+    const array = [];
+    const shuffled = array.shuffled();
+    assert.areEqual(shuffled, []);
+    assert.areEqual(array, []); // original unchanged
+  });
+
+  test('shuffled() returns a shuffled string without modifying original', () => {
+    const originalString = 'hello';
+    const shuffledString = originalString.shuffled();
+
+    // original should be unchanged
+    assert.areEqual(originalString, 'hello');
+    
+    // shuffled should have the same characters
+    assert.areEqual(shuffledString.asArray().sort().join(''), 'ehllo');
+    
+    // shuffled should have the same length
+    assert.areEqual(shuffledString.dimension(), originalString.length);
+  });
+
+  test('shuffled() with single character string', () => {
+    const string = 'a';
+    const shuffled = string.shuffled();
+    assert.areEqual(shuffled, 'a');
+  });
+
+  test('shuffled() with empty string', () => {
+    const string = '';
+    const shuffled = string.shuffled();
+    assert.areEqual(shuffled, '');
+  });
 });