yq-dns 1.0.1 → 1.0.2

package/README.md

@@ -12,37 +12,18 @@ A comprehensive, promise-based DNS resolver library that aggregates multiple DNS
 - [Features](#-features)
 - [Installation](#-installation)
 - [Quick Start](#-quick-start)
-  - [ESM (ES Modules)](#esm-es-modules)
-  - [CommonJS](#commonjs)
 - [DNS Providers](#-dns-providers)
 - [Configuration](#-configuration)
-  - [Provider Configuration](#provider-configuration)
-  - [Global Configuration](#global-configuration)
-  - [Default Settings](#default-settings)
 - [API Reference](#-api-reference)
-  - [YqDns Class](#yqdns-class)
-  - [Standalone Functions](#standalone-functions)
-  - [DNS Resolution Methods](#dns-resolution-methods)
-  - [Email Validation](#email-validation)
 - [DNS Record Types](#-dns-record-types)
-- [Advanced Usage](#-advanced-usage)
-  - [Rate Limiting](#rate-limiting)
-  - [Provider Selection](#provider-selection)
-  - [Error Handling](#error-handling)
-  - [Concurrency Control](#concurrency-control)
-- [Email Validation System](#-email-validation-system)
-  - [Domain Validation](#domain-validation)
-  - [Webmail Detection](#webmail-detection)
-  - [Provider Recognition](#provider-recognition)
+- [Email Validation](#email-validation)
 - [TypeScript Support](#-typescript-support)
-- [Performance](#-performance)
-- [Examples](#-examples)
-- [Troubleshooting](#-troubleshooting)
-- [Contributing](#-contributing)
 - [License](#-license)
 
 ## 🚀 Features
 
+YQ-DNS 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
@@ -58,21 +39,35 @@ A comprehensive, promise-based DNS resolver library that aggregates multiple DNS
 
 ## 📦 Installation
 
+YQ-DNS 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.
+
+**Using npm:**
 ```bash
 npm install yq-dns
 ```
 
+**Using Yarn:**
 ```bash
 yarn add yq-dns
 ```
 
+**Using pnpm:**
 ```bash
 pnpm add yq-dns
 ```
 
+**Requirements:**
+- Node.js 18.0.0 or higher
+- TypeScript 4.5+ (for TypeScript projects)
+- Modern JavaScript environment with Promise support
+
 ## 🚀 Quick Start
 
-### ESM (ES Modules)
+Get started with YQ-DNS in seconds! The library offers two main approaches: standalone functions for simple DNS queries and the YqDns class for advanced configuration and control. Both approaches provide the same powerful DNS resolution capabilities with automatic provider selection and intelligent error handling.
+
+### Standalone Functions (Recommended for Simple Use Cases)
+
+Standalone functions provide the quickest way to perform DNS lookups with sensible defaults and automatic provider selection:
 
 ```typescript
 // Using standalone functions (recommended for simple use cases)
@@ -88,932 +83,532 @@ console.log(mxRecords); // [{ priority: 10, exchange: 'mail.example.com' }]
 
 // Resolve with specific provider
 const googleResult = await resolve4('example.com', undefined, 'google');
-
-// Resolve with TTL information
-const withTtl = await resolve4('example.com', { ttl: true });
-console.log(withTtl); // [{ address: '93.184.216.34', ttl: 300 }]
 ```
 
+### YqDns Class (For Advanced Configuration)
+
+The YqDns class provides fine-grained control over DNS providers, concurrency limits, timeouts, and retry behavior:
+
 ```typescript
-// Using YqDns class (recommended for advanced configuration)
+// Using YqDns class (for advanced configuration)
 import { YqDns } from 'yq-dns';
 
 const dns = new YqDns({
   google: { enabled: true, limit: { concurrency: 10 } },
-  cloudflare: { enabled: true, limit: { concurrency: 5 } },
-  quad9: { enabled: false },
-  native: { enabled: true }
+  cloudflare: { enabled: true, limit: { concurrency: 5 } }
 });
 
 const addresses = await dns.resolve4('example.com');
-const mxRecords = await dns.resolveMx('example.com');
 ```
 
-### CommonJS
+### CommonJS Support
 
-```javascript
-// Using require (Node.js with CommonJS)
-const { resolve4, resolveMx, YqDns } = require('yq-dns');
-
-// Standalone functions
-resolve4('example.com').then(addresses => {
-  console.log(addresses);
-});
+YQ-DNS fully supports CommonJS environments for maximum compatibility:
 
-// Class usage
-const dns = new YqDns({
-  google: { enabled: true },
-  cloudflare: { enabled: true }
-});
+```javascript
+// CommonJS usage
+const { resolve4, YqDns } = require('yq-dns');
 
-dns.resolve4('example.com').then(addresses => {
-  console.log(addresses);
-});
+const addresses = await resolve4('example.com');
 ```
 
 ## 🌐 DNS Providers
 
+YQ-DNS 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.
 
-### Google DoH
 - **Endpoint**: `https://dns.google/resolve`
-- **Features**: DNSSEC validation, high reliability
+- **Features**: DNSSEC validation, high reliability, global anycast network
 - **Use Case**: Public DNS resolution with Google's infrastructure
-- **Advantages**: Global CDN, excellent uptime, DNSSEC support
+- **Advantages**: Global CDN, excellent uptime, DNSSEC support, comprehensive logging
+- **Best For**: Production applications, global services, DNSSEC-required environments
 
-### Cloudflare DoH
-- **Endpoint**: `https://cloudflare-dns.com/dns-query`
-- **Features**: Privacy-focused, minimal logging
-- **Use Case**: Privacy-conscious applications
-- **Advantages**: Fast global network, strong privacy policy
+### Cloudflare DoH (DNS-over-HTTPS)
 
-### Quad9 DoH
-- **Endpoint**: `https://dns.quad9.net/dns-query`
-- **Features**: Security-focused, threat blocking
-- **Use Case**: Security-sensitive applications
-- **Advantages**: Malware blocking, non-profit organization
+Cloudflare's privacy-focused DNS service emphasizes user privacy with minimal logging and fast global resolution.
 
-## ⚙️ Configuration
+- **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
 
-### Provider Configuration
+### Quad9 DoH (DNS-over-HTTPS)
 
-```typescript
-interface ProviderConfig {
-  enabled?: boolean;           // Enable/disable provider (default: true)
-  limit?: {
-    concurrency: number;       // Max concurrent requests
-    interval?: number;         // Rate limiting interval in ms
-    intervalCap?: number;      // Max requests per interval
-    carryoverConcurrencyCount?: boolean; // Carry over concurrency count
-  };
-}
-```
+Quad9's security-focused DNS service provides threat intelligence and malware blocking while maintaining user privacy.
 
-### Global Configuration
+- **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
 
-```typescript
-interface YqConfig {
-  native?: ProviderConfig;      // Node.js built-in DNS
-  google?: ProviderConfig;      // Google DoH
-  cloudflare?: ProviderConfig;  // Cloudflare DoH
-  quad9?: ProviderConfig;       // Quad9 DoH
-}
-```
+## ⚙️ Configuration
 
-### Default Settings
+YQ-DNS 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.
+
+### Basic Configuration Example
 
 ```typescript
-const defaultConfig: YqConfig = {
-  native: { 
-    enabled: true, 
-    limit: { 
-      concurrency: 10, 
-      interval: 1000, 
-      intervalCap: 200, 
-      carryoverConcurrencyCount: true 
-    } 
-  },
-  google: { 
-    enabled: true, 
-    limit: { 
-      concurrency: 5, 
-      interval: 1000, 
-      intervalCap: 50, 
-      carryoverConcurrencyCount: true 
-    } 
+const dns = new YqDns({
+  google: {
+    enabled: true,
+    limit: { concurrency: 10, rps: 100 },
+    timeout: 5000,
+    retries: 3
   },
-  cloudflare: { 
-    enabled: true, 
-    limit: { 
-      concurrency: 7, 
-      interval: 1000, 
-      intervalCap: 70, 
-      carryoverConcurrencyCount: true 
-    } 
+  cloudflare: {
+    enabled: true,
+    limit: { concurrency: 5, rps: 50 }
   },
-  quad9: { 
-    enabled: true, 
-    limit: { 
-      concurrency: 5, 
-      interval: 1000, 
-      intervalCap: 50, 
-      carryoverConcurrencyCount: true 
-    } 
-  }
-};
+  quad9: { enabled: false },
+  native: { enabled: true }
+});
 ```
 
-## 📚 API Reference
-
-### YqDns Class
-
-#### Constructor
+### Configuration Options
 
-```typescript
-new YqDns(config?: YqConfig)
-```
+- **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)
 
-Creates a new DNS resolver instance with optional configuration.
-
-**Parameters:**
-- `config` (optional): Global configuration for all providers
+### Dynamic Configuration Updates
 
-**Example:**
 ```typescript
-const dns = new YqDns({
-  google: { enabled: true, limit: { concurrency: 15 } },
-  cloudflare: { enabled: false }
-});
+// Update configuration at runtime
+dns.setConfig('google', { enabled: false });
+dns.setConfigs({ cloudflare: { limit: { concurrency: 15 } } });
 ```
 
-#### Configuration Methods
+## 📚 API Reference
 
-##### `setConfig(provider: string, config: ProviderConfig): void`
+The YQ-DNS 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.
 
-Sets configuration for a specific provider.
+### YqDns Class
 
-**Parameters:**
-- `provider`: Provider name ('native', 'google', 'cloudflare', 'quad9')
-- `config`: Provider configuration object
+The YqDns class provides a comprehensive DNS resolution interface with full configuration control and advanced features like provider management, concurrency control, and runtime configuration updates.
 
-**Example:**
 ```typescript
-dns.setConfig('google', { 
-  enabled: true, 
-  limit: { concurrency: 20, interval: 1000, intervalCap: 100 } 
-});
-```
+const dns = new YqDns(config?: YqConfig);
 
-##### `setConfigs(config: YqConfig): void`
+// 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
 
-Sets configurations for multiple providers at once.
+// Configuration methods
+dns.setConfig(provider: string, config: ProviderConfig): void
+dns.setConfigs(configs: Partial<YqConfig>): void
 
-**Parameters:**
-- `config`: Global configuration object
-
-**Example:**
-```typescript
-dns.setConfigs({
-  google: { enabled: true, limit: { concurrency: 10 } },
-  cloudflare: { enabled: false },
-  native: { enabled: true }
-});
+// Email validation
+dns.emailValidator: EmailValidator
 ```
 
-#### Static Methods
-
-##### `YqDns.createEmailValidator(config?: ValidationConfig, dnsConfig?: YqConfig): EmailValidator`
-
-Creates or returns the singleton email validator instance.
-
-**Parameters:**
-- `config` (optional): Email validation configuration
-- `dnsConfig` (optional): DNS configuration for the validator
-
-**Returns:** EmailValidator instance
-
-##### `YqDns.emailValidator: EmailValidator`
-
-Gets the singleton email validator instance (creates one if it doesn't exist).
-
 ### Standalone Functions
 
-All standalone functions use a default YqDns instance and support the same parameters as their class counterparts.
-
-#### `resolve4(hostname: string, options?: ResolveOptions, provider?: ProviderName): Promise<string[] | RecordWithTtl[]>`
-
-Resolves A (IPv4) records for a hostname.
-
-**Parameters:**
-- `hostname`: The hostname to resolve
-- `options` (optional): Resolution options (`{ ttl: boolean }`)
-- `provider` (optional): Specific provider to use
+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.
 
-**Returns:** Array of IPv4 addresses or records with TTL
-
-**Example:**
 ```typescript
-// Basic usage
-const addresses = await resolve4('example.com');
+import { resolve4, resolveMx, resolveAny } from 'yq-dns';
 
-// With TTL
-const withTtl = await resolve4('example.com', { ttl: true });
+// 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
 
-// With specific provider
+// With optional provider specification
 const googleResult = await resolve4('example.com', undefined, 'google');
+const cloudflareResult = await resolveMx('example.com', undefined, 'cloudflare');
 ```
 
-#### `resolve6(hostname: string, options?: ResolveOptions, provider?: ProviderName): Promise<string[] | RecordWithTtl[]>`
-
-Resolves AAAA (IPv6) records for a hostname.
-
-#### `resolveAny(hostname: string, provider?: ProviderName): Promise<AnyRecord[]>`
-
-Resolves ANY records for a hostname.
-
-#### `resolveCaa(hostname: string, provider?: ProviderName): Promise<CaaRecord[]>`
-
-Resolves CAA (Certificate Authority Authorization) records.
-
-#### `resolveCname(hostname: string, provider?: ProviderName): Promise<string[]>`
-
-Resolves CNAME (Canonical Name) records.
-
-#### `resolveMx(hostname: string, provider?: ProviderName): Promise<MxRecord[]>`
-
-Resolves MX (Mail Exchange) records.
-
-#### `resolveNaptr(hostname: string, provider?: ProviderName): Promise<NaptrRecord[]>`
-
-Resolves NAPTR (Name Authority Pointer) records.
-
-#### `resolveNs(hostname: string, provider?: ProviderName): Promise<string[]>`
-
-Resolves NS (Name Server) records.
-
-#### `resolvePtr(ip: string, provider?: ProviderName): Promise<string[]>`
-
-Resolves PTR (Pointer) records for reverse DNS lookup.
-
-#### `resolveSoa(hostname: string, provider?: ProviderName): Promise<SoaRecord>`
-
-Resolves SOA (Start of Authority) record.
+### Method Parameters
 
-#### `resolveSrv(hostname: string, provider?: ProviderName): Promise<SrvRecord[]>`
+Most DNS resolution methods accept the following parameters:
 
-Resolves SRV (Service) records.
+- **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)
 
-#### `resolveTlsa(hostname: string, provider?: ProviderName): Promise<TlsaRecord[]>`
+### Return Types
 
-Resolves TLSA (Transport Layer Security Authentication) records.
+All methods return strongly-typed promises with comprehensive type definitions for maximum TypeScript compatibility and IntelliSense support.
 
-#### `resolveTxt(hostname: string, provider?: ProviderName): Promise<string[][]>`
 
-Resolves TXT records.
-
-#### `reverse(ip: string, provider?: ProviderName): Promise<string[]>`
-
-Performs reverse DNS lookup.
-
-### DNS Resolution Methods
-
-All DNS resolution methods in the YqDns class follow the same pattern:
-
-```typescript
-// Method signature pattern
-async methodName(hostname: string, options?: ResolveOptions, provider?: ProviderName): Promise<ReturnType>
-```
-
-**Common Parameters:**
-- `hostname`: The hostname or IP address to resolve
-- `options` (optional): Resolution options (currently supports `{ ttl: boolean }`)
-- `provider` (optional): Force using a specific provider ('native', 'google', 'cloudflare', 'quad9')
-
-**Provider Selection Logic:**
-1. If `provider` is specified, use that provider (must be enabled)
-2. Otherwise, randomly select from enabled providers
-3. Prefer providers that are not at queue capacity
-4. Throw error if no providers are enabled
 
 ### Email Validation
 
+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.
+
 #### `EmailValidator` Class
 
-The EmailValidator provides comprehensive email validation and analysis.
+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.
 
 ##### `validate(email: string, deep?: boolean): Promise<EmailResponse>`
 
-Validates an email address and determines its provider/service.
+Performs comprehensive email validation and analysis, returning detailed information about the email address including provider detection, webmail availability, and role-based email identification.
 
 **Parameters:**
-- `email`: Email address to validate
-- `deep` (optional): Enable deep validation with additional DNS lookups (default: false)
+- `email`: Email address to validate (string)
+- `deep` (optional): Enable deep validation with additional DNS lookups and extended checks (default: false)
 
 **Returns:** EmailResponse object with one of the following structures:
 
-**Success Response:**
+**Success Response Structure:**
 ```typescript
 {
   success: true,
   data: {
-    provider: string,     // Email provider name
+    provider: string,     // Email provider name (e.g., "Gmail", "Outlook")
     email: string,        // Normalized email address
-    role: boolean,        // Whether it's a role-based email
+    role: boolean,        // Whether it's a role-based email (admin, support, etc.)
     webmail?: string      // Webmail URL if available
   }
 }
 ```
 
-**Error Response:**
+**Error Response Structure:**
 ```typescript
 {
   success: false,
   type: 'Syntanx' | 'Rejected' | 'Invalid' | 'Error',
   email: string,
-  message?: string      // Only present for 'Error' type
+  message?: string      // Detailed error message (only present for 'Error' type)
 }
 ```
 
-**Example:**
+#### Basic Email Validation Examples
+
+**Simple Validation:**
 ```typescript
+import { YqDns } from 'yq-dns';
+
 const validator = YqDns.emailValidator;
+
+// Basic email validation
 const result = await validator.validate('user@gmail.com');
 if (result.success) {
-  console.log('Provider:', result.data.provider);
-  console.log('Webmail:', result.data.webmail);
-  console.log('Role email:', result.data.role);
+  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('Validation failed:', result.type);
+  console.log('❌ Invalid email:', result.type);
 }
 ```
 
-## 🗂️ DNS Record Types
-
-### Supported Record Types
-
-| Record Type | Description | Return Type |
-|-------------|-------------|-------------|
-| **A** | IPv4 address records | `string[]` or `RecordWithTtl[]` |
-| **AAAA** | IPv6 address records | `string[]` or `RecordWithTtl[]` |
-| **ANY** | All available records | `AnyRecord[]` |
-| **CAA** | Certificate Authority Authorization | `CaaRecord[]` |
-| **CNAME** | Canonical name records | `string[]` |
-| **MX** | Mail exchange records | `MxRecord[]` |
-| **NAPTR** | Name Authority Pointer | `NaptrRecord[]` |
-| **NS** | Name server records | `string[]` |
-| **PTR** | Pointer records (reverse DNS) | `string[]` |
-| **SOA** | Start of Authority | `SoaRecord` |
-| **SRV** | Service records | `SrvRecord[]` |
-| **TLSA** | TLS Authentication | `TlsaRecord[]` |
-| **TXT** | Text records | `string[][]` |
-
-### Type Definitions
-
+**Deep Validation Mode:**
 ```typescript
-interface RecordWithTtl {
-  address: string;
-  ttl: number;
-}
-
-interface MxRecord {
-  priority: number;
-  exchange: string;
-}
-
-interface SrvRecord {
-  priority: number;
-  weight: number;
-  port: number;
-  name: string;
-}
-
-interface SoaRecord {
-  nsname: string;
-  hostmaster: string;
-  serial: number;
-  refresh: number;
-  retry: number;
-  expire: number;
-  minttl: number;
-}
-
-interface CaaRecord {
-  critical: number;
-  issue?: string;
-  issuewild?: string;
-  iodef?: string;
-}
-
-interface NaptrRecord {
-  flags: string;
-  service: string;
-  regexp: string;
-  replacement: string;
-  order: number;
-  preference: number;
-}
-
-interface TlsaRecord {
-  usage: number;
-  selector: number;
-  matchingType: number;
-  certificate: string;
+// 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"
 }
 ```
 
-## 🔧 Advanced Usage
-
-### Rate Limiting
-
-Configure rate limiting to control request frequency:
+#### Provider Detection Examples
 
+**Major Email Providers:**
 ```typescript
-const dns = new YqDns({
-  google: {
-    enabled: true,
-    limit: {
-      concurrency: 5,        // Max 5 concurrent requests
-      interval: 1000,        // Per 1 second
-      intervalCap: 10,       // Max 10 requests per interval
-      carryoverConcurrencyCount: true
-    }
-  }
-});
-```
+// Gmail detection
+const gmailResult = await validator.validate('john.doe@gmail.com');
+console.log(gmailResult.data?.provider);  // "Gmail"
 
-### Provider Selection
+// Outlook detection
+const outlookResult = await validator.validate('jane@outlook.com');
+console.log(outlookResult.data?.provider);  // "Outlook"
 
-```typescript
-// Force specific provider
-const googleResult = await resolve4('example.com', undefined, 'google');
-const cloudflareResult = await resolve4('example.com', undefined, 'cloudflare');
+// Yahoo detection
+const yahooResult = await validator.validate('user@yahoo.com');
+console.log(yahooResult.data?.provider);  // "Yahoo"
 
-// Let the library choose (recommended)
-const autoResult = await resolve4('example.com');
-
-// Disable specific providers
-const dns = new YqDns({
-  quad9: { enabled: false },  // Disable Quad9
-  native: { enabled: false }  // Disable native DNS
-});
+// Corporate email detection
+const corpResult = await validator.validate('employee@microsoft.com');
+console.log(corpResult.data?.provider);  // "Microsoft"
 ```
 
-### Error Handling
+#### Role-Based Email Detection
 
+**Identifying Role-Based Addresses:**
 ```typescript
-import { 
-  NoEnabledProvidersError, 
-  InvalidHostnameError, 
-  ProviderNotEnabledError,
-  InvalidProviderError 
-} from 'yq-dns';
+// Common role-based emails
+const roleEmails = [
+  'admin@company.com',
+  'support@service.com',
+  'info@business.org',
+  'sales@enterprise.net',
+  'noreply@platform.io'
+];
 
-try {
-  const result = await resolve4('invalid..hostname');
-} catch (error) {
-  if (error instanceof InvalidHostnameError) {
-    console.error('Invalid hostname:', error.message);
-  } else if (error instanceof NoEnabledProvidersError) {
-    console.error('No DNS providers are enabled');
-  } else if (error instanceof ProviderNotEnabledError) {
-    console.error('Requested provider is not enabled:', error.message);
-  } else {
-    console.error('DNS resolution failed:', error.message);
+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`);
   }
 }
 ```
 
-### Concurrency Control
+#### Webmail Detection and Access
 
+**Webmail URL Extraction:**
 ```typescript
-// High-throughput configuration
-const highThroughputDns = new YqDns({
-  google: {
-    enabled: true,
-    limit: {
-      concurrency: 50,       // High concurrency
-      interval: 1000,
-      intervalCap: 1000      // High rate limit
-    }
-  },
-  cloudflare: {
-    enabled: true,
-    limit: {
-      concurrency: 30,
-      interval: 1000,
-      intervalCap: 500
-    }
-  }
-});
+// 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
+];
 
-// Conservative configuration
-const conservativeDns = new YqDns({
-  native: {
-    enabled: true,
-    limit: {
-      concurrency: 2,        // Low concurrency
-      interval: 2000,        // Longer interval
-      intervalCap: 5         // Low rate limit
-    }
+for (const email of webmailEmails) {
+  const result = await validator.validate(email);
+  if (result.success && result.data.webmail) {
+    console.log(`${email} -> ${result.data.webmail}`);
   }
-});
-```
-
-## 📧 Email Validation System
-
-### Domain Validation
-
-Validate email domains with comprehensive analysis:
-
-```typescript
-const validator = YqDns.emailValidator;
-
-// Basic domain validation
-const result = await validator.validate('user@example.com');
-if (result.success) {
-  console.log('Domain is valid');
-  console.log('Provider:', result.data.provider);
-}
-```
-
-### Webmail Detection
-
-Detect and identify webmail interfaces:
-
-```typescript
-const result = await validator.validate('user@gmail.com');
-if (result.success && result.data.webmail) {
-  console.log('Webmail URL:', result.data.webmail);
-  // Output: https://mail.google.com
 }
 ```
 
-### Provider Recognition
-
-Recognize 100+ email providers:
+#### Batch Email Validation
 
+**Validating Multiple Emails:**
 ```typescript
-const result = await validator.validate('user@outlook.com');
-if (result.success) {
-  console.log('Provider:', result.data.provider);
-  // Output: 'Outlook'
+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'
+      };
+    }
+  });
 }
-```
-
-### Supported Email Providers
-
-- **Major Providers**: Gmail, Outlook, Yahoo, iCloud, ProtonMail
-- **Business**: Office 365, Google Workspace, Zoho, Fastmail
-- **Regional**: 163.com, QQ.com, Mail.ru, Yandex, Naver
-- **Hosting**: GoDaddy, Namecheap, Rackspace, Amazon SES
-- **Security**: Mimecast, Proofpoint, Barracuda
-- **And 80+ more providers...
-
-## 🔷 TypeScript Support
-
-### Full Type Safety
-
-```typescript
-import { YqDns, MxRecord, SrvRecord, ProviderName } from 'yq-dns';
 
-// Strongly typed configuration
-const config: YqConfig = {
-  google: {
-    enabled: true,
-    limit: {
-      concurrency: 10,
-      interval: 1000,
-      intervalCap: 100
+// Usage example
+const emailList = [
+  'valid@gmail.com',
+  'invalid.email',
+  'admin@company.com',
+  'user@nonexistent-domain.xyz'
+];
+
+const batchResults = await validateEmailBatch(emailList);
+console.log('Batch validation results:', batchResults);
+```
+
+#### Error Handling and Response Types
+
+**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 'Syntanx':
+          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 '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'
+    };
   }
-};
-
-// Strongly typed results
-const mxRecords: MxRecord[] = await resolveMx('example.com');
-const srvRecords: SrvRecord[] = await resolveSrv('_sip._tcp.example.com');
-
-// Type-safe provider names
-const provider: ProviderName = 'google';
-const addresses = await resolve4('example.com', undefined, provider);
-```
-
-### Generic Overloads
-
-```typescript
-// Method overloads for different return types
-const addresses: string[] = await resolve4('example.com');
-const withTtl: RecordWithTtl[] = await resolve4('example.com', { ttl: true });
-```
-
-### Custom Types
-
-```typescript
-// Import specific types as needed
-import type {
-  YqConfig,
-  ProviderConfig,
-  ProviderName,
-  RecordType,
-  AnyRecord,
-  RecordWithTtl,
-  ResolveOptions,
-  ResolveWithTtlOptions
-} from 'yq-dns';
-```
-
-## ⚡ Performance
-
-### Benchmarks
-
-- **Concurrent Requests**: Up to 50 concurrent DNS requests per provider
-- **Response Time**: Average 50-200ms depending on provider and location
-- **Throughput**: 1000+ requests per second with optimal configuration
-- **Memory Usage**: Minimal memory footprint with efficient queue management
-
-### Optimization Tips
-
-1. **Use Multiple Providers**: Enable multiple providers for better load distribution
-2. **Tune Concurrency**: Adjust concurrency limits based on your use case
-3. **Provider Selection**: Use faster providers for time-sensitive applications
-4. **Caching**: Implement your own caching layer for frequently accessed domains
-5. **Error Handling**: Implement proper retry logic for failed requests
-
-### Performance Configuration
-
-```typescript
-// High-performance configuration
-const performanceDns = new YqDns({
-  google: {
-    enabled: true,
-    limit: { concurrency: 20, interval: 1000, intervalCap: 200 }
-  },
-  cloudflare: {
-    enabled: true,
-    limit: { concurrency: 20, interval: 1000, intervalCap: 200 }
-  },
-  quad9: {
-    enabled: true,
-    limit: { concurrency: 15, interval: 1000, intervalCap: 150 }
-  },
-  native: {
-    enabled: true,
-    limit: { concurrency: 10, interval: 1000, intervalCap: 100 }
-  }
-});
-```
-
-## 📖 Examples
-
-### Basic DNS Resolution
-
-```typescript
-import { resolve4, resolveMx, resolveAny } from 'yq-dns';
-
-// Resolve multiple record types
-const [addresses, mxRecords, anyRecords] = await Promise.all([
-  resolve4('example.com'),
-  resolveMx('example.com'),
-  resolveAny('example.com')
-]);
+}
 
-console.log('A Records:', addresses);
-console.log('MX Records:', mxRecords);
-console.log('All Records:', anyRecords);
+// Usage
+const validationResult = await handleEmailValidation('test@example.com');
+console.log(validationResult);
 ```
 
-### Email Domain Analysis
+#### Advanced Use Cases
 
+**Email Domain Analysis:**
 ```typescript
-import { YqDns } from 'yq-dns';
-
-const validator = YqDns.emailValidator;
-
 async function analyzeEmailDomain(email: string) {
-  const result = await validator.validate(email);
+  const result = await validator.validate(email, true); // Deep validation
   
   if (result.success) {
+    const domain = email.split('@')[1];
     return {
-      isValid: true,
+      email: result.data.email,
+      domain,
       provider: result.data.provider,
       hasWebmail: !!result.data.webmail,
       webmailUrl: result.data.webmail,
-      isRole: result.data.role
+      isRoleBased: result.data.role,
+      isPersonal: ['Gmail', 'Yahoo', 'Outlook', 'iCloud'].includes(result.data.provider),
+      isCorporate: !['Gmail', 'Yahoo', 'Outlook', 'iCloud'].includes(result.data.provider)
     };
   } else {
     return {
-      isValid: false,
-      error: result.type,
-      message: result.message
+      email,
+      valid: false,
+      errorType: result.type,
+      errorMessage: result.message
     };
   }
 }
 
-const analysis = await analyzeEmailDomain('user@gmail.com');
-console.log(analysis);
-```
-
-### Bulk DNS Resolution
-
-```typescript
-import { YqDns } from 'yq-dns';
-
-const dns = new YqDns({
-  google: { enabled: true, limit: { concurrency: 10 } },
-  cloudflare: { enabled: true, limit: { concurrency: 10 } }
-});
-
-async function bulkResolve(hostnames: string[]) {
-  const results = await Promise.allSettled(
-    hostnames.map(hostname => dns.resolve4(hostname))
-  );
-  
-  return results.map((result, index) => ({
-    hostname: hostnames[index],
-    success: result.status === 'fulfilled',
-    addresses: result.status === 'fulfilled' ? result.value : [],
-    error: result.status === 'rejected' ? result.reason.message : null
-  }));
-}
-
-const domains = ['google.com', 'github.com', 'stackoverflow.com'];
-const results = await bulkResolve(domains);
-console.log(results);
+const analysis = await analyzeEmailDomain('ceo@apple.com');
+console.log('Email analysis:', analysis);
 ```
 
-### Service Discovery
+## 🗂️ DNS Record Types
 
-```typescript
-import { resolveSrv, resolveTxt } from 'yq-dns';
-
-async function discoverServices(domain: string) {
-  const [sipServices, httpServices, txtRecords] = await Promise.all([
-    resolveSrv(`_sip._tcp.${domain}`).catch(() => []),
-    resolveSrv(`_http._tcp.${domain}`).catch(() => []),
-    resolveTxt(domain).catch(() => [])
-  ]);
-  
-  return {
-    sip: sipServices,
-    http: httpServices,
-    txt: txtRecords
-  };
-}
+YQ-DNS 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.
 
-const services = await discoverServices('example.com');
-console.log('Discovered services:', services);
-```
+| 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[]` |
 
-### Custom Provider Configuration
+### Record Type Examples
 
 ```typescript
-import { YqDns } from 'yq-dns';
-
-// Create DNS resolver with custom configuration
-const customDns = new YqDns();
-
-// Configure providers at runtime
-customDns.setConfig('google', {
-  enabled: true,
-  limit: {
-    concurrency: 15,
-    interval: 1000,
-    intervalCap: 50
-  }
-});
+// A records - IPv4 addresses
+const ipv4 = await resolve4('example.com');
+// Returns: ['93.184.216.34']
 
-customDns.setConfig('cloudflare', {
-  enabled: true,
-  limit: {
-    concurrency: 10,
-    interval: 2000,
-    intervalCap: 30
-  }
-});
+// MX records - Mail servers with priority
+const mailServers = await resolveMx('example.com');
+// Returns: [{ priority: 10, exchange: 'mail.example.com' }]
 
-// Disable other providers
-customDns.setConfigs({
-  quad9: { enabled: false },
-  native: { enabled: false }
-});
+// TXT records - Text data (SPF, DKIM, etc.)
+const txtRecords = await resolveTxt('example.com');
+// Returns: [['v=spf1 include:_spf.example.com ~all']]
 
-const result = await customDns.resolve4('example.com');
-console.log('Custom DNS result:', result);
+// SRV records - Service discovery
+const services = await resolveSrv('_sip._tcp.example.com');
+// Returns: [{ priority: 10, weight: 5, port: 5060, name: 'sip.example.com' }]
 ```
 
-## 🔧 Troubleshooting
 
-### Common Issues
 
-#### No Enabled Providers Error
+## 🔷 TypeScript Support
 
-```typescript
-// Problem: All providers are disabled
-const dns = new YqDns({
-  google: { enabled: false },
-  cloudflare: { enabled: false },
-  quad9: { enabled: false },
-  native: { enabled: false }
-});
+YQ-DNS 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.
 
-// Solution: Enable at least one provider
-const dns = new YqDns({
-  google: { enabled: true }
-});
-```
-
-#### Rate Limiting Issues
+### Complete Type Safety
 
 ```typescript
-// Problem: Too aggressive rate limiting
-const dns = new YqDns({
-  google: {
-    enabled: true,
-    limit: {
-      concurrency: 1,
-      interval: 5000,
-      intervalCap: 1
-    }
-  }
-});
-
-// Solution: Increase limits
-const dns = new YqDns({
-  google: {
-    enabled: true,
-    limit: {
-      concurrency: 10,
-      interval: 1000,
-      intervalCap: 50
-    }
-  }
-});
-```
+import { YqDns, MxRecord, SrvRecord, ProviderName } from 'yq-dns';
 
-#### Provider Not Available
+// Strongly typed results with full IntelliSense
+const mxRecords: MxRecord[] = await resolveMx('example.com');
+const srvRecords: SrvRecord[] = await resolveSrv('_sip._tcp.example.com');
 
-```typescript
-try {
-  const result = await resolve4('example.com', undefined, 'invalidprovider');
-} catch (error) {
-  if (error instanceof InvalidProviderError) {
-    console.error('Invalid provider name');
-    // Use valid provider names: 'native', 'google', 'cloudflare', 'quad9'
-  }
-}
+// Type-safe provider names prevent typos
+const provider: ProviderName = 'google';
+const addresses = await resolve4('example.com', undefined, provider);
 ```
 
-### Debug Mode
+### Available Type Exports
 
 ```typescript
-// Enable debug logging (if implemented)
-process.env.DEBUG = 'yq-dns:*';
-
-// Or check queue status
-const dns = new YqDns();
-console.log('Queue sizes:', {
-  google: dns.getProvider('google')?.queueSize,
-  cloudflare: dns.getProvider('cloudflare')?.queueSize
-});
+// Core types
+import {
+  YqDns,                    // Main DNS class
+  ProviderName,             // 'google' | 'cloudflare' | 'quad9' | 'native'
+  YqConfig,                 // 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 'yq-dns';
 ```
 
-### Performance Issues
-
-1. **Check Provider Status**: Ensure providers are not at capacity
-2. **Adjust Concurrency**: Increase concurrency limits if needed
-3. **Enable Multiple Providers**: Use multiple providers for load distribution
-4. **Monitor Network**: Check network connectivity to DoH endpoints
+### Generic Type Support
 
-## 🤝 Contributing
-
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
-
-### Development Setup
-
-```bash
-# Clone the repository
-git clone https://github.com/yuniqsolutions/yq-dns.git
-cd yq-dns
-
-# Install dependencies
-npm install
+```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;
+};
 
-# Build the project
-npm run build
+// Usage with automatic type inference
+const mxRecords = await resolveWithType<MxRecord[]>('example.com', 'MX');
+```
 
-# Run tests
-npm test
 
-# Lint code
-npm run lint
-```
 
-### Reporting Issues
 
-Please report issues on our [GitHub Issues](https://github.com/yuniqsolutions/yq-dns/issues) page.
 
 ## 📄 License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yq-dns",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "A promise-based DNS resolver that aggregates multiple DNS-over-HTTPS (DoH) providers with concurrency control",
   "main": "dist/index.js",
   "types": "/index.d.ts",