feat(helpers): add length range support in `arrayElements` (#1772)

2 files changed, 69 insertions, 1 deletions

diff --git a/test/__snapshots__/helpers.spec.ts.snap b/test/__snapshots__/helpers.spec.ts.snap
index ca5ae30a..3b149cf6 100644
--- a/test/__snapshots__/helpers.spec.ts.snap
+++ b/test/__snapshots__/helpers.spec.ts.snap
@@ -29,6 +29,13 @@ exports[`helpers > 42 > arrayElements > with array and count 1`] = `
 ]
 `;
 
+exports[`helpers > 42 > arrayElements > with array and count range 1`] = `
+[
+  "d",
+  "l",
+]
+`;
+
 exports[`helpers > 42 > fake > with a dynamic template 1`] = `"my string: Cky2eiXX/J"`;
 
 exports[`helpers > 42 > fake > with a static template 1`] = `"my test string"`;
@@ -218,6 +225,16 @@ exports[`helpers > 1211 > arrayElements > with array and count 1`] = `
 ]
 `;
 
+exports[`helpers > 1211 > arrayElements > with array and count range 1`] = `
+[
+  "e",
+  "l",
+  "o",
+  "l",
+  " ",
+]
+`;
+
 exports[`helpers > 1211 > fake > with a dynamic template 1`] = `"my string: wKti5-}$_/"`;
 
 exports[`helpers > 1211 > fake > with a static template 1`] = `"my test string"`;
@@ -403,6 +420,13 @@ exports[`helpers > 1337 > arrayElements > with array and count 1`] = `
 ]
 `;
 
+exports[`helpers > 1337 > arrayElements > with array and count range 1`] = `
+[
+  "e",
+  "W",
+]
+`;
+
 exports[`helpers > 1337 > fake > with a dynamic template 1`] = `"my string: 9U/4:SK$>6"`;
 
 exports[`helpers > 1337 > fake > with a static template 1`] = `"my test string"`;
diff --git a/test/helpers.spec.ts b/test/helpers.spec.ts
index 0e75e10f..b991cbac 100644
--- a/test/helpers.spec.ts
+++ b/test/helpers.spec.ts
@@ -76,7 +76,11 @@ describe('helpers', () => {
     t.describe('arrayElements', (t) => {
       t.it('noArgs')
         .it('with array', 'Hello World!'.split(''))
-        .it('with array and count', 'Hello World!'.split(''), 3);
+        .it('with array and count', 'Hello World!'.split(''), 3)
+        .it('with array and count range', 'Hello World!'.split(''), {
+          min: 1,
+          max: 5,
+        });
     });
 
     t.describe('shuffle', (t) => {
@@ -281,6 +285,46 @@ describe('helpers', () => {
           expect(subset).toHaveLength(new Set(subset).size);
         });
 
+        it('should return a subset with random elements in the array for a length range', () => {
+          const testArray = ['hello', 'to', 'you', 'my', 'friend'];
+          const subset = faker.helpers.arrayElements(testArray, {
+            min: 2,
+            max: 4,
+          });
+
+          // Check length
+          expect(subset.length).toBeGreaterThanOrEqual(2);
+          expect(subset.length).toBeLessThanOrEqual(4);
+
+          // Check elements
+          subset.forEach((element) => {
+            expect(testArray).toContain(element);
+          });
+
+          // Check uniqueness
+          expect(subset).not.toContainDuplicates();
+        });
+
+        it('should return an array with all elements when count > array length', () => {
+          const testArray = ['hello', 'to', 'you', 'my', 'friend'];
+          const subset = faker.helpers.arrayElements(testArray, 6);
+
+          // Check length
+          expect(subset.length).toEqual(5);
+
+          // Check elements
+          subset.forEach((element) => {
+            expect(testArray).toContain(element);
+          });
+        });
+
+        it('should return an empty array when array length > 0 and count = 0', () => {
+          const testArray = ['hello', 'to', 'you', 'my', 'friend'];
+          const result = faker.helpers.arrayElements(testArray, 0);
+
+          expect(result).toHaveLength(0);
+        });
+
         it('should return an empty array when receiving an empty array', () => {
           const result = faker.helpers.arrayElements([]);