diff --git a/docs/guide/upgrading.md b/docs/guide/upgrading.md index 555c267ca28..a767b566dd5 100644 --- a/docs/guide/upgrading.md +++ b/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 | diff --git a/src/modules/location/index.ts b/src/modules/location/index.ts index 03d3413431b..0709796097f 100644 --- a/src/modules/location/index.ts +++ b/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 }); } /** diff --git a/test/__snapshots__/location.spec.ts.snap b/test/__snapshots__/location.spec.ts.snap index d263703c76d..1d09415c9b2 100644 --- a/test/__snapshots__/location.spec.ts.snap +++ b/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"`; diff --git a/test/location.spec.ts b/test/location.spec.ts index 3c41d351278..69af0a6d255 100644 --- a/test/location.spec.ts +++ b/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()', () => {