From 7b8c4b0f2c5a75651f42637cb692c86a1a1f02d2 Mon Sep 17 00:00:00 2001 From: xDivisionByZerox Date: Sun, 16 Apr 2023 14:29:24 +0200 Subject: [PATCH 1/7] refactor(location)!: merge state and stateAbbr --- src/modules/location/index.ts | 98 +++++++++++++++++++++--- test/__snapshots__/location.spec.ts.snap | 18 ++++- test/location.spec.ts | 9 ++- 3 files changed, 112 insertions(+), 13 deletions(-) diff --git a/src/modules/location/index.ts b/src/modules/location/index.ts index 0709796097f..06253f44a88 100644 --- a/src/modules/location/index.ts +++ b/src/modules/location/index.ts @@ -338,17 +338,91 @@ 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 useAbbreviation Whether to return an abbreviation. Defaults to `false`. + * * @example * faker.location.state() // 'Mississippi' - * fakerEN_CA.location.state() // 'Saskatchewan' - * fakerDE.location.state() // 'Nordrhein-Westfalen' + * faker.location.state(false) // 'Florida' + * faker.location.state(true) // 'AR' * * @since 8.0.0 */ - state(): string { - return this.faker.helpers.arrayElement( - this.faker.definitions.location.state - ); + state(useAbbreviation?: boolean): string; + /** + * 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.useAbbreviation Whether to return an abbreviation. Defaults to `false`. + * + * @example + * faker.location.state() // 'Mississippi' + * faker.location.state({ useAbbreviation: false }) // 'Florida' + * faker.location.state({ useAbbreviation: true }) // 'AR' + * + * @since 8.0.0 + */ + state(options?: { + /** + * Whether to return an abbreviation. Defaults to `false`. + */ + useAbbreviation?: boolean; + }): string; + /** + * 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 Whether to return an abbreviation or an options object. Defaults to `{}`. + * @param options.useAbbreviation Whether to return an abbreviation. Defaults to `false`. + * + * @example + * faker.location.state() // 'Mississippi' + * faker.location.state(false) // 'Iowa' + * fakerDE.location.state({ useAbbreviation: true }) // 'NRW' + * + * @since 8.0.0 + */ + state( + options?: + | boolean + | { + /** + * Whether to return an abbreviation. Defaults to `false`. + */ + useAbbreviation?: boolean; + } + ): string; + /** + * 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 Whether to return an abbreviation or an options object. Defaults to `{}`. + * @param options.useAbbreviation Whether to return an abbreviation. Defaults to `false`. + * + * @example + * faker.location.state() // 'Mississippi' + * faker.location.state(false) // 'Iowa' + * fakerDE.location.state({ useAbbreviation: true }) // 'NRW' + * + * @since 8.0.0 + */ + state( + options: + | boolean + | { + /** + * Whether to return an abbreviation. Defaults to `false`. + */ + useAbbreviation?: boolean; + } = {} + ): string { + if (typeof options === 'boolean') { + options = { useAbbreviation: options }; + } + + const { useAbbreviation = false } = options; + const stateDataSet = useAbbreviation + ? this.faker.definitions.location.state_abbr + : this.faker.definitions.location.state; + + return this.faker.helpers.arrayElement(stateDataSet); } /** @@ -358,11 +432,17 @@ export class LocationModule { * faker.location.stateAbbr() // 'ND' * * @since 8.0.0 + * + * @deprecated Use `faker.location.state({ useAbbreviation: true })` instead. */ stateAbbr(): string { - return this.faker.helpers.arrayElement( - this.faker.definitions.location.state_abbr - ); + deprecated({ + deprecated: 'faker.location.stateAbbr()', + proposed: 'faker.location.state({ useAbbreviation: true })', + since: '8.0', + until: '9.0', + }); + return this.state({ useAbbreviation: true }); } /** diff --git a/test/__snapshots__/location.spec.ts.snap b/test/__snapshots__/location.spec.ts.snap index 1d09415c9b2..e3b128ff234 100644 --- a/test/__snapshots__/location.spec.ts.snap +++ b/test/__snapshots__/location.spec.ts.snap @@ -128,7 +128,11 @@ exports[`location > 42 > ordinalDirection > with useAbbr option 1`] = `"NW"`; 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 boolean 1`] = `"Maine"`; + +exports[`location > 42 > state > with options 1`] = `"ME"`; exports[`location > 42 > stateAbbr 1`] = `"ME"`; @@ -280,7 +284,11 @@ exports[`location > 1211 > ordinalDirection > with useAbbr option 1`] = `"SW"`; 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 boolean 1`] = `"Washington"`; + +exports[`location > 1211 > state > with options 1`] = `"WA"`; exports[`location > 1211 > stateAbbr 1`] = `"WA"`; @@ -432,7 +440,11 @@ exports[`location > 1337 > ordinalDirection > with useAbbr option 1`] = `"NW"`; 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 boolean 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 69af0a6d255..c3d00c6ddd1 100644 --- a/test/location.spec.ts +++ b/test/location.spec.ts @@ -96,7 +96,14 @@ 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 boolean', false) + .it('with options', { useAbbreviation: true }); + }); + + t.it('stateAbbr'); t.it('timeZone'); From 9d8415e6218587c5a1d92d734dc1843f1a64b024 Mon Sep 17 00:00:00 2001 From: xDivisionByZerox Date: Sun, 16 Apr 2023 14:53:56 +0200 Subject: [PATCH 2/7] docs(location): better default JSDocs --- src/modules/location/index.ts | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/src/modules/location/index.ts b/src/modules/location/index.ts index 06253f44a88..51db3346b19 100644 --- a/src/modules/location/index.ts +++ b/src/modules/location/index.ts @@ -363,7 +363,9 @@ export class LocationModule { */ state(options?: { /** - * Whether to return an abbreviation. Defaults to `false`. + * Whether to return an abbreviation. + * + * @default false */ useAbbreviation?: boolean; }): string; @@ -385,7 +387,9 @@ export class LocationModule { | boolean | { /** - * Whether to return an abbreviation. Defaults to `false`. + * Whether to return an abbreviation. + * + * @default false */ useAbbreviation?: boolean; } @@ -408,7 +412,9 @@ export class LocationModule { | boolean | { /** - * Whether to return an abbreviation. Defaults to `false`. + * Whether to return an abbreviation. + * + * @default false */ useAbbreviation?: boolean; } = {} From 11c62c842b3926e557e932855a6ad4dcb192588a Mon Sep 17 00:00:00 2001 From: xDivisionByZerox Date: Sun, 16 Apr 2023 14:56:02 +0200 Subject: [PATCH 3/7] refactor(location): rename useAbbreviation to abbreviated --- src/modules/location/index.ts | 36 +++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/src/modules/location/index.ts b/src/modules/location/index.ts index 51db3346b19..9291ace2718 100644 --- a/src/modules/location/index.ts +++ b/src/modules/location/index.ts @@ -338,7 +338,7 @@ 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 useAbbreviation Whether to return an abbreviation. Defaults to `false`. + * @param abbreviated Whether to return an abbreviation. Defaults to `false`. * * @example * faker.location.state() // 'Mississippi' @@ -347,17 +347,17 @@ export class LocationModule { * * @since 8.0.0 */ - state(useAbbreviation?: boolean): string; + state(abbreviated?: boolean): string; /** * 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.useAbbreviation Whether to return an abbreviation. Defaults to `false`. + * @param options.abbreviated Whether to return an abbreviation. Defaults to `false`. * * @example * faker.location.state() // 'Mississippi' - * faker.location.state({ useAbbreviation: false }) // 'Florida' - * faker.location.state({ useAbbreviation: true }) // 'AR' + * faker.location.state({ abbreviated: false }) // 'Florida' + * faker.location.state({ abbreviated: true }) // 'AR' * * @since 8.0.0 */ @@ -367,18 +367,18 @@ export class LocationModule { * * @default false */ - useAbbreviation?: boolean; + abbreviated?: boolean; }): string; /** * 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 Whether to return an abbreviation or an options object. Defaults to `{}`. - * @param options.useAbbreviation Whether to return an abbreviation. Defaults to `false`. + * @param options.abbreviated Whether to return an abbreviation. Defaults to `false`. * * @example * faker.location.state() // 'Mississippi' * faker.location.state(false) // 'Iowa' - * fakerDE.location.state({ useAbbreviation: true }) // 'NRW' + * fakerDE.location.state({ abbreviated: true }) // 'NRW' * * @since 8.0.0 */ @@ -391,19 +391,19 @@ export class LocationModule { * * @default false */ - useAbbreviation?: boolean; + abbreviated?: boolean; } ): string; /** * 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 Whether to return an abbreviation or an options object. Defaults to `{}`. - * @param options.useAbbreviation Whether to return an abbreviation. Defaults to `false`. + * @param options.abbreviated Whether to return an abbreviation. Defaults to `false`. * * @example * faker.location.state() // 'Mississippi' * faker.location.state(false) // 'Iowa' - * fakerDE.location.state({ useAbbreviation: true }) // 'NRW' + * fakerDE.location.state({ abbreviated: true }) // 'NRW' * * @since 8.0.0 */ @@ -416,15 +416,15 @@ export class LocationModule { * * @default false */ - useAbbreviation?: boolean; + abbreviated?: boolean; } = {} ): string { if (typeof options === 'boolean') { - options = { useAbbreviation: options }; + options = { abbreviated: options }; } - const { useAbbreviation = false } = options; - const stateDataSet = useAbbreviation + const { abbreviated = false } = options; + const stateDataSet = abbreviated ? this.faker.definitions.location.state_abbr : this.faker.definitions.location.state; @@ -439,16 +439,16 @@ export class LocationModule { * * @since 8.0.0 * - * @deprecated Use `faker.location.state({ useAbbreviation: true })` instead. + * @deprecated Use `faker.location.state({ abbreviated: true })` instead. */ stateAbbr(): string { deprecated({ deprecated: 'faker.location.stateAbbr()', - proposed: 'faker.location.state({ useAbbreviation: true })', + proposed: 'faker.location.state({ abbreviated: true })', since: '8.0', until: '9.0', }); - return this.state({ useAbbreviation: true }); + return this.state({ abbreviated: true }); } /** From f7ccf404dcc3c0c920a900cf8b2a71b8f55bbafd Mon Sep 17 00:00:00 2001 From: xDivisionByZerox Date: Sun, 16 Apr 2023 15:05:16 +0200 Subject: [PATCH 4/7] refactor(location): remove boolean signature --- src/modules/location/index.ts | 79 +++--------------------- test/__snapshots__/location.spec.ts.snap | 6 -- test/location.spec.ts | 4 +- 3 files changed, 10 insertions(+), 79 deletions(-) diff --git a/src/modules/location/index.ts b/src/modules/location/index.ts index 9291ace2718..e1c4aca4743 100644 --- a/src/modules/location/index.ts +++ b/src/modules/location/index.ts @@ -335,19 +335,6 @@ export class LocationModule { )[key]; } - /** - * Returns a random localized state, or other equivalent first-level administrative entity for the locale's country such as a province or region. - * - * @param abbreviated Whether to return an abbreviation. Defaults to `false`. - * - * @example - * faker.location.state() // 'Mississippi' - * faker.location.state(false) // 'Florida' - * faker.location.state(true) // 'AR' - * - * @since 8.0.0 - */ - state(abbreviated?: boolean): string; /** * Returns a random localized state, or other equivalent first-level administrative entity for the locale's country such as a province or region. * @@ -356,68 +343,20 @@ export class LocationModule { * * @example * faker.location.state() // 'Mississippi' - * faker.location.state({ abbreviated: false }) // 'Florida' - * faker.location.state({ abbreviated: true }) // 'AR' - * - * @since 8.0.0 - */ - state(options?: { - /** - * Whether to return an abbreviation. - * - * @default false - */ - abbreviated?: boolean; - }): string; - /** - * 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 Whether to return an abbreviation or an options object. Defaults to `{}`. - * @param options.abbreviated Whether to return an abbreviation. Defaults to `false`. - * - * @example - * faker.location.state() // 'Mississippi' * faker.location.state(false) // 'Iowa' - * fakerDE.location.state({ abbreviated: true }) // 'NRW' + * faker.location.state({ abbreviated: true }) // 'LA' * * @since 8.0.0 */ state( - options?: - | boolean - | { - /** - * Whether to return an abbreviation. - * - * @default false - */ - abbreviated?: boolean; - } - ): string; - /** - * 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 Whether to return an abbreviation or an options object. Defaults to `{}`. - * @param options.abbreviated Whether to return an abbreviation. Defaults to `false`. - * - * @example - * faker.location.state() // 'Mississippi' - * faker.location.state(false) // 'Iowa' - * fakerDE.location.state({ abbreviated: true }) // 'NRW' - * - * @since 8.0.0 - */ - state( - options: - | boolean - | { - /** - * Whether to return an abbreviation. - * - * @default false - */ - abbreviated?: boolean; - } = {} + options: { + /** + * Whether to return an abbreviation. + * + * @default false + */ + abbreviated?: boolean; + } = {} ): string { if (typeof options === 'boolean') { options = { abbreviated: options }; diff --git a/test/__snapshots__/location.spec.ts.snap b/test/__snapshots__/location.spec.ts.snap index e3b128ff234..5bea023d732 100644 --- a/test/__snapshots__/location.spec.ts.snap +++ b/test/__snapshots__/location.spec.ts.snap @@ -130,8 +130,6 @@ exports[`location > 42 > secondaryAddress 1`] = `"Apt. 791"`; exports[`location > 42 > state > noArgs 1`] = `"Maine"`; -exports[`location > 42 > state > with boolean 1`] = `"Maine"`; - exports[`location > 42 > state > with options 1`] = `"ME"`; exports[`location > 42 > stateAbbr 1`] = `"ME"`; @@ -286,8 +284,6 @@ exports[`location > 1211 > secondaryAddress 1`] = `"Suite 487"`; exports[`location > 1211 > state > noArgs 1`] = `"Washington"`; -exports[`location > 1211 > state > with boolean 1`] = `"Washington"`; - exports[`location > 1211 > state > with options 1`] = `"WA"`; exports[`location > 1211 > stateAbbr 1`] = `"WA"`; @@ -442,8 +438,6 @@ exports[`location > 1337 > secondaryAddress 1`] = `"Apt. 512"`; exports[`location > 1337 > state > noArgs 1`] = `"Indiana"`; -exports[`location > 1337 > state > with boolean 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 c3d00c6ddd1..5841aa28d62 100644 --- a/test/location.spec.ts +++ b/test/location.spec.ts @@ -98,9 +98,7 @@ describe('location', () => { }); t.describe('state', (t) => { - t.it('noArgs') - .it('with boolean', false) - .it('with options', { useAbbreviation: true }); + t.it('noArgs').it('with options', { abbreviated: true }); }); t.it('stateAbbr'); From c4d2391565bcf8ac9c84e7a1078273e2f143ca10 Mon Sep 17 00:00:00 2001 From: DivisionByZero Date: Sun, 16 Apr 2023 16:08:48 +0200 Subject: [PATCH 5/7] chore: apply suggestions from code review Co-authored-by: ST-DDT --- src/modules/location/index.ts | 5 ----- 1 file changed, 5 deletions(-) diff --git a/src/modules/location/index.ts b/src/modules/location/index.ts index e1c4aca4743..16d424cbfd9 100644 --- a/src/modules/location/index.ts +++ b/src/modules/location/index.ts @@ -343,7 +343,6 @@ export class LocationModule { * * @example * faker.location.state() // 'Mississippi' - * faker.location.state(false) // 'Iowa' * faker.location.state({ abbreviated: true }) // 'LA' * * @since 8.0.0 @@ -358,10 +357,6 @@ export class LocationModule { abbreviated?: boolean; } = {} ): string { - if (typeof options === 'boolean') { - options = { abbreviated: options }; - } - const { abbreviated = false } = options; const stateDataSet = abbreviated ? this.faker.definitions.location.state_abbr From 59f526469f28dd1314843bf631a009217399a115 Mon Sep 17 00:00:00 2001 From: xDivisionByZerox Date: Sun, 16 Apr 2023 22:36:54 +0200 Subject: [PATCH 6/7] docs: revert divers examples --- src/modules/location/index.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/modules/location/index.ts b/src/modules/location/index.ts index 16d424cbfd9..26d6b71456c 100644 --- a/src/modules/location/index.ts +++ b/src/modules/location/index.ts @@ -343,6 +343,8 @@ export class LocationModule { * * @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 From b2815247d074e8ec3c8942e32fc02d906ecfc1a4 Mon Sep 17 00:00:00 2001 From: xDivisionByZerox Date: Sun, 16 Apr 2023 22:40:08 +0200 Subject: [PATCH 7/7] docs: align with #2061 --- src/modules/location/index.ts | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/modules/location/index.ts b/src/modules/location/index.ts index 26d6b71456c..24aef3b9d99 100644 --- a/src/modules/location/index.ts +++ b/src/modules/location/index.ts @@ -339,7 +339,8 @@ 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 Whether to return an abbreviation. Defaults to `false`. + * @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' @@ -352,7 +353,8 @@ export class LocationModule { state( options: { /** - * Whether to return an abbreviation. + * If true this will return abbreviated first-level administrative entity names. + * Otherwise this will return the long name. * * @default false */