👾 Diggy

👾 Diggy is a flexible, multi-backend JavaScript DNS resolver for fetching DNS records with support for various resolution methods including DNS over HTTPS, native dig commands, and Node.js built-in DNS functionality.

Features

• ✨ Multiple DNS backends - Choose from Google DoH, Cloudflare DoH, Node.js DNS, or native dig command or even create your own custom resolver!
• 🔒 DNS over HTTPS (DoH) - Secure DNS queries over encrypted connections
• ⚡ Native dig Support - Leverage system DNS tools directly from Node.js
• 🛠️ Node.js Integration - Use built-in Node.js DNS functionality
• 📋 Complete Record Support - Fetch A, AAAA, SOA, CNAME, TXT, MX, SRV, CAA, NAPTR, and more
• 🚀 Zero Dependencies - Lightweight with literally no external dependencies
• 🎯 TypeScript ready - Full type definitions included

📦 Installation

npm install diggy
Copy

yarn add diggy
Copy

pnpm add diggy
Copy

bun add diggy
Copy

🚀 Quick Start

Basic Usage

import { getDnsRecords } from 'diggy';

// Fetch all DNS records for a domain
const allRecords = await getDnsRecords('example.com');
console.log(allRecords);

// Fetch specific record types
const aRecords = await getDnsRecords('example.com', 'A');
const txtRecords = await getDnsRecords('example.com', 'TXT');
const mxRecords = await getDnsRecords('example.com', 'MX');
Copy

TypeScript Support

import { type AnyDNSRecord, getDnsRecords } from 'diggy';
const records: AnyDNSRecord[] = await getDnsRecords('example.com', 'A');
Copy

function getDnsRecords(
  host: string,
  type?: string,
  resolver?: string | BuildInDNSResolver | DNSResolver,
): Promise<AnyDNSRecord[]>
Copy

Parameters:

• host (string): The domain name to query
• type (string, optional): DNS record type (A, AAAA, MX, TXT, etc.). If omitted, returns all available records
• resolver (string | BuildInDNSResolver | DNSResolver, optional): DNS resolver to use

Returns: Promise resolving to an array of DNS records, see Response format for details.

🌍 Browser Usage

You can also use Diggy in the browser via ESM imports. This allows you to fetch DNS records directly from client-side JavaScript. There are built-in resolvers for Google and Cloudflare DNS over HTTPS, which work seamlessly in the browser.

<script type="module">
  import { getDnsRecords } from 'https://esm.sh/diggy';
  const records = await getDnsRecords('ozana.cz');
</script>
Copy

🌐 Available Resolvers

Built-in Resolvers

Diggy includes several pre-configured resolvers:

// Use Google DNS JSON Over HTTPS
const records = await getDnsRecords('example.com', 'A', "google");

// Use Cloudflare DNS JSON Over HTTPS
const records = await getDnsRecords('example.com', 'A', "cloudflare");

// Use nodejs dns module
const records = await getDnsRecords('example.com', 'A', "nodejs");

// Use dig command
const records = await getDnsRecords('example.com', 'A', "dig");
Copy

Resolver	Description	Environment
google	Google DNS over HTTPS	Browsers, Node.js
cloudflare	Cloudflare DNS over HTTPS	Browsers, Node.js
nodejs	Node.js built-in DNS module	Node.js only
dig	Native dig command	Node.js only, requires dig installed

Configure built-in resolvers

Create your own DNS resolver for custom endpoints:

import { getDnsRecords, dohResolver } from 'diggy';

const customDohResolver = dohResolver("https://custom.dns.provider/resolve");
const records = await getDnsRecords('example.com', 'TXT', customDohResolver);
Copy

💡 Tip: Find more public DoH endpoints here

Just like with dohResolver, you can also use digResolver or nodeResolver and specify a custom DNS server:

import { getDnsRecords, digResolver, nodeResolver } from 'diggy';

// Native nodejs dns resolver witg specific DNS server
const customNodejsResolver = nodeResolver(['8.8.8.8']);
const records = await getDnsRecords('example.com', 'A', customNodejsResolver);

// Native dig command with specific DNS server
const customDigResolver = digResolver('1.1.1.1');
const records = await getDnsRecords('example.com', 'A', customDigResolver);
Copy

💡 Tip: Find more public DNS servers here

You can also create your own custom resolver by implementing the DNSResolver interface:

export type DNSResolver = (
  host: string,
  type: DNSRecordType,
) => Promise<AnyDNSRecord[]>;
Copy

📝 Supported Record Types

Type	Description	Example Use Case
A	IPv4 address	Website hosting
AAAA	IPv6 address	IPv6 connectivity
CNAME	Canonical name	Domain aliases
MX	Mail exchange	Email routing
TXT	Text records	SPF, DKIM, verification
SOA	Start of authority	Zone information
SRV	Service records	Service discovery
CAA	Certificate authority	SSL/TLS security
NAPTR	Name authority pointer	ENUM, SIP routing

Response Format

DNS records are returned as an array of objects with the following structure:

import { CaaRecordData, MxRecordData, SoaRecordData, SrvRecordData, NaptrRecordData } from "./types";

interface AnyDNSRecord {
  name: string;    // Domain name
  type: string;    // Record type (A, AAAA, MX, etc.)
  ttl: number;     // Time-to-live in seconds

  // Record data (format varies by type)
  data:
    | string
    | string[]
    | MxRecordData
    | SoaRecordData
    | CaaRecordData
    | NaptrRecordData
    | SrvRecordData;
}
Copy

Example Response

[
  {
    "name": "example.com",
    "type": "SOA",
    "ttl": 3600,
    "data": {
      "nsname": "ns1.example.com.",
      "hostmaster": "hostmaster.example.com.",
      "serial": 2025051204,
      "refresh": 10800,
      "retry": 3600,
      "expire": 604800,
      "minttl": 3600
    }
  },
  {
    "name": "example.cz",
    "type": "A",
    "ttl": 1800,
    "data": "66.33.66.33"
  },
  {
    "name": "example.cz",
    "type": "MX",
    "ttl": 60,
    "data": {
      "priority": 10,
      "exchange": "mail.example.com"
    }
  }
]
Copy

🔧 Requirements

• Node.js: Version 22 or higher
• dig command: Required only when using the 'dig' resolver
• Internet connection: Required for DoH resolvers (google, cloudflare)

📄 License

MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

Made with ❤️ by the Roman Ožana