cacheable-lookup

A cacheable dns.lookup(…) that respects TTL 🎉

Making lots of HTTP requests? You can save some time by caching DNS lookups ⚡

Usage

Using the lookup option

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

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

Attaching CacheableLookup to an Agent

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

cacheable.install(http.globalAgent);

http.get('https://example.com', 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.maxTtl

Type: number
Default: Infinity

Limits the cache time (TTL in seconds).

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

options.resolver

Type: dns.Resolver | dns.promises.Resolver
Default: new dns.promises.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).

expires

Type: number

Note: This is not present when using the native dns.lookup(...)!

The timestamp (Date.now() + ttl * 1000) when the entry expires.

ttl

Note: This is not present when using the native dns.lookup(...)!

The time in seconds for its lifetime.

Entry object (callback-style)

When options.all is false, then callback(error, address, family, expires, ttl) is called.
When options.all is true, then callback(error, entries) is called.

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 by default.

hostname

Type: string

options

Type: object

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

options.throwNotFound

Type: boolean
Default: false

If set to false and it gets no match, it will return undefined. If set to true and it gets no match, it will throw ENOTFOUND error.

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

query(hostname)

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)

An asynchronous function which makes two DNS queries: A and AAAA. The result is cached.
This is used by query(hostname) if no entry in the database is present.

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

updateInterfaceInfo()

Updates interface info. For example, you need to run this when you plug or unplug your WiFi driver.

Note: Running updateInterfaceInfo() will also trigger clear()!

clear()

Clears the cache.

High performance

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

CacheableLookup#lookupAsync                x 2,525,219 ops/sec ±1.66%  (86 runs sampled)
CacheableLookup#lookupAsync.all            x 2,648,106 ops/sec ±0.59%  (88 runs sampled)
CacheableLookup#lookupAsync.all.ADDRCONFIG x 2,263,173 ops/sec ±0.95%  (88 runs sampled)
CacheableLookup#lookup                     x 2,108,952 ops/sec ±0.97%  (89 runs sampled)
CacheableLookup#lookup.all                 x 2,081,357 ops/sec ±1.19%  (83 runs sampled)
CacheableLookup#lookup.all.ADDRCONFIG      x 1,913,955 ops/sec ±0.60%  (89 runs sampled)
CacheableLookup#lookupAsync - zero TTL     x 36.50     ops/sec ±11.21% (39 runs sampled)
CacheableLookup#lookup - zero TTL          x 33.66     ops/sec ±7.57%  (47 runs sampled)
dns#resolve4                               x 40.31     ops/sec ±16.10% (49 runs sampled)
dns#lookup                                 x 13,722    ops/sec ±20.69% (37 runs sampled)
dns#lookup.all                             x 30,343    ops/sec ±28.97% (47 runs sampled)
dns#lookup.all.ADDRCONFIG                  x 7,023     ops/sec ±15.86% (31 runs sampled)
Fastest is CacheableLookup#lookupAsync.all

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