node_modules/jest-worker/node_modules/@types/node/dns/promises.d.ts

   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, v14.17.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     /**
 335      * Set the default value of `verbatim` in `dns.lookup()` and `dnsPromises.lookup()`. The value could be:
 336      *
 337      * * `ipv4first`: sets default `verbatim` `false`.
 338      * * `verbatim`: sets default `verbatim` `true`.
 339      *
 340      * The default is `ipv4first` and `dnsPromises.setDefaultResultOrder()` have
 341      * higher priority than `--dns-result-order`. When using `worker threads`,`dnsPromises.setDefaultResultOrder()` from the main thread won't affect the
 342      * default dns orders in workers.
 343      * @since v16.4.0, v14.18.0
 344      * @param order must be `'ipv4first'` or `'verbatim'`.
 345      */
 346     function setDefaultResultOrder(order: 'ipv4first' | 'verbatim'): void;
 347     class Resolver {
 348         constructor(options?: ResolverOptions);
 349         cancel(): void;
 350         getServers: typeof getServers;
 351         resolve: typeof resolve;
 352         resolve4: typeof resolve4;
 353         resolve6: typeof resolve6;
 354         resolveAny: typeof resolveAny;
 355         resolveCname: typeof resolveCname;
 356         resolveMx: typeof resolveMx;
 357         resolveNaptr: typeof resolveNaptr;
 358         resolveNs: typeof resolveNs;
 359         resolvePtr: typeof resolvePtr;
 360         resolveSoa: typeof resolveSoa;
 361         resolveSrv: typeof resolveSrv;
 362         resolveTxt: typeof resolveTxt;
 363         reverse: typeof reverse;
 364         setLocalAddress(ipv4?: string, ipv6?: string): void;
 365         setServers: typeof setServers;
 366     }
 367 }
 368 declare module 'node:dns/promises' {
 369     export * from 'dns/promises';
 370 }