@gmana/email-checker
Version:
232 lines • 7.24 kB
TypeScript
//#region src/lib/types.d.ts
/**
* Configuration options for email validation
*/
interface EmailValidationOptions {
/** Allow international domain names (default: true) */
allowInternational?: boolean;
/** Allow subdomains (default: true) */
allowSubdomains?: boolean;
/** Custom disposable domains to include */
customDisposableDomains?: string[];
/** Domains to whitelist (override disposable check) */
whitelistedDomains?: string[];
/** Strict mode for more rigorous email validation (default: false) */
strictMode?: boolean;
}
/**
* Result of email validation with detailed information
*/
interface EmailValidationResult {
/** Whether the email is valid format */
isValid: boolean;
/** Whether the email uses a disposable domain */
isDisposable: boolean;
/** The extracted domain from the email */
domain: string | null;
/** Any validation errors encountered */
errors: string[];
/** Additional metadata about the validation */
metadata: {
/** Whether the domain is internationalized */
isInternational: boolean;
/** Whether the domain has subdomains */
hasSubdomains: boolean;
/** Whether the domain was whitelisted */
isWhitelisted: boolean;
};
}
/**
* Domain information structure
*/
interface DomainInfo {
/** The domain name */
domain: string;
/** Whether it's a known disposable domain */
isDisposable: boolean;
/** Whether it's whitelisted */
isWhitelisted: boolean;
/** Whether it's an international domain */
isInternational: boolean;
}
/**
* Email checker configuration
*/
interface EmailCheckerConfig extends EmailValidationOptions {
/** Whether to enable caching for domain lookups (default: true) */
enableCaching?: boolean;
/** Maximum cache size (default: 1000) */
maxCacheSize?: number;
}
//#endregion
//#region src/lib/is-disposable-email.d.ts
/**
* Updates the global configuration for email validation
*
* @param config - Partial configuration to merge with defaults
* @example
* ```typescript
* configureEmailChecker({
* strictMode: true,
* whitelistedDomains: ['company.com'],
* customDisposableDomains: ['suspicious-domain.com']
* });
* ```
*/
declare function configureEmailChecker(config: Partial<EmailCheckerConfig>): void;
/**
* Resets the global configuration to defaults
*/
declare function resetEmailCheckerConfig(): void;
/**
* Gets the current global configuration
*/
declare function getEmailCheckerConfig(): Required<EmailCheckerConfig>;
/**
* Simple check if an email address uses a disposable domain
*
* @param email - The email address to check
* @param options - Optional configuration overrides
* @returns true if the email uses a disposable domain, false otherwise
*
* @example
* ```typescript
* // Basic usage
* console.log(isDisposableEmail("user@10minutemail.com")); // true
* console.log(isDisposableEmail("user@gmail.com")); // false
*
* // With custom options
* console.log(isDisposableEmail("user@subdomain.company.com", {
* allowSubdomains: false
* })); // false (subdomain not allowed)
*
* // With whitelist
* console.log(isDisposableEmail("user@tempmail.com", {
* whitelistedDomains: ["tempi.com"]
* })); // false (whitelisted)
* ```
*/
declare function isDisposableEmail(email: string, options?: EmailValidationOptions): boolean;
/**
* Comprehensive email validation with detailed results
*
* @param email - The email address to validate
* @param options - Optional configuration overrides
* @returns Detailed validation result with metadata
*
* @example
* ```typescript
* const result = validateEmail("user@subdomain.tempmail.com");
* console.log(result);
* // {
* // isValid: true,
* // isDisposable: true,
* // domain: "subdomain.tempi.com",
* // errors: [],
* // metadata: {
* // isInternational: false,
* // hasSubdomains: true,
* // isWhitelisted: false
* // }
* // }
* ```
*/
declare function validateEmail(email: string, options?: EmailValidationOptions): EmailValidationResult;
/**
* Checks if a domain is in the built-in disposable domains list
*
* @param domain - The domain to check
* @returns true if the domain is in the disposable list
*
* @example
* ```typescript
* console.log(isDomainDisposable("10minutemail.com")); // true
* console.log(isDomainDisposable("gmail.com")); // false
* ```
*/
declare function isDomainDisposable(domain: string): boolean;
/**
* Gets the list of all built-in disposable domains
*
* @returns Array of disposable domain names
*/
declare function getDisposableDomains(): string[];
/**
* Gets information about a specific domain
*
* @param domain - The domain to analyze
* @param options - Optional configuration overrides
* @returns Domain information object
*/
declare function getDomainInfo(domain: string, options?: EmailValidationOptions): DomainInfo;
/**
* Clears the domain cache
*/
declare function clearCache(): void;
/**
* Gets cache statistics
*/
declare function getCacheStats(): {
size: number;
maxSize: number;
};
//#endregion
//#region src/lib/domain-utils.d.ts
/**
* Cache for domain lookups to improve performance
*/
declare class DomainCache {
private cache;
private maxSize;
constructor(maxSize?: number);
get(domain: string): DomainInfo | undefined;
set(domain: string, info: DomainInfo): void;
clear(): void;
size(): number;
}
/**
* Global domain cache instance
*/
declare const domainCache: DomainCache;
/**
* Validates email format
*/
declare function isValidEmailFormat(email: string, strictMode?: boolean): boolean;
/**
* Extracts and normalizes domain from email address
*/
declare function extractDomain(email: string): string | null;
/**
* Normalizes a domain name
*/
declare function normalizeDomain(domain: string): string;
/**
* Checks if a domain is internationalized
*/
declare function isInternationalDomain(domain: string): boolean;
/**
* Checks if a domain has subdomains
*/
declare function hasSubdomains(domain: string): boolean;
/**
* Gets the root domain from a domain (removes subdomains)
*/
declare function getRootDomain(domain: string): string;
/**
* Validates domain against options
*/
declare function validateDomainOptions(domain: string, options?: EmailValidationOptions): string[];
/**
* Checks if a domain is whitelisted
*/
declare function isWhitelistedDomain(domain: string, whitelistedDomains?: string[]): boolean;
/**
* Checks if a domain is in a list of disposable domains
*/
declare function isDomainInList(domain: string, domainList: Set<string> | string[]): boolean;
/**
* Creates domain information object
*/
declare function createDomainInfo(domain: string, disposableDomains: Set<string>, options?: EmailValidationOptions): DomainInfo;
//#endregion
export { DomainInfo, EmailCheckerConfig, EmailValidationOptions, EmailValidationResult, clearCache, configureEmailChecker, createDomainInfo, domainCache, extractDomain, getCacheStats, getDisposableDomains, getDomainInfo, getEmailCheckerConfig, getRootDomain, hasSubdomains, isDisposableEmail, isDomainDisposable, isDomainInList, isInternationalDomain, isValidEmailFormat, isWhitelistedDomain, normalizeDomain, resetEmailCheckerConfig, validateDomainOptions, validateEmail };