Operating-system host lookup
A network client needs the addresses associated with a host name using the machine's normal resolution behavior.
Node.js · Module
node:dns
The node:dns module provides APIs for resolving host names, IP addresses, and DNS records. Choose dns.lookup() for operating-system resolution or DNS resolver methods when querying DNS records directly.
How it works
The node:dns module provides hostname and address resolution. Its lookup operation uses the operating system's name-resolution facilities, while other APIs can query DNS records directly; the promises interface exposes asynchronous methods that resolve to Promises.
Syntax
import dns from 'node:dns';
import { promises as dnsPromises } from 'node:dns';Parameters
| Name | Type | Description |
|---|---|---|
hostname/address | string | A host name or address to resolve, depending on the selected DNS method. |
options | object | Optional method-specific settings, such as whether lookup results include all addresses. |
callback | function | For callback APIs, receives an error or the resolution result. |
Returns
The selected resolution method returns its documented result asynchronously; the promises API returns Promise objects.
Key points
- Use this module to resolve host names and network addresses.
- A common operation is translating a host name into one or more IP addresses.
- The lookup API delegates name resolution to the operating system rather than necessarily issuing DNS protocol queries.
- Promise-based variants are available when asynchronous code is preferred over callback-style methods.
- Promise methods integrate with
awaitand return Promise objects. - CommonJS applications can obtain the promises API through either documented access path.
Common mistakes
- The module name does not guarantee that every lookup uses DNS protocol queries;
dns.lookup()relies on operating-system facilities. - A lookup through
dns.lookup()can complete without network communication, so it may differ from querying a DNS server directly.
Example: Look up all addresses
import { promises as dns } from 'node:dns';
const addresses = await dns.lookup('nodejs.org', { all: true });
console.log(addresses);Looks up a hostname using Node.js's promise-based DNS API and prints all returned addresses.
When to use it
Promise-based resolution
An application needs asynchronous DNS operations that fit naturally into async/await code.
Record and reverse lookups
A service needs to inspect DNS records or map an address back to host names.
Interview questions
QWhat is the distinction between dns.lookup() and DNS record-resolution methods?
dns.lookup() resolves names through the operating system's facilities and may not perform network communication. Use it when matching how applications on the same system resolve names.
Follow-up: How would you force DNS-protocol resolution? Use the module's resolver methods, such as dns.resolve4() or the corresponding promises API, rather than dns.lookup().
QHow can the promise-based DNS API be accessed?
The dns.promises API offers asynchronous DNS methods that return Promise objects instead of using callbacks. It is available through require('node:dns').promises or require('node:dns/promises').
Follow-up: How would you consume it in an ES module? Import the promises namespace from node:dns, then await its lookup or record-resolution methods.
QWhat problem does node:dns solve?
The module is used for name resolution, including looking up IP addresses for host names. It also includes APIs for resolving DNS record types and reverse-resolving addresses.
Follow-up: What should be selected when an application needs behavior consistent with the host operating system? Choose dns.lookup(), because it uses the operating system's name-resolution facilities.
Related
dns.lookup()dns.resolve()dns.resolve4()dns.resolve6()dns.reverse()dns.promisesdns.Resolverdns.getDefaultResultOrder()