From c8c87449be05f5d910919b2f46d48c449d56ea49 Mon Sep 17 00:00:00 2001
From: ST-DDT <ST-DDT@gmx.de>
Date: Sat, 26 Oct 2024 13:31:05 +0200
Subject: [PATCH 1/2] refactor(location): deprecate zipCode format parameter

---
 src/modules/location/index.ts | 121 ++++++++++++++++++++++++++++++++--
 test/modules/location.spec.ts |   2 +
 2 files changed, 117 insertions(+), 6 deletions(-)

diff --git a/src/modules/location/index.ts b/src/modules/location/index.ts
index 4a49e029501..926cb6a1418 100644
--- a/src/modules/location/index.ts
+++ b/src/modules/location/index.ts
@@ -1,4 +1,5 @@
 import { FakerError } from '../../errors/faker-error';
+import { deprecated } from '../../internal/deprecated';
 import { ModuleBase } from '../../internal/module-base';
 
 /**
@@ -13,6 +14,60 @@ import { ModuleBase } from '../../internal/module-base';
  * For a random country, you can use [`country()`](https://fakerjs.dev/api/location.html#country) or [`countryCode()`](https://fakerjs.dev/api/location.html#countrycode).
  */
 export class LocationModule extends ModuleBase {
+  /**
+   * Generates random zip code for the entire locale or the given state.
+   *
+   * @param options The optional options object.
+   * @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.
+   *
+   * @example
+   * faker.location.zipCode() // '17839'
+   * fakerEN_US.location.zipCode({ state: 'CA' }) // '90210'
+   *
+   * @since 8.0.0
+   */
+  zipCode(options?: {
+    /**
+     * 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.
+     */
+    state?: string;
+  }): string;
+  /**
+   * Generates random zip code from specified format. If format is not specified,
+   * the locale's zip format is used.
+   *
+   * @param options The format used to generate the zip code or an options object.
+   * @param options.format The optional format used to generate the zip code.
+   * By default, a random format is used from the locale zip formats.
+   * This won't be used if the state option is specified.
+   *
+   * @see faker.helpers.replaceSymbols(): For more information about how the pattern is used.
+   *
+   * @example
+   * faker.location.zipCode() // '17839'
+   * faker.location.zipCode('####') // '6925'
+   *
+   * @since 8.0.0
+   *
+   * @deprecated Use `faker.location.zipCode()` or `faker.location.zipCode({ state })` or `faker.helpers.replaceSymbols(format)` instead.
+   */
+  zipCode(
+    options?:
+      | string
+      | {
+          /**
+           * The optional format used to generate the zip code.
+           *
+           * This won't be used if the state option is specified.
+           *
+           * @default faker.definitions.location.postcode
+           */
+          format?: string;
+        }
+  ): string;
   /**
    * Generates random zip code from specified format. If format is not specified,
    * the locale's zip format is used.
@@ -28,7 +83,46 @@ export class LocationModule extends ModuleBase {
    *
    * @example
    * faker.location.zipCode() // '17839'
-   * faker.location.zipCode('####') // '6925'
+   * fakerEN_US.location.zipCode({ state: 'CA' }) // '90210'
+   *
+   * @since 8.0.0
+   */
+  zipCode(
+    options?:
+      | string
+      | {
+          /**
+           * 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.
+           */
+          state?: string;
+          /**
+           * The optional format used to generate the zip code.
+           *
+           * This won't be used if the state option is specified.
+           *
+           * @default faker.definitions.location.postcode
+           */
+          format?: string;
+        }
+  ): string;
+  /**
+   * Generates random zip code from specified format. If format is not specified,
+   * the locale's zip format is used.
+   *
+   * @param options The format used to generate the zip code or an options object.
+   * @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 zip code.
+   * By default, a random format is used from the locale zip formats.
+   * This won't be used if the state option is specified.
+   *
+   * @see faker.helpers.replaceSymbols(): For more information about how the pattern is used.
+   *
+   * @example
+   * faker.location.zipCode() // '17839'
+   * fakerEN_US.location.zipCode({ state: 'CA' }) // '90210'
    *
    * @since 8.0.0
    */
@@ -71,14 +165,29 @@ export class LocationModule extends ModuleBase {
       return this.faker.helpers.fake(zipPattern);
     }
 
-    let { format = this.faker.definitions.location.postcode } = options;
-    if (typeof format === 'string') {
-      format = [format];
+    const { format } = options;
+
+    if (format != null) {
+      deprecated({
+        deprecated:
+          'faker.location.zipCode(format) and faker.location.zipCode({ format })',
+        proposed:
+          'faker.location.zipCode(), faker.location.zipCode({ state }), or faker.helpers.replaceSymbols(format)',
+        since: '9.1.0',
+        until: '10.0.0',
+      });
+      return this.faker.helpers.replaceSymbols(format);
+    }
+
+    let zipPattern = this.faker.definitions.location.postcode;
+
+    if (typeof zipPattern === 'string') {
+      zipPattern = [zipPattern];
     }
 
-    format = this.faker.helpers.arrayElement(format);
+    zipPattern = this.faker.helpers.arrayElement(zipPattern);
 
-    return this.faker.helpers.replaceSymbols(format);
+    return this.faker.helpers.replaceSymbols(zipPattern);
   }
 
   /**
diff --git a/test/modules/location.spec.ts b/test/modules/location.spec.ts
index 2be7c4896a3..9b0707d1184 100644
--- a/test/modules/location.spec.ts
+++ b/test/modules/location.spec.ts
@@ -182,11 +182,13 @@ describe('location', () => {
 
       describe('zipCode()', () => {
         it('returns random zipCode - user specified format', () => {
+          // eslint-disable-next-line @typescript-eslint/no-deprecated
           let zipCode = faker.location.zipCode({ format: '?#? #?#' });
 
           expect(zipCode).toMatch(/^[A-Za-z]\d[A-Za-z]\s\d[A-Za-z]\d$/);
 
           // try another format
+          // eslint-disable-next-line @typescript-eslint/no-deprecated
           zipCode = faker.location.zipCode({ format: '###-###' });
 
           expect(zipCode).toMatch(/^\d{3}-\d{3}$/);

From ebd0dd04a6055c8878f82c565d6ad13aa34ddd40 Mon Sep 17 00:00:00 2001
From: ST-DDT <ST-DDT@gmx.de>
Date: Tue, 29 Oct 2024 20:43:21 +0100
Subject: [PATCH 2/2] Update src/modules/location/index.ts

---
 src/modules/location/index.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/modules/location/index.ts b/src/modules/location/index.ts
index 926cb6a1418..88f4a9cb711 100644
--- a/src/modules/location/index.ts
+++ b/src/modules/location/index.ts
@@ -173,7 +173,7 @@ export class LocationModule extends ModuleBase {
           'faker.location.zipCode(format) and faker.location.zipCode({ format })',
         proposed:
           'faker.location.zipCode(), faker.location.zipCode({ state }), or faker.helpers.replaceSymbols(format)',
-        since: '9.1.0',
+        since: '9.2.0',
         until: '10.0.0',
       });
       return this.faker.helpers.replaceSymbols(format);