Merge branch 'next' into pr/munkeawtoast/1922

docs/guide/upgrading.md

@@ -120,10 +120,6 @@ For more information refer to our [Localization Guide](localization).
 | `faker.address.streetSuffix`    | _Removed_                                                         |
 | `faker.image.lorempixel`        | _Removed, as the LoremPixel service is no longer available_       |
 
-### Locale renamed
-
-The `en_IND` (English, India) locale was renamed to `en_IN` for consistency with other locales.
-
 ## Deprecations and other changes
 
 ### `faker.name` changed to `faker.person`
@@ -220,3 +216,7 @@ The `allowLeadingZeros` boolean parameter in `faker.string.numeric` (in the new
 ### Simplified MIME type data
 
 The functions `faker.system.mimeType`, `faker.system.fileType` and `faker.system.fileExt` now return data from a smaller set of more common MIME types, filetypes and extensions.
+
+### Locale renamed
+
+The `en_IND` (English, India) locale was renamed to `en_IN` for consistency with other locales.

scripts/apidoc/apiDocsWriter.ts

@@ -41,6 +41,7 @@ export function writeApiDocsModulePage(
   moduleName: string,
   lowerModuleName: string,
   comment: string,
+  deprecated: string | undefined,
   methods: Method[]
 ): void {
   // Write api docs page
@@ -57,6 +58,16 @@ export function writeApiDocsModulePage(
 
   ::: v-pre
 
+  ${
+    deprecated == null
+      ? ''
+      : `<div class="warning custom-block">
+           <p class="custom-block-title">Deprecated</p>
+           <p>This module is deprecated and will be removed in a future version.</p>
+           <span>${deprecated}</span>
+         </div>`
+  }
+
   ${comment}
 
   :::

scripts/apidoc/moduleMethods.ts

@@ -3,6 +3,7 @@ import type { Method } from '../../docs/.vitepress/components/api-docs/method';
 import { writeApiDocsData, writeApiDocsModulePage } from './apiDocsWriter';
 import { analyzeSignature, stripAbsoluteFakerUrls, toBlock } from './signature';
 import {
+  extractDeprecated,
   extractModuleFieldName,
   extractModuleName,
   selectApiMethodSignatures,
@@ -41,7 +42,7 @@ function processModuleMethod(module: DeclarationReflection): PageAndDiffIndex {
   const moduleFieldName = extractModuleFieldName(module);
   console.log(`Processing Module ${moduleName}`);
   const comment = stripAbsoluteFakerUrls(toBlock(module.comment));
-
+  const deprecated = extractDeprecated(module);
   const methods: Method[] = [];
 
   // Generate method section
@@ -52,7 +53,13 @@ function processModuleMethod(module: DeclarationReflection): PageAndDiffIndex {
     methods.push(analyzeSignature(signature, moduleFieldName, methodName));
   }
 
-  writeApiDocsModulePage(moduleName, moduleFieldName, comment, methods);
+  writeApiDocsModulePage(
+    moduleName,
+    moduleFieldName,
+    comment,
+    deprecated,
+    methods
+  );
   writeApiDocsData(moduleFieldName, methods);
 
   return [

scripts/generateLocales.ts

@@ -23,7 +23,7 @@ import { resolve } from 'node:path';
 import type { Options } from 'prettier';
 import { format } from 'prettier';
 import options from '../.prettierrc.cjs';
-import type { Definitions, LocaleDefinition } from '../src/definitions';
+import type { LocaleDefinition, MetadataDefinitions } from '../src/definitions';
 
 // Constants
 
@@ -45,7 +45,7 @@ type PascalCase<S extends string> = S extends `${infer P1}_${infer P2}`
   : Capitalize<S>;
 
 type DefinitionsType = {
-  [key in keyof Definitions]: PascalCase<`${key}Definitions`>;
+  [key in keyof LocaleDefinition]-?: PascalCase<`${key}Definitions`>;
 };
 
 /**
@@ -64,6 +64,7 @@ const definitionsTypes: DefinitionsType = {
   internet: 'InternetDefinitions',
   location: 'LocationDefinitions',
   lorem: 'LoremDefinitions',
+  metadata: 'MetadataDefinitions',
   music: 'MusicDefinitions',
   person: 'PersonDefinitions',
   phone_number: 'PhoneNumberDefinitions',
@@ -153,43 +154,11 @@ function generateLocaleFile(locale: string): void {
   writeFileSync(resolve(pathLocale, `${locale}.ts`), content);
 }
 
-function tryLoadLocalesMainIndexFile(
-  pathModules: string
-): LocaleDefinition | undefined {
-  let localeDef: LocaleDefinition | undefined;
-  // This call might fail, if the module setup is broken.
-  // Unfortunately, we try to fix it with this script
-  // Thats why have a fallback logic here, we only need the title anyway
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    localeDef = require(pathModules).default;
-  } catch (e) {
-    try {
-      console.log(
-        `Failed to load ${pathModules}. Attempting manual parse instead...`
-      );
-      const localeIndex = readFileSync(
-        resolve(pathModules, 'index.ts'),
-        'utf-8'
-      );
-      const title = localeIndex.match(/title: '(.*)',/)?.[1];
-      if (title) {
-        localeDef = { title };
-      }
-    } catch {
-      console.error(`Failed to load ${pathModules} or manually parse it.`, e);
-    }
-  }
-
-  return localeDef;
-}
-
 function generateLocalesIndexFile(
   path: string,
   name: string,
   type: string,
-  depth: number,
-  extra: string = ''
+  depth: number
 ): void {
   let modules = readdirSync(path);
   modules = removeIndexTs(modules);
@@ -214,7 +183,6 @@ function generateLocalesIndexFile(
   );
 
   content.push(`\nconst ${name}${fieldType} = {
-        ${extra}
         ${modules.map((module) => `${escapeField(name, module)},`).join('\n')}
       };\n`);
 
@@ -230,10 +198,9 @@ function generateRecursiveModuleIndexes(
   path: string,
   name: string,
   definition: string,
-  depth: number,
-  extra?: string
+  depth: number
 ): void {
-  generateLocalesIndexFile(path, name, definition, depth, extra);
+  generateLocalesIndexFile(path, name, definition, depth);
 
   let submodules = readdirSync(path);
   submodules = removeIndexTs(submodules);
@@ -255,8 +222,7 @@ function generateRecursiveModuleIndexes(
         pathModule,
         submodule,
         moduleDefinition,
-        depth + 1,
-        undefined
+        depth + 1
       );
     }
   }
@@ -311,10 +277,21 @@ let localizationLocales = '| Locale | Name | Faker |\n| :--- | :--- | :--- |\n';
 
 for (const locale of locales) {
   const pathModules = resolve(pathLocales, locale);
-
-  const localeDef = tryLoadLocalesMainIndexFile(pathModules);
-  // We use a fallback here to at least generate a working file.
-  const localeTitle = localeDef?.title ?? `TODO: Insert Title for ${locale}`;
+  const pathMetadata = resolve(pathModules, 'metadata.ts');
+  let localeTitle = 'No title found';
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const metadata: MetadataDefinitions = require(pathMetadata).default;
+    localeTitle = metadata.title;
+    if (!localeTitle) {
+      throw new Error(`No title property found on ${JSON.stringify(metadata)}`);
+    }
+  } catch (e) {
+    console.error(
+      `Failed to load ${pathMetadata}. Please make sure the file exists and exports MetadataDefinitions.`
+    );
+    console.error(e);
+  }
 
   const localizedFaker = `faker${locale.replace(/^([a-z]+)/, (part) =>
     part.toUpperCase()
@@ -330,13 +307,7 @@ for (const locale of locales) {
   generateLocaleFile(locale);
 
   // src/locales/**/index.ts
-  generateRecursiveModuleIndexes(
-    pathModules,
-    locale,
-    'LocaleDefinition',
-    1,
-    `title: '${localeTitle}',`
-  );
+  generateRecursiveModuleIndexes(pathModules, locale, 'LocaleDefinition', 1);
 }
 
 // src/locale/index.ts

src/definitions/definitions.ts

@@ -10,6 +10,7 @@ import type { HackerDefinitions } from './hacker';
 import type { InternetDefinitions } from './internet';
 import type { LocationDefinitions } from './location';
 import type { LoremDefinitions } from './lorem';
+import type { MetadataDefinitions } from './metadata';
 import type { MusicDefinitions } from './music';
 import type { PersonDefinitions } from './person';
 import type { PhoneNumberDefinitions } from './phone_number';
@@ -18,44 +19,37 @@ import type { SystemDefinitions } from './system';
 import type { VehicleDefinitions } from './vehicle';
 import type { WordDefinitions } from './word';
 
-export type LocaleEntry<T> = Partial<T> &
-  // Unsupported & custom modules
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  Record<string, any>;
-
 /**
- * The definitions as used by the Faker modules.
+ * Wrapper type for all definition categories that will make all properties optional and allow extra properties.
  */
-export interface Definitions {
-  airline: AirlineDefinitions;
-  animal: AnimalDefinitions;
-  color: ColorDefinitions;
-  commerce: CommerceDefinitions;
-  company: CompanyDefinitions;
-  database: DatabaseDefinitions;
-  date: DateDefinitions;
-  finance: FinanceDefinitions;
-  hacker: HackerDefinitions;
-  internet: InternetDefinitions;
-  location: LocationDefinitions;
-  lorem: LoremDefinitions;
-  music: MusicDefinitions;
-  person: PersonDefinitions;
-  phone_number: PhoneNumberDefinitions;
-  science: ScienceDefinitions;
-  system: SystemDefinitions;
-  vehicle: VehicleDefinitions;
-  word: WordDefinitions;
-}
+export type LocaleEntry<T extends Record<string, unknown>> = Partial<T> &
+  // Unsupported & custom entries
+  Record<string, unknown>;
 
 /**
  * The definitions as used by the translations/locales.
  * This is basically the same as Definitions with the exception,
  * that most properties are optional and extra properties are allowed.
  */
 export type LocaleDefinition = {
-  /**
-   * The English name of the language (and the specific country, if defined).
-   */
-  title: string;
-} & LocaleEntry<Definitions>;
+  metadata: MetadataDefinitions;
+  airline?: AirlineDefinitions;
+  animal?: AnimalDefinitions;
+  color?: ColorDefinitions;
+  commerce?: CommerceDefinitions;
+  company?: CompanyDefinitions;
+  database?: DatabaseDefinitions;
+  date?: DateDefinitions;
+  finance?: FinanceDefinitions;
+  hacker?: HackerDefinitions;
+  internet?: InternetDefinitions;
+  location?: LocationDefinitions;
+  lorem?: LoremDefinitions;
+  music?: MusicDefinitions;
+  person?: PersonDefinitions;
+  phone_number?: PhoneNumberDefinitions;
+  science?: ScienceDefinitions;
+  system?: SystemDefinitions;
+  vehicle?: VehicleDefinitions;
+  word?: WordDefinitions;
+} & Record<string, Record<string, unknown>>;

src/definitions/index.ts

@@ -8,12 +8,13 @@ export type {
 export type { CompanyDefinitions } from './company';
 export type { DatabaseDefinitions } from './database';
 export type { DateDefinitions, DateEntryDefinition } from './date';
-export type { Definitions, LocaleDefinition } from './definitions';
+export type { LocaleDefinition, LocaleEntry } from './definitions';
 export type { FinanceDefinitions } from './finance';
 export type { HackerDefinitions } from './hacker';
 export type { InternetDefinitions } from './internet';
 export type { LocationDefinitions } from './location';
 export type { LoremDefinitions } from './lorem';
+export type { MetadataDefinitions } from './metadata';
 export type { MusicDefinitions } from './music';
 export type { PersonDefinitions, PersonTitleDefinitions } from './person';
 export type { PhoneNumberDefinitions } from './phone_number';

src/definitions/metadata.ts

@@ -0,0 +1,6 @@
+export type MetadataDefinitions = {
+  /**
+   * The English name of the language (and the specific country, if defined).
+   */
+  title: string;
+} & Record<string, unknown>;

src/index.ts

@@ -12,10 +12,12 @@ export type {
   HackerDefinitions,
   InternetDefinitions,
   LocaleDefinition,
+  LocaleEntry,
   /** @deprecated Use LocationDefinitions instead */
   LocationDefinitions as AddressDefinitions,
   LocationDefinitions,
   LoremDefinitions,
+  MetadataDefinitions,
   MusicDefinitions,
   /** @deprecated Use PersonDefinitions instead */
   PersonDefinitions as NameDefinitions,

src/locale/en_IND.ts

@@ -0,0 +1,12 @@
+import { deprecated } from '../internal/deprecated';
+import { faker as en_IN } from './en_IN';
+
+export const faker = (() => {
+  deprecated({
+    deprecated: "import { faker } from '@faker-js/faker/locale/en_IND'",
+    proposed: "import { faker } from '@faker-js/faker/locale/en_IN'",
+    since: '8.0',
+    until: '9.0',
+  });
+  return en_IN;
+})();

src/locales/af_ZA/index.ts

@@ -7,15 +7,16 @@ import cell_phone from './cell_phone';
 import company from './company';
 import internet from './internet';
 import location from './location';
+import metadata from './metadata';
 import person from './person';
 import phone_number from './phone_number';
 
 const af_ZA: LocaleDefinition = {
-  title: 'Afrikaans',
   cell_phone,
   company,
   internet,
   location,
+  metadata,
   person,
   phone_number,
 };

src/locales/af_ZA/metadata.ts

@@ -0,0 +1,7 @@
+import type { MetadataDefinitions } from '../..';
+
+const metadata: MetadataDefinitions = {
+  title: 'Afrikaans',
+};
+
+export default metadata;

src/locales/ar/index.ts

@@ -8,18 +8,19 @@ import color from './color';
 import commerce from './commerce';
 import date from './date';
 import location from './location';
+import metadata from './metadata';
 import person from './person';
 import phone_number from './phone_number';
 import team from './team';
 import vehicle from './vehicle';
 
 const ar: LocaleDefinition = {
-  title: 'Arabic',
   cell_phone,
   color,
   commerce,
   date,
   location,
+  metadata,
   person,
   phone_number,
   team,

src/locales/ar/metadata.ts

@@ -0,0 +1,7 @@
+import type { MetadataDefinitions } from '../..';
+
+const metadata: MetadataDefinitions = {
+  title: 'Arabic',
+};
+
+export default metadata;