Upgrading to v8 ​

This is the migration guide for upgrading from v7 to v8.

Breaking changes ​

Removed ability to change the locale on existing Faker instances ​

In order to facilitate better and easier locale fallback mechanics, we removed the methods to change the locales on existing Faker instances. Now, we expose specific faker instances for each locale that you can use:

Old

import { faker } from '@faker-js/faker';

faker.setLocale('de_CH');
// or
faker.locale = 'de_CH';
faker.localeFallback = 'en';

New

import { fakerDE_CH as faker } from '@faker-js/faker';

This also fixes issues where more than two locales are required:

Old

import { faker, Faker } from '@faker-js/faker';

const { de_CH, de, en } = faker.locales;
const customFaker = new Faker({
  locale: 'de_CH', // the expected locale
  localeFallback: 'de', // ensure we have a German fallback for addresses
  locales: { de_CH, de, en },
});
const a = customFaker.internet.email();
customFaker.locale = 'en'; // neither 'de_CH' nor 'de' have emojis
const b = customFaker.internet.emoji();

New

import { base, de, de_CH, en, Faker } from '@faker-js/faker';

// same as fakerDE_CH
export const customFaker = new Faker({
  // Now multiple fallbacks are supported
  locale: [de_CH, de, en, base],
});
const a = customFaker.internet.email();
const b = customFaker.internet.emoji();

If you wish to create entries for multiple locales, you can still do so:

Old

import { faker } from '@faker-js/faker';

for (let user of users) {
  const lang = faker.helpers.arrayElement(['de', 'en', 'fr']);
  faker.locale = lang;
  user.email = faker.internet.email();
}

New

import { faker, fakerDE, fakerEN, fakerFR } from '@faker-js/faker';

for (let user of users) {
  const currentFaker = faker.helpers.arrayElement([fakerDE, fakerEN, fakerFR]);
  user.email = currentFaker.internet.email();
}

For more information refer to our Localization Guide.

For missing locale data, Faker will now throw instead of returning undefined or a-c ​

Previously, for example if en didn't have data for animal.cat, then faker.animal.cat() would have returned one of a, b or c (arrayElement's default value). These values aren't expected/useful as a fallback and potentially also violate the method's defined return type definitions (in case it doesn't return a string).

We have now addressed this by changing the implementation so that an error is thrown, prompting you to provide/contribute the missing data. This will also give you detailed information which data are missing. If you want to check for data you can either use entry in faker.definitions.category or use faker.rawDefinitions.category?.entry instead.

import { es, Faker, fakerES } from '@faker-js/faker';

const fakerES_noFallbacks = new Faker({
  locale: [es],
});
fakerES.music.songName(); // 'I Want to Hold Your Hand' (fallback from en)
// Previously:
//fakerES_noFallbacks.music.songName(); // 'b'
// Now:
fakerES_noFallbacks.music.songName(); // throws a FakerError

This also has an impact on data that aren't applicable to a locale, for example Hong Kong (en_HK) doesn't use ZIP codes/postcodes.

import { fakerEN_HK, fakerEN_US } from '@faker-js/faker';
fakerEN_US.location.zipCode(); // 90210
fakerEN_HK.location.zipCode(); // throws a FakerError

faker.mersenne and faker.helpers.repeatString removed ​

faker.mersenne and faker.helpers.repeatString were only ever intended for internal use, and are no longer available.

faker.location.zipCodeByState ​

The faker.location.zipCodeByState method has been deprecated, but will also now throw an error if the current locale does not have a postcode_by_state definition.

Methods will throw on empty data set inputs ​

The methods faker.helpers.arrayElement and faker.helpers.arrayElements previously defaulted the array argument to a simple string array if none was provided. This behavior is no longer supported, as the default value has been removed. You are now required to provide an argument.

Additionally, when passing in an empty array argument ([]), the functions previously returned undefined. This behavior violated the expected return type of the method. The methods will now throw an FakerError instead.

The same thing happens now if you provide an empty object {} to faker.helpers.objectKey or faker.helpers.objectValue.

Old

const allTags = ['dogs', 'cats', 'fish', 'horses', 'sheep'];
const tags = faker.helpers.arrayElements(allTags, { min: 0, max: 3 });
// `tags` might be an empty array which was no problem in v7
const featuredTag = faker.helpers.arrayElement(tags);
// `featureTag` will be typed as `string` but could actually be `undefined`

New

const allTags = ['dogs', 'cats', 'fish', 'horses', 'sheep'];
const tags = faker.helpers.arrayElements(allTags, { min: 0, max: 3 });
// `tags` might be an empty array which will throw in v8
const featuredTag =
  tags.length === 0 ? undefined : faker.helpers.arrayElement(tags);
// `featureTag` has to be explicitly set to `undefined` on your side

// OR

const allTags = ['dogs', 'cats', 'fish', 'horses', 'sheep'];
const tags = faker.helpers.arrayElements(allTags, { min: 0, max: 3 });
let featuredTag: string | undefined;
try {
  featuredTag = faker.helpers.arrayElement(post.tags);
} catch (e) {
  // handle error and do something special
}

Other deprecated methods removed/replaced ​

Definitions removed ​

Some data definitions, which were only available via the faker.helpers.fake method, or the undocumented faker.definitions, have been removed.

Deprecations and other changes ​

This is not an exhaustive list of all deprecations in v8.0.0. Many methods and parameters have been renamed in this release. You can:

• use the warnings which are shown at runtime to guide you to the new names
• use a suitable plugin to find usages of deprecated code
• Review the full list of deprecations here and here
• Ignore the deprecations for now: the old names will continue to work for v8.x.x, however you will need to make changes before upgrading to v9.x.x.

faker.name changed to faker.person ​

The whole faker.name module is now located at faker.person, as it contains more information than just names. The faker.name.* methods will continue to work as an alias in v8 and v9, but it is recommended to change to faker.person.*

faker.address changed to faker.location ​

The whole faker.address module is now located at faker.location, as it contains more information than just addresses. The faker.address.* methods will continue to work as an alias in v8 and v9, but it is recommended to change to faker.location.*

Number methods of faker.datatype moved to new faker.number module ​

The number-related methods previously found in faker.datatype have been moved to a new faker.number module. For the old faker.datatype.number method you should replace with faker.number.int or faker.number.float depending on the precision required.

By default, faker.number.float no longer defaults to a precision of 0.01

// OLD
faker.datatype.number(); // 88999 (NOTE: The default max was 99999)
faker.datatype.number({ max: 100 }); // 35
faker.datatype.number({ max: 100, precision: 0.01 }); // 35.21
faker.datatype.float({ max: 100 }); // 35.21
faker.datatype.float({ max: 100, precision: 0.001 }); // 35.211

// NEW
faker.number.int({ max: 99999 }); // 88999 (NOTE: the default max is now Number.MAX_SAFE_INTEGER)
faker.number.int({ max: 100 }); // 35
faker.number.float({ max: 100 }); // 35.21092065742612
faker.number.float({ max: 100, precision: 0.01 }); // 35.21

Deprecation of faker.datatype.array ​

The method faker.datatype.array has been deprecated and will be removed in v9. If you need an array of useful values, you are better off creating your own one using faker.helpers.multiple.

faker.datatype.datetime deprecated in favor of faker.date.between and faker.date.anytime ​

The datetime method previously found in faker.datatype has been deprecated, use faker.date.between or faker.date.anytime instead.

faker.helpers.regexpStyleStringParse deprecated in favor of faker.helpers.fromRegExp ​

The regexpStyleStringParse method in faker.helpers has been deprecated in Faker 8.1. A likely replacement is the more powerful faker.helpers.fromRegExp.

faker.helpers.regexpStyleStringParse('a{3,6}'); // aaaaa
faker.helpers.fromRegExp('a{3,6}'); // aaaaa

However, please note that faker.helpers.fromRegExp is not an exact replacement for faker.helpers.regexpStyleStringParse as fromRegExp cannot handle numeric ranges. This will now need to be handled separately.

faker.helpers.regexpStyleStringParse('a{3,6}[1-100]'); // "aaaa53", etc.
faker.helpers.fromRegExp('a{3,6}') + faker.number.int({ min: 1, max: 100 });

allowLeadingZeros behavior change in faker.string.numeric ​

The allowLeadingZeros boolean parameter in faker.string.numeric (in the new string module) now defaults to true. faker.string.numeric will now generate numeric strings that could have leading zeros by default.

Simplified MIME type data ​

The functions faker.system.mimeType, faker.system.fileType and faker.system.fileExt now return data from a smaller set of more common MIME types, filetypes and extensions.

faker.helpers.unique is planned to be outsourced ​

The faker.helpers.unique method is planned to be outsourced to a separate package.
Please check issue #1785 for more details.

Locales renamed ​

The en_IND (English, India) locale was renamed to en_IN for consistency with other locales.

The cz (Czech) locale was renamed to cs_CZ to use the standard ISO codes for language and country.

The ge (Georgian) locale was renamed to ka_GE to use the standard ISO codes for language and country.