0
# DNS Operations
1

2
Perform DNS lookups and resolve various record types with promise support. Provides modern async/await compatibility for Node.js dns operations.
3

4
## Capabilities
5

6
### DNS Lookup
7

8
Resolve hostnames to IP addresses and vice versa.
9

10
```javascript { .api }
11
/**
12
 * Resolve hostname to IP address
13
 * @param hostname - Hostname to resolve
14
 * @param options - Lookup options or address family
15
 * @returns Promise resolving to lookup result
16
 */
17
function lookup(hostname, options): Promise<string | {address: string, family: number}>;
18
```
19

20
### Generic DNS Resolution
21

22
Resolve various types of DNS records.
23

24
```javascript { .api }
25
/**
26
 * Resolve hostname using specified record type
27
 * @param hostname - Hostname to resolve
28
 * @param rrtype - Record type (A, AAAA, CNAME, MX, NS, SRV, TXT, PTR)
29
 * @returns Promise resolving to array of records
30
 */
31
function resolve(hostname, rrtype): Promise<string[] | object[]>;
32
```
33

34
### Specific DNS Record Types
35

36
Resolve specific types of DNS records with optimized interfaces.
37

38
```javascript { .api }
39
/**
40
 * Resolve IPv4 addresses (A records)
41
 * @param hostname - Hostname to resolve
42
 * @param options - Resolution options
43
 * @returns Promise resolving to array of IPv4 addresses
44
 */
45
function resolve4(hostname, options): Promise<string[]>;
46

47
/**
48
 * Resolve IPv6 addresses (AAAA records)
49
 * @param hostname - Hostname to resolve
50
 * @param options - Resolution options
51
 * @returns Promise resolving to array of IPv6 addresses
52
 */
53
function resolve6(hostname, options): Promise<string[]>;
54

55
/**
56
 * Resolve canonical name records (CNAME)
57
 * @param hostname - Hostname to resolve
58
 * @returns Promise resolving to array of canonical names
59
 */
60
function resolveCname(hostname): Promise<string[]>;
61

62
/**
63
 * Resolve mail exchange records (MX)
64
 * @param hostname - Hostname to resolve
65
 * @returns Promise resolving to array of MX record objects
66
 */
67
function resolveMx(hostname): Promise<{priority: number, exchange: string}[]>;
68

69
/**
70
 * Resolve name server records (NS)
71
 * @param hostname - Hostname to resolve
72
 * @returns Promise resolving to array of name server hostnames
73
 */
74
function resolveNs(hostname): Promise<string[]>;
75

76
/**
77
 * Resolve service records (SRV)
78
 * @param hostname - Hostname to resolve
79
 * @returns Promise resolving to array of SRV record objects
80
 */
81
function resolveSrv(hostname): Promise<{priority: number, weight: number, port: number, name: string}[]>;
82

83
/**
84
 * Resolve text records (TXT)
85
 * @param hostname - Hostname to resolve
86
 * @returns Promise resolving to array of text record arrays
87
 */
88
function resolveTxt(hostname): Promise<string[][]>;
89

90
/**
91
 * Reverse DNS lookup (PTR records)
92
 * @param ip - IP address to reverse lookup
93
 * @returns Promise resolving to array of hostnames
94
 */
95
function reverse(ip): Promise<string[]>;
96
```
97

98
**Usage Examples:**
99

100
```javascript
101
const dns = require('mz/dns');
102

103
// Basic hostname lookup
104
async function lookupHost() {
105
  try {
106
    // Simple lookup (returns first IP)
107
    const address = await dns.lookup('google.com');
108
    console.log('Google IP:', address);
109
    
110
    // Lookup with options
111
    const result = await dns.lookup('google.com', { family: 4, all: false });
112
    console.log('IPv4 address:', result);
113
    
114
    // Get all addresses
115
    const all = await dns.lookup('google.com', { all: true });
116
    console.log('All addresses:', all);
117
    
118
  } catch (error) {
119
    console.error('Lookup failed:', error);
120
  }
121
}
122

123
// Resolve specific record types
124
async function resolveRecords() {
125
  try {
126
    // IPv4 addresses
127
    const ipv4 = await dns.resolve4('google.com');
128
    console.log('IPv4 addresses:', ipv4);
129
    
130
    // IPv6 addresses
131
    const ipv6 = await dns.resolve6('google.com');
132
    console.log('IPv6 addresses:', ipv6);
133
    
134
    // MX records
135
    const mx = await dns.resolveMx('google.com');
136
    console.log('Mail servers:', mx);
137
    // Output: [{priority: 10, exchange: 'smtp.google.com'}, ...]
138
    
139
    // NS records
140
    const ns = await dns.resolveNs('google.com');
141
    console.log('Name servers:', ns);
142
    
143
    // TXT records
144
    const txt = await dns.resolveTxt('google.com');
145
    console.log('TXT records:', txt);
146
    
147
  } catch (error) {
148
    console.error('Resolution failed:', error);
149
  }
150
}
151

152
// Reverse DNS lookup
153
async function reverseLoookup() {
154
  try {
155
    const hostnames = await dns.reverse('8.8.8.8');
156
    console.log('8.8.8.8 resolves to:', hostnames);
157
  } catch (error) {
158
    console.error('Reverse lookup failed:', error);
159
  }
160
}
161

162
// Generic resolve with different record types
163
async function genericResolve() {
164
  try {
165
    // A records
166
    const a = await dns.resolve('example.com', 'A');
167
    console.log('A records:', a);
168
    
169
    // CNAME records
170
    const cname = await dns.resolve('www.example.com', 'CNAME');
171
    console.log('CNAME records:', cname);
172
    
173
    // SRV records
174
    const srv = await dns.resolve('_http._tcp.example.com', 'SRV');
175
    console.log('SRV records:', srv);
176
    
177
  } catch (error) {
178
    console.error('Generic resolve failed:', error);
179
  }
180
}
181

182
// Callback support is still available
183
dns.lookup('example.com', (err, address, family) => {
184
  if (err) {
185
    console.error('Error:', err);
186
  } else {
187
    console.log('Address:', address, 'Family:', family);
188
  }
189
});
190

191
// Practical example: Check if domain has mail servers
192
async function hasMailServers(domain) {
193
  try {
194
    const mx = await dns.resolveMx(domain);
195
    return mx.length > 0;
196
  } catch (error) {
197
    // DNS resolution failed, assume no mail servers
198
    return false;
199
  }
200
}
201

202
// Practical example: Get fastest responding IP
203
async function getFastestIP(hostname) {
204
  try {
205
    const addresses = await dns.resolve4(hostname);
206
    // In practice, you might ping each to find the fastest
207
    return addresses[0]; // Return first for simplicity
208
  } catch (error) {
209
    throw new Error(`Failed to resolve ${hostname}: ${error.message}`);
210
  }
211
}
212
```
213

214
## Lookup Options
215

216
The `lookup()` function accepts an options object:
217

218
```javascript { .api }
219
interface LookupOptions {
220
  /** Address family (4 for IPv4, 6 for IPv6, 0 for both) */
221
  family?: number;
222
  /** Return all addresses instead of just the first */
223
  all?: boolean;
224
  /** Custom hints for getaddrinfo */
225
  hints?: number;
226
  /** Whether to use numeric host */
227
  verbatim?: boolean;
228
}
229
```
230

231
## Error Handling
232

233
DNS functions will reject with errors for various conditions:
234
- `ENOTFOUND`: Domain not found
235
- `ENODATA`: No data for the requested record type
236
- `ESERVFAIL`: DNS server failure
237
- `ETIMEOUT`: DNS query timeout
238
- `ECONNREFUSED`: Connection to DNS server refused
239

240
```javascript
241
const dns = require('mz/dns');
242

243
async function handleDNSErrors() {
244
  try {
245
    await dns.lookup('nonexistent-domain-12345.com');
246
  } catch (error) {
247
    if (error.code === 'ENOTFOUND') {
248
      console.log('Domain not found');
249
    } else if (error.code === 'ETIMEOUT') {
250
      console.log('DNS query timed out');
251
    } else {
252
      console.log('DNS error:', error.code, error.message);
253
    }
254
  }
255
}
256
```
257

258
## Record Type Formats
259

260
Different DNS record types return different data structures:
261

262
- **A/AAAA records**: Array of IP address strings
263
- **CNAME records**: Array of canonical name strings
264
- **MX records**: Array of `{priority: number, exchange: string}` objects
265
- **NS records**: Array of name server hostname strings
266
- **SRV records**: Array of `{priority: number, weight: number, port: number, name: string}` objects
267
- **TXT records**: Array of arrays (each TXT record can have multiple strings)
268
- **PTR records**: Array of hostname strings
269

270
## Implementation Notes
271

272
- Uses `thenify-all` to wrap native dns methods
273
- Maintains complete compatibility with native dns behavior
274
- Supports both promise and callback interfaces
275
- Error codes and messages match native dns module exactly
276
- All resolution functions return arrays or objects as specified by Node.js dns module