tangerine 1.3.0 → 1.4.0

package/README.md

@@ -11,7 +11,7 @@
 </div>
 <br />
 <div align="center">
-  🍊 <a href="https://github.com/forwardemail/tangerine" target="_blank">Tangerine</a> is the best <a href="https://nodejs.org" target="_blank">Node.js</a> drop-in replacement for <a href="https://nodejs.org/api/dns.html#resolveroptions" target="_blank">dns.promises.Resolver</a> using <a href="https://en.wikipedia.org/wiki/DNS_over_HTTPS" target="_blank">DNS over HTTPS</a> ("DoH") via <a href="https://github.com/nodejs/undici" target="_blank">undici</a> with built-in retries, timeouts, smart server rotation, <a href="https://developer.mozilla.org/en-US/docs/Web/API/AbortController" target="_blank">AbortControllers</a>, and caching support for multiple backends (with TTL support).
+  🍊 <a href="https://github.com/forwardemail/tangerine" target="_blank">Tangerine</a> is the best <a href="https://nodejs.org" target="_blank">Node.js</a> drop-in replacement for <a href="https://nodejs.org/api/dns.html#resolveroptions" target="_blank">dns.promises.Resolver</a> using <a href="https://en.wikipedia.org/wiki/DNS_over_HTTPS" target="_blank">DNS over HTTPS</a> ("DoH") via <a href="https://github.com/nodejs/undici" target="_blank">undici</a> with built-in retries, timeouts, smart server rotation, <a href="https://developer.mozilla.org/en-US/docs/Web/API/AbortController" target="_blank">AbortControllers</a>, and caching support for multiple backends (with TTL and purge support).
 </div>
 <hr />
 <div align="center">
@@ -37,21 +37,21 @@
   * [`tangerine.cancel()`](#tangerinecancel)
   * [`tangerine.getServers()`](#tangerinegetservers)
   * [`tangerine.lookup(hostname[, options])`](#tangerinelookuphostname-options)
-  * [`tangerine.lookupService(address, port, abortController)`](#tangerinelookupserviceaddress-port-abortcontroller)
+  * [`tangerine.lookupService(address, port[, abortController, purgeCache])`](#tangerinelookupserviceaddress-port-abortcontroller-purgecache)
   * [`tangerine.resolve(hostname[, rrtype, options, abortController])`](#tangerineresolvehostname-rrtype-options-abortcontroller)
   * [`tangerine.resolve4(hostname[, options, abortController])`](#tangerineresolve4hostname-options-abortcontroller)
   * [`tangerine.resolve6(hostname[, options, abortController])`](#tangerineresolve6hostname-options-abortcontroller)
-  * [`tangerine.resolveAny(hostname[, abortController])`](#tangerineresolveanyhostname-abortcontroller)
-  * [`tangerine.resolveCaa(hostname[, abortController]))`](#tangerineresolvecaahostname-abortcontroller)
-  * [`tangerine.resolveCname(hostname[, abortController]))`](#tangerineresolvecnamehostname-abortcontroller)
-  * [`tangerine.resolveMx(hostname[, abortController]))`](#tangerineresolvemxhostname-abortcontroller)
-  * [`tangerine.resolveNaptr(hostname[, abortController]))`](#tangerineresolvenaptrhostname-abortcontroller)
-  * [`tangerine.resolveNs(hostname[, abortController]))`](#tangerineresolvenshostname-abortcontroller)
-  * [`tangerine.resolvePtr(hostname[, abortController]))`](#tangerineresolveptrhostname-abortcontroller)
-  * [`tangerine.resolveSoa(hostname[, abortController]))`](#tangerineresolvesoahostname-abortcontroller)
-  * [`tangerine.resolveSrv(hostname[, abortController]))`](#tangerineresolvesrvhostname-abortcontroller)
-  * [`tangerine.resolveTxt(hostname[, abortController]))`](#tangerineresolvetxthostname-abortcontroller)
-  * [`tangerine.reverse(ip[, abortController])`](#tangerinereverseip-abortcontroller)
+  * [`tangerine.resolveAny(hostname[, options, abortController])`](#tangerineresolveanyhostname-options-abortcontroller)
+  * [`tangerine.resolveCaa(hostname[, options, abortController]))`](#tangerineresolvecaahostname-options-abortcontroller)
+  * [`tangerine.resolveCname(hostname[, options, abortController]))`](#tangerineresolvecnamehostname-options-abortcontroller)
+  * [`tangerine.resolveMx(hostname[, options, abortController]))`](#tangerineresolvemxhostname-options-abortcontroller)
+  * [`tangerine.resolveNaptr(hostname[, options, abortController]))`](#tangerineresolvenaptrhostname-options-abortcontroller)
+  * [`tangerine.resolveNs(hostname[, options, abortController]))`](#tangerineresolvenshostname-options-abortcontroller)
+  * [`tangerine.resolvePtr(hostname[, options, abortController]))`](#tangerineresolveptrhostname-options-abortcontroller)
+  * [`tangerine.resolveSoa(hostname[, options, abortController]))`](#tangerineresolvesoahostname-options-abortcontroller)
+  * [`tangerine.resolveSrv(hostname[, options, abortController]))`](#tangerineresolvesrvhostname-options-abortcontroller)
+  * [`tangerine.resolveTxt(hostname[, options, abortController]))`](#tangerineresolvetxthostname-options-abortcontroller)
+  * [`tangerine.reverse(ip[, abortController, purgeCache])`](#tangerinereverseip-abortcontroller-purgecache)
   * [`tangerine.setDefaultResultOrder(order)`](#tangerinesetdefaultresultorderorder)
   * [`tangerine.setServers(servers)`](#tangerinesetserversservers)
 * [Options](#options)
@@ -97,7 +97,7 @@ Our team at [Forward Email](https://forwardemail.net) (100% open-source and priv
     * Once popular packages such as [native-dns](https://github.com/tjfontaine/node-dns/issues/111) and [dnscached](https://github.com/yahoo/dnscache/issues/28) are archived or deprecated.
     * [Other packages](https://www.npmjs.com/search?q=dns%20cache) only provide `lookup` functions, have a limited sub-set of methods such as [@zeit/dns-cached-resolver](https://github.com/vercel/dns-cached-resolve), or are unmaintained.
   * Act as a 1:1 drop-in replacement for `dns.promises.Resolver` with DNS over HTTPS ("DoH").
-  * Support caching for multiple backends (with TTL support), retries, smart server rotation, and [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) usage.
+  * Support caching for multiple backends (with TTL and purge support), retries, smart server rotation, and [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) usage.
   * Provide out of the box support for both ECMAScript modules (ESM) **and** CommonJS (CJS) (see discussions [for](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) and [against](https://gist.github.com/joepie91/bca2fda868c1e8b2c2caf76af7dfcad3)).
 * The native Node.js `dns` module does not support caching out of the box – which is a [highly requested feature](https://github.com/nodejs/node/issues/5893) (but belongs in userland).
 * Writing tests against DNS-related infrastructure requires either hacky DNS mocking or a DNS server (manipulating cache is much easier).
@@ -225,8 +225,11 @@ tangerine.resolve('forwardemail.net').then(console.log);
   * Specify default request options based off the library under `requestOptions` below
 * Instance methods of [dns.promises.Resolver](https://nodejs.org/api/dns.html) are mirrored to :tangerine: Tangerine.
 * Resolver methods accept an optional `abortController` argument, which is an instance of [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).  Note that :tangerine: Tangerine manages `AbortController` usage internally – so you most likely won't need to pass your own (see [index.js](https://github.com/forwardemail/tangerine/blob/main/index.js) for more insight).
-* See the complete list of [Options](#options) below.
+* Resolver methods that accept `options` argument also accept an optional `options.purgeCache` option.
+* Resolver methods support a `purgeCache` option as either `options.purgeCache` (Boolean) via `options` argument or `purgeCache` (Boolean) argument – see [API](#api) and [Cache](#cache) for more insight.
+  * If set to `true`, then the result will be re-queried and re-cached – see [Cache](#cache) documentation for more insight.
 * Instances of `new Tangerine()` are instances of `dns.promises.Resolver` via `class Tangerine extends dns.promises.Resolver { ... }` (namely for compatibility with projects such as [cacheable-lookup](https://github.com/szmarczak/cacheable-lookup)).
+* See the complete list of [Options](#options) below.
 
 ### `tangerine.cancel()`
 
@@ -234,7 +237,7 @@ tangerine.resolve('forwardemail.net').then(console.log);
 
 ### `tangerine.lookup(hostname[, options])`
 
-### `tangerine.lookupService(address, port, abortController)`
+### `tangerine.lookupService(address, port[, abortController, purgeCache])`
 
 ### `tangerine.resolve(hostname[, rrtype, options, abortController])`
 
@@ -246,27 +249,27 @@ Tangerine supports a new `ecsSubnet` property in the `options` Object argument.
 
 Tangerine supports a new `ecsSubnet` property in the `options` Object argument.
 
-### `tangerine.resolveAny(hostname[, abortController])`
+### `tangerine.resolveAny(hostname[, options, abortController])`
 
-### `tangerine.resolveCaa(hostname[, abortController]))`
+### `tangerine.resolveCaa(hostname[, options, abortController]))`
 
-### `tangerine.resolveCname(hostname[, abortController]))`
+### `tangerine.resolveCname(hostname[, options, abortController]))`
 
-### `tangerine.resolveMx(hostname[, abortController]))`
+### `tangerine.resolveMx(hostname[, options, abortController]))`
 
-### `tangerine.resolveNaptr(hostname[, abortController]))`
+### `tangerine.resolveNaptr(hostname[, options, abortController]))`
 
-### `tangerine.resolveNs(hostname[, abortController]))`
+### `tangerine.resolveNs(hostname[, options, abortController]))`
 
-### `tangerine.resolvePtr(hostname[, abortController]))`
+### `tangerine.resolvePtr(hostname[, options, abortController]))`
 
-### `tangerine.resolveSoa(hostname[, abortController]))`
+### `tangerine.resolveSoa(hostname[, options, abortController]))`
 
-### `tangerine.resolveSrv(hostname[, abortController]))`
+### `tangerine.resolveSrv(hostname[, options, abortController]))`
 
-### `tangerine.resolveTxt(hostname[, abortController]))`
+### `tangerine.resolveTxt(hostname[, options, abortController]))`
 
-### `tangerine.reverse(ip[, abortController])`
+### `tangerine.reverse(ip[, abortController, purgeCache])`
 
 ### `tangerine.setDefaultResultOrder(order)`
 
@@ -358,6 +361,19 @@ without cache: 98.25ms
 with cache: 0.091ms
 ```
 
+You can also force the cache to be purged and reset to a new value:
+
+```js
+await tangerine.resolve('forwardemail.net'); // cached
+await tangerine.resolve('forwardemail.net'); // uses cached value
+await tangerine.resolve('forwardemail.net'); // uses cached value
+await tangerine.resolve('forwardemail.net', { purgeCache: true }); // re-cached
+await tangerine.resolve('forwardemail.net'); // uses cached value
+await tangerine.resolve('forwardemail.net'); // uses cached value
+```
+
+This purge cache feature is useful for DNS records that have recently changed and have had their caches purged at the relevant DNS provider (e.g. [Cloudflare's Purge Cache tool](https://1.1.1.1/purge-cache/)).
+
 
 ## Debugging
 
@@ -385,10 +401,10 @@ npm install
 npm run benchmarks
 ```
 
-You can also specify optional custom environment variables to test against real-world or locally running servers (instead of using mocked in-memory servers):
+You can also specify optional custom environment variables to test against real-world or locally running servers (instead of using mocked in-memory servers) for the [HTTP Library Benchmarks](#http-library-benchmarks):
 
 ```sh
-BENCHMARK_PROTOCOL="http" BENCHMARK_HOST="127.0.0.1" BENCHMARK_PORT="4000" BENCHMARK_PATH="/v1/test" npm run benchmarks
+BENCHMARK_PROTOCOL="http" BENCHMARK_HOST="127.0.0.1" BENCHMARK_PORT="4000" BENCHMARK_PATH="/v1/test" node benchmarks/http
 ```
 
 ### Tangerine Benchmarks
@@ -400,7 +416,7 @@ The latest benchmark results are viewable on GitHub under this repository's [Git
 > [Node 16 on ubuntu-latest](https://github.com/forwardemail/tangerine/actions/runs/4297805550/jobs/7491228635#step:6:1)
 
 ```diff
-> node benchmarks/lookup && node benchmarks/resolve && node benchmarks/reverse
+node benchmarks/lookup && node benchmarks/resolve && node benchmarks/reverse
 
 Started: lookup
 tangerine.lookup POST with caching using Cloudflare x 735 ops/sec ±195.35% (88 runs sampled)
@@ -437,7 +453,7 @@ dns.promises.reverse with caching x 5,123,900 ops/sec ±0.96% (85 runs sampled)
 > [Node 18 on ubuntu latest](https://github.com/forwardemail/tangerine/actions/runs/4297805550/jobs/7491228742#step:6:1)
 
 ```diff
-> node benchmarks/lookup && node benchmarks/resolve && node benchmarks/reverse && node benchmarks/http
+node benchmarks/lookup && node benchmarks/resolve && node benchmarks/reverse && node benchmarks/http
 
 Started: lookup
 tangerine.lookup POST with caching using Cloudflare x 666 ops/sec ±195.48% (87 runs sampled)
@@ -482,10 +498,10 @@ Provided below are additional benchmark tests we have run:
 > Node v18.14.2 on MacBook Air M1 16GB (without VPN):
 
 ```diff
-> node --version
+node --version
 v18.14.2
 
-> node benchmarks/lookup && node benchmarks/resolve && node benchmarks/reverse
+node benchmarks/lookup && node benchmarks/resolve && node benchmarks/reverse
 
 Started: lookup
 tangerine.lookup POST with caching using Cloudflare x 1,035 ops/sec ±195.73% (91 runs sampled)
@@ -522,10 +538,10 @@ Fastest without caching is: dns.promises.reverse without caching, resolver.rever
 > Node v18.14.2 on MacBook Air M1 16GB (with DNS blackholed VPN) – **this highlights the DNS blackhole problem**:
 
 ```diff
-> node --version
+node --version
 v18.14.2
 
-> node benchmarks/lookup && node benchmarks/resolve && node benchmarks/reverse
+node benchmarks/lookup && node benchmarks/resolve && node benchmarks/reverse
 
 Started: lookup
 tangerine.lookup POST with caching using Cloudflare x 1,327 ops/sec ±195.65% (89 runs sampled)
@@ -570,7 +586,7 @@ Originally we wrote this library using [got](https://github.com/sindresorhus/got
 > Node v18.14.2 on MacBook Air M1 16GB (using real-world API server):
 
 ```sh
-> node --version
+node --version
 v18.14.2
 
 > BENCHMARK_HOST="127.0.0.1" BENCHMARK_PORT="4000" BENCHMARK_PATH="/v1/test" node benchmarks/http

package/index.js

@@ -7,6 +7,7 @@ const { debuglog } = require('node:util');
 const { getEventListeners, setMaxListeners } = require('node:events');
 const { isIP, isIPv4, isIPv6 } = require('node:net');
 
+const { toASCII } = require('punycode/');
 const getStream = require('get-stream');
 const ipaddr = require('ipaddr.js');
 const mergeOptions = require('merge-options');
@@ -464,7 +465,7 @@ class Tangerine extends dns.promises.Resolver {
 
       options = { family: options };
     } else if (
-      typeof options.family !== 'undefined' &&
+      typeof options?.family !== 'undefined' &&
       ![0, 4, 6, 'IPv4', 'IPv6'].includes(options.family)
     ) {
       // validate family
@@ -475,12 +476,12 @@ class Tangerine extends dns.promises.Resolver {
       throw err;
     }
 
-    if (options.family === 'IPv4') options.family = 4;
-    else if (options.family === 'IPv6') options.family = 6;
+    if (options?.family === 'IPv4') options.family = 4;
+    else if (options?.family === 'IPv6') options.family = 6;
 
     // validate hints
     // eslint-disable-next-line no-bitwise
-    if ((options.hints & ~(dns.ADDRCONFIG | dns.ALL | dns.V4MAPPED)) !== 0) {
+    if ((options?.hints & ~(dns.ADDRCONFIG | dns.ALL | dns.V4MAPPED)) !== 0) {
       const err = new TypeError(
         `The argument 'hints' is invalid. Received ${options.hints}`
       );
@@ -488,16 +489,55 @@ class Tangerine extends dns.promises.Resolver {
       throw err;
     }
 
-    // resolve the first A or AAAA record
+    // purge cache support
+    let purgeCache;
+    if (options?.purgeCache) {
+      purgeCache = true;
+      delete options.purgeCache;
+    }
+
+    if (options.hints) {
+      switch (options.hints) {
+        case dns.ADDRCONFIG: {
+          options.family = this.constructor.getAddrConfigTypes();
+          break;
+        }
+
+        // eslint-disable-next-line no-bitwise
+        case dns.ADDRCONFIG | dns.V4MAPPED: {
+          options.family = this.constructor.getAddrConfigTypes();
+          break;
+        }
+
+        // eslint-disable-next-line no-bitwise
+        case dns.ADDRCONFIG | dns.V4MAPPED | dns.ALL: {
+          options.family = this.constructor.getAddrConfigTypes();
+
+          break;
+        }
+
+        default: {
+          break;
+        }
+      }
+    }
+
+    // resolve the first A or AAAA record (conditionally)
     let answers = [];
 
     try {
-      answers = await Promise.any([
-        this.resolve4(name),
-        // the only downside here is that if one succeeds the other won't be aborted
-        // (an alternative approach could be implemented, but would have to wrap around ENOTFOUND err
-        this.resolve6(name)
+      // `any` or `all` is based off !options.family || options.family === 0
+      // (according to official nodejs dns.lookup docs)
+      answers = await Promise[
+        typeof options.family === 'undefined' || options.family === 0
+          ? 'all'
+          : 'any'
+      ]([
+        // the only downside here is that if one succeeds the other won't be aborted (iff "any")
+        this.resolve4(name, { purgeCache, noThrowOnNODATA: true }),
+        this.resolve6(name, { purgeCache, noThrowOnNODATA: true })
       ]);
+      answers = answers.flat();
     } catch (_err) {
       debug(_err);
 
@@ -522,9 +562,18 @@ class Tangerine extends dns.promises.Resolver {
       throw err;
     }
 
+    // if no results then throw ENODATA
+    if (answers.length === 0) {
+      const err = this.constructor.createError(name, '', dns.NODATA);
+      // remap and perform syscall
+      err.syscall = 'getaddrinfo';
+      // err.errno = -3008;
+      throw err;
+    }
+
     // respect options from dns module
     // <https://nodejs.org/api/dns.html#dnspromiseslookuphostname-options>
-    // - [x]: `family` (4, 6, or 0, default is 0)
+    // - [x] `family` (4, 6, or 0, default is 0)
     // - [x] `hints` multiple flags may be passed by bitwise OR'ing values
     // - [x] `all` (iff true, then return all results, otherwise single result)
     // - [x] `verbatim` - if `true` then return as-is, otherwise use dns order
@@ -541,14 +590,8 @@ class Tangerine extends dns.promises.Resolver {
     // dns.ALL:
     //   If dns.V4MAPPED is specified, return resolved IPv6 addresses as well as IPv4 mapped IPv6 addresses.
     //
-    const { hints } = options;
-    if (hints) {
-      switch (hints) {
-        case dns.ADDRCONFIG: {
-          options.family = this.constructor.getAddrConfigTypes();
-          break;
-        }
-
+    if (options.hints) {
+      switch (options.hints) {
         case dns.V4MAPPED: {
           if (options.family === 6 && !answers.some((answer) => isIPv6(answer)))
             answers = answers.map((answer) =>
@@ -564,7 +607,6 @@ class Tangerine extends dns.promises.Resolver {
 
         // eslint-disable-next-line no-bitwise
         case dns.ADDRCONFIG | dns.V4MAPPED: {
-          options.family = this.constructor.getAddrConfigTypes();
           if (options.family === 6 && !answers.some((answer) => isIPv6(answer)))
             answers = answers.map((answer) =>
               ipaddr.parse(answer).toIPv4MappedAddress().toString()
@@ -584,7 +626,6 @@ class Tangerine extends dns.promises.Resolver {
 
         // eslint-disable-next-line no-bitwise
         case dns.ADDRCONFIG | dns.V4MAPPED | dns.ALL: {
-          options.family = this.constructor.getAddrConfigTypes();
           if (options.family === 6 && !answers.some((answer) => isIPv6(answer)))
             answers = answers.map((answer) =>
               ipaddr.parse(answer).toIPv4MappedAddress().toString()
@@ -605,9 +646,20 @@ class Tangerine extends dns.promises.Resolver {
     else if (options.family === 6)
       answers = answers.filter((answer) => isIPv6(answer));
 
+    //
     // respect sort order from `setDefaultResultOrder` method
-    if (options.verbatim !== true && this.options.dnsOrder === 'ipv4first')
-      answers = answers.sort((answer) => (isIPv4(answer) ? 0 : 1));
+    //
+    // NOTE: we need to optimize this sort logic at some point
+    //
+    if (options.verbatim !== true && this.options.dnsOrder === 'ipv4first') {
+      answers = answers.sort((a, b) => {
+        const aFamily = isIP(a);
+        const bFamily = isIP(b);
+        if (aFamily < bFamily) return -1;
+        if (aFamily > bFamily) return 1;
+        return 0;
+      });
+    }
 
     return options.all === true
       ? answers.map((answer) => ({
@@ -618,7 +670,7 @@ class Tangerine extends dns.promises.Resolver {
   }
 
   // <https://man7.org/linux/man-pages/man3/getnameinfo.3.html>
-  async lookupService(address, port, abortController) {
+  async lookupService(address, port, abortController, purgeCache = false) {
     if (!address || !port) {
       const err = new TypeError(
         'The "address" and "port" arguments must be specified.'
@@ -647,7 +699,11 @@ class Tangerine extends dns.promises.Resolver {
 
     // reverse lookup
     try {
-      const [hostname] = await this.reverse(address, abortController);
+      const [hostname] = await this.reverse(
+        address,
+        abortController,
+        purgeCache
+      );
       return { hostname, service: name };
     } catch (err) {
       err.syscall = 'getnameinfo';
@@ -655,7 +711,7 @@ class Tangerine extends dns.promises.Resolver {
     }
   }
 
-  async reverse(ip, abortController) {
+  async reverse(ip, abortController, purgeCache = false) {
     // basically reverse the IP and then perform PTR lookup
     if (typeof ip !== 'string') {
       const err = new TypeError('The "ip" argument must be of type string.');
@@ -677,7 +733,12 @@ class Tangerine extends dns.promises.Resolver {
 
     // perform resolvePTR
     try {
-      const answers = await this.resolve(name, 'PTR', {}, abortController);
+      const answers = await this.resolve(
+        name,
+        'PTR',
+        { purgeCache },
+        abortController
+      );
       return answers;
     } catch (err) {
       // remap syscall
@@ -699,40 +760,40 @@ class Tangerine extends dns.promises.Resolver {
     return this.resolve(name, 'AAAA', options, abortController);
   }
 
-  resolveCaa(name, abortController) {
-    return this.resolve(name, 'CAA', {}, abortController);
+  resolveCaa(name, options, abortController) {
+    return this.resolve(name, 'CAA', options, abortController);
   }
 
-  resolveCname(name, abortController) {
-    return this.resolve(name, 'CNAME', {}, abortController);
+  resolveCname(name, options, abortController) {
+    return this.resolve(name, 'CNAME', options, abortController);
   }
 
-  resolveMx(name, abortController) {
-    return this.resolve(name, 'MX', {}, abortController);
+  resolveMx(name, options, abortController) {
+    return this.resolve(name, 'MX', options, abortController);
   }
 
-  resolveNaptr(name, abortController) {
-    return this.resolve(name, 'NAPTR', {}, abortController);
+  resolveNaptr(name, options, abortController) {
+    return this.resolve(name, 'NAPTR', options, abortController);
   }
 
-  resolveNs(name, abortController) {
-    return this.resolve(name, 'NS', {}, abortController);
+  resolveNs(name, options, abortController) {
+    return this.resolve(name, 'NS', options, abortController);
   }
 
-  resolvePtr(name, abortController) {
-    return this.resolve(name, 'PTR', {}, abortController);
+  resolvePtr(name, options, abortController) {
+    return this.resolve(name, 'PTR', options, abortController);
   }
 
-  resolveSoa(name, abortController) {
-    return this.resolve(name, 'SOA', {}, abortController);
+  resolveSoa(name, options, abortController) {
+    return this.resolve(name, 'SOA', options, abortController);
   }
 
-  resolveSrv(name, abortController) {
-    return this.resolve(name, 'SRV', {}, abortController);
+  resolveSrv(name, options, abortController) {
+    return this.resolve(name, 'SRV', options, abortController);
   }
 
-  resolveTxt(name, abortController) {
-    return this.resolve(name, 'TXT', {}, abortController);
+  resolveTxt(name, options, abortController) {
+    return this.resolve(name, 'TXT', options, abortController);
   }
 
   // 1:1 mapping with node's official dns.promises API
@@ -789,7 +850,13 @@ class Tangerine extends dns.promises.Resolver {
   // eslint-disable-next-line complexity
   async #query(name, rrtype = 'A', ecsSubnet, abortController) {
     if (!dohdec) await pWaitFor(() => Boolean(dohdec));
-    debug('query', { name, rrtype, ecsSubnet, abortController });
+    debug('query', {
+      name,
+      nameToASCII: toASCII(name),
+      rrtype,
+      ecsSubnet,
+      abortController
+    });
     // <https://github.com/hildjj/dohdec/blob/43564118c40f2127af871bdb4d40f615409d4b9c/pkg/dohdec/lib/dnsUtils.js#L161>
     const pkt = dohdec.DNSoverHTTPS.makePacket({
       id:
@@ -797,7 +864,8 @@ class Tangerine extends dns.promises.Resolver {
           ? await this.options.id()
           : this.options.id,
       rrtype,
-      name,
+      // mirrors dns module behavior
+      name: toASCII(name),
       // <https://github.com/mafintosh/dns-packet/pull/47#issuecomment-1435818437>
       ecsSubnet
     });
@@ -932,7 +1000,7 @@ class Tangerine extends dns.promises.Resolver {
     }
   }
 
-  #resolveByType(name, parentAbortController) {
+  #resolveByType(name, options = {}, parentAbortController) {
     return async (type) => {
       const abortController = new AbortController();
       this.abortControllers.add(abortController);
@@ -956,7 +1024,7 @@ class Tangerine extends dns.promises.Resolver {
           case 'A': {
             const result = await this.resolve4(
               name,
-              { ttl: true },
+              { ...options, ttl: true },
               abortController
             );
             return result.map((r) => ({ type, ...r }));
@@ -965,49 +1033,73 @@ class Tangerine extends dns.promises.Resolver {
           case 'AAAA': {
             const result = await this.resolve6(
               name,
-              { ttl: true },
+              { ...options, ttl: true },
               abortController
             );
             return result.map((r) => ({ type, ...r }));
           }
 
           case 'CNAME': {
-            const result = await this.resolveCname(name, abortController);
+            const result = await this.resolveCname(
+              name,
+              options,
+              abortController
+            );
             return result.map((value) => ({ type, value }));
           }
 
           case 'MX': {
-            const result = await this.resolveMx(name, abortController);
+            const result = await this.resolveMx(name, options, abortController);
             return result.map((r) => ({ type, ...r }));
           }
 
           case 'NAPTR': {
-            const result = await this.resolveNaptr(name, abortController);
+            const result = await this.resolveNaptr(
+              name,
+              options,
+              abortController
+            );
             return result.map((value) => ({ type, value }));
           }
 
           case 'NS': {
-            const result = await this.resolveNs(name, abortController);
+            const result = await this.resolveNs(name, options, abortController);
             return result.map((value) => ({ type, value }));
           }
 
           case 'PTR': {
-            const result = await this.resolvePtr(name, abortController);
+            const result = await this.resolvePtr(
+              name,
+              options,
+              abortController
+            );
             return result.map((value) => ({ type, value }));
           }
 
           case 'SOA': {
-            const result = await this.resolveSoa(name, abortController);
+            const result = await this.resolveSoa(
+              name,
+              options,
+              abortController
+            );
             return { type, ...result };
           }
 
           case 'SRV': {
-            const result = await this.resolveSrv(name, abortController);
+            const result = await this.resolveSrv(
+              name,
+              options,
+              abortController
+            );
             return result.map((value) => ({ type, value }));
           }
 
           case 'TXT': {
-            const result = await this.resolveTxt(name, abortController);
+            const result = await this.resolveTxt(
+              name,
+              options,
+              abortController
+            );
             return result.map((entries) => ({ type, entries }));
           }
 
@@ -1025,7 +1117,7 @@ class Tangerine extends dns.promises.Resolver {
   }
 
   // <https://nodejs.org/api/dns.html#dnspromisesresolveanyhostname>
-  async resolveAny(name, abortController) {
+  async resolveAny(name, options = {}, abortController) {
     if (typeof name !== 'string') {
       const err = new TypeError('The "name" argument must be of type string.');
       err.code = 'ERR_INVALID_ARG_TYPE';
@@ -1056,7 +1148,7 @@ class Tangerine extends dns.promises.Resolver {
 
     const results = await pMap(
       this.constructor.ANY_TYPES,
-      this.#resolveByType(name, abortController),
+      this.#resolveByType(name, options, abortController),
       // <https://developers.cloudflare.com/fundamentals/api/reference/limits/>
       { concurrency: this.options.concurrency, signal: abortController.signal }
     );
@@ -1114,9 +1206,16 @@ class Tangerine extends dns.promises.Resolver {
       throw err;
     }
 
+    // purge cache support
+    let purgeCache;
+    if (options?.purgeCache) {
+      purgeCache = true;
+      delete options.purgeCache;
+    }
+
     // ecsSubnet support
     let ecsSubnet;
-    if (options.ecsSubnet) {
+    if (options?.ecsSubnet) {
       ecsSubnet = options.ecsSubnet;
       delete options.ecsSubnet;
     }
@@ -1127,7 +1226,7 @@ class Tangerine extends dns.promises.Resolver {
 
     let result;
     let data;
-    if (this.options.cache) {
+    if (this.options.cache && !purgeCache) {
       //
       // NOTE: we store `result.ttl` which was the lowest TTL determined
       //       (this saves us from duplicating the same `...sort().filter(Number.isFinite)` logic)
@@ -1309,7 +1408,8 @@ class Tangerine extends dns.promises.Resolver {
     }
 
     // if no results then throw ENODATA
-    if (result.answers.length === 0)
+    // (hidden option for `lookup` to prevent errors being thrown)
+    if (result.answers.length === 0 && !options.noThrowOnNODATA)
       throw this.constructor.createError(name, rrtype, dns.NODATA);
 
     // filter the answers for the same type

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tangerine",
-  "description": "Tangerine is the best Node.js drop-in replacement for dns.promises.Resolver using DNS over HTTPS (\"DoH\") via undici with built-in retries, timeouts, smart server rotation, AbortControllers, and caching support for multiple backends (with TTL support).",
-  "version": "1.3.0",
+  "description": "Tangerine is the best Node.js drop-in replacement for dns.promises.Resolver using DNS over HTTPS (\"DoH\") via undici with built-in retries, timeouts, smart server rotation, AbortControllers, and caching support for multiple backends (with TTL and purge support).",
+  "version": "1.4.0",
   "author": "Forward Email (https://forwardemail.net)",
   "bugs": {
     "url": "https://github.com/forwardemail/tangerine/issues"
@@ -20,6 +20,7 @@
     "p-timeout": "4",
     "p-wait-for": "3",
     "port-numbers": "^6.0.1",
+    "punycode": "^2.3.0",
     "semver": "^7.3.8"
   },
   "devDependencies": {