feat(metadata): add method to access metadata (#2143)

src/faker.ts

@@ -1,4 +1,4 @@
-import type { LocaleDefinition } from './definitions';
+import type { LocaleDefinition, MetadataDefinition } from './definitions';
 import { FakerError } from './errors/faker-error';
 import { deprecated } from './internal/deprecated';
 import type { Mersenne } from './internal/mersenne/mersenne';
@@ -458,6 +458,19 @@ export class Faker {
     return seed;
   }
 
+  /**
+   * Returns an object with metadata about the current locale.
+   *
+   * @example
+   * import { faker, fakerES_MX } from '@faker-js/faker';
+   * // const { faker, fakerES_MX } = require("@faker-js/faker")
+   * faker.getMetadata(); // { title: 'English', code: 'en', language: 'en', endonym: 'English', dir: 'ltr', script: 'Latn' }
+   * fakerES_MX.getMetadata(); // { title: 'Spanish (Mexico)', code: 'es_MX', language: 'es', endonym: 'Español (México)', dir: 'ltr', script: 'Latn', country: 'MX' }
+   */
+  getMetadata(): MetadataDefinition {
+    return this.rawDefinitions.metadata ?? {};
+  }
+
   // Pure JS backwards compatibility
 
   /**

test/faker.spec.ts

@@ -30,6 +30,14 @@ describe('faker', () => {
     }
   });
 
+  describe('getMetadata()', () => {
+    it('should return metadata for the locale', () => {
+      expect(faker.getMetadata()).toBeDefined();
+      expect(faker.getMetadata().title).toBeTypeOf('string');
+      // Not all properties are tested here, see locale-imports.spec.ts for full tests
+    });
+  });
+
   describe('rawDefinitions', () => {
     it('locale rawDefinition accessibility', () => {
       // Metadata