@edgefirst-dev/email

The Email class offers methods to validate, parse, and manipulate email addresses. It supports operations like retrieving the username, domain, and alias, and email validation using an external API via the EmailVerifier class.

Installation

bun add @edgefirst-dev/email
Copy

Usage

Import the Email class and create an instance using a valid email string or an Email object.

import { Email } from "@edgefirst-dev/email";

let email = Email.from("user@example.com");
console.log(email.toString()); // "user@example.com"
Copy

Email Parsing

You can retrieve and modify the username, domain (hostname), and alias from an email object.

let email = Email.from("user+alias@example.com");

console.log(email.username); // "user"
console.log(email.hostname); // "example.com"
console.log(email.alias); // "alias"

email.username = "newuser";
email.hostname = "newdomain.com";
email.alias = "newalias";

console.log(email.toString()); // "newuser+newalias@newdomain.com"
Copy

[!TIP] If you want to disallow users from using aliases in their email addresses, you can set the alias property to undefined.

let email = Email.from("user+alias@example.com)
email.alias = undefined;
console.log(email.toString()); // "user@example.com"
Copy

This can be useful to prevent users from creating multiple accounts using the same email address.

Email Verification

The EmailVerifier class validates an email through an external API.

import { Email } from "@edgefirst-dev/email";

let email = Email.from("user@example.com");

try {
  await email.verify();
  console.log("Email is valid");
} catch (error) {
  console.error("Invalid email:", error);
}
Copy

You can override this by extending the Email class and implementing your own verification logic.

class MyEmail extends Email {
  override verifier = {
    async verify(email: Email): Promise<void> {
      // Custom verification logic that throws if it's invalid
    },
  };
}

let myEmail = MyEmail.from("user@example.com");
await myEmail.verify(); // This will call your own verify function
Copy

Email Hashing

You can retrieve the SHA-256 hash of an email address.

console.log(email.hash); // SHA-256 hash of the email
Copy

This can be used along with Gravatar to get the user's avatar.

let email = Email.from("user@example.com");
let avatar = `https://www.gravatar.com/avatar/${email.hash}`;
Copy

Static Methods

The Email class provides static methods for validation and parsing:

Email.canParse("user@example.com"); // true
Email.canParse("invalid-email"); // false
Copy

This is similar to URL.canParse in the URL class.

Testing

You can test the EmailVerifier using msw to mock API responses.

import { http } from "msw";
import { setupServer } from "msw/node";
import { Email } from "@edgefirst-dev/email";

let server = setupServer(
  http.get(
    "https://verifier.meetchopra.com/verify/user@example.com",
    (req, res, ctx) => {
      return res(ctx.json({ status: true }));
    }
  )
);

server.listen();

let email = Email.from("user@example.com");
await email.verify(); // Mocked valid response
Copy

License

See LICENSE

Author

• Sergio Xalambrí