cacheable-lookup

What is cacheable-lookup?

The cacheable-lookup npm package is designed to enhance the Node.js DNS module with caching capabilities. It provides a way to cache DNS lookup results in order to improve performance for repeated DNS queries. This is particularly useful for applications making numerous requests to the same domains, as it reduces the number of DNS queries that need to be performed over the network.

What are cacheable-lookup's main functionalities?

Caching DNS lookups

This feature allows you to cache DNS lookups to improve performance. The code sample demonstrates how to perform a DNS lookup for 'example.com' and cache the result.

const CacheableLookup = require('cacheable-lookup');
const cacheable = new CacheableLookup();
cacheable.lookup('example.com', (err, address, family) => {
  console.log(address);
});

Integration with http.Agent

This feature demonstrates how cacheable-lookup can be integrated with Node.js http.Agent to automatically use cached DNS lookups for HTTP requests. This can significantly reduce DNS lookup times for repeated requests to the same domain.

const CacheableLookup = require('cacheable-lookup');
const http = require('http');
const cacheable = new CacheableLookup();
const agent = new http.Agent({
  lookup: cacheable.lookup
});
http.get('http://example.com', { agent }, (res) => {
  // Handle response
});

Other packages similar to cacheable-lookup

dns-cache

dns-cache is a simple DNS cache module. It provides basic caching functionalities similar to cacheable-lookup but lacks some of the advanced features and customizability options such as integration with http.Agent.

README

cacheable-lookup

A cacheable dns.lookup(…) that respects the TTL :tada:

Making lots of HTTP requests? You can save some time by caching DNS lookups.
Don't worry, this package respects the TTL :smiley:

Usage

const CacheableLookup = require('cacheable-lookup');
const cacheable = new CacheableLookup();

http.get('https://example.com', {lookup: cacheable.lookup}, response => {
	// Handle the response here
});

API

new CacheableLookup(options)

Returns a new instance of CacheableLookup.

options

Type: Object
Default: {}

Options used to cache the DNS lookups.

options.cacheAdapter

Type: Keyv adapter instance
Default: new Map()

A Keyv adapter which stores the cache.

options.maxTtl

Type: number
Default: Infinity

Limits the cache time (TTL).

If set to 0, it will make a new DNS query each time.

options.resolver

Type: Function
Default: new dns.Resolver()

An instance of DNS Resolver used to make DNS queries.

Entry object

Type: Object

address

Type: string

The IP address (can be an IPv4 or IPv6 address).

family

Type: number

The IP family (4 or 6).

CacheableLookup instance

servers

Type: Array

DNS servers used to make the query. Can be overridden - then the new servers will be used.

lookup(hostname, options, callback)

lookupAsync(hostname, options)

The asynchronous version of dns.lookup(…).

Returns an entry object.
If options.all is true, returns an array of entry objects.

Note: If entry(ies) were not found, it will return undefined.

hostname

Type: string

options

Type: Object

The same as the dns.lookup(…) options.

options.throwNotFound

Type: boolean
Default: false

Throw when there's no match.

If set to false and it gets no match, it will return undefined.

Note: This option is meant only for the asynchronous implementation! The synchronous version will always throw an error if no match found.

options.details

Type: boolean
Default: false

If true the entries returned by lookup(…) and lookupAsync(…) will have additional expires and ttl properties representing the expiration timestamp and the original TTL.

query(hostname, family)

An asynchronous function which returns cached DNS lookup entries. This is the base for lookupAsync(hostname, options) and lookup(hostname, options, callback).

Note: This function has no options.

Returns an array of objects with address, family, ttl and expires properties.

queryAndCache(hostname, family)

An asynchronous function which makes a new DNS lookup query and updates the database. This is used by query(hostname, family) if no entry in the database is present.

Returns an array of objects with address, family, ttl and expires properties.

High performance

See the benchmarks (queries localhost, performed on i7-7700k):

CacheableLookup#lookupAsync            x 219,396 ops/sec ±0.69%  (285 runs sampled)
CacheableLookup#lookup                 x 219,296 ops/sec ±0.20%  (284 runs sampled)
CacheableLookup#lookupAsync - zero TTL x 27.67   ops/sec ±51.06% (246 runs sampled)
CacheableLookup#lookup      - zero TTL x 29.64   ops/sec ±49.60% (204 runs sampled)
dns#resolve4                           x 27.03   ops/sec ±41.64% (246 runs sampled)
dns#lookup                             x 5,994   ops/sec ±0.26%  (285 runs sampled)
Fastest is CacheableLookup#lookup

The package is based on dns.resolve4(…) and dns.resolve6(…).

Why not dns.lookup(…)?

It is not possible to use dns.lookup(…) because underlying calls like getaddrinfo have no concept of servers or TTL (caching is done on OS level instead).

Related

• cacheable-request - Wrap native HTTP requests with RFC compliant cache support

License

MIT