chore(location): standardize abbreviated parameter (#2061)

2 files changed, 229 insertions, 24 deletions

diff --git a/src/modules/location/index.ts b/src/modules/location/index.ts
index 07097960..4931d46f 100644
--- a/src/modules/location/index.ts
+++ b/src/modules/location/index.ts
@@ -676,15 +676,77 @@ export class LocationModule {
   /**
    * Returns a random direction (cardinal and ordinal; northwest, east, etc).
    *
-   * @param options Whether to use abbreviated or an options object.
-   * @param options.useAbbr If true this will return abbreviated directions (NW, E, etc).
+   * @param options The options to use. Defaults to `{}`.
+   * @param options.abbreviated If true this will return abbreviated directions (NW, E, etc).
+   * Otherwise this will return the long name. Defaults to `false`.
+   *
+   * @example
+   * faker.location.direction() // 'Northeast'
+   * faker.location.direction({ abbreviated: true }) // 'SW'
+   *
+   * @since 8.0.0
+   */
+  direction(options?: {
+    /**
+     * If true this will return abbreviated directions (NW, E, etc).
+     * Otherwise this will return the long name.
+     *
+     * @default false
+     */
+    abbreviated?: boolean;
+  }): string;
+  /**
+   * Returns a random direction (cardinal and ordinal; northwest, east, etc).
+   *
+   * @param abbreviated If true this will return abbreviated directions (NW, E, etc).
    * Otherwise this will return the long name. Defaults to `false`.
    *
    * @example
    * faker.location.direction() // 'Northeast'
    * faker.location.direction(false) // 'South'
    * faker.location.direction(true) // 'NE'
-   * faker.location.direction({ useAbbr: true }) // 'SW'
+   *
+   * @since 8.0.0
+   *
+   * @deprecated Use `faker.location.direction({ abbreviated })` instead.
+   */
+  direction(abbreviated?: boolean): string;
+  /**
+   * Returns a random direction (cardinal and ordinal; northwest, east, etc).
+   *
+   * @param options Whether to use abbreviated or an options object. Defaults to `{}`.
+   * @param options.abbreviated If true this will return abbreviated directions (NW, E, etc).
+   * Otherwise this will return the long name. Defaults to `false`.
+   *
+   * @example
+   * faker.location.direction() // 'Northeast'
+   * faker.location.direction({ abbreviated: true }) // 'SW'
+   *
+   * @since 8.0.0
+   */
+  direction(
+    options?:
+      | boolean
+      | {
+          /**
+           * If true this will return abbreviated directions (NW, E, etc).
+           * Otherwise this will return the long name.
+           *
+           * @default false
+           */
+          abbreviated?: boolean;
+        }
+  ): string;
+  /**
+   * Returns a random direction (cardinal and ordinal; northwest, east, etc).
+   *
+   * @param options Whether to use abbreviated or an options object. Defaults to `{}`.
+   * @param options.abbreviated If true this will return abbreviated directions (NW, E, etc).
+   * Otherwise this will return the long name. Defaults to `false`.
+   *
+   * @example
+   * faker.location.direction() // 'Northeast'
+   * faker.location.direction({ abbreviated: true }) // 'SW'
    *
    * @since 8.0.0
    */
@@ -698,16 +760,22 @@ export class LocationModule {
            *
            * @default false
            */
-          useAbbr?: boolean;
+          abbreviated?: boolean;
         } = {}
   ): string {
     if (typeof options === 'boolean') {
-      options = { useAbbr: options };
+      deprecated({
+        deprecated: 'faker.location.direction(abbreviated)',
+        proposed: 'faker.location.direction({ abbreviated })',
+        since: '8.0',
+        until: '9.0',
+      });
+      options = { abbreviated: options };
     }
 
-    const { useAbbr = false } = options;
+    const { abbreviated = false } = options;
 
-    if (!useAbbr) {
+    if (!abbreviated) {
       return this.faker.helpers.arrayElement(
         this.faker.definitions.location.direction
       );
@@ -721,15 +789,77 @@ export class LocationModule {
   /**
    * Returns a random cardinal direction (north, east, south, west).
    *
-   * @param options Whether to use abbreviated or an options object.
-   * @param options.useAbbr If true this will return abbreviated directions (N, E, etc).
+   * @param options The options to use. Defaults to `{}`.
+   * @param options.abbreviated If true this will return abbreviated directions (N, E, etc).
+   * Otherwise this will return the long name. Defaults to `false`.
+   *
+   * @example
+   * faker.location.cardinalDirection() // 'North'
+   * faker.location.cardinalDirection({ abbreviated: true }) // 'W'
+   *
+   * @since 8.0.0
+   */
+  cardinalDirection(options?: {
+    /**
+     * If true this will return abbreviated directions (N, E, etc).
+     * Otherwise this will return the long name.
+     *
+     * @default false
+     */
+    abbreviated?: boolean;
+  }): string;
+  /**
+   * Returns a random cardinal direction (north, east, south, west).
+   *
+   * @param abbreviated If true this will return abbreviated directions (N, E, etc).
    * Otherwise this will return the long name. Defaults to `false`.
    *
    * @example
    * faker.location.cardinalDirection() // 'North'
    * faker.location.cardinalDirection(false) // 'South'
    * faker.location.cardinalDirection(true) // 'N'
-   * faker.location.cardinalDirection({ useAbbr: true }) // 'W'
+   *
+   * @since 8.0.0
+   *
+   * @deprecated Use `faker.location.cardinalDirection({ abbreviated })` instead.
+   */
+  cardinalDirection(abbreviated?: boolean): string;
+  /**
+   * Returns a random cardinal direction (north, east, south, west).
+   *
+   * @param options Whether to use abbreviated or an options object. Defaults to`{}`.
+   * @param options.abbreviated If true this will return abbreviated directions (N, E, etc).
+   * Otherwise this will return the long name. Defaults to `false`.
+   *
+   * @example
+   * faker.location.cardinalDirection() // 'North'
+   * faker.location.cardinalDirection({ abbreviated: true }) // 'W'
+   *
+   * @since 8.0.0
+   */
+  cardinalDirection(
+    options?:
+      | boolean
+      | {
+          /**
+           * If true this will return abbreviated directions (N, E, etc).
+           * Otherwise this will return the long name.
+           *
+           * @default false
+           */
+          abbreviated?: boolean;
+        }
+  ): string;
+  /**
+   * Returns a random cardinal direction (north, east, south, west).
+   *
+   * @param options Whether to use abbreviated or an options object. Defaults to `{}`.
+   * @param options.abbreviated If true this will return abbreviated directions (N, E, etc).
+   * Otherwise this will return the long name. Defaults to `false`.
+   *
+   * @example
+   * faker.location.cardinalDirection() // 'North'
+   * faker.location.cardinalDirection({ abbreviated: true }) // 'W'
    *
    * @since 8.0.0
    */
@@ -743,15 +873,21 @@ export class LocationModule {
            *
            * @default false
            */
-          useAbbr?: boolean;
+          abbreviated?: boolean;
         } = {}
   ): string {
     if (typeof options === 'boolean') {
-      options = { useAbbr: options };
+      deprecated({
+        deprecated: 'faker.location.cardinalDirection(abbreviated)',
+        proposed: 'faker.location.cardinalDirection({ abbreviated })',
+        since: '8.0',
+        until: '9.0',
+      });
+      options = { abbreviated: options };
     }
 
-    const { useAbbr = false } = options;
-    if (!useAbbr) {
+    const { abbreviated = false } = options;
+    if (!abbreviated) {
       return this.faker.helpers.arrayElement(
         this.faker.definitions.location.direction.slice(0, 4)
       );
@@ -765,15 +901,78 @@ export class LocationModule {
   /**
    * Returns a random ordinal direction (northwest, southeast, etc).
    *
-   * @param options Whether to use abbreviated or an options object.
-   * @param options.useAbbr If true this will return abbreviated directions (NW, SE, etc).
+   * @param options Whether to use abbreviated or an options object. Defaults to `{}`.
+   * @param options.abbreviated If true this will return abbreviated directions (NW, SE, etc).
+   * Otherwise this will return the long name. Defaults to `false`.
+   *
+   * @example
+   * faker.location.ordinalDirection() // 'Northeast'
+   * faker.location.ordinalDirection({ abbreviated: true }) // 'SW'
+   *
+   * @since 8.0.0
+   */
+  ordinalDirection(options?: {
+    /**
+     * If true this will return abbreviated directions (NW, SE, etc).
+     * Otherwise this will return the long name.
+     *
+     * @default false
+     */
+    abbreviated?: boolean;
+  }): string;
+  /**
+   * Returns a random ordinal direction (northwest, southeast, etc).
+   *
+   * @param options Whether to use abbreviated or an options object. Defaults to `{}`.
+   * @param options.abbreviated If true this will return abbreviated directions (NW, SE, etc).
    * Otherwise this will return the long name. Defaults to `false`.
    *
    * @example
    * faker.location.ordinalDirection() // 'Northeast'
    * faker.location.ordinalDirection(false) // 'Northwest'
    * faker.location.ordinalDirection(true) // 'NE'
-   * faker.location.ordinalDirection({ useAbbr: true }) // 'SW'
+   *
+   * @since 8.0.0
+   *
+   * @deprecated Use `faker.location.ordinalDirection({ abbreviated })` instead.
+   */
+  ordinalDirection(abbreviated?: boolean): string;
+  /**
+   * Returns a random ordinal direction (northwest, southeast, etc).
+   *
+   * @param options Whether to use abbreviated or an options object. Defaults to `{}`.
+   * @param options.abbreviated If true this will return abbreviated directions (NW, SE, etc).
+   * Otherwise this will return the long name. Defaults to `false`.
+   *
+   * @example
+   * faker.location.ordinalDirection() // 'Northeast'
+   * faker.location.ordinalDirection({ abbreviated: true }) // 'SW'
+   *
+   * @since 8.0.0
+   */
+  ordinalDirection(
+    options?:
+      | boolean
+      | {
+          /**
+           * If true this will return abbreviated directions (NW, SE, etc).
+           * Otherwise this will return the long name.
+           *
+           * @default false
+           */
+          abbreviated?: boolean;
+        }
+  ): string;
+  /**
+   * Returns a random ordinal direction (northwest, southeast, etc).
+   *
+   * @param options Whether to use abbreviated or an options object. Defaults to `{}`.
+   * @param options.abbreviated If true this will return abbreviated directions (NW, SE, etc).
+   * Otherwise this will return the long name. Defaults to `false`.
+   *
+   * @example
+   * faker.location.ordinalDirection() // 'Northeast'
+   * faker.location.ordinalDirection({ abbreviated: true }) // 'SW'
    *
    * @since 8.0.0
    */
@@ -787,15 +986,21 @@ export class LocationModule {
            *
            * @default false
            */
-          useAbbr?: boolean;
+          abbreviated?: boolean;
         } = {}
   ): string {
     if (typeof options === 'boolean') {
-      options = { useAbbr: options };
+      deprecated({
+        deprecated: 'faker.location.ordinalDirection(abbreviated)',
+        proposed: 'faker.location.ordinalDirection({ abbreviated })',
+        since: '8.0',
+        until: '9.0',
+      });
+      options = { abbreviated: options };
     }
 
-    const { useAbbr = false } = options;
-    if (!useAbbr) {
+    const { abbreviated = false } = options;
+    if (!abbreviated) {
       return this.faker.helpers.arrayElement(
         this.faker.definitions.location.direction.slice(4, 8)
       );
diff --git a/src/modules/random/index.ts b/src/modules/random/index.ts
index 2a44b0e2..03f126f8 100644
--- a/src/modules/random/index.ts
+++ b/src/modules/random/index.ts
@@ -52,12 +52,12 @@ export class RandomModule {
     });
 
     const wordMethods = [
-      this.faker.location.cardinalDirection,
+      () => this.faker.location.cardinalDirection(),
       this.faker.location.cityName,
       this.faker.location.country,
       this.faker.location.county,
-      this.faker.location.direction,
-      this.faker.location.ordinalDirection,
+      () => this.faker.location.direction(),
+      () => this.faker.location.ordinalDirection(),
       this.faker.location.state,
       this.faker.location.street,