@darcas/smart-dns-promises 1.0.0 → 1.1.0

package/README.md

@@ -1,9 +1,10 @@
 # SmartDns
 
-![NPM Last Update](https://img.shields.io/npm/last-update/%40darcas%2Fsmart-dns-promises)
-![NPM Version](https://img.shields.io/npm/v/%40darcas%2Fsmart-dns-promises)
-![NPM Downloads](https://img.shields.io/npm/dw/%40darcas%2Fsmart-dns-promises)
-![NPM License](https://img.shields.io/npm/l/%40darcas%2Fsmart-dns-promises)
+![NPM Last Update](https://img.shields.io/npm/last-update/%40darcas%2Fsmart-dns-promises?style=for-the-badge)
+![NPM Version](https://img.shields.io/npm/v/%40darcas%2Fsmart-dns-promises?style=for-the-badge)
+![NPM Downloads](https://img.shields.io/npm/dy/%40darcas%2Fsmart-dns-promises?style=for-the-badge)
+
+![NPM License](https://img.shields.io/npm/l/%40darcas%2Fsmart-dns-promises?style=for-the-badge)
 
 A simple and efficient DNS resolver with caching and configurable DNS providers for Node.js 20 and 22 or above.
 
@@ -11,9 +12,14 @@ The purpose of this library is to increase the speed and performance of DNS reso
 
 ## Features
 
-- DNS resolution with caching for faster lookups.
+- DNS resolution with caching for faster lookups (zero runtime dependencies).
+- Cache entries expire according to the **real DNS record TTL** (configurable min/max clamp).
+- Negative caching of failed lookups to avoid hammering the resolver on down hosts.
+- In-flight deduplication: concurrent lookups for the same hostname trigger a single DNS query.
+- Optional stale-while-revalidate: expired entries are served immediately and refreshed in background.
+- Lookup statistics: hits, misses, errors, revalidations and average resolve time.
 - Supports configurable DNS providers: CloudFlare, Google, and OpenDNS.
-- Allows custom result order for DNS resolutions: IPv4 first, IPv6 first, or verbatim.
+- Allows custom result order for DNS resolutions: IPv4 first, IPv6 first, or verbatim, plus `ipv4`/`ipv6` family selection.
 - Singleton pattern to ensure only one instance of the resolver is used.
 - Manual configuration of DNS server addresses.
 
@@ -34,6 +40,7 @@ yarn add @darcas/smart-dns-promises
 ## Usage
 
 > In environments such as APIs, it is recommended to call `factory` as early as possible in the application lifecycle to benefit from Node.js's DNS system configuration.
+> See [Process-wide behaviour](#process-wide-behaviour) for details.
  
 ### Creating an instance
 
@@ -47,6 +54,37 @@ const dns = SmartDns.factory();
 
 // Optionally, configure DNS provider and result order
 const dnsWithConfig = SmartDns.factory('Google', 'ipv4first', 600000);
+
+// Advanced options (4th argument)
+const dnsAdvanced = SmartDns.factory('CloudFlare', 'ipv4first', undefined, {
+    swr: true,          // serve stale entries and refresh in background
+    negativeTtl: 30000, // how long failed lookups are negatively cached (ms)
+    minTtl: 1000,       // clamp for record TTLs coming from DNS (ms)
+    maxTtl: 3600000,    // clamp for record TTLs coming from DNS (ms)
+    family: 'ipv6',     // resolve AAAA records instead of A records
+    onStats: (stats) => console.log(stats),
+});
+```
+
+> Configuration passed to `factory` after the first call is ignored, because the singleton has already been created.
+
+### Process-wide behaviour
+
+`SmartDns` intentionally configures **Node's process-global DNS system** (`node:dns`):
+
+- `setProvider()` and `setServers()` replace the resolver servers for the **whole process**, not just for this library.
+- The `resultOrder` argument of `factory`/the constructor calls Node's `dns.setDefaultResultOrder()`, which is global too.
+
+This is by design: every HTTP client in the application — axios, fetch, or any other dependency performing DNS lookups — benefits from (and is affected by) the configured provider. For this reason, call `factory()` as **early as possible** in the application lifecycle, ideally once, so your entire Node.js software runs with a consistent and fast DNS configuration.
+
+If multiple configurations are applied, the last one wins for the whole process.
+
+### Statistics
+
+Every lookup updates the instance counters, available via the `stats` getter:
+
+```js
+const { hits, misses, errors, revalidations, avgResolveMs } = dns.stats
 ```
 ### Setting the DNS provider
 
@@ -118,6 +156,33 @@ axios.interceptors.request.use(async (config: InternalAxiosRequestConfig): Promi
 })
 ```
 
+## Example with fetch
+
+The same idea with the global `fetch`: resolve once, request the IP directly and pass the original hostname in the `Host` header.
+
+```ts
+import { SmartDns } from '@darcas/smart-dns-promises'
+
+const dns = SmartDns.factory()
+
+async function smartFetch(url: string, init: RequestInit = {}): Promise<Response> {
+    const { urlReplaced } = await dns.resolver(url)
+
+    return fetch(urlReplaced, {
+        ...init,
+        headers: {
+            ...init.headers,
+            Host: new URL(url).hostname,
+        },
+    })
+}
+```
+
+Two things to keep in mind:
+
+1. Replacing the hostname with the IP address means the TLS handshake is performed against the IP: this works out of the box with plain HTTP endpoints or controlled environments, but on public HTTPS endpoints the certificate is issued to the hostname, so the request will fail certificate validation. For HTTPS use cases prefer the axios example above.
+2. Thanks to the cache, subsequent requests to the same host skip the DNS lookup entirely.
+
 ## Contributing
 
 If you'd like to contribute to the project, feel free to fork it and create a pull request. Please ensure that your changes are well-tested and properly documented.

package/dist/commonjs/index.d.ts

@@ -1,9 +1,3 @@
-/**
- * @author      Dario Casertano <dario@casertano.name>
- * @copyright   Copyright (c) 2024 Casertano Dario – All rights reserved.
- * @license     MIT
- */
-import { LRUCache } from "lru-cache";
 /**
  * Represents a hostname of a server.
  */
@@ -16,6 +10,66 @@ type IPAddress = string;
  * Specifies the order of DNS resolution results.
  */
 type ResultOrder = 'ipv4first' | 'ipv6first' | 'verbatim';
+/**
+ * Specifies which IP address family to resolve.
+ */
+type AddressFamily = 'ipv4' | 'ipv6';
+/**
+ * A cached resolved address with its expiry timestamp.
+ */
+interface CacheEntry {
+    address: IPAddress;
+    expiresAt: number;
+}
+/**
+ * Advanced options for cache and resolver behaviour.
+ */
+export interface SmartDnsOptions {
+    /**
+     * Which IP address family to resolve.
+     * @default 'ipv4'
+     */
+    family?: AddressFamily;
+    /**
+     * Upper bound for record TTLs coming from the DNS server, in milliseconds.
+     * @default 3600000
+     */
+    maxTtl?: number;
+    /**
+     * Lower bound for record TTLs coming from the DNS server, in milliseconds.
+     * @default 1000
+     */
+    minTtl?: number;
+    /**
+     * How long failed lookups are negatively cached, in milliseconds.
+     * @default 30000
+     */
+    negativeTtl?: number;
+    /**
+     * Called with updated statistics after every lookup.
+     */
+    onStats?: (stats: SmartDnsStats) => void;
+    /**
+     * Serve expired entries immediately and refresh them in the background.
+     * @default false
+     */
+    swr?: boolean;
+}
+/**
+ * Lookup statistics for the current instance.
+ */
+export interface SmartDnsStats {
+    /** Average wall time of actual DNS queries, in milliseconds. */
+    avgResolveMs: number;
+    /** Failed lookups (including those served from the negative cache). */
+    errors: number;
+    /** Lookups served from cache. */
+    hits: number;
+    /** Lookups that required an actual DNS query. */
+    misses: number;
+    /** Background refreshes triggered by stale-while-revalidate. */
+    revalidations: number;
+}
 /**
  * Enum for built-in DNS providers.
  * @readonly
@@ -38,31 +92,70 @@ export declare class SmartDnsProviderError extends Error {
  */
 export declare class SmartDnsResolverError extends Error {
 }
+/**
+ * Minimal zero-dependency LRU cache with expiry support.
+ */
+declare class LruCache {
+    private readonly maxEntries;
+    private readonly entries;
+    constructor(maxEntries: number);
+    get(hostname: Hostname): CacheEntry | undefined;
+    set(hostname: Hostname, entry: CacheEntry): void;
+}
 /**
  * SmartDns class for managing DNS resolution with caching and configurable DNS providers.
+ *
+ * Configuration is applied to Node's process-global DNS system (`node:dns`):
+ * `setProvider` and `setServers` replace the resolver servers for the whole
+ * process, and `resultOrder` calls `dns.setDefaultResultOrder`. Every HTTP
+ * client in the application is affected by (and benefits from) this setup.
+ * Instantiate and configure SmartDns as early as possible in the application
+ * lifecycle, ideally once.
  */
 export declare class SmartDns {
+    private readonly ttl;
     /**
      * Cache for hostname-IP mappings.
      */
-    protected readonly cache: LRUCache<Hostname, IPAddress>;
+    protected readonly cache: LruCache;
+    private readonly inflight;
+    private readonly negative;
+    private readonly swr;
+    private readonly negativeTtl;
+    private readonly minTtl;
+    private readonly maxTtl;
+    private readonly family;
+    private readonly onStats?;
+    private readonly counters;
     /**
      * Creates an instance of SmartDns.
      * @param [dnsProvider] Optional DNS provider to use.
      * @param [resultOrder='ipv4first'] Order of DNS resolution results.
-     * @param [ttl=3600000] Time-to-live for cached entries in milliseconds.
+     * @param [ttl=3600000] Fallback time-to-live for cached entries in milliseconds.
+     * @param [options] Advanced cache and resolver options.
      */
-    protected constructor(dnsProvider?: DnsProvider, resultOrder?: ResultOrder, ttl?: number);
+    protected constructor(dnsProvider?: DnsProvider, resultOrder?: ResultOrder, ttl?: number, options?: SmartDnsOptions);
     /**
      * Creates or retrieves a singleton instance of SmartDns.
+     *
+     * As in v1, configuration passed after the first call is ignored because the
+     * singleton has already been created.
+     *
      * @param [dnsProvider] Optional DNS provider to use.
      * @param [resultOrder] Order of DNS resolution results.
-     * @param [ttl] Time-to-live for cached entries in milliseconds.
+     * @param [ttl] Fallback time-to-live for cached entries in milliseconds.
+     * @param [options] Advanced cache and resolver options.
      * @returns The singleton SmartDns instance.
      */
-    static factory(dnsProvider?: DnsProvider, resultOrder?: ResultOrder, ttl?: number): SmartDns;
+    static factory(dnsProvider?: DnsProvider, resultOrder?: ResultOrder, ttl?: number, options?: SmartDnsOptions): SmartDns;
+    /**
+     * Current lookup statistics for this instance.
+     */
+    get stats(): SmartDnsStats;
     /**
      * Sets the DNS servers by the provider.
+     *
+     * Note: this mutates the process-global DNS configuration via `node:dns`.
      * @param dnsProvider The DNS provider to use.
      * @throws {SmartDnsProviderError} If the DNS provider is unsupported.
      */
@@ -70,21 +163,28 @@ export declare class SmartDns {
     /**
      * Resolves a URL and retrieves its IP address, hostname, and updated URL.
      * @async
-     * @param url The URL to resolve.
+     * @param url The URL to resolve (must start with http/https).
      * @returns An object containing the resolved IP address, hostname, and the URL with the hostname replaced by the IP address.
-     * @throws {SmartDnsResolverError} If the URL is invalid.
+     * @throws {SmartDnsResolverError} If the URL is invalid or the lookup was recently failing.
      * @throws {Error} If the resolution fails.
      */
     resolver(url: string): Promise<{
         address: IPAddress;
         hostname: Hostname;
         urlReplaced: string;
-    } | undefined>;
+    }>;
     /**
      * Manually sets DNS servers.
+     *
+     * Note: this mutates the process-global DNS configuration via `node:dns`.
      * @param servers Array of DNS server IP addresses.
      */
     setServers(servers: IPAddress[]): void;
+    private resolveAddress;
+    private fetchAddress;
+    private revalidate;
+    private doResolve;
+    private emit;
 }
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/commonjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAGrC;;GAEG;AACH,KAAK,QAAQ,GAAG,MAAM,CAAA;AAEtB;;GAEG;AACH,KAAK,SAAS,GAAG,MAAM,CAAA;AAEvB;;GAEG;AACH,KAAK,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,CAAA;AAEzD;;;;GAIG;AACH,oBAAY,WAAW;IACnB,UAAU,IAAA;IACV,MAAM,IAAA;IACN,OAAO,IAAA;CACV;AAED;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;CAC/C;AAED;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;CAC/C;AAID;;GAEG;AACH,qBAAa,QAAQ;IACjB;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAA;IAEvD;;;;;OAKG;IACH,SAAS,aACL,WAAW,CAAC,EAAE,WAAW,EACzB,WAAW,GAAE,WAAyB,EACtC,GAAG,SAAY;IAcnB;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,WAAW,EAAE,WAAW,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,QAAQ;IAQ5F;;;;OAIG;IACH,WAAW,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IA4B3C;;;;;;;OAOG;IACG,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QACjC,OAAO,EAAE,SAAS,CAAA;QAClB,QAAQ,EAAE,QAAQ,CAAA;QAClB,WAAW,EAAE,MAAM,CAAA;KACtB,GAAG,SAAS,CAAC;IA8Bd;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,IAAI;CAGzC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/commonjs/index.js

@@ -1,13 +1,11 @@
 "use strict";
-// noinspection JSUnusedGlobalSymbols
+/*
+ * Dario Casertano <dario@casertano.name>
+ * Copyright (c) 2026 Casertano Dario – All rights reserved.
+ * MIT
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SmartDns = exports.SmartDnsResolverError = exports.SmartDnsProviderError = exports.DnsProvider = void 0;
-/**
- * @author      Dario Casertano <dario@casertano.name>
- * @copyright   Copyright (c) 2024 Casertano Dario – All rights reserved.
- * @license     MIT
- */
-const lru_cache_1 = require("lru-cache");
 const promises_1 = require("node:dns/promises");
 /**
  * Enum for built-in DNS providers.
@@ -34,26 +32,84 @@ exports.SmartDnsProviderError = SmartDnsProviderError;
 class SmartDnsResolverError extends Error {
 }
 exports.SmartDnsResolverError = SmartDnsResolverError;
+/**
+ * Minimal zero-dependency LRU cache with expiry support.
+ */
+class LruCache {
+    maxEntries;
+    entries = new Map();
+    constructor(maxEntries) {
+        this.maxEntries = maxEntries;
+    }
+    get(hostname) {
+        const entry = this.entries.get(hostname);
+        if (!entry) {
+            return undefined;
+        }
+        this.entries.delete(hostname);
+        this.entries.set(hostname, entry);
+        return entry;
+    }
+    set(hostname, entry) {
+        this.entries.delete(hostname);
+        this.entries.set(hostname, entry);
+        if (this.entries.size > this.maxEntries) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest !== undefined) {
+                this.entries.delete(oldest);
+            }
+        }
+    }
+}
 let SmartDnsInstance;
 /**
  * SmartDns class for managing DNS resolution with caching and configurable DNS providers.
+ *
+ * Configuration is applied to Node's process-global DNS system (`node:dns`):
+ * `setProvider` and `setServers` replace the resolver servers for the whole
+ * process, and `resultOrder` calls `dns.setDefaultResultOrder`. Every HTTP
+ * client in the application is affected by (and benefits from) this setup.
+ * Instantiate and configure SmartDns as early as possible in the application
+ * lifecycle, ideally once.
  */
 class SmartDns {
+    ttl;
     /**
      * Cache for hostname-IP mappings.
      */
     cache;
+    inflight = new Map();
+    negative = new Map();
+    swr;
+    negativeTtl;
+    minTtl;
+    maxTtl;
+    family;
+    onStats;
+    counters = {
+        errors: 0,
+        hits: 0,
+        misses: 0,
+        resolutions: 0,
+        revalidations: 0,
+        totalResolveMs: 0,
+    };
     /**
      * Creates an instance of SmartDns.
      * @param [dnsProvider] Optional DNS provider to use.
      * @param [resultOrder='ipv4first'] Order of DNS resolution results.
-     * @param [ttl=3600000] Time-to-live for cached entries in milliseconds.
+     * @param [ttl=3600000] Fallback time-to-live for cached entries in milliseconds.
+     * @param [options] Advanced cache and resolver options.
      */
-    constructor(dnsProvider, resultOrder = 'ipv4first', ttl = 3_600_000) {
-        this.cache = new lru_cache_1.LRUCache({
-            max: 100,
-            ttl,
-        });
+    constructor(dnsProvider, resultOrder = 'ipv4first', ttl = 3_600_000, options = {}) {
+        this.ttl = ttl;
+        this.swr = options.swr ?? false;
+        this.negativeTtl = options.negativeTtl ?? 30_000;
+        this.minTtl = Math.max(options.minTtl ?? 1_000, 1);
+        this.maxTtl = Math.max(options.maxTtl ?? 3_600_000, this.minTtl);
+        this.family = options.family ?? 'ipv4';
+        this.onStats = options.onStats;
+        this.cache = new LruCache(100);
         if (dnsProvider) {
             this.setProvider(dnsProvider);
         }
@@ -61,19 +117,40 @@ class SmartDns {
     }
     /**
      * Creates or retrieves a singleton instance of SmartDns.
+     *
+     * As in v1, configuration passed after the first call is ignored because the
+     * singleton has already been created.
+     *
      * @param [dnsProvider] Optional DNS provider to use.
      * @param [resultOrder] Order of DNS resolution results.
-     * @param [ttl] Time-to-live for cached entries in milliseconds.
+     * @param [ttl] Fallback time-to-live for cached entries in milliseconds.
+     * @param [options] Advanced cache and resolver options.
      * @returns The singleton SmartDns instance.
      */
-    static factory(dnsProvider, resultOrder, ttl) {
+    static factory(dnsProvider, resultOrder, ttl, options) {
         if (!SmartDnsInstance) {
-            SmartDnsInstance = new SmartDns(dnsProvider, resultOrder, ttl);
+            SmartDnsInstance = new SmartDns(dnsProvider, resultOrder, ttl, options);
         }
         return SmartDnsInstance;
     }
+    /**
+     * Current lookup statistics for this instance.
+     */
+    get stats() {
+        return {
+            avgResolveMs: this.counters.resolutions > 0
+                ? this.counters.totalResolveMs / this.counters.resolutions
+                : 0,
+            errors: this.counters.errors,
+            hits: this.counters.hits,
+            misses: this.counters.misses,
+            revalidations: this.counters.revalidations,
+        };
+    }
     /**
      * Sets the DNS servers by the provider.
+     *
+     * Note: this mutates the process-global DNS configuration via `node:dns`.
      * @param dnsProvider The DNS provider to use.
      * @throws {SmartDnsProviderError} If the DNS provider is unsupported.
      */
@@ -104,42 +181,111 @@ class SmartDns {
     /**
      * Resolves a URL and retrieves its IP address, hostname, and updated URL.
      * @async
-     * @param url The URL to resolve.
+     * @param url The URL to resolve (must start with http/https).
      * @returns An object containing the resolved IP address, hostname, and the URL with the hostname replaced by the IP address.
-     * @throws {SmartDnsResolverError} If the URL is invalid.
+     * @throws {SmartDnsResolverError} If the URL is invalid or the lookup was recently failing.
      * @throws {Error} If the resolution fails.
      */
     async resolver(url) {
         if (!/^https?:\/\//.test(url)) {
             throw new SmartDnsResolverError(`The URL must start with http/https.`);
         }
+        let parsedUrl;
         try {
-            const hostname = new URL(url).hostname;
-            if (!this.cache.has(hostname)) {
-                const resolver = new promises_1.Resolver();
-                const [address] = await resolver.resolve4(hostname);
-                this.cache.set(hostname, address);
-            }
-            if (this.cache.has(hostname)) {
-                const address = this.cache.get(hostname);
-                return {
-                    address,
-                    hostname,
-                    urlReplaced: url.replace(hostname, address),
-                };
-            }
-            return undefined;
+            parsedUrl = new URL(url);
         }
-        catch (e) {
-            throw e;
+        catch {
+            throw new SmartDnsResolverError(`The URL "${url}" is not a valid URL.`);
         }
+        const hostname = parsedUrl.hostname;
+        const address = await this.resolveAddress(hostname);
+        return {
+            address,
+            hostname,
+            urlReplaced: url.replace(hostname, address),
+        };
     }
     /**
      * Manually sets DNS servers.
+     *
+     * Note: this mutates the process-global DNS configuration via `node:dns`.
      * @param servers Array of DNS server IP addresses.
      */
     setServers(servers) {
         (0, promises_1.setServers)(servers);
     }
+    async resolveAddress(hostname) {
+        const now = Date.now();
+        const entry = this.cache.get(hostname);
+        if (entry && entry.expiresAt > now) {
+            this.counters.hits++;
+            this.emit();
+            return entry.address;
+        }
+        if (entry && this.swr) {
+            this.counters.hits++;
+            this.counters.revalidations++;
+            this.revalidate(hostname);
+            this.emit();
+            return entry.address;
+        }
+        const negativeUntil = this.negative.get(hostname);
+        if (negativeUntil !== undefined && negativeUntil > now) {
+            this.counters.errors++;
+            this.emit();
+            throw new SmartDnsResolverError(`A recent lookup for "${hostname}" failed; retrying is rate limited by the negative cache.`);
+        }
+        this.counters.misses++;
+        return this.fetchAddress(hostname).finally(() => {
+            this.emit();
+        });
+    }
+    fetchAddress(hostname) {
+        let pending = this.inflight.get(hostname);
+        if (!pending) {
+            pending = this.doResolve(hostname);
+            this.inflight.set(hostname, pending);
+            pending.then(() => undefined, () => undefined).finally(() => {
+                this.inflight.delete(hostname);
+            });
+        }
+        return pending;
+    }
+    revalidate(hostname) {
+        void this.fetchAddress(hostname);
+    }
+    async doResolve(hostname) {
+        const startedAt = Date.now();
+        try {
+            const resolver = new promises_1.Resolver();
+            const records = this.family === 'ipv6'
+                ? await resolver.resolve6(hostname, { ttl: true })
+                : await resolver.resolve4(hostname, { ttl: true });
+            const [record] = records;
+            if (!record) {
+                throw new Error(`No ${this.family} records found for "${hostname}".`);
+            }
+            const rawTtl = record.ttl > 0 ? record.ttl * 1000 : this.ttl;
+            const recordTtl = Math.min(Math.max(rawTtl, this.minTtl), this.maxTtl);
+            this.cache.set(hostname, {
+                address: record.address,
+                expiresAt: Date.now() + recordTtl,
+            });
+            this.negative.delete(hostname);
+            return record.address;
+        }
+        catch (e) {
+            this.counters.errors++;
+            this.negative.set(hostname, Date.now() + this.negativeTtl);
+            throw e;
+        }
+        finally {
+            this.counters.resolutions++;
+            this.counters.totalResolveMs += Date.now() - startedAt;
+        }
+    }
+    emit() {
+        this.onStats?.(this.stats);
+    }
 }
 exports.SmartDns = SmartDns;

package/dist/commonjs/index.min.js

@@ -1,7 +1,2 @@
-"use strict";var B=(o,t)=>()=>(t||o((t={exports:{}}).exports,t),t.exports);var q=B(D=>{"use strict";Object.defineProperty(D,"__esModule",{value:!0});D.LRUCache=void 0;var F=typeof performance=="object"&&performance&&typeof performance.now=="function"?performance:Date,k=new Set,U=typeof process=="object"&&process?process:{},H=(o,t,e,i)=>{typeof U.emitWarning=="function"?U.emitWarning(o,t,e,i):console.error(`[${e}] ${t}: ${o}`)},R=globalThis.AbortController,P=globalThis.AbortSignal;if(typeof R>"u"){P=class{onabort;_onabort=[];reason;aborted=!1;addEventListener(i,s){this._onabort.push(s)}},R=class{constructor(){t()}signal=new P;abort(i){if(!this.signal.aborted){this.signal.reason=i,this.signal.aborted=!0;for(let s of this.signal._onabort)s(i);this.signal.onabort?.(i)}}};let o=U.env?.LRU_CACHE_IGNORE_AC_WARNING!=="1",t=()=>{o&&(o=!1,H("AbortController is not defined. If using lru-cache in node 14, load an AbortController polyfill from the `node-abort-controller` package. A minimal polyfill is provided for use by LRUCache.fetch(), but it should not be relied upon in other contexts (eg, passing it to other APIs that use AbortController/AbortSignal might have undesirable effects). You may disable this with LRU_CACHE_IGNORE_AC_WARNING=1 in the env.","NO_ABORT_CONTROLLER","ENOTSUP",t))}}var $=o=>!k.has(o),Q=Symbol("type"),A=o=>o&&o===Math.floor(o)&&o>0&&isFinite(o),V=o=>A(o)?o<=Math.pow(2,8)?Uint8Array:o<=Math.pow(2,16)?Uint16Array:o<=Math.pow(2,32)?Uint32Array:o<=Number.MAX_SAFE_INTEGER?O:null:null,O=class extends Array{constructor(t){super(t),this.fill(0)}},G=class o{heap;length;static#l=!1;static create(t){let e=V(t);if(!e)return[];o.#l=!0;let i=new o(t,e);return o.#l=!1,i}constructor(t,e){if(!o.#l)throw new TypeError("instantiate Stack using Stack.create(n)");this.heap=new e(t),this.length=0}push(t){this.heap[this.length++]=t}pop(){return this.heap[--this.length]}},M=class o{#l;#c;#p;#w;#R;#D;ttl;ttlResolution;ttlAutopurge;updateAgeOnGet;updateAgeOnHas;allowStale;noDisposeOnSet;noUpdateTTL;maxEntrySize;sizeCalculation;noDeleteOnFetchRejection;noDeleteOnStaleGet;allowStaleOnFetchAbort;allowStaleOnFetchRejection;ignoreFetchAbort;#n;#S;#s;#i;#t;#a;#u;#o;#h;#m;#r;#_;#b;#d;#y;#E;#f;static unsafeExposeInternals(t){return{starts:t.#b,ttls:t.#d,sizes:t.#_,keyMap:t.#s,keyList:t.#i,valList:t.#t,next:t.#a,prev:t.#u,get head(){return t.#o},get tail(){return t.#h},free:t.#m,isBackgroundFetch:e=>t.#e(e),backgroundFetch:(e,i,s,n)=>t.#x(e,i,s,n),moveToTail:e=>t.#C(e),indexes:e=>t.#A(e),rindexes:e=>t.#v(e),isStale:e=>t.#g(e)}}get max(){return this.#l}get maxSize(){return this.#c}get calculatedSize(){return this.#S}get size(){return this.#n}get fetchMethod(){return this.#R}get memoMethod(){return this.#D}get dispose(){return this.#p}get disposeAfter(){return this.#w}constructor(t){let{max:e=0,ttl:i,ttlResolution:s=1,ttlAutopurge:n,updateAgeOnGet:h,updateAgeOnHas:l,allowStale:r,dispose:g,disposeAfter:_,noDisposeOnSet:f,noUpdateTTL:u,maxSize:c=0,maxEntrySize:v=0,sizeCalculation:d,fetchMethod:S,memoMethod:a,noDeleteOnFetchRejection:w,noDeleteOnStaleGet:b,allowStaleOnFetchRejection:p,allowStaleOnFetchAbort:m,ignoreFetchAbort:T}=t;if(e!==0&&!A(e))throw new TypeError("max option must be a nonnegative integer");let y=e?V(e):Array;if(!y)throw new Error("invalid max value: "+e);if(this.#l=e,this.#c=c,this.maxEntrySize=v||this.#c,this.sizeCalculation=d,this.sizeCalculation){if(!this.#c&&!this.maxEntrySize)throw new TypeError("cannot set sizeCalculation without setting maxSize or maxEntrySize");if(typeof this.sizeCalculation!="function")throw new TypeError("sizeCalculation set to non-function")}if(a!==void 0&&typeof a!="function")throw new TypeError("memoMethod must be a function if defined");if(this.#D=a,S!==void 0&&typeof S!="function")throw new TypeError("fetchMethod must be a function if specified");if(this.#R=S,this.#E=!!S,this.#s=new Map,this.#i=new Array(e).fill(void 0),this.#t=new Array(e).fill(void 0),this.#a=new y(e),this.#u=new y(e),this.#o=0,this.#h=0,this.#m=G.create(e),this.#n=0,this.#S=0,typeof g=="function"&&(this.#p=g),typeof _=="function"?(this.#w=_,this.#r=[]):(this.#w=void 0,this.#r=void 0),this.#y=!!this.#p,this.#f=!!this.#w,this.noDisposeOnSet=!!f,this.noUpdateTTL=!!u,this.noDeleteOnFetchRejection=!!w,this.allowStaleOnFetchRejection=!!p,this.allowStaleOnFetchAbort=!!m,this.ignoreFetchAbort=!!T,this.maxEntrySize!==0){if(this.#c!==0&&!A(this.#c))throw new TypeError("maxSize must be a positive integer if specified");if(!A(this.maxEntrySize))throw new TypeError("maxEntrySize must be a positive integer if specified");this.#P()}if(this.allowStale=!!r,this.noDeleteOnStaleGet=!!b,this.updateAgeOnGet=!!h,this.updateAgeOnHas=!!l,this.ttlResolution=A(s)||s===0?s:1,this.ttlAutopurge=!!n,this.ttl=i||0,this.ttl){if(!A(this.ttl))throw new TypeError("ttl must be a positive integer if specified");this.#U()}if(this.#l===0&&this.ttl===0&&this.#c===0)throw new TypeError("At least one of max, maxSize, or ttl is required");if(!this.ttlAutopurge&&!this.#l&&!this.#c){let C="LRU_CACHE_UNBOUNDED";$(C)&&(k.add(C),H("TTL caching without ttlAutopurge, max, or maxSize can result in unbounded memory consumption.","UnboundedCacheWarning",C,o))}}getRemainingTTL(t){return this.#s.has(t)?1/0:0}#U(){let t=new O(this.#l),e=new O(this.#l);this.#d=t,this.#b=e,this.#G=(n,h,l=F.now())=>{if(e[n]=h!==0?l:0,t[n]=h,h!==0&&this.ttlAutopurge){let r=setTimeout(()=>{this.#g(n)&&this.#F(this.#i[n],"expire")},h+1);r.unref&&r.unref()}},this.#T=n=>{e[n]=t[n]!==0?F.now():0},this.#O=(n,h)=>{if(t[h]){let l=t[h],r=e[h];if(!l||!r)return;n.ttl=l,n.start=r,n.now=i||s();let g=n.now-r;n.remainingTTL=l-g}};let i=0,s=()=>{let n=F.now();if(this.ttlResolution>0){i=n;let h=setTimeout(()=>i=0,this.ttlResolution);h.unref&&h.unref()}return n};this.getRemainingTTL=n=>{let h=this.#s.get(n);if(h===void 0)return 0;let l=t[h],r=e[h];if(!l||!r)return 1/0;let g=(i||s())-r;return l-g},this.#g=n=>{let h=e[n],l=t[n];return!!l&&!!h&&(i||s())-h>l}}#T=()=>{};#O=()=>{};#G=()=>{};#g=()=>!1;#P(){let t=new O(this.#l);this.#S=0,this.#_=t,this.#z=e=>{this.#S-=t[e],t[e]=0},this.#M=(e,i,s,n)=>{if(this.#e(i))return 0;if(!A(s))if(n){if(typeof n!="function")throw new TypeError("sizeCalculation must be a function");if(s=n(i,e),!A(s))throw new TypeError("sizeCalculation return invalid (expect positive integer)")}else throw new TypeError("invalid size value (must be positive integer). When maxSize or maxEntrySize is used, sizeCalculation or size must be set.");return s},this.#W=(e,i,s)=>{if(t[e]=i,this.#c){let n=this.#c-t[e];for(;this.#S>n;)this.#L(!0)}this.#S+=t[e],s&&(s.entrySize=i,s.totalCalculatedSize=this.#S)}}#z=t=>{};#W=(t,e,i)=>{};#M=(t,e,i,s)=>{if(i||s)throw new TypeError("cannot set size without setting maxSize or maxEntrySize on cache");return 0};*#A({allowStale:t=this.allowStale}={}){if(this.#n)for(let e=this.#h;!(!this.#N(e)||((t||!this.#g(e))&&(yield e),e===this.#o));)e=this.#u[e]}*#v({allowStale:t=this.allowStale}={}){if(this.#n)for(let e=this.#o;!(!this.#N(e)||((t||!this.#g(e))&&(yield e),e===this.#h));)e=this.#a[e]}#N(t){return t!==void 0&&this.#s.get(this.#i[t])===t}*entries(){for(let t of this.#A())this.#t[t]!==void 0&&this.#i[t]!==void 0&&!this.#e(this.#t[t])&&(yield[this.#i[t],this.#t[t]])}*rentries(){for(let t of this.#v())this.#t[t]!==void 0&&this.#i[t]!==void 0&&!this.#e(this.#t[t])&&(yield[this.#i[t],this.#t[t]])}*keys(){for(let t of this.#A()){let e=this.#i[t];e!==void 0&&!this.#e(this.#t[t])&&(yield e)}}*rkeys(){for(let t of this.#v()){let e=this.#i[t];e!==void 0&&!this.#e(this.#t[t])&&(yield e)}}*values(){for(let t of this.#A())this.#t[t]!==void 0&&!this.#e(this.#t[t])&&(yield this.#t[t])}*rvalues(){for(let t of this.#v())this.#t[t]!==void 0&&!this.#e(this.#t[t])&&(yield this.#t[t])}[Symbol.iterator](){return this.entries()}[Symbol.toStringTag]="LRUCache";find(t,e={}){for(let i of this.#A()){let s=this.#t[i],n=this.#e(s)?s.__staleWhileFetching:s;if(n!==void 0&&t(n,this.#i[i],this))return this.get(this.#i[i],e)}}forEach(t,e=this){for(let i of this.#A()){let s=this.#t[i],n=this.#e(s)?s.__staleWhileFetching:s;n!==void 0&&t.call(e,n,this.#i[i],this)}}rforEach(t,e=this){for(let i of this.#v()){let s=this.#t[i],n=this.#e(s)?s.__staleWhileFetching:s;n!==void 0&&t.call(e,n,this.#i[i],this)}}purgeStale(){let t=!1;for(let e of this.#v({allowStale:!0}))this.#g(e)&&(this.#F(this.#i[e],"expire"),t=!0);return t}info(t){let e=this.#s.get(t);if(e===void 0)return;let i=this.#t[e],s=this.#e(i)?i.__staleWhileFetching:i;if(s===void 0)return;let n={value:s};if(this.#d&&this.#b){let h=this.#d[e],l=this.#b[e];if(h&&l){let r=h-(F.now()-l);n.ttl=r,n.start=Date.now()}}return this.#_&&(n.size=this.#_[e]),n}dump(){let t=[];for(let e of this.#A({allowStale:!0})){let i=this.#i[e],s=this.#t[e],n=this.#e(s)?s.__staleWhileFetching:s;if(n===void 0||i===void 0)continue;let h={value:n};if(this.#d&&this.#b){h.ttl=this.#d[e];let l=F.now()-this.#b[e];h.start=Math.floor(Date.now()-l)}this.#_&&(h.size=this.#_[e]),t.unshift([i,h])}return t}load(t){this.clear();for(let[e,i]of t){if(i.start){let s=Date.now()-i.start;i.start=F.now()-s}this.set(e,i.value,i)}}set(t,e,i={}){if(e===void 0)return this.delete(t),this;let{ttl:s=this.ttl,start:n,noDisposeOnSet:h=this.noDisposeOnSet,sizeCalculation:l=this.sizeCalculation,status:r}=i,{noUpdateTTL:g=this.noUpdateTTL}=i,_=this.#M(t,e,i.size||0,l);if(this.maxEntrySize&&_>this.maxEntrySize)return r&&(r.set="miss",r.maxEntrySizeExceeded=!0),this.#F(t,"set"),this;let f=this.#n===0?void 0:this.#s.get(t);if(f===void 0)f=this.#n===0?this.#h:this.#m.length!==0?this.#m.pop():this.#n===this.#l?this.#L(!1):this.#n,this.#i[f]=t,this.#t[f]=e,this.#s.set(t,f),this.#a[this.#h]=f,this.#u[f]=this.#h,this.#h=f,this.#n++,this.#W(f,_,r),r&&(r.set="add"),g=!1;else{this.#C(f);let u=this.#t[f];if(e!==u){if(this.#E&&this.#e(u)){u.__abortController.abort(new Error("replaced"));let{__staleWhileFetching:c}=u;c!==void 0&&!h&&(this.#y&&this.#p?.(c,t,"set"),this.#f&&this.#r?.push([c,t,"set"]))}else h||(this.#y&&this.#p?.(u,t,"set"),this.#f&&this.#r?.push([u,t,"set"]));if(this.#z(f),this.#W(f,_,r),this.#t[f]=e,r){r.set="replace";let c=u&&this.#e(u)?u.__staleWhileFetching:u;c!==void 0&&(r.oldValue=c)}}else r&&(r.set="update")}if(s!==0&&!this.#d&&this.#U(),this.#d&&(g||this.#G(f,s,n),r&&this.#O(r,f)),!h&&this.#f&&this.#r){let u=this.#r,c;for(;c=u?.shift();)this.#w?.(...c)}return this}pop(){try{for(;this.#n;){let t=this.#t[this.#o];if(this.#L(!0),this.#e(t)){if(t.__staleWhileFetching)return t.__staleWhileFetching}else if(t!==void 0)return t}}finally{if(this.#f&&this.#r){let t=this.#r,e;for(;e=t?.shift();)this.#w?.(...e)}}}#L(t){let e=this.#o,i=this.#i[e],s=this.#t[e];return this.#E&&this.#e(s)?s.__abortController.abort(new Error("evicted")):(this.#y||this.#f)&&(this.#y&&this.#p?.(s,i,"evict"),this.#f&&this.#r?.push([s,i,"evict"])),this.#z(e),t&&(this.#i[e]=void 0,this.#t[e]=void 0,this.#m.push(e)),this.#n===1?(this.#o=this.#h=0,this.#m.length=0):this.#o=this.#a[e],this.#s.delete(i),this.#n--,e}has(t,e={}){let{updateAgeOnHas:i=this.updateAgeOnHas,status:s}=e,n=this.#s.get(t);if(n!==void 0){let h=this.#t[n];if(this.#e(h)&&h.__staleWhileFetching===void 0)return!1;if(this.#g(n))s&&(s.has="stale",this.#O(s,n));else return i&&this.#T(n),s&&(s.has="hit",this.#O(s,n)),!0}else s&&(s.has="miss");return!1}peek(t,e={}){let{allowStale:i=this.allowStale}=e,s=this.#s.get(t);if(s===void 0||!i&&this.#g(s))return;let n=this.#t[s];return this.#e(n)?n.__staleWhileFetching:n}#x(t,e,i,s){let n=e===void 0?void 0:this.#t[e];if(this.#e(n))return n;let h=new R,{signal:l}=i;l?.addEventListener("abort",()=>h.abort(l.reason),{signal:h.signal});let r={signal:h.signal,options:i,context:s},g=(d,S=!1)=>{let{aborted:a}=h.signal,w=i.ignoreFetchAbort&&d!==void 0;if(i.status&&(a&&!S?(i.status.fetchAborted=!0,i.status.fetchError=h.signal.reason,w&&(i.status.fetchAbortIgnored=!0)):i.status.fetchResolved=!0),a&&!w&&!S)return f(h.signal.reason);let b=c;return this.#t[e]===c&&(d===void 0?b.__staleWhileFetching?this.#t[e]=b.__staleWhileFetching:this.#F(t,"fetch"):(i.status&&(i.status.fetchUpdated=!0),this.set(t,d,r.options))),d},_=d=>(i.status&&(i.status.fetchRejected=!0,i.status.fetchError=d),f(d)),f=d=>{let{aborted:S}=h.signal,a=S&&i.allowStaleOnFetchAbort,w=a||i.allowStaleOnFetchRejection,b=w||i.noDeleteOnFetchRejection,p=c;if(this.#t[e]===c&&(!b||p.__staleWhileFetching===void 0?this.#F(t,"fetch"):a||(this.#t[e]=p.__staleWhileFetching)),w)return i.status&&p.__staleWhileFetching!==void 0&&(i.status.returnedStale=!0),p.__staleWhileFetching;if(p.__returned===p)throw d},u=(d,S)=>{let a=this.#R?.(t,n,r);a&&a instanceof Promise&&a.then(w=>d(w===void 0?void 0:w),S),h.signal.addEventListener("abort",()=>{(!i.ignoreFetchAbort||i.allowStaleOnFetchAbort)&&(d(void 0),i.allowStaleOnFetchAbort&&(d=w=>g(w,!0)))})};i.status&&(i.status.fetchDispatched=!0);let c=new Promise(u).then(g,_),v=Object.assign(c,{__abortController:h,__staleWhileFetching:n,__returned:void 0});return e===void 0?(this.set(t,v,{...r.options,status:void 0}),e=this.#s.get(t)):this.#t[e]=v,v}#e(t){if(!this.#E)return!1;let e=t;return!!e&&e instanceof Promise&&e.hasOwnProperty("__staleWhileFetching")&&e.__abortController instanceof R}async fetch(t,e={}){let{allowStale:i=this.allowStale,updateAgeOnGet:s=this.updateAgeOnGet,noDeleteOnStaleGet:n=this.noDeleteOnStaleGet,ttl:h=this.ttl,noDisposeOnSet:l=this.noDisposeOnSet,size:r=0,sizeCalculation:g=this.sizeCalculation,noUpdateTTL:_=this.noUpdateTTL,noDeleteOnFetchRejection:f=this.noDeleteOnFetchRejection,allowStaleOnFetchRejection:u=this.allowStaleOnFetchRejection,ignoreFetchAbort:c=this.ignoreFetchAbort,allowStaleOnFetchAbort:v=this.allowStaleOnFetchAbort,context:d,forceRefresh:S=!1,status:a,signal:w}=e;if(!this.#E)return a&&(a.fetch="get"),this.get(t,{allowStale:i,updateAgeOnGet:s,noDeleteOnStaleGet:n,status:a});let b={allowStale:i,updateAgeOnGet:s,noDeleteOnStaleGet:n,ttl:h,noDisposeOnSet:l,size:r,sizeCalculation:g,noUpdateTTL:_,noDeleteOnFetchRejection:f,allowStaleOnFetchRejection:u,allowStaleOnFetchAbort:v,ignoreFetchAbort:c,status:a,signal:w},p=this.#s.get(t);if(p===void 0){a&&(a.fetch="miss");let m=this.#x(t,p,b,d);return m.__returned=m}else{let m=this.#t[p];if(this.#e(m)){let j=i&&m.__staleWhileFetching!==void 0;return a&&(a.fetch="inflight",j&&(a.returnedStale=!0)),j?m.__staleWhileFetching:m.__returned=m}let T=this.#g(p);if(!S&&!T)return a&&(a.fetch="hit"),this.#C(p),s&&this.#T(p),a&&this.#O(a,p),m;let y=this.#x(t,p,b,d),x=y.__staleWhileFetching!==void 0&&i;return a&&(a.fetch=T?"stale":"refresh",x&&T&&(a.returnedStale=!0)),x?y.__staleWhileFetching:y.__returned=y}}async forceFetch(t,e={}){let i=await this.fetch(t,e);if(i===void 0)throw new Error("fetch() returned undefined");return i}memo(t,e={}){let i=this.#D;if(!i)throw new Error("no memoMethod provided to constructor");let{context:s,forceRefresh:n,...h}=e,l=this.get(t,h);if(!n&&l!==void 0)return l;let r=i(t,l,{options:h,context:s});return this.set(t,r,h),r}get(t,e={}){let{allowStale:i=this.allowStale,updateAgeOnGet:s=this.updateAgeOnGet,noDeleteOnStaleGet:n=this.noDeleteOnStaleGet,status:h}=e,l=this.#s.get(t);if(l!==void 0){let r=this.#t[l],g=this.#e(r);return h&&this.#O(h,l),this.#g(l)?(h&&(h.get="stale"),g?(h&&i&&r.__staleWhileFetching!==void 0&&(h.returnedStale=!0),i?r.__staleWhileFetching:void 0):(n||this.#F(t,"expire"),h&&i&&(h.returnedStale=!0),i?r:void 0)):(h&&(h.get="hit"),g?r.__staleWhileFetching:(this.#C(l),s&&this.#T(l),r))}else h&&(h.get="miss")}#I(t,e){this.#u[e]=t,this.#a[t]=e}#C(t){t!==this.#h&&(t===this.#o?this.#o=this.#a[t]:this.#I(this.#u[t],this.#a[t]),this.#I(this.#h,t),this.#h=t)}delete(t){return this.#F(t,"delete")}#F(t,e){let i=!1;if(this.#n!==0){let s=this.#s.get(t);if(s!==void 0)if(i=!0,this.#n===1)this.#j(e);else{this.#z(s);let n=this.#t[s];if(this.#e(n)?n.__abortController.abort(new Error("deleted")):(this.#y||this.#f)&&(this.#y&&this.#p?.(n,t,e),this.#f&&this.#r?.push([n,t,e])),this.#s.delete(t),this.#i[s]=void 0,this.#t[s]=void 0,s===this.#h)this.#h=this.#u[s];else if(s===this.#o)this.#o=this.#a[s];else{let h=this.#u[s];this.#a[h]=this.#a[s];let l=this.#a[s];this.#u[l]=this.#u[s]}this.#n--,this.#m.push(s)}}if(this.#f&&this.#r?.length){let s=this.#r,n;for(;n=s?.shift();)this.#w?.(...n)}return i}clear(){return this.#j("delete")}#j(t){for(let e of this.#v({allowStale:!0})){let i=this.#t[e];if(this.#e(i))i.__abortController.abort(new Error("deleted"));else{let s=this.#i[e];this.#y&&this.#p?.(i,s,t),this.#f&&this.#r?.push([i,s,t])}}if(this.#s.clear(),this.#t.fill(void 0),this.#i.fill(void 0),this.#d&&this.#b&&(this.#d.fill(0),this.#b.fill(0)),this.#_&&this.#_.fill(0),this.#o=0,this.#h=0,this.#m.length=0,this.#S=0,this.#n=0,this.#f&&this.#r){let e=this.#r,i;for(;i=e?.shift();)this.#w?.(...i)}}};D.LRUCache=M});Object.defineProperty(exports,"__esModule",{value:!0});exports.SmartDns=exports.SmartDnsResolverError=exports.SmartDnsProviderError=exports.DnsProvider=void 0;var Y=q(),E=require("node:dns/promises"),z;(function(o){o[o.CloudFlare=0]="CloudFlare",o[o.Google=1]="Google",o[o.OpenDNS=2]="OpenDNS"})(z||(exports.DnsProvider=z={}));var W=class extends Error{};exports.SmartDnsProviderError=W;var L=class extends Error{};exports.SmartDnsResolverError=L;var N,I=class o{cache;constructor(t,e="ipv4first",i=36e5){this.cache=new Y.LRUCache({max:100,ttl:i}),t&&this.setProvider(t),(0,E.setDefaultResultOrder)(e)}static factory(t,e,i){return N||(N=new o(t,e,i)),N}setProvider(t){switch(t){case z.CloudFlare:(0,E.setServers)(["1.1.1.1","1.0.0.1"]);break;case z.Google:(0,E.setServers)(["8.8.8.8","8.8.4.4"]);break;case z.OpenDNS:(0,E.setServers)(["208.67.222.222","208.67.220.220"]);break;default:throw new W(`Unsupported DNS provider: ${t}. You can use the "setServers" method to manually set the DNS server IP addresses.`)}}async resolver(t){if(!/^https?:\/\//.test(t))throw new L("The URL must start with http/https.");try{let e=new URL(t).hostname;if(!this.cache.has(e)){let i=new E.Resolver,[s]=await i.resolve4(e);this.cache.set(e,s)}if(this.cache.has(e)){let i=this.cache.get(e);return{address:i,hostname:e,urlReplaced:t.replace(e,i)}}return}catch(e){throw e}}setServers(t){(0,E.setServers)(t)}};exports.SmartDns=I;
-/**
- * @author      Dario Casertano <dario@casertano.name>
- * @copyright   Copyright (c) 2024 Casertano Dario – All rights reserved.
- * @license     MIT
- */
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});exports.SmartDns=exports.SmartDnsResolverError=exports.SmartDnsProviderError=exports.DnsProvider=void 0;var n=require("node:dns/promises"),o;(function(i){i[i.CloudFlare=0]="CloudFlare",i[i.Google=1]="Google",i[i.OpenDNS=2]="OpenDNS"})(o||(exports.DnsProvider=o={}));var h=class extends Error{};exports.SmartDnsProviderError=h;var a=class extends Error{};exports.SmartDnsResolverError=a;var d=class{maxEntries;entries=new Map;constructor(t){this.maxEntries=t}get(t){let e=this.entries.get(t);if(e)return this.entries.delete(t),this.entries.set(t,e),e}set(t,e){if(this.entries.delete(t),this.entries.set(t,e),this.entries.size>this.maxEntries){let s=this.entries.keys().next().value;s!==void 0&&this.entries.delete(s)}}},c,u=class i{ttl;cache;inflight=new Map;negative=new Map;swr;negativeTtl;minTtl;maxTtl;family;onStats;counters={errors:0,hits:0,misses:0,resolutions:0,revalidations:0,totalResolveMs:0};constructor(t,e="ipv4first",s=36e5,r={}){this.ttl=s,this.swr=r.swr??!1,this.negativeTtl=r.negativeTtl??3e4,this.minTtl=Math.max(r.minTtl??1e3,1),this.maxTtl=Math.max(r.maxTtl??36e5,this.minTtl),this.family=r.family??"ipv4",this.onStats=r.onStats,this.cache=new d(100),t&&this.setProvider(t),(0,n.setDefaultResultOrder)(e)}static factory(t,e,s,r){return c||(c=new i(t,e,s,r)),c}get stats(){return{avgResolveMs:this.counters.resolutions>0?this.counters.totalResolveMs/this.counters.resolutions:0,errors:this.counters.errors,hits:this.counters.hits,misses:this.counters.misses,revalidations:this.counters.revalidations}}setProvider(t){switch(t){case o.CloudFlare:(0,n.setServers)(["1.1.1.1","1.0.0.1"]);break;case o.Google:(0,n.setServers)(["8.8.8.8","8.8.4.4"]);break;case o.OpenDNS:(0,n.setServers)(["208.67.222.222","208.67.220.220"]);break;default:throw new h(`Unsupported DNS provider: ${t}. You can use the "setServers" method to manually set the DNS server IP addresses.`)}}async resolver(t){if(!/^https?:\/\//.test(t))throw new a("The URL must start with http/https.");let e;try{e=new URL(t)}catch{throw new a(`The URL "${t}" is not a valid URL.`)}let s=e.hostname,r=await this.resolveAddress(s);return{address:r,hostname:s,urlReplaced:t.replace(s,r)}}setServers(t){(0,n.setServers)(t)}async resolveAddress(t){let e=Date.now(),s=this.cache.get(t);if(s&&s.expiresAt>e)return this.counters.hits++,this.emit(),s.address;if(s&&this.swr)return this.counters.hits++,this.counters.revalidations++,this.revalidate(t),this.emit(),s.address;let r=this.negative.get(t);if(r!==void 0&&r>e)throw this.counters.errors++,this.emit(),new a(`A recent lookup for "${t}" failed; retrying is rate limited by the negative cache.`);return this.counters.misses++,this.fetchAddress(t).finally(()=>{this.emit()})}fetchAddress(t){let e=this.inflight.get(t);return e||(e=this.doResolve(t),this.inflight.set(t,e),e.then(()=>{},()=>{}).finally(()=>{this.inflight.delete(t)})),e}revalidate(t){this.fetchAddress(t)}async doResolve(t){let e=Date.now();try{let s=new n.Resolver,r=this.family==="ipv6"?await s.resolve6(t,{ttl:!0}):await s.resolve4(t,{ttl:!0}),[l]=r;if(!l)throw new Error(`No ${this.family} records found for "${t}".`);let v=l.ttl>0?l.ttl*1e3:this.ttl,f=Math.min(Math.max(v,this.minTtl),this.maxTtl);return this.cache.set(t,{address:l.address,expiresAt:Date.now()+f}),this.negative.delete(t),l.address}catch(s){throw this.counters.errors++,this.negative.set(t,Date.now()+this.negativeTtl),s}finally{this.counters.resolutions++,this.counters.totalResolveMs+=Date.now()-e}}emit(){this.onStats?.(this.stats)}};exports.SmartDns=u;
 //# sourceMappingURL=index.min.js.map