From 20f2236265467feb095cce5b5735bbadc07b9696 Mon Sep 17 00:00:00 2001 From: Shinigami Date: Mon, 17 Oct 2022 04:05:05 +0800 Subject: refactor(person)!: rename name module (#1445) Co-authored-by: ST-DDT --- src/modules/git/index.ts | 2 +- src/modules/helpers/index.ts | 16 +- src/modules/internet/index.ts | 4 +- src/modules/name/index.ts | 328 ----------------------------------------- src/modules/person/index.ts | 333 ++++++++++++++++++++++++++++++++++++++++++ src/modules/random/index.ts | 12 +- 6 files changed, 350 insertions(+), 345 deletions(-) delete mode 100644 src/modules/name/index.ts create mode 100644 src/modules/person/index.ts (limited to 'src/modules') diff --git a/src/modules/git/index.ts b/src/modules/git/index.ts index d92e3454..cd9e7de0 100644 --- a/src/modules/git/index.ts +++ b/src/modules/git/index.ts @@ -65,7 +65,7 @@ export class GitModule { } lines.push( - `Author: ${this.faker.name.firstName()} ${this.faker.name.lastName()} <${this.faker.internet.email()}>`, + `Author: ${this.faker.person.firstName()} ${this.faker.person.lastName()} <${this.faker.internet.email()}>`, `Date: ${this.faker.date.recent().toString()}`, '', `\xa0\xa0\xa0\xa0${this.commitMessage()}`, diff --git a/src/modules/helpers/index.ts b/src/modules/helpers/index.ts index 5f90027d..bd765802 100644 --- a/src/modules/helpers/index.ts +++ b/src/modules/helpers/index.ts @@ -276,7 +276,7 @@ export class HelpersModule { * * @example * faker.helpers.uniqueArray(faker.random.word, 50) - * faker.helpers.uniqueArray(faker.definitions.name.first_name, 6) + * faker.helpers.uniqueArray(faker.definitions.person.first_name, 6) * faker.helpers.uniqueArray(["Hello", "World", "Goodbye"], 2) * * @since 6.0.0 @@ -478,10 +478,10 @@ export class HelpersModule { * It checks the given string for placeholders and replaces them by calling faker methods: * * ```js - * const hello = faker.helpers.fake('Hi, my name is {{name.firstName}} {{name.lastName}}!') + * const hello = faker.helpers.fake('Hi, my name is {{person.firstName}} {{person.lastName}}!') * ``` * - * This would use the `faker.name.firstName()` and `faker.name.lastName()` method to resolve the placeholders respectively. + * This would use the `faker.person.firstName()` and `faker.person.lastName()` method to resolve the placeholders respectively. * * It is also possible to provide parameters. At first, they will be parsed as json, * and if that isn't possible, we will fall back to string: @@ -499,10 +499,10 @@ export class HelpersModule { * @see faker.helpers.mustache() to use custom functions for resolution. * * @example - * faker.helpers.fake('{{name.lastName}}') // 'Barrows' - * faker.helpers.fake('{{name.lastName}}, {{name.firstName}} {{name.suffix}}') // 'Durgan, Noe MD' + * faker.helpers.fake('{{person.lastName}}') // 'Barrows' + * faker.helpers.fake('{{person.lastName}}, {{person.firstName}} {{person.suffix}}') // 'Durgan, Noe MD' * faker.helpers.fake('This is static test.') // 'This is static test.' - * faker.helpers.fake('Good Morning {{name.firstName}}!') // 'Good Morning Estelle!' + * faker.helpers.fake('Good Morning {{person.firstName}}!') // 'Good Morning Estelle!' * faker.helpers.fake('You can call me at {{phone.number(!## ### #####!)}}.') // 'You can call me at 202 555 973722.' * faker.helpers.fake('I flipped the coin and got: {{helpers.arrayElement(["heads", "tails"])}}') // 'I flipped the coin and got: tails' * @@ -524,7 +524,7 @@ export class HelpersModule { } // extract method name from between the {{ }} that we found - // for example: {{name.firstName}} + // for example: {{person.firstName}} const token = str.substring(start + 2, end + 2); let method = token.replace('}}', '').replace('{{', ''); @@ -614,7 +614,7 @@ export class HelpersModule { * @param options.store The store of unique entries. Defaults to a global store. * * @example - * faker.helpers.unique(faker.name.firstName) // 'Corbin' + * faker.helpers.unique(faker.person.firstName) // 'Corbin' * * @since 7.5.0 */ diff --git a/src/modules/internet/index.ts b/src/modules/internet/index.ts index 3c4eedee..1c7e85cc 100644 --- a/src/modules/internet/index.ts +++ b/src/modules/internet/index.ts @@ -136,8 +136,8 @@ export class InternetModule { */ userName(firstName?: string, lastName?: string): string { let result: string; - firstName = firstName || this.faker.name.firstName(); - lastName = lastName || this.faker.name.lastName(); + firstName = firstName || this.faker.person.firstName(); + lastName = lastName || this.faker.person.lastName(); switch (this.faker.datatype.number(2)) { case 0: result = `${firstName}${this.faker.datatype.number(99)}`; diff --git a/src/modules/name/index.ts b/src/modules/name/index.ts deleted file mode 100644 index 99d25f8f..00000000 --- a/src/modules/name/index.ts +++ /dev/null @@ -1,328 +0,0 @@ -import type { Faker } from '../..'; - -export enum Sex { - Female = 'female', - Male = 'male', -} - -export type SexType = `${Sex}`; - -/** - * Select a definition based on given sex. - * - * @param faker Faker instance. - * @param sex Sex. - * @param param2 Definitions. - * @param param2.generic Non-sex definitions. - * @param param2.female Female definitions. - * @param param2.male Male definitions. - * @returns Definition based on given sex. - */ -function selectDefinition( - faker: Faker, - sex: SexType | undefined, - // TODO @Shinigami92 2022-03-21: Remove fallback empty object when `strict: true` - { - generic, - female, - male, - }: { generic?: string[]; female?: string[]; male?: string[] } = {} -) { - let values: string[] | undefined; - - switch (sex) { - case Sex.Female: - values = female; - break; - - case Sex.Male: - values = male; - break; - - default: - values = generic; - break; - } - - if (values == null) { - if (female != null && male != null) { - values = faker.helpers.arrayElement([female, male]); - } else { - values = generic; - } - } - - return faker.helpers.arrayElement(values); -} - -/** - * Module to generate people's names and titles. - */ -export class NameModule { - constructor(private readonly faker: Faker) { - // Bind `this` so namespaced is working correctly - for (const name of Object.getOwnPropertyNames(NameModule.prototype)) { - if (name === 'constructor' || typeof this[name] !== 'function') { - continue; - } - this[name] = this[name].bind(this); - } - } - - /** - * Returns a random first name. - * - * @param sex The optional sex to use. - * Can be either `'female'` or `'male'`. - * - * @example - * faker.name.firstName() // 'Antwan' - * faker.name.firstName('female') // 'Victoria' - * faker.name.firstName('male') // 'Tom' - * - * @since 2.0.1 - */ - firstName(sex?: SexType): string { - const { first_name, female_first_name, male_first_name } = - this.faker.definitions.name; - - return selectDefinition(this.faker, sex, { - generic: first_name, - female: female_first_name, - male: male_first_name, - }); - } - - /** - * Returns a random last name. - * - * @param sex The optional sex to use. - * Can be either `'female'` or `'male'`. - * - * @example - * faker.name.lastName() // 'Hauck' - * faker.name.lastName('female') // 'Grady' - * faker.name.lastName('male') // 'Barton' - * - * @since 2.0.1 - */ - lastName(sex?: SexType): string { - const { last_name, female_last_name, male_last_name } = - this.faker.definitions.name; - - return selectDefinition(this.faker, sex, { - generic: last_name, - female: female_last_name, - male: male_last_name, - }); - } - - /** - * Returns a random middle name. - * - * @param sex The optional sex to use. - * Can be either `'female'` or `'male'`. - * - * @example - * faker.name.middleName() // 'James' - * faker.name.middleName('female') // 'Eloise' - * faker.name.middleName('male') // 'Asher' - * - * @since 5.2.0 - */ - middleName(sex?: SexType): string { - const { middle_name, female_middle_name, male_middle_name } = - this.faker.definitions.name; - - return selectDefinition(this.faker, sex, { - generic: middle_name, - female: female_middle_name, - male: male_middle_name, - }); - } - - /** - * Generates a random full name. - * - * @param options An options object. Defaults to `{}`. - * @param options.firstName The optional first name to use. If not specified a random one will be chosen. - * @param options.lastName The optional last name to use. If not specified a random one will be chosen. - * @param options.sex The optional sex to use. Can be either `'female'` or `'male'`. - * - * @example - * faker.name.fullName() // 'Allen Brown' - * faker.name.fullName({ firstName: 'Joann' }) // 'Joann Osinski' - * faker.name.fullName({ firstName: 'Marcella', sex: 'female' }) // 'Mrs. Marcella Huels' - * faker.name.fullName({ lastName: 'Beer' }) // 'Mr. Alfonso Beer' - * faker.name.fullName({ sex: 'male' }) // 'Fernando Schaefer' - * - * @since 7.4.0 - */ - fullName( - options: { - firstName?: string; - lastName?: string; - sex?: SexType; - } = {} - ): string { - const { - sex = this.faker.helpers.arrayElement([Sex.Female, Sex.Male]), - firstName = this.firstName(sex), - lastName = this.lastName(sex), - } = options; - - const nameParts: string[] = []; - const prefix = this.faker.helpers.maybe(() => this.prefix(sex), { - probability: 0.125, - }); - - if (prefix) { - nameParts.push(prefix); - } - - nameParts.push(firstName); - nameParts.push(lastName); - - const suffix = this.faker.helpers.maybe(() => this.suffix(), { - probability: 0.125, - }); - - if (suffix) { - nameParts.push(suffix); - } - - return nameParts.join(' '); - } - - /** - * Returns a random gender. - * - * @see faker.name.sex() if you would like to generate binary-gender value - * - * @example - * faker.name.gender() // 'Trans*Man' - * - * @since 5.0.0 - */ - gender(): string { - return this.faker.helpers.arrayElement(this.faker.definitions.name.gender); - } - - /** - * Returns a random sex. - * - * Output of this method is localised, so it should not be used to fill the parameter `sex` - * available in some other modules for example `faker.name.firstName()`. - * - * @see faker.name.gender() if you would like to generate gender related values. - * - * @example - * faker.name.sex() // 'female' - * - * @since 7.5.0 - */ - sex(): string { - return this.faker.helpers.arrayElement(this.faker.definitions.name.sex); - } - - /** - * Returns a random sex type. - * - * @example - * faker.name.sexType() // Sex.Female - * - * @since 7.5.0 - */ - sexType(): SexType { - return this.faker.helpers.objectValue(Sex); - } - - /** - * Returns a random name prefix. - * - * @param sex The optional sex to use. Can be either `'female'` or `'male'`. - * - * @example - * faker.name.prefix() // 'Miss' - * faker.name.prefix('female') // 'Ms.' - * faker.name.prefix('male') // 'Mr.' - * - * @since 2.0.1 - */ - prefix(sex?: SexType): string { - const { prefix, female_prefix, male_prefix } = this.faker.definitions.name; - - return selectDefinition(this.faker, sex, { - generic: prefix, - female: female_prefix, - male: male_prefix, - }); - } - - /** - * Returns a random name suffix. - * - * @example - * faker.name.suffix() // 'DDS' - * - * @since 2.0.1 - */ - suffix(): string { - // TODO @Shinigami92 2022-03-21: Add female_suffix and male_suffix - return this.faker.helpers.arrayElement(this.faker.definitions.name.suffix); - } - - /** - * Generates a random job title. - * - * @example - * faker.name.jobTitle() // 'Global Accounts Engineer' - * - * @since 3.0.0 - */ - jobTitle(): string { - return `${this.jobDescriptor()} ${this.jobArea()} ${this.jobType()}`; - } - - /** - * Generates a random job descriptor. - * - * @example - * faker.name.jobDescriptor() // 'Customer' - * - * @since 3.0.0 - */ - jobDescriptor(): string { - return this.faker.helpers.arrayElement( - this.faker.definitions.name.title.descriptor - ); - } - - /** - * Generates a random job area. - * - * @example - * faker.name.jobArea() // 'Brand' - * - * @since 3.0.0 - */ - jobArea(): string { - return this.faker.helpers.arrayElement( - this.faker.definitions.name.title.level - ); - } - - /** - * Generates a random job type. - * - * @example - * faker.name.jobType() // 'Assistant' - * - * @since 3.0.0 - */ - jobType(): string { - return this.faker.helpers.arrayElement( - this.faker.definitions.name.title.job - ); - } -} diff --git a/src/modules/person/index.ts b/src/modules/person/index.ts new file mode 100644 index 00000000..9938a077 --- /dev/null +++ b/src/modules/person/index.ts @@ -0,0 +1,333 @@ +import type { Faker } from '../..'; + +export enum Sex { + Female = 'female', + Male = 'male', +} + +export type SexType = `${Sex}`; + +/** + * Select a definition based on given sex. + * + * @param faker Faker instance. + * @param sex Sex. + * @param param2 Definitions. + * @param param2.generic Non-sex definitions. + * @param param2.female Female definitions. + * @param param2.male Male definitions. + * @returns Definition based on given sex. + */ +function selectDefinition( + faker: Faker, + sex: SexType | undefined, + // TODO @Shinigami92 2022-03-21: Remove fallback empty object when `strict: true` + { + generic, + female, + male, + }: { generic?: string[]; female?: string[]; male?: string[] } = {} +) { + let values: string[] | undefined; + + switch (sex) { + case Sex.Female: + values = female; + break; + + case Sex.Male: + values = male; + break; + + default: + values = generic; + break; + } + + if (values == null) { + if (female != null && male != null) { + values = faker.helpers.arrayElement([female, male]); + } else { + values = generic; + } + } + + return faker.helpers.arrayElement(values); +} + +/** + * Module to generate people's names and titles. + */ +export class PersonModule { + constructor(private readonly faker: Faker) { + // Bind `this` so namespaced is working correctly + for (const name of Object.getOwnPropertyNames(PersonModule.prototype)) { + if (name === 'constructor' || typeof this[name] !== 'function') { + continue; + } + this[name] = this[name].bind(this); + } + } + + /** + * Returns a random first name. + * + * @param sex The optional sex to use. + * Can be either `'female'` or `'male'`. + * + * @example + * faker.person.firstName() // 'Antwan' + * faker.person.firstName('female') // 'Victoria' + * faker.person.firstName('male') // 'Tom' + * + * @since 2.0.1 + */ + firstName(sex?: SexType): string { + const { first_name, female_first_name, male_first_name } = + this.faker.definitions.person; + + return selectDefinition(this.faker, sex, { + generic: first_name, + female: female_first_name, + male: male_first_name, + }); + } + + /** + * Returns a random last name. + * + * @param sex The optional sex to use. + * Can be either `'female'` or `'male'`. + * + * @example + * faker.person.lastName() // 'Hauck' + * faker.person.lastName('female') // 'Grady' + * faker.person.lastName('male') // 'Barton' + * + * @since 2.0.1 + */ + lastName(sex?: SexType): string { + const { last_name, female_last_name, male_last_name } = + this.faker.definitions.person; + + return selectDefinition(this.faker, sex, { + generic: last_name, + female: female_last_name, + male: male_last_name, + }); + } + + /** + * Returns a random middle name. + * + * @param sex The optional sex to use. + * Can be either `'female'` or `'male'`. + * + * @example + * faker.person.middleName() // 'James' + * faker.person.middleName('female') // 'Eloise' + * faker.person.middleName('male') // 'Asher' + * + * @since 5.2.0 + */ + middleName(sex?: SexType): string { + const { middle_name, female_middle_name, male_middle_name } = + this.faker.definitions.person; + + return selectDefinition(this.faker, sex, { + generic: middle_name, + female: female_middle_name, + male: male_middle_name, + }); + } + + /** + * Generates a random full name. + * + * @param options An options object. Defaults to `{}`. + * @param options.firstName The optional first name to use. If not specified a random one will be chosen. + * @param options.lastName The optional last name to use. If not specified a random one will be chosen. + * @param options.sex The optional sex to use. Can be either `'female'` or `'male'`. + * + * @example + * faker.person.fullName() // 'Allen Brown' + * faker.person.fullName({ firstName: 'Joann' }) // 'Joann Osinski' + * faker.person.fullName({ firstName: 'Marcella', sex: 'female' }) // 'Mrs. Marcella Huels' + * faker.person.fullName({ lastName: 'Beer' }) // 'Mr. Alfonso Beer' + * faker.person.fullName({ sex: 'male' }) // 'Fernando Schaefer' + * + * @since 7.4.0 + */ + fullName( + options: { + firstName?: string; + lastName?: string; + sex?: SexType; + } = {} + ): string { + const { + sex = this.faker.helpers.arrayElement([Sex.Female, Sex.Male]), + firstName = this.firstName(sex), + lastName = this.lastName(sex), + } = options; + + const nameParts: string[] = []; + const prefix = this.faker.helpers.maybe(() => this.prefix(sex), { + probability: 0.125, + }); + + if (prefix) { + nameParts.push(prefix); + } + + nameParts.push(firstName); + nameParts.push(lastName); + + const suffix = this.faker.helpers.maybe(() => this.suffix(), { + probability: 0.125, + }); + + if (suffix) { + nameParts.push(suffix); + } + + return nameParts.join(' '); + } + + /** + * Returns a random gender. + * + * @see faker.person.sex() if you would like to generate binary-gender value + * + * @example + * faker.person.gender() // 'Trans*Man' + * + * @since 5.0.0 + */ + gender(): string { + return this.faker.helpers.arrayElement( + this.faker.definitions.person.gender + ); + } + + /** + * Returns a random sex. + * + * Output of this method is localised, so it should not be used to fill the parameter `sex` + * available in some other modules for example `faker.person.firstName()`. + * + * @see faker.person.gender() if you would like to generate gender related values. + * + * @example + * faker.person.sex() // 'female' + * + * @since 7.5.0 + */ + sex(): string { + return this.faker.helpers.arrayElement(this.faker.definitions.person.sex); + } + + /** + * Returns a random sex type. + * + * @example + * faker.person.sexType() // Sex.Female + * + * @since 7.5.0 + */ + sexType(): SexType { + return this.faker.helpers.objectValue(Sex); + } + + /** + * Returns a random person prefix. + * + * @param sex The optional sex to use. Can be either `'female'` or `'male'`. + * + * @example + * faker.person.prefix() // 'Miss' + * faker.person.prefix('female') // 'Ms.' + * faker.person.prefix('male') // 'Mr.' + * + * @since 2.0.1 + */ + prefix(sex?: SexType): string { + const { prefix, female_prefix, male_prefix } = + this.faker.definitions.person; + + return selectDefinition(this.faker, sex, { + generic: prefix, + female: female_prefix, + male: male_prefix, + }); + } + + /** + * Returns a random person suffix. + * + * @example + * faker.person.suffix() // 'DDS' + * + * @since 2.0.1 + */ + suffix(): string { + // TODO @Shinigami92 2022-03-21: Add female_suffix and male_suffix + return this.faker.helpers.arrayElement( + this.faker.definitions.person.suffix + ); + } + + /** + * Generates a random job title. + * + * @example + * faker.person.jobTitle() // 'Global Accounts Engineer' + * + * @since 3.0.0 + */ + jobTitle(): string { + return `${this.jobDescriptor()} ${this.jobArea()} ${this.jobType()}`; + } + + /** + * Generates a random job descriptor. + * + * @example + * faker.person.jobDescriptor() // 'Customer' + * + * @since 3.0.0 + */ + jobDescriptor(): string { + return this.faker.helpers.arrayElement( + this.faker.definitions.person.title.descriptor + ); + } + + /** + * Generates a random job area. + * + * @example + * faker.person.jobArea() // 'Brand' + * + * @since 3.0.0 + */ + jobArea(): string { + return this.faker.helpers.arrayElement( + this.faker.definitions.person.title.level + ); + } + + /** + * Generates a random job type. + * + * @example + * faker.person.jobType() // 'Assistant' + * + * @since 3.0.0 + */ + jobType(): string { + return this.faker.helpers.arrayElement( + this.faker.definitions.person.title.job + ); + } +} diff --git a/src/modules/random/index.ts b/src/modules/random/index.ts index 7ce4df75..e79a2e70 100644 --- a/src/modules/random/index.ts +++ b/src/modules/random/index.ts @@ -155,12 +155,12 @@ export class RandomModule { this.faker.music.genre, - this.faker.name.gender, - this.faker.name.jobArea, - this.faker.name.jobDescriptor, - this.faker.name.jobTitle, - this.faker.name.jobType, - this.faker.name.sex, + this.faker.person.gender, + this.faker.person.jobArea, + this.faker.person.jobDescriptor, + this.faker.person.jobTitle, + this.faker.person.jobType, + this.faker.person.sex, () => this.faker.science.chemicalElement().name, () => this.faker.science.unit().name, -- cgit v1.2.3