feat: separate methods for object key value (#503)

Co-authored-by: Leyla Jähnig <[email protected]>
Co-authored-by: Shinigami92 <[email protected]>

5 files changed, 139 insertions, 24 deletions

diff --git a/src/finance.ts b/src/finance.ts
index 2214088d..1ff24eca 100644
--- a/src/finance.ts
+++ b/src/finance.ts
@@ -171,7 +171,7 @@ export class Finance {
    * faker.finance.currencyCode() // 'USD'
    */
   currencyCode(): string {
-    return this.faker.random.objectElement(
+    return this.faker.helpers.objectValue(
       this.faker.definitions.finance.currency
     )['code'];
   }
@@ -183,10 +183,9 @@ export class Finance {
    * faker.finance.currencyName() // 'US Dollar'
    */
   currencyName(): string {
-    return this.faker.random.objectElement(
-      this.faker.definitions.finance.currency,
-      'key'
-    );
+    return this.faker.helpers.objectKey(
+      this.faker.definitions.finance.currency
+    ) as string;
   }
 
   /**
@@ -198,7 +197,7 @@ export class Finance {
   currencySymbol(): string {
     let symbol: string;
     while (!symbol) {
-      symbol = this.faker.random.objectElement(
+      symbol = this.faker.helpers.objectValue(
         this.faker.definitions.finance.currency
       )['symbol'];
     }
@@ -265,7 +264,7 @@ export class Finance {
     } else {
       // Choose a random provider
       // Credit cards are in an object structure
-      const formats = this.faker.random.objectElement(localeFormat, 'value'); // There could be multiple formats
+      const formats = this.faker.helpers.objectValue(localeFormat); // There could be multiple formats
       format = this.faker.random.arrayElement(formats);
     }
     format = format.replace(/\//g, '');
diff --git a/src/helpers.ts b/src/helpers.ts
index 5ca332d4..a04c5779 100644
--- a/src/helpers.ts
+++ b/src/helpers.ts
@@ -112,7 +112,8 @@ export interface Transaction {
 }
 
 /**
- * Module with various helper methods that don't fit in a particular category.
+ * Module with various helper methods that transform the method input rather than returning values from locales.
+ * The transformation process may call methods that use the locale data.
  */
 export class Helpers {
   constructor(private readonly faker: Faker) {
@@ -701,9 +702,9 @@ export class Helpers {
    * @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!'
+   * faker.helpers.maybe(() => 'Hello World!') // 'Hello World!'
+   * faker.helpers.maybe(() => 'Hello World!', { probability: 0.1 }) // undefined
+   * faker.helpers.maybe(() => 'Hello World!', { probability: 0.9 }) // 'Hello World!'
    */
   maybe<T>(
     callback: () => T,
@@ -715,4 +716,30 @@ export class Helpers {
     }
     return undefined;
   }
+
+  /**
+   * Returns a random key from given object.
+   *
+   * @param object The object to be used.
+   *
+   * @example
+   * faker.helpers.objectKey({ myProperty: 'myValue' }) // 'myProperty'
+   */
+  objectKey<T extends Record<string, unknown>>(object: T): keyof T {
+    const array: Array<keyof T> = Object.keys(object);
+    return this.faker.random.arrayElement(array);
+  }
+
+  /**
+   * Returns a random value from given object.
+   *
+   * @param object The object to be used.
+   *
+   * @example
+   * faker.helpers.objectValue({ myProperty: 'myValue' }) // 'myValue'
+   */
+  objectValue<T extends Record<string, unknown>>(object: T): T[keyof T] {
+    const key = this.faker.helpers.objectKey(object);
+    return object[key];
+  }
 }
diff --git a/src/random.ts b/src/random.ts
index c349c92f..2b90db07 100644
--- a/src/random.ts
+++ b/src/random.ts
@@ -161,25 +161,42 @@ export class Random {
   }
 
   /**
-   * Returns a random key or value from given object.
+   * Returns a random key from given object.
    *
    * @template T The type of `Record` to pick from.
    * @template K The keys of `T`.
-   * @param object The object to get the keys or values from.
+   * @param object The object to get the keys from.
    * @param field If this is set to `'key'`, this method will a return a random key of the given instance.
-   * If this is set to `'value'`, this method will a return a random value of the given instance.
-   * Defaults to `'value'`.
+   *
+   * @see faker.helpers.objectKey()
    *
    * @example
    * const object = { keyA: 'valueA', keyB: 42 };
-   * faker.random.objectElement(object) // 42
    * faker.random.objectElement(object, 'key') // 'keyB'
-   * faker.random.objectElement(object, 'value') // 'valueA'
+   *
+   * @deprecated
    */
   objectElement<T extends Record<string, unknown>, K extends keyof T>(
     object: T,
     field: 'key'
   ): K;
+  /**
+   * Returns a random value from given object.
+   *
+   * @template T The type of `Record` to pick from.
+   * @template K The keys of `T`.
+   * @param object The object to get the values from.
+   * @param field If this is set to `'value'`, this method will a return a random value of the given instance.
+   *
+   * @see faker.helpers.objectValue()
+   *
+   * @example
+   * const object = { keyA: 'valueA', keyB: 42 };
+   * faker.random.objectElement(object) // 42
+   * faker.random.objectElement(object, 'value') // 'valueA'
+   *
+   * @deprecated
+   */
   objectElement<T extends Record<string, unknown>, K extends keyof T>(
     object: T,
     field?: unknown
@@ -194,24 +211,56 @@ export class Random {
    * If this is set to `'value'`, this method will a return a random value of the given instance.
    * Defaults to `'value'`.
    *
+   * @see faker.helpers.objectKey()
+   * @see faker.helpers.objectValue()
+   *
    * @example
    * const object = { keyA: 'valueA', keyB: 42 };
    * faker.random.objectElement(object) // 42
    * faker.random.objectElement(object, 'key') // 'keyB'
    * faker.random.objectElement(object, 'value') // 'valueA'
+   *
+   * @deprecated
    */
   objectElement<T extends Record<string, unknown>, K extends keyof T>(
-    object: T,
+    object?: T,
     field?: 'key' | 'value'
   ): K | T[K];
+  /**
+   * Returns a random key or value from given object.
+   *
+   * @template T The type of `Record` to pick from.
+   * @template K The keys of `T`.
+   * @param object The object to get the keys or values from.
+   * @param field If this is set to `'key'`, this method will a return a random key of the given instance.
+   * If this is set to `'value'`, this method will a return a random value of the given instance.
+   * Defaults to `'value'`.
+   *
+   * @see faker.helpers.objectKey()
+   * @see faker.helpers.objectValue()
+   *
+   * @example
+   * const object = { keyA: 'valueA', keyB: 42 };
+   * faker.random.objectElement(object) // 42
+   * faker.random.objectElement(object, 'key') // 'keyB'
+   * faker.random.objectElement(object, 'value') // 'valueA'
+   *
+   * @deprecated
+   */
   objectElement<T extends Record<string, unknown>, K extends keyof T>(
-    object = { foo: 'bar', too: 'car' } as unknown as T,
-    field = 'value'
+    object: T = { foo: 'bar', too: 'car' } as unknown as T,
+    field: 'key' | 'value' = 'value'
   ): K | T[K] {
-    const array: Array<keyof T> = Object.keys(object);
-    const key = this.arrayElement(array);
-
-    return field === 'key' ? (key as K) : (object[key] as T[K]);
+    const useKey = field === 'key';
+    deprecated({
+      deprecated: `faker.random.objectElement(${useKey ? "obj, 'key'" : ''})`,
+      proposed: `faker.helpers.object${useKey ? 'Key' : 'Value'}()`,
+      since: 'v6.3.0',
+      until: 'v7.0.0',
+    });
+    return field === 'key'
+      ? (this.faker.helpers.objectKey(object) as K)
+      : (this.faker.helpers.objectValue(object) as T[K]);
   }
 
   /**
diff --git a/test/helpers.spec.ts b/test/helpers.spec.ts
index 5ee4b2a7..3f63a807 100644
--- a/test/helpers.spec.ts
+++ b/test/helpers.spec.ts
@@ -831,6 +831,32 @@ describe('helpers', () => {
         });
       });
 
+      describe('objectKey', () => {
+        it('should return a random key', () => {
+          const testObject = {
+            hello: 'to',
+            you: 'my',
+            friend: '!',
+          };
+          const actual = faker.helpers.objectKey(testObject);
+
+          expect(Object.keys(testObject)).toContain(actual);
+        });
+      });
+
+      describe('objectValue', () => {
+        it('should return a random value', () => {
+          const testObject = {
+            hello: 'to',
+            you: 'my',
+            friend: '!',
+          };
+          const actual = faker.helpers.objectValue(testObject);
+
+          expect(Object.values(testObject)).toContain(actual);
+        });
+      });
+
       describe('deprecation warnings', () => {
         it.each([['randomize', 'random.arrayElement']])(
           'should warn user that function helpers.%s is deprecated',
diff --git a/test/random.spec.ts b/test/random.spec.ts
index f3a47d87..a3c93562 100644
--- a/test/random.spec.ts
+++ b/test/random.spec.ts
@@ -159,6 +159,8 @@ describe('random', () => {
 
       describe('objectElement', () => {
         it('should return a random value', () => {
+          const spy = vi.spyOn(console, 'warn');
+
           const testObject = {
             hello: 'to',
             you: 'my',
@@ -167,9 +169,16 @@ describe('random', () => {
           const actual = faker.random.objectElement(testObject);
 
           expect(Object.values(testObject)).toContain(actual);
+          expect(spy).toHaveBeenCalledWith(
+            `[@faker-js/faker]: faker.random.objectElement() is deprecated since v6.3.0 and will be removed in v7.0.0. Please use faker.helpers.objectValue() instead.`
+          );
+
+          spy.mockRestore();
         });
 
         it('should return a random key', () => {
+          const spy = vi.spyOn(console, 'warn');
+
           const testObject = {
             hello: 'to',
             you: 'my',
@@ -178,6 +187,11 @@ describe('random', () => {
           const actual = faker.random.objectElement(testObject, 'key');
 
           expect(Object.keys(testObject)).toContain(actual);
+          expect(spy).toHaveBeenCalledWith(
+            `[@faker-js/faker]: faker.random.objectElement(obj, 'key') is deprecated since v6.3.0 and will be removed in v7.0.0. Please use faker.helpers.objectKey() instead.`
+          );
+
+          spy.mockRestore();
         });
       });