diff --git a/src/modules/location/index.ts b/src/modules/location/index.ts index 29267eb1a44..c1b5ab06453 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'; /** @@ -33,6 +34,60 @@ export interface Language { * 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. @@ -48,7 +103,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 */ @@ -91,14 +185,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.2.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 78b688126dc..1459139468f 100644 --- a/test/modules/location.spec.ts +++ b/test/modules/location.spec.ts @@ -184,11 +184,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}$/);