Upgrading to v8

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

Not the version you are looking for?

Breaking changes

Removed ability to change the locale on existing `Faker` instances

Note

If you are using only the default (en) locale, then you don't have to change anything.

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`

Note

The following section mostly applies to custom-built Faker instances.

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

Old method	New method
`faker.unique`	`faker.helpers.unique` (⚠️ please check #1785)
`faker.fake`	`faker.helpers.fake`
`faker.commerce.color`	`faker.color.human`
`faker.company.companyName`	`faker.company.name`
`faker.phone.phoneNumber`	`faker.phone.number`
`faker.phone.phoneNumberFormat`	No direct replacement, see documentation for `faker.phone.number`
`faker.phone.phoneFormats`	No direct replacement, see documentation for `faker.phone.number`
`faker.name.findName`	Removed, replace with `faker.person.fullName`
`faker.address.cityPrefix`	Removed
`faker.address.citySuffix`	Removed
`faker.address.streetPrefix`	Removed
`faker.address.streetSuffix`	Removed
`faker.image.lorempixel`	Removed, as the LoremPixel service is no longer available

Definitions removed

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

Removed data	Alternative
`faker.definitions.business.credit_card_numbers`	`faker.finance.creditCardNumber()`
`faker.definitions.business.credit_card_types`	`faker.finance.creditCardIssuer()`
`faker.definitions.business.credit_card_expiry_dates`	`faker.date.future()`

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.*

Old method	New method
`faker.name.firstName`	`faker.person.firstName`
`faker.name.lastName`	`faker.person.lastName`
`faker.name.middleName`	`faker.person.middleName`
`faker.name.fullName`	`faker.person.fullName`
`faker.name.gender`	`faker.person.gender`
`faker.name.sex`	`faker.person.sex`
`faker.name.sexType`	`faker.person.sexType`
`faker.name.prefix`	`faker.person.prefix`
`faker.name.suffix`	`faker.person.suffix`
`faker.name.jobTitle`	`faker.person.jobTitle`
`faker.name.jobDescriptor`	`faker.person.jobDescriptor`
`faker.name.jobArea`	`faker.person.jobArea`
`faker.name.jobType`	`faker.person.jobType`
`faker.name.findName`	Removed, replace with `faker.person.fullName`

`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.*

Old method	New method
`faker.address.buildingNumber`	`faker.location.buildingNumber`
`faker.address.cardinalDirection`	`faker.location.cardinalDirection`
`faker.address.city`	`faker.location.city`
`faker.address.cityName`	`faker.location.city`
`faker.address.country`	`faker.location.country`
`faker.address.countryCode`	`faker.location.countryCode`
`faker.address.county`	`faker.location.county`
`faker.address.direction`	`faker.location.direction`
`faker.address.faker`	`faker.location.faker`
`faker.address.latitude`	`faker.location.latitude`
`faker.address.longitude`	`faker.location.longitude`
`faker.address.nearbyGPSCoordinate`	`faker.location.nearbyGPSCoordinate`
`faker.address.ordinalDirection`	`faker.location.ordinalDirection`
`faker.address.secondaryAddress`	`faker.location.secondaryAddress`
`faker.address.state`	`faker.location.state`
`faker.address.stateAbbr`	`faker.location.stateAbbr`
`faker.address.street`	`faker.location.street`
`faker.address.streetAddress`	`faker.location.streetAddress`
`faker.address.streetName`	`faker.location.street`
`faker.address.timeZone`	`faker.location.timeZone`
`faker.address.zipCode`	`faker.location.zipCode`
`faker.address.zipCodeByState`	`faker.location.zipCodeByState`
`faker.address.cityPrefix`	Removed
`faker.address.citySuffix`	Removed
`faker.address.streetPrefix`	Removed
`faker.address.streetSuffix`	Removed

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

Old method	New method
`faker.datatype.number`	`faker.number.int` or `faker.number.float`
`faker.datatype.float`	`faker.number.float`
`faker.datatype.bigInt`	`faker.number.bigInt`

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.

Upgrading to v8 ​

Breaking changes ​

Removed ability to change the locale on existing Faker instances ​

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

faker.mersenne and faker.helpers.repeatString removed ​

faker.location.zipCodeByState ​

Methods will throw on empty data set inputs ​

Other deprecated methods removed/replaced ​

Definitions removed ​

Deprecations and other changes ​

faker.name changed to faker.person ​

faker.address changed to faker.location ​

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

Deprecation of faker.datatype.array ​

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

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

allowLeadingZeros behavior change in faker.string.numeric ​

Simplified MIME type data ​

faker.helpers.unique is planned to be outsourced ​

Locales renamed ​

Upgrading to v8

Breaking changes

Removed ability to change the locale on existing `Faker` instances

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

`faker.mersenne` and `faker.helpers.repeatString` removed

`faker.location.zipCodeByState`

Methods will throw on empty data set inputs

Other deprecated methods removed/replaced

Definitions removed

Deprecations and other changes

`faker.name` changed to `faker.person`

`faker.address` changed to `faker.location`

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

Deprecation of `faker.datatype.array`

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

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

`allowLeadingZeros` behavior change in `faker.string.numeric`

Simplified MIME type data

`faker.helpers.unique` is planned to be outsourced

Locales renamed