NodeDns
Node.js implementation of Effect's Dns service.
Address lookups use the operating system resolver through dns.lookup,
including the hosts file. Record queries and reverse lookups share one
dns.Resolver. Interruption discards a query's result but cannot cancel
that query; closing the scope cancels all pending queries.
Unrepresentable records, such as invalid Host.DomainName values, are
skipped. If every record is skipped, the query fails with InvalidResponse.
make decodes Node.js's Latin-1 TXT and CAA strings as UTF-8. TLSA queries
need Node.js 22.15 or 23.9 and later, and fail with Unsupported on runtimes
without resolveTlsa. Other runtimes reuse lookup, resolver, and the
conversion helpers to build their services.
Constructors
Creates a Node.js Dns service whose resolver lives as long as the scope.
Signature
declare const make: (...args: [options?: Options]) => Effect<any, unknown, Scope>Creates a function that queries DNS records with the runtime's node:dns
module.
Details
All queries share one dns.Resolver, which is cancelled when the scope
closes. Names in records are fully qualified, and TXT and CAA character
strings are returned as the runtime decodes them, without the UTF-8
correction that make applies for Node.js. Records are converted with
recordsFromResolver.
Signature
declare const resolver: (...args: [options?: Options]) => Effect<(name: string, type: RecordType) => Effect<Array<DnsRecord>, DnsError>, unknown, Scope>Converting
Converts the entries returned by an address lookup, such as dns.lookup
with all: true, to IP addresses, keeping their order.
Details
IPv6 zones are dropped, and addresses that cannot be parsed are skipped.
Signature
declare function addressesFromLookup(entries: readonly Array<{ readonly address: string;}>): Array<IpAddress>Converts a failure of node:dns or of Bun's DNS functions to a
Dns.DnsError, choosing the reason from the error's code.
Details
Bun prefixes c-ares codes with DNS_, such as DNS_ENOTFOUND; the prefix is
ignored. Errors without a known code get the reason Unknown.
Signature
declare function dnsErrorFromCause(cause: unknown, method: DnsError, hostname: string, recordType?: any): DnsErrorConverts a name returned by a resolver to a fully qualified
Host.DomainName, throwing when it is not a valid domain name.
Signature
declare function domainNameFromResolverUnsafe(name: string): DomainNameConverts a name returned by a resolver to fully qualified text, for names that need not be host names, such as PTR targets and SOA mailboxes.
Details
Resolvers write bytes as \DDD escapes, c-ares in decimal (radix 10) and
Deno.resolveDns in octal (radix 8), and escape special characters with
a backslash, such as \. for a dot inside a label or \( for a
parenthesis. Decoding the bytes as UTF-8 and removing the escapes gives the
text of the name, keeping only the \. and \\ escapes.
Signature
declare function nameTextFromResolver(name: string, radix: 8 | 10): stringConverts the entries of a resolver's answer to a query for name to records
of a record type, skipping entries whose data cannot be represented, such as
names that are not valid Host.DomainName values.
Details
When the answer has entries but every one is skipped, the conversion fails
with an InvalidResponse error whose cause is the first entry's failure,
rather than returning no records, which would be reported as NotFound.
Signature
declare function recordsFromResolver<T extends RecordType, A>(name: string, type: T, entries: readonly Array<A>, fields: (entry: A) => RecordFields<T>): Result<Array<RecordFor<T>>, DnsError>Converts a number of seconds that a resolver reports as a signed 32-bit
integer, such as the SOA refresh, retry, and expire intervals, to a
Duration.
Signature
declare function secondsFromInt32(value: number): DurationConverts an IP family to the numeric family used by dns.lookup, with 0
for addresses of either family.
Signature
declare function toFamily(family: any): 0 | 4 | 6Decodes a string that holds one byte per character as UTF-8.
Details
Node.js and Deno.resolveDns decode each byte of TXT and CAA character
strings as one Latin-1 character; decoding the bytes as UTF-8 matches other
runtimes. Strings with only ASCII characters are returned unchanged.
Signature
declare function utf8FromLatin1(value: string): stringLayers
Layer that provides the Node.js Dns service using the system resolver
configuration.
Signature
declare const layer: Layer.Layer<Dns.Dns>Creates a layer that provides the Node.js Dns service with options read
from configuration.
Signature
declare function layerConfig(options: { readonly nameServers?: Config<readonly Array<any> | undefined>; readonly timeout?: Config<Input | undefined>; readonly tries?: Config<number | undefined>;} | Config<Options>): Layer<Dns, NetAddressError | ConfigError>Models
Options for the Node.js Dns service and resolver.
Details
nameServers replaces the system name servers, which are converted like
Dns.nameServerFromInput, and an empty list keeps the system name servers.
timeout is the time allowed for each attempt and tries the number of
attempts per name server. Address lookups always use the operating system
resolver and are not affected.
timeout is rounded up to whole milliseconds and tries down to a whole
number, and both are clamped to 1 through 2^31 - 1, so Duration.infinity
uses the longest timeout the resolver supports.
Gotchas
Invalid name servers fail with a NetAddress.NetAddressError when the
service is created, and so do IPv6 name servers with a scope ID, such as
link-local addresses, because the resolver drops the scope.
Signature
interface Options { readonly nameServers?: readonly Array<any>; readonly timeout?: Input; readonly tries?: number;}