refactor(location): merge state and stateAbbr (#2060)

3 files changed, 46 insertions, 11 deletions

diff --git a/src/modules/location/index.ts b/src/modules/location/index.ts
index 4931d46f..1d0bd4a4 100644
--- a/src/modules/location/index.ts
+++ b/src/modules/location/index.ts
@@ -338,17 +338,35 @@ export class LocationModule {
   /**
    * Returns a random localized state, or other equivalent first-level administrative entity for the locale's country such as a province or region.
    *
+   * @param options An options object. Defaults to `{}`.
+   * @param options.abbreviated If true this will return abbreviated first-level administrative entity names.
+   * Otherwise this will return the long name. Defaults to `false`.
+   *
    * @example
    * faker.location.state() // 'Mississippi'
    * fakerEN_CA.location.state() // 'Saskatchewan'
    * fakerDE.location.state() // 'Nordrhein-Westfalen'
+   * faker.location.state({ abbreviated: true }) // 'LA'
    *
    * @since 8.0.0
    */
-  state(): string {
-    return this.faker.helpers.arrayElement(
-      this.faker.definitions.location.state
-    );
+  state(
+    options: {
+      /**
+       * If true this will return abbreviated first-level administrative entity names.
+       * Otherwise this will return the long name.
+       *
+       * @default false
+       */
+      abbreviated?: boolean;
+    } = {}
+  ): string {
+    const { abbreviated = false } = options;
+    const stateDataSet = abbreviated
+      ? this.faker.definitions.location.state_abbr
+      : this.faker.definitions.location.state;
+
+    return this.faker.helpers.arrayElement(stateDataSet);
   }
 
   /**
@@ -358,11 +376,17 @@ export class LocationModule {
    * faker.location.stateAbbr() // 'ND'
    *
    * @since 8.0.0
+   *
+   * @deprecated Use `faker.location.state({ abbreviated: true })` instead.
    */
   stateAbbr(): string {
-    return this.faker.helpers.arrayElement(
-      this.faker.definitions.location.state_abbr
-    );
+    deprecated({
+      deprecated: 'faker.location.stateAbbr()',
+      proposed: 'faker.location.state({ abbreviated: true })',
+      since: '8.0',
+      until: '9.0',
+    });
+    return this.state({ abbreviated: true });
   }
 
   /**
diff --git a/test/__snapshots__/location.spec.ts.snap b/test/__snapshots__/location.spec.ts.snap
index f41c9f70..8fa97b7a 100644
--- a/test/__snapshots__/location.spec.ts.snap
+++ b/test/__snapshots__/location.spec.ts.snap
@@ -128,7 +128,9 @@ exports[`location > 42 > ordinalDirection > with boolean 1`] = `"Northwest"`;
 
 exports[`location > 42 > secondaryAddress 1`] = `"Apt. 791"`;
 
-exports[`location > 42 > state 1`] = `"Maine"`;
+exports[`location > 42 > state > noArgs 1`] = `"Maine"`;
+
+exports[`location > 42 > state > with options 1`] = `"ME"`;
 
 exports[`location > 42 > stateAbbr 1`] = `"ME"`;
 
@@ -280,7 +282,9 @@ exports[`location > 1211 > ordinalDirection > with boolean 1`] = `"Southwest"`;
 
 exports[`location > 1211 > secondaryAddress 1`] = `"Suite 487"`;
 
-exports[`location > 1211 > state 1`] = `"Washington"`;
+exports[`location > 1211 > state > noArgs 1`] = `"Washington"`;
+
+exports[`location > 1211 > state > with options 1`] = `"WA"`;
 
 exports[`location > 1211 > stateAbbr 1`] = `"WA"`;
 
@@ -432,7 +436,9 @@ exports[`location > 1337 > ordinalDirection > with boolean 1`] = `"Northwest"`;
 
 exports[`location > 1337 > secondaryAddress 1`] = `"Apt. 512"`;
 
-exports[`location > 1337 > state 1`] = `"Indiana"`;
+exports[`location > 1337 > state > noArgs 1`] = `"Indiana"`;
+
+exports[`location > 1337 > state > with options 1`] = `"IN"`;
 
 exports[`location > 1337 > stateAbbr 1`] = `"IN"`;
 
diff --git a/test/location.spec.ts b/test/location.spec.ts
index 1835ab43..4dbc85c2 100644
--- a/test/location.spec.ts
+++ b/test/location.spec.ts
@@ -96,7 +96,12 @@ describe('location', () => {
         .it('only radius', { radius: 12 })
         .it('only isMetric', { isMetric: true });
     });
-    t.it('state').it('stateAbbr');
+
+    t.describe('state', (t) => {
+      t.it('noArgs').it('with options', { abbreviated: true });
+    });
+
+    t.it('stateAbbr');
 
     t.it('timeZone');