feat(word): add sample method (#714)

Co-authored-by: Shinigami <[email protected]>
Co-authored-by: ST-DDT <[email protected]>

3 files changed, 79 insertions, 7 deletions

diff --git a/src/modules/helpers/index.ts b/src/modules/helpers/index.ts
index 063ec8d3..82eaf5f7 100644
--- a/src/modules/helpers/index.ts
+++ b/src/modules/helpers/index.ts
@@ -307,7 +307,7 @@ export class HelpersModule {
    * @param length The number of elements to generate.
    *
    * @example
-   * faker.helpers.uniqueArray(faker.random.word, 50)
+   * faker.helpers.uniqueArray(faker.word.sample, 50)
    * faker.helpers.uniqueArray(faker.definitions.person.first_name, 6)
    * faker.helpers.uniqueArray(["Hello", "World", "Goodbye"], 2)
    *
diff --git a/src/modules/system/index.ts b/src/modules/system/index.ts
index 860ab7b9..8c935c88 100644
--- a/src/modules/system/index.ts
+++ b/src/modules/system/index.ts
@@ -53,8 +53,8 @@ export class SystemModule {
    * @param options.extensionCount Define how many extensions the file name should have. A negative number will be treated as `0`. Defaults to `1`.
    *
    * @example
-   * faker.system.fileName() // 'self_enabling_accountability_toys.kpt'
-   * faker.system.fileName({ extensionCount: 2 }) // 'bike_table.res.vcs'
+   * faker.system.fileName() // 'faithfully_calculating.u8mdn'
+   * faker.system.fileName({ extensionCount: 2 }) // 'times_after.swf.ntf'
    *
    * @since 3.1.0
    */
@@ -68,10 +68,7 @@ export class SystemModule {
   ): string {
     const { extensionCount = 1 } = options;
 
-    const baseName = this.faker.random
-      .words()
-      .toLowerCase()
-      .replace(/\W/g, '_');
+    const baseName = this.faker.word.words().toLowerCase().replace(/\W/g, '_');
 
     if (extensionCount <= 0) {
       return baseName;
diff --git a/src/modules/word/index.ts b/src/modules/word/index.ts
index 9bdf8f06..89795919 100644
--- a/src/modules/word/index.ts
+++ b/src/modules/word/index.ts
@@ -1,4 +1,5 @@
 import type { Faker } from '../..';
+import { FakerError } from '../../errors/faker-error';
 import { filterWordListByLength } from './filterWordListByLength';
 
 /**
@@ -315,4 +316,78 @@ export class WordModule {
       })
     );
   }
+
+  /**
+   * Returns a random sample of random or optionally specified length.
+   *
+   * @param options The expected length of the word or the options to use.
+   * @param options.length The expected length of the word.
+   * @param options.strategy The strategy to apply when no words with a matching length are found.
+   *
+   * Available error handling strategies:
+   *
+   * - `fail`: Throws an error if no words with the given length are found.
+   * - `shortest`: Returns any of the shortest words.
+   * - `closest`: Returns any of the words closest to the given length.
+   * - `longest`: Returns any of the longest words.
+   * - `any-length`: Returns a word with any length.
+   *
+   * Defaults to `'any-length'`.
+   *
+   * @example
+   * faker.word.sample() // 'incidentally'
+   * faker.word.sample(5) // 'fruit'
+   *
+   * @since 8.0.0
+   */
+  sample(
+    options:
+      | number
+      | {
+          length?: number | { min: number; max: number };
+          strategy?: 'fail' | 'closest' | 'shortest' | 'longest' | 'any-length';
+        } = {}
+  ): string {
+    const wordMethods = this.faker.helpers.shuffle([
+      this.adjective,
+      this.adverb,
+      this.conjunction,
+      this.interjection,
+      this.noun,
+      this.preposition,
+      this.verb,
+    ]);
+
+    for (const randomWordMethod of wordMethods) {
+      try {
+        return randomWordMethod(options);
+      } catch {
+        // catch missing locale data potentially required by randomWordMethod
+        continue;
+      }
+    }
+
+    throw new FakerError(
+      'No matching word data available for the current locale'
+    );
+  }
+
+  /**
+   * Returns a string containing a number of space separated random words.
+   *
+   * @param count Number of words. Defaults to a random value between `1` and `3`.
+   *
+   * @example
+   * faker.word.words() // 'almost'
+   * faker.word.words(5) // 'before hourly patiently dribble equal'
+   *
+   * @since 8.0.0
+   */
+  words(count?: number): string {
+    if (count == null) {
+      count = this.faker.datatype.number({ min: 1, max: 3 });
+    }
+
+    return Array.from({ length: count }, () => this.sample()).join(' ');
+  }
 }