A cacheable
dns.lookup(…)that respects TTL 🎉
Making lots of HTTP requests? You can save some time by caching DNS lookups ⚡
const http = require('http');
const CacheableLookup = require('cacheable-lookup');
const cacheable = new CacheableLookup();
http.get('http://example.com', {lookup: cacheable.lookup}, response => {
// Handle the response here
});const http = require('http');
const CacheableLookup = require('cacheable-lookup');
const cacheable = new CacheableLookup();
cacheable.install(http.globalAgent);
http.get('http://example.com', response => {
// Handle the response here
});Returns a new instance of CacheableLookup.
Type: Map | Keyv
Default: new Map()
Custom cache instance. If undefined, it will create a new one.
Note: If you decide to use Keyv instead of the native implementation, the performance will drop by 10x. Memory leaks may occur as it doesn't provide any way to remove all the deprecated values at once.
Type: object
Default: {}
Options used to cache the DNS lookups.
Type: number
Default: Infinity
The maximum lifetime of the entries received from the specifed DNS server (TTL in seconds).
If set to 0, it will make a new DNS query each time.
Pro Tip: This shouldn't be lower than your DNS server response time in order to prevent bottlenecks. For example, if you use Cloudflare, this value should be greater than 0.01.
Type: number
Default: 1
The lifetime of the entries received from the OS (TTL in seconds).
Note: This option is independent, options.maxTtl does not affect this.
Pro Tip: This shouldn't be lower than your DNS server response time in order to prevent bottlenecks. For example, if you use Cloudflare, this value should be greater than 0.01.
Type: number
Default: 0.15
The time how long it needs to remember queries that threw ENOTFOUND (TTL in seconds).
Note: This option is independent, options.maxTtl does not affect this.
Pro Tip: This shouldn't be lower than your DNS server response time in order to prevent bottlenecks. For example, if you use Cloudflare, this value should be greater than 0.01.
Type: dns.Resolver | dns.promises.Resolver
Default: new dns.promises.Resolver()
An instance of DNS Resolver used to make DNS queries.
Type: string
Default: undefined (OS-specific)
The full path to the hosts file. Set this to false to prevent loading entries from the hosts file.
Type: object
Type: string
The IP address (can be an IPv4 or IPv6 address).
Type: number
The IP family (4 or 6).
Type: number
Note: This is not present when using the native dns.lookup(...)!
The timestamp (Date.now() + ttl * 1000) when the entry expires.
Note: This is not present when using the native dns.lookup(...)!
The time in seconds for its lifetime.
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.
Type: Array
The DNS servers used to make queries. Can be overridden - doing so will trigger cacheableLookup.updateInterfaceInfo().
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.
Type: string
Type: object
The same as the dns.lookup(…) options.
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.
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.
Deprecated - it is a noop. Outdated entries are removed automatically.
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()!
Clears the cache for the given hostname. If the hostname argument is not present, the entire cache will be cleared.
Performed on:
- Query:
example.com - CPU: i7-7700k
- CPU governor: performance
CacheableLookup#lookupAsync x 2,421,707 ops/sec ±1.11% (86 runs sampled)
CacheableLookup#lookupAsync.all x 2,338,741 ops/sec ±1.74% (84 runs sampled)
CacheableLookup#lookupAsync.all.ADDRCONFIG x 2,238,534 ops/sec ±0.94% (89 runs sampled)
CacheableLookup#lookup x 2,298,645 ops/sec ±1.26% (87 runs sampled)
CacheableLookup#lookup.all x 2,260,194 ops/sec ±1.49% (87 runs sampled)
CacheableLookup#lookup.all.ADDRCONFIG x 2,133,142 ops/sec ±1.52% (86 runs sampled)
dns#lookup x 7,272 ops/sec ±0.36% (86 runs sampled)
dns#lookup.all x 7,249 ops/sec ±0.40% (86 runs sampled)
dns#lookup.all.ADDRCONFIG x 5,693 ops/sec ±0.28% (85 runs sampled)
Fastest is CacheableLookup#lookupAsync.all
The package is based on dns.resolve4(…) and dns.resolve6(…).
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).
- cacheable-request - Wrap native HTTP requests with RFC compliant cache support
MIT
