Merge branch 'main' into 321-improve-address-nearby-gps-coordinate

src/helpers.ts

@@ -691,4 +691,28 @@ export class Helpers {
       account: this.faker.finance.account(),
     };
   }
+
+  /**
+   * Returns the result of the callback if the probability check was successful, otherwise `undefined`.
+   *
+   * @template T The type of result of the given callback.
+   * @param callback The callback to that will be invoked if the probability check was successful.
+   * @param options The options to use. Defaults to `{}`.
+   * @param options.probability The probability (`[0.00, 1.00]`) of the callback being invoked. Defaults to `0.5`.
+   *
+   * @example
+   * faker.random.maybe(() => 'Hello World!') // 'Hello World!'
+   * faker.random.maybe(() => 'Hello World!', { probability: 0.1 }) // undefined
+   * faker.random.maybe(() => 'Hello World!', { probability: 0.9 }) // 'Hello World!'
+   */
+  maybe<T>(
+    callback: () => T,
+    options: { probability?: number } = {}
+  ): T | undefined {
+    const { probability = 0.5 } = options;
+    if (this.faker.datatype.float({ min: 0, max: 1 }) < probability) {
+      return callback();
+    }
+    return undefined;
+  }
 }

src/word.ts

@@ -1,5 +1,30 @@
 import type { Faker } from '.';
 
+/**
+ * Filters a string array for values with a specific length.
+ * If length is not provided or no values with this length there found a copy of the original array is returned.
+ *
+ * @param options The options to provide
+ * @param options.wordList A list of word to filter
+ * @param options.length The exact length words should have
+ */
+function filterWordListByLength(options: {
+  wordList: string[];
+  length?: number;
+}): string[] {
+  if (!options.length) {
+    return options.wordList;
+  }
+
+  const wordListWithLengthFilter = options.wordList.filter(
+    (word) => word.length === options.length
+  );
+
+  return wordListWithLengthFilter.length > 0
+    ? wordListWithLengthFilter
+    : [...options.wordList];
+}
+
 /**
  * Module to return various types of words.
  */
@@ -25,18 +50,11 @@ export class Word {
    * faker.word.adjective(100) // 'complete'
    */
   adjective(length?: number): string {
-    let wordList = this.faker.definitions.word.adjective;
-    if (length) {
-      wordList = this.faker.definitions.word.adjective.filter(
-        (word) => word.length === length
-      );
-    }
-
-    // If result of filtered word list is undefined, return an element
-    // from the unfiltered list.
-    return (
-      this.faker.random.arrayElement(wordList) ||
-      this.faker.random.arrayElement(this.faker.definitions.word.adjective)
+    return this.faker.random.arrayElement(
+      filterWordListByLength({
+        wordList: this.faker.definitions.word.adjective,
+        length,
+      })
     );
   }
 
@@ -51,18 +69,11 @@ export class Word {
    * faker.word.adverb(100) // 'sadly'
    */
   adverb(length?: number): string {
-    let wordList = this.faker.definitions.word.adverb;
-    if (length) {
-      wordList = this.faker.definitions.word.adverb.filter(
-        (word: string) => word.length === length
-      );
-    }
-
-    // If result of filtered word list is undefined, return an element
-    // from the unfiltered list.
-    return (
-      this.faker.random.arrayElement(wordList) ||
-      this.faker.random.arrayElement(this.faker.definitions.word.adverb)
+    return this.faker.random.arrayElement(
+      filterWordListByLength({
+        wordList: this.faker.definitions.word.adverb,
+        length,
+      })
     );
   }
 
@@ -77,18 +88,11 @@ export class Word {
    * faker.word.conjunction(100) // 'as long as'
    */
   conjunction(length?: number): string {
-    let wordList = this.faker.definitions.word.conjunction;
-    if (length) {
-      wordList = this.faker.definitions.word.conjunction.filter(
-        (word: string) => word.length === length
-      );
-    }
-
-    // If result of filtered word list is undefined, return an element
-    // from the unfiltered list.
-    return (
-      this.faker.random.arrayElement(wordList) ||
-      this.faker.random.arrayElement(this.faker.definitions.word.conjunction)
+    return this.faker.random.arrayElement(
+      filterWordListByLength({
+        wordList: this.faker.definitions.word.conjunction,
+        length,
+      })
     );
   }
 
@@ -103,18 +107,11 @@ export class Word {
    * faker.word.interjection(100) // 'yowza'
    */
   interjection(length?: number): string {
-    let wordList = this.faker.definitions.word.interjection;
-    if (length) {
-      wordList = this.faker.definitions.word.interjection.filter(
-        (word: string) => word.length === length
-      );
-    }
-
-    // If result of filtered word list is undefined, return an element
-    // from the unfiltered list.
-    return (
-      this.faker.random.arrayElement(wordList) ||
-      this.faker.random.arrayElement(this.faker.definitions.word.interjection)
+    return this.faker.random.arrayElement(
+      filterWordListByLength({
+        wordList: this.faker.definitions.word.interjection,
+        length,
+      })
     );
   }
 
@@ -129,18 +126,11 @@ export class Word {
    * faker.word.noun(100) // 'care'
    */
   noun(length?: number): string {
-    let wordList = this.faker.definitions.word.noun;
-    if (length) {
-      wordList = this.faker.definitions.word.noun.filter(
-        (word: string) => word.length === length
-      );
-    }
-
-    // If result of filtered word list is undefined, return an element
-    // from the unfiltered list.
-    return (
-      this.faker.random.arrayElement(wordList) ||
-      this.faker.random.arrayElement(this.faker.definitions.word.noun)
+    return this.faker.random.arrayElement(
+      filterWordListByLength({
+        wordList: this.faker.definitions.word.noun,
+        length,
+      })
     );
   }
 
@@ -155,18 +145,11 @@ export class Word {
    * faker.word.preposition(100) // 'an'
    */
   preposition(length?: number): string {
-    let wordList = this.faker.definitions.word.preposition;
-    if (length) {
-      wordList = this.faker.definitions.word.preposition.filter(
-        (word: string) => word.length === length
-      );
-    }
-
-    // If result of filtered word list is undefined, return an element
-    // from the unfiltered list.
-    return (
-      this.faker.random.arrayElement(wordList) ||
-      this.faker.random.arrayElement(this.faker.definitions.word.preposition)
+    return this.faker.random.arrayElement(
+      filterWordListByLength({
+        wordList: this.faker.definitions.word.preposition,
+        length,
+      })
     );
   }
 
@@ -181,18 +164,11 @@ export class Word {
    * faker.word.verb(100) // 'mess'
    */
   verb(length?: number): string {
-    let wordList = this.faker.definitions.word.verb;
-    if (length) {
-      wordList = this.faker.definitions.word.verb.filter(
-        (word: string) => word.length === length
-      );
-    }
-
-    // If result of filtered word list is undefined, return an element
-    // from the unfiltered list.
-    return (
-      this.faker.random.arrayElement(wordList) ||
-      this.faker.random.arrayElement(this.faker.definitions.word.verb)
+    return this.faker.random.arrayElement(
+      filterWordListByLength({
+        wordList: this.faker.definitions.word.verb,
+        length,
+      })
     );
   }
 }

test/helpers.spec.ts

@@ -786,6 +786,7 @@ describe('helpers', () => {
           expect(card).toBeTypeOf('object');
         });
       });
+
       describe('userCard()', () => {
         it('returns an object', () => {
           const card = faker.helpers.userCard();
@@ -806,6 +807,30 @@ describe('helpers', () => {
         });
       });
 
+      describe('maybe', () => {
+        it('should always return the callback result when probability is 1', () => {
+          const actual = faker.helpers.maybe(() => 'foo', { probability: 1 });
+
+          expect(actual).toBe('foo');
+        });
+
+        it('should never return the callback result when probability is 0', () => {
+          const actual = faker.helpers.maybe(() => expect.fail(), {
+            probability: 0,
+          });
+
+          expect(actual).toBeUndefined();
+        });
+
+        it('should not mutate the input object', () => {
+          const input = Object.freeze({
+            probability: 0.4,
+          });
+
+          expect(() => faker.helpers.maybe(() => 'foo', input)).not.toThrow();
+        });
+      });
+
       describe('deprecation warnings', () => {
         it.each([['randomize', 'random.arrayElement']])(
           'should warn user that function helpers.%s is deprecated',
@@ -823,6 +848,7 @@ describe('helpers', () => {
       });
     }
   });
+
   describe('deprecation warnings', () => {
     it.each(['createCard', 'contextualCard', 'userCard'])(
       'should warn user that function random.%s is deprecated',