diff --git a/docs/guide/upgrading_v9/2682.md b/docs/guide/upgrading_v9/2682.md new file mode 100644 index 00000000000..f735f6243d0 --- /dev/null +++ b/docs/guide/upgrading_v9/2682.md @@ -0,0 +1,10 @@ +### 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` diff --git a/src/faker.ts b/src/faker.ts index ff54e2f3893..dbced02e193 100644 --- a/src/faker.ts +++ b/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; - /** - * 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[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; - /** - * 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; - locale?: string; - localeFallback?: string; - randomizer?: Randomizer; - } - ) { + constructor(options: { + locale: LocaleDefinition | LocaleDefinition[]; + randomizer?: Randomizer; + }) { super({ randomizer: options.randomizer }); - const { locales } = options as { - locales: Record; - }; - - 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[0];