@emailcheck/email-validator-js
Version:
Advanced email validation with MX records, SMTP verification, disposable email detection, batch processing, and caching. Production-ready with TypeScript support.
96 lines (95 loc) • 3.88 kB
TypeScript
/**
* Edge-runtime / serverless email validator.
*
* No Node.js APIs (no `node:net`, no `node:dns`) — DNS is delegated to a
* caller-supplied `DNSResolver`, so the same code runs on Cloudflare Workers,
* Vercel Edge, Lambda@Edge, and Deno Deploy.
*
* Shares data with the main validator: `commonEmailDomains` and the typo map
* are imported from `src/data/`, so we never drift between the two surfaces.
*/
import type { DomainSuggesterOptions, EmailValidationResult, ValidateEmailOptions } from '../types';
/** Compact LRU/TTL cache. One Map, expiry stamp per entry, batched eviction. */
export declare class EdgeCache<T> {
private readonly maxSize;
private readonly ttl;
private readonly cache;
constructor(maxSize?: number, ttl?: number);
get(key: string): T | undefined;
set(key: string, value: T): void;
clear(): void;
size(): number;
private evict;
}
export declare const validationCache: EdgeCache<EmailValidationResult>;
export declare const mxCache: EdgeCache<string[]>;
/**
* Common email domains — re-exported so callers (Vercel Edge, etc.) can pass a
* custom subset via `DomainSuggesterOptions.customDomains`.
*/
export declare const COMMON_DOMAINS: readonly string[];
/** DNS resolver contract — caller-supplied so we don't import `node:dns`. */
export interface DNSResolver {
resolveMx(domain: string): Promise<Array<{
exchange: string;
priority: number;
}>>;
resolveTxt(domain: string): Promise<string[]>;
}
/** No-op resolver for environments where DNS isn't available. */
export declare class StubDNSResolver implements DNSResolver {
resolveMx(): Promise<Array<{
exchange: string;
priority: number;
}>>;
resolveTxt(): Promise<string[]>;
}
/**
* DNS-over-HTTPS resolver — works in any runtime with `fetch` (Cloudflare
* Workers, Vercel Edge, Deno, browsers, Node 18+). Defaults to Cloudflare's
* 1.1.1.1 endpoint; pass `endpoint` to use Google (8.8.8.8), NextDNS, or
* a self-hosted resolver.
*
* Compatible with [`cf-doh`](https://www.npmjs.com/package/cf-doh) — if you
* already use that, drop it in directly. This built-in keeps the package
* zero-dep so the same code works on every edge runtime without an extra
* install step.
*/
export interface DoHResolverOptions {
/** DoH endpoint URL. Default: https://cloudflare-dns.com/dns-query */
endpoint?: string;
/** Per-query request timeout, ms. Default: 5000 */
timeoutMs?: number;
/** Custom fetch (e.g. to add headers / proxy). Default: globalThis.fetch */
fetch?: typeof fetch;
}
export declare class DoHResolver implements DNSResolver {
private readonly endpoint;
private readonly timeoutMs;
private readonly fetchFn;
constructor(options?: DoHResolverOptions);
resolveMx(domain: string): Promise<Array<{
exchange: string;
priority: number;
}>>;
resolveTxt(domain: string): Promise<string[]>;
private query;
}
/**
* Suggest a corrected domain. Returns the canonical for a known typo,
* otherwise the closest match within the threshold, otherwise null.
*/
export declare function suggestDomain(domain: string, options?: DomainSuggesterOptions): string | null;
/**
* Validate one email — syntax / typo / disposable / free / MX (if a resolver
* is supplied). Each step is independently flag-gated so callers pay only for
* what they use.
*/
export declare function validateEmailCore(email: string, options?: ValidateEmailOptions & {
dnsResolver?: DNSResolver;
}): Promise<EmailValidationResult>;
export declare function validateEmailBatch(emails: string[], options?: ValidateEmailOptions & {
dnsResolver?: DNSResolver;
}): Promise<EmailValidationResult[]>;
export declare function clearCache(): void;
export type { DomainSuggesterOptions, EmailValidationResult, ValidateEmailOptions } from '../types';