Merge branch 'main' into fix-vehicle-vin-length

Author: Shinigami92

package.json

@@ -22,7 +22,7 @@
   },
   "license": "MIT",
   "main": "dist/cjs/index.js",
-  "module": "dist/esm/index.js",
+  "module": "dist/esm/index.mjs",
   "types": "index.d.ts",
   "typesVersions": {
     ">=4.0": {
@@ -33,14 +33,12 @@
   },
   "exports": {
     ".": {
-      "node": "./dist/cjs/index.js",
-      "es2015": "./dist/esm/index.js",
-      "default": "./dist/esm/index.js"
+      "require": "./dist/cjs/index.js",
+      "import": "./dist/esm/index.mjs"
     },
     "./locale/*": {
-      "node": "./dist/cjs/locale/*.js",
-      "es2015": "./dist/esm/locale/*.js",
-      "default": "./dist/esm/locale/*.js"
+      "require": "./dist/cjs/locale/*.js",
+      "import": "./dist/esm/locale/*.mjs"
     },
     "./package.json": "./package.json"
   },

scripts/bundle.ts

@@ -53,4 +53,5 @@ buildSync({
   splitting: true,
   format: 'esm',
   target: 'node12.20',
+  outExtension: { '.js': '.mjs' },
 });

src/fake.ts

@@ -17,7 +17,10 @@ export class Fake {
   /**
    * Generator method for combining faker methods based on string input.
    *
-   * This will check the given string for placeholders and replace them by calling the specified faker method.
+   * Note: If you just want to create a string on the fly, we recommend using string template literals instead.
+   * This method is useful if you wish to choose a random format from a non-executable source or persistent storage (json etc.).
+   *
+   * It checks the given string for placeholders and replace them by calling the specified faker method.
    * E.g. the input `Hi, my name is {{name.firstName}}!`,
    * will use the `faker.name.firstName()` method to resolve the placeholder.
    * It is also possible to combine static text with placeholders,

src/faker.ts

@@ -36,7 +36,7 @@ export type UsableLocale = LiteralUnion<KnownLocale>;
 export type UsedLocales = Partial<Record<UsableLocale, LocaleDefinition>>;
 
 export interface FakerOptions {
-  locales?: UsedLocales;
+  locales: UsedLocales;
   locale?: UsableLocale;
   localeFallback?: UsableLocale;
 }
@@ -81,50 +81,59 @@ export class Faker {
   readonly vehicle: Vehicle = new Vehicle(this);
   readonly word: Word = new Word(this);
 
-  constructor(opts: FakerOptions = {}) {
-    this.locales = this.locales || opts.locales || {};
+  constructor(opts: FakerOptions) {
+    if (!opts) {
+      throw new Error(
+        'Options with at least one entry in locales must be provided'
+      );
+    }
+
+    if (Object.keys(opts.locales ?? {}).length === 0) {
+      throw new Error(
+        'At least one entry in locales must be provided in the locales parameter'
+      );
+    }
+
+    this.locales = opts.locales;
     this.locale = this.locale || opts.locale || 'en';
     this.localeFallback = this.localeFallback || opts.localeFallback || 'en';
 
     this.loadDefinitions();
   }
 
   /**
-   * Load the definitions contained in the locales file for the given types
+   * Load the definitions contained in the locales file for the given types.
+   *
+   * Background: Certain localization sets contain less data then others.
+   * In the case of a missing definition, use the localeFallback's values
+   * to substitute the missing data.
    */
   private loadDefinitions(): void {
     // TODO @Shinigami92 2022-01-11: Find a way to load this even more dynamically
     // In a way so that we don't accidentally miss a definition
-    Object.entries(DEFINITIONS).forEach(([t, v]) => {
-      if (this.definitions[t] == null) {
-        this.definitions[t] = {};
+    for (const [moduleName, entryNames] of Object.entries(DEFINITIONS)) {
+      if (typeof entryNames === 'string') {
+        // For 'title' and 'separator'
+        Object.defineProperty(this.definitions, moduleName, {
+          get: (): unknown /* string */ =>
+            this.locales[this.locale][moduleName] ??
+            this.locales[this.localeFallback][moduleName],
+        });
+        continue;
       }
 
-      if (typeof v === 'string') {
-        this.definitions[t] = v;
-        return;
+      if (this.definitions[moduleName] == null) {
+        this.definitions[moduleName] = {};
       }
 
-      v.forEach((p) => {
-        Object.defineProperty(this.definitions[t], p, {
-          get: () => {
-            if (
-              this.locales[this.locale][t] == null ||
-              this.locales[this.locale][t][p] == null
-            ) {
-              // certain localization sets contain less data then others.
-              // in the case of a missing definition, use the default localeFallback
-              // to substitute the missing set data
-              // throw new Error('unknown property ' + d + p)
-              return this.locales[this.localeFallback][t][p];
-            } else {
-              // return localized data
-              return this.locales[this.locale][t][p];
-            }
-          },
+      for (const entryName of entryNames) {
+        Object.defineProperty(this.definitions[moduleName], entryName, {
+          get: (): unknown =>
+            this.locales[this.locale][moduleName]?.[entryName] ??
+            this.locales[this.localeFallback][moduleName]?.[entryName],
         });
-      });
-    });
+      }
+    }
   }
 
   seed(seed?: number | number[]): void {

src/git.ts

@@ -61,18 +61,17 @@ export class Git {
    */
   commitEntry(options: { merge?: boolean } = {}): string {
     // TODO @Shinigami92 2022-01-11: We may want to make it configurable to use just `\n` instead of `\r\n`
-    let entry = 'commit {{git.commitSha}}\r\n';
+    let entry = `commit ${this.commitSha()}\r\n`;
 
     if (options.merge || this.faker.datatype.number({ min: 0, max: 4 }) === 0) {
-      entry += 'Merge: {{git.shortSha}} {{git.shortSha}}\r\n';
+      entry += `Merge: ${this.shortSha()}} ${this.shortSha()}\r\n`;
     }
 
-    entry +=
-      'Author: {{name.firstName}} {{name.lastName}} <{{internet.email}}>\r\n';
-    entry += 'Date: ' + this.faker.date.recent().toString() + '\r\n';
-    entry += '\r\n\xa0\xa0\xa0\xa0{{git.commitMessage}}\r\n';
+    entry += `Author: ${this.faker.name.firstName()} ${this.faker.name.lastName()} <${this.faker.internet.email()}>\r\n`;
+    entry += `Date: ${this.faker.date.recent().toString()}\r\n`;
+    entry += `\r\n\xa0\xa0\xa0\xa0${this.commitMessage()}\r\n`;
 
-    return this.faker.fake(entry);
+    return entry;
   }
 
   /**
@@ -82,8 +81,7 @@ export class Git {
    * faker.git.commitMessage() // 'reboot cross-platform driver'
    */
   commitMessage(): string {
-    const format = '{{hacker.verb}} {{hacker.adjective}} {{hacker.noun}}';
-    return this.faker.fake(format);
+    return `${this.faker.hacker.verb()} ${this.faker.hacker.adjective()} ${this.faker.hacker.noun()}`;
   }
 
   /**

src/helpers.ts

@@ -1,4 +1,5 @@
 import type { Faker } from '.';
+import { deprecated } from './internal/deprecated';
 
 /**
  * A full card with various details.
@@ -143,9 +144,12 @@ export class Helpers {
   randomize<T = string>(
     array: ReadonlyArray<T> = ['a', 'b', 'c'] as unknown as ReadonlyArray<T>
   ): T {
-    console.warn(
-      'Deprecation Warning: faker.helpers.randomize is now located in faker.random.arrayElement'
-    );
+    deprecated({
+      deprecated: 'faker.helpers.randomize()',
+      proposed: 'faker.random.arrayElement()',
+      // since: 'v5.0.0', (?)
+      until: 'v7.0.0',
+    });
     return this.faker.random.arrayElement(array);
   }
 
@@ -511,9 +515,12 @@ export class Helpers {
    * @deprecated If you need some specific object you should create your own method.
    */
   createCard(): Card {
-    console.warn(
-      'Deprecation Warning: If you need some specific object you should create your own method.'
-    );
+    deprecated({
+      deprecated: 'helpers.createCard()',
+      proposed: 'a self-build function',
+      since: 'v6.1.0',
+      until: 'v7.0.0',
+    });
     return {
       name: this.faker.name.findName(),
       username: this.faker.internet.userName(),
@@ -582,9 +589,12 @@ export class Helpers {
    * @deprecated If you need some specific object you should create your own method.
    */
   contextualCard(): ContextualCard {
-    console.warn(
-      'Deprecation Warning: If you need some specific object you should create your own method.'
-    );
+    deprecated({
+      deprecated: 'helpers.contextualCard()',
+      proposed: 'a self-build function',
+      since: 'v6.1.0',
+      until: 'v7.0.0',
+    });
     const name = this.faker.name.firstName();
     const userName = this.faker.internet.userName(name);
     return {
@@ -631,9 +641,12 @@ export class Helpers {
    * @deprecated If you need some specific object you should create your own method.
    */
   userCard(): UserCard {
-    console.warn(
-      'Deprecation Warning: If you need some specific object you should create your own method.'
-    );
+    deprecated({
+      deprecated: 'helpers.userCard()',
+      proposed: 'a self-build function',
+      since: 'v6.1.0',
+      until: 'v7.0.0',
+    });
     return {
       name: this.faker.name.findName(),
       username: this.faker.internet.userName(),

src/internal/deprecated.ts

@@ -0,0 +1,29 @@
+/* eslint-disable jsdoc/check-tag-names */
+/* eslint-disable jsdoc/require-param */
+
+/** @internal */
+export interface DeprecatedOptions {
+  deprecated: string;
+  proposed?: string;
+  since?: string;
+  until?: string;
+}
+
+/** @internal */
+export function deprecated(opts: DeprecatedOptions): void {
+  let message = `[@faker-js/faker]: ${opts.deprecated} is deprecated`;
+
+  if (opts.since) {
+    message += ` since ${opts.since}`;
+  }
+
+  if (opts.until) {
+    message += ` and will be removed in ${opts.until}`;
+  }
+
+  if (opts.proposed) {
+    message += `. Please use ${opts.proposed} instead`;
+  }
+
+  console.warn(message + '.');
+}

src/lorem.ts

@@ -175,17 +175,19 @@ export class Lorem {
    * // Dolor tempora iusto.'
    */
   text(): string {
-    const loremMethods = [
-      'lorem.word',
-      'lorem.words',
-      'lorem.sentence',
-      'lorem.sentences',
-      'lorem.paragraph',
-      'lorem.paragraphs',
-      'lorem.lines',
+    const methods: Array<keyof Lorem> = [
+      'word',
+      'words',
+      'sentence',
+      'sentences',
+      'paragraph',
+      'paragraphs',
+      'lines',
     ];
-    const randomLoremMethod = this.faker.random.arrayElement(loremMethods);
-    return this.faker.fake(`{{${randomLoremMethod}}}`);
+
+    const method = this.faker.random.arrayElement(methods);
+
+    return `${this[method]()}`;
   }
 
   /**