refactor(location)!: rename address module (#1469)

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

CONTRIBUTING.md

@@ -437,7 +437,7 @@ feat: add casing option
 feat(locale): extend Hebrew (he)
 fix: lower target to support Webpack 4
 chore: add naming convention rule
-refactor(address): deprecate streetPrefix and streetSuffix
+refactor(location): deprecate streetPrefix and streetSuffix
 docs: remove unused playground
 test: validate @see contents
 ci: allow breaking change commits

README.md

@@ -21,7 +21,7 @@
 
 ## 🚀 Features
 
-- 💌 Addresses - Generate valid looking Addresses, Zip Codes, Street Names, States, and Countries!
+- 💌 Locations - Generate valid looking Addresses, Zip Codes, Street Names, States, and Countries!
 - ⏰ Time-based Data - Past, present, future, recent, soon... whenever!
 - 🌏 Localization - Set a locale to generate realistic looking Names, Addresses, and Phone Numbers.
 - 💸 Finance - Create stubbed out Account Details, Transactions, and Crypto Addresses.
@@ -72,7 +72,6 @@ The API covers the following modules:
 
 | Module   | Example                                       | Output                                                                                             |
 | -------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| Address  | `faker.address.city()`                        | Lake Raoulfort                                                                                     |
 | Animal   | `faker.animal.cat()`                          | Norwegian Forest Cat                                                                               |
 | Color    | `faker.color.rgb()`                           | #cdfcdc                                                                                            |
 | Commerce | `faker.commerce.product()`                    | Polo t-shirt                                                                                       |
@@ -86,6 +85,7 @@ The API covers the following modules:
 | Helpers  | `faker.helpers.arrayElement(['a', 'b', 'c'])` | b                                                                                                  |
 | Image    | `faker.image.cats()`                          | https://loremflickr.com/640/480/cats <img src="https://loremflickr.com/640/480/cats" height="100"> |
 | Internet | `faker.internet.domainName()`                 | muddy-neuropathologist.net                                                                         |
+| Location | `faker.location.city()`                       | Lake Raoulfort                                                                                     |
 | Lorem    | `faker.lorem.paragraph()`                     | Porro nulla id vero perspiciatis nulla nihil. ...                                                  |
 | Music    | `faker.music.genre()`                         | R&B                                                                                                |
 | Person   | `faker.person.firstName()`                    | Cameron                                                                                            |

docs/.vitepress/api-pages.ts

@@ -2,7 +2,6 @@
 // Run 'pnpm run generate:api-docs' to update
 export const apiPages = [
   { text: 'Overview', link: '/api/' },
-  { text: 'Address', link: '/api/address.html' },
   { text: 'Animal', link: '/api/animal.html' },
   { text: 'Color', link: '/api/color.html' },
   { text: 'Commerce', link: '/api/commerce.html' },
@@ -16,6 +15,7 @@ export const apiPages = [
   { text: 'Helpers', link: '/api/helpers.html' },
   { text: 'Image', link: '/api/image.html' },
   { text: 'Internet', link: '/api/internet.html' },
+  { text: 'Location', link: '/api/location.html' },
   { text: 'Lorem', link: '/api/lorem.html' },
   { text: 'Music', link: '/api/music.html' },
   { text: 'Person', link: '/api/person.html' },

docs/index.md

@@ -24,7 +24,7 @@ features:
     title: Finance
     details: Create stubbed out Account Details, Transactions, and Crypto Addresses.
   - icon: 💌
-    title: Addresses
+    title: Locations
     details: Generate valid Addresses, Zip Codes, Street Names, States, and Countries!
   - icon: 👾
     title: Hacker Jargon

scripts/apidoc/moduleMethods.ts

@@ -41,7 +41,9 @@ export function extractModuleName(module: DeclarationReflection): string {
   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') {
+  if (name === 'AddressModule') {
+    return 'Location';
+  } else if (name === 'NameModule') {
     return 'Person';
   }
   return name.replace(/Module$/, '');

scripts/generateLocales.ts

@@ -45,7 +45,6 @@ type DefinitionsType = {
  * The types of the definitions.
  */
 const definitionsTypes: DefinitionsType = {
-  address: 'AddressDefinitions',
   animal: 'AnimalDefinitions',
   color: 'ColorDefinitions',
   commerce: 'CommerceDefinitions',
@@ -55,6 +54,7 @@ const definitionsTypes: DefinitionsType = {
   finance: 'FinanceDefinitions',
   hacker: 'HackerDefinitions',
   internet: 'InternetDefinitions',
+  location: 'LocationDefinitions',
   lorem: 'LoremDefinitions',
   music: 'MusicDefinitions',
   person: 'PersonDefinitions',

src/definitions/definitions.ts

@@ -1,4 +1,3 @@
-import type { AddressDefinitions } from './address';
 import type { AnimalDefinitions } from './animal';
 import type { ColorDefinitions } from './color';
 import type { CommerceDefinitions } from './commerce';
@@ -8,6 +7,7 @@ import type { DateDefinitions } from './date';
 import type { FinanceDefinitions } from './finance';
 import type { HackerDefinitions } from './hacker';
 import type { InternetDefinitions } from './internet';
+import type { LocationDefinitions } from './location';
 import type { LoremDefinitions } from './lorem';
 import type { MusicDefinitions } from './music';
 import type { PersonDefinitions } from './person';
@@ -26,7 +26,6 @@ export type LocaleEntry<T> = Partial<T> &
  * The definitions as used by the Faker modules.
  */
 export interface Definitions {
-  address: AddressDefinitions;
   animal: AnimalDefinitions;
   color: ColorDefinitions;
   commerce: CommerceDefinitions;
@@ -36,6 +35,7 @@ export interface Definitions {
   finance: FinanceDefinitions;
   hacker: HackerDefinitions;
   internet: InternetDefinitions;
+  location: LocationDefinitions;
   lorem: LoremDefinitions;
   music: MusicDefinitions;
   person: PersonDefinitions;

src/definitions/index.ts

@@ -1,4 +1,3 @@
-export type { AddressDefinitions } from './address';
 export type { AnimalDefinitions } from './animal';
 export type { ColorDefinitions } from './color';
 export type {
@@ -15,6 +14,7 @@ export type {
 } from './finance';
 export type { HackerDefinitions } from './hacker';
 export type { InternetDefinitions } from './internet';
+export type { LocationDefinitions } from './location';
 export type { LoremDefinitions } from './lorem';
 export type { MusicDefinitions } from './music';
 export type { PersonDefinitions, PersonTitleDefinitions } from './person';

src/definitions/address.ts → src/definitions/location.ts

@@ -1,9 +1,9 @@
 import type { LocaleEntry } from './definitions';
 
 /**
- * The possible definitions related to addresses.
+ * The possible definitions related to addresses and locations.
  */
-export type AddressDefinitions = LocaleEntry<{
+export type LocationDefinitions = LocaleEntry<{
   /**
    * Postcodes patterns by state
    */

src/faker.ts

@@ -3,7 +3,6 @@ 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';
 import { AnimalModule } from './modules/animal';
 import { ColorModule } from './modules/color';
 import { CommerceModule } from './modules/commerce';
@@ -17,6 +16,8 @@ import { HackerModule } from './modules/hacker';
 import { HelpersModule } from './modules/helpers';
 import { ImageModule } from './modules/image';
 import { InternetModule } from './modules/internet';
+import type { LocationModule as AddressModule } from './modules/location';
+import { LocationModule } from './modules/location';
 import { LoremModule } from './modules/lorem';
 import { MusicModule } from './modules/music';
 import type { PersonModule as NameModule } from './modules/person';
@@ -86,7 +87,6 @@ export class Faker {
 
   readonly datatype: DatatypeModule = new DatatypeModule(this);
 
-  readonly address: AddressModule = new AddressModule(this);
   readonly animal: AnimalModule = new AnimalModule(this);
   readonly color: ColorModule = new ColorModule(this);
   readonly commerce: CommerceModule = new CommerceModule(this);
@@ -98,6 +98,7 @@ export class Faker {
   readonly hacker: HackerModule = new HackerModule(this);
   readonly image: ImageModule = new ImageModule(this);
   readonly internet: InternetModule = new InternetModule(this);
+  readonly location: LocationModule = new LocationModule(this);
   readonly lorem: LoremModule = new LoremModule(this);
   readonly music: MusicModule = new MusicModule(this);
   readonly person: PersonModule = new PersonModule(this);
@@ -109,13 +110,24 @@ export class Faker {
   readonly word: WordModule = new WordModule(this);
 
   // Aliases
+  /** @deprecated Use {@link location} instead */
+  get address(): AddressModule {
+    deprecated({
+      deprecated: 'faker.address',
+      proposed: 'faker.location',
+      since: '8.0',
+      until: '10.0',
+    });
+    return this.location;
+  }
+
   /** @deprecated Use {@link person} instead */
   get name(): NameModule {
     deprecated({
       deprecated: 'faker.name',
       proposed: 'faker.person',
-      since: '8.0.0',
-      until: '10.0.0',
+      since: '8.0',
+      until: '10.0',
     });
     return this.person;
   }
@@ -175,13 +187,21 @@ export class Faker {
     return new Proxy({} as LocaleDefinition, {
       get(target: LocaleDefinition, module: string): unknown {
         // Support aliases
-        if (module === 'name') {
+        if (module === 'address') {
+          module = 'location';
+          deprecated({
+            deprecated: `faker.helpers.fake('{{address.*}}') or faker.definitions.address`,
+            proposed: `faker.helpers.fake('{{location.*}}') or faker.definitions.location`,
+            since: '8.0',
+            until: '10.0',
+          });
+        } else 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',
+            since: '8.0',
+            until: '10.0',
           });
         }
 

src/index.ts

@@ -2,7 +2,6 @@ import { Faker } from './faker';
 import allLocales from './locales';
 
 export type {
-  AddressDefinitions,
   AnimalDefinitions,
   ColorDefinitions,
   CommerceDefinitions,
@@ -16,6 +15,9 @@ export type {
   HackerDefinitions,
   InternetDefinitions,
   LocaleDefinition,
+  /** @deprecated Use LocationDefinitions instead */
+  LocationDefinitions as AddressDefinitions,
+  LocationDefinitions,
   LoremDefinitions,
   MusicDefinitions,
   /** @deprecated Use PersonDefinitions instead */
@@ -33,7 +35,6 @@ export type {
 } from './definitions';
 export { FakerError } from './errors/faker-error';
 export type { FakerOptions, UsableLocale, UsedLocales } from './faker';
-export type { AddressModule } from './modules/address';
 export type { AnimalModule } from './modules/animal';
 export type {
   Casing,
@@ -55,6 +56,11 @@ export type { HackerModule } from './modules/hacker';
 export type { HelpersModule } from './modules/helpers';
 export type { ImageModule } from './modules/image';
 export type { InternetModule } from './modules/internet';
+export type {
+  /** @deprecated Use LocationModule instead */
+  LocationModule as AddressModule,
+  LocationModule,
+} from './modules/location';
 export type { LoremModule } from './modules/lorem';
 export type { MusicModule } from './modules/music';
 export { Sex } from './modules/person';

src/locales/af_ZA/index.ts

@@ -3,19 +3,19 @@
  * Run 'pnpm run generate:locales' to update.
  */
 import type { LocaleDefinition } from '../..';
-import address from './address';
 import cell_phone from './cell_phone';
 import company from './company';
 import internet from './internet';
+import location from './location';
 import person from './person';
 import phone_number from './phone_number';
 
 const af_ZA: LocaleDefinition = {
   title: 'Afrikaans',
-  address,
   cell_phone,
   company,
   internet,
+  location,
   person,
   phone_number,
 };

src/locales/af_ZA/location/city.ts

@@ -0,0 +1,6 @@
+export default [
+  '{{location.city_prefix}} {{person.firstName}}{{location.city_suffix}}',
+  '{{location.city_prefix}} {{person.firstName}}',
+  '{{person.firstName}}{{location.city_suffix}}',
+  '{{person.lastName}}{{location.city_suffix}}',
+];

src/locales/zu_ZA/address/index.ts → src/locales/af_ZA/location/index.ts

@@ -2,17 +2,17 @@
  * This file is automatically generated.
  * Run 'pnpm run generate:locales' to update.
  */
-import type { AddressDefinitions } from '../../..';
+import type { LocationDefinitions } from '../../..';
 import city from './city';
 import default_country from './default_country';
 import postcode from './postcode';
 import street from './street';
 
-const address: AddressDefinitions = {
+const location: LocationDefinitions = {
   city,
   default_country,
   postcode,
   street,
 };
 
-export default address;
+export default location;

src/locales/af_ZA/location/street.ts

@@ -0,0 +1,4 @@
+export default [
+  '{{person.firstName}} {{location.street_suffix}}',
+  '{{person.lastName}} {{location.street_suffix}}',
+];

src/locales/ar/index.ts

@@ -3,11 +3,11 @@
  * Run 'pnpm run generate:locales' to update.
  */
 import type { LocaleDefinition } from '../..';
-import address from './address';
 import cell_phone from './cell_phone';
 import color from './color';
 import commerce from './commerce';
 import date from './date';
+import location from './location';
 import person from './person';
 import phone_number from './phone_number';
 import team from './team';
@@ -16,11 +16,11 @@ import vehicle from './vehicle';
 const ar: LocaleDefinition = {
   title: 'Arabic',
   separator: ' & ',
-  address,
   cell_phone,
   color,
   commerce,
   date,
+  location,
   person,
   phone_number,
   team,

src/locales/ar/location/city.ts

@@ -0,0 +1 @@
+export default ['{{location.city_name}}'];

src/locales/ar/address/index.ts → src/locales/ar/location/index.ts

@@ -2,7 +2,7 @@
  * This file is automatically generated.
  * Run 'pnpm run generate:locales' to update.
  */
-import type { AddressDefinitions } from '../../..';
+import type { LocationDefinitions } from '../../..';
 import building_number from './building_number';
 import city from './city';
 import city_name from './city_name';
@@ -15,7 +15,7 @@ import street from './street';
 import street_address from './street_address';
 import street_prefix from './street_prefix';
 
-const address: AddressDefinitions = {
+const location: LocationDefinitions = {
   building_number,
   city,
   city_name,
@@ -29,4 +29,4 @@ const address: AddressDefinitions = {
   street_prefix,
 };
 
-export default address;
+export default location;

src/locales/ar/location/street.ts

@@ -0,0 +1,4 @@
+export default [
+  '{{location.street_prefix}} {{person.first_name}}',
+  '{{location.street_prefix}} {{person.last_name}}',
+];