Merge branch 'next' into docs/module-guides

.editorconfig

@@ -9,5 +9,4 @@ trim_trailing_whitespace = true
 insert_final_newline = true
 
 [*.md]
-max_line_length = off
 trim_trailing_whitespace = false

docs/guide/localization.md

@@ -44,7 +44,7 @@ If our built-in faker instances don't satisfy your needs, you can build your own
 
 ```ts
 import type { LocaleDefinition } from '@faker-js/faker';
-import { Faker, de_CH, de, en } from '@faker-js/faker';
+import { Faker, de_CH, de, en, base } from '@faker-js/faker';
 
 const customLocale: LocaleDefinition = {
   title: 'My custom locale',
@@ -54,10 +54,18 @@ const customLocale: LocaleDefinition = {
 };
 
 export const customFaker = new Faker({
-  locale: [customLocale, de_CH, de, en, global],
+  locale: [customLocale, de_CH, de, en, base],
 });
 ```
 
+In this example there are 5 locales. Each of these is checked in order, and the first locale which contains the requested data will be used:
+
+- `customLocale` is your custom locale definition which will override all other fallback definitions.
+- `de_CH` is a specific locale definition that overrides some German definitions with `CH` (Switzerland) data.
+- `de` is a generic `de` (German) locale definition.
+- `en` is a generic `en` (English) locale definition. This is our most complete locale, so we add it to fill some gaps. Depending on your needs, you might want or not want to have it as a fallback.
+- `base` is the base locale definition which contains definitions that can be used in every language (e.g. emojis).
+
 ## Available locales
 
 <!-- LOCALES-AUTO-GENERATED-START -->
@@ -69,6 +77,7 @@ export const customFaker = new Faker({
 | `af_ZA`       | Afrikaans                 | `fakerAF_ZA`       |
 | `ar`          | Arabic                    | `fakerAR`          |
 | `az`          | Azerbaijani               | `fakerAZ`          |
+| `base`        | Base                      | `fakerBASE`        |
 | `cz`          | Czech                     | `fakerCZ`          |
 | `de`          | German                    | `fakerDE`          |
 | `de_AT`       | German (Austria)          | `fakerDE_AT`       |

docs/guide/upgrading.md

@@ -60,12 +60,12 @@ const b = customFaker.internet.emoji();
 **New**
 
 ```ts
-import { Faker, de_CH, de, en, global } from '@faker-js/faker';
+import { Faker, de_CH, de, en, base } from '@faker-js/faker';
 
 // same as fakerDE_CH
 export const customFaker = new Faker({
   // Now multiple fallbacks are supported
-  locale: [de_CH, de, en, global],
+  locale: [de_CH, de, en, base],
 });
 const a = customFaker.internet.email();
 const b = customFaker.internet.emoji();

package.json

@@ -112,7 +112,7 @@
     "glob": "~9.3.2",
     "npm-run-all": "~4.1.5",
     "picocolors": "~1.0.0",
-    "prettier": "2.8.4",
+    "prettier": "2.8.7",
     "prettier-plugin-organize-imports": "~3.2.2",
     "react": "~18.2.0",
     "react-dom": "~18.2.0",

scripts/apidoc/signature.ts

@@ -308,7 +308,17 @@ function typeToText(type_?: Type, short = false): string {
 
     case 'reference':
       if (!type.typeArguments || !type.typeArguments.length) {
-        return type.name;
+        const reflection = type.reflection as DeclarationReflection | undefined;
+        const reflectionType = reflection?.type;
+        if (
+          (reflectionType?.type === 'literal' ||
+            reflectionType?.type === 'union') &&
+          !type.name.match(/Char$/)
+        ) {
+          return typeToText(reflectionType, short);
+        } else {
+          return type.name;
+        }
       } else if (type.name === 'LiteralUnion') {
         return [
           typeToText(type.typeArguments[0], short),

scripts/generateLocales.ts

@@ -125,10 +125,15 @@ function generateLocaleFile(locale: string): void {
     }
   }
 
-  if (locales[locales.length - 1] !== 'en') {
+  // TODO christopher 2023-03-07: Remove 'en' fallback in a separate PR
+  if (locales[locales.length - 1] !== 'en' && locale !== 'base') {
     locales.push('en');
   }
 
+  if (locales[locales.length - 1] !== 'base') {
+    locales.push('base');
+  }
+
   let content = `
       ${autoGeneratedCommentHeader}
 
@@ -148,8 +153,10 @@ function generateLocaleFile(locale: string): void {
   writeFileSync(resolve(pathLocale, `${locale}.ts`), content);
 }
 
-function tryLoadLocalesMainIndexFile(pathModules: string): LocaleDefinition {
-  let localeDef: LocaleDefinition;
+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
@@ -165,9 +172,10 @@ function tryLoadLocalesMainIndexFile(pathModules: string): LocaleDefinition {
         resolve(pathModules, 'index.ts'),
         'utf-8'
       );
-      localeDef = {
-        title: localeIndex.match(/title: '(.*)',/)[1],
-      };
+      const title = localeIndex.match(/title: '(.*)',/)?.[1];
+      if (title) {
+        localeDef = { title };
+      }
     } catch {
       console.error(`Failed to load ${pathModules} or manually parse it.`, e);
     }

src/definitions/location.ts

@@ -45,17 +45,17 @@ export type LocationDefinitions = LocaleEntry<{
   country_code: Array<{ alpha2: string; alpha3: string }>;
 
   /**
-   * The names of this country's states.
+   * The names of this country's states, or other first-level administrative areas.
    */
   state: string[];
 
   /**
-   * The abbreviated names of this country's states.
+   * The abbreviated names of this country's states, or other first-level administrative areas.
    */
   state_abbr: string[];
 
   /**
-   * The names of counties inside the country or state.
+   * The names of counties, or other second-level administrative areas, inside the country's states.
    */
   county: string[];
 

src/locale/af_ZA.ts

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

src/locale/ar.ts

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

src/locale/az.ts

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

src/locale/base.ts

@@ -0,0 +1,11 @@
+/*
+ * This file is automatically generated.
+ * Run 'pnpm run generate:locales' to update.
+ */
+
+import { Faker } from '../faker';
+import base from '../locales/base';
+
+export const faker = new Faker({
+  locale: base,
+});

src/locale/cz.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import cz from '../locales/cz';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: [cz, en],
+  locale: [cz, en, base],
 });

src/locale/de.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import de from '../locales/de';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: [de, en],
+  locale: [de, en, base],
 });

src/locale/de_AT.ts

@@ -4,10 +4,11 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import de from '../locales/de';
 import de_AT from '../locales/de_AT';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: [de_AT, de, en],
+  locale: [de_AT, de, en, base],
 });

src/locale/de_CH.ts

@@ -4,10 +4,11 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import de from '../locales/de';
 import de_CH from '../locales/de_CH';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: [de_CH, de, en],
+  locale: [de_CH, de, en, base],
 });

src/locale/dv.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import dv from '../locales/dv';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: [dv, en],
+  locale: [dv, en, base],
 });

src/locale/el.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import el from '../locales/el';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: [el, en],
+  locale: [el, en, base],
 });

src/locale/en.ts

@@ -4,8 +4,9 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: en,
+  locale: [en, base],
 });

src/locale/en_AU.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import en from '../locales/en';
 import en_AU from '../locales/en_AU';
 
 export const faker = new Faker({
-  locale: [en_AU, en],
+  locale: [en_AU, en, base],
 });

src/locale/en_AU_ocker.ts

@@ -4,10 +4,11 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import en from '../locales/en';
 import en_AU from '../locales/en_AU';
 import en_AU_ocker from '../locales/en_AU_ocker';
 
 export const faker = new Faker({
-  locale: [en_AU_ocker, en_AU, en],
+  locale: [en_AU_ocker, en_AU, en, base],
 });

src/locale/en_BORK.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import en from '../locales/en';
 import en_BORK from '../locales/en_BORK';
 
 export const faker = new Faker({
-  locale: [en_BORK, en],
+  locale: [en_BORK, en, base],
 });

src/locale/en_CA.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import en from '../locales/en';
 import en_CA from '../locales/en_CA';
 
 export const faker = new Faker({
-  locale: [en_CA, en],
+  locale: [en_CA, en, base],
 });