dnsnamespacenamespace dnsNames on the network (commons 0001-net FR-007). resolveDns asks for A, AAAA, CNAME, MX, NS, TXT and SRV records, with the records in these shapes (MX as { preference, exchange }, TXT as each record's strings, SRV as { priority, weight, port, target }), and answers with a Result whose error says whether the name does not exist, has no such record, or could not be asked: a name that does not resolve is an expected outcome, not an exception.
The question is asked here, over node:dgram (and node:net where the answer is too long for UDP), not through node:dns: the two runtimes' node:dns can disagree on exactly what this must tell apart (Bun reports a name without the record as one that does not exist), so one small stub resolver (RFC 1035, with EDNS0 for answers up to 1232 bytes over UDP) gives the same answer everywhere. The servers asked are the system's (node:dns's getServers, which reads /etc/resolv.conf or Windows's settings) or the one given; each is tried twice, for two seconds each time.
Names in records come without the trailing dot (mail.example.com, as Node gives them). The DNS is asked directly, so the hosts file (localhost) is not read.
import { resolveDns } from "./dns.ts";
const r = await resolveDns("example.com", "MX");
if (r.kind === "ok") for (const mx of r.value) console.log(mx.preference, mx.exchange);
else if (r.error.kind === "not-found") console.log("no such domain");dnsnamespacenamespace dnsdns.RecordTypetypeno test imports ittype RecordType = "A" | "AAAA" | "CNAME" | "MX" | "NS" | "TXT" | "SRV";The record types that can be asked for.
dns.MxRecordtypeno test imports ittype MxRecord = { readonly preference: number; readonly exchange: string };A mail exchanger.
dns.SrvRecordtypeno test imports ittype SrvRecord = { readonly priority: number; readonly weight: number; readonly port: number; readonly target: string };A service's host and port.
dns.RecordOftypeno test imports ittype RecordOf = {
readonly A: string;
readonly AAAA: string;
readonly CNAME: string;
readonly NS: string;
readonly MX: MxRecord;
readonly TXT: readonly string[];
readonly SRV: SrvRecord;
};The shape of one record of each type: an address or a name as a string, TXT as its strings (join them for the whole text).
dns.DnsErrortypeno test imports ittype DnsError =
| { readonly kind: "not-found"; readonly name: string }
| { readonly kind: "no-data"; readonly name: string; readonly type: RecordType }
| { readonly kind: "failed"; readonly name: string; readonly code: string; readonly message: string };Why there is no answer: the name does not exist (NXDOMAIN), it has no record of that type, or the DNS could not be asked (code is ESERVFAIL, EREFUSED, EFORMERR, ENOTIMP or ERCODE<n> for the server's answer, ETIMEOUT, ECANCELLED, EBADRESP for an answer that cannot be read, EBADNAME, ENOSERVERS, or the host's error code, such as ECONNREFUSED).
dns.NameServertypeno test imports ittype NameServer = { readonly ipAddr: string; readonly port?: number };The server to ask, instead of the system's.
dns.ResolveDnsOptionstypeno test imports ittype ResolveDnsOptions = {
/** The server to ask; the system's where not given. */
readonly nameServer?: NameServer;
/** Aborting it gives up (a `failed` error with code `ECANCELLED`). */
readonly signal?: AbortSignal;
};How to ask.
dns.resolveDnsfunctionno test imports itfunction resolveDns<T extends RecordType>(name: string, type: T, options?: ResolveDnsOptions): Promise<Result<readonly RecordOf[T][], DnsError>>The records of a type for a name, or why there are none.
RecordTypetypeno test imports ittype RecordType = "A" | "AAAA" | "CNAME" | "MX" | "NS" | "TXT" | "SRV";The record types that can be asked for.
MxRecordtypeno test imports ittype MxRecord = { readonly preference: number; readonly exchange: string };A mail exchanger.
SrvRecordtypeno test imports ittype SrvRecord = { readonly priority: number; readonly weight: number; readonly port: number; readonly target: string };A service's host and port.
RecordOftypeno test imports ittype RecordOf = {
readonly A: string;
readonly AAAA: string;
readonly CNAME: string;
readonly NS: string;
readonly MX: MxRecord;
readonly TXT: readonly string[];
readonly SRV: SrvRecord;
};The shape of one record of each type: an address or a name as a string, TXT as its strings (join them for the whole text).
DnsErrortypeno test imports ittype DnsError =
| { readonly kind: "not-found"; readonly name: string }
| { readonly kind: "no-data"; readonly name: string; readonly type: RecordType }
| { readonly kind: "failed"; readonly name: string; readonly code: string; readonly message: string };Why there is no answer: the name does not exist (NXDOMAIN), it has no record of that type, or the DNS could not be asked (code is ESERVFAIL, EREFUSED, EFORMERR, ENOTIMP or ERCODE<n> for the server's answer, ETIMEOUT, ECANCELLED, EBADRESP for an answer that cannot be read, EBADNAME, ENOSERVERS, or the host's error code, such as ECONNREFUSED).
NameServertypeno test imports ittype NameServer = { readonly ipAddr: string; readonly port?: number };The server to ask, instead of the system's.
ResolveDnsOptionstypeno test imports ittype ResolveDnsOptions = {
/** The server to ask; the system's where not given. */
readonly nameServer?: NameServer;
/** Aborting it gives up (a `failed` error with code `ECANCELLED`). */
readonly signal?: AbortSignal;
};How to ask.
resolveDnsfunctionfunction resolveDns<T extends RecordType>(name: string, type: T, options?: ResolveDnsOptions): Promise<Result<readonly RecordOf[T][], DnsError>>The records of a type for a name, or why there are none.