Merge branch 'next' into feat/numberToRomanNumerals

.devcontainer/devcontainer.json

@@ -2,7 +2,7 @@
 // README at: https://github.com/devcontainers/templates/tree/main/src/typescript-node
 {
   "name": "FakerJs",
-  "image": "mcr.microsoft.com/devcontainers/typescript-node:22@sha256:79c4181532784148abe5d0dd37505f420674990fd104f8294fd06155003fa442",
+  "image": "mcr.microsoft.com/devcontainers/typescript-node:22@sha256:dc2c3654370fe92a55daeefe9d2d95839d85bdc1f68f7fd4ab86621f49e5818a",
 
   // Features to add to the dev container. More info: https://containers.dev/features.
   // "features": {},

.gitignore

@@ -20,6 +20,9 @@ lib-cov
 coverage
 *.lcov
 
+# Vitest Temp files
+tsconfig.vitest-temp.json
+
 # nyc test coverage
 .nyc_output
 

README.md

@@ -34,14 +34,14 @@ For detailed API documentation, please select the version of the documentation y
 
 ## 🚀 Features
 
-- 💌 Locations - Generate valid looking Addresses, Zip Codes, Street Names, States, and Countries!
-- ⏰ Time-based Data - Past, present, future, recent, soon... whenever!
-- 🌏 Localization - Pick a locale to generate realistic looking Names, Addresses, and Phone Numbers.
+- 🧍 Person - Generate Names, Genders, Bios, Job titles, and more.
+- 📍 Location - Generate Addresses, Zip Codes, Street Names, States, and Countries!
+- ⏰ Date - Past, present, future, recent, soon... whenever!
 - 💸 Finance - Create stubbed out Account Details, Transactions, and Crypto Addresses.
-- 👠 Products - Generate Prices, Product Names, Adjectives, and Descriptions.
-- 👾 Hacker Jargon - “Try to reboot the SQL bus, maybe it will bypass the virtual application!”
-- 🧍 Names - Generate virtual humans with a complete online and offline identity.
-- 🔢 Numbers - Of course, we can also generate random numbers and strings.
+- 👠 Commerce - Generate Prices, Product Names, Adjectives, and Descriptions.
+- 👾 Hacker - “Try to reboot the SQL bus, maybe it will bypass the virtual application!”
+- 🔢 Number and String - Of course, we can also generate random numbers and strings.
+- 🌏 Localization - Pick from over 60 locales to generate realistic looking Names, Addresses, and Phone Numbers.
 
 > **Note**: Faker tries to generate realistic data and not obvious fake data.
 > The generated names, addresses, emails, phone numbers, and/or other data might be coincidentally valid information.

docs/guide/index.md

@@ -37,6 +37,18 @@ yarn add @faker-js/faker --dev
 
 :::
 
+## Faker Modules
+
+Faker has three types of modules:
+
+- Modules for basic datatypes: [`datatype`](/api/datatype), [`date`](/api/date), [`number`](/api/number) and [`string`](/api/string)
+- Topic specific modules, such as [`animal`](/api/animal), [`food`](/api/food) and many more
+- Lastly, the [`helpers`](/api/datatype) module, with various utility methods to use with your own data (or data generated by other Faker methods)
+
+For a full list of modules, go to our [Api Search](/api/) page.
+
+If you would like to know how to use Faker, go to our [Usage Guide](/guide/usage) page.
+
 ## Community
 
 If you have questions or need help, reach out to the community via [Discord](https://chat.fakerjs.dev) and [GitHub Discussions](https://github.com/faker-js/faker/discussions).

docs/guide/usage.md

@@ -94,15 +94,17 @@ It is highly recommended to use version tags when importing libraries in Deno, e
 
 ## TypeScript Support
 
-Faker supports TypeScript out of the box, so you don't have to install any extra packages.
+We assume that you use TypeScript (strict mode).
+You can use Faker without it, but we don't have dedicated error messages for wrong parameter types.
 
 In order to have Faker working properly, you need to check if these `compilerOptions` are set correctly in your `tsconfig` file:
 
 ```json
 {
   "compilerOptions": {
     "esModuleInterop": true,
-    "moduleResolution": "Bundler" // "Node10", "Node16" or "NodeNext"
+    "moduleResolution": "Bundler", // "Node10", "Node16" or "NodeNext"
+    "strict": true // Optional, but recommended
   }
 }
 ```
@@ -258,4 +260,49 @@ This allows the value to be more reasonable based on the provided arguments.
 
 Unlike the `_id` property that uses an `uuid` implementation, which has a low chance of duplicates, the `email` function is more likely to produce duplicates, especially if the call arguments are similar. We have a dedicated guide page on generating [unique values](unique).
 
-Congratulations, you should now be able to create any complex object you desire. Happy faking 🥳.
+The example above demonstrates how to generate complex objects.
+To gain more control over the values of specific properties, you can introduce `overwrites`, `options` or similar parameters:
+
+```ts {3,17}
+import { faker } from '@faker-js/faker';
+
+function createRandomUser(overwrites: Partial<User> = {}): User {
+  const {
+    _id = faker.string.uuid(),
+    avatar = faker.image.avatar(),
+    birthday = faker.date.birthdate(),
+    sex = faker.person.sexType(),
+    firstName = faker.person.firstName(sex),
+    lastName = faker.person.lastName(),
+    email = faker.internet.email({ firstName, lastName }),
+    subscriptionTier = faker.helpers.arrayElement([
+      'free',
+      'basic',
+      'business',
+    ]),
+  } = overwrites;
+
+  return {
+    _id,
+    avatar,
+    birthday,
+    email,
+    firstName,
+    lastName,
+    sex,
+    subscriptionTier,
+  };
+}
+
+const user = createRandomUser();
+const userToReject = createRandomUser({ birthday: new Date('2124-10-20') });
+```
+
+A potential `options` parameter could be used to:
+
+- control which optional properties are included,
+- control how nested elements and arrays are merged or replaced,
+- or specify the number of items to generate for nested lists.
+
+Congratulations, you should now be able to create any complex object you desire.
+Happy faking 🥳.

docs/index.md

@@ -20,24 +20,24 @@ hero:
       link: https://github.com/faker-js/faker
 
 features:
-  - icon: 👠
-    title: Products
-    details: Generate Prices, Product Names, Adjectives, and Descriptions.
+  - icon: 🧍
+    title: Person
+    details: Generate Names, Genders, Bios, Job titles, and more.
+  - icon: 📍
+    title: Location
+    details: Generate Addresses, Zip Codes, Street Names, States, and Countries!
+  - icon: ⏰
+    title: Date
+    details: Past, present, future, recent, soon... whenever!
   - icon: 💸
     title: Finance
     details: Create stubbed out Account Details, Transactions, and Crypto Addresses.
-  - icon: 💌
-    title: Locations
-    details: Generate valid Addresses, Zip Codes, Street Names, States, and Countries!
-  - icon: 👾
-    title: Hacker Jargon
-    details: “Try to reboot the SQL bus, maybe it will bypass the virtual application!”
-  - icon: ⏰
-    title: Time-based Data
-    details: Past, present, future, recent, soon... whenever!
+  - icon: 👠
+    title: Commerce
+    details: Generate Prices, Product Names, Adjectives, and Descriptions.
   - icon: 🌏
     title: Localization
-    details: Pick a locale to generate realistic looking Names, Addresses, and Phone Numbers.
+    details: Pick from over 60 locales to generate realistic looking Names, Addresses, and Phone Numbers.
 ---
 
 <div class="opencollective">

package.json

@@ -104,27 +104,27 @@
   ],
   "devDependencies": {
     "@actions/github": "6.0.0",
-    "@eslint/compat": "1.2.0",
-    "@eslint/js": "9.12.0",
+    "@eslint/compat": "1.2.1",
+    "@eslint/js": "9.13.0",
     "@stylistic/eslint-plugin": "2.9.0",
     "@types/eslint__js": "8.42.3",
-    "@types/node": "20.16.11",
+    "@types/node": "20.16.15",
     "@types/sanitize-html": "2.13.0",
     "@types/semver": "7.5.8",
     "@types/validator": "13.12.2",
-    "@vitest/coverage-v8": "2.1.2",
+    "@vitest/coverage-v8": "2.1.3",
     "@vitest/eslint-plugin": "1.1.7",
-    "@vitest/ui": "2.1.2",
+    "@vitest/ui": "2.1.3",
     "@vueuse/core": "11.1.0",
     "commit-and-tag-version": "12.5.0",
     "cypress": "13.15.0",
-    "eslint": "9.12.0",
+    "eslint": "9.13.0",
     "eslint-config-prettier": "9.1.0",
     "eslint-plugin-jsdoc": "50.4.3",
     "eslint-plugin-prettier": "5.2.1",
     "eslint-plugin-unicorn": "56.0.0",
-    "jiti": "1.21.6",
-    "npm-run-all2": "6.2.3",
+    "jiti": "2.3.3",
+    "npm-run-all2": "6.2.6",
     "prettier": "3.3.3",
     "prettier-plugin-organize-imports": "4.1.0",
     "prettier-plugin-packagejson": "2.5.3",
@@ -135,15 +135,15 @@
     "tsup": "8.3.0",
     "tsx": "4.19.1",
     "typescript": "5.6.3",
-    "typescript-eslint": "8.10.0",
+    "typescript-eslint": "8.11.0",
     "validator": "13.12.0",
-    "vite": "5.4.8",
+    "vite": "5.4.10",
     "vitepress": "1.4.1",
-    "vitest": "2.1.2",
+    "vitest": "2.1.3",
     "vue": "3.5.12",
     "vue-tsc": "2.1.6"
   },
-  "packageManager": "pnpm@9.12.1",
+  "packageManager": "pnpm@9.12.2",
   "engines": {
     "node": ">=18.0.0",
     "npm": ">=9.0.0"