cacheable-lookup

When instantiating new CacheableLookup(options), you can provide several configuration options to control caching behavior:

• cache: A Map or Keyv instance used for storage. Default is new Map().
  • Tip: Use QuickLRU for a Map-compatible way to limit cache size.
• maxTtl: The maximum lifetime of entries in seconds. Default is Infinity. Setting to 0 disables caching.
• fallbackDuration: Time in seconds to use dns.lookup() directly when the DNS server returns ENOTFOUND or ENODATA. Default is 3600.
• errorTtl: How long to remember queries that threw ENOTFOUND or ENODATA in seconds. Default is 0.15.
• resolver: A dns.Resolver or dns.promises.Resolver instance. Default is new dns.promises.Resolver().
• lookup: The fallback function to use when the DNS server responds with ENOTFOUND or ENODATA. Default is dns.lookup. If you don't query internal hostnames, it is recommended to set this to false.

import http from 'node:http';
import CacheableLookup from 'cacheable-lookup';
import QuickLRU from 'quick-lru';

const cacheable = new CacheableLookup({
	cache: new QuickLRU({maxSize: 1000})
});

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

To use CacheableLookup, instantiate the CacheableLookup class with an optional Options object. This allows you to configure custom caching behavior, DNS resolvers, and fallback mechanisms.

Configuration Options

CacheInstance Interface

If providing a custom cache, it must implement:

• set(hostname: string, entries: EntryObject[], ttl: number): TPromise<void | boolean | this>
• get(hostname: string): TPromise<EntryObject[] | undefined>
• delete(hostname: string): TPromise<boolean>
• clear(): TPromise<void>

import CacheableLookup from 'cacheable-lookup';

const cacheableLookup = new CacheableLookup({
  maxTtl: 3600,
  errorTtl: 1,
  fallbackDuration: 0
});

Use lookupAsync(hostname, options) to retrieve a DNS entry from the cache or perform a new query if not present.

Parameters

• hostname: The hostname to resolve.
• options: An object containing:
  • family: The IP version to filter for (4 or 6).
  • all: If true, returns an array of all matching entries instead of just the first one.
  • hints: Bitwise flags for special handling:
    • V4MAPPED: Maps IPv4 addresses to IPv6 (e.g., ::ffff:1.2.3.4).
    • ADDRCONFIG: Filters results based on the local system's configured interfaces.
    • ALL: Used in conjunction with V4MAPPED to return all entries.

Returns

Returns a Promise that resolves to a single entry object or an array of entry objects (if options.all is true). Each entry includes a source field (either 'cache' or 'query').

If no entry is found, it throws an error with code ENOTFOUND.

// Single entry
const entry = await cacheableLookup.lookupAsync('example.com', { family: 4 });
console.log(entry.address, entry.source);

// All entries
const entries = await cacheableLookup.lookupAsync('example.com', { all: true });

The CacheableLookup class provides both callback-style and Promise-based methods for performing DNS lookups that utilize the internal cache.

Asynchronous Lookups (lookupAsync)

Use lookupAsync for modern async/await workflows. It returns either a single EntryObject or an array of EntryObjects depending on the all flag in LookupOptions.

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

Callback Lookups (lookup)

Use lookup for traditional Node.js callback patterns.

• lookup(hostname: string, callback: (error: Error | null, address: string, family: IPFamily) => void): void
• lookup(hostname: string, options: LookupOptions & {all: true}, callback: (error: Error | null, result: ReadonlyArray<EntryObject>) => void): void

// Promise-based single entry
const entry = await cacheableLookup.lookupAsync('example.com');
console.log(entry.address);

// Promise-based all entries
const entries = await cacheableLookup.lookupAsync('example.com', { all: true });
console.log(entries.map(e => e.address));