feat: introduce locale proxy (#2004)

5 files changed, 232 insertions, 15 deletions

diff --git a/test/all_functional.spec.ts b/test/all_functional.spec.ts
index b5501290..25619c9e 100644
--- a/test/all_functional.spec.ts
+++ b/test/all_functional.spec.ts
@@ -3,6 +3,7 @@ import type { allLocales, Faker, RandomModule } from '../src';
 import { allFakers, fakerEN } from '../src';
 
 const IGNORED_MODULES = [
+  'rawDefinitions',
   'definitions',
   'helpers',
   '_mersenne',
diff --git a/test/faker.spec.ts b/test/faker.spec.ts
index 57f291c0..207dac4a 100644
--- a/test/faker.spec.ts
+++ b/test/faker.spec.ts
@@ -30,16 +30,33 @@ describe('faker', () => {
     }
   });
 
+  describe('rawDefinitions', () => {
+    it('locale rawDefinition accessibility', () => {
+      // Metadata
+      expect(faker.rawDefinitions.metadata.title).toBeDefined();
+      // Standard modules
+      expect(faker.rawDefinitions.location?.city_name).toBeDefined();
+      // Non-existing module
+      expect(faker.rawDefinitions.missing).toBeUndefined();
+      // Non-existing definition in a non-existing module
+      expect(faker.rawDefinitions.missing?.missing).toBeUndefined();
+      // Non-existing definition in an existing module
+      expect(faker.rawDefinitions.location?.missing).toBeUndefined();
+    });
+  });
+
   describe('definitions', () => {
-    it('locale definition accessability', () => {
+    it('locale definition accessibility', () => {
       // Metadata
       expect(faker.definitions.metadata.title).toBeDefined();
       // Standard modules
       expect(faker.definitions.location.city_name).toBeDefined();
       // Non-existing module
-      expect(faker.definitions.missing).toBeUndefined();
+      expect(faker.definitions.missing).toBeDefined();
+      // Non-existing definition in a non-existing module
+      expect(() => faker.definitions.missing.missing).toThrow();
       // Non-existing definition in an existing module
-      expect(faker.definitions.location.missing).toBeUndefined();
+      expect(() => faker.definitions.location.missing).toThrow();
     });
   });
 
diff --git a/test/locale-proxy.spec.ts b/test/locale-proxy.spec.ts
new file mode 100644
index 00000000..88ce9555
--- /dev/null
+++ b/test/locale-proxy.spec.ts
@@ -0,0 +1,189 @@
+import { describe, expect, it } from 'vitest';
+import type { MetadataDefinitions } from '../src';
+import { en, FakerError } from '../src';
+import { createLocaleProxy } from '../src/locale-proxy';
+
+describe('LocaleProxy', () => {
+  const locale = createLocaleProxy(en);
+  const enAirline = en.airline ?? { never: 'missing' };
+
+  describe('category', () => {
+    it('should be possible to check for a missing category', () => {
+      expect('category' in locale).toBe(true);
+    });
+
+    it('should be possible to check for an existing category', () => {
+      expect('airline' in locale).toBe(true);
+    });
+
+    it('should be possible to access the title', () => {
+      expect(locale.metadata.title).toBe('English');
+    });
+
+    it('should be possible to access a missing category', () => {
+      expect(locale.category).toBeDefined();
+    });
+
+    it('should not be possible to add a new category', () => {
+      expect(() => {
+        // @ts-expect-error: LocaleProxy is read-only.
+        locale.category = {};
+      }).toThrowError(
+        new FakerError('You cannot edit the locale data on the faker instance')
+      );
+    });
+
+    it('should not be possible to replace a category', () => {
+      expect(() => {
+        // @ts-expect-error: LocaleProxy is read-only.
+        locale.airline = {};
+      }).toThrowError(
+        new FakerError('You cannot edit the locale data on the faker instance')
+      );
+    });
+
+    it('should not be possible to delete a missing category', () => {
+      expect(() => {
+        // @ts-expect-error: LocaleProxy is read-only.
+        delete locale.category;
+      }).toThrowError(
+        new FakerError('You cannot edit the locale data on the faker instance')
+      );
+    });
+
+    it('should not be possible to delete an existing category', () => {
+      expect(() => {
+        // @ts-expect-error: LocaleProxy is read-only.
+        delete locale.airline;
+      }).toThrowError(
+        new FakerError('You cannot edit the locale data on the faker instance')
+      );
+    });
+
+    it('should be possible to get all categories keys on empty locale', () => {
+      const empty = createLocaleProxy({ metadata: {} as MetadataDefinitions });
+
+      expect(Object.keys(empty)).toEqual(['metadata']);
+    });
+
+    it('should be possible to get all categories keys on actual locale', () => {
+      expect(Object.keys(locale).sort()).toEqual(Object.keys(en).sort());
+    });
+  });
+
+  describe('entry', () => {
+    it('should be possible to check for a missing entry in a missing category', () => {
+      expect('missing' in locale.category).toBe(false);
+    });
+
+    it('should be possible to check for a missing entry in a present category', () => {
+      expect('missing' in locale.airline).toBe(false);
+    });
+
+    it('should be possible to check for a present entry', () => {
+      expect('airline' in locale.airline).toBe(true);
+    });
+
+    it('should not be possible to access a missing entry in a missing category', () => {
+      expect(() => locale.category.missing).toThrowError(
+        new FakerError(
+          `The locale data for 'category.missing' are missing in this locale.
+  Please contribute the missing data to the project or use a locale/Faker instance that has these data.
+  For more information see https://next.fakerjs.dev/guide/localization.html`
+        )
+      );
+    });
+
+    it('should not be possible to access a missing entry in a present category', () => {
+      expect(() => locale.airline.missing).toThrowError(
+        new FakerError(
+          `The locale data for 'airline.missing' are missing in this locale.
+  Please contribute the missing data to the project or use a locale/Faker instance that has these data.
+  For more information see https://next.fakerjs.dev/guide/localization.html`
+        )
+      );
+    });
+
+    it('should be possible to access a present entry', () => {
+      expect(locale.airline.airline).toBeDefined();
+    });
+
+    it('should not be possible to access an unavailable entry in a present category', () => {
+      const unavailable = createLocaleProxy({
+        metadata: {} as MetadataDefinitions,
+        airline: { airline: null },
+      });
+
+      expect(() => unavailable.airline.airline).toThrowError(
+        new FakerError(
+          `The locale data for 'airline.airline' aren't applicable to this locale.
+  If you think this is a bug, please report it at: https://github.com/faker-js/faker`
+        )
+      );
+    });
+
+    it('should not be possible to add a new entry in a missing category', () => {
+      expect(() => {
+        // @ts-expect-error: LocaleProxy is read-only.
+        locale.category.missing = {};
+      }).toThrowError(
+        new FakerError('You cannot edit the locale data on the faker instance')
+      );
+    });
+
+    it('should not be possible to add a new entry in an existing category', () => {
+      expect(() => {
+        // @ts-expect-error: LocaleProxy is read-only.
+        locale.airline.missing = {};
+      }).toThrowError(
+        new FakerError('You cannot edit the locale data on the faker instance')
+      );
+    });
+
+    it('should not be possible to replace an entry in an existing category', () => {
+      expect(() => {
+        // @ts-expect-error: LocaleProxy is read-only.
+        locale.airline.airline = ['dummy'];
+      }).toThrowError(
+        new FakerError('You cannot edit the locale data on the faker instance')
+      );
+    });
+
+    it('should not be possible to delete a missing entry in a missing category', () => {
+      expect(() => {
+        // @ts-expect-error: LocaleProxy is read-only.
+        delete locale.category.missing;
+      }).toThrowError(
+        new FakerError('You cannot edit the locale data on the faker instance')
+      );
+    });
+
+    it('should not be possible to delete a missing entry in an existing category', () => {
+      expect(() => {
+        // @ts-expect-error: LocaleProxy is read-only.
+        delete locale.airline.missing;
+      }).toThrowError(
+        new FakerError('You cannot edit the locale data on the faker instance')
+      );
+    });
+
+    it('should not be possible to delete an existing entry in an existing category', () => {
+      expect(() => {
+        // @ts-expect-error: LocaleProxy is read-only.
+        delete locale.airline.airline;
+      }).toThrowError(
+        new FakerError('You cannot edit the locale data on the faker instance')
+      );
+    });
+
+    it('should be possible to get all keys from missing category', () => {
+      expect(Object.keys(locale.missing)).toEqual([]);
+    });
+
+    it('should be possible to get all keys from existing category', () => {
+      expect(Object.keys(locale.airline).sort()).toEqual(
+        Object.keys(enAirline).sort()
+      );
+    });
+  });
+});
diff --git a/test/location.spec.ts b/test/location.spec.ts
index 78f32b53..9ea62cd9 100644
--- a/test/location.spec.ts
+++ b/test/location.spec.ts
@@ -181,6 +181,16 @@ describe('location', () => {
 
         it('should throw when definitions.location.postcode_by_state not set', () => {
           expect(() => faker.location.zipCode({ state: 'XX' })).toThrow(
+            new FakerError(
+              `The locale data for 'location.postcode_by_state' are missing in this locale.
+  Please contribute the missing data to the project or use a locale/Faker instance that has these data.
+  For more information see https://next.fakerjs.dev/guide/localization.html`
+            )
+          );
+        });
+
+        it('should throw when definitions.location.postcode_by_state[state] is unknown', () => {
+          expect(() => fakerEN_US.location.zipCode({ state: 'XX' })).toThrow(
             new FakerError('No zip code definition found for state "XX"')
           );
         });
diff --git a/test/person.spec.ts b/test/person.spec.ts
index dbd2169d..7465efbd 100644
--- a/test/person.spec.ts
+++ b/test/person.spec.ts
@@ -122,10 +122,10 @@ describe('person', () => {
 
         it('should return a female sex-specific name without firstName and lastName', () => {
           const female_specific = [
-            ...fakerMK.definitions.person.female_prefix,
-            ...fakerMK.definitions.person.female_first_name,
-            ...fakerMK.definitions.person.female_last_name,
-            // ...fakerMK.definitions.person.suffix, // Not applicable
+            ...(fakerMK.rawDefinitions.person?.female_prefix ?? []),
+            ...(fakerMK.rawDefinitions.person?.female_first_name ?? []),
+            ...(fakerMK.rawDefinitions.person?.female_last_name ?? []),
+            // ...(fakerMK.rawDefinitions.person?.suffix ?? []), Not applicable
           ];
 
           const fullName = fakerMK.person.fullName({ sex: 'female' });
@@ -138,10 +138,10 @@ describe('person', () => {
 
         it('should return a male sex-specific name without firstName and lastName', () => {
           const male_specific = [
-            ...fakerMK.definitions.person.male_prefix,
-            ...fakerMK.definitions.person.male_first_name,
-            ...fakerMK.definitions.person.male_last_name,
-            // ...fakerMK.definitions.person.suffix, // Not applicable
+            ...(fakerMK.rawDefinitions.person?.male_prefix ?? []),
+            ...(fakerMK.rawDefinitions.person?.male_first_name ?? []),
+            ...(fakerMK.rawDefinitions.person?.male_last_name ?? []),
+            // ...(fakerMK.rawDefinitions.person?.suffix ?? []), Not applicable
           ];
 
           const fullName = fakerMK.person.fullName({ sex: 'male' });
@@ -154,10 +154,10 @@ describe('person', () => {
 
         it('should return a female sex-specific name with given firstName and lastName', () => {
           const male_specific = [
-            ...fakerMK.definitions.person.female_prefix,
+            ...(fakerMK.rawDefinitions.person?.female_prefix ?? []),
             'firstName',
             'lastName',
-            // ...fakerMK.definitions.person.suffix, // Not applicable
+            // ...(fakerMK.rawDefinitions.person?.suffix ?? []), Not applicable
           ];
 
           const fullName = fakerMK.person.fullName({
@@ -174,10 +174,10 @@ describe('person', () => {
 
         it('should return a male sex-specific name with given firstName and lastName', () => {
           const male_specific = [
-            ...fakerMK.definitions.person.male_prefix,
+            ...(fakerMK.rawDefinitions.person?.male_prefix ?? []),
             'firstName',
             'lastName',
-            //...fakerMK.definitions.person.suffix, // Not applicable
+            // ...(fakerMK.rawDefinitions.person?.suffix ?? []), Not applicable
           ];
 
           const fullName = fakerMK.person.fullName({