diff --git a/src/index.ts b/src/index.ts index 8a6b7ecc6b6..e3b223b0750 100644 --- a/src/index.ts +++ b/src/index.ts @@ -37,8 +37,8 @@ export type { NumberColorFormat, StringColorFormat, } from './modules/color'; -export { Gender } from './modules/name'; -export type { GenderType } from './modules/name'; +export { Gender, Sex } from './modules/name'; +export type { GenderType, SexType } from './modules/name'; export type { ChemicalElement, Unit } from './modules/science'; export { Faker }; diff --git a/src/modules/name/index.ts b/src/modules/name/index.ts index 3ff775e2b9e..0a67c382cda 100644 --- a/src/modules/name/index.ts +++ b/src/modules/name/index.ts @@ -1,30 +1,43 @@ import type { Faker } from '../..'; import { deprecated } from '../../internal/deprecated'; -// disabled until renamed to Sex +/** + * @deprecated Use Sex enum instead. + */ export enum Gender { + // disabled until renamed to Sex // eslint-disable-next-line @typescript-eslint/naming-convention female = 'female', // eslint-disable-next-line @typescript-eslint/naming-convention male = 'male', } -export type GenderType = 'female' | 'male'; +/** + * @deprecated Use SexType instead. + */ +export type GenderType = SexType; + +export enum Sex { + Female = 'female', + Male = 'male', +} + +export type SexType = `${Sex}`; /** - * Select a definition based on given gender. + * Select a definition based on given sex. * * @param faker Faker instance. - * @param gender Gender. + * @param sex Sex. * @param param2 Definitions. - * @param param2.generic Non-gender definitions. + * @param param2.generic Non-sex definitions. * @param param2.female Female definitions. * @param param2.male Male definitions. - * @returns Definition based on given gender. + * @returns Definition based on given sex. */ function selectDefinition( faker: Faker, - gender: GenderType | undefined, + sex: SexType | undefined, // TODO @Shinigami92 2022-03-21: Remove fallback empty object when `strict: true` { generic, @@ -33,13 +46,16 @@ function selectDefinition( }: { generic?: string[]; female?: string[]; male?: string[] } = {} ) { let values: string[] | undefined; - switch (gender) { - case 'female': + + switch (sex) { + case Sex.Female: values = female; break; - case 'male': + + case Sex.Male: values = male; break; + default: values = generic; break; @@ -73,7 +89,7 @@ export class Name { /** * Returns a random first name. * - * @param gender The optional gender to use. + * @param sex The optional sex to use. * Can be either `'female'` or `'male'`. * * @example @@ -81,11 +97,11 @@ export class Name { * faker.name.firstName('female') // 'Victoria' * faker.name.firstName('male') // 'Tom' */ - firstName(gender?: GenderType): string { + firstName(sex?: SexType): string { const { first_name, female_first_name, male_first_name } = this.faker.definitions.name; - return selectDefinition(this.faker, gender, { + return selectDefinition(this.faker, sex, { generic: first_name, female: female_first_name, male: male_first_name, @@ -95,7 +111,7 @@ export class Name { /** * Returns a random last name. * - * @param gender The optional gender to use. + * @param sex The optional sex to use. * Can be either `'female'` or `'male'`. * * @example @@ -103,11 +119,11 @@ export class Name { * faker.name.lastName('female') // 'Grady' * faker.name.lastName('male') // 'Barton' */ - lastName(gender?: GenderType): string { + lastName(sex?: SexType): string { const { last_name, female_last_name, male_last_name } = this.faker.definitions.name; - return selectDefinition(this.faker, gender, { + return selectDefinition(this.faker, sex, { generic: last_name, female: female_last_name, male: male_last_name, @@ -117,7 +133,7 @@ export class Name { /** * Returns a random middle name. * - * @param gender The optional gender to use. + * @param sex The optional sex to use. * Can be either `'female'` or `'male'`. * * @example @@ -125,11 +141,11 @@ export class Name { * faker.name.middleName('female') // 'Eloise' * faker.name.middleName('male') // 'Asher' */ - middleName(gender?: GenderType): string { + middleName(sex?: SexType): string { const { middle_name, female_middle_name, male_middle_name } = this.faker.definitions.name; - return selectDefinition(this.faker, gender, { + return selectDefinition(this.faker, sex, { generic: middle_name, female: female_middle_name, male: male_middle_name, @@ -141,8 +157,7 @@ export class Name { * * @param firstName The optional first name to use. If not specified a random one will be chosen. * @param lastName The optional last name to use. If not specified a random one will be chosen. - * @param gender The optional gender to use. - * Can be either `'female'` or `'male'`. + * @param sex The optional sex to use. Can be either `'female'` or `'male'`. * * @see faker.name.fullName() * @@ -155,14 +170,15 @@ export class Name { * * @deprecated Use faker.name.fullName() instead. */ - findName(firstName?: string, lastName?: string, gender?: GenderType): string { + findName(firstName?: string, lastName?: string, sex?: SexType): string { deprecated({ deprecated: 'faker.name.findName()', proposed: 'faker.name.fullName()', since: '7.4', until: '8.0', }); - return this.fullName({ firstName, lastName, gender }); + + return this.fullName({ firstName, lastName, sex }); } /** @@ -171,33 +187,45 @@ export class 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.gender The optional gender to use. - * Can be either `'female'` or `'male'`. + * @param options.sex The optional sex to use. Can be either `'female'` or `'male'`. + * @param options.gender Deprecated. Use `sex` instead. * * @example * faker.name.fullName() // 'Allen Brown' - * faker.name.fullName('Joann') // 'Joann Osinski' - * faker.name.fullName('Marcella', '', 'female') // 'Mrs. Marcella Huels' - * faker.name.fullName(undefined, 'Beer') // 'Mr. Alfonso Beer' - * faker.name.fullName(undefined, undefined, 'male') // 'Fernando Schaefer' + * 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' */ fullName( options: { firstName?: string; lastName?: string; gender?: GenderType; + sex?: SexType; } = {} ): string { const { - gender = this.faker.helpers.arrayElement(['female', 'male']), - firstName = this.firstName(gender), - lastName = this.lastName(gender), + gender, + sex = gender || this.faker.helpers.arrayElement([Sex.Female, Sex.Male]), + firstName = this.firstName(sex), + lastName = this.lastName(sex), } = options; + if (gender) { + deprecated({ + deprecated: `faker.name.fullName({ gender: '...' })`, + proposed: `faker.name.fullName({ sex: '...' })`, + since: '7.4', + until: '8.0', + }); + } + const nameParts: string[] = []; - const prefix = this.faker.helpers.maybe(() => this.prefix(gender), { + const prefix = this.faker.helpers.maybe(() => this.prefix(sex), { probability: 0.125, }); + if (prefix) { nameParts.push(prefix); } @@ -208,13 +236,12 @@ export class Name { const suffix = this.faker.helpers.maybe(() => this.suffix(), { probability: 0.125, }); + if (suffix) { nameParts.push(suffix); } - const fullName = nameParts.join(' '); - - return fullName; + return nameParts.join(' '); } /** @@ -239,18 +266,17 @@ export class Name { /** * Returns a random name prefix. * - * @param gender The optional gender to use. - * Can be either `'female'` or `'male'`. + * @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.' */ - prefix(gender?: GenderType): string { + prefix(sex?: SexType): string { const { prefix, female_prefix, male_prefix } = this.faker.definitions.name; - return selectDefinition(this.faker, gender, { + return selectDefinition(this.faker, sex, { generic: prefix, female: female_prefix, male: male_prefix, diff --git a/test/__snapshots__/name.spec.ts.snap b/test/__snapshots__/name.spec.ts.snap index dc56d58ea46..39043915c7c 100644 --- a/test/__snapshots__/name.spec.ts.snap +++ b/test/__snapshots__/name.spec.ts.snap @@ -14,7 +14,9 @@ exports[`name > 42 > firstName > with gender 1`] = `"Glen"`; exports[`name > 42 > fullName > noArgs 1`] = `"Sadie Wiegand"`; -exports[`name > 42 > fullName > with all 1`] = `"John Doe"`; +exports[`name > 42 > fullName > with all (gender) 1`] = `"John Doe"`; + +exports[`name > 42 > fullName > with all (sex) 1`] = `"John Doe"`; exports[`name > 42 > fullName > with firstName 1`] = `"John Schinner"`; @@ -22,6 +24,8 @@ exports[`name > 42 > fullName > with gender 1`] = `"Melanie Schinner"`; exports[`name > 42 > fullName > with lastName 1`] = `"Sadie Doe"`; +exports[`name > 42 > fullName > with sex 1`] = `"Melanie Schinner"`; + exports[`name > 42 > gender > noArgs 1`] = `"Gender nonconforming"`; exports[`name > 42 > gender > with gender 1`] = `"Female"`; @@ -64,7 +68,9 @@ exports[`name > 1211 > firstName > with gender 1`] = `"Percy"`; exports[`name > 1211 > fullName > noArgs 1`] = `"Claude Trantow"`; -exports[`name > 1211 > fullName > with all 1`] = `"John Doe"`; +exports[`name > 1211 > fullName > with all (gender) 1`] = `"John Doe"`; + +exports[`name > 1211 > fullName > with all (sex) 1`] = `"John Doe"`; exports[`name > 1211 > fullName > with firstName 1`] = `"John Koch"`; @@ -72,6 +78,8 @@ exports[`name > 1211 > fullName > with gender 1`] = `"Patti Koch"`; exports[`name > 1211 > fullName > with lastName 1`] = `"Claude Doe"`; +exports[`name > 1211 > fullName > with sex 1`] = `"Patti Koch"`; + exports[`name > 1211 > gender > noArgs 1`] = `"Trigender"`; exports[`name > 1211 > gender > with gender 1`] = `"Male"`; @@ -114,7 +122,9 @@ exports[`name > 1337 > firstName > with gender 1`] = `"Ray"`; exports[`name > 1337 > fullName > noArgs 1`] = `"Leona Cronin"`; -exports[`name > 1337 > fullName > with all 1`] = `"John Doe"`; +exports[`name > 1337 > fullName > with all (gender) 1`] = `"John Doe"`; + +exports[`name > 1337 > fullName > with all (sex) 1`] = `"John Doe"`; exports[`name > 1337 > fullName > with firstName 1`] = `"John Macejkovic"`; @@ -122,6 +132,8 @@ exports[`name > 1337 > fullName > with gender 1`] = `"Esther Macejkovic"`; exports[`name > 1337 > fullName > with lastName 1`] = `"Leona Doe"`; +exports[`name > 1337 > fullName > with sex 1`] = `"Esther Macejkovic"`; + exports[`name > 1337 > gender > noArgs 1`] = `"Demigender"`; exports[`name > 1337 > gender > with gender 1`] = `"Female"`; diff --git a/test/name.spec.ts b/test/name.spec.ts index 92dfe0929c7..a8ef5687571 100644 --- a/test/name.spec.ts +++ b/test/name.spec.ts @@ -33,11 +33,18 @@ describe('name', () => { t.it('noArgs') .it('with firstName', { firstName: 'John' }) .it('with lastName', { lastName: 'Doe' }) - .it('with gender', { gender: 'female' }) - .it('with all', { + .it('with gender', { gender: 'female' }) // deprecated + .it('with sex', { sex: 'female' }) + .it('with all (gender)', { firstName: 'John', lastName: 'Doe', + // deprecated gender: 'female', + }) + .it('with all (sex)', { + firstName: 'John', + lastName: 'Doe', + sex: 'female', }); }); }); @@ -57,7 +64,7 @@ describe('name', () => { expect(first_name.length).toBeGreaterThan(0); }); - it('should return a gender-specific first name', () => { + it('should return a sex-specific first name', () => { let name = faker.name.firstName('female'); expect(faker.definitions.name.female_first_name).toContain(name); @@ -65,7 +72,7 @@ describe('name', () => { expect(faker.definitions.name.male_first_name).toContain(name); }); - it('should return a gender-specific first name when no gender-specific first name was defined', () => { + it('should return a sex-specific first name when no sex-specific first name was defined', () => { faker.locale = 'az'; faker.localeFallback = 'az'; @@ -90,7 +97,7 @@ describe('name', () => { expect(last_name.length).toBeGreaterThan(0); }); - it('should return a gender-specific last name', () => { + it('should return a sex-specific last name', () => { faker.locale = 'az'; let name = faker.name.lastName('female'); @@ -127,7 +134,7 @@ describe('name', () => { expect(faker.definitions.name.male_middle_name).toContain(name); }); - it('should return a gender-specific middle name', () => { + it('should return a sex-specific middle name', () => { faker.locale = 'uk'; let name = faker.name.middleName('female'); @@ -151,7 +158,7 @@ describe('name', () => { expect(fullName).toContain(' '); }); - it('should return a female gender-specific name with firstName and lastName', () => { + it('should return a female sex-specific name with firstName and lastName', () => { faker.locale = 'mk'; const female_specific = [ @@ -169,7 +176,7 @@ describe('name', () => { } }); - it('should return a male gender-specific name with firstName and lastName', () => { + it('should return a male sex-specific name with firstName and lastName', () => { faker.locale = 'mk'; const male_specific = [ @@ -187,7 +194,7 @@ describe('name', () => { } }); - it('should return a female gender-specific name with given firstName and lastName', () => { + it('should return a female sex-specific name with given firstName and lastName', () => { faker.locale = 'mk'; const male_specific = [ @@ -209,7 +216,7 @@ describe('name', () => { } }); - it('should return a male gender-specific name with given firstName and lastName', () => { + it('should return a male sex-specific name with given firstName and lastName', () => { faker.locale = 'mk'; const male_specific = [