feat: de-proxy locale access

src/definitions/definitions.ts

@@ -29,29 +29,49 @@ export type LocaleEntry<TCategoryDefinition extends Record<string, unknown>> = {
 } & Record<string, unknown>; // Unsupported & custom entries
 
 /**
- * The definitions as used by the translations/locales.
+ * The internal types for the definitions.
  */
-export type LocaleDefinition = {
-  metadata?: MetadataDefinition;
-  airline?: AirlineDefinition;
-  animal?: AnimalDefinition;
-  book?: BookDefinition;
-  color?: ColorDefinition;
-  commerce?: CommerceDefinition;
-  company?: CompanyDefinition;
-  database?: DatabaseDefinition;
-  date?: DateDefinition;
-  finance?: FinanceDefinition;
-  food?: FoodDefinition;
-  hacker?: HackerDefinition;
-  internet?: InternetDefinition;
-  location?: LocationDefinition;
-  lorem?: LoremDefinition;
-  music?: MusicDefinition;
-  person?: PersonDefinition;
-  phone_number?: PhoneNumberDefinition;
-  science?: ScienceDefinition;
-  system?: SystemDefinition;
-  vehicle?: VehicleDefinition;
-  word?: WordDefinition;
-} & Record<string, Record<string, unknown>>;
+type RawLocaleDefinition = {
+  metadata: MetadataDefinition;
+  airline: AirlineDefinition;
+  animal: AnimalDefinition;
+  book: BookDefinition;
+  color: ColorDefinition;
+  commerce: CommerceDefinition;
+  company: CompanyDefinition;
+  database: DatabaseDefinition;
+  date: DateDefinition;
+  finance: FinanceDefinition;
+  food: FoodDefinition;
+  hacker: HackerDefinition;
+  internet: InternetDefinition;
+  location: LocationDefinition;
+  lorem: LoremDefinition;
+  music: MusicDefinition;
+  person: PersonDefinition;
+  phone_number: PhoneNumberDefinition;
+  science: ScienceDefinition;
+  system: SystemDefinition;
+  vehicle: VehicleDefinition;
+  word: WordDefinition;
+};
+
+/**
+ * Helper type to undo `LocaleEntry<T>` wrapping.
+ */
+type DefinedLocaleEntry<T> = T extends LocaleEntry<infer U> ? U : never;
+
+/**
+ * Helper type containing the well known locale definitions as used by this library, assuming all values are present.
+ *
+ * This type is mainly used for `resolveLocaleData()` to enable auto completion.
+ */
+export type DefinedLocaleDefinition = {
+  [K in keyof RawLocaleDefinition]: DefinedLocaleEntry<RawLocaleDefinition[K]>;
+};
+
+/**
+ * The extensible definitions as used by the translations/locales.
+ */
+export type LocaleDefinition = Partial<RawLocaleDefinition> &
+  Record<string, Record<string, unknown>>;

src/faker.ts

@@ -60,6 +60,12 @@ import { generateMersenne53Randomizer } from './utils/mersenne';
  * customFaker.music.genre(); // throws Error as this data is not available in `es`
  */
 export class Faker extends SimpleFaker {
+  /**
+   * The definitions for the current locale.
+   *
+   * @deprecated Use `faker.fakerCore.locale` and `resolveLocaleData()` instead.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-deprecated
   readonly definitions: LocaleProxy;
 
   readonly airline: AirlineModule = new AirlineModule(this);
@@ -87,8 +93,12 @@ export class Faker extends SimpleFaker {
   readonly vehicle: VehicleModule = new VehicleModule(this);
   readonly word: WordModule = new WordModule(this);
 
+  /**
+   * The raw definitions for the current locale.
+   *
+   * @deprecated Use `faker.fakerCore.locale` instead.
+   */
   get rawDefinitions(): LocaleDefinition {
-    // TODO @ST-DDT 2024-05-14: Should we deprecate this?
     return this.fakerCore.locale;
   }
 
@@ -201,6 +211,7 @@ export class Faker extends SimpleFaker {
     this.fakerCore = fakerCore;
     // super({ fakerCore });
 
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     this.definitions = createLocaleProxy(this.rawDefinitions);
   }
 

src/index.ts

@@ -88,3 +88,4 @@ export {
   generateMersenne32Randomizer,
   generateMersenne53Randomizer,
 } from './utils/mersenne';
+export { resolveLocaleData } from './utils/resolve-locale-data';

src/internal/locale-proxy.ts

@@ -1,8 +1,11 @@
+/* eslint-disable @typescript-eslint/no-deprecated */
 import type { LocaleDefinition } from '../definitions';
 import { FakerError } from '../errors/faker-error';
 
 /**
  * A proxy for LocaleDefinition that marks all properties as required and throws an error when an entry is accessed that is not defined.
+ *
+ * @deprecated Use `faker.fakerCore.locale` and `resolveLocaleData()` instead.
  */
 export type LocaleProxy = Readonly<{
   [key in keyof LocaleDefinition]-?: LocaleProxyCategory<LocaleDefinition[key]>;

src/modules/airline/index.ts

@@ -5,6 +5,7 @@
  * operations.
  */
 import { ModuleBase } from '../../internal/module-base';
+import { resolveLocaleData } from '../../utils/resolve-locale-data';
 
 export enum Aircraft {
   Narrowbody = 'narrowbody',
@@ -88,7 +89,7 @@ export class AirlineModule extends ModuleBase {
    */
   airport(): Airport {
     return this.faker.helpers.arrayElement(
-      this.faker.definitions.airline.airport
+      resolveLocaleData(this.faker.fakerCore, 'airline', 'airport')
     );
   }
 
@@ -102,7 +103,7 @@ export class AirlineModule extends ModuleBase {
    */
   airline(): Airline {
     return this.faker.helpers.arrayElement(
-      this.faker.definitions.airline.airline
+      resolveLocaleData(this.faker.fakerCore, 'airline', 'airline')
     );
   }
 
@@ -116,7 +117,7 @@ export class AirlineModule extends ModuleBase {
    */
   airplane(): Airplane {
     return this.faker.helpers.arrayElement(
-      this.faker.definitions.airline.airplane
+      resolveLocaleData(this.faker.fakerCore, 'airline', 'airplane')
     );
   }
 

src/modules/animal/index.ts

@@ -1,4 +1,5 @@
 import { ModuleBase } from '../../internal/module-base';
+import { resolveLocaleData } from '../../utils/resolve-locale-data';
 
 /**
  * Module to generate animal related entries.
@@ -21,7 +22,9 @@ export class AnimalModule extends ModuleBase {
    * @since 5.5.0
    */
   dog(): string {
-    return this.faker.helpers.arrayElement(this.faker.definitions.animal.dog);
+    return this.faker.helpers.arrayElement(
+      resolveLocaleData(this.faker.fakerCore, 'animal', 'dog')
+    );
   }
 
   /**
@@ -33,7 +36,9 @@ export class AnimalModule extends ModuleBase {
    * @since 5.5.0
    */
   cat(): string {
-    return this.faker.helpers.arrayElement(this.faker.definitions.animal.cat);
+    return this.faker.helpers.arrayElement(
+      resolveLocaleData(this.faker.fakerCore, 'animal', 'cat')
+    );
   }
 
   /**
@@ -45,7 +50,9 @@ export class AnimalModule extends ModuleBase {
    * @since 5.5.0
    */
   snake(): string {
-    return this.faker.helpers.arrayElement(this.faker.definitions.animal.snake);
+    return this.faker.helpers.arrayElement(
+      resolveLocaleData(this.faker.fakerCore, 'animal', 'snake')
+    );
   }
 
   /**
@@ -57,7 +64,9 @@ export class AnimalModule extends ModuleBase {
    * @since 5.5.0
    */
   bear(): string {
-    return this.faker.helpers.arrayElement(this.faker.definitions.animal.bear);
+    return this.faker.helpers.arrayElement(
+      resolveLocaleData(this.faker.fakerCore, 'animal', 'bear')
+    );
   }
 
   /**
@@ -69,7 +78,9 @@ export class AnimalModule extends ModuleBase {
    * @since 5.5.0
    */
   lion(): string {
-    return this.faker.helpers.arrayElement(this.faker.definitions.animal.lion);
+    return this.faker.helpers.arrayElement(
+      resolveLocaleData(this.faker.fakerCore, 'animal', 'lion')
+    );
   }
 
   /**
@@ -82,7 +93,7 @@ export class AnimalModule extends ModuleBase {
    */
   cetacean(): string {
     return this.faker.helpers.arrayElement(
-      this.faker.definitions.animal.cetacean
+      resolveLocaleData(this.faker.fakerCore, 'animal', 'cetacean')
     );
   }
 
@@ -95,7 +106,9 @@ export class AnimalModule extends ModuleBase {
    * @since 5.5.0
    */
   horse(): string {
-    return this.faker.helpers.arrayElement(this.faker.definitions.animal.horse);
+    return this.faker.helpers.arrayElement(
+      resolveLocaleData(this.faker.fakerCore, 'animal', 'horse')
+    );
   }
 
   /**
@@ -107,7 +120,9 @@ export class AnimalModule extends ModuleBase {
    * @since 5.5.0
    */
   bird(): string {
-    return this.faker.helpers.arrayElement(this.faker.definitions.animal.bird);
+    return this.faker.helpers.arrayElement(
+      resolveLocaleData(this.faker.fakerCore, 'animal', 'bird')
+    );
   }
 
   /**
@@ -119,7 +134,9 @@ export class AnimalModule extends ModuleBase {
    * @since 5.5.0
    */
   cow(): string {
-    return this.faker.helpers.arrayElement(this.faker.definitions.animal.cow);
+    return this.faker.helpers.arrayElement(
+      resolveLocaleData(this.faker.fakerCore, 'animal', 'cow')
+    );
   }
 
   /**
@@ -131,7 +148,9 @@ export class AnimalModule extends ModuleBase {
    * @since 5.5.0
    */
   fish(): string {
-    return this.faker.helpers.arrayElement(this.faker.definitions.animal.fish);
+    return this.faker.helpers.arrayElement(
+      resolveLocaleData(this.faker.fakerCore, 'animal', 'fish')
+    );
   }
 
   /**
@@ -144,7 +163,7 @@ export class AnimalModule extends ModuleBase {
    */
   crocodilia(): string {
     return this.faker.helpers.arrayElement(
-      this.faker.definitions.animal.crocodilia
+      resolveLocaleData(this.faker.fakerCore, 'animal', 'crocodilia')
     );
   }
 
@@ -158,7 +177,7 @@ export class AnimalModule extends ModuleBase {
    */
   insect(): string {
     return this.faker.helpers.arrayElement(
-      this.faker.definitions.animal.insect
+      resolveLocaleData(this.faker.fakerCore, 'animal', 'insect')
     );
   }
 
@@ -172,7 +191,7 @@ export class AnimalModule extends ModuleBase {
    */
   rabbit(): string {
     return this.faker.helpers.arrayElement(
-      this.faker.definitions.animal.rabbit
+      resolveLocaleData(this.faker.fakerCore, 'animal', 'rabbit')
     );
   }
 
@@ -186,7 +205,7 @@ export class AnimalModule extends ModuleBase {
    */
   rodent(): string {
     return this.faker.helpers.arrayElement(
-      this.faker.definitions.animal.rodent
+      resolveLocaleData(this.faker.fakerCore, 'animal', 'rodent')
     );
   }
 
@@ -199,6 +218,8 @@ export class AnimalModule extends ModuleBase {
    * @since 5.5.0
    */
   type(): string {
-    return this.faker.helpers.arrayElement(this.faker.definitions.animal.type);
+    return this.faker.helpers.arrayElement(
+      resolveLocaleData(this.faker.fakerCore, 'animal', 'type')
+    );
   }
 }

src/modules/book/index.ts

@@ -1,4 +1,5 @@
 import { ModuleBase } from '../../internal/module-base';
+import { resolveLocaleData } from '../../utils/resolve-locale-data';
 
 /**
  * Module to generate book related entries.
@@ -26,7 +27,9 @@ export class BookModule extends ModuleBase {
    * @since 9.1.0
    */
   author(): string {
-    return this.faker.helpers.arrayElement(this.faker.definitions.book.author);
+    return this.faker.helpers.arrayElement(
+      resolveLocaleData(this.faker.fakerCore, 'book', 'author')
+    );
   }
 
   /**
@@ -38,7 +41,9 @@ export class BookModule extends ModuleBase {
    * @since 9.1.0
    */
   format(): string {
-    return this.faker.helpers.arrayElement(this.faker.definitions.book.format);
+    return this.faker.helpers.arrayElement(
+      resolveLocaleData(this.faker.fakerCore, 'book', 'format')
+    );
   }
 
   /**
@@ -50,7 +55,9 @@ export class BookModule extends ModuleBase {
    * @since 9.1.0
    */
   genre(): string {
-    return this.faker.helpers.arrayElement(this.faker.definitions.book.genre);
+    return this.faker.helpers.arrayElement(
+      resolveLocaleData(this.faker.fakerCore, 'book', 'genre')
+    );
   }
 
   /**
@@ -63,7 +70,7 @@ export class BookModule extends ModuleBase {
    */
   publisher(): string {
     return this.faker.helpers.arrayElement(
-      this.faker.definitions.book.publisher
+      resolveLocaleData(this.faker.fakerCore, 'book', 'publisher')
     );
   }
 
@@ -76,7 +83,9 @@ export class BookModule extends ModuleBase {
    * @since 9.1.0
    */
   series(): string {
-    return this.faker.helpers.arrayElement(this.faker.definitions.book.series);
+    return this.faker.helpers.arrayElement(
+      resolveLocaleData(this.faker.fakerCore, 'book', 'series')
+    );
   }
 
   /**
@@ -88,6 +97,8 @@ export class BookModule extends ModuleBase {
    * @since 9.1.0
    */
   title(): string {
-    return this.faker.helpers.arrayElement(this.faker.definitions.book.title);
+    return this.faker.helpers.arrayElement(
+      resolveLocaleData(this.faker.fakerCore, 'book', 'title')
+    );
   }
 }