feat(helpers): new method `objectEntry` (#2123)

3 files changed, 73 insertions, 2 deletions

diff --git a/src/modules/helpers/index.ts b/src/modules/helpers/index.ts
index ba7e083a..e6cf9075 100644
--- a/src/modules/helpers/index.ts
+++ b/src/modules/helpers/index.ts
@@ -764,12 +764,14 @@ export class HelpersModule {
   }
 
   /**
-   * Returns a random key from given object or `undefined` if no key could be found.
+   * Returns a random key from given object.
    *
    * @template T The type of the object to select from.
    *
    * @param object The object to be used.
    *
+   * @throws If the given object is empty.
+   *
    * @example
    * faker.helpers.objectKey({ myProperty: 'myValue' }) // 'myProperty'
    *
@@ -781,12 +783,14 @@ export class HelpersModule {
   }
 
   /**
-   * Returns a random value from given object or `undefined` if no key could be found.
+   * Returns a random value from given object.
    *
    * @template T The type of object to select from.
    *
    * @param object The object to be used.
    *
+   * @throws If the given object is empty.
+   *
    * @example
    * faker.helpers.objectValue({ myProperty: 'myValue' }) // 'myValue'
    *
@@ -798,6 +802,27 @@ export class HelpersModule {
   }
 
   /**
+   * Returns a random `[key, value]` pair from the given object.
+   *
+   * @template T The type of the object to select from.
+   *
+   * @param object The object to be used.
+   *
+   * @throws If the given object is empty.
+   *
+   * @example
+   * faker.helpers.objectEntry({ prop1: 'value1', prop2: 'value2' }) // ['prop1', 'value1']
+   *
+   * @since 8.0.0
+   */
+  objectEntry<T extends Record<string, unknown>>(
+    object: T
+  ): [keyof T, T[keyof T]] {
+    const key = this.faker.helpers.objectKey(object);
+    return [key, object[key]];
+  }
+
+  /**
    * Returns random element from the given array.
    *
    * @template T The type of the elements to pick from.
diff --git a/test/__snapshots__/helpers.spec.ts.snap b/test/__snapshots__/helpers.spec.ts.snap
index 64562da7..04af3ac0 100644
--- a/test/__snapshots__/helpers.spec.ts.snap
+++ b/test/__snapshots__/helpers.spec.ts.snap
@@ -110,6 +110,13 @@ exports[`helpers > 42 > mustache > template with method 1`] = `"Hello John!"`;
 
 exports[`helpers > 42 > mustache > template with string 1`] = `"Hello John!"`;
 
+exports[`helpers > 42 > objectEntry > simple 1`] = `
+[
+  "b",
+  2,
+]
+`;
+
 exports[`helpers > 42 > objectKey > simple 1`] = `"b"`;
 
 exports[`helpers > 42 > objectValue > simple 1`] = `2`;
@@ -343,6 +350,13 @@ exports[`helpers > 1211 > mustache > template with method 1`] = `"Hello John!"`;
 
 exports[`helpers > 1211 > mustache > template with string 1`] = `"Hello John!"`;
 
+exports[`helpers > 1211 > objectEntry > simple 1`] = `
+[
+  "c",
+  3,
+]
+`;
+
 exports[`helpers > 1211 > objectKey > simple 1`] = `"c"`;
 
 exports[`helpers > 1211 > objectValue > simple 1`] = `3`;
@@ -558,6 +572,13 @@ exports[`helpers > 1337 > mustache > template with method 1`] = `"Hello John!"`;
 
 exports[`helpers > 1337 > mustache > template with string 1`] = `"Hello John!"`;
 
+exports[`helpers > 1337 > objectEntry > simple 1`] = `
+[
+  "a",
+  1,
+]
+`;
+
 exports[`helpers > 1337 > objectKey > simple 1`] = `"a"`;
 
 exports[`helpers > 1337 > objectValue > simple 1`] = `1`;
diff --git a/test/helpers.spec.ts b/test/helpers.spec.ts
index 6cb397cb..437a3284 100644
--- a/test/helpers.spec.ts
+++ b/test/helpers.spec.ts
@@ -157,6 +157,10 @@ describe('helpers', () => {
       t.it('simple', { a: 1, b: 2, c: 3 });
     });
 
+    t.describe('objectEntry', (t) => {
+      t.it('simple', { a: 1, b: 2, c: 3 });
+    });
+
     t.describe('fake', (t) => {
       t.it('with empty string', '')
         .it('with a static template', 'my test string')
@@ -935,6 +939,27 @@ describe('helpers', () => {
         });
       });
 
+      describe('objectEntry', () => {
+        it('should return a random key, value pair', () => {
+          const testObject = {
+            hello: 'to',
+            you: 'my',
+            friend: '!',
+          };
+          const [key, value] = faker.helpers.objectEntry(testObject);
+
+          expect(Object.keys(testObject)).toContain(key);
+          expect(Object.values(testObject)).toContain(value);
+          expect(testObject[key]).toEqual(value);
+        });
+
+        it('should throw if given object is empty', () => {
+          expect(() => faker.helpers.objectEntry({})).toThrowError(
+            new FakerError('Cannot get value from empty dataset.')
+          );
+        });
+      });
+
       describe('fake()', () => {
         it('does allow empty string input', () => {
           const actual = faker.helpers.fake('');