feat(person): sexType can return 'generic' (#3259)

Co-authored-by: Eric Cheng <[email protected]>
Co-authored-by: xDivisionByZerox <[email protected]>
Co-authored-by: Matt Mayer <[email protected]>
Co-authored-by: Shinigami <[email protected]>

Author: 5 people

src/definitions/person.ts

@@ -1,15 +1,30 @@
 import type { LocaleEntry } from './definitions';
 
+/**
+ * Entries that are dependent on a person's sex.
+ */
 export type PersonEntryDefinition<T> =
   | {
+      /**
+       * Values that are primarily attributable to only females.
+       */
+      female: T[];
+      /**
+       * Values that cannot clearly be attributed to a specific sex or are used for both sexes.
+       */
       generic?: T[];
+      /**
+       * Values that are primarily attributable to only males.
+       */
       male: T[];
-      female: T[];
     }
   | {
+      female?: never;
+      /**
+       * Values that cannot clearly be attributed to a specific sex or are used for both sexes.
+       */
       generic: T[];
       male?: never;
-      female?: never;
     };
 
 type SimplePersonEntryDefinition = PersonEntryDefinition<string>;

src/modules/image/index.ts

@@ -60,7 +60,7 @@ export class ImageModule extends ModuleBase {
    * The image URLs are served via the JSDelivr CDN and subject to their [terms of use](https://www.jsdelivr.com/terms).
    *
    * @param options Options for generating an AI avatar.
-   * @param options.sex The sex of the person for the avatar. Can be `'female'` or `'male'`. If not provided, defaults to a random selection.
+   * @param options.sex The sex of the person for the avatar. Can be `'female'` or `'male'`. If not provided or `'generic'`, defaults to a random selection.
    * @param options.size The size of the image. Can be `512`, `256`, `128`, `64` or `32`. If not provided, defaults to `512`.
    *
    * @example
@@ -73,7 +73,7 @@ export class ImageModule extends ModuleBase {
     options: {
       /**
        * The sex of the person for the avatar.
-       * Can be `'female'` or `'male'`.
+       * Can be `'female'` or `'male'`. `'generic'` uses a random selection.
        *
        * @default faker.person.sexType()
        */
@@ -87,7 +87,13 @@ export class ImageModule extends ModuleBase {
       size?: 512 | 256 | 128 | 64 | 32;
     } = {}
   ): string {
-    const { sex = this.faker.person.sexType(), size = 512 } = options;
+    const { size = 512 } = options;
+    let { sex = this.faker.person.sexType() } = options;
+
+    if (sex === 'generic') {
+      sex = this.faker.person.sexType();
+    }
+
     const baseURL =
       'https://cdn.jsdelivr.net/gh/faker-js/assets-person-portrait';
     return `${baseURL}/${sex}/${size}/${this.faker.number.int({ min: 0, max: 99 })}.jpg`;

src/modules/person/index.ts

@@ -2,11 +2,27 @@ import type { Faker } from '../..';
 import type { PersonEntryDefinition } from '../../definitions/person';
 import { ModuleBase } from '../../internal/module-base';
 
+/**
+ * The enum for values corresponding to a person's sex.
+ */
 export enum Sex {
+  /**
+   * Is used for values that are primarily attributable to only females.
+   */
   Female = 'female',
+  /**
+   * Is used for values that cannot clearly be attributed to a specific sex or are used for both sexes.
+   */
+  Generic = 'generic',
+  /**
+   * Is used for values that are primarily attributable to only males.
+   */
   Male = 'male',
 }
 
+/**
+ * The parameter type for values corresponding to a person's sex.
+ */
 export type SexType = `${Sex}`;
 
 /**
@@ -20,30 +36,48 @@ export type SexType = `${Sex}`;
  */
 function selectDefinition<T>(
   faker: Faker,
-  sex: SexType | undefined,
+  sex: SexType = faker.person.sexType(),
   personEntry: PersonEntryDefinition<T>
 ): T[] {
   const { generic, female, male } = personEntry;
-  switch (sex) {
-    case Sex.Female: {
-      return female ?? generic;
-    }
 
-    case Sex.Male: {
-      return male ?? generic;
-    }
+  if (sex === 'generic') {
+    return (
+      generic ??
+      faker.helpers.arrayElement([female, male]) ??
+      // The last statement should never happen at run time. At this point in time,
+      // the entry will satisfy at least (generic || (female && male)).
+      // TS is not able to infer the type correctly.
+      []
+    );
+  }
 
-    default: {
-      return (
-        generic ??
-        faker.helpers.arrayElement([female, male]) ??
-        // The last statement should never happen at run time. At this point in time,
-        // the entry will satisfy at least (generic || (female && male)).
-        // TS is not able to infer the type correctly.
-        []
-      );
+  const binary = sex === 'female' ? female : male;
+
+  if (binary != null) {
+    if (generic != null) {
+      return faker.helpers.weightedArrayElement([
+        {
+          weight: 3 * Math.sqrt(binary.length),
+          value: binary,
+        },
+        {
+          weight: Math.sqrt(generic.length),
+          value: generic,
+        },
+      ]);
     }
+
+    return binary;
   }
+
+  return (
+    generic ??
+    // The last statement should never happen at run time. At this point in time,
+    // the entry will satisfy at least (generic || (female && male)).
+    // TS is not able to infer the type correctly.
+    []
+  );
 }
 
 /**
@@ -238,16 +272,38 @@ export class PersonModule extends ModuleBase {
   /**
    * Returns a random sex type. The `SexType` is intended to be used in parameters and conditions.
    *
+   * @param options The optional options object.
+   * @param options.includeGeneric Whether `'generic'` should be included in the potential outputs.
+   * If `false`, this method only returns `'female'` and `'male'`.
+   * Default is `false`.
+   *
    * @see faker.person.gender(): For generating a gender related value in forms.
    * @see faker.person.sex(): For generating a binary-gender value in forms.
    *
    * @example
    * faker.person.sexType() // Sex.Female
+   * faker.person.sexType({ includeGeneric: true }) // Sex.Generic
    *
    * @since 8.0.0
    */
-  sexType(): SexType {
-    return this.faker.helpers.enumValue(Sex);
+  sexType(
+    options: {
+      /**
+       * Whether `'generic'` should be included in the potential outputs.
+       * If `false`, this method only returns `'female'` and `'male'`.
+       *
+       * @default false
+       */
+      includeGeneric?: boolean;
+    } = {}
+  ): SexType {
+    const { includeGeneric = false } = options;
+
+    if (includeGeneric) {
+      return this.faker.helpers.enumValue(Sex);
+    }
+
+    return this.faker.helpers.arrayElement([Sex.Female, Sex.Male]);
   }
 
   /**

test/modules/__snapshots__/git.spec.ts.snap

@@ -10,28 +10,28 @@ exports[`git > 42 > commitDate > with only string refDate 1`] = `"Tue Dec 31 08:
 
 exports[`git > 42 > commitEntry > with only Date refDate 1`] = `
 "commit ead331ddf0fc4446b96d368ab4bd1d31efb62f92
-Author: Jerome Vandervort <Jerome_Vandervort@yahoo.com>
-Date: Tue Dec 31 14:20:57 2019 +1100
+Author: Suzanne.Hahn <Suzanne_Hahn92@yahoo.com>
+Date: Tue Dec 31 04:42:12 2019 -1000
 
-    bypass bluetooth application
+    copy haptic card
 "
 `;
 
 exports[`git > 42 > commitEntry > with only number refDate 1`] = `
 "commit ead331ddf0fc4446b96d368ab4bd1d31efb62f92
-Author: Jerome Vandervort <Jerome_Vandervort@yahoo.com>
-Date: Tue Dec 31 14:20:57 2019 +1100
+Author: Suzanne.Hahn <Suzanne_Hahn92@yahoo.com>
+Date: Tue Dec 31 04:42:12 2019 -1000
 
-    bypass bluetooth application
+    copy haptic card
 "
 `;
 
 exports[`git > 42 > commitEntry > with only string refDate 1`] = `
 "commit ead331ddf0fc4446b96d368ab4bd1d31efb62f92
-Author: Jerome Vandervort <Jerome_Vandervort@yahoo.com>
-Date: Tue Dec 31 14:20:57 2019 +1100
+Author: Suzanne.Hahn <Suzanne_Hahn92@yahoo.com>
+Date: Tue Dec 31 04:42:12 2019 -1000
 
-    bypass bluetooth application
+    copy haptic card
 "
 `;
 
@@ -53,28 +53,28 @@ exports[`git > 1211 > commitDate > with only string refDate 1`] = `"Tue Dec 31 2
 
 exports[`git > 1211 > commitEntry > with only Date refDate 1`] = `
 "commit d4fefa7fbaec9dc4c48fa8ebf46fb7c8563cf3fa
-Author: Deion Durgan <Deion.Durgan@yahoo.com>
-Date: Tue Dec 31 11:08:15 2019 -0600
+Author: Debbie.Kshlerin70 <Debbie.Kshlerin@hotmail.com>
+Date: Tue Dec 31 20:55:12 2019 -0900
 
-    override solid state array
+    reboot multi-byte feed
 "
 `;
 
 exports[`git > 1211 > commitEntry > with only number refDate 1`] = `
 "commit d4fefa7fbaec9dc4c48fa8ebf46fb7c8563cf3fa
-Author: Deion Durgan <Deion.Durgan@yahoo.com>
-Date: Tue Dec 31 11:08:15 2019 -0600
+Author: Debbie.Kshlerin70 <Debbie.Kshlerin@hotmail.com>
+Date: Tue Dec 31 20:55:12 2019 -0900
 
-    override solid state array
+    reboot multi-byte feed
 "
 `;
 
 exports[`git > 1211 > commitEntry > with only string refDate 1`] = `
 "commit d4fefa7fbaec9dc4c48fa8ebf46fb7c8563cf3fa
-Author: Deion Durgan <Deion.Durgan@yahoo.com>
-Date: Tue Dec 31 11:08:15 2019 -0600
+Author: Debbie.Kshlerin70 <Debbie.Kshlerin@hotmail.com>
+Date: Tue Dec 31 20:55:12 2019 -0900
 
-    override solid state array
+    reboot multi-byte feed
 "
 `;
 
@@ -96,28 +96,28 @@ exports[`git > 1337 > commitDate > with only string refDate 1`] = `"Tue Dec 31 0
 
 exports[`git > 1337 > commitEntry > with only Date refDate 1`] = `
 "commit 36a7b5fa28d2f9bb79ca46ea394bc4f9bb0af328
-Author: Matt_Hills <Matt_Hills99@hotmail.com>
-Date: Tue Dec 31 00:20:42 2019 -0900
+Author: Gene_Heller <Gene.Heller1@yahoo.com>
+Date: Tue Dec 31 22:32:07 2019 +1200
 
-    synthesize wireless hard drive
+    index haptic pixel
 "
 `;
 
 exports[`git > 1337 > commitEntry > with only number refDate 1`] = `
 "commit 36a7b5fa28d2f9bb79ca46ea394bc4f9bb0af328
-Author: Matt_Hills <Matt_Hills99@hotmail.com>
-Date: Tue Dec 31 00:20:42 2019 -0900
+Author: Gene_Heller <Gene.Heller1@yahoo.com>
+Date: Tue Dec 31 22:32:07 2019 +1200
 
-    synthesize wireless hard drive
+    index haptic pixel
 "
 `;
 
 exports[`git > 1337 > commitEntry > with only string refDate 1`] = `
 "commit 36a7b5fa28d2f9bb79ca46ea394bc4f9bb0af328
-Author: Matt_Hills <Matt_Hills99@hotmail.com>
-Date: Tue Dec 31 00:20:42 2019 -0900
+Author: Gene_Heller <Gene.Heller1@yahoo.com>
+Date: Tue Dec 31 22:32:07 2019 +1200
 
-    synthesize wireless hard drive
+    index haptic pixel
 "
 `;