refactor!: remove dynamic locale switching support

scripts/bundle.ts

@@ -1,7 +1,7 @@
 import { buildSync } from 'esbuild';
 import { sync as globSync } from 'glob';
 import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
-import locales from '../src/locales';
+import { allLocales } from '../src';
 
 console.log('Building dist for node (cjs)...');
 
@@ -14,7 +14,7 @@ if (existsSync(localeDir)) {
 }
 
 mkdirSync(localeDir);
-for (const locale of Object.keys(locales)) {
+for (const locale of Object.keys(allLocales)) {
   writeFileSync(
     `${localeDir}/${locale}.js`,
     `module.exports = require('../dist/cjs/locale/${locale}');\n`,
@@ -43,7 +43,7 @@ console.log('Building dist for node type=module (esm)...');
 buildSync({
   entryPoints: [
     './src/index.ts',
-    ...Object.keys(locales).map((locale) => `./src/locale/${locale}.ts`),
+    ...Object.keys(allLocales).map((locale) => `./src/locale/${locale}.ts`),
   ],
   outdir: './dist/esm',
   bundle: true,

scripts/generateLocales.ts

@@ -12,7 +12,13 @@
  *
  * Run this script using `pnpm run generate:locales`
  */
-import { lstatSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import {
+  existsSync,
+  lstatSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs';
 import { resolve } from 'node:path';
 import type { Options } from 'prettier';
 import { format } from 'prettier';
@@ -24,6 +30,7 @@ import type { Definitions, LocaleDefinition } from '../src/definitions';
 const pathRoot = resolve(__dirname, '..');
 const pathLocale = resolve(pathRoot, 'src', 'locale');
 const pathLocales = resolve(pathRoot, 'src', 'locales');
+const pathLocaleIndex = resolve(pathLocale, 'index.ts');
 const pathLocalesIndex = resolve(pathLocales, 'index.ts');
 const pathDocsGuideLocalization = resolve(
   pathRoot,
@@ -107,19 +114,31 @@ function escapeField(module: string): string {
 }
 
 function generateLocaleFile(locale: string): void {
+  const parts = locale.split('_');
+  const locales = [locale];
+
+  for (let i = parts.length - 1; i > 0; i--) {
+    const fallback = parts.slice(0, i).join('_');
+    if (existsSync(resolve(pathLocales, fallback))) {
+      locales.push(fallback);
+    }
+  }
+
+  if (locales[locales.length - 1] !== 'en') {
+    locales.push('en');
+  }
+
   let content = `
       ${autoGeneratedCommentHeader}
 
       import { Faker } from '../faker';
-      import ${locale} from '../locales/${locale}';
-      ${locale !== 'en' ? "import en from '../locales/en';" : ''}
+      ${locales
+        .map((imp) => `import ${imp} from '../locales/${imp}';`)
+        .join('\n')}
 
       export const faker = new Faker({
-        locale: '${locale}',
-        localeFallback: 'en',
-        locales: {
-          ${locale},
-          ${locale !== 'en' ? 'en,' : ''}
+        locale: ${
+          locales.length === 1 ? locales[0] : `[${locales.join(', ')}]`
         },
       });
       `;
@@ -273,9 +292,10 @@ function updateLocaleFileHook(
 const locales = readdirSync(pathLocales);
 removeIndexTs(locales);
 
-let localeIndexImports = "import type { LocaleDefinition } from '..';\n";
-let localeIndexType = 'export type KnownLocale =\n';
-let localeIndexLocales = 'const locales: KnownLocales = {\n';
+let localeIndexImports = '';
+let localeIndexExportsIndividual = '';
+let localeIndexExportsGrouped = '';
+let localesIndexExports = '';
 
 let localizationLocales = '| Locale | Name |\n| :--- | :--- |\n';
 
@@ -287,9 +307,14 @@ for (const locale of locales) {
   const localeTitle = localeDef?.title ?? `TODO: Insert Title for ${locale}`;
   const localeSeparator = localeDef?.separator;
 
-  localeIndexImports += `import ${locale} from './${locale}';\n`;
-  localeIndexType += `  | '${locale}'\n`;
-  localeIndexLocales += `  ${locale},\n`;
+  const capitalizedLocale = locale.replace(/^([a-z]+)/, (part) =>
+    part.toUpperCase()
+  );
+
+  localeIndexImports += `import { faker as faker${capitalizedLocale} } from './${locale}';\n`;
+  localeIndexExportsIndividual += `  faker${capitalizedLocale},\n`;
+  localeIndexExportsGrouped += `  ${locale}: faker${capitalizedLocale},\n`;
+  localesIndexExports += `export { default as ${locale} } from './${locale}';\n`;
   localizationLocales += `| ${locale} | ${localeTitle} |\n`;
 
   // src/locale/<locale>.ts
@@ -307,24 +332,35 @@ for (const locale of locales) {
   );
 }
 
-// src/locales/index.ts
+// src/locale/index.ts
 
-let indexContent = `
+let localeIndexContent = `
   ${autoGeneratedCommentHeader}
 
   ${localeIndexImports}
 
-  ${localeIndexType};
+  export {
+  ${localeIndexExportsIndividual}
+  };
+
+  export const allFakers = {
+  ${localeIndexExportsGrouped}
+  } as const;
+  `;
 
-  export type KnownLocales = Record<KnownLocale, LocaleDefinition>;
+localeIndexContent = format(localeIndexContent, prettierTsOptions);
+writeFileSync(pathLocaleIndex, localeIndexContent);
 
-  ${localeIndexLocales}};
+// src/locales/index.ts
+
+let localesIndexContent = `
+  ${autoGeneratedCommentHeader}
 
-  export default locales;
+  ${localesIndexExports}
   `;
 
-indexContent = format(indexContent, prettierTsOptions);
-writeFileSync(pathLocalesIndex, indexContent);
+localesIndexContent = format(localesIndexContent, prettierTsOptions);
+writeFileSync(pathLocalesIndex, localesIndexContent);
 
 // docs/guide/localization.md
 

src/faker.ts

@@ -3,7 +3,6 @@ import { FakerError } from './errors/faker-error';
 import { deprecated } from './internal/deprecated';
 import type { Mersenne } from './internal/mersenne/mersenne';
 import mersenne from './internal/mersenne/mersenne';
-import type { KnownLocale } from './locales';
 import { AnimalModule } from './modules/animal';
 import { ColorModule } from './modules/color';
 import { CommerceModule } from './modules/commerce';
@@ -31,56 +30,10 @@ import { StringModule } from './modules/string';
 import { SystemModule } from './modules/system';
 import { VehicleModule } from './modules/vehicle';
 import { WordModule } from './modules/word';
-import type { LiteralUnion } from './utils/types';
-
-export type UsableLocale = LiteralUnion<KnownLocale>;
-export type UsedLocales = Partial<Record<UsableLocale, LocaleDefinition>>;
-
-export interface FakerOptions {
-  locales: UsedLocales;
-  locale?: UsableLocale;
-  localeFallback?: UsableLocale;
-}
-
-const metadataKeys: ReadonlyArray<keyof LocaleDefinition> = [
-  'title',
-  'separator',
-];
+import { mergeLocales } from './utils/merge-locales';
 
 export class Faker {
-  locales: UsedLocales;
-  private _locale: UsableLocale;
-  private _localeFallback: UsableLocale;
-
-  get locale(): UsableLocale {
-    return this._locale;
-  }
-
-  set locale(locale: UsableLocale) {
-    if (!this.locales[locale]) {
-      throw new FakerError(
-        `Locale ${locale} is not supported. You might want to add the requested locale first to \`faker.locales\`.`
-      );
-    }
-
-    this._locale = locale;
-  }
-
-  get localeFallback(): UsableLocale {
-    return this._localeFallback;
-  }
-
-  set localeFallback(localeFallback: UsableLocale) {
-    if (!this.locales[localeFallback]) {
-      throw new FakerError(
-        `Locale ${localeFallback} is not supported. You might want to add the requested locale first to \`faker.locales\`.`
-      );
-    }
-
-    this._localeFallback = localeFallback;
-  }
-
-  readonly definitions: LocaleDefinition = this.initDefinitions();
+  readonly definitions: LocaleDefinition;
 
   /** @internal */
   private readonly _mersenne: Mersenne = mersenne();
@@ -137,91 +90,20 @@ export class Faker {
     return this.person;
   }
 
-  constructor(opts: FakerOptions) {
-    if (!opts) {
-      throw new FakerError(
-        'Options with at least one entry in locales must be provided'
-      );
-    }
-
-    if (Object.keys(opts.locales ?? {}).length === 0) {
-      throw new FakerError(
-        'At least one entry in locales must be provided in the locales parameter'
-      );
-    }
-
-    this.locales = opts.locales;
-    this.locale = opts.locale || 'en';
-    this.localeFallback = opts.localeFallback || 'en';
-  }
-
-  /**
-   * Creates a Proxy based LocaleDefinition that virtually merges the locales.
-   */
-  private initDefinitions(): LocaleDefinition {
-    // Returns the first LocaleDefinition[key] in any locale
-    const resolveBaseData = (key: keyof LocaleDefinition): unknown =>
-      this.locales[this.locale][key] ?? this.locales[this.localeFallback][key];
+  constructor(options: { locale: LocaleDefinition | LocaleDefinition[] }) {
+    let { locale } = options;
 
-    // Returns the first LocaleDefinition[module][entry] in any locale
-    const resolveModuleData = (
-      module: keyof LocaleDefinition,
-      entry: string
-    ): unknown =>
-      this.locales[this.locale][module]?.[entry] ??
-      this.locales[this.localeFallback][module]?.[entry];
-
-    // Returns a proxy that can return the entries for a module (if it exists)
-    const moduleLoader = (
-      module: keyof LocaleDefinition
-    ): Record<string, unknown> | undefined => {
-      if (resolveBaseData(module)) {
-        return new Proxy(
-          {},
-          {
-            get(target, entry: string): unknown {
-              return resolveModuleData(module, entry);
-            },
-          }
+    if (Array.isArray(locale)) {
+      if (locale.length === 0) {
+        throw new FakerError(
+          'The locale option must contain at least one locale definition.'
         );
-      } else {
-        return undefined;
       }
-    };
 
-    return new Proxy({} as LocaleDefinition, {
-      get(target: LocaleDefinition, module: string): unknown {
-        // Support aliases
-        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',
-            until: '10.0',
-          });
-        }
+      locale = mergeLocales(locale);
+    }
 
-        let result = target[module];
-        if (result) {
-          return result;
-        } else if (metadataKeys.includes(module)) {
-          return resolveBaseData(module);
-        } else {
-          result = moduleLoader(module);
-          target[module] = result;
-          return result;
-        }
-      },
-    });
+    this.definitions = locale;
   }
 
   /**
@@ -295,13 +177,4 @@ export class Faker {
 
     return seed;
   }
-
-  /**
-   * Set Faker's locale
-   *
-   * @param locale The locale to set (e.g. `en` or `en_AU`, `en_AU_ocker`).
-   */
-  setLocale(locale: UsableLocale): void {
-    this.locale = locale;
-  }
 }

src/index.ts

@@ -1,6 +1,3 @@
-import { Faker } from './faker';
-import allLocales from './locales';
-
 export type {
   AnimalDefinitions,
   ColorDefinitions,
@@ -34,7 +31,11 @@ export type {
   WordDefinitions,
 } from './definitions';
 export { FakerError } from './errors/faker-error';
-export type { FakerOptions, UsableLocale, UsedLocales } from './faker';
+export { Faker } from './faker';
+export * from './locale';
+export { fakerEN as faker } from './locale';
+export * from './locales';
+export * as allLocales from './locales';
 export type { AnimalModule } from './modules/animal';
 export type {
   Casing,
@@ -78,9 +79,3 @@ export type { StringModule } from './modules/string';
 export type { SystemModule } from './modules/system';
 export type { VehicleModule } from './modules/vehicle';
 export type { WordModule } from './modules/word';
-export { Faker };
-
-// since we are requiring the top level of faker, load all locales by default
-export const faker: Faker = new Faker({
-  locales: allLocales,
-});

src/locale/af_ZA.ts

@@ -8,10 +8,5 @@ import af_ZA from '../locales/af_ZA';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: 'af_ZA',
-  localeFallback: 'en',
-  locales: {
-    af_ZA,
-    en,
-  },
+  locale: [af_ZA, en],
 });