-
-
Notifications
You must be signed in to change notification settings - Fork 902
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: create stub for v9 migration guide (#2665)
- Loading branch information
1 parent
f6e6c72
commit c96176b
Showing
2 changed files
with
5 additions
and
342 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,350 +1,13 @@ | ||
| # Upgrading to v8 | ||
| # Upgrading to v9 | ||
|
|
||
| This is the migration guide for upgrading from v7 to v8. | ||
| This is the migration guide for upgrading from v8 to v9. | ||
|
|
||
| ::: info Not the version you are looking for? | ||
|
|
||
| - [Upgrading to v8](https://v8.fakerjs.dev/guide/upgrading.html) | ||
| - [Upgrading to v7](https://v7.fakerjs.dev/guide/upgrading.html) | ||
| - [Upgrading to v6](https://v6.fakerjs.dev/migration-guide-v5/) | ||
|
|
||
| ::: | ||
|
|
||
| ## Breaking changes | ||
|
|
||
| ### Removed ability to change the locale on existing `Faker` instances | ||
|
|
||
| ::: tip 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** | ||
|
|
||
| ```ts | ||
| import { faker } from '@faker-js/faker'; | ||
|
|
||
| faker.setLocale('de_CH'); | ||
| // or | ||
| faker.locale = 'de_CH'; | ||
| faker.localeFallback = 'en'; | ||
| ``` | ||
|
|
||
| **New** | ||
|
|
||
| ```ts | ||
| import { fakerDE_CH as faker } from '@faker-js/faker'; | ||
| ``` | ||
|
|
||
| This also fixes issues where more than two locales are required: | ||
|
|
||
| **Old** | ||
|
|
||
| ```ts | ||
| 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** | ||
|
|
||
| ```ts | ||
| 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** | ||
|
|
||
| ```ts | ||
| 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** | ||
|
|
||
| ```ts | ||
| 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](localization). | ||
|
|
||
| ### For missing locale data, Faker will now throw instead of returning `undefined` or `a`-`c` | ||
|
|
||
| ::: info 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. | ||
|
|
||
| ```ts | ||
| 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. | ||
|
|
||
| ```ts | ||
| 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** | ||
|
|
||
| ```ts | ||
| 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** | ||
|
|
||
| ```ts | ||
| 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` (:warning: please check [#1785](https://github.com/faker-js/faker/issues/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](https://www.npmjs.com/package/eslint-plugin-deprecation) to find usages of deprecated code | ||
| - Review the full list of deprecations [here](https://github.com/faker-js/faker/issues?q=label%3Adeprecation+is%3Amerged+milestone%3A%22v8.0+-+Module+Re-Shuffling%22) and [here](https://github.com/faker-js/faker/issues?q=label%3Adeprecation+is%3Amerged+milestone%3A%22v8+-+None+milestone+specific+tasks%22) | ||
| - 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 | ||
|
|
||
| ```js | ||
| // 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`. | ||
|
|
||
| ```js | ||
| 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. | ||
|
|
||
| ```js | ||
| 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](https://github.com/faker-js/faker/issues/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. | ||
| v9 has not yet been released. This page will contain a work-in-progress list of breaking changes in v9. |