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

A cacheable dns.lookup(…) that respects TTL

sindresorhus

szmarczak

cacheable-lookup

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

import {Resolver, promises as dnsPromises, lookup} from 'dns';

type AsyncResolver = dnsPromises.Resolver;

set(hostname: string, entries: EntryObject[], ttl: number): TPromise<void | boolean | this>;

get(hostname: string): TPromise<EntryObject[] | undefined>;

delete(hostname: string): TPromise<boolean>;

	 * Custom cache instance. If `undefined`, it will create a new one.

	 * Limits the cache time (TTL). If set to `0`, it will make a new DNS query each time.

	 * DNS Resolver used to make DNS queries.

	 * When the DNS server responds with `ENOTFOUND` or `ENODATA` and the OS reports that the entry is available,

	 * it will use `dns.lookup(...)` directly for the requested hostnames for the specified amount of time (in seconds).

	 * If you don't query internal hostnames (such as `localhost`, `database.local` etc.),

	 * it is strongly recommended to set this value to `0`.

	 * The time how long it needs to remember failed queries (TTL in seconds).

	 * **Note**: This option is independent, `options.maxTtl` does not affect this.

	 * The fallback function to use when the DNS server responds with `ENOTFOUND` or `ENODATA`.

	 * **Note**: This has no effect if the `fallbackDuration` option is less than `1`.

	 * The IP address (can be an IPv4 or IPv5 address).

	 * One or more supported getaddrinfo flags. Multiple flags may be passed by bitwise ORing their values.

	 * The record family. Must be `4` or `6`. IPv4 and IPv6 addresses are both returned by default.

	 * When `true`, the callback returns all resolved addresses in an array. Otherwise, returns a single address.

	 * The DNS servers used to make queries. Can be overridden - doing so will clear the cache.

	 * @see https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback

	lookup(hostname: string, family: IPFamily, callback: (error: NodeJS.ErrnoException, address: string, family: IPFamily) => void): void;

	lookup(hostname: string, callback: (error: NodeJS.ErrnoException, address: string, family: IPFamily) => void): void;

lookup(hostname: string, options: LookupOptions & {all: true}, callback: (error: NodeJS.ErrnoException, result: ReadonlyArray<EntryObject>) => void): void;

	lookup(hostname: string, options: LookupOptions, callback: (error: NodeJS.ErrnoException, address: string, family: IPFamily) => void): void;

	 * The asynchronous version of `dns.lookup(…)`.

lookupAsync(hostname: string, options: LookupOptions & {all: true}): Promise<ReadonlyArray<EntryObject>>;

lookupAsync(hostname: string, options: LookupOptions): Promise<EntryObject>;

lookupAsync(hostname: string): Promise<EntryObject>;

lookupAsync(hostname: string, family: IPFamily): Promise<EntryObject>;

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

query(hostname: string): Promise<ReadonlyArray<EntryObject>>;

	 * 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.

queryAndCache(hostname: string): Promise<ReadonlyArray<EntryObject>>;

	 * Attaches itself to an Agent instance.

	 * Removes itself from an Agent instance.

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

	 * **Note:** Running `updateInterfaceInfo()` will trigger `clear()` only on network interface removal.

	 * Clears the cache for the given hostname. If the hostname argument is not present, the entire cache will be emptied.

  "description": "A cacheable dns.lookup(…) that respects the TTL",

    "test": "xo && nyc --reporter=lcovonly --reporter=text ava && tsd"

    "url": "git+https://github.com/szmarczak/cacheable-lookup.git"

    "url": "https://github.com/szmarczak/cacheable-lookup/issues"

  "homepage": "https://github.com/szmarczak/cacheable-lookup#readme",

> A cacheable [`dns.lookup(…)`](https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback) that respects TTL :tada:

[![Node CI](https://github.com/szmarczak/cacheable-lookup/workflows/Node%20CI/badge.svg)](https://github.com/szmarczak/cacheable-lookup/actions)

[![Coverage Status](https://coveralls.io/repos/github/szmarczak/cacheable-lookup/badge.svg?branch=master)](https://coveralls.io/github/szmarczak/cacheable-lookup?branch=master)

[![npm](https://img.shields.io/npm/dm/cacheable-lookup.svg)](https://www.npmjs.com/package/cacheable-lookup)

[![install size](https://packagephobia.now.sh/badge?p=cacheable-lookup)](https://packagephobia.now.sh/result?p=cacheable-lookup)

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

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

http.get('http://example.com', {lookup: cacheable.lookup}, response => {

### Attaching CacheableLookup to an Agent

http.get('http://example.com', response => {

Returns a new instance of `CacheableLookup`.

Type: `Map` | [`Keyv`](https://github.com/lukechilds/keyv/)

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.

**Tip**: [`QuickLRU`](https://github.com/sindresorhus/quick-lru) is fully compatible with the Map API, you can use it to limit the amount of cached entries. Example:

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`.

When the DNS server responds with `ENOTFOUND` or `ENODATA` and the OS reports that the entry is available, it will use `dns.lookup(...)` directly for the requested hostnames for the specified amount of time (in seconds).

If you don't query internal hostnames (such as `localhost`, `database.local` etc.), it is strongly recommended to set this value to `0`.

**Note**: You should avoid setting this to `0` unless the provided DNS servers' database is limited to few domains.

The time how long it needs to remember queries that threw `ENOTFOUND` or `ENODATA` (TTL in seconds).

**Note**: This option is independent, `options.maxTtl` does not affect this.

Type: `dns.Resolver | dns.promises.Resolver`

Default: [`new dns.promises.Resolver()`](https://nodejs.org/api/dns.html#dns_class_dns_resolver)

An instance of [DNS Resolver](https://nodejs.org/api/dns.html#dns_class_dns_resolver) used to make DNS queries.

Default: [`dns.lookup`](https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback)

The fallback function to use when the DNS server responds with `ENOTFOUND` or `ENODATA`.

**Note**: This has no effect if the `fallbackDuration` option is less than `1`.

If you don't query internal hostnames (such as `localhost`, `database.local` etc.), it is strongly recommended to set this to `false`.

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

**Note**: This is not present when falling back to `dns.lookup(...)`!

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

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.

The DNS servers used to make queries. Can be overridden - doing so will clear the cache.

#### [lookup(hostname, options, callback)](https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback)

The asynchronous version of `dns.lookup(…)`.

Returns an [entry object](#entry-object).

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

The same as the [`dns.lookup(…)`](https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback) options.

An asynchronous function which returns cached DNS lookup entries.

This is the base for `lookupAsync(hostname, options)` and `lookup(hostname, options, callback)`.

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.

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

**Note:** Running `updateInterfaceInfo()` will trigger `clear()` only on network interface removal.

Clears the cache for the given hostname. If the hostname argument is not present, the entire cache will be emptied.

CacheableLookup#lookupAsync                x 2,896,251 ops/sec ±1.07% (85 runs sampled)

CacheableLookup#lookupAsync.all            x 2,842,664 ops/sec ±1.11% (88 runs sampled)

CacheableLookup#lookupAsync.all.ADDRCONFIG x 2,598,283 ops/sec ±1.21% (88 runs sampled)

CacheableLookup#lookup                     x 2,565,913 ops/sec ±1.56% (85 runs sampled)

const kCacheableLookupCreateConnection = Symbol('cacheableLookupCreateConnection');

const kCacheableLookupInstance = Symbol('cacheableLookupInstance');

const supportsALL = typeof ALL === 'number';

	if (!(agent && typeof agent.createConnection === 'function')) {

		throw new Error('Expected an Agent instance as the first argument');

		entry.address = `::ffff:${entry.address}`;

	for (const device of Object.values(os.networkInterfaces())) {

		this._dnsLookup = lookup && promisify(lookup);

		if (this._resolver instanceof AsyncResolver) {

			this._resolve4 = this._resolver.resolve4.bind(this._resolver);

			this._resolve6 = this._resolver.resolve6.bind(this._resolver);

			this._resolve4 = promisify(this._resolver.resolve4.bind(this._resolver));

			this._resolve6 = promisify(this._resolver.resolve6.bind(this._resolver));

		this.fallbackDuration = fallbackDuration;

			/* istanbul ignore next: There is no `interval.unref()` when running inside an Electron renderer */

		this.lookupAsync = this.lookupAsync.bind(this);

		} else if (typeof options === 'number') {

			throw new Error('Callback must be a function.');

		// eslint-disable-next-line promise/prefer-await-to-then

		this.lookupAsync(hostname, options).then(result => {

				callback(null, result.address, result.family, result.expires, result.ttl);

	async lookupAsync(hostname, options = {}) {

		let cached = await this.query(hostname);

			const filtered = cached.filter(entry => entry.family === 6);

				if ((supportsALL && options.hints & ALL) || filtered.length === 0) {

			cached = cached.filter(entry => entry.family === 4);

			cached = cached.filter(entry => entry.family === 6 ? _iface.has6 : _iface.has4);

			const error = new Error(`cacheableLookup ENOTFOUND ${hostname}`);

		let cached = await this._cache.get(hostname);

			const pending = this._pending[hostname];

				const newPromise = this.queryAndCache(hostname);

				this._pending[hostname] = newPromise;

		if (query.entries.length === 0 && this._fallback) {

		if (query.entries.length === 0 && this._dnsLookup) {

			if (query.entries.length !== 0 && this.fallbackDuration > 0) {

				// Use `dns.lookup(...)` for that particular hostname

				this._hostnamesToFallback.add(hostname);

		const cacheTtl = query.entries.length === 0 ? this.errorTtl : query.cacheTtl;

		await this._set(hostname, query.entries, cacheTtl);

		const nextRemovalTime = this._nextRemovalTime;

if (!nextRemovalTime || ms < nextRemovalTime) {

			this._removalTimeout = setTimeout(() => {

				for (const [hostname, entries] of this._cache) {

			/* istanbul ignore next: There is no `timeout.unref()` when running inside an Electron renderer */

		if (kCacheableLookupCreateConnection in agent) {

			throw new Error('CacheableLookup has been already installed');

		agent[kCacheableLookupCreateConnection] = agent.createConnection;

		agent[kCacheableLookupInstance] = this;

		agent.createConnection = (options, callback) => {

			return agent[kCacheableLookupCreateConnection](options, callback);

		if (agent[kCacheableLookupCreateConnection]) {

			if (agent[kCacheableLookupInstance] !== this) {

				throw new Error('The agent is not owned by this CacheableLookup instance');

			agent.createConnection = agent[kCacheableLookupCreateConnection];

			delete agent[kCacheableLookupCreateConnection];

			delete agent[kCacheableLookupInstance];

		if ((_iface.has4 && !this._iface.has4) || (_iface.has6 && !this._iface.has6)) {

		@@ -55,3 +55,3 @@ import {Resolver, promises as dnsPromises, lookup} from 'dns';
		*/
		lookup?: typeof lookup;
		lookup?: typeof lookup \| false;
		}
		@@ -58,0 +58,0 @@

		{
		"name": "cacheable-lookup",
		"version": "5.0.4",
		"version": "6.0.0",
		"description": "A cacheable dns.lookup(…) that respects the TTL",
		@@ -5,0 +5,0 @@ "engines": {

		@@ -83,3 +83,3 @@ 'use strict';
		this._resolver = resolver;
		this._dnsLookup = promisify(lookup);
		this._dnsLookup = lookup && promisify(lookup);

		@@ -100,7 +100,5 @@ if (this._resolver instanceof AsyncResolver) {

		if (fallbackDuration < 1) {
		this._fallback = false;
		} else {
		this._fallback = true;
		this.fallbackDuration = fallbackDuration;

		if (fallbackDuration > 0) {
		const interval = setInterval(() => {
		@@ -114,2 +112,4 @@ this._hostnamesToFallback.clear();
		}

		this._fallbackInterval = interval;
		}
		@@ -332,6 +332,6 @@

		if (query.entries.length === 0 && this._fallback) {
		if (query.entries.length === 0 && this._dnsLookup) {
		query = await this._lookup(hostname);

		if (query.entries.length !== 0) {
		if (query.entries.length !== 0 && this.fallbackDuration > 0) {
		// Use `dns.lookup(...)` for that particular hostname
		@@ -338,0 +338,0 @@ this._hostnamesToFallback.add(hostname);

Improved metrics

Worsened metrics

		@@ -97,3 +97,3 @@ # cacheable-lookup

		If you don't query internal hostnames (such as `localhost`, `database.local` etc.), it is strongly recommended to set this value to `0`.
		Note: You should avoid setting this to `0` unless the provided DNS servers' database is limited to few domains.

		@@ -125,3 +125,3 @@ ##### options.errorTtl

		Note: This has no effect if the `fallbackDuration` option is less than `1`.
		If you don't query internal hostnames (such as `localhost`, `database.local` etc.), it is strongly recommended to set this to `false`.

		@@ -128,0 +128,0 @@ ### Entry object