bare-dns

stable

bare-dns — Domain name resolution for JavaScript. It is a native addon and requires Bare >=1.7.0.

Mirrors the Node.js dns module.

npm i bare-dns

Usage

const dns = require('bare-dns')

dns.lookup('github.com', (err, address, family) => {
  console.log(address, family)
})

API

dns

`dns.AnyRecord`

type AnyRecord = | ({ type: 'A' } & RecordWithTTL)
  | ({ type: 'AAAA' } & RecordWithTTL)
  | { type: 'CNAME'; value: string }
  | { type: 'NS'; value: string }
  | { type: 'PTR'; value: string }
  | { type: 'TXT'; entries: string[] }
  | ({ type: 'MX' } & MXRecord)
  | ({ type: 'SRV' } & SRVRecord)
  | ({ type: 'NAPTR' } & NAPTRRecord)
  | ({ type: 'SOA' } & SOARecord)

`dns.constants`

dns.constants: {
  readonly type: {
    readonly A: 1
    readonly NS: 2
    readonly CNAME: 5
    readonly SOA: 6
    readonly PTR: 12
    readonly HINFO: 13
    readonly MX: 15
    readonly TXT: 16
    readonly SIG: 24
    readonly AAAA: 28
    readonly SRV: 33
    readonly NAPTR: 35
    readonly OPT: 41
    readonly TLSA: 52
    readonly SVCB: 64
    readonly HTTPS: 65
    readonly ANY: 255
    readonly URI: 256
    readonly CAA: 257
  }
  readonly status: Record<string, number>
}

`dns.IPFamily`

type IPFamily = 4 | 6

The IP address family: 4 for IPv4 or 6 for IPv6.

`dns.lookup`

dns.lookup(hostname: string, cb: (err: Error | null, address: string | null, family: IPFamily | 0) => void): void

Resolve hostname into an IP address using the operating system's getaddrinfo facility, not the DNS protocol directly. With all: true, the callback receives every resolved address instead of just the first.

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	The host name to resolve.
`cb`	`(err: Error \| null, address: string \| null, family: IPFamily \| 0) => void`	—	Called with `(err, address, family)`, or `(err, addresses)` when `all: true`.

`dns.RecordType`

type RecordType = | 'A'
  | 'AAAA'
  | 'ANY'
  | 'CAA'
  | 'CNAME'
  | 'MX'
  | 'NAPTR'
  | 'NS'
  | 'PTR'
  | 'SOA'
  | 'SRV'
  | 'TLSA'
  | 'TXT'

`dns.resolve: DNSResolver['resolve']`

`dns.resolve4: DNSResolver['resolve4']`

`dns.resolve6: DNSResolver['resolve6']`

`dns.resolveAny: DNSResolver['resolveAny']`

`dns.resolveCaa: DNSResolver['resolveCaa']`

`dns.resolveCname: DNSResolver['resolveCname']`

`dns.resolveMx: DNSResolver['resolveMx']`

`dns.resolveNaptr: DNSResolver['resolveNaptr']`

`dns.resolveNs: DNSResolver['resolveNs']`

`dns.resolvePtr: DNSResolver['resolvePtr']`

`dns.resolveSoa: DNSResolver['resolveSoa']`

`dns.resolveSrv: DNSResolver['resolveSrv']`

`dns.resolveTlsa: DNSResolver['resolveTlsa']`

`dns.resolveTxt: DNSResolver['resolveTxt']`

Use the DNS protocol to resolve TXT records for hostname, on the global resolver. The callback receives an array of records, each itself an array of the strings that make up that record.

`dns.reverse: DNSResolver['reverse']`

`dns.setLocalAddress(ipv4?: string | null, ipv6?: string | null): void`

Parameters

Parameter	Type	Default	Description
`ipv4?`	`string` \| `null`	—	—
`ipv6?`	`string` \| `null`	—	—

`dns.setServers(servers: string[]): void`

Parameters

Parameter	Type	Default	Description
`servers`	`string[]`	—	—

DNSResolver

`new DNSResolver(opts?: DNSResolverOptions)`

An independent resolver for DNS queries over the DNS protocol, with its own servers and local address. Each instance keeps its own set of outstanding queries, which cancel() aborts and destroy() releases.

Parameters

Parameter	Type	Default	Description
`opts?`	`DNSResolverOptions`	—	—

`DNSResolver.cancel(): void`

Aborts every query outstanding on this resolver. Each pending callback is invoked with ECANCELLED.

`DNSResolver.destroy(): void`

Cancels every query outstanding on this resolver, so that none is left without an answer, and releases the resources it holds. A query made after this throws.

`DNSResolver.global: DNSResolver`

`DNSResolver.getServers(): string[]`

`resolve(hostname: string, cb: Callback<string[]>): void`

Overloads:

resolve(hostname: string, cb: Callback<string[]>): void
resolve(hostname: string, rrtype: 'A' | 'AAAA' | 'CNAME' | 'NS' | 'PTR', cb: Callback<string[]>): void
resolve(hostname: string, rrtype: 'TXT', cb: Callback<string[][]>): void
resolve(hostname: string, rrtype: 'MX', cb: Callback<MXRecord[]>): void
resolve(hostname: string, rrtype: 'SRV', cb: Callback<SRVRecord[]>): void
resolve(hostname: string, rrtype: 'NAPTR', cb: Callback<NAPTRRecord[]>): void
resolve(hostname: string, rrtype: 'SOA', cb: Callback<SOARecord>): void
resolve(hostname: string, rrtype: 'CAA', cb: Callback<CAARecord[]>): void
resolve(hostname: string, rrtype: 'TLSA', cb: Callback<TLSARecord[]>): void
resolve(hostname: string, rrtype: 'ANY', cb: Callback<AnyRecord[]>): void

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—
`cb`	`Callback<string[]>`	—	—

`resolve4(hostname: string, cb: Callback<string[]>): void`

Overloads:

resolve4(hostname: string, cb: Callback<string[]>): void
resolve4(hostname: string, opts: { ttl?: false }, cb: Callback<string[]>): void
resolve4(hostname: string, opts: { ttl: true }, cb: Callback<RecordWithTTL[]>): void

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—
`cb`	`Callback<string[]>`	—	—

`resolve6(hostname: string, cb: Callback<string[]>): void`

Overloads:

resolve6(hostname: string, cb: Callback<string[]>): void
resolve6(hostname: string, opts: { ttl?: false }, cb: Callback<string[]>): void
resolve6(hostname: string, opts: { ttl: true }, cb: Callback<RecordWithTTL[]>): void

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—
`cb`	`Callback<string[]>`	—	—

`resolveAny(hostname: string, cb: Callback<AnyRecord[]>): void`

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—
`cb`	`Callback<AnyRecord[]>`	—	—

`resolveCaa(hostname: string, cb: Callback<CAARecord[]>): void`

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—
`cb`	`Callback<CAARecord[]>`	—	—

`resolveCname(hostname: string, cb: Callback<string[]>): void`

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—
`cb`	`Callback<string[]>`	—	—

`resolveMx(hostname: string, cb: Callback<MXRecord[]>): void`

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—
`cb`	`Callback<MXRecord[]>`	—	—

`resolveNaptr(hostname: string, cb: Callback<NAPTRRecord[]>): void`

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—
`cb`	`Callback<NAPTRRecord[]>`	—	—

`resolveNs(hostname: string, cb: Callback<string[]>): void`

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—
`cb`	`Callback<string[]>`	—	—

`resolvePtr(hostname: string, cb: Callback<string[]>): void`

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—
`cb`	`Callback<string[]>`	—	—

`resolveSoa(hostname: string, cb: Callback<SOARecord>): void`

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—
`cb`	`Callback<SOARecord>`	—	—

`resolveSrv(hostname: string, cb: Callback<SRVRecord[]>): void`

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—
`cb`	`Callback<SRVRecord[]>`	—	—

`resolveTlsa(hostname: string, cb: Callback<TLSARecord[]>): void`

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—
`cb`	`Callback<TLSARecord[]>`	—	—

`resolveTxt(hostname: string, cb: Callback<string[][]>): void`

Use the DNS protocol to resolve TXT records for hostname. The callback receives an array of records, each itself an array of the strings that make up that record.

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	The host name to query TXT records for.
`cb`	`Callback<string[][]>`	—	Called with `(err, records)`; each record is an array of the strings it is made of.

`reverse(ip: string, cb: Callback<string[]>): void`

Resolves the pointer records for ip.

This queries the reverse zone for the address only. Unlike Node.js, the hosts file is not consulted first, so an address that is only named there does not resolve.

Parameters

Parameter	Type	Default	Description
`ip`	`string`	—	—
`cb`	`Callback<string[]>`	—	—

`DNSResolver.setLocalAddress(ipv4?: string | null, ipv6?: string | null): void`

Parameters

Parameter	Type	Default	Description
`ipv4?`	`string` \| `null`	—	—
`ipv6?`	`string` \| `null`	—	—

`DNSResolver.setServers(servers: string[]): void`

Parameters

Parameter	Type	Default	Description
`servers`	`string[]`	—	—

DNSError

`DNSError.code: string`

`DNSError.DNSError.INVALID_IP_ADDRESS(msg?: string): DNSError`

Parameters

Parameter	Type	Default	Description
`msg?`	`string`	—	—

`DNSError.DNSError.query(status: number, syscall: string, hostname?: string | null): DNSError`

Parameters

Parameter	Type	Default	Description
`status`	`number`	—	—
`syscall`	`string`	—	—
`hostname?`	`string` \| `null`	—	—

`DNSError.DNSError.RESOLVER_DESTROYED(msg?: string): DNSError`

Parameters

Parameter	Type	Default	Description
`msg?`	`string`	—	—

`DNSError.DNSError.UNKNOWN_RECORD_TYPE(msg?: string): DNSError`

Parameters

Parameter	Type	Default	Description
`msg?`	`string`	—	—

`DNSError.hostname: string`

Present on errors created by DNSError.query() for a named host.

`DNSError.name: 'DNSError'`

`DNSError.syscall: string`

Present on errors created by DNSError.query().

Types

`LookupOptions`

interface LookupOptions {
  family?: `IPv${IPFamily}` | IPFamily | 0
  hints?: number
  all?: boolean
}

`DNSResolverOptions`

interface DNSResolverOptions {
  servers?: string[]
  localAddress?: { ipv4?: string; ipv6?: string }
}

`RecordWithTTL`

interface RecordWithTTL {
  address: string
  ttl: number
}

`MXRecord`

interface MXRecord {
  priority: number
  exchange: string
}

`SRVRecord`

interface SRVRecord {
  priority: number
  weight: number
  port: number
  name: string
}

`NAPTRRecord`

interface NAPTRRecord {
  flags: string
  service: string
  regexp: string
  replacement: string
  order: number
  preference: number
}

`SOARecord`

interface SOARecord {
  nsname: string
  hostmaster: string
  serial: number
  refresh: number
  retry: number
  expire: number
  minttl: number
}

`CAARecord`

interface CAARecord {
  critical: number
  issue?: string
  issuewild?: string
  iodef?: string
  contactemail?: string
  contactphone?: string
}

`TLSARecord`

interface TLSARecord {
  certUsage: number
  selector: number
  match: number
  data: Buffer
}

`bare-dns/promises`

promises

`promises.AnyRecord`

type AnyRecord = | ({ type: 'A' } & RecordWithTTL)
  | ({ type: 'AAAA' } & RecordWithTTL)
  | { type: 'CNAME'; value: string }
  | { type: 'NS'; value: string }
  | { type: 'PTR'; value: string }
  | { type: 'TXT'; entries: string[] }
  | ({ type: 'MX' } & MXRecord)
  | ({ type: 'SRV' } & SRVRecord)
  | ({ type: 'NAPTR' } & NAPTRRecord)
  | ({ type: 'SOA' } & SOARecord)

`promises.cancel(): void`

`promises.constants`

promises.constants: {
  readonly type: {
    readonly A: 1
    readonly NS: 2
    readonly CNAME: 5
    readonly SOA: 6
    readonly PTR: 12
    readonly HINFO: 13
    readonly MX: 15
    readonly TXT: 16
    readonly SIG: 24
    readonly AAAA: 28
    readonly SRV: 33
    readonly NAPTR: 35
    readonly OPT: 41
    readonly TLSA: 52
    readonly SVCB: 64
    readonly HTTPS: 65
    readonly ANY: 255
    readonly URI: 256
    readonly CAA: 257
  }
  readonly status: Record<string, number>
}

`promises.getServers(): string[]`

`promises.lookup`

promises.lookup(hostname: string, opts?: LookupOptions & { all?: false }): Promise<{ address: string; family: IPFamily | 0 }>

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—
`opts?`	`LookupOptions & { all?: false }`	—	—

`promises.resolve: DNSPromiseResolver['resolve']`

`promises.resolve4: DNSPromiseResolver['resolve4']`

`promises.resolve6: DNSPromiseResolver['resolve6']`

`promises.resolveAny: DNSPromiseResolver['resolveAny']`

`promises.resolveCaa: DNSPromiseResolver['resolveCaa']`

`promises.resolveCname: DNSPromiseResolver['resolveCname']`

`promises.resolveMx: DNSPromiseResolver['resolveMx']`

`promises.resolveNaptr: DNSPromiseResolver['resolveNaptr']`

`promises.resolveNs: DNSPromiseResolver['resolveNs']`

`promises.resolvePtr: DNSPromiseResolver['resolvePtr']`

`promises.resolveSoa: DNSPromiseResolver['resolveSoa']`

`promises.resolveSrv: DNSPromiseResolver['resolveSrv']`

`promises.resolveTlsa: DNSPromiseResolver['resolveTlsa']`

`promises.resolveTxt: DNSPromiseResolver['resolveTxt']`

`promises.reverse: DNSPromiseResolver['reverse']`

`promises.setLocalAddress(ipv4?: string | null, ipv6?: string | null): void`

Parameters

Parameter	Type	Default	Description
`ipv4?`	`string` \| `null`	—	—
`ipv6?`	`string` \| `null`	—	—

`promises.setServers(servers: string[]): void`

Parameters

Parameter	Type	Default	Description
`servers`	`string[]`	—	—

DNSPromiseResolver

`new DNSPromiseResolver(opts?: DNSResolverOptions)`

Parameters

Parameter	Type	Default	Description
`opts?`	`DNSResolverOptions`	—	—

resolve(hostname: string, rrtype?: 'A' | 'AAAA' | 'CNAME' | 'NS' | 'PTR'): Promise<string[]>
resolve(hostname: string, rrtype: 'TXT'): Promise<string[][]>
resolve(hostname: string, rrtype: 'MX'): Promise<MXRecord[]>
resolve(hostname: string, rrtype: 'SRV'): Promise<SRVRecord[]>
resolve(hostname: string, rrtype: 'NAPTR'): Promise<NAPTRRecord[]>
resolve(hostname: string, rrtype: 'SOA'): Promise<SOARecord>
resolve(hostname: string, rrtype: 'CAA'): Promise<CAARecord[]>
resolve(hostname: string, rrtype: 'TLSA'): Promise<TLSARecord[]>
resolve(hostname: string, rrtype: 'ANY'): Promise<AnyRecord[]>

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—
`rrtype?`	`'A'` \| `'AAAA'` \| `'CNAME'` \| `'NS'` \| `'PTR'`	—	—

`resolve4(hostname: string, opts?: { ttl?: false }): Promise<string[]>`

Overloads:

resolve4(hostname: string, opts?: { ttl?: false }): Promise<string[]>
resolve4(hostname: string, opts: { ttl: true }): Promise<RecordWithTTL[]>

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—
`opts?`	`{ ttl?: false }`	—	—

`resolve6(hostname: string, opts?: { ttl?: false }): Promise<string[]>`

Overloads:

resolve6(hostname: string, opts?: { ttl?: false }): Promise<string[]>
resolve6(hostname: string, opts: { ttl: true }): Promise<RecordWithTTL[]>

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—
`opts?`	`{ ttl?: false }`	—	—

`resolveAny(hostname: string): Promise<AnyRecord[]>`

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—

`resolveCaa(hostname: string): Promise<CAARecord[]>`

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—

`resolveCname(hostname: string): Promise<string[]>`

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—

`resolveMx(hostname: string): Promise<MXRecord[]>`

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—

`resolveNaptr(hostname: string): Promise<NAPTRRecord[]>`

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—

`resolveNs(hostname: string): Promise<string[]>`

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—

`resolvePtr(hostname: string): Promise<string[]>`

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—

`resolveSoa(hostname: string): Promise<SOARecord>`

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—

`resolveSrv(hostname: string): Promise<SRVRecord[]>`

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—

`resolveTlsa(hostname: string): Promise<TLSARecord[]>`

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—

`resolveTxt(hostname: string): Promise<string[][]>`

Parameters

Parameter	Type	Default	Description
`hostname`	`string`	—	—

`reverse(ip: string): Promise<string[]>`

Resolves the pointer records for ip.

This queries the reverse zone for the address only. Unlike Node.js, the hosts file is not consulted first, so an address that is only named there does not resolve.

Parameters

Parameter	Type	Default	Description
`ip`	`string`	—	—

`DNSPromiseResolver.setLocalAddress(ipv4?: string | null, ipv6?: string | null): void`

Parameters

Parameter	Type	Default	Description
`ipv4?`	`string` \| `null`	—	—
`ipv6?`	`string` \| `null`	—	—

`DNSPromiseResolver.setServers(servers: string[]): void`

Parameters

Parameter	Type	Default	Description
`servers`	`string[]`	—	—

Parameter	Type	Default	Description
`msg?`	`string`	—	—

`DNSError.DNSError.query(status: number, syscall: string, hostname?: string | null): DNSError`

Parameters

Parameter	Type	Default	Description
`status`	`number`	—	—
`syscall`	`string`	—	—
`hostname?`	`string` \| `null`	—	—

`DNSError.DNSError.RESOLVER_DESTROYED(msg?: string): DNSError`

Parameters

Parameter	Type	Default	Description
`msg?`	`string`	—	—

`DNSError.DNSError.UNKNOWN_RECORD_TYPE(msg?: string): DNSError`

Parameters

Parameter	Type	Default	Description
`msg?`	`string`	—	—

interface RecordWithTTL {
  address: string
  ttl: number
}

`promises.MXRecord`

interface MXRecord {
  priority: number
  exchange: string
}

`promises.SRVRecord`

interface SRVRecord {
  priority: number
  weight: number
  port: number
  name: string
}

`promises.NAPTRRecord`

interface NAPTRRecord {
  flags: string
  service: string
  regexp: string
  replacement: string
  order: number
  preference: number
}

`promises.SOARecord`

interface SOARecord {
  nsname: string
  hostmaster: string
  serial: number
  refresh: number
  retry: number
  expire: number
  minttl: number
}

`promises.CAARecord`

interface CAARecord {
  critical: number
  issue?: string
  issuewild?: string
  iodef?: string
  contactemail?: string
  contactphone?: string
}

`promises.TLSARecord`

interface TLSARecord {
  certUsage: number
  selector: number
  match: number
  data: Buffer
}

`promises.LookupOptions`

interface LookupOptions {
  family?: `IPv${IPFamily}` | IPFamily | 0
  hints?: number
  all?: boolean
}

`promises.DNSResolverOptions`

interface DNSResolverOptions {
  servers?: string[]
  localAddress?: { ipv4?: string; ipv6?: string }
}

constants: {
  readonly type: {
    readonly A: 1
    readonly NS: 2
    readonly CNAME: 5
    readonly SOA: 6
    readonly PTR: 12
    readonly HINFO: 13
    readonly MX: 15
    readonly TXT: 16
    readonly SIG: 24
    readonly AAAA: 28
    readonly SRV: 33
    readonly NAPTR: 35
    readonly OPT: 41
    readonly TLSA: 52
    readonly SVCB: 64
    readonly HTTPS: 65
    readonly ANY: 255
    readonly URI: 256
    readonly CAA: 257
  }
  readonly status: Record<string, number>
}

Parameter	Type	Default	Description
`msg?`	`string`	—	—

`DNSError.DNSError.query(status: number, syscall: string, hostname?: string | null): DNSError`

Parameters

Parameter	Type	Default	Description
`status`	`number`	—	—
`syscall`	`string`	—	—
`hostname?`	`string` \| `null`	—	—

`DNSError.DNSError.RESOLVER_DESTROYED(msg?: string): DNSError`

Parameters

Parameter	Type	Default	Description
`msg?`	`string`	—	—

`DNSError.DNSError.UNKNOWN_RECORD_TYPE(msg?: string): DNSError`

Parameters

Parameter	Type	Default	Description
`msg?`	`string`	—	—