feat(name): extract sex generator from gender to sex (#1168)

src/definitions/name.ts

@@ -5,7 +5,7 @@ import type { LocaleEntry } from './definitions';
  */
 export type NameDefinitions = LocaleEntry<{
   gender: string[];
-  binary_gender: string[];
+  sex: string[];
 
   prefix?: string[];
   female_prefix?: string[];

src/locales/de/name/index.ts

@@ -10,6 +10,7 @@ import male_first_name from './male_first_name';
 import name_ from './name';
 import nobility_title_prefix from './nobility_title_prefix';
 import prefix from './prefix';
+import sex from './sex';
 
 const name: NameDefinitions = {
   female_first_name,
@@ -19,6 +20,7 @@ const name: NameDefinitions = {
   name: name_,
   nobility_title_prefix,
   prefix,
+  sex,
 };
 
 export default name;

src/locales/de/name/sex.ts

@@ -0,0 +1 @@
+export default ['männlich', 'weiblich'];

src/locales/en/name/index.ts

@@ -3,7 +3,6 @@
  * Run 'pnpm run generate:locales' to update.
  */
 import type { NameDefinitions } from '../../..';
-import binary_gender from './binary_gender';
 import female_first_name from './female_first_name';
 import female_middle_name from './female_middle_name';
 import first_name from './first_name';
@@ -14,11 +13,11 @@ import male_middle_name from './male_middle_name';
 import middle_name from './middle_name';
 import name_ from './name';
 import prefix from './prefix';
+import sex from './sex';
 import suffix from './suffix';
 import title from './title';
 
 const name: NameDefinitions = {
-  binary_gender,
   female_first_name,
   female_middle_name,
   first_name,
@@ -29,6 +28,7 @@ const name: NameDefinitions = {
   middle_name,
   name: name_,
   prefix,
+  sex,
   suffix,
   title,
 };

src/locales/en/name/sex.ts

@@ -0,0 +1 @@
+export default ['female', 'male'];

src/locales/fr/name/index.ts

@@ -3,23 +3,23 @@
  * Run 'pnpm run generate:locales' to update.
  */
 import type { NameDefinitions } from '../../..';
-import binary_gender from './binary_gender';
 import female_first_name from './female_first_name';
 import first_name from './first_name';
 import last_name from './last_name';
 import male_first_name from './male_first_name';
 import name_ from './name';
 import prefix from './prefix';
+import sex from './sex';
 import title from './title';
 
 const name: NameDefinitions = {
-  binary_gender,
   female_first_name,
   first_name,
   last_name,
   male_first_name,
   name: name_,
   prefix,
+  sex,
   title,
 };
 

src/locales/fr_CH/name/index.ts

@@ -3,23 +3,23 @@
  * Run 'pnpm run generate:locales' to update.
  */
 import type { NameDefinitions } from '../../..';
-import binary_gender from './binary_gender';
 import female_first_name from './female_first_name';
 import first_name from './first_name';
 import last_name from './last_name';
 import male_first_name from './male_first_name';
 import name_ from './name';
 import prefix from './prefix';
+import sex from './sex';
 import title from './title';
 
 const name: NameDefinitions = {
-  binary_gender,
   female_first_name,
   first_name,
   last_name,
   male_first_name,
   name: name_,
   prefix,
+  sex,
   title,
 };
 

src/locales/pl/name/index.ts

@@ -3,25 +3,25 @@
  * Run 'pnpm run generate:locales' to update.
  */
 import type { NameDefinitions } from '../../..';
-import binary_gender from './binary_gender';
 import female_first_name from './female_first_name';
 import first_name from './first_name';
 import gender from './gender';
 import last_name from './last_name';
 import male_first_name from './male_first_name';
 import name_ from './name';
 import prefix from './prefix';
+import sex from './sex';
 import title from './title';
 
 const name: NameDefinitions = {
-  binary_gender,
   female_first_name,
   first_name,
   gender,
   last_name,
   male_first_name,
   name: name_,
   prefix,
+  sex,
   title,
 };
 

src/locales/pl/name/sex.ts

@@ -0,0 +1 @@
+export default ['kobieta', 'mężczyzna'];

src/locales/pt_BR/name/index.ts

@@ -3,24 +3,24 @@
  * Run 'pnpm run generate:locales' to update.
  */
 import type { NameDefinitions } from '../../..';
-import binary_gender from './binary_gender';
 import female_first_name from './female_first_name';
 import first_name from './first_name';
 import last_name from './last_name';
 import male_first_name from './male_first_name';
 import name_ from './name';
 import prefix from './prefix';
+import sex from './sex';
 import suffix from './suffix';
 import title from './title';
 
 const name: NameDefinitions = {
-  binary_gender,
   female_first_name,
   first_name,
   last_name,
   male_first_name,
   name: name_,
   prefix,
+  sex,
   suffix,
   title,
 };

src/locales/ur/name/index.ts

@@ -3,24 +3,24 @@
  * Run 'pnpm run generate:locales' to update.
  */
 import type { NameDefinitions } from '../../..';
-import binary_gender from './binary_gender';
 import female_first_name from './female_first_name';
 import first_name from './first_name';
 import last_name from './last_name';
 import male_first_name from './male_first_name';
 import name_ from './name';
 import prefix from './prefix';
+import sex from './sex';
 import suffix from './suffix';
 import title from './title';
 
 const name: NameDefinitions = {
-  binary_gender,
   female_first_name,
   first_name,
   last_name,
   male_first_name,
   name: name_,
   prefix,
+  sex,
   suffix,
   title,
 };

src/modules/name/index.ts

@@ -245,24 +245,45 @@ export class Name {
   }
 
   /**
-   * Return a random gender.
+   * Returns a random gender.
    *
-   * @param binary Whether to return only binary gender names. Defaults to `false`.
+   * @param binary (deprecated) Whether to return only binary gender names. Defaults to `false`.
+   *
+   * @see faker.name.sex() if you would like to generate binary-gender value
    *
    * @example
    * faker.name.gender() // 'Trans*Man'
-   * faker.name.gender(true) // 'Female'
    */
   gender(binary?: boolean): string {
     if (binary) {
-      return this.faker.helpers.arrayElement(
-        this.faker.definitions.name.binary_gender
-      );
+      deprecated({
+        deprecated: 'faker.name.gender(true)',
+        proposed: 'faker.name.sex()',
+        since: '7.5',
+        until: '8.0',
+      });
+
+      return this.faker.name.sex();
     }
 
     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'
+   */
+  sex(): string {
+    return this.faker.helpers.arrayElement(this.faker.definitions.name.sex);
+  }
+
   /**
    * Returns a random name prefix.
    *

test/__snapshots__/name.spec.ts.snap

@@ -28,7 +28,7 @@ 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"`;
+exports[`name > 42 > gender > with gender 1`] = `"female"`;
 
 exports[`name > 42 > jobArea 1`] = `"Identity"`;
 
@@ -50,6 +50,10 @@ exports[`name > 42 > prefix > noArgs 1`] = `"Mrs."`;
 
 exports[`name > 42 > prefix > with gender 1`] = `"Mrs."`;
 
+exports[`name > 42 > sex > noArgs 1`] = `"female"`;
+
+exports[`name > 42 > sex > with gender 1`] = `"female"`;
+
 exports[`name > 42 > suffix > noArgs 1`] = `"III"`;
 
 exports[`name > 42 > suffix > with gender 1`] = `"III"`;
@@ -82,7 +86,7 @@ exports[`name > 1211 > fullName > with sex 1`] = `"Patti Koch"`;
 
 exports[`name > 1211 > gender > noArgs 1`] = `"Trigender"`;
 
-exports[`name > 1211 > gender > with gender 1`] = `"Male"`;
+exports[`name > 1211 > gender > with gender 1`] = `"male"`;
 
 exports[`name > 1211 > jobArea 1`] = `"Factors"`;
 
@@ -104,6 +108,10 @@ exports[`name > 1211 > prefix > noArgs 1`] = `"Dr."`;
 
 exports[`name > 1211 > prefix > with gender 1`] = `"Dr."`;
 
+exports[`name > 1211 > sex > noArgs 1`] = `"male"`;
+
+exports[`name > 1211 > sex > with gender 1`] = `"male"`;
+
 exports[`name > 1211 > suffix > noArgs 1`] = `"DVM"`;
 
 exports[`name > 1211 > suffix > with gender 1`] = `"DVM"`;
@@ -136,7 +144,7 @@ exports[`name > 1337 > fullName > with sex 1`] = `"Esther Macejkovic"`;
 
 exports[`name > 1337 > gender > noArgs 1`] = `"Demigender"`;
 
-exports[`name > 1337 > gender > with gender 1`] = `"Female"`;
+exports[`name > 1337 > gender > with gender 1`] = `"female"`;
 
 exports[`name > 1337 > jobArea 1`] = `"Functionality"`;
 
@@ -158,6 +166,10 @@ exports[`name > 1337 > prefix > noArgs 1`] = `"Mrs."`;
 
 exports[`name > 1337 > prefix > with gender 1`] = `"Mrs."`;
 
+exports[`name > 1337 > sex > noArgs 1`] = `"female"`;
+
+exports[`name > 1337 > sex > with gender 1`] = `"female"`;
+
 exports[`name > 1337 > suffix > noArgs 1`] = `"I"`;
 
 exports[`name > 1337 > suffix > with gender 1`] = `"I"`;

test/name.spec.ts

@@ -19,6 +19,7 @@ describe('name', () => {
       'middleName',
       'gender',
       'prefix',
+      'sex',
       'suffix'
     )((t) => t.it('noArgs').it('with gender', 'male'));
 
@@ -346,7 +347,21 @@ describe('name', () => {
           const gender = faker.name.gender(true);
 
           expect(gender).toBeTypeOf('string');
-          expect(faker.definitions.name.binary_gender).toContain(gender);
+          expect(faker.definitions.name.sex).toContain(gender);
+        });
+      });
+
+      describe('sex()', () => {
+        beforeEach(() => {
+          faker.locale = 'en';
+          faker.localeFallback = 'en';
+        });
+
+        it('should return a sex', () => {
+          const sex = faker.name.sex();
+
+          expect(sex).toBeTypeOf('string');
+          expect(faker.definitions.name.sex).toContain(sex);
         });
       });
 

test/scripts/apidoc/examplesAndDeprecations.spec.ts

@@ -17,7 +17,7 @@ import { loadProject } from './utils';
 /*
  * This test ensures, that every method
  * - has working examples
- * - and running these does not log anything, unless the method is deprecated
+ * - and running these do not log anything, unless the method is deprecated
  */
 
 const locales: Record<string, string> = {