refactor(person)!: rename name module (#1445)

Co-authored-by: ST-DDT <ST-DDT@gmx.de>

Author: Shinigami92

README.md

@@ -88,7 +88,7 @@ The API covers the following modules:
 | Internet | `faker.internet.domainName()`                 | muddy-neuropathologist.net                                                                         |
 | Lorem    | `faker.lorem.paragraph()`                     | Porro nulla id vero perspiciatis nulla nihil. ...                                                  |
 | Music    | `faker.music.genre()`                         | R&B                                                                                                |
-| Name     | `faker.name.firstName()`                      | Cameron                                                                                            |
+| Person   | `faker.person.firstName()`                    | Cameron                                                                                            |
 | Phone    | `faker.phone.phoneNumber()`                   | +1 291-299-0192                                                                                    |
 | Random   | `faker.random.locale()`                       | fr_CA                                                                                              |
 | Science  | `faker.science.unit()`                        | `{ name: 'meter', symbol: 'm' }`                                                                   |
@@ -103,7 +103,7 @@ Faker contains a generator method `faker.helpers.fake` for combining faker API m
 ```ts
 console.log(
   faker.helpers.fake(
-    'Hello {{name.prefix}} {{name.lastName}}, how are you today?'
+    'Hello {{person.prefix}} {{person.lastName}}, how are you today?'
   )
 );
 ```

docs/.vitepress/api-pages.ts

@@ -18,7 +18,7 @@ export const apiPages = [
   { text: 'Internet', link: '/api/internet.html' },
   { text: 'Lorem', link: '/api/lorem.html' },
   { text: 'Music', link: '/api/music.html' },
-  { text: 'Name', link: '/api/name.html' },
+  { text: 'Person', link: '/api/person.html' },
   { text: 'Phone', link: '/api/phone.html' },
   { text: 'Random', link: '/api/random.html' },
   { text: 'Science', link: '/api/science.html' },

docs/guide/usage.md

@@ -7,7 +7,7 @@ Using Faker is as easy as importing it from `@faker-js/faker`.
 ```js
 import { faker } from '@faker-js/faker';
 
-const randomName = faker.name.fullName(); // Rowan Nikolaus
+const randomName = faker.person.fullName(); // Rowan Nikolaus
 const randomEmail = faker.internet.email(); // Kassandra.Haley@erich.biz
 ```
 
@@ -16,7 +16,7 @@ Or if you using CommonJS
 ```js
 const { faker } = require('@faker-js/faker');
 
-const randomName = faker.name.fullName(); // Rowan Nikolaus
+const randomName = faker.person.fullName(); // Rowan Nikolaus
 const randomEmail = faker.internet.email(); // Kassandra.Haley@erich.biz
 ```
 
@@ -27,7 +27,7 @@ const randomEmail = faker.internet.email(); // Kassandra.Haley@erich.biz
   import { faker } from 'https://cdn.skypack.dev/@faker-js/faker';
 
   // Caitlyn Kerluke
-  const randomName = faker.name.fullName();
+  const randomName = faker.person.fullName();
 
   // Rusty@arne.info
   const randomEmail = faker.internet.email();
@@ -43,7 +43,7 @@ Using the browser is great for experimenting 👍. However, due to all of the st
 ```js
 import { faker } from 'https://cdn.skypack.dev/@faker-js/faker';
 
-const randomName = faker.name.findName(); // Willie Bahringer
+const randomName = faker.person.findName(); // Willie Bahringer
 const randomEmail = faker.internet.email(); // Tomasa_Ferry14@hotmail.com
 ```
 
@@ -120,9 +120,9 @@ function createRandomUser(): User {
     avatar: faker.image.avatar(),
     birthday: faker.date.birthdate(),
     email: faker.internet.email(),
-    firstName: faker.name.firstName(),
-    lastName: faker.name.lastName(),
-    sex: faker.name.sexType(),
+    firstName: faker.person.firstName(),
+    lastName: faker.person.lastName(),
+    sex: faker.person.sexType(),
     subscriptionTier: faker.helpers.arrayElement(['free', 'basic', 'business']),
   };
 }
@@ -142,9 +142,9 @@ Let's refactor our current code:
 import { faker } from '@faker-js/faker';
 
 function createRandomUser(): User {
-  const sex = this.faker.name.sexType();
-  const firstName = faker.name.firstName(sex);
-  const lastName = faker.name.lastName();
+  const sex = this.faker.person.sexType();
+  const firstName = faker.person.firstName(sex);
+  const lastName = faker.person.lastName();
   const email = faker.internet.email(firstName, lastName);
 
   return {
@@ -179,9 +179,9 @@ Faker has your back, with another helper method:
 import { faker } from '@faker-js/faker';
 
 function createRandomUser(): User {
-  const sex = this.faker.name.sexType();
-  const firstName = faker.name.firstName(sex);
-  const lastName = faker.name.lastName();
+  const sex = this.faker.person.sexType();
+  const firstName = faker.person.firstName(sex);
+  const lastName = faker.person.lastName();
   const email = faker.helpers.unique(faker.internet.email, [
     firstName,
     lastName,

scripts/apidoc/moduleMethods.ts

@@ -38,7 +38,13 @@ export function processModuleMethods(project: ProjectReflection): PageIndex {
 }
 
 export function extractModuleName(module: DeclarationReflection): string {
-  return module.name.replace(/Module$/, '');
+  const { name } = module;
+  // TODO @ST-DDT 2022-10-16: Remove in v10.
+  // Typedoc prefers the name of the module that is exported first.
+  if (name === 'NameModule') {
+    return 'Person';
+  }
+  return name.replace(/Module$/, '');
 }
 
 function extractModuleFieldName(module: DeclarationReflection): string {

scripts/generateLocales.ts

@@ -57,7 +57,7 @@ const definitionsTypes: DefinitionsType = {
   internet: 'InternetDefinitions',
   lorem: 'LoremDefinitions',
   music: 'MusicDefinitions',
-  name: 'NameDefinitions',
+  person: 'PersonDefinitions',
   phone_number: 'PhoneNumberDefinitions',
   science: 'ScienceDefinitions',
   system: 'SystemDefinitions',

src/definitions/definitions.ts

@@ -10,7 +10,7 @@ import type { HackerDefinitions } from './hacker';
 import type { InternetDefinitions } from './internet';
 import type { LoremDefinitions } from './lorem';
 import type { MusicDefinitions } from './music';
-import type { NameDefinitions } from './name';
+import type { PersonDefinitions } from './person';
 import type { PhoneNumberDefinitions } from './phone_number';
 import type { ScienceDefinitions } from './science';
 import type { SystemDefinitions } from './system';
@@ -38,7 +38,7 @@ export interface Definitions {
   internet: InternetDefinitions;
   lorem: LoremDefinitions;
   music: MusicDefinitions;
-  name: NameDefinitions;
+  person: PersonDefinitions;
   phone_number: PhoneNumberDefinitions;
   science: ScienceDefinitions;
   system: SystemDefinitions;

src/definitions/index.ts

@@ -17,7 +17,7 @@ export type { HackerDefinitions } from './hacker';
 export type { InternetDefinitions } from './internet';
 export type { LoremDefinitions } from './lorem';
 export type { MusicDefinitions } from './music';
-export type { NameDefinitions, NameTitleDefinitions } from './name';
+export type { PersonDefinitions, PersonTitleDefinitions } from './person';
 export type { PhoneNumberDefinitions } from './phone_number';
 export type { ScienceDefinitions } from './science';
 export type {

src/definitions/name.ts src/definitions/person.tssrc/definitions/name.ts renamed to src/definitions/person.ts

@@ -3,7 +3,7 @@ import type { LocaleEntry } from './definitions';
 /**
  * The possible definitions related to people's names.
  */
-export type NameDefinitions = LocaleEntry<{
+export type PersonDefinitions = LocaleEntry<{
   gender: string[];
   sex: string[];
 
@@ -30,13 +30,13 @@ export type NameDefinitions = LocaleEntry<{
    */
   name: string[];
 
-  title: NameTitleDefinitions;
+  title: PersonTitleDefinitions;
 }>;
 
 /**
  * The possible definitions related to people's titles.
  */
-export interface NameTitleDefinitions {
+export interface PersonTitleDefinitions {
   descriptor?: string[];
   job: string[];
   level?: string[];

src/faker.ts

@@ -1,5 +1,6 @@
 import type { LocaleDefinition } from './definitions';
 import { FakerError } from './errors/faker-error';
+import { deprecated } from './internal/deprecated';
 import { MersenneModule } from './internal/mersenne/mersenne';
 import type { KnownLocale } from './locales';
 import { AddressModule } from './modules/address';
@@ -18,7 +19,8 @@ import { ImageModule } from './modules/image';
 import { InternetModule } from './modules/internet';
 import { LoremModule } from './modules/lorem';
 import { MusicModule } from './modules/music';
-import { NameModule } from './modules/name';
+import type { PersonModule as NameModule } from './modules/person';
+import { PersonModule } from './modules/person';
 import { PhoneModule } from './modules/phone';
 import { RandomModule } from './modules/random';
 import { ScienceModule } from './modules/science';
@@ -97,13 +99,25 @@ export class Faker {
   readonly internet: InternetModule = new InternetModule(this);
   readonly lorem: LoremModule = new LoremModule(this);
   readonly music: MusicModule = new MusicModule(this);
-  readonly name: NameModule = new NameModule(this);
+  readonly person: PersonModule = new PersonModule(this);
   readonly phone: PhoneModule = new PhoneModule(this);
   readonly science: ScienceModule = new ScienceModule(this);
   readonly system: SystemModule = new SystemModule(this);
   readonly vehicle: VehicleModule = new VehicleModule(this);
   readonly word: WordModule = new WordModule(this);
 
+  // Aliases
+  /** @deprecated Use {@link person} instead */
+  get name(): NameModule {
+    deprecated({
+      deprecated: 'faker.name',
+      proposed: 'faker.person',
+      since: '8.0.0',
+      until: '10.0.0',
+    });
+    return this.person;
+  }
+
   constructor(opts: FakerOptions) {
     if (!opts) {
       throw new FakerError(
@@ -158,6 +172,17 @@ export class Faker {
 
     return new Proxy({} as LocaleDefinition, {
       get(target: LocaleDefinition, module: string): unknown {
+        // Support aliases
+        if (module === 'name') {
+          module = 'person';
+          deprecated({
+            deprecated: `faker.helpers.fake('{{name.*}}') or faker.definitions.name`,
+            proposed: `faker.helpers.fake('{{person.*}}') or faker.definitions.person`,
+            since: '8.0.0',
+            until: '10.0.0',
+          });
+        }
+
         let result = target[module];
         if (result) {
           return result;

src/index.ts

@@ -18,8 +18,12 @@ export type {
   LocaleDefinition,
   LoremDefinitions,
   MusicDefinitions,
-  NameDefinitions,
-  NameTitleDefinitions,
+  /** @deprecated Use PersonDefinitions instead */
+  PersonDefinitions as NameDefinitions,
+  PersonDefinitions,
+  /** @deprecated Use PersonTitleDefinitions instead */
+  PersonTitleDefinitions as NameTitleDefinitions,
+  PersonTitleDefinitions,
   PhoneNumberDefinitions,
   ScienceDefinitions,
   SystemDefinitions,
@@ -53,8 +57,13 @@ export type { ImageModule } from './modules/image';
 export type { InternetModule } from './modules/internet';
 export type { LoremModule } from './modules/lorem';
 export type { MusicModule } from './modules/music';
-export { Sex } from './modules/name';
-export type { NameModule, SexType } from './modules/name';
+export { Sex } from './modules/person';
+export type {
+  /** @deprecated Use PersonModule instead */
+  PersonModule as NameModule,
+  PersonModule,
+  SexType,
+} from './modules/person';
 export type { PhoneModule } from './modules/phone';
 export type { RandomModule } from './modules/random';
 export type { ChemicalElement, ScienceModule, Unit } from './modules/science';