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

4 files changed, 257 insertions, 52 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,
 
diff --git a/test/__snapshots__/location.spec.ts.snap b/test/__snapshots__/location.spec.ts.snap
index 1d09415c..f41c9f70 100644
--- a/test/__snapshots__/location.spec.ts.snap
+++ b/test/__snapshots__/location.spec.ts.snap
@@ -4,9 +4,9 @@ exports[`location > 42 > buildingNumber 1`] = `"7917"`;
 
 exports[`location > 42 > cardinalDirection > noArgs 1`] = `"East"`;
 
-exports[`location > 42 > cardinalDirection > with boolean 1`] = `"East"`;
+exports[`location > 42 > cardinalDirection > with abbreviated option 1`] = `"E"`;
 
-exports[`location > 42 > cardinalDirection > with useAbbr option 1`] = `"E"`;
+exports[`location > 42 > cardinalDirection > with boolean 1`] = `"East"`;
 
 exports[`location > 42 > city 1`] = `"Port Valentine"`;
 
@@ -24,9 +24,9 @@ exports[`location > 42 > county 1`] = `"Berkshire"`;
 
 exports[`location > 42 > direction > noArgs 1`] = `"South"`;
 
-exports[`location > 42 > direction > with boolean 1`] = `"South"`;
+exports[`location > 42 > direction > with abbreviated option 1`] = `"S"`;
 
-exports[`location > 42 > direction > with useAbbr option 1`] = `"S"`;
+exports[`location > 42 > direction > with boolean 1`] = `"South"`;
 
 exports[`location > 42 > latitude > noArgs 1`] = `-22.5828`;
 
@@ -122,9 +122,9 @@ exports[`location > 42 > nearbyGPSCoordinate > with radius and isMetric 1`] = `
 
 exports[`location > 42 > ordinalDirection > noArgs 1`] = `"Northwest"`;
 
-exports[`location > 42 > ordinalDirection > with boolean 1`] = `"Northwest"`;
+exports[`location > 42 > ordinalDirection > with abbreviated option 1`] = `"NW"`;
 
-exports[`location > 42 > ordinalDirection > with useAbbr option 1`] = `"NW"`;
+exports[`location > 42 > ordinalDirection > with boolean 1`] = `"Northwest"`;
 
 exports[`location > 42 > secondaryAddress 1`] = `"Apt. 791"`;
 
@@ -156,9 +156,9 @@ exports[`location > 1211 > buildingNumber 1`] = `"487"`;
 
 exports[`location > 1211 > cardinalDirection > noArgs 1`] = `"West"`;
 
-exports[`location > 1211 > cardinalDirection > with boolean 1`] = `"West"`;
+exports[`location > 1211 > cardinalDirection > with abbreviated option 1`] = `"W"`;
 
-exports[`location > 1211 > cardinalDirection > with useAbbr option 1`] = `"W"`;
+exports[`location > 1211 > cardinalDirection > with boolean 1`] = `"West"`;
 
 exports[`location > 1211 > city 1`] = `"La Crosse"`;
 
@@ -176,9 +176,9 @@ exports[`location > 1211 > county 1`] = `"Cambridgeshire"`;
 
 exports[`location > 1211 > direction > noArgs 1`] = `"Southwest"`;
 
-exports[`location > 1211 > direction > with boolean 1`] = `"Southwest"`;
+exports[`location > 1211 > direction > with abbreviated option 1`] = `"SW"`;
 
-exports[`location > 1211 > direction > with useAbbr option 1`] = `"SW"`;
+exports[`location > 1211 > direction > with boolean 1`] = `"Southwest"`;
 
 exports[`location > 1211 > latitude > noArgs 1`] = `77.1337`;
 
@@ -274,9 +274,9 @@ exports[`location > 1211 > nearbyGPSCoordinate > with radius and isMetric 1`] =
 
 exports[`location > 1211 > ordinalDirection > noArgs 1`] = `"Southwest"`;
 
-exports[`location > 1211 > ordinalDirection > with boolean 1`] = `"Southwest"`;
+exports[`location > 1211 > ordinalDirection > with abbreviated option 1`] = `"SW"`;
 
-exports[`location > 1211 > ordinalDirection > with useAbbr option 1`] = `"SW"`;
+exports[`location > 1211 > ordinalDirection > with boolean 1`] = `"Southwest"`;
 
 exports[`location > 1211 > secondaryAddress 1`] = `"Suite 487"`;
 
@@ -308,9 +308,9 @@ exports[`location > 1337 > buildingNumber 1`] = `"51225"`;
 
 exports[`location > 1337 > cardinalDirection > noArgs 1`] = `"East"`;
 
-exports[`location > 1337 > cardinalDirection > with boolean 1`] = `"East"`;
+exports[`location > 1337 > cardinalDirection > with abbreviated option 1`] = `"E"`;
 
-exports[`location > 1337 > cardinalDirection > with useAbbr option 1`] = `"E"`;
+exports[`location > 1337 > cardinalDirection > with boolean 1`] = `"East"`;
 
 exports[`location > 1337 > city 1`] = `"New Carmella"`;
 
@@ -328,9 +328,9 @@ exports[`location > 1337 > county 1`] = `"Bedfordshire"`;
 
 exports[`location > 1337 > direction > noArgs 1`] = `"South"`;
 
-exports[`location > 1337 > direction > with boolean 1`] = `"South"`;
+exports[`location > 1337 > direction > with abbreviated option 1`] = `"S"`;
 
-exports[`location > 1337 > direction > with useAbbr option 1`] = `"S"`;
+exports[`location > 1337 > direction > with boolean 1`] = `"South"`;
 
 exports[`location > 1337 > latitude > noArgs 1`] = `-42.8356`;
 
@@ -426,9 +426,9 @@ exports[`location > 1337 > nearbyGPSCoordinate > with radius and isMetric 1`] =
 
 exports[`location > 1337 > ordinalDirection > noArgs 1`] = `"Northwest"`;
 
-exports[`location > 1337 > ordinalDirection > with boolean 1`] = `"Northwest"`;
+exports[`location > 1337 > ordinalDirection > with abbreviated option 1`] = `"NW"`;
 
-exports[`location > 1337 > ordinalDirection > with useAbbr option 1`] = `"NW"`;
+exports[`location > 1337 > ordinalDirection > with boolean 1`] = `"Northwest"`;
 
 exports[`location > 1337 > secondaryAddress 1`] = `"Apt. 512"`;
 
diff --git a/test/location.spec.ts b/test/location.spec.ts
index 69af0a6d..1835ab43 100644
--- a/test/location.spec.ts
+++ b/test/location.spec.ts
@@ -107,7 +107,7 @@ describe('location', () => {
     )((t) => {
       t.it('noArgs')
         .it('with boolean', false)
-        .it('with useAbbr option', { useAbbr: true });
+        .it('with abbreviated option', { abbreviated: true });
     });
 
     t.describe('zipCode', (t) => {
@@ -275,11 +275,11 @@ describe('location', () => {
       });
 
       describe('direction()', () => {
-        it('returns abbreviation when useAbbr is true', () => {
-          const direction = faker.location.direction({ useAbbr: true });
+        it('returns abbreviation when abbreviated is true', () => {
+          const direction = faker.location.direction({ abbreviated: true });
           const lengthDirection = direction.length;
           const prefixErrorMessage =
-            'The abbreviation of direction when useAbbr is true should';
+            'The abbreviation of direction when abbreviated is true should';
 
           expect(
             direction,
@@ -290,14 +290,14 @@ describe('location', () => {
       });
 
       describe('ordinalDirection()', () => {
-        it('returns abbreviation when useAbbr is true', () => {
+        it('returns abbreviation when abbreviated is true', () => {
           const ordinalDirection = faker.location.ordinalDirection({
-            useAbbr: true,
+            abbreviated: true,
           });
           const expectedType = 'string';
           const ordinalDirectionLength = ordinalDirection.length;
           const prefixErrorMessage =
-            'The ordinal direction when useAbbr is true should';
+            'The ordinal direction when abbreviated is true should';
 
           expect(
             ordinalDirection,
@@ -308,14 +308,14 @@ describe('location', () => {
       });
 
       describe('cardinalDirection()', () => {
-        it('returns abbreviation when useAbbr is true', () => {
+        it('returns abbreviation when abbreviated is true', () => {
           const cardinalDirection = faker.location.cardinalDirection({
-            useAbbr: true,
+            abbreviated: true,
           });
           const expectedType = 'string';
           const cardinalDirectionLength = cardinalDirection.length;
           const prefixErrorMessage =
-            'The cardinal direction when useAbbr is true should';
+            'The cardinal direction when abbreviated is true should';
 
           expect(
             cardinalDirection,