1 | /**
|
2 | * The `dns.promises` API provides an alternative set of asynchronous DNS methods
|
3 | * that return `Promise` objects rather than using callbacks. The API is accessible
|
4 | * via `require('dns').promises` or `require('dns/promises')`.
|
5 | * @since v10.6.0
|
6 | */
|
7 | declare module 'dns/promises' {
|
8 | import {
|
9 | LookupAddress,
|
10 | LookupOneOptions,
|
11 | LookupAllOptions,
|
12 | LookupOptions,
|
13 | AnyRecord,
|
14 | CaaRecord,
|
15 | MxRecord,
|
16 | NaptrRecord,
|
17 | SoaRecord,
|
18 | SrvRecord,
|
19 | ResolveWithTtlOptions,
|
20 | RecordWithTtl,
|
21 | ResolveOptions,
|
22 | ResolverOptions,
|
23 | } from 'node:dns';
|
24 | /**
|
25 | * Returns an array of IP address strings, formatted according to [RFC 5952](https://tools.ietf.org/html/rfc5952#section-6),
|
26 | * that are currently configured for DNS resolution. A string will include a port
|
27 | * section if a custom port is used.
|
28 | *
|
29 | * ```js
|
30 | * [
|
31 | * '4.4.4.4',
|
32 | * '2001:4860:4860::8888',
|
33 | * '4.4.4.4:1053',
|
34 | * '[2001:4860:4860::8888]:1053',
|
35 | * ]
|
36 | * ```
|
37 | * @since v10.6.0
|
38 | */
|
39 | function getServers(): string[];
|
40 | /**
|
41 | * Resolves a host name (e.g. `'nodejs.org'`) into the first found A (IPv4) or
|
42 | * AAAA (IPv6) record. All `option` properties are optional. If `options` is an
|
43 | * integer, then it must be `4` or `6` – if `options` is not provided, then IPv4
|
44 | * and IPv6 addresses are both returned if found.
|
45 | *
|
46 | * With the `all` option set to `true`, the `Promise` is resolved with `addresses`being an array of objects with the properties `address` and `family`.
|
47 | *
|
48 | * On error, the `Promise` is rejected with an `Error` object, where `err.code`is the error code.
|
49 | * Keep in mind that `err.code` will be set to `'ENOTFOUND'` not only when
|
50 | * the host name does not exist but also when the lookup fails in other ways
|
51 | * such as no available file descriptors.
|
52 | *
|
53 | * `dnsPromises.lookup()` does not necessarily have anything to do with the DNS
|
54 | * protocol. The implementation uses an operating system facility that can
|
55 | * associate names with addresses, and vice versa. This implementation can have
|
56 | * subtle but important consequences on the behavior of any Node.js program. Please
|
57 | * take some time to consult the `Implementation considerations section` before
|
58 | * using `dnsPromises.lookup()`.
|
59 | *
|
60 | * Example usage:
|
61 | *
|
62 | * ```js
|
63 | * const dns = require('dns');
|
64 | * const dnsPromises = dns.promises;
|
65 | * const options = {
|
66 | * family: 6,
|
67 | * hints: dns.ADDRCONFIG | dns.V4MAPPED,
|
68 | * };
|
69 | *
|
70 | * dnsPromises.lookup('example.com', options).then((result) => {
|
71 | * console.log('address: %j family: IPv%s', result.address, result.family);
|
72 | * // address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6
|
73 | * });
|
74 | *
|
75 | * // When options.all is true, the result will be an Array.
|
76 | * options.all = true;
|
77 | * dnsPromises.lookup('example.com', options).then((result) => {
|
78 | * console.log('addresses: %j', result);
|
79 | * // addresses: [{"address":"2606:2800:220:1:248:1893:25c8:1946","family":6}]
|
80 | * });
|
81 | * ```
|
82 | * @since v10.6.0
|
83 | */
|
84 | function lookup(hostname: string, family: number): Promise<LookupAddress>;
|
85 | function lookup(hostname: string, options: LookupOneOptions): Promise<LookupAddress>;
|
86 | function lookup(hostname: string, options: LookupAllOptions): Promise<LookupAddress[]>;
|
87 | function lookup(hostname: string, options: LookupOptions): Promise<LookupAddress | LookupAddress[]>;
|
88 | function lookup(hostname: string): Promise<LookupAddress>;
|
89 | /**
|
90 | * Resolves the given `address` and `port` into a host name and service using
|
91 | * the operating system's underlying `getnameinfo` implementation.
|
92 | *
|
93 | * If `address` is not a valid IP address, a `TypeError` will be thrown.
|
94 | * The `port` will be coerced to a number. If it is not a legal port, a `TypeError`will be thrown.
|
95 | *
|
96 | * On error, the `Promise` is rejected with an `Error` object, where `err.code`is the error code.
|
97 | *
|
98 | * ```js
|
99 | * const dnsPromises = require('dns').promises;
|
100 | * dnsPromises.lookupService('127.0.0.1', 22).then((result) => {
|
101 | * console.log(result.hostname, result.service);
|
102 | * // Prints: localhost ssh
|
103 | * });
|
104 | * ```
|
105 | * @since v10.6.0
|
106 | */
|
107 | function lookupService(
|
108 | address: string,
|
109 | port: number
|
110 | ): Promise<{
|
111 | hostname: string;
|
112 | service: string;
|
113 | }>;
|
114 | /**
|
115 | * Uses the DNS protocol to resolve a host name (e.g. `'nodejs.org'`) into an array
|
116 | * of the resource records. When successful, the `Promise` is resolved with an
|
117 | * array of resource records. The type and structure of individual results vary
|
118 | * based on `rrtype`:
|
119 | *
|
120 | * <omitted>
|
121 | *
|
122 | * On error, the `Promise` is rejected with an `Error` object, where `err.code`is one of the `DNS error codes`.
|
123 | * @since v10.6.0
|
124 | * @param hostname Host name to resolve.
|
125 | * @param [rrtype='A'] Resource record type.
|
126 | */
|
127 | function resolve(hostname: string): Promise<string[]>;
|
128 | function resolve(hostname: string, rrtype: 'A'): Promise<string[]>;
|
129 | function resolve(hostname: string, rrtype: 'AAAA'): Promise<string[]>;
|
130 | function resolve(hostname: string, rrtype: 'ANY'): Promise<AnyRecord[]>;
|
131 | function resolve(hostname: string, rrtype: 'CAA'): Promise<CaaRecord[]>;
|
132 | function resolve(hostname: string, rrtype: 'CNAME'): Promise<string[]>;
|
133 | function resolve(hostname: string, rrtype: 'MX'): Promise<MxRecord[]>;
|
134 | function resolve(hostname: string, rrtype: 'NAPTR'): Promise<NaptrRecord[]>;
|
135 | function resolve(hostname: string, rrtype: 'NS'): Promise<string[]>;
|
136 | function resolve(hostname: string, rrtype: 'PTR'): Promise<string[]>;
|
137 | function resolve(hostname: string, rrtype: 'SOA'): Promise<SoaRecord>;
|
138 | function resolve(hostname: string, rrtype: 'SRV'): Promise<SrvRecord[]>;
|
139 | function resolve(hostname: string, rrtype: 'TXT'): Promise<string[][]>;
|
140 | function resolve(hostname: string, rrtype: string): Promise<string[] | MxRecord[] | NaptrRecord[] | SoaRecord | SrvRecord[] | string[][] | AnyRecord[]>;
|
141 | /**
|
142 | * Uses the DNS protocol to resolve IPv4 addresses (`A` records) for the`hostname`. On success, the `Promise` is resolved with an array of IPv4
|
143 | * addresses (e.g. `['74.125.79.104', '74.125.79.105', '74.125.79.106']`).
|
144 | * @since v10.6.0
|
145 | * @param hostname Host name to resolve.
|
146 | */
|
147 | function resolve4(hostname: string): Promise<string[]>;
|
148 | function resolve4(hostname: string, options: ResolveWithTtlOptions): Promise<RecordWithTtl[]>;
|
149 | function resolve4(hostname: string, options: ResolveOptions): Promise<string[] | RecordWithTtl[]>;
|
150 | /**
|
151 | * Uses the DNS protocol to resolve IPv6 addresses (`AAAA` records) for the`hostname`. On success, the `Promise` is resolved with an array of IPv6
|
152 | * addresses.
|
153 | * @since v10.6.0
|
154 | * @param hostname Host name to resolve.
|
155 | */
|
156 | function resolve6(hostname: string): Promise<string[]>;
|
157 | function resolve6(hostname: string, options: ResolveWithTtlOptions): Promise<RecordWithTtl[]>;
|
158 | function resolve6(hostname: string, options: ResolveOptions): Promise<string[] | RecordWithTtl[]>;
|
159 | /**
|
160 | * Uses the DNS protocol to resolve all records (also known as `ANY` or `*` query).
|
161 | * On success, the `Promise` is resolved with an array containing various types of
|
162 | * records. Each object has a property `type` that indicates the type of the
|
163 | * current record. And depending on the `type`, additional properties will be
|
164 | * present on the object:
|
165 | *
|
166 | * <omitted>
|
167 | *
|
168 | * Here is an example of the result object:
|
169 | *
|
170 | * ```js
|
171 | * [ { type: 'A', address: '127.0.0.1', ttl: 299 },
|
172 | * { type: 'CNAME', value: 'example.com' },
|
173 | * { type: 'MX', exchange: 'alt4.aspmx.l.example.com', priority: 50 },
|
174 | * { type: 'NS', value: 'ns1.example.com' },
|
175 | * { type: 'TXT', entries: [ 'v=spf1 include:_spf.example.com ~all' ] },
|
176 | * { type: 'SOA',
|
177 | * nsname: 'ns1.example.com',
|
178 | * hostmaster: 'admin.example.com',
|
179 | * serial: 156696742,
|
180 | * refresh: 900,
|
181 | * retry: 900,
|
182 | * expire: 1800,
|
183 | * minttl: 60 } ]
|
184 | * ```
|
185 | * @since v10.6.0
|
186 | */
|
187 | function resolveAny(hostname: string): Promise<AnyRecord[]>;
|
188 | /**
|
189 | * Uses the DNS protocol to resolve `CAA` records for the `hostname`. On success,
|
190 | * the `Promise` is resolved with an array of objects containing available
|
191 | * certification authority authorization records available for the `hostname`(e.g. `[{critical: 0, iodef: 'mailto:pki@example.com'},{critical: 128, issue: 'pki.example.com'}]`).
|
192 | * @since v15.0.0
|
193 | */
|
194 | function resolveCaa(hostname: string): Promise<CaaRecord[]>;
|
195 | /**
|
196 | * Uses the DNS protocol to resolve `CNAME` records for the `hostname`. On success,
|
197 | * the `Promise` is resolved with an array of canonical name records available for
|
198 | * the `hostname` (e.g. `['bar.example.com']`).
|
199 | * @since v10.6.0
|
200 | */
|
201 | function resolveCname(hostname: string): Promise<string[]>;
|
202 | /**
|
203 | * Uses the DNS protocol to resolve mail exchange records (`MX` records) for the`hostname`. On success, the `Promise` is resolved with an array of objects
|
204 | * containing both a `priority` and `exchange` property (e.g.`[{priority: 10, exchange: 'mx.example.com'}, ...]`).
|
205 | * @since v10.6.0
|
206 | */
|
207 | function resolveMx(hostname: string): Promise<MxRecord[]>;
|
208 | /**
|
209 | * Uses the DNS protocol to resolve regular expression based records (`NAPTR`records) for the `hostname`. On success, the `Promise` is resolved with an array
|
210 | * of objects with the following properties:
|
211 | *
|
212 | * * `flags`
|
213 | * * `service`
|
214 | * * `regexp`
|
215 | * * `replacement`
|
216 | * * `order`
|
217 | * * `preference`
|
218 | *
|
219 | * ```js
|
220 | * {
|
221 | * flags: 's',
|
222 | * service: 'SIP+D2U',
|
223 | * regexp: '',
|
224 | * replacement: '_sip._udp.example.com',
|
225 | * order: 30,
|
226 | * preference: 100
|
227 | * }
|
228 | * ```
|
229 | * @since v10.6.0
|
230 | */
|
231 | function resolveNaptr(hostname: string): Promise<NaptrRecord[]>;
|
232 | /**
|
233 | * Uses the DNS protocol to resolve name server records (`NS` records) for the`hostname`. On success, the `Promise` is resolved with an array of name server
|
234 | * records available for `hostname` (e.g.`['ns1.example.com', 'ns2.example.com']`).
|
235 | * @since v10.6.0
|
236 | */
|
237 | function resolveNs(hostname: string): Promise<string[]>;
|
238 | /**
|
239 | * Uses the DNS protocol to resolve pointer records (`PTR` records) for the`hostname`. On success, the `Promise` is resolved with an array of strings
|
240 | * containing the reply records.
|
241 | * @since v10.6.0
|
242 | */
|
243 | function resolvePtr(hostname: string): Promise<string[]>;
|
244 | /**
|
245 | * Uses the DNS protocol to resolve a start of authority record (`SOA` record) for
|
246 | * the `hostname`. On success, the `Promise` is resolved with an object with the
|
247 | * following properties:
|
248 | *
|
249 | * * `nsname`
|
250 | * * `hostmaster`
|
251 | * * `serial`
|
252 | * * `refresh`
|
253 | * * `retry`
|
254 | * * `expire`
|
255 | * * `minttl`
|
256 | *
|
257 | * ```js
|
258 | * {
|
259 | * nsname: 'ns.example.com',
|
260 | * hostmaster: 'root.example.com',
|
261 | * serial: 2013101809,
|
262 | * refresh: 10000,
|
263 | * retry: 2400,
|
264 | * expire: 604800,
|
265 | * minttl: 3600
|
266 | * }
|
267 | * ```
|
268 | * @since v10.6.0
|
269 | */
|
270 | function resolveSoa(hostname: string): Promise<SoaRecord>;
|
271 | /**
|
272 | * Uses the DNS protocol to resolve service records (`SRV` records) for the`hostname`. On success, the `Promise` is resolved with an array of objects with
|
273 | * the following properties:
|
274 | *
|
275 | * * `priority`
|
276 | * * `weight`
|
277 | * * `port`
|
278 | * * `name`
|
279 | *
|
280 | * ```js
|
281 | * {
|
282 | * priority: 10,
|
283 | * weight: 5,
|
284 | * port: 21223,
|
285 | * name: 'service.example.com'
|
286 | * }
|
287 | * ```
|
288 | * @since v10.6.0
|
289 | */
|
290 | function resolveSrv(hostname: string): Promise<SrvRecord[]>;
|
291 | /**
|
292 | * Uses the DNS protocol to resolve text queries (`TXT` records) for the`hostname`. On success, the `Promise` is resolved with a two-dimensional array
|
293 | * of the text records available for `hostname` (e.g.`[ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]`). Each sub-array contains TXT chunks of
|
294 | * one record. Depending on the use case, these could be either joined together or
|
295 | * treated separately.
|
296 | * @since v10.6.0
|
297 | */
|
298 | function resolveTxt(hostname: string): Promise<string[][]>;
|
299 | /**
|
300 | * Performs a reverse DNS query that resolves an IPv4 or IPv6 address to an
|
301 | * array of host names.
|
302 | *
|
303 | * On error, the `Promise` is rejected with an `Error` object, where `err.code`is one of the `DNS error codes`.
|
304 | * @since v10.6.0
|
305 | */
|
306 | function reverse(ip: string): Promise<string[]>;
|
307 | /**
|
308 | * Sets the IP address and port of servers to be used when performing DNS
|
309 | * resolution. The `servers` argument is an array of [RFC 5952](https://tools.ietf.org/html/rfc5952#section-6) formatted
|
310 | * addresses. If the port is the IANA default DNS port (53) it can be omitted.
|
311 | *
|
312 | * ```js
|
313 | * dnsPromises.setServers([
|
314 | * '4.4.4.4',
|
315 | * '[2001:4860:4860::8888]',
|
316 | * '4.4.4.4:1053',
|
317 | * '[2001:4860:4860::8888]:1053',
|
318 | * ]);
|
319 | * ```
|
320 | *
|
321 | * An error will be thrown if an invalid address is provided.
|
322 | *
|
323 | * The `dnsPromises.setServers()` method must not be called while a DNS query is in
|
324 | * progress.
|
325 | *
|
326 | * This method works much like[resolve.conf](https://man7.org/linux/man-pages/man5/resolv.conf.5.html).
|
327 | * That is, if attempting to resolve with the first server provided results in a`NOTFOUND` error, the `resolve()` method will _not_ attempt to resolve with
|
328 | * subsequent servers provided. Fallback DNS servers will only be used if the
|
329 | * earlier ones time out or result in some other error.
|
330 | * @since v10.6.0
|
331 | * @param servers array of `RFC 5952` formatted addresses
|
332 | */
|
333 | function setServers(servers: ReadonlyArray<string>): void;
|
334 | class Resolver {
|
335 | constructor(options?: ResolverOptions);
|
336 | cancel(): void;
|
337 | getServers: typeof getServers;
|
338 | resolve: typeof resolve;
|
339 | resolve4: typeof resolve4;
|
340 | resolve6: typeof resolve6;
|
341 | resolveAny: typeof resolveAny;
|
342 | resolveCname: typeof resolveCname;
|
343 | resolveMx: typeof resolveMx;
|
344 | resolveNaptr: typeof resolveNaptr;
|
345 | resolveNs: typeof resolveNs;
|
346 | resolvePtr: typeof resolvePtr;
|
347 | resolveSoa: typeof resolveSoa;
|
348 | resolveSrv: typeof resolveSrv;
|
349 | resolveTxt: typeof resolveTxt;
|
350 | reverse: typeof reverse;
|
351 | setLocalAddress(ipv4?: string, ipv6?: string): void;
|
352 | setServers: typeof setServers;
|
353 | }
|
354 | }
|
355 | declare module 'node:dns/promises' {
|
356 | export * from 'dns/promises';
|
357 | }
|