feat(helpers): introduce `multiple` method (#1545)

9 files changed, 97 insertions, 92 deletions

diff --git a/src/modules/color/index.ts b/src/modules/color/index.ts
index b232f649..11ebdcd9 100644
--- a/src/modules/color/index.ts
+++ b/src/modules/color/index.ts
@@ -320,7 +320,7 @@ export class ColorModule {
       color = formatHexColor(color, options);
       return color;
     }
-    color = Array.from({ length: 3 }).map(() => this.faker.number.int(255));
+    color = Array.from({ length: 3 }, () => this.faker.number.int(255));
     if (includeAlpha) {
       color.push(this.faker.number.float({ max: 1, precision: 0.01 }));
       cssFunction = 'rgba';
@@ -380,7 +380,7 @@ export class ColorModule {
    */
   cmyk(options?: { format?: ColorFormat }): string | number[];
   cmyk(options?: { format?: ColorFormat }): string | number[] {
-    const color: string | number[] = Array.from({ length: 4 }).map(() =>
+    const color: string | number[] = Array.from({ length: 4 }, () =>
       this.faker.number.float({ max: 1, precision: 0.01 })
     );
     return toColorFormat(color, options?.format || 'decimal', 'cmyk');
@@ -742,7 +742,7 @@ export class ColorModule {
     if (options?.format === 'css' && !options?.space) {
       options = { ...options, space: 'sRGB' };
     }
-    const color = Array.from({ length: 3 }).map(() =>
+    const color = Array.from({ length: 3 }, () =>
       this.faker.number.float({ max: 1, precision: 0.0001 })
     );
     return toColorFormat(
diff --git a/src/modules/datatype/index.ts b/src/modules/datatype/index.ts
index 70a539d7..b7000dc6 100644
--- a/src/modules/datatype/index.ts
+++ b/src/modules/datatype/index.ts
@@ -278,16 +278,23 @@ export class DatatypeModule {
    * Returns an array with random strings and numbers.
    *
    * @param length Size of the returned array. Defaults to `10`.
+   * @param length.min The minimum size of the array.
+   * @param length.max The maximum size of the array.
    *
    * @example
    * faker.datatype.array() // [ 94099, 85352, 'Hz%T.C\\l;8', '|#gmtw3otS', '2>:rJ|3$&d', 56864, 'Ss2-p0RXSI', 51084, 2039, 'mNEU[.r0Vf' ]
    * faker.datatype.array(3) // [ 61845, 'SK7H$W3:d*', 'm[%7N8*GVK' ]
+   * faker.datatype.array({ min: 3, max: 5 }) // [ 99403, 76924, 42281, "Q'|$&y\\G/9" ]
    *
    * @since 5.5.0
    */
-  array(length = 10): Array<string | number> {
-    return Array.from<string | number>({ length }).map(() =>
-      this.boolean() ? this.faker.string.sample() : this.faker.number.int()
+  array(
+    length: number | { min: number; max: number } = 10
+  ): Array<string | number> {
+    return this.faker.helpers.multiple(
+      () =>
+        this.boolean() ? this.faker.string.sample() : this.faker.number.int(),
+      { count: length }
     );
   }
 
diff --git a/src/modules/date/index.ts b/src/modules/date/index.ts
index a76b430f..e8bdde28 100644
--- a/src/modules/date/index.ts
+++ b/src/modules/date/index.ts
@@ -331,13 +331,19 @@ export class DateModule {
    * // ]
    * faker.date.betweens({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z', count: 2 })
    * // [ 2023-05-02T16:00:00.000Z, 2026-09-01T08:00:00.000Z ]
+   * faker.date.betweens({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z', count: { min: 2, max: 5 }})
+   * // [
+   * //   2021-12-19T06:35:40.191Z,
+   * //   2022-09-10T08:03:51.351Z,
+   * //   2023-04-19T11:41:17.501Z
+   * // ]
    *
    * @since 8.0.0
    */
   betweens(options: {
     from: string | Date | number;
     to: string | Date | number;
-    count?: number;
+    count?: number | { min: number; max: number };
   }): Date[];
   /**
    * Generates random dates between the given boundaries.
@@ -345,6 +351,8 @@ export class DateModule {
    * @param from The early date boundary.
    * @param to The late date boundary.
    * @param count The number of dates to generate. Defaults to `3`.
+   * @param count.min The minimum number of dates to generate.
+   * @param count.max The maximum number of dates to generate.
    *
    * @example
    * faker.date.betweens('2020-01-01T00:00:00.000Z', '2030-01-01T00:00:00.000Z')
@@ -384,6 +392,12 @@ export class DateModule {
    * // ]
    * faker.date.betweens({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z', count: 2 })
    * // [ 2023-05-02T16:00:00.000Z, 2026-09-01T08:00:00.000Z ]
+   * faker.date.betweens({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z', count: { min: 2, max: 5 }})
+   * // [
+   * //   2021-12-19T06:35:40.191Z,
+   * //   2022-09-10T08:03:51.351Z,
+   * //   2023-04-19T11:41:17.501Z
+   * // ]
    *
    * @since 8.0.0
    */
@@ -395,7 +409,7 @@ export class DateModule {
       | {
           from: string | Date | number;
           to: string | Date | number;
-          count?: number;
+          count?: number | { min: number; max: number };
         },
     legacyTo?: string | Date | number,
     legacyCount?: number
@@ -408,7 +422,7 @@ export class DateModule {
       | {
           from: string | Date | number;
           to: string | Date | number;
-          count?: number;
+          count?: number | { min: number; max: number };
         },
     legacyTo?: string | Date | number,
     legacyCount: number = 3
@@ -425,9 +439,9 @@ export class DateModule {
 
     const { from, to, count = 3 } = options;
 
-    return Array.from({ length: count }, () => this.between({ from, to })).sort(
-      (a, b) => a.getTime() - b.getTime()
-    );
+    return this.faker.helpers
+      .multiple(() => this.between({ from, to }), { count })
+      .sort((a, b) => a.getTime() - b.getTime());
   }
 
   /**
diff --git a/src/modules/helpers/index.ts b/src/modules/helpers/index.ts
index af6ae4b8..37487247 100644
--- a/src/modules/helpers/index.ts
+++ b/src/modules/helpers/index.ts
@@ -690,4 +690,33 @@ export class HelpersModule {
       currentIterations: 0,
     });
   }
+
+  /**
+   * Generates an array containing values returned by the given method.
+   *
+   * @param method The method used to generate the values.
+   * @param options The optional options object.
+   * @param options.count The number or range of elements to generate. Defaults to `3`.
+   *
+   * @example
+   * faker.helpers.multiple(faker.person.firstName) // [ 'Aniya', 'Norval', 'Dallin' ]
+   * faker.helpers.multiple(faker.person.firstName, { count: 3 }) // [ 'Santos', 'Lavinia', 'Lavinia' ]
+   *
+   * @since 8.0.0
+   */
+  multiple<T>(
+    method: () => T,
+    options: {
+      count?: number | { min: number; max: number };
+    } = {}
+  ): T[] {
+    const count = this.rangeToNumber(options.count ?? 3);
+    if (count <= 0) {
+      return [];
+    }
+
+    // TODO @ST-DDT 2022-11-21: Add support for unique option
+
+    return Array.from({ length: count }, method);
+  }
 }
diff --git a/src/modules/internet/index.ts b/src/modules/internet/index.ts
index dc3eaa62..4f313275 100644
--- a/src/modules/internet/index.ts
+++ b/src/modules/internet/index.ts
@@ -387,16 +387,9 @@ export class InternetModule {
    * @since 6.1.1
    */
   ipv4(): string {
-    const randNum = () => {
-      return this.faker.number.int(255).toFixed(0);
-    };
-
-    const result: string[] = [];
-    for (let i = 0; i < 4; i++) {
-      result[i] = randNum();
-    }
-
-    return result.join('.');
+    return Array.from({ length: 4 }, () => this.faker.number.int(255)).join(
+      '.'
+    );
   }
 
   /**
@@ -408,36 +401,13 @@ export class InternetModule {
    * @since 4.0.0
    */
   ipv6(): string {
-    const randHash = () => {
-      let result = '';
-      for (let i = 0; i < 4; i++) {
-        result += this.faker.helpers.arrayElement([
-          '0',
-          '1',
-          '2',
-          '3',
-          '4',
-          '5',
-          '6',
-          '7',
-          '8',
-          '9',
-          'a',
-          'b',
-          'c',
-          'd',
-          'e',
-          'f',
-        ]);
-      }
-      return result;
-    };
-
-    const result: string[] = [];
-    for (let i = 0; i < 8; i++) {
-      result[i] = randHash();
-    }
-    return result.join(':');
+    return Array.from({ length: 8 }, () =>
+      this.faker.string.hexadecimal({
+        length: 4,
+        casing: 'lower',
+        prefix: '',
+      })
+    ).join(':');
   }
 
   /**
diff --git a/src/modules/lorem/index.ts b/src/modules/lorem/index.ts
index c73a92c8..8e989ab6 100644
--- a/src/modules/lorem/index.ts
+++ b/src/modules/lorem/index.ts
@@ -72,10 +72,8 @@ export class LoremModule {
    * @since 2.0.1
    */
   words(wordCount: number | { min: number; max: number } = 3): string {
-    wordCount = this.faker.helpers.rangeToNumber(wordCount);
-
-    return Array.from({ length: wordCount })
-      .map(() => this.word())
+    return this.faker.helpers
+      .multiple(() => this.word(), { count: wordCount })
       .join(' ');
   }
 
@@ -141,10 +139,8 @@ export class LoremModule {
     sentenceCount: number | { min: number; max: number } = { min: 2, max: 6 },
     separator: string = ' '
   ): string {
-    sentenceCount = this.faker.helpers.rangeToNumber(sentenceCount);
-
-    return Array.from({ length: sentenceCount })
-      .map(() => this.sentence())
+    return this.faker.helpers
+      .multiple(() => this.sentence(), { count: sentenceCount })
       .join(separator);
   }
 
@@ -202,10 +198,8 @@ export class LoremModule {
     paragraphCount: number | { min: number; max: number } = 3,
     separator: string = '\n'
   ): string {
-    paragraphCount = this.faker.helpers.rangeToNumber(paragraphCount);
-
-    return Array.from({ length: paragraphCount })
-      .map(() => this.paragraph())
+    return this.faker.helpers
+      .multiple(() => this.paragraph(), { count: paragraphCount })
       .join(separator);
   }
 
@@ -267,8 +261,6 @@ export class LoremModule {
   lines(
     lineCount: number | { min: number; max: number } = { min: 1, max: 5 }
   ): string {
-    lineCount = this.faker.helpers.rangeToNumber(lineCount);
-
     return this.sentences(lineCount, '\n');
   }
 }
diff --git a/src/modules/random/index.ts b/src/modules/random/index.ts
index f8691198..1f4b499b 100644
--- a/src/modules/random/index.ts
+++ b/src/modules/random/index.ts
@@ -137,28 +137,23 @@ export class RandomModule {
   }
 
   /**
-   * Returns string with set of random words.
+   * Returns a string with a given number of random words.
    *
-   * @param count Number of words. Defaults to a random value between `1` and `3`.
+   * @param count The number or range of words. Defaults to a random value between `1` and `3`.
+   * @param count.min The minimum number of words. Defaults to `1`.
+   * @param count.max The maximum number of words. Defaults to `3`.
    *
    * @example
    * faker.random.words() // 'neural'
    * faker.random.words(5) // 'copy Handcrafted bus client-server Point'
+   * faker.random.words({ min: 3, max: 5 }) // 'cool sticky Borders'
    *
    * @since 3.1.0
    */
-  words(count?: number): string {
-    const words: string[] = [];
-
-    if (count == null) {
-      count = this.faker.number.int({ min: 1, max: 3 });
-    }
-
-    for (let i = 0; i < count; i++) {
-      words.push(this.word());
-    }
-
-    return words.join(' ');
+  words(
+    count: number | { min: number; max: number } = { min: 1, max: 3 }
+  ): string {
+    return this.faker.helpers.multiple(this.word, { count }).join(' ');
   }
 
   /**
diff --git a/src/modules/system/index.ts b/src/modules/system/index.ts
index 4bf28aff..ca78929e 100644
--- a/src/modules/system/index.ts
+++ b/src/modules/system/index.ts
@@ -67,20 +67,18 @@ export class SystemModule {
       extensionCount?: number | { min: number; max: number };
     } = {}
   ): string {
-    const extensionCount = this.faker.helpers.rangeToNumber(
-      options.extensionCount ?? 1
-    );
+    const { extensionCount = 1 } = options;
 
     const baseName = this.faker.word.words().toLowerCase().replace(/\W/g, '_');
 
-    if (extensionCount <= 0) {
+    const extensionsStr = this.faker.helpers
+      .multiple(() => this.fileExt(), { count: extensionCount })
+      .join('.');
+
+    if (extensionsStr.length === 0) {
       return baseName;
     }
 
-    const extensionsStr = Array.from({ length: extensionCount })
-      .map(() => this.fileExt())
-      .join('.');
-
     return `${baseName}.${extensionsStr}`;
   }
 
diff --git a/src/modules/word/index.ts b/src/modules/word/index.ts
index d326cd70..22a22a0b 100644
--- a/src/modules/word/index.ts
+++ b/src/modules/word/index.ts
@@ -392,10 +392,10 @@ export class WordModule {
     if (typeof options === 'number') {
       options = { count: options };
     }
-    const count = this.faker.helpers.rangeToNumber(
-      options.count ?? { min: 1, max: 3 }
-    );
+    const { count = { min: 1, max: 3 } } = options;
 
-    return Array.from({ length: count }, () => this.sample()).join(' ');
+    return this.faker.helpers
+      .multiple(() => this.sample(), { count })
+      .join(' ');
   }
 }