zynor 0.0.73 → 0.0.82

package/dist/index.d.ts

@@ -685,19 +685,60 @@ declare const EmailProviders: readonly [
 		readonly name: "Outlook";
 		readonly domains: readonly [
 			"@outlook.com",
+			"@outlook.com.au",
+			"@outlook.com.br",
+			"@outlook.cl",
+			"@outlook.cz",
+			"@outlook.de",
+			"@outlook.dk",
+			"@outlook.es",
+			"@outlook.fr",
+			"@outlook.hu",
+			"@outlook.ie",
+			"@outlook.in",
+			"@outlook.it",
+			"@outlook.jp",
+			"@outlook.kr",
+			"@outlook.lv",
+			"@outlook.my",
+			"@outlook.ph",
+			"@outlook.pt",
+			"@outlook.sa",
+			"@outlook.sg",
+			"@outlook.sk",
+			"@outlook.co.id",
+			"@outlook.co.th",
 			"@hotmail.com",
+			"@hotmail.com.ar",
+			"@hotmail.com.au",
+			"@hotmail.com.br",
 			"@hotmail.co.uk",
+			"@hotmail.de",
+			"@hotmail.es",
 			"@hotmail.fr",
+			"@hotmail.gr",
 			"@hotmail.it",
-			"@hotmail.es",
-			"@hotmail.de",
+			"@hotmail.jp",
+			"@hotmail.nl",
+			"@hotmail.no",
+			"@hotmail.se",
 			"@live.com",
+			"@live.com.ar",
+			"@live.com.au",
+			"@live.com.mx",
 			"@live.co.uk",
+			"@live.ca",
+			"@live.cl",
+			"@live.cn",
+			"@live.de",
+			"@live.dk",
 			"@live.fr",
-			"@live.nl",
 			"@live.it",
-			"@live.com.au",
-			"@live.ca",
+			"@live.jp",
+			"@live.nl",
+			"@live.no",
+			"@live.ru",
+			"@live.se",
 			"@msn.com"
 		];
 	},
@@ -1612,6 +1653,338 @@ declare const EmailProviders: readonly [
 			"@tutamail.com",
 			"@keemail.me"
 		];
+	},
+	{
+		readonly name: "DuckDuckGo Email";
+		readonly domains: readonly [
+			"@duck.com"
+		];
+	},
+	{
+		readonly name: "SimpleLogin";
+		readonly domains: readonly [
+			"@simplelogin.com",
+			"@simplelogin.fr",
+			"@simplelogin.co",
+			"@simplelogin.io",
+			"@aleeas.com",
+			"@silomails.com",
+			"@slmails.com",
+			"@slmail.me"
+		];
+	},
+	{
+		readonly name: "Addy.io";
+		readonly domains: readonly [
+			"@addy.io",
+			"@anonaddy.com",
+			"@anonaddy.me"
+		];
+	},
+	{
+		readonly name: "Firefox Relay";
+		readonly domains: readonly [
+			"@mozmail.com"
+		];
+	},
+	{
+		readonly name: "StartMail";
+		readonly domains: readonly [
+			"@startmail.com"
+		];
+	},
+	{
+		readonly name: "Runbox";
+		readonly domains: readonly [
+			"@runbox.com"
+		];
+	},
+	{
+		readonly name: "Disroot";
+		readonly domains: readonly [
+			"@disroot.org"
+		];
+	},
+	{
+		readonly name: "Riseup";
+		readonly domains: readonly [
+			"@riseup.net"
+		];
+	},
+	{
+		readonly name: "CounterMail";
+		readonly domains: readonly [
+			"@countermail.com"
+		];
+	},
+	{
+		readonly name: "Soverin";
+		readonly domains: readonly [
+			"@soverin.net"
+		];
+	},
+	{
+		readonly name: "WP";
+		readonly domains: readonly [
+			"@wp.pl",
+			"@o2.pl",
+			"@tlen.pl"
+		];
+	},
+	{
+		readonly name: "Onet";
+		readonly domains: readonly [
+			"@onet.pl",
+			"@op.pl",
+			"@vp.pl",
+			"@onet.eu"
+		];
+	},
+	{
+		readonly name: "Interia";
+		readonly domains: readonly [
+			"@interia.pl",
+			"@interia.eu",
+			"@poczta.fm"
+		];
+	},
+	{
+		readonly name: "Gazeta.pl";
+		readonly domains: readonly [
+			"@gazeta.pl"
+		];
+	},
+	{
+		readonly name: "Seznam";
+		readonly domains: readonly [
+			"@seznam.cz",
+			"@email.cz",
+			"@post.cz"
+		];
+	},
+	{
+		readonly name: "Centrum";
+		readonly domains: readonly [
+			"@centrum.cz",
+			"@centrum.sk"
+		];
+	},
+	{
+		readonly name: "Volny";
+		readonly domains: readonly [
+			"@volny.cz"
+		];
+	},
+	{
+		readonly name: "Freemail HU";
+		readonly domains: readonly [
+			"@freemail.hu",
+			"@citromail.hu"
+		];
+	},
+	{
+		readonly name: "In.gr";
+		readonly domains: readonly [
+			"@in.gr"
+		];
+	},
+	{
+		readonly name: "Sify";
+		readonly domains: readonly [
+			"@sifymail.com",
+			"@sify.com"
+		];
+	},
+	{
+		readonly name: "Indiatimes";
+		readonly domains: readonly [
+			"@indiatimes.com"
+		];
+	},
+	{
+		readonly name: "BSNL";
+		readonly domains: readonly [
+			"@bsnl.in",
+			"@dataone.in"
+		];
+	},
+	{
+		readonly name: "Locaweb";
+		readonly domains: readonly [
+			"@lwmail.com.br"
+		];
+	},
+	{
+		readonly name: "Movistar";
+		readonly domains: readonly [
+			"@telefonica.net",
+			"@movistar.es"
+		];
+	},
+	{
+		readonly name: "Telkom SA";
+		readonly domains: readonly [
+			"@telkomsa.net",
+			"@vodamail.co.za",
+			"@webmail.co.za"
+		];
+	},
+	{
+		readonly name: "BIGLOBE";
+		readonly domains: readonly [
+			"@biglobe.ne.jp"
+		];
+	},
+	{
+		readonly name: "@nifty";
+		readonly domains: readonly [
+			"@nifty.com",
+			"@nifty.ne.jp"
+		];
+	},
+	{
+		readonly name: "OCN";
+		readonly domains: readonly [
+			"@ocn.ne.jp"
+		];
+	},
+	{
+		readonly name: "Rakuten";
+		readonly domains: readonly [
+			"@rakuten.co.jp",
+			"@gol.com"
+		];
+	},
+	{
+		readonly name: "Excite Japan";
+		readonly domains: readonly [
+			"@excite.co.jp"
+		];
+	},
+	{
+		readonly name: "So-net";
+		readonly domains: readonly [
+			"@so-net.ne.jp"
+		];
+	},
+	{
+		readonly name: "Xtra";
+		readonly domains: readonly [
+			"@xtra.co.nz"
+		];
+	},
+	{
+		readonly name: "Spectrum";
+		readonly domains: readonly [
+			"@spectrum.net"
+		];
+	},
+	{
+		readonly name: "RoadRunner";
+		readonly domains: readonly [
+			"@rr.com",
+			"@twc.com",
+			"@roadrunner.com",
+			"@nc.rr.com",
+			"@sc.rr.com",
+			"@socal.rr.com",
+			"@tampabay.rr.com",
+			"@cinci.rr.com",
+			"@nycap.rr.com",
+			"@neo.rr.com"
+		];
+	},
+	{
+		readonly name: "Mediacom";
+		readonly domains: readonly [
+			"@mediacombb.net",
+			"@mchsi.com"
+		];
+	},
+	{
+		readonly name: "Optimum";
+		readonly domains: readonly [
+			"@optimum.net"
+		];
+	},
+	{
+		readonly name: "Suddenlink";
+		readonly domains: readonly [
+			"@suddenlink.net"
+		];
+	},
+	{
+		readonly name: "RCN";
+		readonly domains: readonly [
+			"@rcn.com"
+		];
+	},
+	{
+		readonly name: "Breezeline";
+		readonly domains: readonly [
+			"@atlanticbb.net",
+			"@breezeline.com"
+		];
+	},
+	{
+		readonly name: "BT Internet";
+		readonly domains: readonly [
+			"@btinternet.com",
+			"@btopenworld.com",
+			"@talk21.com"
+		];
+	},
+	{
+		readonly name: "Virgin Media";
+		readonly domains: readonly [
+			"@virginmedia.com",
+			"@virgin.net"
+		];
+	},
+	{
+		readonly name: "TalkTalk";
+		readonly domains: readonly [
+			"@talktalk.net"
+		];
+	},
+	{
+		readonly name: "Plusnet";
+		readonly domains: readonly [
+			"@plus.net",
+			"@force9.co.uk",
+			"@free-online.net"
+		];
+	},
+	{
+		readonly name: "Rogers";
+		readonly domains: readonly [
+			"@rogers.com"
+		];
+	},
+	{
+		readonly name: "Bell";
+		readonly domains: readonly [
+			"@bell.net"
+		];
+	},
+	{
+		readonly name: "Telus";
+		readonly domains: readonly [
+			"@telus.net"
+		];
+	},
+	{
+		readonly name: "Videotron";
+		readonly domains: readonly [
+			"@videotron.ca",
+			"@videotron.qc.ca"
+		];
+	},
+	{
+		readonly name: "Cogeco";
+		readonly domains: readonly [
+			"@cogeco.ca"
+		];
 	}
 ];
 export type ProviderNames = typeof EmailProviders[number]["name"];
@@ -2100,22 +2473,38 @@ type ProviderName$1 = typeof records[number]["name"] | ProviderNames;
  * Logger signature for debug output. Receives one preformatted line per event.
  */
 export type DebugLogger = (line: string) => void;
+/**
+ * Verbosity level for debug logging.
+ * - `info`  — top-level checkpoints only: validate() enter/exit, MX result,
+ *             shallow/deep/Invalid outcome, deep-validation enter/exit,
+ *             validateBulk phase boundaries. Best for spotting *where* a hang
+ *             occurs without drowning in noise.
+ * - `debug` — adds sub-operations: cache hits/misses, MX→record matches,
+ *             domain_check probes, dnsLookup per-IP iteration, IP-cascade
+ *             HTTP calls, per-EmailProviders match.
+ * - `trace` — adds every event: inflight hit/cleared, per-mx loop iterations,
+ *             per-worker bulk progress, syntax/rejected/disposable early
+ *             returns. Use only when `debug` doesn't pinpoint the issue.
+ */
+export type DebugLevel = "info" | "debug" | "trace";
 export interface ValidationConfig {
 	/**
-	 * Enable structured debug logging for every async boundary in the
-	 * validation flow (cache hits/misses, MX resolution, MX-record matches,
-	 * domain_check probes, deep-validation phases, IP-lookup cascade,
-	 * inflight enter/exit). Useful for diagnosing slow or stalled calls.
+	 * Structured debug logging for the validation flow. Off by default.
 	 *
-	 * - `true` — log to stderr via `console.error`
-	 * - `(line: string) => void` — receive each line as a string
 	 * - `false` / omitted — silent (no overhead)
+	 * - `true` — `info` level, logged to stderr via `console.error`
+	 * - `'info' | 'debug' | 'trace'` — that level on stderr
+	 * - `(line: string) => void` — `trace` level, each line passed to fn
+	 * - `{ level, log }` — both explicit
 	 *
-	 * Each line is `[zynor HH:MM:SS.mmm] <scope>: <msg>`.
+	 * Each line is `[zynor HH:MM:SS.mmm <LEVEL>] <scope>: <msg>`.
 	 *
 	 * @default false
 	 */
-	debug?: boolean | DebugLogger;
+	debug?: boolean | DebugLevel | DebugLogger | {
+		level?: DebugLevel;
+		log?: DebugLogger;
+	};
 	/**
 	 * @description This will enable deep validation of the email. slower than normal email validator as it triggers multiple dns requests, or travel to the ip address to get the domain name.
 	 * This is per request option, passing true to the getProvider without turning this ON, it wont work and vice versa.
@@ -2170,7 +2559,6 @@ export interface ValidateCacheEntry {
 	method?: "shallow" | "deep";
 }
 export declare class EmailValidator {
-	private resolver;
 	private findIpKeys;
 	private roles;
 	private records;
@@ -2182,6 +2570,8 @@ export declare class EmailValidator {
 	private ipCache;
 	private inflight;
 	private _logFn;
+	/** 0=silent, 1=info, 2=debug, 3=trace */
+	private _logLevel;
 	private validationConfig;
 	constructor(config?: {
 		options?: ValidationConfig;
@@ -2257,11 +2647,33 @@ export declare class EmailValidator {
 		logo?: boolean;
 	}): Promise<EmailResponse>;
 	/**
-	 * Emit a debug line if `validationConfig.debug` is enabled.
-	 * Format: `[zynor HH:MM:SS.mmm] <scope>: <msg>`. No-op (and zero string
-	 * formatting cost) when logging is off.
+	 * Emit a log line if its level is at or below the configured threshold.
+	 * Format: `[zynor HH:MM:SS.mmm <LVL>] <scope>: <msg>`. Zero formatting
+	 * cost when level is filtered out.
+	 *
+	 * Use the typed wrappers (`_info`/`_debug`/`_trace`) — they make every
+	 * call site self-document its expected verbosity.
 	 */
-	private _log;
+	private _emit;
+	/** Top-level checkpoint (validate enter/exit, MX result, terminal outcome). */
+	private _info;
+	/** Sub-operation (cache hit/miss, network call start/end, sub-loop boundary). */
+	private _debug;
+	/** Fine-grained event (singleflight cleanup, per-iteration loop, early returns). */
+	private _trace;
+	/**
+	 * Belt-and-suspenders timeout for DNS calls. Races the underlying
+	 * operation against a `setTimeout`-based watchdog so a hung c-ares
+	 * query (or a broken AbortSignal propagation) cannot pin the inflight
+	 * Map indefinitely. The leaked DNS promise continues running in the
+	 * background — c-ares eventually abandons it on its own — but the
+	 * wrapper rejects on time and the inflight key is always cleared.
+	 *
+	 * Logged at INFO so the watchdog firing is visible at default
+	 * `debug: true`; the `WATCHDOG fired` line tells you which domain is
+	 * misbehaving.
+	 */
+	private _withWatchdog;
 	/**
 	 * Build a Valid response with `websiteTitle` and optional `loginUrl`
 	 * populated from the provider maps in ./provider-webmail.
@@ -2307,6 +2719,66 @@ export declare class EmailValidator {
 		signal?: AbortSignal;
 		timeout?: number;
 	}): Promise<EmailResponse[]>;
+	/**
+	 * Streams validation results as they complete, in completion order.
+	 *
+	 * Unlike {@link validateBulk}, which waits for every input before returning,
+	 * `each` invokes `onBatch` as soon as enough results have accumulated
+	 * (`returnBatch`, default 10) and continues until every input has been
+	 * processed. Designed for very large inputs (millions) where time-to-first
+	 * result matters and holding the entire result array in memory is wasteful.
+	 *
+	 * Concurrency is controlled here, not by the DNS layer: every validation
+	 * routes through the validator-internal direct path, which bypasses the
+	 * per-provider PQueue and rate limiter. DoH providers are load-balanced
+	 * round-robin per validation.
+	 *
+	 * Backpressure: `onBatch` is awaited serially. If the callback is slow and
+	 * the in-memory buffer reaches `10 * returnBatch`, workers pause picking
+	 * new emails until the buffer drains below the cap. This keeps memory
+	 * bounded for truly large inputs.
+	 *
+	 * Errors:
+	 * - Per-email errors become error-shaped {@link EmailResponse} entries in
+	 *   the stream — they never abort the batch.
+	 * - An error thrown by `onBatch` aborts production: workers stop picking
+	 *   new emails, in-flight work is awaited, and the returned promise
+	 *   rejects with the first such error.
+	 *
+	 * Abort: when the supplied `signal` fires, workers stop picking new
+	 * emails, in-flight validations finish, the buffer is flushed via
+	 * `onBatch`, and the returned promise resolves cleanly.
+	 *
+	 * @param emails - The list of email addresses to validate
+	 * @param options - Streaming options
+	 * @param options.concurrency - Max parallel validations (default 500)
+	 * @param options.returnBatch - Min results buffered before invoking onBatch (default 10)
+	 * @param options.deep - Enable deep validation per email
+	 * @param options.logo - Fetch provider logo per email
+	 * @param options.signal - AbortSignal to cancel the batch
+	 * @param options.timeout - Per-validation timeout in ms
+	 * @param onBatch - Invoked with each completed batch; may return a Promise
+	 * @returns Resolves once every input has been processed and flushed
+	 *
+	 * @example
+	 * ```typescript
+	 * await validator.each(
+	 *   emails, // could be millions
+	 *   { concurrency: 500, returnBatch: 50, deep: true },
+	 *   async (batch) => {
+	 *     await db.insertMany(batch);
+	 *   },
+	 * );
+	 * ```
+	 */
+	each(emails: string[], options: {
+		concurrency?: number;
+		returnBatch?: number;
+		deep?: boolean;
+		logo?: boolean;
+		signal?: AbortSignal;
+		timeout?: number;
+	} | undefined, onBatch: (batch: EmailResponse[]) => void | Promise<void>): Promise<void>;
 	private is_wale4r_zimbra;
 	private is_zimbra;
 	private is_webmail;
@@ -2682,6 +3154,13 @@ export declare class Zynor {
 	private dnsCache;
 	private dnsTtl;
 	private inflight;
+	private rrIndex;
+	private dnsInFlight;
+	/** Epoch-ms until which a DoH provider is considered failing and excluded
+	 *  from {@link pickFreestProvider}. Native is never paused — libuv errors
+	 *  are local concerns, not upstream-health signals. */
+	private dohPausedUntil;
+	private static readonly DOH_PAUSE_MS;
 	/**
 	 * Creates a new Zynor resolver instance.
 	 * @param config - Configuration for all providers
@@ -2960,6 +3439,36 @@ export declare class Zynor {
 	 * ```
 	 */
 	resolve: IResolver["resolve"];
+	/**
+	 * @internal Validator-only. Picks the enabled provider with the most spare
+	 * capacity (advertised `concurrency` minus current in-flight count),
+	 * skipping any DoH provider currently paused after a failure. Round-robin
+	 * breaks ties so we don't always hit the same one when load is even.
+	 * Native is included in the pool — it rides libuv's thread pool rather
+	 * than the shared HTTP socket pool DoH providers contend for, so mixing
+	 * it in spreads load across independent I/O substrates. If every enabled
+	 * provider is paused, the pause filter is dropped (we'd rather retry than
+	 * fail).
+	 */
+	private pickFreestProvider;
+	/**
+	 * Distinguishes "this provider is broken/slow" from cases that don't
+	 * indicate provider health:
+	 *  - DNS-level no-such-name answers (ENOTFOUND/NODATA): authoritative,
+	 *    not the provider's fault.
+	 *  - AbortError: caller-initiated cancellation or per-call timeout.
+	 *    A user's tight deadline shouldn't make us blacklist a healthy provider.
+	 */
+	private isProviderFailure;
+	/**
+	 * @internal Validator-only. Direct DNS path that bypasses the per-provider
+	 * PQueue and rate limiter while keeping LRU cache + singleflight. Provider
+	 * is chosen by least-loaded-first (the validator does not need to know or
+	 * pick); the in-flight counter is incremented inside the singleflight
+	 * closure so coalesced waiters don't overcount upstream load. Public
+	 * consumers must continue to use the queued resolve* methods.
+	 */
+	_resolveDirect<T>(hostname: string, type: RecordType, options?: AbortOptions): Promise<T>;
 	/**
 	 * Returns the sum of concurrency limits across all enabled DNS providers.
 	 * Used by `validateBulk` to determine default parallelism.
@@ -2989,6 +3498,32 @@ export declare class Zynor {
 		signal?: AbortSignal;
 		timeout?: number;
 	}): Promise<EmailResponse[]>;
+	/**
+	 * Streams validation results as they complete. Forwards to
+	 * {@link EmailValidator.each} on the singleton validator. See `each` for
+	 * full semantics — defaults are `concurrency: 500`, `returnBatch: 10`, and
+	 * all validator-routed DNS calls bypass the per-provider queue.
+	 *
+	 * @param emails - The list of email addresses to validate
+	 * @param options - Streaming options (concurrency, returnBatch, deep, etc.)
+	 * @param onBatch - Callback invoked with each completed batch
+	 * @returns Resolves once every input has been processed and flushed
+	 *
+	 * @example
+	 * ```typescript
+	 * await Zynor.each(emails, { returnBatch: 50 }, async (batch) => {
+	 *   await db.insertMany(batch);
+	 * });
+	 * ```
+	 */
+	static each(emails: string[], options: {
+		concurrency?: number;
+		returnBatch?: number;
+		deep?: boolean;
+		logo?: boolean;
+		signal?: AbortSignal;
+		timeout?: number;
+	} | undefined, onBatch: Parameters<EmailValidator["each"]>[2]): Promise<void>;
 }
 /**
  * Resets the default resolver instance.