zynor 0.0.73 → 0.0.77

package/dist/index.d.ts

@@ -2100,22 +2100,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.
@@ -2182,6 +2198,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 +2275,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.
-	 */
-	private _log;
+	 * 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.