feat(helpers): add rangeToNumber method and add range parameters (#1486)

Author: ST-DDT

src/modules/helpers/index.ts

@@ -627,6 +627,26 @@ export class HelpersModule {
     return this.fake(res);
   }
 
+  /**
+   * Helper method that converts the given number or range to a number.
+   *
+   * @param numberOrRange The number or range to convert.
+   * @param numberOrRange.min The minimum value for the range.
+   * @param numberOrRange.max The maximum value for the range.
+   *
+   * @example
+   * faker.helpers.rangeToNumber(1) // 1
+   * faker.helpers.rangeToNumber({ min: 1, max: 10 }) // 5
+   *
+   * @since 8.0.0
+   */
+  rangeToNumber(numberOrRange: number | { min: number; max: number }): number {
+    if (typeof numberOrRange === 'number') {
+      return numberOrRange;
+    }
+    return this.faker.datatype.number(numberOrRange);
+  }
+
   /**
    * Generates a unique result using the results of the given method.
    * Used unique entries will be stored internally and filtered from subsequent calls.

src/modules/lorem/index.ts

@@ -36,7 +36,7 @@ export class LoremModule {
    * faker.lorem.word() // 'temporibus'
    * faker.lorem.word(5) // 'velit'
    * faker.lorem.word({ strategy: 'shortest' }) // 'a'
-   * faker.lorem.word({ length: { min: 5, max: 7 }, strategy: "fail" }) // 'quaerat'
+   * faker.lorem.word({ length: { min: 5, max: 7 }, strategy: 'fail' }) // 'quaerat'
    *
    * @since 3.1.0
    */
@@ -60,62 +60,71 @@ export class LoremModule {
   /**
    * Generates a space separated list of words.
    *
-   * @param num The number of words to generate. Defaults to `3`.
+   * @param wordCount The number of words to generate. Defaults to `3`.
+   * @param wordCount.min The minimum number of words to generate.
+   * @param wordCount.max The maximum number of words to generate.
    *
    * @example
    * faker.lorem.words() // 'qui praesentium pariatur'
    * faker.lorem.words(10) // 'debitis consectetur voluptatem non doloremque ipsum autem totam eum ratione'
+   * faker.lorem.words({ min: 1, max: 3 }) // 'tenetur error cum'
    *
    * @since 2.0.1
    */
-  words(num: number = 3): string {
-    const words: string[] = [];
-    for (let i = 0; i < num; i++) {
-      words.push(this.word());
-    }
-    return words.join(' ');
+  words(wordCount: number | { min: number; max: number } = 3): string {
+    wordCount = this.faker.helpers.rangeToNumber(wordCount);
+
+    return Array.from({ length: wordCount })
+      .map(() => this.word())
+      .join(' ');
   }
 
   /**
-   * Generates a space separated list of words beginning a capital letter and ending with a dot.
+   * Generates a space separated list of words beginning with a capital letter and ending with a period.
    *
    * @param wordCount The number of words, that should be in the sentence. Defaults to a random number between `3` and `10`.
+   * @param wordCount.min The minimum number of words to generate. Defaults to `3`.
+   * @param wordCount.max The maximum number of words to generate. Defaults to `10`.
    *
    * @example
    * faker.lorem.sentence() // 'Voluptatum cupiditate suscipit autem eveniet aut dolorem aut officiis distinctio.'
    * faker.lorem.sentence(5) // 'Laborum voluptatem officiis est et.'
+   * faker.lorem.sentence({ min: 3, max: 5 }) // 'Fugiat repellendus nisi.'
    *
    * @since 2.0.1
    */
-  sentence(wordCount?: number): string {
-    if (wordCount == null) {
-      wordCount = this.faker.datatype.number({ min: 3, max: 10 });
-    }
-
+  sentence(
+    wordCount: number | { min: number; max: number } = { min: 3, max: 10 }
+  ): string {
     const sentence = this.words(wordCount);
-    return `${sentence.charAt(0).toUpperCase() + sentence.slice(1)}.`;
+    return `${sentence.charAt(0).toUpperCase() + sentence.substring(1)}.`;
   }
 
   /**
    * Generates a slugified text consisting of the given number of hyphen separated words.
    *
    * @param wordCount The number of words to generate. Defaults to `3`.
+   * @param wordCount.min The minimum number of words to generate.
+   * @param wordCount.max The maximum number of words to generate.
    *
    * @example
    * faker.lorem.slug() // 'dolores-illo-est'
+   * faker.lorem.slug(5) // 'delectus-totam-iusto-itaque-placeat'
+   * faker.lorem.slug({ min: 1, max: 3 }) // 'illo-ratione'
    *
    * @since 4.0.0
    */
-  slug(wordCount?: number): string {
+  slug(wordCount: number | { min: number; max: number } = 3): string {
     const words = this.words(wordCount);
-
     return this.faker.helpers.slugify(words);
   }
 
   /**
    * Generates the given number of sentences.
    *
    * @param sentenceCount The number of sentences to generate. Defaults to a random number between `2` and `6`.
+   * @param sentenceCount.min The minimum number of sentences to generate. Defaults to `2`.
+   * @param sentenceCount.max The maximum number of sentences to generate. Defaults to `6`.
    * @param separator The separator to add between sentences. Defaults to `' '`.
    *
    * @example
@@ -124,39 +133,45 @@ export class LoremModule {
    * faker.lorem.sentences(2, '\n')
    * // 'Et rerum a unde tempora magnam sit nisi.
    * // Et perspiciatis ipsam omnis.'
+   * faker.lorem.sentences({ min: 1, max: 3 }) // 'Placeat ex natus tenetur repellendus repellendus iste. Optio nostrum veritatis.'
    *
    * @since 2.0.1
    */
-  sentences(sentenceCount?: number, separator: string = ' '): string {
-    if (sentenceCount == null) {
-      sentenceCount = this.faker.datatype.number({ min: 2, max: 6 });
-    }
-    const sentences: string[] = [];
-    for (sentenceCount; sentenceCount > 0; sentenceCount--) {
-      sentences.push(this.sentence());
-    }
-    return sentences.join(separator);
+  sentences(
+    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())
+      .join(separator);
   }
 
   /**
-   * Generates a paragraph with at least the given number of sentences.
+   * Generates a paragraph with the given number of sentences.
    *
-   * @param sentenceCount The minim number of sentences to generate. Defaults to `3`.
+   * @param sentenceCount The number of sentences to generate. Defaults to `3`.
+   * @param sentenceCount.min The minimum number of sentences to generate.
+   * @param sentenceCount.max The maximum number of sentences to generate.
    *
    * @example
    * faker.lorem.paragraph() // 'Non architecto nam unde sint. Ex tenetur dolor facere optio aut consequatur. Ea laudantium reiciendis repellendus.'
-   * faker.lorem.paragraph() // 'Animi possimus nemo consequuntur ut ea et tempore unde qui. Quis corporis esse occaecati.'
+   * faker.lorem.paragraph(2) // 'Animi possimus nemo consequuntur ut ea et tempore unde qui. Quis corporis esse occaecati.'
+   * faker.lorem.paragraph({ min: 1, max: 3 }) // 'Quis doloribus necessitatibus sint. Rerum accusamus impedit corporis porro.'
    *
    * @since 2.0.1
    */
-  paragraph(sentenceCount: number = 3): string {
-    return this.sentences(sentenceCount + this.faker.datatype.number(3));
+  paragraph(sentenceCount: number | { min: number; max: number } = 3): string {
+    return this.sentences(sentenceCount);
   }
 
   /**
    * Generates the given number of paragraphs.
    *
    * @param paragraphCount The number of paragraphs to generate. Defaults to `3`.
+   * @param paragraphCount.min The minimum number of paragraphs to generate.
+   * @param paragraphCount.max The maximum number of paragraphs to generate.
    * @param separator The separator to use. Defaults to `'\n'`.
    *
    * @example
@@ -176,14 +191,22 @@ export class LoremModule {
    * // 'Eos magnam aut qui accusamus. Sapiente quas culpa totam excepturi. Blanditiis totam distinctio occaecati dignissimos cumque atque qui officiis.<br/>
    * // Nihil quis vel consequatur. Blanditiis commodi deserunt sunt animi dolorum. A optio porro hic dolorum fugit aut et sint voluptas. Minima ad sed ipsa est non dolores.'
    *
+   * faker.lorem.paragraphs({ min: 1, max: 3 })
+   * // 'Eum nam fugiat laudantium.
+   * // Dignissimos tempore porro necessitatibus commodi nam.
+   * // Veniam at commodi iste perferendis totam dolorum corporis ipsam.'
+   *
    * @since 2.0.1
    */
-  paragraphs(paragraphCount: number = 3, separator: string = '\n'): string {
-    const paragraphs: string[] = [];
-    for (paragraphCount; paragraphCount > 0; paragraphCount--) {
-      paragraphs.push(this.paragraph());
-    }
-    return paragraphs.join(separator);
+  paragraphs(
+    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())
+      .join(separator);
   }
 
   /**
@@ -202,8 +225,6 @@ export class LoremModule {
    */
   text(): string {
     const methods: Array<keyof LoremModule> = [
-      'word',
-      'words',
       'sentence',
       'sentences',
       'paragraph',
@@ -220,6 +241,8 @@ export class LoremModule {
    * Generates the given number lines of lorem separated by `'\n'`.
    *
    * @param lineCount The number of lines to generate. Defaults to a random number between `1` and `5`.
+   * @param lineCount.min The minimum number of lines to generate. Defaults to `1`.
+   * @param lineCount.max The maximum number of lines to generate. Defaults to `5`.
    *
    * @example
    * faker.lorem.lines()
@@ -232,12 +255,20 @@ export class LoremModule {
    * // 'Soluta deserunt eos quam reiciendis libero autem enim nam ut.
    * // Voluptate aut aut.'
    *
+   * faker.lorem.lines(2)
+   * // 'Quod quas nam quis impedit aut consequuntur.
+   * // Animi dolores aspernatur.'
+   *
+   * faker.lorem.lines({ min: 1, max: 3 })
+   * // 'Error dolorem natus quos eum consequatur necessitatibus.'
+   *
    * @since 3.1.0
    */
-  lines(lineCount?: number): string {
-    if (lineCount == null) {
-      lineCount = this.faker.datatype.number({ min: 1, max: 5 });
-    }
+  lines(
+    lineCount: number | { min: number; max: number } = { min: 1, max: 5 }
+  ): string {
+    lineCount = this.faker.helpers.rangeToNumber(lineCount);
+
     return this.sentences(lineCount, '\n');
   }
 }