DNS Cache for Node.js

Common errors

• TypeError: dnscache is not a function

  cause Attempting to import `dnscache` using ECMAScript Modules (ESM) syntax (e.g., `import dnscache from 'dnscache'`).
  fix Use CommonJS `require` syntax: `const dnscache = require('dnscache');`

• Error: getaddrinfo ENOTFOUND www.example.com

  cause While using `dnscache`, receiving ENOTFOUND errors, potentially due to DNS resolution issues or (less commonly) stale cache entries if a domain's IP changed but the cache was not updated.
  fix Check network connectivity and DNS server configuration. If suspecting stale cache, reduce `ttl` or explicitly clear the cache if the library supports it (though `dnscache` does not expose a public cache clearing API, it relies on TTL expiration). The library configuration includes `ttl` and `cachesize` parameters.

• UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch().

  cause `dnscache` is callback-based and does not return Promises. This warning indicates a misuse in an `async/await` context or an attempt to chain `.then()`/`.catch()` on a non-Promise return.
  fix Ensure `dnscache` methods are used with callbacks, e.g., `dnscache.lookup('host', (err, result) => { /* handle */ });`. If you need Promise-based DNS resolution, consider `node:dns/promises` or other modern alternatives.

Warnings

• breaking The `dnscache` package is abandoned, with its last publish date 7 years ago (April 22, 2019). It is not actively maintained, which poses security risks, compatibility issues with newer Node.js versions, and a lack of support for modern DNS features or practices.
  Fix: Consider migrating to actively maintained DNS caching libraries like `cacheable-lookup` or application-level DNS resolution solutions (e.g., `tangerine`) that are compatible with modern Node.js versions and ESM, or leverage system-level DNS caching solutions.
• breaking This module alters the error handling behavior of Node.js's built-in `dns` functions. While original `dns` functions might throw errors in certain situations, `dnscache` intercepts these and passes all errors as the first argument to the callback function, standardizing error propagation. Developers expecting synchronous throws might encounter unexpected behavior.
  Fix: Always handle errors as the first argument in callback functions when using `dnscache` (e.g., `function(err, result) { if (err) { /* handle error */ } }`). Review your error handling logic for any code paths that might rely on synchronous `dns` throws.
• gotcha Setting a high `ttl` (Time-To-Live) for cache entries can lead to stale DNS information if the IP addresses for a domain change. This can result in your application attempting to connect to an old, incorrect IP, leading to connection errors or service unavailability.
  Fix: Carefully configure the `ttl` based on the expected volatility of your target domains' DNS records. Lower TTLs offer better consistency but might increase cache misses. Ensure proper monitoring for DNS resolution failures.

Install

• npm install dnscache npm
• yarn add dnscache yarn
• pnpm add dnscache pnpm

Imports

• dnscache
  wrong:

  import dnscache from 'dnscache';

  correct:

  const dnscache = require('dnscache');

  This package is CommonJS-only and does not support ESM imports.
• dns
  wrong:

  import * as dns from 'dns';

  correct:

  const dns = require('dns');

  After initializing `dnscache`, subsequent `require('dns')` calls will also return the wrapped, cached DNS module.
• Configuration options

  dnscache({
    "enable": true,
    "ttl": 300,
    "cachesize": 1000
  });

  The module is configured by calling the imported `dnscache` function directly with an options object.

Quickstart

This quickstart demonstrates how to enable `dnscache` and use both the `dnscache` instance and the wrapped `dns` module for hostname lookups, showcasing the transparent caching mechanism.

const dns = require('dns');
const dnscache = require('dnscache')({
    "enable": true,
    "ttl": 300,
    "cachesize": 1000
});

console.log('DNS Caching enabled with TTL:', dnscache.ttl, 'and cache size:', dnscache.cachesize);

// Using the dnscache instance directly
dnscache.lookup('www.yahoo.com', function(err, result) {
    if (err) {
        console.error('Yahoo lookup error:', err.message);
        return;
    }
    console.log('Lookup www.yahoo.com (via dnscache.lookup):', result);
});

// Using the wrapped 'dns' module
dns.lookup('www.google.com', function(err, result) {
    if (err) {
        console.error('Google lookup error:', err.message);
        return;
    }
    console.log('Lookup www.google.com (via wrapped dns.lookup):', result);
});

// Example of a second lookup to demonstrate caching (though output won't show it directly)
setTimeout(() => {
    dnscache.lookup('www.yahoo.com', function(err, result) {
        if (err) {
            console.error('Second Yahoo lookup error:', err.message);
            return;
        }
        console.log('Second lookup www.yahoo.com (should be cached):', result);
    });
}, 500);

// To prevent the process from exiting immediately for async operations
setTimeout(() => console.log('Exiting example.'), 2000);