refactor(location): normalize signatures (#1784)

1 files changed, 429 insertions, 35 deletions

diff --git a/src/modules/location/index.ts b/src/modules/location/index.ts
index ab472658..5fe542cb 100644
--- a/src/modules/location/index.ts
+++ b/src/modules/location/index.ts
@@ -20,7 +20,8 @@ export class LocationModule {
    * Generates random zip code from specified format. If format is not specified,
    * the locale's zip format is used.
    *
-   * @param format The optional format used to generate the the zip code.
+   * @param options The format used to generate the the zip code or an options object. Defaults to `{}`.
+   * @param options.format The optional format used to generate the the zip code.
    * By default, a random format is used from the locale zip formats.
    *
    * @see faker.helpers.replaceSymbols()
@@ -31,28 +32,42 @@ export class LocationModule {
    *
    * @since 8.0.0
    */
-  zipCode(format?: string): string {
-    // if zip format is not specified, use the zip format defined for the locale
-    if (format == null) {
-      const localeFormat = this.faker.definitions.location.postcode;
-      if (typeof localeFormat === 'string') {
-        format = localeFormat;
-      } else {
-        format = this.faker.helpers.arrayElement(localeFormat);
-      }
+  zipCode(
+    options:
+      | string
+      | {
+          /**
+           * The optional format used to generate the the zip code.
+           *
+           * @default faker.definitions.location.postcode
+           */
+          format?: string;
+        } = {}
+  ): string {
+    if (typeof options === 'string') {
+      options = { format: options };
+    }
+
+    let { format = this.faker.definitions.location.postcode } = options;
+    if (typeof format === 'string') {
+      format = [format];
     }
 
+    format = this.faker.helpers.arrayElement(format);
+
     return this.faker.helpers.replaceSymbols(format);
   }
 
   /**
-   * Generates random zip code from state abbreviation. If state abbreviation is
-   * not specified, a random zip code is generated according to the locale's zip format.
+   * Generates random zip code from state abbreviation.
+   *
    * Only works for locales with postcode_by_state definition. If a locale does not
    * have a postcode_by_state definition, a random zip code is generated according
    * to the locale's zip format.
    *
-   * @param state The abbreviation of the state to generate the zip code for.
+   * @param options A state abbreviation or an options object. Defaults to `{}`.
+   * @param options.state The abbreviation of the state to generate the zip code for.
+   * If not specified, a random zip code is generated according to the locale's zip format.
    *
    * @example
    * fakerUS.location.zipCodeByState("AK") // '99595'
@@ -60,7 +75,23 @@ export class LocationModule {
    *
    * @since 8.0.0
    */
-  zipCodeByState(state: string): string {
+  zipCodeByState(
+    options:
+      | string
+      | {
+          /**
+           * The abbreviation of the state to generate the zip code for.
+           * If not specified, a random zip code is generated according to the locale's zip format.
+           */
+          state?: string;
+        } = {}
+  ): string {
+    if (typeof options === 'string') {
+      options = { state: options };
+    }
+
+    const { state } = options;
+
     const zipRange = this.faker.definitions.location.postcode_by_state?.[state];
     if (zipRange) {
       return String(this.faker.number.int(zipRange));
@@ -142,17 +173,35 @@ export class LocationModule {
   /**
    * Generates a random localized street address.
    *
-   * @param useFullAddress When true this will generate a full address.
+   * @param options Whether to use a full address or an options object. Defaults to `{}`.
+   * @param options.useFullAddress When true this will generate a full address.
    * Otherwise it will just generate a street address.
    *
    * @example
    * faker.location.streetAddress() // '0917 O'Conner Estates'
    * faker.location.streetAddress(false) // '34830 Erdman Hollow'
    * faker.location.streetAddress(true) // '3393 Ronny Way Apt. 742'
+   * faker.location.streetAddress({ useFullAddress: true }) // '7917 Miller Park Apt. 410'
    *
    * @since 8.0.0
    */
-  streetAddress(useFullAddress: boolean = false): string {
+  streetAddress(
+    options:
+      | boolean
+      | {
+          /**
+           * When true this will generate a full address.
+           * Otherwise it will just generate a street address.
+           */
+          useFullAddress?: boolean;
+        } = {}
+  ): string {
+    if (typeof options === 'boolean') {
+      options = { useFullAddress: options };
+    }
+
+    const { useFullAddress } = options;
+
     const formats = this.faker.definitions.location.street_address;
     const format = formats[useFullAddress ? 'full' : 'normal'];
 
@@ -207,7 +256,8 @@ export class LocationModule {
   /**
    * Returns a random country code.
    *
-   * @param alphaCode The code to return. Can be either `'alpha-2'` (2 letter code)
+   * @param options The code to return or an options object. Defaults to `{}`.
+   * @param options.variant The variant to return. Can be either `'alpha-2'` (2 letter code)
    * or `'alpha-3'` (three letter code). Defaults to `'alpha-2'`.
    *
    * @example
@@ -217,9 +267,27 @@ export class LocationModule {
    *
    * @since 8.0.0
    */
-  countryCode(alphaCode: 'alpha-2' | 'alpha-3' = 'alpha-2'): string {
-    const key =
-      alphaCode === 'alpha-3' ? 'country_code_alpha_3' : 'country_code';
+  countryCode(
+    options:
+      | 'alpha-2'
+      | 'alpha-3'
+      | {
+          /**
+           * The code to return.
+           * Can be either `'alpha-2'` (2 letter code)
+           * or `'alpha-3'` (three letter code).
+           *
+           * @default 'alpha-2'
+           */
+          variant?: 'alpha-2' | 'alpha-3';
+        } = {}
+  ): string {
+    if (typeof options === 'string') {
+      options = { variant: options };
+    }
+
+    const { variant = 'alpha-2' } = options;
+    const key = variant === 'alpha-3' ? 'country_code_alpha_3' : 'country_code';
 
     return this.faker.helpers.arrayElement(
       this.faker.definitions.location[key]
@@ -257,57 +325,345 @@ export class LocationModule {
   /**
    * Generates a random latitude.
    *
+   * @param options An options object. Defaults to `{}`.
+   * @param options.max The upper bound for the latitude to generate. Defaults to `90`.
+   * @param options.min The lower bound for the latitude to generate. Defaults to `-90`.
+   * @param options.precision The number of decimal points of precision for the latitude. Defaults to `4`.
+   *
+   * @example
+   * faker.location.latitude() // -30.9501
+   * faker.location.latitude({ max: 10 }) // 5.7225
+   * faker.location.latitude({ max: 10, min: -10 }) // -9.6273
+   * faker.location.latitude({ max: 10, min: -10, precision: 5 }) // 2.68452
+   *
+   * @since 8.0.0
+   */
+  latitude(options?: {
+    /**
+     * The upper bound for the latitude to generate.
+     *
+     * @default 90
+     */
+    max?: number;
+    /**
+     * The lower bound for the latitude to generate.
+     *
+     * @default -90
+     */
+    min?: number;
+    /**
+     * The number of decimal points of precision for the latitude.
+     *
+     * @default 4
+     */
+    precision?: number;
+  }): number;
+  /**
+   * Generates a random latitude.
+   *
    * @param max The upper bound for the latitude to generate. Defaults to `90`.
    * @param min The lower bound for the latitude to generate. Defaults to `-90`.
    * @param precision The number of decimal points of precision for the latitude. Defaults to `4`.
    *
    * @example
    * faker.location.latitude() // -30.9501
+   * faker.location.latitude(10) // 5.7225
+   * faker.location.latitude(10, -10) // -9.6273
+   * faker.location.latitude(10, -10, 5) // 2.68452
+   *
+   * @since 8.0.0
+   */
+  latitude(max?: number, min?: number, precision?: number): number;
+  /**
+   * Generates a random latitude.
+   *
+   * @param options The upper bound for the latitude or an options object. Defaults to `{}`.
+   * @param options.max The upper bound for the latitude to generate. Defaults to `90`.
+   * @param options.min The lower bound for the latitude to generate. Defaults to `-90`.
+   * @param options.precision The number of decimal points of precision for the latitude. Defaults to `4`.
+   * @param legacyMin The lower bound for the latitude to generate. Defaults to `-90`.
+   * @param legacyPrecision The number of decimal points of precision for the latitude. Defaults to `4`.
+   *
+   * @example
+   * faker.location.latitude() // -30.9501
+   * faker.location.latitude({ max: 10 }) // 5.7225
+   * faker.location.latitude({ max: 10, min: -10 }) // -9.6273
+   * faker.location.latitude({ max: 10, min: -10, precision: 5 }) // 2.68452
+   * faker.location.latitude(10) // 5.7225
+   * faker.location.latitude(10, -10) // -9.6273
    * faker.location.latitude(10, -10, 5) // 2.68452
    *
    * @since 8.0.0
    */
-  // TODO @xDivisionByZerox 2022-06-12 this signature should probably be an object for easier maintainability
-  latitude(max: number = 90, min: number = -90, precision: number = 4): number {
+  latitude(
+    options:
+      | number
+      | {
+          /**
+           * The upper bound for the latitude to generate.
+           *
+           * @default 90
+           */
+          max?: number;
+          /**
+           * The lower bound for the latitude to generate.
+           *
+           * @default -90
+           */
+          min?: number;
+          /**
+           * The number of decimal points of precision for the latitude.
+           *
+           * @default 4
+           */
+          precision?: number;
+        },
+    legacyMin?: number,
+    legacyPrecision?: number
+  ): number;
+  /**
+   * Generates a random latitude.
+   *
+   * @param options The upper bound for the latitude or an options object. Defaults to `{}`.
+   * @param options.max The upper bound for the latitude to generate. Defaults to `90`.
+   * @param options.min The lower bound for the latitude to generate. Defaults to `-90`.
+   * @param options.precision The number of decimal points of precision for the latitude. Defaults to `4`.
+   * @param legacyMin The lower bound for the latitude to generate. Defaults to `-90`.
+   * @param legacyPrecision The number of decimal points of precision for the latitude. Defaults to `4`.
+   *
+   * @example
+   * faker.location.latitude() // -30.9501
+   * faker.location.latitude({ max: 10 }) // 5.7225
+   * faker.location.latitude({ max: 10, min: -10 }) // -9.6273
+   * faker.location.latitude({ max: 10, min: -10, precision: 5 }) // 2.68452
+   * faker.location.latitude(10) // 5.7225
+   * faker.location.latitude(10, -10) // -9.6273
+   * faker.location.latitude(10, -10, 5) // 2.68452
+   *
+   * @since 8.0.0
+   */
+  latitude(
+    options:
+      | number
+      | {
+          /**
+           * The upper bound for the latitude to generate.
+           *
+           * @default 90
+           */
+          max?: number;
+          /**
+           * The lower bound for the latitude to generate.
+           *
+           * @default -90
+           */
+          min?: number;
+          /**
+           * The number of decimal points of precision for the latitude.
+           *
+           * @default 4
+           */
+          precision?: number;
+        } = {},
+    legacyMin = -90,
+    legacyPrecision = 4
+  ): number {
+    if (typeof options === 'number') {
+      options = { max: options };
+    }
+
+    const { max = 90, min = legacyMin, precision = legacyPrecision } = options;
+
     return this.faker.number.float({ min, max, precision: 10 ** -precision });
   }
 
   /**
    * Generates a random longitude.
    *
-   * @param max The upper bound for the longitude to generate. Defaults to `180`.
-   * @param min The lower bound for the longitude to generate. Defaults to `-180`.
-   * @param precision The number of decimal points of precision for the longitude. Defaults to `4`.
+   * @param options An options object. Defaults to `{}`.
+   * @param options.max The upper bound for the longitude to generate. Defaults to `180`.
+   * @param options.min The lower bound for the longitude to generate. Defaults to `-180`.
+   * @param options.precision The number of decimal points of precision for the longitude. Defaults to `4`.
+   *
+   * @example
+   * faker.location.longitude() // -30.9501
+   * faker.location.longitude({ max: 10 }) // 5.7225
+   * faker.location.longitude({ max: 10, min: -10 }) // -9.6273
+   * faker.location.longitude({ max: 10, min: -10, precision: 5 }) // 2.68452
+   *
+   * @since 8.0.0
+   */
+  longitude(options?: {
+    /**
+     * The upper bound for the latitude to generate.
+     *
+     * @default 90
+     */
+    max?: number;
+    /**
+     * The lower bound for the latitude to generate.
+     *
+     * @default -90
+     */
+    min?: number;
+    /**
+     * The number of decimal points of precision for the latitude.
+     *
+     * @default 4
+     */
+    precision?: number;
+  }): number;
+  /**
+   * Generates a random longitude.
+   *
+   * @param options An options object. Defaults to `{}`.
+   * @param options.max The upper bound for the longitude to generate. Defaults to `180`.
+   * @param options.min The lower bound for the longitude to generate. Defaults to `-180`.
+   * @param options.precision The number of decimal points of precision for the longitude. Defaults to `4`.
+   *
+   * @example
+   * faker.location.longitude() // -30.9501
+   * faker.location.longitude({ max: 10 }) // 5.7225
+   * faker.location.longitude({ max: 10, min: -10 }) // -9.6273
+   * faker.location.longitude({ max: 10, min: -10, precision: 5 }) // 2.68452
+   *
+   * @since 8.0.0
+   */
+  longitude(max?: number, min?: number, precision?: number): number;
+  /**
+   * Generates a random longitude.
+   *
+   * @param options The upper bound for the longitude or an options object. Defaults to `{}`.
+   * @param options.max The upper bound for the longitude to generate. Defaults to `180`.
+   * @param options.min The lower bound for the longitude to generate. Defaults to `-180`.
+   * @param options.precision The number of decimal points of precision for the longitude. Defaults to `4`.
+   * @param legacyMin The lower bound for the longitude to generate. Defaults to `-180`.
+   * @param legacyPrecision The number of decimal points of precision for the longitude. Defaults to `4`.
+   *
+   * @example
+   * faker.location.longitude() // -30.9501
+   * faker.location.longitude({ max: 10 }) // 5.7225
+   * faker.location.longitude({ max: 10, min: -10 }) // -9.6273
+   * faker.location.longitude({ max: 10, min: -10, precision: 5 }) // 2.68452
+   *
+   * @since 8.0.0
+   */
+  longitude(
+    options?:
+      | number
+      | {
+          /**
+           * The upper bound for the longitude to generate.
+           *
+           * @default 180
+           */
+          max?: number;
+          /**
+           * The lower bound for the longitude to generate.
+           *
+           * @default -180
+           */
+          min?: number;
+          /**
+           * The number of decimal points of precision for the longitude.
+           *
+           * @default 4
+           */
+          precision?: number;
+        },
+    legacyMin?: number,
+    legacyPrecision?: number
+  ): number;
+  /**
+   * Generates a random longitude.
+   *
+   * @param options An options object. Defaults to `{}`.
+   * @param options.max The upper bound for the longitude to generate. Defaults to `180`.
+   * @param options.min The lower bound for the longitude to generate. Defaults to `-180`.
+   * @param options.precision The number of decimal points of precision for the longitude. Defaults to `4`.
+   * @param legacyMin The lower bound for the longitude to generate. Defaults to `-180`.
+   * @param legacyPrecision The number of decimal points of precision for the longitude. Defaults to `4`.
    *
    * @example
    * faker.location.longitude() // -154.0226
+   * faker.location.longitude({ max: 10 }) // 2.4387
+   * faker.location.longitude({ max: 10, min: -10 }) // 6.9126
+   * faker.location.longitude({ max: 10, min: -10, precision: 5 }) // -4.03620
+   * faker.location.longitude(10) // 2.4387
+   * faker.location.longitude(10, -10) // 6.9126
    * faker.location.longitude(10, -10, 5) // -4.03620
    *
    * @since 8.0.0
    */
-  // TODO @xDivisionByZerox 2022-06-12 this signature should probably be an object for easier maintainability
   longitude(
-    max: number = 180,
-    min: number = -180,
-    precision: number = 4
+    options:
+      | number
+      | {
+          /**
+           * The upper bound for the longitude to generate.
+           *
+           * @default 180
+           */
+          max?: number;
+          /**
+           * The lower bound for the longitude to generate.
+           *
+           * @default -180
+           */
+          min?: number;
+          /**
+           * The number of decimal points of precision for the longitude.
+           *
+           * @default 4
+           */
+          precision?: number;
+        } = {},
+    legacyMin = -180,
+    legacyPrecision = 4
   ): number {
+    if (typeof options === 'number') {
+      options = { max: options };
+    }
+
+    const { max = 180, min = legacyMin, precision = legacyPrecision } = options;
+
     return this.faker.number.float({ max, min, precision: 10 ** -precision });
   }
 
   /**
    * Returns a random direction (cardinal and ordinal; northwest, east, etc).
    *
-   * @param useAbbr If true this will return abbreviated directions (NW, E, etc).
+   * @param options Whether to use abbreviated or an options object.
+   * @param options.useAbbr 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
    */
-  direction(useAbbr: boolean = false): string {
+  direction(
+    options:
+      | boolean
+      | {
+          /**
+           * If true this will return abbreviated directions (NW, E, etc).
+           * Otherwise this will return the long name.
+           *
+           * @default false
+           */
+          useAbbr?: boolean;
+        } = {}
+  ): string {
+    if (typeof options === 'boolean') {
+      options = { useAbbr: options };
+    }
+
+    const { useAbbr = false } = options;
+
     if (!useAbbr) {
       return this.faker.helpers.arrayElement(
         this.faker.definitions.location.direction
@@ -322,17 +678,36 @@ export class LocationModule {
   /**
    * Returns a random cardinal direction (north, east, south, west).
    *
-   * @param useAbbr If true this will return abbreviated directions (N, E, etc).
+   * @param options Whether to use abbreviated or an options object.
+   * @param options.useAbbr 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
    */
-  cardinalDirection(useAbbr: boolean = false): string {
+  cardinalDirection(
+    options:
+      | boolean
+      | {
+          /**
+           * If true this will return abbreviated directions (N, E, etc).
+           * Otherwise this will return the long name.
+           *
+           * @default false
+           */
+          useAbbr?: boolean;
+        } = {}
+  ): string {
+    if (typeof options === 'boolean') {
+      options = { useAbbr: options };
+    }
+
+    const { useAbbr = false } = options;
     if (!useAbbr) {
       return this.faker.helpers.arrayElement(
         this.faker.definitions.location.direction.slice(0, 4)
@@ -347,17 +722,36 @@ export class LocationModule {
   /**
    * Returns a random ordinal direction (northwest, southeast, etc).
    *
-   * @param useAbbr If true this will return abbreviated directions (NW, SE, etc).
+   * @param options Whether to use abbreviated or an options object.
+   * @param options.useAbbr 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
    */
-  ordinalDirection(useAbbr: boolean = false): string {
+  ordinalDirection(
+    options:
+      | boolean
+      | {
+          /**
+           * If true this will return abbreviated directions (NW, SE, etc).
+           * Otherwise this will return the long name.
+           *
+           * @default false
+           */
+          useAbbr?: boolean;
+        } = {}
+  ): string {
+    if (typeof options === 'boolean') {
+      options = { useAbbr: options };
+    }
+
+    const { useAbbr = false } = options;
     if (!useAbbr) {
       return this.faker.helpers.arrayElement(
         this.faker.definitions.location.direction.slice(4, 8)