feat: faker.helpers.maybe

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;
+  }
 }

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',