zynor 0.0.82 → 0.0.89

package/dist/index.d.ts

@@ -673,6 +673,87 @@ export interface IResolver {
 	reverse(ip: string, options: AbortOptions): Promise<string[]>;
 	reverse(ip: string, options: AbortOptions, provider: ProviderName): Promise<string[]>;
 }
+declare class NativeProvider {
+	private queue;
+	private config;
+	/** Injected hickory binding, or null for the libuv path. Provided by the
+	 *  `'zynor/native'` entry; never loaded here. */
+	private rustBinding;
+	/**
+	 * Creates a new native DNS provider instance.
+	 *
+	 * @param config - Provider config (concurrency, rate limiting, enabled).
+	 * @param runtime - Internal: `rust` is the hickory binding injected by the
+	 *   `'zynor/native'` entry. When present, MX/A/AAAA/etc. route through it;
+	 *   when absent, everything uses libuv. Not part of the public surface.
+	 */
+	constructor(config?: ProviderConfig);
+	/**
+	 * Updates the provider configuration.
+	 */
+	updateConfig(config: ProviderConfig): void;
+	get enabled(): boolean;
+	get queueSize(): number;
+	get concurrency(): number;
+	get isFull(): boolean;
+	/** Returns the injected hickory binding, or null for the libuv path.
+	 *  No loading happens here — the `'zynor/native'` entry injects (or
+	 *  refuses to construct, if the binary is missing). */
+	private rust;
+	/**
+	 * Executes a function through the queue with abort/timeout support.
+	 */
+	private executeQueued;
+	/**
+	 * @internal Bypasses PQueue and intervalCap. Reserved for the validator
+	 * hot path. Dispatches to Rust when `useRust` is on (and binary loaded);
+	 * otherwise to `dns.resolve`. Both paths remain abort-aware.
+	 */
+	_resolveDirect<T>(hostname: string, type: RecordType, options?: AbortOptions): Promise<T>;
+	/**
+	 * Resolves A records for a hostname. TTL-aware variants stay on libuv.
+	 */
+	resolve4(hostname: string): Promise<string[]>;
+	resolve4(hostname: string, options: ResolveWithTtlOptions): Promise<RecordWithTtl[]>;
+	/** Resolves AAAA records for a hostname. TTL-aware variants stay on libuv. */
+	resolve6(hostname: string): Promise<string[]>;
+	resolve6(hostname: string, options: ResolveWithTtlOptions): Promise<RecordWithTtl[]>;
+	/** ANY records — Rust binding's shape doesn't mirror libuv's tagged union,
+	 *  so we always go through libuv. */
+	resolveAny(hostname: string, options?: AbortOptions): Promise<AnyRecord[]>;
+	resolveCaa(hostname: string, options?: AbortOptions): Promise<CaaRecord[]>;
+	resolveCname(hostname: string, options?: AbortOptions): Promise<string[]>;
+	resolveMx(hostname: string, options?: AbortOptions): Promise<MxRecord[]>;
+	resolveNaptr(hostname: string, options?: AbortOptions): Promise<NaptrRecord[]>;
+	resolveNs(hostname: string, options?: AbortOptions): Promise<string[]>;
+	resolvePtr(hostname: string, options?: AbortOptions): Promise<string[]>;
+	/** SOA. Rust returns `RustSoaRecord | null`; libuv throws on missing.
+	 *  Bridge: if Rust returns null, throw to match libuv contract. */
+	resolveSoa(hostname: string, options?: AbortOptions): Promise<SoaRecord>;
+	resolveSrv(hostname: string, options?: AbortOptions): Promise<SrvRecord[]>;
+	resolveTlsa(hostname: string, options?: AbortOptions): Promise<TlsaRecord[]>;
+	resolveTxt(hostname: string, options?: AbortOptions): Promise<string[][]>;
+	reverse(ip: string, options?: AbortOptions): Promise<string[]>;
+	/**
+	 * Generic resolve method. Dispatches to the typed methods so that the
+	 * Rust path is honored consistently — calling `resolve('gmail.com', 'MX')`
+	 * with `useRust: true` goes through hickory just like `resolveMx` would.
+	 */
+	resolve(hostname: string): Promise<string[]>;
+	resolve(hostname: string, rrtype: "A"): Promise<string[]>;
+	resolve(hostname: string, rrtype: "AAAA"): Promise<string[]>;
+	resolve(hostname: string, rrtype: "ANY"): Promise<AnyRecord[]>;
+	resolve(hostname: string, rrtype: "CAA"): Promise<CaaRecord[]>;
+	resolve(hostname: string, rrtype: "CNAME"): Promise<string[]>;
+	resolve(hostname: string, rrtype: "MX"): Promise<MxRecord[]>;
+	resolve(hostname: string, rrtype: "NAPTR"): Promise<NaptrRecord[]>;
+	resolve(hostname: string, rrtype: "NS"): Promise<string[]>;
+	resolve(hostname: string, rrtype: "PTR"): Promise<string[]>;
+	resolve(hostname: string, rrtype: "SOA"): Promise<SoaRecord>;
+	resolve(hostname: string, rrtype: "SRV"): Promise<SrvRecord[]>;
+	resolve(hostname: string, rrtype: "TLSA"): Promise<TlsaRecord[]>;
+	resolve(hostname: string, rrtype: "TXT"): Promise<string[][]>;
+}
 declare const EmailProviders: readonly [
 	{
 		readonly name: "Gmail";
@@ -2468,7 +2549,7 @@ declare const records: readonly [
 		readonly mx: "..................";
 	}
 ];
-type ProviderName$1 = typeof records[number]["name"] | ProviderNames;
+export type EmailProviderName = typeof records[number]["name"] | ProviderNames;
 /**
  * Logger signature for debug output. Receives one preformatted line per event.
  */
@@ -2577,6 +2658,18 @@ export declare class EmailValidator {
 		options?: ValidationConfig;
 		dns?: Omit<ZynorConfig, "cache">;
 	});
+	/**
+	 * @internal Overridable factory for the internal DNS resolver. Base
+	 * implementation returns a libuv-backed {@link Zynor} (quad9 off,
+	 * cache off). The subclass exported from `'zynor/native'` overrides
+	 * this to return a hickory-Rust-backed Zynor instead, so users of
+	 * that subpath get the Rust DNS engine without any public config
+	 * knob.
+	 *
+	 * Called from the constructor; JS method dispatch goes through the
+	 * actual class of `this`, so subclass overrides fire correctly.
+	 */
+	protected createDns(config?: Omit<ZynorConfig, "cache">): Zynor;
 	/**
 	 * Creates or returns an existing instance of the EmailValidator (Singleton pattern)
 	 * @param config - Configuration object for the EmailValidator
@@ -2724,7 +2817,7 @@ export declare class EmailValidator {
 	 *
 	 * 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
+	 * (`perPage`, 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.
 	 *
@@ -2734,7 +2827,7 @@ export declare class EmailValidator {
 	 * 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
+	 * the in-memory buffer reaches `10 * perPage`, workers pause picking
 	 * new emails until the buffer drains below the cap. This keeps memory
 	 * bounded for truly large inputs.
 	 *
@@ -2752,7 +2845,7 @@ export declare class EmailValidator {
 	 * @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.perPage - 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
@@ -2764,7 +2857,7 @@ export declare class EmailValidator {
 	 * ```typescript
 	 * await validator.each(
 	 *   emails, // could be millions
-	 *   { concurrency: 500, returnBatch: 50, deep: true },
+	 *   { concurrency: 500, perPage: 50, deep: true },
 	 *   async (batch) => {
 	 *     await db.insertMany(batch);
 	 *   },
@@ -2773,7 +2866,7 @@ export declare class EmailValidator {
 	 */
 	each(emails: string[], options: {
 		concurrency?: number;
-		returnBatch?: number;
+		perPage?: number;
 		deep?: boolean;
 		logo?: boolean;
 		signal?: AbortSignal;
@@ -3023,11 +3116,11 @@ export declare class EmailValidator {
 	 * business/enterprise providers, and many others. See the provider list for complete coverage.
 	 *
 	 * @overload
-	 * @param {ProviderName} provider - The name of the email provider (e.g., "Gmail", "Yahoo", "Outlook").
+	 * @param {EmailProviderName} provider - The name of the email provider (e.g., "Gmail", "Yahoo", "Outlook").
 	 * @returns {string | null} The webmail URL for the provider, or `null` if not found.
 	 *
 	 * @overload
-	 * @param {ProviderName} provider - The name of the email provider.
+	 * @param {EmailProviderName} provider - The name of the email provider.
 	 * @param {string} domainOrEmail - A domain name (e.g., "example.com") or email address (e.g., "user@example.com").
 	 *                                 Used as a fallback if the provider name doesn't have a direct URL mapping.
 	 * @returns {string | null} The webmail URL for the provider/domain, or `null` if not found.
@@ -3067,8 +3160,8 @@ export declare class EmailValidator {
 	 * validator.getProviderWebmailUrl("CustomProvider", "customdomain.com");
 	 * // May return a URL if the domain is recognized as a free provider
 	 */
-	getProviderWebmailUrl(provider: ProviderName$1): string | null;
-	getProviderWebmailUrl(provider: ProviderName$1, domainOrEmail: string): string | null;
+	getProviderWebmailUrl(provider: EmailProviderName): string | null;
+	getProviderWebmailUrl(provider: EmailProviderName, domainOrEmail: string): string | null;
 	getProviderWebmailUrl(domainOrEmail: string): string | null;
 	/**
 	 * Extract and validate email addresses from mixed HTML or plain-text content.
@@ -3103,7 +3196,7 @@ export declare class EmailValidator {
 export interface Valid {
 	success: true;
 	data: {
-		provider: ProviderName$1;
+		provider: EmailProviderName;
 		isFree: boolean;
 		email: string;
 		role: boolean;
@@ -3119,7 +3212,7 @@ export interface Invalid {
 	email: string;
 	role: boolean;
 }
-interface Disposable$1 {
+export interface EmailDisposable {
 	success: false;
 	type: "Disposable";
 	email: string;
@@ -3137,14 +3230,89 @@ export interface Syntax {
 	email: string;
 	role: boolean;
 }
-interface Error$1 {
+export interface EmailError {
 	success: false;
 	type: "Error";
 	email: string;
 	message: string;
 	role: boolean;
 }
-export type EmailResponse = Valid | Invalid | Rejected | Syntax | Error$1 | Disposable$1;
+export type EmailResponse = Valid | Invalid | Rejected | Syntax | EmailError | EmailDisposable;
+export interface RustResolveOptions {
+	/** Hard deadline in milliseconds. Rust task self-cancels at the
+	 *  boundary; prevents orphan tasks if the JS caller's watchdog gives
+	 *  up first. `| undefined` is explicit so callers can spread
+	 *  `{ timeoutMs: options?.timeout }` under exactOptionalPropertyTypes. */
+	timeoutMs?: number | undefined;
+}
+export interface RustMxRecord {
+	exchange: string;
+	priority: number;
+}
+export interface RustSrvRecord {
+	priority: number;
+	weight: number;
+	port: number;
+	name: string;
+}
+export interface RustSoaRecord {
+	nsname: string;
+	hostmaster: string;
+	serial: number;
+	refresh: number;
+	retry: number;
+	expire: number;
+	minttl: number;
+}
+export interface RustCaaRecord {
+	/** 128 when issuer-critical bit set, 0 otherwise (mirrors libuv). */
+	critical: number;
+	issue?: string;
+	issuewild?: string;
+	iodef?: string;
+}
+export interface RustNaptrRecord {
+	order: number;
+	preference: number;
+	flags: string;
+	service: string;
+	regexp: string;
+	replacement: string;
+}
+/** TLSA. Note: field is `matching` (not `match`); the validator-side
+ *  adapter renames if needed for the public TS type. */
+export interface RustTlsaRecord {
+	certUsage: number;
+	selector: number;
+	matching: number;
+	data: Uint8Array;
+}
+/** Generic envelope for `resolveAny`. Different shape from node:dns's
+ *  tagged union — `kind` is the record-type name ("A", "MX", …) and
+ *  `data` is hickory's textual rendering. The validator's hot path
+ *  doesn't use ANY, so divergence is acceptable. */
+export interface RustAnyRecord {
+	kind: string;
+	data: string;
+	ttl: number;
+}
+export interface RustBinding {
+	resolveMx(hostname: string, options?: RustResolveOptions | null): Promise<RustMxRecord[]>;
+	resolveA(hostname: string, options?: RustResolveOptions | null): Promise<string[]>;
+	resolveAaaa(hostname: string, options?: RustResolveOptions | null): Promise<string[]>;
+	resolveCname(hostname: string, options?: RustResolveOptions | null): Promise<string[]>;
+	resolveTxt(hostname: string, options?: RustResolveOptions | null): Promise<string[][]>;
+	resolveNs(hostname: string, options?: RustResolveOptions | null): Promise<string[]>;
+	resolvePtr(hostname: string, options?: RustResolveOptions | null): Promise<string[]>;
+	resolveSrv(hostname: string, options?: RustResolveOptions | null): Promise<RustSrvRecord[]>;
+	resolveSoa(hostname: string, options?: RustResolveOptions | null): Promise<RustSoaRecord | null>;
+	resolveCaa(hostname: string, options?: RustResolveOptions | null): Promise<RustCaaRecord[]>;
+	resolveNaptr(hostname: string, options?: RustResolveOptions | null): Promise<RustNaptrRecord[]>;
+	resolveTlsa(hostname: string, options?: RustResolveOptions | null): Promise<RustTlsaRecord[]>;
+	resolveAny(hostname: string, options?: RustResolveOptions | null): Promise<RustAnyRecord[]>;
+	reverseLookup(ip: string, options?: RustResolveOptions | null): Promise<string[]>;
+	buildInfo?(): string;
+}
 /**
  * Main DNS resolver class that aggregates multiple DNS providers.
  */
@@ -3155,12 +3323,24 @@ export declare class Zynor {
 	private dnsTtl;
 	private inflight;
 	private rrIndex;
+	protected rust: RustBinding | null;
 	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;
+	/** Consecutive-failure counters per provider; reset on any success. We only
+	 *  pause once a provider's streak exceeds {@link DOH_PAUSE_AFTER}, so single
+	 *  transient errors don't cascade-pause healthy providers under high load. */
+	private dohFailureStreak;
 	private static readonly DOH_PAUSE_MS;
+	private static readonly DOH_PAUSE_AFTER;
+	/** Native's reported `concurrency` (default 50) is the PQueue limit, which
+	 *  the validator path bypasses anyway. The *real* parallel ceiling is
+	 *  libuv's getaddrinfo thread pool — defaults to 4 unless UV_THREADPOOL_SIZE
+	 *  is set. {@link pickFreestProvider} uses this to weight native correctly
+	 *  in load balancing instead of dumping 60%+ of traffic on libuv. */
+	private static readonly NATIVE_EFFECTIVE_CONCURRENCY;
 	/**
 	 * Creates a new Zynor resolver instance.
 	 * @param config - Configuration for all providers
@@ -3213,6 +3393,18 @@ export declare class Zynor {
 	 * Initializes all DNS providers with their configurations.
 	 */
 	private initializeProviders;
+	/**
+	 * @internal Overridable factory for the `native` provider. Base
+	 * implementation returns a libuv-backed NativeProvider. The subclass
+	 * exported from `'zynor/native'` overrides this to inject `useRust: true`
+	 * so importers of that subpath get the hickory-dns binding.
+	 *
+	 * Called from {@link initializeProviders} during construction. JS method
+	 * dispatch resolves through the *actual* class of `this`, so subclass
+	 * overrides fire correctly even though the call site is in the base
+	 * constructor's code path.
+	 */
+	protected createNativeProvider(config?: ProviderConfig): NativeProvider;
 	/**
 	 * Sets configuration for a specific provider.
 	 * @param provider - The provider name
@@ -3440,15 +3632,20 @@ 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).
+	 * @internal Validator-only. Picks the enabled provider with the lowest
+	 * load ratio (`inFlight / effectiveCapacity`), which yields a distribution
+	 * proportional to each provider's capacity even when total in-flight far
+	 * exceeds total capacity. A simple slack-based picker over-saturates
+	 * everyone equally above their cap and effectively ignores weights; the
+	 * ratio formulation keeps weights honest at any load level.
+	 *
+	 * Native is included but its effective cap is clamped to libuv's
+	 * getaddrinfo pool ({@link NATIVE_EFFECTIVE_CONCURRENCY}, defaults to
+	 * UV_THREADPOOL_SIZE or 4) — otherwise the validator would dump 50+ in-
+	 * flight lookups onto a 4-thread pool. Paused DoH providers are excluded;
+	 * if every enabled provider is paused, the filter is dropped.
+	 *
+	 * RR breaks ties so even loads spread.
 	 */
 	private pickFreestProvider;
 	/**
@@ -3501,24 +3698,24 @@ export declare class Zynor {
 	/**
 	 * 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
+	 * full semantics — defaults are `concurrency: 500`, `perPage: 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 options - Streaming options (concurrency, perPage, 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 Zynor.each(emails, { perPage: 50 }, async (batch) => {
 	 *   await db.insertMany(batch);
 	 * });
 	 * ```
 	 */
 	static each(emails: string[], options: {
 		concurrency?: number;
-		returnBatch?: number;
+		perPage?: number;
 		deep?: boolean;
 		logo?: boolean;
 		signal?: AbortSignal;