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

Co-authored-by: Shinigami <chrissi92@hotmail.de>
Co-authored-by: ST-DDT <ST-DDT@gmx.de>

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)
    *

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;

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(' ');
+  }
 }

test/__snapshots__/system.spec.ts.snap

@@ -2,9 +2,9 @@
 
 exports[`system > 42 > commonFileExt 1`] = `"png"`;
 
-exports[`system > 42 > commonFileName > noArgs 1`] = `"lavender_shoes.mpe"`;
+exports[`system > 42 > commonFileName > noArgs 1`] = `"nonbeliever_stub.png"`;
 
-exports[`system > 42 > commonFileName > with extension 1`] = `"lavender_shoes.ext"`;
+exports[`system > 42 > commonFileName > with extension 1`] = `"nonbeliever_stub.ext"`;
 
 exports[`system > 42 > commonFileType 1`] = `"audio"`;
 
@@ -24,11 +24,11 @@ exports[`system > 42 > fileExt > noArgs 1`] = `"lrm"`;
 
 exports[`system > 42 > fileExt > with mimeType 1`] = `"json"`;
 
-exports[`system > 42 > fileName > noArgs 1`] = `"lavender_shoes.jxsc"`;
+exports[`system > 42 > fileName > noArgs 1`] = `"nonbeliever_stub.skt"`;
 
-exports[`system > 42 > fileName > with extensionCount 1`] = `"lavender_shoes.jxsc.jardiff"`;
+exports[`system > 42 > fileName > with extensionCount 1`] = `"nonbeliever_stub.skt.latex"`;
 
-exports[`system > 42 > filePath 1`] = `"/opt/bin/comeback_neptunium_hip.ptid"`;
+exports[`system > 42 > filePath 1`] = `"/opt/bin/crowded_fail_woefully.dra"`;
 
 exports[`system > 42 > fileType 1`] = `"image"`;
 
@@ -80,9 +80,9 @@ exports[`system > 42 > semver 1`] = `"3.7.9"`;
 
 exports[`system > 1211 > commonFileExt 1`] = `"htm"`;
 
-exports[`system > 1211 > commonFileName > noArgs 1`] = `"invoice_cyclocross_assault.mp4"`;
+exports[`system > 1211 > commonFileName > noArgs 1`] = `"although_instantly_though.gif"`;
 
-exports[`system > 1211 > commonFileName > with extension 1`] = `"invoice_cyclocross_assault.ext"`;
+exports[`system > 1211 > commonFileName > with extension 1`] = `"although_instantly_though.ext"`;
 
 exports[`system > 1211 > commonFileType 1`] = `"application"`;
 
@@ -102,11 +102,11 @@ exports[`system > 1211 > fileExt > noArgs 1`] = `"dic"`;
 
 exports[`system > 1211 > fileExt > with mimeType 1`] = `"map"`;
 
-exports[`system > 1211 > fileName > noArgs 1`] = `"invoice_cyclocross_assault.z2"`;
+exports[`system > 1211 > fileName > noArgs 1`] = `"although_instantly_though.ustar"`;
 
-exports[`system > 1211 > fileName > with extensionCount 1`] = `"invoice_cyclocross_assault.z2.tsd"`;
+exports[`system > 1211 > fileName > with extensionCount 1`] = `"although_instantly_though.ustar.ecelp4800"`;
 
-exports[`system > 1211 > filePath 1`] = `"/var/log/strictly_rustic.avi"`;
+exports[`system > 1211 > filePath 1`] = `"/var/log/outside_even.xhvml"`;
 
 exports[`system > 1211 > fileType 1`] = `"x-shader"`;
 
@@ -158,9 +158,9 @@ exports[`system > 1211 > semver 1`] = `"9.4.8"`;
 
 exports[`system > 1337 > commonFileExt 1`] = `"wav"`;
 
-exports[`system > 1337 > commonFileName > noArgs 1`] = `"quia.mp2"`;
+exports[`system > 1337 > commonFileName > noArgs 1`] = `"although.wav"`;
 
-exports[`system > 1337 > commonFileName > with extension 1`] = `"quia.ext"`;
+exports[`system > 1337 > commonFileName > with extension 1`] = `"although.ext"`;
 
 exports[`system > 1337 > commonFileType 1`] = `"audio"`;
 
@@ -180,11 +180,11 @@ exports[`system > 1337 > fileExt > noArgs 1`] = `"oa3"`;
 
 exports[`system > 1337 > fileExt > with mimeType 1`] = `"json"`;
 
-exports[`system > 1337 > fileName > noArgs 1`] = `"quia.cmc"`;
+exports[`system > 1337 > fileName > noArgs 1`] = `"although.chrt"`;
 
-exports[`system > 1337 > fileName > with extensionCount 1`] = `"quia.cmc.kml"`;
+exports[`system > 1337 > fileName > with extensionCount 1`] = `"although.chrt.dpg"`;
 
-exports[`system > 1337 > filePath 1`] = `"/Library/duane_fort.wmlc"`;
+exports[`system > 1337 > filePath 1`] = `"/Library/yum_fast.aiff"`;
 
 exports[`system > 1337 > fileType 1`] = `"font"`;
 
@@ -236,7 +236,7 @@ exports[`system > 1337 > semver 1`] = `"2.5.1"`;
 
 exports[`system > seed: 42 > commonFileExt() 1`] = `"png"`;
 
-exports[`system > seed: 42 > commonFileName() 1`] = `"lavender_shoes.mpe"`;
+exports[`system > seed: 42 > commonFileName() 1`] = `"nonbeliever_stub.png"`;
 
 exports[`system > seed: 42 > commonFileType() 1`] = `"audio"`;
 
@@ -246,9 +246,9 @@ exports[`system > seed: 42 > directoryPath() 1`] = `"/opt/bin"`;
 
 exports[`system > seed: 42 > fileExt() 1`] = `"lrm"`;
 
-exports[`system > seed: 42 > fileName() 1`] = `"lavender_shoes.jxsc"`;
+exports[`system > seed: 42 > fileName() 1`] = `"nonbeliever_stub.skt"`;
 
-exports[`system > seed: 42 > filePath() 1`] = `"/opt/bin/comeback_neptunium_hip.ptid"`;
+exports[`system > seed: 42 > filePath() 1`] = `"/opt/bin/crowded_fail_woefully.dra"`;
 
 exports[`system > seed: 42 > fileType() 1`] = `"image"`;
 
@@ -260,7 +260,7 @@ exports[`system > seed: 42 > semver() 1`] = `"3.7.9"`;
 
 exports[`system > seed: 1211 > commonFileExt() 1`] = `"htm"`;
 
-exports[`system > seed: 1211 > commonFileName() 1`] = `"invoice_cyclocross_assault.mp4"`;
+exports[`system > seed: 1211 > commonFileName() 1`] = `"although_instantly_though.gif"`;
 
 exports[`system > seed: 1211 > commonFileType() 1`] = `"application"`;
 
@@ -270,9 +270,9 @@ exports[`system > seed: 1211 > directoryPath() 1`] = `"/var/log"`;
 
 exports[`system > seed: 1211 > fileExt() 1`] = `"dic"`;
 
-exports[`system > seed: 1211 > fileName() 1`] = `"invoice_cyclocross_assault.z2"`;
+exports[`system > seed: 1211 > fileName() 1`] = `"although_instantly_though.ustar"`;
 
-exports[`system > seed: 1211 > filePath() 1`] = `"/var/log/strictly_rustic.avi"`;
+exports[`system > seed: 1211 > filePath() 1`] = `"/var/log/outside_even.xhvml"`;
 
 exports[`system > seed: 1211 > fileType() 1`] = `"x-shader"`;
 
@@ -284,7 +284,7 @@ exports[`system > seed: 1211 > semver() 1`] = `"9.4.8"`;
 
 exports[`system > seed: 1337 > commonFileExt() 1`] = `"wav"`;
 
-exports[`system > seed: 1337 > commonFileName() 1`] = `"quia.mp2"`;
+exports[`system > seed: 1337 > commonFileName() 1`] = `"although.wav"`;
 
 exports[`system > seed: 1337 > commonFileType() 1`] = `"audio"`;
 
@@ -294,9 +294,9 @@ exports[`system > seed: 1337 > directoryPath() 1`] = `"/Library"`;
 
 exports[`system > seed: 1337 > fileExt() 1`] = `"oa3"`;
 
-exports[`system > seed: 1337 > fileName() 1`] = `"quia.cmc"`;
+exports[`system > seed: 1337 > fileName() 1`] = `"although.chrt"`;
 
-exports[`system > seed: 1337 > filePath() 1`] = `"/Library/duane_fort.wmlc"`;
+exports[`system > seed: 1337 > filePath() 1`] = `"/Library/yum_fast.aiff"`;
 
 exports[`system > seed: 1337 > fileType() 1`] = `"font"`;
 

test/__snapshots__/word.spec.ts.snap

@@ -72,6 +72,18 @@ exports[`word > 42 > preposition > with options.length and options.strategy 1`]
 
 exports[`word > 42 > preposition > with options.strategy 1`] = `"a"`;
 
+exports[`word > 42 > sample > noArgs 1`] = `"eek"`;
+
+exports[`word > 42 > sample > with length = 10 1`] = `"eek"`;
+
+exports[`word > 42 > sample > with length = 20 1`] = `"eek"`;
+
+exports[`word > 42 > sample > with options.length 1`] = `"eek"`;
+
+exports[`word > 42 > sample > with options.length and options.strategy 1`] = `"gadzooks"`;
+
+exports[`word > 42 > sample > with options.strategy 1`] = `"aw"`;
+
 exports[`word > 42 > verb > noArgs 1`] = `"function"`;
 
 exports[`word > 42 > verb > with length = 10 1`] = `"exasperate"`;
@@ -84,6 +96,10 @@ exports[`word > 42 > verb > with options.length and options.strategy 1`] = `"ins
 
 exports[`word > 42 > verb > with options.strategy 1`] = `"cc"`;
 
+exports[`word > 42 > words > noArgs 1`] = `"nonbeliever stub"`;
+
+exports[`word > 42 > words > with count = 10 1`] = `"eek loudly alibi abnormally aw great-grandmother nor without conjoin mind"`;
+
 exports[`word > 1211 > adjective > noArgs 1`] = `"vibrant"`;
 
 exports[`word > 1211 > adjective > with length = 10 1`] = `"unpleasant"`;
@@ -156,6 +172,18 @@ exports[`word > 1211 > preposition > with options.length and options.strategy 1`
 
 exports[`word > 1211 > preposition > with options.strategy 1`] = `"a"`;
 
+exports[`word > 1211 > sample > noArgs 1`] = `"youthfully"`;
+
+exports[`word > 1211 > sample > with length = 10 1`] = `"youthfully"`;
+
+exports[`word > 1211 > sample > with length = 20 1`] = `"youthfully"`;
+
+exports[`word > 1211 > sample > with options.length 1`] = `"youthfully"`;
+
+exports[`word > 1211 > sample > with options.length and options.strategy 1`] = `"enthusiastically"`;
+
+exports[`word > 1211 > sample > with options.strategy 1`] = `"too"`;
+
 exports[`word > 1211 > verb > noArgs 1`] = `"trick"`;
 
 exports[`word > 1211 > verb > with length = 10 1`] = `"trampoline"`;
@@ -168,6 +196,10 @@ exports[`word > 1211 > verb > with options.length and options.strategy 1`] = `"i
 
 exports[`word > 1211 > verb > with options.strategy 1`] = `"up"`;
 
+exports[`word > 1211 > words > noArgs 1`] = `"although instantly though"`;
+
+exports[`word > 1211 > words > with count = 10 1`] = `"youthfully woot speedily gracefully positively hurry aw content thin monster"`;
+
 exports[`word > 1337 > adjective > noArgs 1`] = `"fair"`;
 
 exports[`word > 1337 > adjective > with length = 10 1`] = `"enchanting"`;
@@ -240,6 +272,18 @@ exports[`word > 1337 > preposition > with options.length and options.strategy 1`
 
 exports[`word > 1337 > preposition > with options.strategy 1`] = `"a"`;
 
+exports[`word > 1337 > sample > noArgs 1`] = `"nor"`;
+
+exports[`word > 1337 > sample > with length = 10 1`] = `"nor"`;
+
+exports[`word > 1337 > sample > with length = 20 1`] = `"nor"`;
+
+exports[`word > 1337 > sample > with options.length 1`] = `"nor"`;
+
+exports[`word > 1337 > sample > with options.length and options.strategy 1`] = `"consequently"`;
+
+exports[`word > 1337 > sample > with options.strategy 1`] = `"if"`;
+
 exports[`word > 1337 > verb > noArgs 1`] = `"dispense"`;
 
 exports[`word > 1337 > verb > with length = 10 1`] = `"demoralize"`;
@@ -251,3 +295,7 @@ exports[`word > 1337 > verb > with options.length 1`] = `"demoralize"`;
 exports[`word > 1337 > verb > with options.length and options.strategy 1`] = `"compartmentalize"`;
 
 exports[`word > 1337 > verb > with options.strategy 1`] = `"be"`;
+
+exports[`word > 1337 > words > noArgs 1`] = `"although"`;
+
+exports[`word > 1337 > words > with count = 10 1`] = `"nor brr instead anenst intently hard larder team vacation repentant"`;

test/system.spec.ts

@@ -295,6 +295,7 @@ describe('system', () => {
 
       describe('mimeType()', () => {
         it('should return mime types', () => {
+          faker.system.mimeType(); // The first call returns bad data in the test suite
           const mimeType = faker.system.mimeType();
 
           expect(

test/word.spec.ts

@@ -18,7 +18,8 @@ describe('word', () => {
       'interjection',
       'noun',
       'preposition',
-      'verb'
+      'verb',
+      'sample'
     )((t) => {
       t.it('noArgs')
         .it('with length = 10', 10)
@@ -30,6 +31,9 @@ describe('word', () => {
           strategy: 'closest',
         });
     });
+    t.describe('words', (t) => {
+      t.it('noArgs').it('with count = 10', 10);
+    });
   });
 
   describe('filterWordListByLength', () => {