From c96176b359c98c60f3519579dc6fff855e4c3c20 Mon Sep 17 00:00:00 2001 From: Matt Mayer <152770+matthewmayer@users.noreply.github.com> Date: Wed, 14 Feb 2024 15:29:39 +0700 Subject: [PATCH] docs: create stub for v9 migration guide (#2665) --- docs/.vitepress/config.ts | 2 +- docs/guide/upgrading.md | 345 +------------------------------------- 2 files changed, 5 insertions(+), 342 deletions(-) diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index eaf99abd5c0..17d7d84d74c 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -214,7 +214,7 @@ const config: UserConfig = { link: '/guide/randomizer', }, { - text: 'Upgrading to v8', + text: 'Upgrading to v9', link: '/guide/upgrading', }, ], diff --git a/docs/guide/upgrading.md b/docs/guide/upgrading.md index 85b75268cca..ae3edaa5b7a 100644 --- a/docs/guide/upgrading.md +++ b/docs/guide/upgrading.md @@ -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.