chore: rename Gender to Sex (#1163)

Co-authored-by: Leyla Jähnig <[email protected]>
Co-authored-by: Shinigami <[email protected]>

2 files changed, 68 insertions, 42 deletions

diff --git a/src/index.ts b/src/index.ts
index 8a6b7ecc..e3b223b0 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 3ff775e2..0a67c382 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,