zynor 0.0.68 → 0.0.77

package/dist/index.d.ts

@@ -2096,7 +2096,42 @@ declare const records: readonly [
 	}
 ];
 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 {
+	/**
+	 * Structured debug logging for the validation flow. Off by default.
+	 *
+	 * - `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 <LEVEL>] <scope>: <msg>`.
+	 *
+	 * @default false
+	 */
+	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.
@@ -2162,6 +2197,9 @@ export declare class EmailValidator {
 	private validateCache;
 	private ipCache;
 	private inflight;
+	private _logFn;
+	/** 0=silent, 1=info, 2=debug, 3=trace */
+	private _logLevel;
 	private validationConfig;
 	constructor(config?: {
 		options?: ValidationConfig;
@@ -2236,6 +2274,34 @@ export declare class EmailValidator {
 		deep?: boolean;
 		logo?: boolean;
 	}): Promise<EmailResponse>;
+	/**
+	 * 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 _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.