Merge branch 'next' into docs/api/default/prevent-line-breaks

Author: ST-DDT

.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": {},

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/usage.md

@@ -260,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

@@ -123,7 +123,7 @@
     "eslint-plugin-jsdoc": "50.4.3",
     "eslint-plugin-prettier": "5.2.1",
     "eslint-plugin-unicorn": "56.0.0",
-    "jiti": "1.21.6",
+    "jiti": "2.3.3",
     "npm-run-all2": "6.2.3",
     "prettier": "3.3.3",
     "prettier-plugin-organize-imports": "4.1.0",
@@ -143,7 +143,7 @@
     "vue": "3.5.12",
     "vue-tsc": "2.1.6"
   },
-  "packageManager": "[email protected].1",
+  "packageManager": "[email protected].2",
   "engines": {
     "node": ">=18.0.0",
     "npm": ">=9.0.0"