refactor(name.findName): rename to fullName (#1127)

3 files changed, 150 insertions, 11 deletions

diff --git a/src/modules/name/index.ts b/src/modules/name/index.ts
index 009b35fc..07a4164d 100644
--- a/src/modules/name/index.ts
+++ b/src/modules/name/index.ts
@@ -1,4 +1,5 @@
 import type { Faker } from '../..';
+import { deprecated } from '../../internal/deprecated';
 
 export enum Gender {
   female = 'female',
@@ -140,19 +141,55 @@ export class Name {
    * @param gender The optional gender to use.
    * Can be either `'female'` or `'male'`.
    *
+   * @see faker.name.fullName()
+   *
    * @example
    * faker.name.findName() // 'Allen Brown'
    * faker.name.findName('Joann') // 'Joann Osinski'
    * faker.name.findName('Marcella', '', 'female') // 'Mrs. Marcella Huels'
    * faker.name.findName(undefined, 'Beer') // 'Mr. Alfonso Beer'
    * faker.name.findName(undefined, undefined, 'male') // 'Fernando Schaefer'
+   *
+   * @deprecated Use faker.name.fullName() instead.
    */
   findName(firstName?: string, lastName?: string, gender?: GenderType): string {
-    const normalizedGender: GenderType =
-      gender ?? this.faker.helpers.arrayElement(['female', 'male']);
+    deprecated({
+      deprecated: 'faker.name.findName()',
+      proposed: 'faker.name.fullName()',
+      since: '7.4',
+      until: '8.0',
+    });
+    return this.fullName({ firstName, lastName, gender });
+  }
 
-    firstName = firstName || this.firstName(normalizedGender);
-    lastName = lastName || this.lastName(normalizedGender);
+  /**
+   * 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.gender The optional gender to use.
+   * Can be either `'female'` or `'male'`.
+   *
+   * @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'
+   */
+  fullName(
+    options: {
+      firstName?: string;
+      lastName?: string;
+      gender?: GenderType;
+    } = {}
+  ): string {
+    const {
+      gender = this.faker.helpers.arrayElement(['female', 'male']),
+      firstName = this.firstName(gender),
+      lastName = this.lastName(gender),
+    } = options;
 
     const nameParts: string[] = [];
     const prefix = this.faker.helpers.maybe(() => this.prefix(gender), {
diff --git a/test/__snapshots__/name.spec.ts.snap b/test/__snapshots__/name.spec.ts.snap
index e07b6047..32cd8cdc 100644
--- a/test/__snapshots__/name.spec.ts.snap
+++ b/test/__snapshots__/name.spec.ts.snap
@@ -4,6 +4,8 @@ exports[`name > seed: 42 > findName() 1`] = `"Sadie Wiegand"`;
 
 exports[`name > seed: 42 > firstName() 1`] = `"Garnett"`;
 
+exports[`name > seed: 42 > fullName() 1`] = `"Sadie Wiegand"`;
+
 exports[`name > seed: 42 > gender() 1`] = `"Gender nonconforming"`;
 
 exports[`name > seed: 42 > jobArea() 1`] = `"Identity"`;
@@ -26,6 +28,8 @@ exports[`name > seed: 1211 > findName() 1`] = `"Claude Trantow"`;
 
 exports[`name > seed: 1211 > firstName() 1`] = `"Tito"`;
 
+exports[`name > seed: 1211 > fullName() 1`] = `"Claude Trantow"`;
+
 exports[`name > seed: 1211 > gender() 1`] = `"Trigender"`;
 
 exports[`name > seed: 1211 > jobArea() 1`] = `"Factors"`;
@@ -48,6 +52,8 @@ exports[`name > seed: 1337 > findName() 1`] = `"Leona Cronin"`;
 
 exports[`name > seed: 1337 > firstName() 1`] = `"Devyn"`;
 
+exports[`name > seed: 1337 > fullName() 1`] = `"Leona Cronin"`;
+
 exports[`name > seed: 1337 > gender() 1`] = `"Demigender"`;
 
 exports[`name > seed: 1337 > jobArea() 1`] = `"Functionality"`;
diff --git a/test/name.spec.ts b/test/name.spec.ts
index 1d9f4421..c7baf5a9 100644
--- a/test/name.spec.ts
+++ b/test/name.spec.ts
@@ -1,21 +1,23 @@
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { faker } from '../src';
+import type { Name } from '../src/modules/name';
 import { seededRuns } from './support/seededRuns';
 
 const NON_SEEDED_BASED_RUN = 5;
 
-const functionNames = [
+const functionNames: (keyof Name)[] = [
+  'findName',
   'firstName',
+  'fullName',
+  'gender',
+  'jobArea',
+  'jobDescriptor',
+  'jobTitle',
+  'jobType',
   'lastName',
   'middleName',
-  'findName',
-  'jobTitle',
-  'gender',
   'prefix',
   'suffix',
-  'jobDescriptor',
-  'jobArea',
-  'jobType',
 ];
 
 describe('name', () => {
@@ -226,6 +228,100 @@ describe('name', () => {
         });
       });
 
+      describe('fullName()', () => {
+        beforeEach(() => {
+          faker.locale = 'en';
+          faker.localeFallback = 'en';
+        });
+
+        it('should return a name with firstName and lastName', () => {
+          const fullName = faker.name.fullName();
+
+          expect(fullName).toBeTypeOf('string');
+          expect(fullName).toContain(' ');
+        });
+
+        it('should return a female gender-specific name without firstName and lastName', () => {
+          faker.locale = 'mk';
+
+          const female_specific = [
+            ...faker.definitions.name.female_prefix,
+            ...faker.definitions.name.female_first_name,
+            ...faker.definitions.name.female_last_name,
+            ...faker.definitions.name.suffix,
+          ];
+
+          const fullName = faker.name.fullName({ gender: 'female' });
+
+          const parts = fullName.split(' ');
+          for (const part of parts) {
+            expect(female_specific).toContain(part);
+          }
+        });
+
+        it('should return a male gender-specific name without firstName and lastName', () => {
+          faker.locale = 'mk';
+
+          const male_specific = [
+            ...faker.definitions.name.male_prefix,
+            ...faker.definitions.name.male_first_name,
+            ...faker.definitions.name.male_last_name,
+            ...faker.definitions.name.suffix,
+          ];
+
+          const fullName = faker.name.fullName({ gender: 'male' });
+
+          const parts = fullName.split(' ');
+          for (const part of parts) {
+            expect(male_specific).toContain(part);
+          }
+        });
+
+        it('should return a female gender-specific name with given firstName and lastName', () => {
+          faker.locale = 'mk';
+
+          const male_specific = [
+            ...faker.definitions.name.female_prefix,
+            'firstName',
+            'lastName',
+            ...faker.definitions.name.suffix,
+          ];
+
+          const fullName = faker.name.fullName({
+            firstName: 'firstName',
+            lastName: 'lastName',
+            gender: 'female',
+          });
+
+          const parts = fullName.split(' ');
+          for (const part of parts) {
+            expect(male_specific).toContain(part);
+          }
+        });
+
+        it('should return a male gender-specific name with given firstName and lastName', () => {
+          faker.locale = 'mk';
+
+          const male_specific = [
+            ...faker.definitions.name.male_prefix,
+            'firstName',
+            'lastName',
+            ...faker.definitions.name.suffix,
+          ];
+
+          const fullName = faker.name.fullName({
+            firstName: 'firstName',
+            lastName: 'lastName',
+            gender: 'male',
+          });
+
+          const parts = fullName.split(' ');
+          for (const part of parts) {
+            expect(male_specific).toContain(part);
+          }
+        });
+      });
+
       describe('gender()', () => {
         beforeEach(() => {
           faker.locale = 'en';