feat: special characters in emails (#792)

1 files changed, 31 insertions, 9 deletions

diff --git a/src/internet.ts b/src/internet.ts
index 7615607f..08ac2e91 100644
--- a/src/internet.ts
+++ b/src/internet.ts
@@ -34,25 +34,39 @@ export class Internet {
    * @param firstName The optional first name to use. If not specified, a random one will be chosen.
    * @param lastName The optional last name to use. If not specified, a random one will be chosen.
    * @param provider The mail provider domain to use. If not specified, a random free mail provider will be chosen.
+   * @param options The options to use. Defaults to `{ allowSpecialCharacters: false }`.
+   * @param options.allowSpecialCharacters Whether special characters such as `.!#$%&'*+-/=?^_`{|}~` should be included
+   * in the email address. Defaults to `false`.
    *
    * @example
    * faker.internet.email() // '[email protected]'
    * faker.internet.email('Jeanne', 'Doe') // '[email protected]'
    * faker.internet.email('Jeanne', 'Doe', 'example.fakerjs.dev') // '[email protected]'
+   * faker.internet.email('Jeanne', 'Doe', 'example.fakerjs.dev', { allowSpecialCharacters: true }) // 'Jeanne%[email protected]'
    */
-  email(firstName?: string, lastName?: string, provider?: string): string {
+  email(
+    firstName?: string,
+    lastName?: string,
+    provider?: string,
+    options?: { allowSpecialCharacters?: boolean }
+  ): string {
     provider =
       provider ||
       this.faker.random.arrayElement(
         this.faker.definitions.internet.free_email
       );
-    return (
-      this.faker.helpers.slugify(
-        this.faker.internet.userName(firstName, lastName)
-      ) +
-      '@' +
-      provider
+    let localPart: string = this.faker.helpers.slugify(
+      this.faker.internet.userName(firstName, lastName)
     );
+    if (options?.allowSpecialCharacters) {
+      const usernameChars: string[] = '._-'.split('');
+      const specialChars: string[] = ".!#$%&'*+-/=?^_`{|}~".split('');
+      localPart = localPart.replace(
+        this.faker.random.arrayElement(usernameChars),
+        this.faker.random.arrayElement(specialChars)
+      );
+    }
+    return `${localPart}@${provider}`;
   }
 
   /**
@@ -60,16 +74,24 @@ export class Internet {
    *
    * @param firstName The optional first name to use. If not specified, a random one will be chosen.
    * @param lastName The optional last name to use. If not specified, a random one will be chosen.
+   * @param options The options to use. Defaults to `{ allowSpecialCharacters: false }`.
+   * @param options.allowSpecialCharacters Whether special characters such as `.!#$%&'*+-/=?^_`{|}~` should be included
+   * in the email address. Defaults to `false`.
    *
    * @example
    * faker.internet.exampleEmail() // '[email protected]'
    * faker.internet.exampleEmail('Jeanne', 'Doe') // '[email protected]'
+   * faker.internet.exampleEmail('Jeanne', 'Doe', { allowSpecialCharacters: true }) // 'Jeanne%[email protected]'
    */
-  exampleEmail(firstName?: string, lastName?: string): string {
+  exampleEmail(
+    firstName?: string,
+    lastName?: string,
+    options?: { allowSpecialCharacters?: boolean }
+  ): string {
     const provider = this.faker.random.arrayElement(
       this.faker.definitions.internet.example_email
     );
-    return this.email(firstName, lastName, provider);
+    return this.email(firstName, lastName, provider, options);
   }
 
   /**