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

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

1 files changed, 62 insertions, 13 deletions

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]);
   }
 
   /**