Email Validator

The Email Validator module provides a robust set of tools for handling email addresses, ensuring they follow standard formats while providing features for privacy and identification.

Overview

Working with email addresses requires balancing strict validation with the flexibility of real-world usage. This module follows common RFC standards while providing specific Indonesian-centric utilities.

Key Features

Standard Compliance: Validates emails against standard RFC patterns, including special characters and long TLDs.
Privacy First: Built-in masking utilities to hide sensitive information in logs or UI.
Security: Optional blocking for known disposable/temporary email providers to prevent spam.
Identification: Easily detect if an email belongs to a common provider (Gmail, Yahoo, etc.) or is a potential temporary address.

Installation

npm


npm install @indodev/toolkit

pnpm


pnpm add @indodev/toolkit

yarn


yarn add @indodev/toolkit

bun


bun add @indodev/toolkit

Quick Start


import { validateEmail, maskEmail, getEmailInfo } from '@indodev/toolkit/email-validator';
 
// Standard validation
validateEmail('halo@indodev.id'); // true
 
// Security: Block disposable emails
validateEmail('spam@mailinator.com', { blockDisposable: true }); // false
 
// Privacy: Masking for logs/UI
maskEmail('choirul@adamm.cloud'); // 'c*****l@adamm.cloud'
 
// Identification: Extract info
const info = getEmailInfo('adam@gmail.com');
// info.isCommonProvider => true

API Reference

validateEmail()

Validates if a string is a properly formatted email address.

Type Signature:


function validateEmail(email: string, options?: EmailValidationOptions): boolean;

Parameters:

Name	Type	Description
`email`	`string`	The email address to validate.
`options`	`EmailValidationOptions`	Optional configuration settings.

Options:

Property	Type	Default	Description
`blockDisposable`	`boolean`	`false`	If true, blocks common disposable email domains.

The validation follows a standard regex that supports most common email patterns including subdomains and special characters allowed by RFC 5322.

maskEmail()

Masks the username portion of an email for privacy protection.

Type Signature:


function maskEmail(email: string, options?: EmailMaskOptions): string;

Parameters:

Name	Type	Description
`email`	`string`	The email address to mask.
`options`	`EmailMaskOptions`	Custom masking configuration.

Options:

Property	Type	Default	Description
`visibleStart`	`number`	`1`	Characters to show at the start of the username.
`visibleEnd`	`number`	`1`	Characters to show at the end of the username.
`maskChar`	`string`	`'*'`	Character used for masking.

Example:


maskEmail('user@example.com', { visibleStart: 2, maskChar: '#' });
// 'us##r@example.com'

getEmailInfo()

Parses an email address to extract useful metadata.

Type Signature:


function getEmailInfo(email: string): EmailInfo | null;

Returns:

EmailInfo | null - An object containing email details, or null if the email is invalid.

Object Properties:

Property	Type	Description
`username`	`string`	The part before the @ symbol.
`domain`	`string`	The domain part after the @ symbol.
`isCommonProvider`	`boolean`	True if it’s a major provider (Gmail, Yahoo, etc).
`isDisposable`	`boolean`	True if it’s a known temporary email domain.

normalizeEmail()

Standardizes an email string for database storage or comparison.

Type Signature:


function normalizeEmail(email: string): string;

Behavior:

Trims leading and trailing whitespace.
Converts the entire string to lowercase.

Constants

EMAIL_REGEX

The regular expression used internally for validation.

DISPOSABLE_DOMAINS

A list of common disposable email domains that are blocked when blockDisposable is enabled.