refactor: move some random methods to helpers

src/helpers.ts

@@ -147,11 +147,11 @@ export class Helpers {
   ): T {
     deprecated({
       deprecated: 'faker.helpers.randomize()',
-      proposed: 'faker.random.arrayElement()',
+      proposed: 'faker.helpers.arrayElement()',
       // since: 'v5.0.0', (?)
       until: 'v7.0.0',
     });
-    return this.faker.random.arrayElement(array);
+    return this.faker.helpers.arrayElement(array);
   }
 
   /**
@@ -742,4 +742,62 @@ export class Helpers {
     const key = this.faker.helpers.objectKey(object);
     return object[key];
   }
+
+  /**
+   * Returns random element from the given array.
+   *
+   * @template T The type of the entries to pick from.
+   * @param array Array to pick the value from.
+   *
+   * @example
+   * faker.helpers.arrayElement(['cat', 'dog', 'mouse']) // 'dog'
+   */
+  arrayElement<T = string>(array: ReadonlyArray<T>): T {
+    const index =
+      array.length > 1
+        ? this.faker.datatype.number({ max: array.length - 1 })
+        : 0;
+
+    return array[index];
+  }
+
+  /**
+   * Returns a subset with random elements of the given array in random order.
+   *
+   * @template T The type of the entries to pick from.
+   * @param array Array to pick the value from. Defaults to `['a', 'b', 'c']`.
+   * @param count Number of elements to pick.
+   *    When not provided, random number of elements will be picked.
+   *    When value exceeds array boundaries, it will be limited to stay inside.
+   *
+   * @example
+   * faker.helpers.arrayElements(['cat', 'dog', 'mouse']) // ['mouse', 'cat']
+   * faker.helpers.arrayElements([1, 2, 3, 4, 5], 2) // [4, 2]
+   */
+  arrayElements<T>(array: ReadonlyArray<T>, count?: number): T[] {
+    if (typeof count !== 'number') {
+      count = this.faker.datatype.number({ min: 1, max: array.length });
+    } else if (count > array.length) {
+      count = array.length;
+    } else if (count < 0) {
+      count = 0;
+    }
+
+    const arrayCopy = array.slice(0);
+    let i = array.length;
+    const min = i - count;
+    let temp: T;
+    let index: number;
+
+    while (i-- > min) {
+      index = Math.floor(
+        (i + 1) * this.faker.datatype.float({ min: 0, max: 0.99 })
+      );
+      temp = arrayCopy[index];
+      arrayCopy[index] = arrayCopy[i];
+      arrayCopy[i] = temp;
+    }
+
+    return arrayCopy.slice(min);
+  }
 }

src/random.ts

@@ -104,16 +104,19 @@ export class Random {
    * @example
    * faker.random.arrayElement() // 'b'
    * faker.random.arrayElement(['cat', 'dog', 'mouse']) // 'dog'
+   *
+   * @deprecated
    */
   arrayElement<T = string>(
     array: ReadonlyArray<T> = ['a', 'b', 'c'] as unknown as ReadonlyArray<T>
   ): T {
-    const index =
-      array.length > 1
-        ? this.faker.datatype.number({ max: array.length - 1 })
-        : 0;
-
-    return array[index];
+    deprecated({
+      deprecated: 'faker.random.arrayElement()',
+      proposed: 'faker.helpers.arrayElement()',
+      since: 'v6.3.0',
+      until: 'v7.0.0',
+    });
+    return this.faker.helpers.arrayElement(array);
   }
 
   /**
@@ -129,35 +132,20 @@ export class Random {
    * faker.random.arrayElements() // ['b', 'c']
    * faker.random.arrayElements(['cat', 'dog', 'mouse']) // ['mouse', 'cat']
    * faker.random.arrayElements([1, 2, 3, 4, 5], 2) // [4, 2]
+   *
+   * @deprecated
    */
   arrayElements<T>(
     array: ReadonlyArray<T> = ['a', 'b', 'c'] as unknown as ReadonlyArray<T>,
     count?: number
   ): T[] {
-    if (typeof count !== 'number') {
-      count = this.faker.datatype.number({ min: 1, max: array.length });
-    } else if (count > array.length) {
-      count = array.length;
-    } else if (count < 0) {
-      count = 0;
-    }
-
-    const arrayCopy = array.slice(0);
-    let i = array.length;
-    const min = i - count;
-    let temp: T;
-    let index: number;
-
-    while (i-- > min) {
-      index = Math.floor(
-        (i + 1) * this.faker.datatype.float({ min: 0, max: 0.99 })
-      );
-      temp = arrayCopy[index];
-      arrayCopy[index] = arrayCopy[i];
-      arrayCopy[i] = temp;
-    }
-
-    return arrayCopy.slice(min);
+    deprecated({
+      deprecated: 'faker.random.arrayElements()',
+      proposed: 'faker.helpers.arrayElements()',
+      since: 'v6.3.0',
+      until: 'v7.0.0',
+    });
+    return this.faker.helpers.arrayElements(array, count);
   }
 
   /**

test/helpers.spec.ts

@@ -497,9 +497,58 @@ describe('helpers', () => {
     faker.seedValue
   )}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
-      describe('randomize()', () => {
-        // Will be marked as deprecated soon
+      describe('arrayElement', () => {
+        it('should return a random element in the array', () => {
+          const testArray = ['hello', 'to', 'you', 'my', 'friend'];
+          const actual = faker.helpers.arrayElement(testArray);
+
+          expect(testArray).toContain(actual);
+        });
+
+        it('should return a random element in the array when there is only 1', () => {
+          const testArray = ['hello'];
+          const actual = faker.helpers.arrayElement(testArray);
+
+          expect(actual).toBe('hello');
+        });
+      });
+
+      describe('arrayElements', () => {
+        it('should return a subset with random elements in the array', () => {
+          const testArray = ['hello', 'to', 'you', 'my', 'friend'];
+          const subset = faker.helpers.arrayElements(testArray);
+
+          // Check length
+          expect(subset.length).toBeGreaterThanOrEqual(1);
+          expect(subset.length).toBeLessThanOrEqual(testArray.length);
+
+          // Check elements
+          subset.forEach((element) => {
+            expect(testArray).toContain(element);
+          });
 
+          // Check uniqueness
+          expect(subset).toHaveLength(new Set(subset).size);
+        });
+
+        it('should return a subset of fixed length with random elements in the array', () => {
+          const testArray = ['hello', 'to', 'you', 'my', 'friend'];
+          const subset = faker.helpers.arrayElements(testArray, 3);
+
+          // Check length
+          expect(subset).toHaveLength(3);
+
+          // Check elements
+          subset.forEach((element) => {
+            expect(testArray).toContain(element);
+          });
+
+          // Check uniqueness
+          expect(subset).toHaveLength(new Set(subset).size);
+        });
+      });
+
+      describe('randomize()', () => {
         it('returns a random element from an array', () => {
           const arr = ['a', 'b', 'c'];
           const elem = faker.helpers.randomize(arr);