Merge branch 'next' into feat/more-locale-metadata

faker-js · Apr 22, 2023 · 1cfdee2 · 1cfdee2
2 parents d4123b0 + ed19bef
commit 1cfdee2
Show file tree

Hide file tree

Showing 388 changed files with 3,362 additions and 3,933 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -36,11 +36,16 @@ jobs:
           # Required for docs/versions tests
           fetch-depth: 0
 
-      - name: Install pnpm
+      - name: Install pnpm (node 14, pnpm 7)
+        if: matrix.node_version == 14
         uses: pnpm/[email protected]
         with:
           version: 7
 
+      - name: Install pnpm
+        if: matrix.node_version != 14
+        uses: pnpm/[email protected]
+
       - name: Set node version to ${{ matrix.node_version }}
         uses: actions/setup-node@v3
         with:
@@ -255,7 +260,7 @@ jobs:
         run: pnpm vitest run --coverage
 
       - name: Upload coverage to Codecov
-        uses: codecov/[email protected].1
+        uses: codecov/[email protected].2
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           fail_ci_if_error: true
diff --git a/docs/.vitepress/components/api-docs/method.ts b/docs/.vitepress/components/api-docs/method.ts
@@ -8,6 +8,7 @@ export interface Method {
   readonly since: string;
   readonly sourcePath: string; // URL-Suffix
   readonly seeAlsos: string[];
+  readonly throws?: string; // HTML
 }
 
 export interface MethodParameter {

diff --git a/docs/.vitepress/components/api-docs/method.vue b/docs/.vitepress/components/api-docs/method.vue
@@ -36,6 +36,10 @@ function seeAlsoToUrl(see: string): string {
 
     <p><strong>Returns:</strong> {{ props.method.returns }}</p>
 
+    <p v-if="props.method.throws">
+      <strong>Throws:</strong> <span v-html="props.method.throws" />
+    </p>
+
     <div v-html="props.method.examples" />
 
     <div v-if="props.method.seeAlsos.length > 0">

diff --git a/docs/api/ApiIndex.vue b/docs/api/ApiIndex.vue
@@ -60,7 +60,7 @@ function apiSearchFocusHandler(event: KeyboardEvent): void {
     if (!item) return;
     const header = item.headers[0];
     if (!header) return;
-    window.location.href = item.link + '.html#' + slugify(header.anchor);
+    window.location.href = item.link + '#' + slugify(header.anchor);
   } else if (
     /^[a-z]$/.test(event.key) &&
     !event.altKey &&
@@ -101,7 +101,11 @@ onUnmounted(() => window.removeEventListener('keydown', apiSearchFocusHandler));
           </h3>
           <ul>
             <li v-for="h of item.headers" :key="h.anchor">
-              <a :href="item.link + '#' + slugify(h.anchor)">{{ h.text }}</a>
+              <a
+                :href="item.link + '#' + slugify(h.anchor)"
+                :class="{ deprecated: h.deprecated }"
+                >{{ h.text }}</a
+              >
             </li>
           </ul>
         </div>
@@ -166,6 +170,10 @@ h3 {
   transition: color 0.5s;
 }
 
+.api-groups ul a.deprecated {
+  text-decoration: line-through;
+}
+
 .dark .api-groups ul a {
   font-weight: 400;
 }

diff --git a/docs/api/api-types.ts b/docs/api/api-types.ts
@@ -6,6 +6,7 @@
 export interface APIHeader {
   anchor: string;
   text: string;
+  deprecated: boolean;
 }
 
 /**

diff --git a/docs/guide/localization.md b/docs/guide/localization.md
@@ -144,3 +144,34 @@ The `Locale` (data) and `Faker` columns refer to the respective `import` names:
 ```ts
 import { de, fakerDE } from '@faker-js/faker';
 ```
+
+## Locale codes
+
+Locales are named in a systematic way. The first two characters are a lowercase language code following the [ISO 639-1 standard](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for example `ar` for Arabic or `en` for English.
+
+The same language may be spoken in different countries, with different patterns for addresses, phone numbers etc. Optionally a two-letter uppercase country code can be added after an underscore, following the [ISO 3166-1 alpha-2 standard](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2), for example `en_US` represents English (United States) and `en_AU` represents English (Australia).
+
+Rarely, an additional variant may be needed to fully represent an accented variant of the locale, or for languages which can be written in different scripts. This is appended after another underscore, for example `en_AU_ocker` (English in Australia in "Ocker" dialect) or `sr_RS_latin` (Serbian in Serbia in Latin script).
+
+The recommended way to access Faker instances is by using one of the individual imports as shown above. If needed you can access all prebuilt Faker instances or all locale definitions via an object where the locale codes are the keys:
+
+```ts
+import { allFakers, allLocales } from '@faker-js/faker';
+console.dir(allFakers['de_AT']); // the prebuilt Faker instance for de_AT
+console.dir(allLocales['de_AT']); // the raw locale definitions for de_AT
+```
+
+This could be useful if you want to enumerate all locales, for example:
+
+```ts
+import { allFakers } from '@faker-js/faker';
+for (let key of Object.keys(allFakers)) {
+  try {
+    console.log(
+      `In locale ${key}, a sample name is ${allFakers[key].person.fullName()}`
+    );
+  } catch (e) {
+    console.log(`In locale ${key}, an error occurred: ${e}`);
+  }
+}
+```
diff --git a/docs/guide/upgrading.md b/docs/guide/upgrading.md
@@ -101,6 +101,54 @@ For more information refer to our [Localization Guide](localization).
 
 `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                                                                                                      |
@@ -119,6 +167,16 @@ For more information refer to our [Localization Guide](localization).
 | `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
 
 ### `faker.name` changed to `faker.person`
@@ -153,7 +211,7 @@ The `faker.address.*` methods will continue to work as an alias in v8 and v9, bu
 | `faker.address.buildingNumber`      | `faker.location.buildingNumber`      |
 | `faker.address.cardinalDirection`   | `faker.location.cardinalDirection`   |
 | `faker.address.city`                | `faker.location.city`                |
-| `faker.address.cityName`            | `faker.location.cityName`            |
+| `faker.address.cityName`            | `faker.location.city`                |
 | `faker.address.country`             | `faker.location.country`             |
 | `faker.address.countryCode`         | `faker.location.countryCode`         |
 | `faker.address.county`              | `faker.location.county`              |
@@ -168,7 +226,7 @@ The `faker.address.*` methods will continue to work as an alias in v8 and v9, bu
 | `faker.address.stateAbbr`           | `faker.location.stateAbbr`           |
 | `faker.address.street`              | `faker.location.street`              |
 | `faker.address.streetAddress`       | `faker.location.streetAddress`       |
-| `faker.address.streetName`          | `faker.location.streetName`          |
+| `faker.address.streetName`          | `faker.location.street`              |
 | `faker.address.timeZone`            | `faker.location.timeZone`            |
 | `faker.address.zipCode`             | `faker.location.zipCode`             |
 | `faker.address.zipCodeByState`      | `faker.location.zipCodeByState`      |
@@ -177,6 +235,14 @@ The `faker.address.*` methods will continue to work as an alias in v8 and v9, bu
 | `faker.address.streetPrefix`        | _Removed_                            |
 | `faker.address.streetSuffix`        | _Removed_                            |
 
+### `faker.finance.account` changed to `faker.finance.accountNumber`
+
+The `faker.finance.account` method has been renamed to `faker.finance.accountNumber` to better reflect the data it returns and not to get confused with a user "Account".
+
+### `faker.finance.mask` changed to `faker.finance.maskedNumber`
+
+The `faker.finance.mask` method has been renamed to `faker.finance.maskedNumber` to better reflect its purpose.
+
 ### 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.

diff --git a/package.json b/package.json
@@ -20,6 +20,13 @@
     "type": "git",
     "url": "https://github.com/faker-js/faker.git"
   },
+  "funding": [
+    {
+      "type": "opencollective",
+      "url": "https://opencollective.com/fakerjs"
+    }
+  ],
+  "bugs": "https://github.com/faker-js/faker/issues",
   "license": "MIT",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.mjs",
@@ -91,48 +98,47 @@
     "@types/markdown-it": "~12.2.3",
     "@types/node": "~18.15.11",
     "@types/prettier": "~2.7.2",
-    "@types/react": "~18.0.32",
+    "@types/react": "~18.0.35",
     "@types/sanitize-html": "~2.9.0",
     "@types/semver": "~7.3.13",
-    "@types/validator": "~13.7.14",
-    "@typescript-eslint/eslint-plugin": "~5.57.1",
-    "@typescript-eslint/parser": "~5.57.1",
-    "@vitest/coverage-c8": "~0.29.8",
-    "@vitest/ui": "~0.29.8",
-    "@vueuse/core": "~9.13.0",
+    "@types/validator": "~13.7.15",
+    "@typescript-eslint/eslint-plugin": "~5.58.0",
+    "@typescript-eslint/parser": "~5.58.0",
+    "@vitest/coverage-c8": "~0.30.1",
+    "@vitest/ui": "~0.30.1",
+    "@vueuse/core": "~10.0.2",
     "c8": "~7.13.0",
     "conventional-changelog-cli": "~2.2.2",
     "cypress": "~12.9.0",
-    "esbuild": "~0.17.15",
-    "eslint": "~8.37.0",
+    "esbuild": "~0.17.17",
+    "eslint": "~8.38.0",
     "eslint-config-prettier": "~8.8.0",
-    "eslint-define-config": "~1.17.0",
+    "eslint-define-config": "~1.18.0",
     "eslint-gitignore": "~0.1.0",
-    "eslint-plugin-deprecation": "~1.4.0",
-    "eslint-plugin-jsdoc": "~40.1.1",
+    "eslint-plugin-deprecation": "~1.4.1",
+    "eslint-plugin-jsdoc": "~41.1.2",
     "eslint-plugin-prettier": "~4.2.1",
-    "glob": "~9.3.4",
+    "glob": "~10.1.0",
     "npm-run-all": "~4.1.5",
     "picocolors": "~1.0.0",
     "prettier": "2.8.7",
     "prettier-plugin-organize-imports": "~3.2.2",
     "react": "~18.2.0",
     "react-dom": "~18.2.0",
-    "rimraf": "~4.4.1",
+    "rimraf": "~5.0.0",
     "sanitize-html": "~2.10.0",
-    "semver": "~7.3.8",
+    "semver": "~7.4.0",
     "standard-version": "~9.5.0",
     "tsx": "~3.12.6",
-    "typedoc": "~0.23.28",
-    "typedoc-plugin-missing-exports": "~1.0.0",
+    "typedoc": "~0.24.4",
     "typescript": "~4.9.5",
     "validator": "~13.9.0",
     "vite": "~4.2.1",
-    "vitepress": "1.0.0-alpha.64",
-    "vitest": "~0.29.8",
+    "vitepress": "1.0.0-alpha.72",
+    "vitest": "~0.30.1",
     "vue": "~3.2.47"
   },
-  "packageManager": "pnpm@7.30.5",
+  "packageManager": "pnpm@8.2.0",
   "engines": {
     "node": "^14.17.0 || ^16.13.0 || >=18.0.0",
     "npm": ">=6.14.13"