zynor 0.0.44 → 0.0.48

package/README.md

@@ -1,758 +1,722 @@
 # zynor
 
 [![npm version](https://badge.fury.io/js/zynor.svg)](https://badge.fury.io/js/zynor)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
 
-A comprehensive, promise-based DNS resolver library that aggregates multiple DNS-over-HTTPS (DoH) providers with advanced concurrency control, email validation, and flexible configuration. Built with TypeScript for maximum type safety and developer experience.
-
-## 📋 Table of Contents
-
-- [Features](#-features)
-- [Installation](#-installation)
-- [Quick Start](#-quick-start)
-- [DNS Providers](#-dns-providers)
-- [Configuration](#-configuration)
-- [API Reference](#-api-reference)
-- [DNS Record Types](#-dns-record-types)
+A DNS resolution and email intelligence library for Node.js. Zynor combines four DNS providers behind a single API with built-in concurrency control, caching, automatic failover, and a full-featured email validation engine.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [DNS Resolution](#dns-resolution)
+  - [Standalone Functions](#standalone-functions)
+  - [Zynor Class](#zynor-class)
+  - [Supported Record Types](#supported-record-types)
+  - [Provider Selection](#provider-selection)
+  - [AbortSignal and Timeout](#abortsignal-and-timeout)
+- [DNS Caching](#dns-caching)
+  - [Request Deduplication](#request-deduplication)
+  - [LruCache](#lrucache)
+- [Provider Configuration](#provider-configuration)
+  - [Concurrency and Rate Limiting](#concurrency-and-rate-limiting)
+  - [Runtime Configuration Updates](#runtime-configuration-updates)
 - [Email Validation](#email-validation)
-- [TypeScript Support](#-typescript-support)
-- [License](#-license)
-
-## 🚀 Features
-
-Zynor is designed to be the most comprehensive and reliable DNS resolution library for modern JavaScript applications. It combines multiple DNS-over-HTTPS providers with intelligent load balancing, advanced error handling, and extensive email validation capabilities to deliver enterprise-grade DNS resolution with exceptional performance and reliability.
-
-- **🌐 Multiple DNS Providers**: Google DoH, Cloudflare DoH, Quad9 DoH, and Node.js native DNS
-- **⚡ High Performance**: Concurrent requests with intelligent load balancing
-- **🎯 Smart Provider Selection**: Automatic failover and random selection
-- **🔧 Flexible Configuration**: Per-provider concurrency and rate limiting
-- **📝 Full TypeScript Support**: Complete type definitions and IntelliSense
-- **🌍 Cross-Platform**: Works with Node.js 18+, Deno, and Bun
-- **📊 Complete DNS API**: All standard DNS record types supported
-- **📧 Email Validation**: Comprehensive email domain validation and webmail detection
-- **🛡️ Error Handling**: Robust error handling with detailed error information
-- **🔄 Automatic Retry**: Built-in retry logic with exponential backoff
-- **📈 Queue Management**: Advanced queue management with rate limiter
-- **🎛️ Runtime Configuration**: Dynamic configuration updates without restart
+  - [Basic Validation](#basic-validation)
+  - [Deep Validation](#deep-validation)
+  - [Bulk Validation](#bulk-validation)
+  - [Provider Detection](#provider-detection)
+  - [Disposable Email Detection](#disposable-email-detection)
+  - [Role-Based Email Detection](#role-based-email-detection)
+  - [Free Domain Detection](#free-domain-detection)
+  - [Webmail URL Lookup](#webmail-url-lookup)
+  - [Email Extraction](#email-extraction)
+  - [Persistent Caching](#persistent-caching)
+- [Error Handling](#error-handling)
+- [TypeScript Support](#typescript-support)
+- [License](#license)
 
-## 📦 Installation
+---
 
-Zynor is available as an npm package and can be installed using any modern JavaScript package manager. The library is built with zero dependencies for maximum compatibility and minimal bundle size, making it perfect for both server-side applications and edge computing environments.
+## Installation
 
-**Using npm:**
 ```bash
 npm install zynor
 ```
 
-**Using Yarn:**
 ```bash
 yarn add zynor
 ```
 
-**Using pnpm:**
 ```bash
 pnpm add zynor
 ```
 
-**Requirements:**
-- Node.js 18.0.0 or higher
-- TypeScript 4.5+ (for TypeScript projects)
-- Modern JavaScript environment with Promise support
-
-## 🚀 Quick Start
-
-Get started with Zynor in seconds! The library offers two main approaches: standalone functions for simple DNS queries and the Zynor class for advanced configuration and control. Both approaches provide the same powerful DNS resolution capabilities with automatic provider selection and intelligent error handling.
+**Requirements:** Node.js 18.0.0 or higher.
 
-### Standalone Functions (Recommended for Simple Use Cases)
+---
 
-Standalone functions provide the quickest way to perform DNS lookups with sensible defaults and automatic provider selection:
+## Quick Start
 
 ```typescript
-// Using standalone functions (recommended for simple use cases)
-import { resolve4, resolveMx, resolveAny } from 'zynor';
-
-// Resolve A records
-const addresses = await resolve4('example.com');
-console.log(addresses); // ['93.184.216.34']
+import { resolve4, resolveMx } from "zynor";
 
-// Resolve MX records
-const mxRecords = await resolveMx('example.com');
-console.log(mxRecords); // [{ priority: 10, exchange: 'mail.example.com' }]
+// Resolve IPv4 addresses
+const ips = await resolve4("example.com");
+// => ['93.184.216.34']
 
-// Resolve with specific provider
-const googleResult = await resolve4('example.com', undefined, 'google');
+// Resolve mail servers
+const mx = await resolveMx("example.com");
+// => [{ priority: 10, exchange: 'mail.example.com' }]
 ```
 
-### Zynor Class (For Advanced Configuration)
+Import a function, pass a hostname, get results. No configuration needed.
 
-The Zynor class provides fine-grained control over DNS providers, concurrency limits, timeouts, and retry behavior:
+For more control:
 
 ```typescript
-// Using Zynor class (for advanced configuration)
-import { Zynor } from 'zynor';
+import { Zynor } from "zynor";
 
 const dns = new Zynor({
   google: { enabled: true, limit: { concurrency: 10 } },
-  cloudflare: { enabled: true, limit: { concurrency: 5 } }
+  cloudflare: { enabled: true, limit: { concurrency: 5 } },
+  quad9: { enabled: false },
+  native: { enabled: true },
 });
 
-const addresses = await dns.resolve4('example.com');
+const ips = await dns.resolve4("example.com");
 ```
 
-### CommonJS Support
-
-Zynor fully supports CommonJS environments for maximum compatibility:
+CommonJS is also supported:
 
 ```javascript
-// CommonJS usage
-const { resolve4, Zynor } = require('zynor');
-
-const addresses = await resolve4('example.com');
+const { resolve4, Zynor } = require("zynor");
 ```
 
-## 🌐 DNS Providers
-
-Zynor integrates with multiple DNS providers to ensure maximum reliability, performance, and flexibility. Each provider offers unique advantages and can be configured independently with custom settings for concurrency, timeouts, and retry behavior. The library automatically selects the best available provider or allows manual provider specification for specific use cases.
-
-### Native Provider
-
-The native provider leverages Node.js's built-in DNS resolution capabilities, providing seamless integration with system DNS settings and local network configurations.
-
-- **Endpoint**: Node.js built-in `dns/promises` module
-- **Features**: Supports all DNS methods including `lookup()`
-- **Use Case**: Local/internal DNS resolution, system DNS settings
-- **Advantages**: No external dependencies, respects system DNS configuration
-- **Best For**: Internal networks, development environments, system-integrated applications
-
-### Google DoH (DNS-over-HTTPS)
-
-Google's public DNS service provides enterprise-grade DNS resolution with global infrastructure and comprehensive DNSSEC validation.
+---
 
-- **Endpoint**: `https://dns.google/resolve`
-- **Features**: DNSSEC validation, high reliability, global anycast network
-- **Use Case**: Public DNS resolution with Google's infrastructure
-- **Advantages**: Global CDN, excellent uptime, DNSSEC support, comprehensive logging
-- **Best For**: Production applications, global services, DNSSEC-required environments
+## DNS Resolution
 
-### Cloudflare DoH (DNS-over-HTTPS)
+### Standalone Functions
 
-Cloudflare's privacy-focused DNS service emphasizes user privacy with minimal logging and fast global resolution.
+You don't need to create an instance or configure anything to start resolving DNS records. Every DNS method is exported as a standalone function you can import and call directly. Each function handles provider selection, queuing, caching, and error translation behind the scenes — just pass a hostname and get back structured results:
 
-- **Endpoint**: `https://cloudflare-dns.com/dns-query`
-- **Features**: Privacy-focused, minimal logging, malware protection
-- **Use Case**: Privacy-conscious applications, consumer-facing services
-- **Advantages**: Fast global network, strong privacy policy, built-in security features
-- **Best For**: Privacy-sensitive applications, consumer products, GDPR-compliant services
+```typescript
+import {
+  resolve4, // A records (IPv4)
+  resolve6, // AAAA records (IPv6)
+  resolveMx, // MX records (mail servers)
+  resolveTxt, // TXT records (SPF, DKIM, verification)
+  resolveCname, // CNAME records (aliases)
+  resolveNs, // NS records (name servers)
+  resolveSoa, // SOA records (zone authority)
+  resolveSrv, // SRV records (service discovery)
+  resolvePtr, // PTR records (reverse DNS)
+  resolveCaa, // CAA records (certificate authority)
+  resolveNaptr, // NAPTR records
+  resolveTlsa, // TLSA records (DANE)
+  resolveAny, // ALL available records
+  reverse, // Reverse DNS lookup
+  resolve, // Generic resolve by record type
+} from "zynor";
+```
 
-### Quad9 DoH (DNS-over-HTTPS)
+Each function accepts an optional provider name as the last argument:
 
-Quad9's security-focused DNS service provides threat intelligence and malware blocking while maintaining user privacy.
+```typescript
+const ips = await resolve4("example.com", "google");
+const mx = await resolveMx("example.com", "cloudflare");
+const ns = await resolve("example.com", "NS");
+const nsViaGoogle = await resolve("example.com", "NS", "google");
+```
 
-- **Endpoint**: `https://dns.quad9.net/dns-query`
-- **Features**: Security-focused, threat blocking, privacy protection
-- **Use Case**: Security-sensitive applications, enterprise environments
-- **Advantages**: Malware blocking, threat intelligence, non-profit organization, no user tracking
-- **Best For**: Security-critical applications, enterprise networks, threat-aware environments
+Request TTL information for A and AAAA records:
 
-## ⚙️ Configuration
+```typescript
+const withTtl = await resolve4("example.com", { ttl: true });
+// => [{ address: '93.184.216.34', ttl: 300 }]
+```
 
-Zynor provides extensive configuration options to fine-tune DNS resolution behavior according to your application's specific requirements. Each DNS provider can be configured independently with custom concurrency limits, rate limiting, timeouts, and retry policies. The configuration system supports both static initialization and dynamic runtime updates.
+### Zynor Class
 
-### Basic Configuration Example
+The `Zynor` class gives full control over providers, concurrency, and caching:
 
 ```typescript
+import { Zynor } from "zynor";
+
 const dns = new Zynor({
   google: {
     enabled: true,
-    limit: { concurrency: 10, rps: 100 },
-    timeout: 5000,
-    retries: 3
+    limit: { concurrency: 10, interval: 1000, intervalCap: 500 },
   },
   cloudflare: {
     enabled: true,
-    limit: { concurrency: 5, rps: 50 }
+    limit: { concurrency: 10 },
   },
   quad9: { enabled: false },
-  native: { enabled: true }
+  native: { enabled: true },
+  cache: {
+    enabled: true,
+    maxSize: 100_000,
+    dnsTtl: 1_440_000,
+  },
 });
+
+const ips = await dns.resolve4("example.com");
+const mx = await dns.resolveMx("example.com", "google");
+const txt = await dns.resolveTxt("example.com", { timeout: 5000 });
 ```
 
-### Configuration Options
+### Supported Record Types
+
+| Record Type | Method           | Returns         | Description                                                        |
+| ----------- | ---------------- | --------------- | ------------------------------------------------------------------ |
+| **A**       | `resolve4()`     | `string[]`      | IPv4 addresses for a domain                                        |
+| **AAAA**    | `resolve6()`     | `string[]`      | IPv6 addresses for a domain                                        |
+| **MX**      | `resolveMx()`    | `MxRecord[]`    | Mail servers with priority, used to find where email is handled    |
+| **TXT**     | `resolveTxt()`   | `string[][]`    | Text records holding SPF rules, DKIM keys, and verification tokens |
+| **CNAME**   | `resolveCname()` | `string[]`      | Canonical name aliases showing what a hostname points to           |
+| **NS**      | `resolveNs()`    | `string[]`      | Authoritative name servers for a domain                            |
+| **SOA**     | `resolveSoa()`   | `SoaRecord`     | Zone serial number, refresh intervals, and admin contact           |
+| **SRV**     | `resolveSrv()`   | `SrvRecord[]`   | Service discovery records with priority, weight, and port          |
+| **PTR**     | `resolvePtr()`   | `string[]`      | Maps an IP address back to a hostname                              |
+| **CAA**     | `resolveCaa()`   | `CaaRecord[]`   | Which certificate authorities can issue certificates for a domain  |
+| **NAPTR**   | `resolveNaptr()` | `NaptrRecord[]` | Complex service resolution for ENUM and SIP routing                |
+| **TLSA**    | `resolveTlsa()`  | `TlsaRecord[]`  | DANE TLS certificate pinning                                       |
+| **ANY**     | `resolveAny()`   | `AnyRecord[]`   | All available record types in a single query                       |
 
-- **enabled**: Enable or disable the provider (boolean)
-- **limit.concurrency**: Maximum concurrent requests per provider (number)
-- **limit.rps**: Requests per second rate limit (number)
-- **timeout**: Request timeout in milliseconds (number)
-- **retries**: Number of retry attempts on failure (number)
-- **priority**: Provider selection priority (number, higher = preferred)
+```typescript
+const mx = await resolveMx("gmail.com");
+// => [
+//   { priority: 5, exchange: 'gmail-smtp-in.l.google.com' },
+//   { priority: 10, exchange: 'alt1.gmail-smtp-in.l.google.com' },
+// ]
+
+const soa = await resolveSoa("example.com");
+// => {
+//   nsname: 'ns1.example.com',
+//   hostmaster: 'admin.example.com',
+//   serial: 2024010101,
+//   refresh: 3600,
+//   retry: 900,
+//   expire: 604800,
+//   minttl: 86400
+// }
+
+const srv = await resolveSrv("_sip._tcp.example.com");
+// => [{ priority: 10, weight: 5, port: 5060, name: 'sip.example.com' }]
+
+const hosts = await reverse("8.8.8.8");
+// => ['dns.google']
+```
 
-### Dynamic Configuration Updates
+### Provider Selection
+
+When you don't specify which provider to use, zynor picks the best one for you automatically. It looks at how busy each provider's queue is and routes your request to the one with the most available capacity. This means that under heavy load, requests naturally spread across all your enabled providers rather than piling up on a single one — giving you faster response times and better reliability without any manual balancing on your part.
+
+If you need a specific provider for a particular query (for example, Quad9 for its built-in malware filtering, or native for internal DNS resolution), you can always override the automatic selection:
 
 ```typescript
-// Update configuration at runtime
-dns.setConfig('google', { enabled: false });
-dns.setConfigs({ cloudflare: { limit: { concurrency: 15 } } });
+const ips = await resolve4("example.com", "google");
+const mx = await dns.resolveMx("example.com", "cloudflare");
 ```
 
-## 📚 API Reference
+Four providers are included:
 
-The Zynor API is designed for simplicity and flexibility, offering both class-based and functional approaches to DNS resolution. All methods return strongly-typed promises and support optional provider selection, custom timeouts, and advanced configuration options.
+| Provider       | Protocol                     | Best For                                             |
+| -------------- | ---------------------------- | ---------------------------------------------------- |
+| **native**     | Node.js `dns/promises`       | Local/internal DNS, system DNS settings, development |
+| **google**     | DNS-over-HTTPS               | Production, global services, DNSSEC validation       |
+| **cloudflare** | DNS-over-HTTPS               | Privacy-sensitive apps, fast global resolution       |
+| **quad9**      | DNS-over-HTTPS (wire format) | Security-focused apps, built-in malware blocking     |
 
-### Zynor Class
+### AbortSignal and Timeout
 
-The Zynor class provides a comprehensive DNS resolution interface with full configuration control and advanced features like provider management, concurrency control, and runtime configuration updates.
+Every DNS method in zynor can be cancelled mid-flight or given a time limit. This is essential for production applications where you can't afford to wait forever on a DNS query that might be hanging due to network issues. The default timeout is 30 seconds, but you can set your own per-request timeout, pass in an `AbortSignal` for manual cancellation, or combine both — whichever fires first will cancel the operation and free up resources immediately.
 
 ```typescript
-const dns = new Zynor(config?: ZynorConfig);
+// Timeout after 5 seconds
+const ips = await resolve4("example.com", { timeout: 5000 });
+
+// Manual cancellation
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 3000);
+const mx = await resolveMx("example.com", { signal: controller.signal });
+
+// Both together -- whichever fires first cancels the operation
+const txt = await resolveTxt("example.com", {
+  signal: controller.signal,
+  timeout: 10000,
+});
+```
+
+Cancellation works across the entire operation: queue wait, network request, and response parsing.
+
+---
+
+## DNS Caching
 
-// Basic DNS resolution methods
-dns.resolve4(hostname: string): Promise<string[]>          // IPv4 addresses
-dns.resolve6(hostname: string): Promise<string[]>          // IPv6 addresses
-dns.resolveMx(hostname: string): Promise<MxRecord[]>       // Mail exchange records
-dns.resolveTxt(hostname: string): Promise<string[][]>      // Text records
-dns.resolveCname(hostname: string): Promise<string[]>      // Canonical name records
-dns.resolveNs(hostname: string): Promise<string[]>        // Name server records
-dns.resolveSoa(hostname: string): Promise<SoaRecord>       // Start of Authority
-dns.resolvePtr(ip: string): Promise<string[]>             // Reverse DNS lookup
-dns.resolveSrv(hostname: string): Promise<SrvRecord[]>     // Service records
-dns.resolveAny(hostname: string): Promise<AnyRecord[]>     // All available records
+### Request Deduplication
 
-// Configuration methods
-dns.setConfig(provider: string, config: ProviderConfig): void
-dns.setConfigs(configs: Partial<ZynorConfig>): void
+If your application fires off the same DNS query from multiple places at the same time — say, ten different parts of your code all resolve `example.com` within the same moment — zynor recognizes that these are duplicate requests and only sends a single query to the DNS provider. Every caller that asked for the same record receives the same result as soon as it comes back. This eliminates redundant network calls, reduces your DNS provider usage, and speeds up your application when multiple components depend on the same domain.
 
-// Email validation
-dns.emailValidator: EmailValidator
+```typescript
+// Only ONE DNS query is made, all three get the same result
+const [a, b, c] = await Promise.all([
+  resolve4("example.com"),
+  resolve4("example.com"),
+  resolve4("example.com"),
+]);
 ```
 
-### Standalone Functions
+Results are then stored in an LRU cache so subsequent requests are served instantly without any network call.
 
-Standalone functions provide a lightweight alternative for simple DNS queries without the need for class instantiation. These functions use sensible defaults and automatic provider selection.
+### LruCache
+
+Zynor includes a general-purpose Least Recently Used (LRU) cache that you can use in your own application code — it's the same cache that powers zynor's internal DNS caching. An LRU cache automatically evicts the oldest unused entries when it reaches its maximum size, and each entry can have a time-to-live (TTL) so stale data expires on its own. This is useful for caching API responses, database queries, computed results, or anything else you want to keep in memory temporarily without worrying about unbounded growth:
 
 ```typescript
-import { resolve4, resolveMx, resolveAny } from 'zynor';
+import { LruCache } from "zynor";
+
+const cache = new LruCache<string>(500); // max 500 entries
+
+cache.set("key", "value", 60_000); // expires in 60 seconds
+cache.get("key"); // => "value"
+cache.peek("key"); // => "value" (without affecting eviction order)
+cache.has("key"); // => true
+cache.ttl("key"); // => remaining ms until expiry
+cache.delete("key"); // => true
+cache.size; // => 0
+cache.prune(); // remove all expired entries, returns count
+cache.clear(); // remove everything
+
+// Iterate non-expired entries
+for (const key of cache.keys()) {
+  /* ... */
+}
+for (const value of cache.values()) {
+  /* ... */
+}
+for (const [key, value] of cache.entries()) {
+  /* ... */
+}
+```
+
+---
 
-// Use directly without creating a class instance
-const addresses = await resolve4('example.com');           // Quick IPv4 resolution
-const mxRecords = await resolveMx('example.com');          // Mail server lookup
-const anyRecords = await resolveAny('example.com');        // Comprehensive DNS query
+## Provider Configuration
 
-// With optional provider specification
-const googleResult = await resolve4('example.com', undefined, 'google');
-const cloudflareResult = await resolveMx('example.com', undefined, 'cloudflare');
+### Concurrency and Rate Limiting
+
+Each DNS provider runs its own independent request queue, which means you have fine-grained control over how aggressively your application talks to each provider. You can set how many requests are allowed to be in flight at the same time (`concurrency`), define a rate-limit window (`interval` in milliseconds), and cap how many requests can be sent within that window (`intervalCap`). This prevents you from being throttled or banned by DNS providers and lets you tune performance based on your use case — high throughput for batch processing, or conservative limits for shared environments:
+
+```typescript
+const dns = new Zynor({
+  google: {
+    enabled: true,
+    limit: {
+      concurrency: 10, // max 10 requests in flight at once
+      interval: 1000, // rate limit window in ms
+      intervalCap: 500, // max requests per window
+      carryoverConcurrencyCount: true,
+    },
+  },
+  cloudflare: {
+    enabled: true,
+    limit: { concurrency: 5 },
+  },
+  quad9: { enabled: false },
+  native: {
+    enabled: true,
+    limit: { concurrency: 10, interval: 1000, intervalCap: 750 },
+  },
+});
 ```
 
-### Method Parameters
+| Option                            | Type      | Description                                     |
+| --------------------------------- | --------- | ----------------------------------------------- |
+| `enabled`                         | `boolean` | Turn the provider on or off. Default: `true`.   |
+| `limit.concurrency`               | `number`  | Maximum requests running simultaneously.        |
+| `limit.interval`                  | `number`  | Time window in ms for rate limiting.            |
+| `limit.intervalCap`               | `number`  | Maximum requests allowed per interval window.   |
+| `limit.carryoverConcurrencyCount` | `boolean` | Carry over concurrency count between intervals. |
 
-Most DNS resolution methods accept the following parameters:
+### Runtime Configuration Updates
 
-- **hostname/ip**: The domain name or IP address to resolve (string)
-- **options**: Optional configuration object (varies by method)
-- **provider**: Optional provider name for specific provider usage (string)
+You can reconfigure providers on the fly without having to tear down and recreate your `Zynor` instance. This is useful when you need to react to changing conditions — for example, disabling a provider that's returning errors, increasing concurrency during off-peak hours, or enabling a provider that was previously turned off. All in-flight requests continue with their original settings; only new requests pick up the changes:
 
-### Return Types
+```typescript
+dns.setConfig("google", { enabled: false });
+dns.setConfig("cloudflare", { limit: { concurrency: 20 } });
 
-All methods return strongly-typed promises with comprehensive type definitions for maximum TypeScript compatibility and IntelliSense support.
+dns.setConfigs({
+  google: { enabled: true, limit: { concurrency: 15 } },
+  cloudflare: { enabled: false },
+});
+```
 
+---
 
+## Email Validation
 
-### Email Validation
+A full email intelligence engine that validates addresses, identifies the hosting provider, detects disposable and role-based emails, and resolves webmail URLs.
 
-The Email Validation system provides comprehensive email address validation, domain analysis, and provider detection. It combines syntax validation, DNS lookups, and an extensive database of email providers to deliver accurate validation results with detailed metadata about the email address and its hosting provider.
+### Basic Validation
 
-#### `EmailValidator` Class
+Validates an email address in a single call — checking syntax, screening for disposable domains, detecting role-based prefixes like `admin@` or `support@`, and identifying the email provider by domain or MX record lookup. Returns the provider name, free/paid status, role flag, and webmail URL when available.
 
-The EmailValidator class is the core component for email validation operations. It provides intelligent email analysis by checking syntax, validating domains through DNS resolution, detecting email providers, and identifying role-based addresses. The validator supports both basic and deep validation modes to accommodate different use cases and performance requirements.
+```typescript
+import { Zynor } from "zynor";
 
-##### `validate(email: string, deep?: boolean): Promise<EmailResponse>`
+const validator = Zynor.emailValidator;
 
-Performs comprehensive email validation and analysis, returning detailed information about the email address including provider detection, webmail availability, and role-based email identification.
+const result = await validator.validate("user@gmail.com");
+
+if (result.success) {
+  console.log(result.data.provider); // "Gmail"
+  console.log(result.data.email); // "user@gmail.com"
+  console.log(result.data.isFree); // true
+  console.log(result.data.role); // false
+  console.log(result.data.webmail); // "https://mail.google.com"
+} else {
+  console.log(result.type); // "Syntax" | "Invalid" | "Rejected" | "Disposable" | "Error"
+  console.log(result.email); // the email that failed
+}
+```
 
-**Parameters:**
-- `email`: Email address to validate (string)
-- `deep` (optional): Enable deep validation with additional DNS lookups and extended checks (default: false)
+Validation checks syntax, inappropriate terms, rejected patterns (noreply, marketing senders, platform notifications), disposable domains, and then identifies the email provider through domain matching and MX record analysis.
 
-**Returns:** EmailResponse object with one of the following structures:
+**Success response:**
 
-**Success Response Structure:**
 ```typescript
 {
   success: true,
   data: {
-    provider: string,     // Email provider name (e.g., "Gmail", "Outlook")
-    email: string,        // Normalized email address
-    isFree: boolean,      // Whether it's a free email provider domain
-    role: boolean,        // Whether it's a role-based email (admin, support, etc.)
-    webmail?: string      // Webmail URL if available
+    provider: string,    // "Gmail", "Office 365", "Zoho", etc.
+    email: string,       // normalized (lowercased) email
+    isFree: boolean,     // true for free providers (Gmail, Yahoo, etc.)
+    role: boolean,       // true for admin@, support@, info@, etc.
+    webmail?: string,    // webmail URL if known
   }
 }
 ```
 
-**Error Response Structure:**
+**Error response:**
+
 ```typescript
 {
   success: false,
-  type: 'Syntax' | 'Rejected' | 'Invalid' | 'Disposable' | 'Error',
+  type: "Syntax" | "Rejected" | "Invalid" | "Disposable" | "Error",
   email: string,
-  role: boolean,        // Whether it's a role-based email
-  message?: string      // Detailed error message (only present for 'Error' type)
+  role: boolean,
+  message?: string,  // only for "Error" type
 }
 ```
 
-#### Basic Email Validation Examples
+### Deep Validation
 
-**Simple Validation:**
-```typescript
-import { Zynor } from 'zynor';
+When basic validation can't identify the provider, deep validation goes further — probing the domain's web presence and querying IP intelligence services to classify the hosting provider. The deep phase is time-capped (default 3 seconds) and results are cached, so repeated lookups are instant.
 
-const validator = Zynor.emailValidator;
+```typescript
+const validator = Zynor.createEmailValidator({
+  options: {
+    enableDeepValidation: true,
+    deepValidationOptions: {
+      maxTimeout: 3000, // max 3 seconds for the deep validation phase
+      http: { timeout: 2500, maxRetry: 0 },
+    },
+    ipResolver: {
+      ipApi: true,
+      findip: { enabled: true, apiKey: ["your-api-key"] },
+    },
+  },
+});
 
-// Basic email validation
-const result = await validator.validate('user@gmail.com');
-if (result.success) {
-  console.log('✅ Valid email');
-  console.log('Provider:', result.data.provider);     // "Gmail"
-  console.log('Webmail:', result.data.webmail);       // "https://mail.google.com"
-  console.log('Role email:', result.data.role);       // false
-} else {
-  console.log('❌ Invalid email:', result.type);
-}
+const result = await validator.validate("employee@obscure-company.com", true);
 ```
 
-**Deep Validation Mode:**
+Deep validation with abort support:
+
 ```typescript
-// Enable deep validation for thorough analysis
-const deepResult = await validator.validate('admin@company.com', true);
-if (deepResult.success) {
-  console.log('Provider:', deepResult.data.provider);
-  console.log('Is role-based:', deepResult.data.role);  // likely true for "admin"
-}
+const result = await validator.validate("user@company.com", {
+  deep: true,
+  timeout: 5000,
+  signal: controller.signal,
+});
 ```
 
-#### Provider Detection Examples
+The deep phase is always capped by `maxTimeout` (default 3s) so it never blocks indefinitely.
 
-**Major Email Providers:**
-```typescript
-// Gmail detection
-const gmailResult = await validator.validate('john.doe@gmail.com');
-console.log(gmailResult.data?.provider);  // "Gmail"
+### Bulk Validation
 
-// Outlook detection
-const outlookResult = await validator.validate('jane@outlook.com');
-console.log(outlookResult.data?.provider);  // "Outlook"
+Validate hundreds or thousands of email addresses concurrently with configurable parallelism. Results come back in the same order as the input array, making it easy to map results back to your original data:
 
-// Yahoo detection
-const yahooResult = await validator.validate('user@yahoo.com');
-console.log(yahooResult.data?.provider);  // "Yahoo"
+```typescript
+const results = await Zynor.validateBulk(
+  ["user@gmail.com", "admin@company.com", "test@mailinator.com"],
+  {
+    concurrency: 10,
+    deep: false,
+    timeout: 30000,
+  },
+);
 
-// Corporate email detection
-const corpResult = await validator.validate('employee@microsoft.com');
-console.log(corpResult.data?.provider);  // "Microsoft"
+// results[0] => { success: true, data: { provider: "Gmail", ... } }
+// results[2] => { success: false, type: "Disposable", ... }
 ```
 
-#### Role-Based Email Detection
+Results are returned in the same order as the input array. Concurrency defaults to the sum of all enabled provider concurrency limits.
 
-**Identifying Role-Based Addresses:**
-```typescript
-// Common role-based emails
-const roleEmails = [
-  'admin@company.com',
-  'support@service.com',
-  'info@business.org',
-  'sales@enterprise.net',
-  'noreply@platform.io'
-];
-
-for (const email of roleEmails) {
-  const result = await validator.validate(email);
-  if (result.success && result.data.role) {
-    console.log(`${email} is a role-based email`);
-  }
-}
-```
+### Provider Detection
 
-#### Webmail Detection and Access
+Zynor identifies 60+ email providers by direct domain matching and 100+ by analyzing MX record patterns. Known domains like `gmail.com` or `outlook.com` are detected instantly without any DNS query. For custom domains (like `user@company.com`), zynor looks up the domain's MX records to figure out which provider handles their email:
 
-**Webmail URL Extraction:**
 ```typescript
-// Get webmail URLs for popular providers
-const webmailEmails = [
-  'user@gmail.com',      // https://mail.google.com
-  'user@outlook.com',    // https://outlook.live.com
-  'user@yahoo.com',      // https://mail.yahoo.com
-  'user@icloud.com'      // https://www.icloud.com/mail
-];
-
-for (const email of webmailEmails) {
-  const result = await validator.validate(email);
-  if (result.success && result.data.webmail) {
-    console.log(`${email} -> ${result.data.webmail}`);
-  }
-}
+const validator = Zynor.emailValidator;
+
+// Instant detection by domain (no DNS needed)
+await validator.validate("user@gmail.com"); // provider: "Gmail"
+await validator.validate("user@outlook.com"); // provider: "Outlook"
+await validator.validate("user@protonmail.com"); // provider: "ProtonMail"
+await validator.validate("user@qq.com"); // provider: "QQ"
+await validator.validate("user@mail.ru"); // provider: "Mail.ru"
+await validator.validate("user@icloud.com"); // provider: "iCloud"
+await validator.validate("user@zoho.com"); // provider: "Zoho"
+await validator.validate("user@fastmail.com"); // provider: "Fastmail"
+
+// Detection by MX record (requires one DNS lookup)
+await validator.validate("user@company.com");
+// MX points to Google => provider: "Gmail"
+
+await validator.validate("user@enterprise.org");
+// MX points to Outlook => provider: "Office 365"
+
+await validator.validate("user@startup.io");
+// MX points to Amazon SES => provider: "Amazon"
 ```
 
-#### Batch Email Validation
+Detected providers include Gmail, Outlook, Office 365, Yahoo, Turbify, AOL, iCloud, ProtonMail, Zoho, Mail.ru, Yandex, GMX, Web.de, Mail.com, Fastmail, AT&T, Comcast, QQ, 163, Naver, Daum, Rackspace, Mimecast, Godaddy, Namecheap, SendGrid, Mailgun, Postmark, Amazon, Elastic Email, Zendesk, Intermedia, Mailjet, Front, and many more.
+
+### Disposable Email Detection
+
+Detects disposable (temporary) email domains and automated/marketing sender patterns:
 
-**Validating Multiple Emails:**
 ```typescript
-async function validateEmailBatch(emails: string[]) {
-  const results = await Promise.allSettled(
-    emails.map(email => validator.validate(email))
-  );
-  
-  return emails.map((email, index) => {
-    const result = results[index];
-    if (result.status === 'fulfilled' && result.value.success) {
-      return {
-        email,
-        valid: true,
-        provider: result.value.data.provider,
-        role: result.value.data.role,
-        webmail: result.value.data.webmail
-      };
-    } else {
-      return {
-        email,
-        valid: false,
-        error: result.status === 'fulfilled' ? result.value.type : 'validation_failed'
-      };
-    }
-  });
-}
+const validator = Zynor.emailValidator;
 
-// Usage example
-const emailList = [
-  'valid@gmail.com',
-  'invalid.email',
-  'admin@company.com',
-  'user@nonexistent-domain.xyz'
-];
+validator.isDisposable("test@mailinator.com"); // true
+validator.isDisposable("user@guerrillamail.com"); // true
+validator.isDisposable("user@gmail.com"); // false
 
-const batchResults = await validateEmailBatch(emailList);
-console.log('Batch validation results:', batchResults);
+// Also caught during validation
+const result = await validator.validate("test@tempmail.com");
+// => { success: false, type: "Disposable", ... }
 ```
 
-#### Error Handling and Response Types
+Additionally catches automated senders (noreply@, notifications@), marketing platforms (@mailchimp.com, @sendgrid.net, @hubspot.com), and platform notifications (GitHub, Amazon, Facebook, LinkedIn).
 
-**Comprehensive Error Handling:**
-```typescript
-async function handleEmailValidation(email: string) {
-  try {
-    const result = await validator.validate(email);
-    
-    if (result.success) {
-      return {
-        status: 'valid',
-        data: result.data
-      };
-    } else {
-      // Handle different error types
-      switch (result.type) {
-        case 'Syntax':
-          return { status: 'syntax_error', message: 'Invalid email format' };
-        case 'Invalid':
-          return { status: 'invalid_domain', message: 'Domain does not exist' };
-        case 'Rejected':
-          return { status: 'rejected', message: 'Email rejected by provider' };
-        case 'Disposable':
-          return { status: 'disposable', message: 'Disposable email address' };
-        case 'Error':
-          return { status: 'validation_error', message: result.message };
-        default:
-          return { status: 'unknown_error', message: 'Validation failed' };
-      }
-    }
-  } catch (error) {
-    return {
-      status: 'exception',
-      message: error instanceof Error ? error.message : 'Unexpected error'
-    };
-  }
-}
-
-// Usage
-const validationResult = await handleEmailValidation('test@example.com');
-console.log(validationResult);
-```
+### Role-Based Email Detection
 
-#### Advanced Use Cases
+Detects 250+ role-based prefixes -- addresses that represent a function rather than a person:
 
-**Email Domain Analysis:**
 ```typescript
-async function analyzeEmailDomain(email: string) {
-  const result = await validator.validate(email, true); // Deep validation
-  
-  if (result.success) {
-    const domain = email.split('@')[1];
-    return {
-      email: result.data.email,
-      domain,
-      provider: result.data.provider,
-      hasWebmail: !!result.data.webmail,
-      webmailUrl: result.data.webmail,
-      isRoleBased: result.data.role,
-      isPersonal: ['Gmail', 'Yahoo', 'Outlook', 'iCloud'].includes(result.data.provider),
-      isCorporate: !['Gmail', 'Yahoo', 'Outlook', 'iCloud'].includes(result.data.provider)
-    };
-  } else {
-    return {
-      email,
-      valid: false,
-      errorType: result.type,
-      errorMessage: result.message
-    };
-  }
-}
+const result = await validator.validate("admin@company.com");
+console.log(result.success && result.data.role); // true
 
-const analysis = await analyzeEmailDomain('ceo@apple.com');
-console.log('Email analysis:', analysis);
+const result2 = await validator.validate("john.doe@company.com");
+console.log(result2.success && result2.data.role); // false
 ```
 
-#### Additional EmailValidator Methods
+Recognized prefixes include `admin`, `support`, `info`, `sales`, `billing`, `help`, `contact`, `hr`, `legal`, `marketing`, `security`, `postmaster`, `webmaster`, `noreply`, `abuse`, `careers`, `ceo`, `press`, `media`, `feedback`, `office`, `accounting`, `engineering`, `operations`, and many more.
 
-The EmailValidator class provides several utility methods for email validation and manipulation:
+### Free Domain Detection
 
-##### `isEmail(email: string): boolean`
+Check whether an email or domain belongs to a free email provider:
 
-Performs advanced email format validation with structural constraints.
-
-**Validation Rules:**
-- Maximum 35 characters for the local part
-- Maximum 3 hyphens in the local part
-- Maximum 3 dots in the local part
-- Maximum 3 dots in the domain part
-- Maximum 2 hyphens in the domain part
-- Maximum 55 total characters in the email address
-- Local part must be at least 2 characters
-- Domain part must be at least 5 characters
-
-**Example:**
 ```typescript
-const validator = EmailValidator.create();
+validator.isFreeDomain("user@gmail.com"); // true
+validator.isFreeDomain("yahoo.com"); // true
+validator.isFreeDomain("user@company.com"); // false
 
-validator.isEmail("john.doe@example.com");  // true
-validator.isEmail("x@y.com");               // false (domain too short)
-validator.isEmail("toolong@d.c");           // false
+// Also in validation results
+const result = await validator.validate("user@gmail.com");
+console.log(result.success && result.data.isFree); // true
 ```
 
-##### `isFreeDomain(email_or_domain: string): boolean`
+### Webmail URL Lookup
 
-Checks if an email address or domain belongs to a free email provider (Gmail, Yahoo, Outlook, etc.).
+Resolve webmail login URLs for 500+ domains including regional variants:
 
-**Example:**
 ```typescript
-validator.isFreeDomain('person@yahoo.com');     // true
-validator.isFreeDomain('gmail.com');            // true
-validator.isFreeDomain('user@company.org');     // false
-```
+const validator = Zynor.emailValidator;
 
-##### `isDisposable(email: string): boolean`
+validator.getProviderWebmailUrl("Gmail");
+// => "https://mail.google.com"
 
-Checks if an email address is from a known disposable/temporary email provider.
+validator.getProviderWebmailUrl("outlook.com");
+// => "https://outlook.live.com/mail/"
 
-**Example:**
-```typescript
-validator.isDisposable('test@mailinator.com'); // true
-validator.isDisposable('john.doe@gmail.com');  // false
-```
+validator.getProviderWebmailUrl("user@yahoo.fr");
+// => "https://fr.mail.yahoo.com/"
 
-##### `isJson(input: string): string[] | null`
+validator.getProviderWebmailUrl("Gmail", "google.com");
+// => "https://mail.google.com"
 
-Validates if a string is a JSON array of valid email addresses.
+validator.getProviderWebmailUrl("unknown-provider.com");
+// => null
+```
 
-**Returns:** Array of valid emails if successful, `null` otherwise.
+Regional examples: `yahoo.fr` resolves to `https://fr.mail.yahoo.com/`, `hotmail.de` to `https://outlook.live.com/mail/`, `gmx.at` to `https://www.gmx.at/mail/`, `att.net` to `https://currently.att.yahoo.com/`.
 
-**Example:**
-```typescript
-validator.isJson('["hello@site.com", "test@a.io"]');
-// Returns: ["hello@site.com", "test@a.io"]
+Also included in validation results:
 
-validator.isJson('["foo", 1, null]');  // Returns: null
-validator.isJson('not json');           // Returns: null
+```typescript
+const result = await validator.validate("user@gmail.com");
+console.log(result.success && result.data.webmail);
+// => "https://mail.google.com"
 ```
 
-##### `extractEmails(input: string[]): string[]`
+### Email Extraction
 
-Extracts valid email addresses from various input formats including:
-- Plain email addresses
-- Comma-separated values
-- URL-encoded strings (automatically decoded)
-- JSON arrays
+Extract valid emails from mixed input formats:
 
-**Example:**
 ```typescript
-// Single email
+const validator = Zynor.emailValidator;
+
+// Plain emails
 validator.extractEmails(["user@example.com"]);
-// Returns: ["user@example.com"]
+// => ["user@example.com"]
 
-// Comma-separated emails
-validator.extractEmails(["user1@example.com,user2@example.com"]);
-// Returns: ["user1@example.com", "user2@example.com"]
+// Comma-separated
+validator.extractEmails(["a@test.com,b@test.com"]);
+// => ["a@test.com", "b@test.com"]
 
 // URL-encoded
-validator.extractEmails(["user%40example.com,test%40domain.com"]);
-// Returns: ["user@example.com", "test@domain.com"]
+validator.extractEmails(["user%40example.com"]);
+// => ["user@example.com"]
 
-// JSON array
-validator.extractEmails(['["email1@test.com", "email2@test.com"]']);
-// Returns: ["email1@test.com", "email2@test.com"]
+// JSON arrays
+validator.extractEmails(['["a@test.com", "b@test.com"]']);
+// => ["a@test.com", "b@test.com"]
 
 // Mixed formats
 validator.extractEmails([
-  "user@example.com",
-  "test@domain.com,admin@site.com",
-  '["json@email.com"]'
+  "one@test.com",
+  "two@test.com,three@test.com",
+  '["four@test.com"]',
 ]);
-// Returns: ["user@example.com", "test@domain.com", "admin@site.com", "json@email.com"]
+// => ["one@test.com", "two@test.com", "three@test.com", "four@test.com"]
 ```
 
-##### `getProviderWebmailUrl(provider: ProviderName): string | null`
-##### `getProviderWebmailUrl(provider: ProviderName, domainOrEmail: string): string | null`
-##### `getProviderWebmailUrl(domainOrEmail: string): string | null`
-
-Retrieves the webmail URL for a given email provider. Supports multiple overloaded signatures for flexibility.
-
-**Parameters:**
-- `provider` - Provider name (e.g., "Gmail", "Outlook") or domain/email
-- `domainOrEmail` (optional) - Domain name or full email address
-
-**Returns:** Webmail URL string if found, `null` otherwise.
+Utility methods:
 
-**Example:**
 ```typescript
-// Using provider name
-validator.getProviderWebmailUrl('Gmail');
-// Returns: "https://mail.google.com"
+validator.isEmail("john.doe@example.com"); // true
+validator.isEmail("x@y.co"); // false
 
-// Using domain
-validator.getProviderWebmailUrl('outlook.com');
-// Returns: "https://outlook.live.com"
+validator.isJson('["a@test.com", "b@test.com"]');
+// => ["a@test.com", "b@test.com"]
 
-// Using email address
-validator.getProviderWebmailUrl('user@yahoo.com');
-// Returns: "https://mail.yahoo.com"
-
-// Using provider name with domain
-validator.getProviderWebmailUrl('Gmail', 'google.com');
-// Returns: "https://mail.google.com"
-
-// Unknown provider
-validator.getProviderWebmailUrl('unknown-provider.com');
-// Returns: null
+validator.isJson("not json");
+// => null
 ```
 
-## 🗂️ DNS Record Types
+### Persistent Caching
 
-Zynor supports all standard DNS record types with comprehensive parsing and type-safe return values. Each record type is optimized for specific use cases, from basic domain resolution to advanced service discovery and email routing. The library automatically handles record parsing and provides structured data objects for easy consumption.
+Validation results are automatically cached to disk and survive process restarts:
 
-| Record Type | Description | Use Cases | Return Type |
-|-------------|-------------|-----------|-------------|
-| **A** | IPv4 address records | Web hosting, basic domain resolution | `string[]` |
-| **AAAA** | IPv6 address records | Modern networking, dual-stack configurations | `string[]` |
-| **MX** | Mail exchange records | Email routing, mail server discovery | `MxRecord[]` |
-| **TXT** | Text records | Domain verification, SPF, DKIM, configuration | `string[][]` |
-| **CNAME** | Canonical name records | Domain aliases, CDN configuration | `string[]` |
-| **NS** | Name server records | DNS delegation, authoritative servers | `string[]` |
-| **SOA** | Start of Authority | Zone information, DNS administration | `SoaRecord` |
-| **SRV** | Service records | Service discovery, load balancing | `SrvRecord[]` |
-| **PTR** | Pointer records (reverse DNS) | IP to domain mapping, security verification | `string[]` |
-| **CAA** | Certificate Authority Authorization | SSL certificate validation | `CaaRecord[]` |
-| **NAPTR** | Name Authority Pointer | Complex service resolution | `NaptrRecord[]` |
-| **TLSA** | Transport Layer Security Authentication | Certificate pinning, security | `TlsaRecord[]` |
-| **ANY** | All available records | Comprehensive domain analysis | `AnyRecord[]` |
+- Results are cached at the domain level so different emails at the same domain share one entry.
+- Entries expire after 48 hours.
+- If a domain was cached as "Unknown" from basic validation, requesting deep validation bypasses the cache and performs a fresh lookup.
+- Falls back to in-memory only if the disk cache directory is not writable.
 
-### Record Type Examples
+---
 
-```typescript
-// A records - IPv4 addresses
-const ipv4 = await resolve4('example.com');
-// Returns: ['93.184.216.34']
+## Error Handling
 
-// MX records - Mail servers with priority
-const mailServers = await resolveMx('example.com');
-// Returns: [{ priority: 10, exchange: 'mail.example.com' }]
+Specific error classes for each failure mode:
 
-// TXT records - Text data (SPF, DKIM, etc.)
-const txtRecords = await resolveTxt('example.com');
-// Returns: [['v=spf1 include:_spf.example.com ~all']]
+```typescript
+import {
+  InvalidHostnameError,
+  NoEnabledProvidersError,
+  ProviderNotEnabledError,
+  InvalidProviderError,
+} from "zynor";
+
+try {
+  await resolve4("");
+} catch (err) {
+  if (err instanceof InvalidHostnameError) {
+    // empty or invalid hostname
+  }
+}
 
-// SRV records - Service discovery
-const services = await resolveSrv('_sip._tcp.example.com');
-// Returns: [{ priority: 10, weight: 5, port: 5060, name: 'sip.example.com' }]
+try {
+  await resolve4("example.com", "google");
+} catch (err) {
+  if (err instanceof ProviderNotEnabledError) {
+    // provider is disabled
+  }
+}
 ```
 
-
-
-## 🔷 TypeScript Support
-
-Zynor is built with TypeScript from the ground up, providing comprehensive type definitions, full IntelliSense support, and compile-time type checking. The library exports all necessary types and interfaces, ensuring type safety across your entire DNS resolution workflow and eliminating runtime type errors.
-
-### Complete Type Safety
+DNS errors are returned as Node.js-compatible error objects with `code`, `errno`, `syscall`, and `hostname`:
 
 ```typescript
-import { Zynor, MxRecord, SrvRecord, ProviderName } from 'zynor';
+try {
+  await resolve4("this-domain-does-not-exist.invalid");
+} catch (err) {
+  err.code; // "ENOTFOUND"
+  err.syscall; // "queryA"
+  err.hostname; // "this-domain-does-not-exist.invalid"
+}
+```
 
-// Strongly typed results with full IntelliSense
-const mxRecords: MxRecord[] = await resolveMx('example.com');
-const srvRecords: SrvRecord[] = await resolveSrv('_sip._tcp.example.com');
+---
 
-// Type-safe provider names prevent typos
-const provider: ProviderName = 'google';
-const addresses = await resolve4('example.com', undefined, provider);
-```
+## TypeScript Support
 
-### Available Type Exports
+Written in TypeScript with every type exported:
 
 ```typescript
-// Core types
 import {
-  Zynor,                    // Main DNS class
-  ProviderName,             // 'google' | 'cloudflare' | 'quad9' | 'native'
-  ZynorConfig,                 // Configuration interface
-  ProviderConfig,           // Individual provider configuration
-  
-  // DNS record types
-  MxRecord,                 // Mail exchange record
-  SrvRecord,                // Service record
-  SoaRecord,                // Start of Authority record
-  CaaRecord,                // Certificate Authority Authorization
-  NaptrRecord,              // Name Authority Pointer
-  TlsaRecord,               // Transport Layer Security Authentication
-  AnyRecord,                // Union of all record types
-  
-  // Email validation types
-  EmailValidator,           // Email validation class
-  EmailResponse,            // Validation response type
-  EmailData,                // Successful validation data
-  EmailError                // Validation error type
-} from 'zynor';
-```
-
-### Generic Type Support
-
-```typescript
-// Generic functions with type inference
-const resolveWithType = async <T>(hostname: string, type: string): Promise<T> => {
-  // Type-safe resolution with custom return types
-  return await dns.resolveAny(hostname) as T;
-};
-
-// Usage with automatic type inference
-const mxRecords = await resolveWithType<MxRecord[]>('example.com', 'MX');
+  Zynor,
+  ZynorConfig,
+  ProviderConfig,
+  ProviderName,
+  RecordType,
+  AbortOptions,
+  MxRecord,
+  SoaRecord,
+  SrvRecord,
+  CaaRecord,
+  NaptrRecord,
+  TlsaRecord,
+  AnyRecord,
+  RecordWithTtl,
+  ResolveOptions,
+  ResolveWithTtlOptions,
+  LruCache,
+  CacheConfig,
+  EmailValidator,
+  EmailResponse,
+  ValidationConfig,
+  NoEnabledProvidersError,
+  InvalidHostnameError,
+  ProviderNotEnabledError,
+  InvalidProviderError,
+} from "zynor";
 ```
 
+Full overload signatures with correct return types:
 
-
-
-
-## 📄 License
-
-MIT License - see the [LICENSE](LICENSE) file for details.
+```typescript
+const strings: string[] = await resolve4("example.com");
+const withTtl: RecordWithTtl[] = await resolve4("example.com", { ttl: true });
+const mx: MxRecord[] = await resolveMx("example.com");
+const soa: SoaRecord = await resolveSoa("example.com");
+```
 
 ---
-
-**Made with ❤️ by [Yuniq Solutions Tech](https://yuniq.solutions)**
-
-For more information, visit our [GitHub repository](https://github.com/yuniqsolutions/zynor) or check out our [documentation](https://github.com/yuniqsolutions/zynor#readme).