@mikkelscheike/email-provider-links
Version:
TypeScript library for email provider detection with 93 providers (207 domains), concurrent DNS resolution, optimized performance, 94.65% test coverage, and enterprise security for login and password reset flows
373 lines • 12.5 kB
JavaScript
;
/**
* Email Provider Links
*
* A modern, robust email provider detection library with:
* - 93+ verified email providers covering 180+ domains
* - Concurrent DNS detection for business domains
* - Zero runtime dependencies
* - Comprehensive error handling with detailed context
* - International email validation (IDN support)
* - Email alias normalization and deduplication
* - Enterprise-grade security features
*
* @author Email Provider Links Team
* @license MIT
* @version 2.7.0
*/
Object.defineProperty(exports, "__esModule", { value: true });
exports.VERSION = exports.DOMAIN_COUNT = exports.PROVIDER_COUNT = exports.isValidEmailAddress = exports.domainToPunycode = exports.emailToPunycode = exports.validateInternationalEmail = exports.detectProviderConcurrent = exports.loadProviders = exports.Config = exports.emailsMatch = exports.normalizeEmail = exports.getEmailProviderFast = exports.getEmailProviderSync = exports.getEmailProvider = void 0;
exports.validateEmailAddress = validateEmailAddress;
exports.getSupportedProviders = getSupportedProviders;
exports.isEmailProviderSupported = isEmailProviderSupported;
exports.extractDomain = extractDomain;
exports.isValidEmail = isValidEmail;
exports.getLibraryStats = getLibraryStats;
exports.batchProcessEmails = batchProcessEmails;
// ===== PRIMARY API =====
// Core functions that 95% of users need
var api_1 = require("./api");
Object.defineProperty(exports, "getEmailProvider", { enumerable: true, get: function () { return api_1.getEmailProvider; } });
Object.defineProperty(exports, "getEmailProviderSync", { enumerable: true, get: function () { return api_1.getEmailProviderSync; } });
Object.defineProperty(exports, "getEmailProviderFast", { enumerable: true, get: function () { return api_1.getEmailProviderFast; } });
Object.defineProperty(exports, "normalizeEmail", { enumerable: true, get: function () { return api_1.normalizeEmail; } });
Object.defineProperty(exports, "emailsMatch", { enumerable: true, get: function () { return api_1.emailsMatch; } });
Object.defineProperty(exports, "Config", { enumerable: true, get: function () { return api_1.Config; } });
// ===== ADVANCED FEATURES =====
// For power users and custom implementations
var loader_1 = require("./loader");
Object.defineProperty(exports, "loadProviders", { enumerable: true, get: function () { return loader_1.loadProviders; } });
var concurrent_dns_1 = require("./concurrent-dns");
Object.defineProperty(exports, "detectProviderConcurrent", { enumerable: true, get: function () { return concurrent_dns_1.detectProviderConcurrent; } });
var idn_1 = require("./idn");
Object.defineProperty(exports, "validateInternationalEmail", { enumerable: true, get: function () { return idn_1.validateInternationalEmail; } });
Object.defineProperty(exports, "emailToPunycode", { enumerable: true, get: function () { return idn_1.emailToPunycode; } });
Object.defineProperty(exports, "domainToPunycode", { enumerable: true, get: function () { return idn_1.domainToPunycode; } });
// ===== EMAIL VALIDATION =====
// Enhanced validation with international support
/**
* Enhanced email validation with comprehensive error reporting
*
* @param email - Email address to validate
* @returns Validation result with detailed error information
*
* @example
* ```typescript
* const result = validateEmailAddress('user@example.com');
* if (result.isValid) {
* console.log('Email is valid');
* } else {
* console.log('Error:', result.error.message);
* }
* ```
*/
function validateEmailAddress(email) {
// Input validation
if (!email || typeof email !== 'string') {
return {
isValid: false,
error: {
type: 'INVALID_INPUT',
code: 'MISSING_EMAIL',
message: 'Email address is required and must be a string'
}
};
}
// Trim whitespace
const trimmedEmail = email.trim();
if (trimmedEmail.length === 0) {
return {
isValid: false,
error: {
type: 'INVALID_INPUT',
code: 'EMPTY_EMAIL',
message: 'Email address cannot be empty'
}
};
}
// Use international validation
const idnError = (0, idn_2.validateInternationalEmail)(trimmedEmail);
if (idnError) {
return {
isValid: false,
error: {
type: idnError.type,
code: idnError.code,
message: idnError.message
}
};
}
return {
isValid: true,
normalizedEmail: trimmedEmail.toLowerCase()
};
}
// ===== UTILITY FUNCTIONS =====
// Helper functions for common tasks
const loader_2 = require("./loader");
const api_2 = require("./api");
const concurrent_dns_2 = require("./concurrent-dns");
const idn_2 = require("./idn");
/**
* Get comprehensive list of all supported email providers
*
* @returns Array of all email providers with metadata
*
* @example
* ```typescript
* const providers = getSupportedProviders();
* console.log(`Supports ${providers.length} providers`);
*
* const gmailProvider = providers.find(p => p.domains.includes('gmail.com'));
* console.log(gmailProvider?.companyProvider); // "Gmail"
* ```
*/
function getSupportedProviders() {
try {
const { providers } = (0, loader_2.loadProviders)();
return [...providers]; // Return defensive copy to prevent external mutations
}
catch (error) {
console.warn('Failed to load providers:', error);
return [];
}
}
/**
* Check if an email provider is supported (synchronous)
*
* @param email - Email address to check
* @returns true if the provider is supported
*
* @example
* ```typescript
* if (isEmailProviderSupported('user@gmail.com')) {
* console.log('Gmail is supported');
* }
* ```
*/
function isEmailProviderSupported(email) {
try {
if (!email || typeof email !== 'string') {
return false;
}
const result = (0, api_2.getEmailProviderSync)(email);
return result.provider !== null;
}
catch {
return false;
}
}
/**
* Extract and normalize domain from email address
*
* @param email - Email address
* @returns Normalized domain portion or null if invalid
*
* @example
* ```typescript
* const domain = extractDomain('USER@GMAIL.COM');
* console.log(domain); // "gmail.com"
*
* const invalid = extractDomain('invalid-email');
* console.log(invalid); // null
* ```
*/
function extractDomain(email) {
try {
if (!email || typeof email !== 'string') {
return null;
}
const validation = validateEmailAddress(email);
if (!validation.isValid || !validation.normalizedEmail) {
return null;
}
const parts = validation.normalizedEmail.split('@');
return parts[1] || null;
}
catch {
return null;
}
}
/**
* Validate email format using enhanced rules
*
* @param email - Email address to validate
* @returns true if valid format
*
* @example
* ```typescript
* if (isValidEmail('user@example.com')) {
* console.log('Email format is valid');
* }
*
* if (isValidEmail('user@münchen.de')) {
* console.log('International domain is valid');
* }
* ```
*/
function isValidEmail(email) {
const validation = validateEmailAddress(email);
return validation.isValid;
}
/**
* Get library metadata and statistics
*
* @returns Object with current library statistics
*
* @example
* ```typescript
* const stats = getLibraryStats();
* console.log(`Supports ${stats.providerCount} providers across ${stats.domainCount} domains`);
* ```
*/
function getLibraryStats() {
try {
const providers = getSupportedProviders();
const domainCount = providers.reduce((total, provider) => total + (provider.domains?.length || 0), 0);
return {
providerCount: providers.length,
domainCount,
version: '2.7.0',
supportsAsync: true,
supportsIDN: true,
supportsAliasDetection: true,
supportsConcurrentDNS: true
};
}
catch {
return {
providerCount: 0,
domainCount: 0,
version: '2.7.0',
supportsAsync: true,
supportsIDN: true,
supportsAliasDetection: true,
supportsConcurrentDNS: true
};
}
}
/**
* Batch process multiple email addresses efficiently
*
* @param emails - Array of email addresses to process
* @param options - Processing options
* @returns Array of results in the same order as input
*
* @example
* ```typescript
* const emails = ['user@gmail.com', 'test@yahoo.com', 'invalid-email'];
* const results = batchProcessEmails(emails);
*
* results.forEach((result, index) => {
* console.log(`${emails[index]}: ${result.isValid ? 'Valid' : 'Invalid'}`);
* });
* ```
*/
function batchProcessEmails(emails, options = {}) {
const { includeProviderInfo = false, normalizeEmails = false, deduplicateAliases = false } = options;
const results = [];
const seenNormalized = new Set();
for (const email of emails) {
try {
const validation = validateEmailAddress(email);
const result = {
email,
isValid: validation.isValid
};
if (!validation.isValid) {
result.error = validation.error?.message;
results.push(result);
continue;
}
// Add normalized email if requested
if (normalizeEmails && validation.normalizedEmail) {
try {
result.normalized = (0, api_2.normalizeEmail)(validation.normalizedEmail);
}
catch {
result.normalized = validation.normalizedEmail;
}
}
// Check for duplicates if requested
if (deduplicateAliases && result.normalized) {
if (seenNormalized.has(result.normalized)) {
result.isDuplicate = true;
}
else {
seenNormalized.add(result.normalized);
}
}
// Add provider info if requested
if (includeProviderInfo && validation.normalizedEmail) {
try {
const providerResult = (0, api_2.getEmailProviderSync)(validation.normalizedEmail);
result.provider = providerResult.provider?.companyProvider || null;
result.loginUrl = providerResult.loginUrl;
}
catch {
result.provider = null;
}
}
results.push(result);
}
catch (error) {
results.push({
email,
isValid: false,
error: error instanceof Error ? error.message : 'Unknown error'
});
}
}
return results;
}
// ===== LEGACY COMPATIBILITY =====
// Maintain backward compatibility
/**
* @deprecated Use validateEmailAddress instead for better error handling
*/
exports.isValidEmailAddress = isValidEmail;
/**
* Library metadata (legacy constants)
*/
exports.PROVIDER_COUNT = 93;
exports.DOMAIN_COUNT = 178;
/**
* Default export for convenience
*
* @example
* ```typescript
* import EmailProviderLinks from '@mikkelscheike/email-provider-links';
*
* const result = await EmailProviderLinks.getEmailProvider('user@gmail.com');
* ```
*/
exports.default = {
// Core functions
getEmailProvider: api_2.getEmailProvider,
getEmailProviderSync: api_2.getEmailProviderSync,
getEmailProviderFast: api_2.getEmailProviderFast,
// Validation
validateEmailAddress,
isValidEmail,
normalizeEmail: api_2.normalizeEmail,
emailsMatch: api_2.emailsMatch,
// Utilities
getSupportedProviders,
isEmailProviderSupported,
extractDomain,
getLibraryStats,
batchProcessEmails,
// Advanced
loadProviders: loader_2.loadProviders,
detectProviderConcurrent: concurrent_dns_2.detectProviderConcurrent,
validateInternationalEmail: idn_2.validateInternationalEmail,
// Constants
Config: api_2.Config,
PROVIDER_COUNT: exports.PROVIDER_COUNT,
DOMAIN_COUNT: exports.DOMAIN_COUNT
};
/**
* Version information
*/
exports.VERSION = '2.7.0';
//# sourceMappingURL=index.js.map