feat: special characters in emails (#792)

2 files changed, 62 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);
   }
 
   /**
diff --git a/test/internet.spec.ts b/test/internet.spec.ts
index b7d9a7ea..fa9ad963 100644
--- a/test/internet.spec.ts
+++ b/test/internet.spec.ts
@@ -191,6 +191,21 @@ describe('internet', () => {
           expect(prefix).match(/^思源_唐3/);
           expect(faker.definitions.internet.free_email).toContain(suffix);
         });
+
+        it('should return an email with special characters', () => {
+          const email = faker.internet.email('Mike', 'Smith', null, {
+            allowSpecialCharacters: true,
+          });
+
+          expect(email).toBeTruthy();
+          expect(email).toBeTypeOf('string');
+          expect(email).satisfy(validator.isEmail);
+
+          const [prefix, suffix] = email.split('@');
+
+          expect(prefix).match(/^Mike([.!#$%&'*+-/=?^_`{|}~]Smith)?\d*/);
+          expect(faker.definitions.internet.free_email).toContain(suffix);
+        });
       });
 
       describe('exampleEmail()', () => {
@@ -248,6 +263,22 @@ describe('internet', () => {
           expect(faker.definitions.internet.example_email).toContain(suffix);
           expect(prefix).match(/^思源_唐3/);
         });
+
+        it('should return an email with special characters', () => {
+          const email = faker.internet.exampleEmail('Mike', 'Smith', {
+            allowSpecialCharacters: true,
+          });
+
+          expect(email).toBeTruthy();
+          expect(email).toBeTypeOf('string');
+          expect(email).satisfy(validator.isEmail);
+
+          const [prefix, suffix] = email.split('@');
+
+          expect(suffix).match(/^example\.(com|net|org)$/);
+          expect(faker.definitions.internet.example_email).toContain(suffix);
+          expect(prefix).match(/^Mike([.!#$%&'*+-/=?^_`{|}~]Smith)?\d*/);
+        });
       });
 
       describe('userName()', () => {