refactor!: remove v8 deprecated faker class parts (#2682)

Author: Shinigami92

docs/guide/upgrading_v9/2682.md

@@ -0,0 +1,22 @@
+### Remove deprecated faker constructor and deprecated JS backwards compatibility
+
+Removed deprecated faker constructor, so it is not possible anymore to just pass a locale string identifier.
+
+Also removed the accessors and method that were only for JS backwards compatibility.
+
+- `get/set locales`
+- `get/set locale`
+- `get/set localeFallback`
+- `setLocale`
+
+To use the new constructor, you need to pass a locale object like:
+
+```ts
+import { Faker, es, base } from '@faker-js/faker';
+
+// A custom faker instance that does not have any fallbacks
+const customEsFakerWithoutFallback = new Faker({ locale: es });
+
+// A custom faker instance that has only base-data as fallback, but not english data
+const customEsFakerWithFallback = new Faker({ locale: [es, base] });
+```

src/faker.ts

@@ -163,169 +163,13 @@ export class Faker extends SimpleFaker {
      */
     randomizer?: Randomizer;
   });
-  /**
-   * Creates a new instance of Faker.
-   *
-   * In most cases you should use one of the prebuilt Faker instances instead of the constructor, for example `fakerDE`, `fakerFR`, ...
-   *
-   * You only need to use the constructor if you need custom fallback logic or a custom locale.
-   *
-   * For more information see our [Localization Guide](https://fakerjs.dev/guide/localization.html).
-   *
-   * @param options The options to use.
-   * @param options.locales The locale data to use.
-   * @param options.locale The name of the main locale to use.
-   * @param options.localeFallback The name of the fallback locale to use.
-   *
-   * @example
-   * import { Faker, allLocales } from '@faker-js/faker';
-   * // const { Faker, allLocales } = require('@faker-js/faker');
-   *
-   * new Faker({ locales: allLocales });
-   *
-   * @since 6.0.0
-   *
-   * @deprecated Use `new Faker({ locale: [locale, localeFallback] })` instead.
-   */
-  constructor(options: {
-    /**
-     * The locale data to use for this instance.
-     *
-     * @deprecated Use `new Faker({ locale: [locale, localeFallback] })` instead.
-     */
-    locales: Record<string, LocaleDefinition>;
-    /**
-     * The name of the main locale to use.
-     *
-     * @default 'en'
-     *
-     * @deprecated Use `new Faker({ locale: [locale, localeFallback] })` instead.
-     */
-    locale?: string;
-    /**
-     * The name of the fallback locale to use.
-     *
-     * @default 'en'
-     *
-     * @deprecated Use `new Faker({ locale: [locale, localeFallback] })` instead.
-     */
-    localeFallback?: string;
-  });
-  // This is somehow required for `ConstructorParameters<typeof Faker>[0]` to work
-  /**
-   * Creates a new instance of Faker.
-   *
-   * In most cases you should use one of the prebuilt Faker instances instead of the constructor, for example `fakerDE`, `fakerFR`, ...
-   *
-   * You only need to use the constructor if you need custom fallback logic or a custom locale.
-   *
-   * For more information see our [Localization Guide](https://fakerjs.dev/guide/localization.html).
-   *
-   * @param options The options to use.
-   * @param options.locale The locale data to use or the name of the main locale.
-   * @param options.locales The locale data to use.
-   * @param options.localeFallback The name of the fallback locale to use.
-   * @param options.randomizer The Randomizer to use.
-   * Specify this only if you want to use it to achieve a specific goal,
-   * such as sharing the same random generator with other instances/tools.
-   * Defaults to faker's Mersenne Twister based pseudo random number generator.
-   *
-   * @example
-   * import { Faker, es } from '@faker-js/faker';
-   * // const { Faker, es } = require('@faker-js/faker');
-   *
-   * // create a Faker instance with only es data and no en fallback (=> smaller bundle size)
-   * const customFaker = new Faker({ locale: [es] });
-   *
-   * customFaker.person.firstName(); // 'Javier'
-   * customFaker.person.lastName(); // 'Ocampo Corrales'
-   *
-   * customFaker.music.genre(); // throws Error as this data is not available in `es`
-   *
-   * @since 8.0.0
-   */
-  constructor(
-    options:
-      | {
-          /**
-           * The locale data to use for this instance.
-           * If an array is provided, the first locale that has a definition for a given property will be used.
-           *
-           * @see mergeLocales(): For more information about how the locales are merged.
-           */
-          locale: LocaleDefinition | LocaleDefinition[];
 
-          /**
-           * The Randomizer to use.
-           * Specify this only if you want to use it to achieve a specific goal,
-           * such as sharing the same random generator with other instances/tools.
-           *
-           * @default generateMersenne32Randomizer()
-           */
-          randomizer?: Randomizer;
-        }
-      | {
-          /**
-           * The locale data to use for this instance.
-           *
-           * @deprecated Use `new Faker({ locale: [locale, localeFallback] })` instead.
-           */
-          locales: Record<string, LocaleDefinition>;
-          /**
-           * The name of the main locale to use.
-           *
-           * @default 'en'
-           *
-           * @deprecated Use `new Faker({ locale: [locale, localeFallback] })` instead.
-           */
-          locale?: string;
-          /**
-           * The name of the fallback locale to use.
-           *
-           * @default 'en'
-           *
-           * @deprecated Use `new Faker({ locale: [locale, localeFallback] })` instead.
-           */
-          localeFallback?: string;
-        }
-  );
-  constructor(
-    options:
-      | {
-          locale: LocaleDefinition | LocaleDefinition[];
-          randomizer?: Randomizer;
-        }
-      | {
-          locales: Record<string, LocaleDefinition>;
-          locale?: string;
-          localeFallback?: string;
-          randomizer?: Randomizer;
-        }
-  ) {
+  constructor(options: {
+    locale: LocaleDefinition | LocaleDefinition[];
+    randomizer?: Randomizer;
+  }) {
     super({ randomizer: options.randomizer });
 
-    const { locales } = options as {
-      locales: Record<string, LocaleDefinition>;
-    };
-
-    if (locales != null) {
-      deprecated({
-        deprecated:
-          "new Faker({ locales: {a, b}, locale: 'a', localeFallback: 'b' })",
-        proposed:
-          'new Faker({ locale: [a, b, ...] }) or new Faker({ locale: a })',
-        since: '8.0',
-        until: '9.0',
-      });
-      const { locale = 'en', localeFallback = 'en' } = options as {
-        locale: string;
-        localeFallback: string;
-      };
-      options = {
-        locale: [locales[locale], locales[localeFallback]],
-      };
-    }
-
     let { locale } = options;
 
     if (Array.isArray(locale)) {
@@ -338,7 +182,7 @@ export class Faker extends SimpleFaker {
       locale = mergeLocales(locale);
     }
 
-    this.rawDefinitions = locale as LocaleDefinition;
+    this.rawDefinitions = locale;
     this.definitions = createLocaleProxy(this.rawDefinitions);
   }
 
@@ -356,85 +200,6 @@ export class Faker extends SimpleFaker {
   getMetadata(): MetadataDefinition {
     return this.rawDefinitions.metadata ?? {};
   }
-
-  // Pure JS backwards compatibility
-
-  /**
-   * Do NOT use. This property has been removed.
-   *
-   * @deprecated Use the constructor instead.
-   */
-  private get locales(): never {
-    throw new FakerError(
-      'The locales property has been removed. Please use the constructor instead.'
-    );
-  }
-
-  /**
-   * Do NOT use. This property has been removed.
-   *
-   * @deprecated Use the constructor instead.
-   */
-  private set locales(value: never) {
-    throw new FakerError(
-      'The locales property has been removed. Please use the constructor instead.'
-    );
-  }
-
-  /**
-   * Do NOT use. This property has been removed.
-   *
-   * @deprecated Use the constructor instead.
-   */
-  private get locale(): never {
-    throw new FakerError(
-      'The locale property has been removed. Please use the constructor instead.'
-    );
-  }
-
-  /**
-   * Do NOT use. This property has been removed.
-   *
-   * @deprecated Use the constructor instead.
-   */
-  private set locale(value: never) {
-    throw new FakerError(
-      'The locale property has been removed. Please use the constructor instead.'
-    );
-  }
-
-  /**
-   * Do NOT use. This property has been removed.
-   *
-   * @deprecated Use the constructor instead.
-   */
-  private get localeFallback(): never {
-    throw new FakerError(
-      'The localeFallback property has been removed. Please use the constructor instead.'
-    );
-  }
-
-  /**
-   * Do NOT use. This property has been removed.
-   *
-   * @deprecated Use the constructor instead.
-   */
-  private set localeFallback(value: never) {
-    throw new FakerError(
-      'The localeFallback property has been removed. Please use the constructor instead.'
-    );
-  }
-
-  /**
-   * Do NOT use. This property has been removed.
-   *
-   * @deprecated Use the constructor instead.
-   */
-  private setLocale(): never {
-    throw new FakerError(
-      'This method has been removed. Please use the constructor instead.'
-    );
-  }
 }
 
 export type FakerOptions = ConstructorParameters<typeof Faker>[0];