refactor(location)!: zip code state (#1874)

docs/guide/upgrading.md

@@ -101,6 +101,10 @@ For more information refer to our [Localization Guide](localization).
 
 `faker.mersenne` and `faker.helpers.repeatString` were only ever intended for internal use, and are no longer available.
 
+### `faker.location.zipCodeByState`
+
+The `faker.location.zipCodeByState` method has been deprecated, but will also now throw an error if the current locale does not have a `postcode_by_state` definition.
+
 ### Other deprecated methods removed/replaced
 
 | Old method                      | New method                                                                                                      |

src/modules/location/index.ts

@@ -1,4 +1,5 @@
 import type { Faker } from '../..';
+import { FakerError } from '../../errors/faker-error';
 import { deprecated } from '../../internal/deprecated';
 
 /**
@@ -31,8 +32,11 @@ export class LocationModule {
    * the locale's zip format is used.
    *
    * @param options The format used to generate the the zip code or an options object. Defaults to `{}`.
+   * @param options.state The state to generate the zip code for.
+   * If the current locale does not have a corresponding `postcode_by_state` definition, an error is thrown.
    * @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.
+   * This wont be used if the state option is specified.
    *
    * @see faker.helpers.replaceSymbols()
    *
@@ -46,9 +50,17 @@ export class LocationModule {
     options:
       | string
       | {
+          /**
+           * The state to generate the zip code for.
+           *
+           * If the currrent locale does not have a corresponding `postcode_by_state` definition, an error is thrown.
+           */
+          state?: string;
           /**
            * The optional format used to generate the the zip code.
            *
+           * This wont be used if the state option is specified.
+           *
            * @default faker.definitions.location.postcode
            */
           format?: string;
@@ -58,6 +70,19 @@ export class LocationModule {
       options = { format: options };
     }
 
+    const { state } = options;
+
+    if (state) {
+      const zipRange =
+        this.faker.definitions.location.postcode_by_state?.[state];
+
+      if (zipRange) {
+        return String(this.faker.number.int(zipRange));
+      }
+
+      throw new FakerError(`No zip code definition found for state "${state}"`);
+    }
+
     let { format = this.faker.definitions.location.postcode } = options;
     if (typeof format === 'string') {
       format = [format];
@@ -71,19 +96,22 @@ export class LocationModule {
   /**
    * 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.
+   * If the current locale does not have a corresponding `postcode_by_state` definition, an error is thrown.
    *
    * @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.
    *
+   * @see faker.location.zipCode()
+   *
    * @example
    * fakerEN_US.location.zipCodeByState("AK") // '99595'
-   * fakerEN_US.location.zipCodeByState("??") // '47683-9880'
+   * fakerEN_US.location.zipCodeByState() // '47683-9880'
+   * fakerEN_US.location.zipCodeByState({ state: "AK" }) // '99595'
    *
    * @since 8.0.0
+   *
+   * @deprecated Use `faker.location.zipCode({ state })` instead.
    */
   zipCodeByState(
     options:
@@ -96,18 +124,20 @@ export class LocationModule {
           state?: string;
         } = {}
   ): string {
+    deprecated({
+      deprecated: 'faker.location.zipCodeByState',
+      proposed: 'faker.location.zipCode({ state })',
+      since: '8.0',
+      until: '9.0',
+    });
+
     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));
-    }
-
-    return this.zipCode();
+    return this.zipCode({ state });
   }
 
   /**

test/__snapshots__/location.spec.ts.snap

@@ -152,12 +152,6 @@ exports[`location > 42 > zipCode > with string 1`] = `"379"`;
 
 exports[`location > 42 > zipCodeByState > noArgs 1`] = `"79177"`;
 
-exports[`location > 42 > zipCodeByState > with state options 1`] = `"79177"`;
-
-exports[`location > 42 > zipCodeByState > with string 1 1`] = `"79177"`;
-
-exports[`location > 42 > zipCodeByState > with string 2 1`] = `"79177"`;
-
 exports[`location > 1211 > buildingNumber 1`] = `"487"`;
 
 exports[`location > 1211 > cardinalDirection > noArgs 1`] = `"West"`;
@@ -310,12 +304,6 @@ exports[`location > 1211 > zipCode > with string 1`] = `"948"`;
 
 exports[`location > 1211 > zipCodeByState > noArgs 1`] = `"48721-9061"`;
 
-exports[`location > 1211 > zipCodeByState > with state options 1`] = `"48721-9061"`;
-
-exports[`location > 1211 > zipCodeByState > with string 1 1`] = `"48721-9061"`;
-
-exports[`location > 1211 > zipCodeByState > with string 2 1`] = `"48721-9061"`;
-
 exports[`location > 1337 > buildingNumber 1`] = `"51225"`;
 
 exports[`location > 1337 > cardinalDirection > noArgs 1`] = `"East"`;
@@ -467,9 +455,3 @@ exports[`location > 1337 > zipCode > with format option 1`] = `"251-225"`;
 exports[`location > 1337 > zipCode > with string 1`] = `"251"`;
 
 exports[`location > 1337 > zipCodeByState > noArgs 1`] = `"51225"`;
-
-exports[`location > 1337 > zipCodeByState > with state options 1`] = `"51225"`;
-
-exports[`location > 1337 > zipCodeByState > with string 1 1`] = `"51225"`;
-
-exports[`location > 1337 > zipCodeByState > with string 2 1`] = `"51225"`;

test/location.spec.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { faker, fakerEN_CA, fakerEN_US } from '../src';
+import { faker, fakerEN_CA, fakerEN_US, FakerError } from '../src';
 import { seededTests } from './support/seededRuns';
 import { times } from './support/times';
 
@@ -114,13 +114,17 @@ describe('location', () => {
       t.it('noArgs')
         .it('with string', '###')
         .it('with format option', { format: '###-###' });
+      // These are currently commented out because non-default locales are currently not supported
+      // .it('with state option', { state: 'CA' })
+      // .it('with options', { state: 'CA', format: '###-###' });
     });
 
     t.describe('zipCodeByState', (t) => {
-      t.it('noArgs')
-        .it('with string 1', 'CA')
-        .it('with string 2', 'WA')
-        .it('with state options', { state: 'WA' });
+      t.it('noArgs');
+      // These are currently commented out because non-default locales are currently not supported
+      // .it('with string 1', 'CA')
+      // .it('with string 2', 'WA')
+      // .it('with state options', { state: 'WA' });
     });
   });
 
@@ -156,6 +160,22 @@ describe('location', () => {
 
           expect(zipCode).toMatch(/^[A-Za-z]\d[A-Za-z]\s?\d[A-Za-z]\d$/);
         });
+
+        it.each([
+          ['IL', 60001, 62999],
+          ['GA', 30001, 31999],
+          ['WA', 98001, 99403],
+        ])('returns zipCode valid for state %s', (state, lower, upper) => {
+          const zipCode1 = +fakerEN_US.location.zipCode({ state });
+          expect(zipCode1).toBeGreaterThanOrEqual(lower);
+          expect(zipCode1).toBeLessThanOrEqual(upper);
+        });
+
+        it('should throw when definitions.location.postcode_by_state not set', () => {
+          expect(() => faker.location.zipCode({ state: 'XX' })).toThrow(
+            new FakerError('No zip code definition found for state "XX"')
+          );
+        });
       });
 
       describe('zipCodeByState()', () => {