diggy 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Roman Ožana <roman@ozana.cz> (https://ozana.cz/)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/get-dns-records.d.ts

@@ -0,0 +1,2 @@
+import type { AnyDNSRecord, BuildInDNSResolver, DNSResolver } from "./types";
+export declare function getDnsRecords(host: string, type?: string, resolver?: string | BuildInDNSResolver | DNSResolver): Promise<AnyDNSRecord[]>;

package/dist/get-dns-records.js

@@ -0,0 +1,10 @@
+import { getResolver } from "./get-resolver";
+import { resolveAllRecords } from "./utils/resolve-all-records";
+import { toDnsType } from "./utils/to-dns-type";
+export function getDnsRecords(host, type, resolver) {
+    const dnsResolver = getResolver(resolver);
+    const dnsType = toDnsType(type);
+    return dnsType
+        ? dnsResolver(host, dnsType)
+        : resolveAllRecords(host, dnsResolver);
+}

package/dist/get-resolver.d.ts

@@ -0,0 +1,2 @@
+import type { BuildInDNSResolver, DNSResolver } from "./types";
+export declare function getResolver(resolver?: string | BuildInDNSResolver | DNSResolver): DNSResolver;

package/dist/get-resolver.js

@@ -0,0 +1,18 @@
+import { digResolver } from "./resolvers/dig-resolver";
+import { dohResolver } from "./resolvers/doh-resolver";
+import { nodeResolver } from "./resolvers/node-resolver";
+const resolvers = {
+    nodejs: nodeResolver(),
+    dig: digResolver(),
+    google: dohResolver("https://dns.google/resolve"),
+    cloudflare: dohResolver("https://cloudflare-dns.com/dns-query"),
+};
+export function getResolver(resolver) {
+    if (typeof resolver === "function") {
+        return resolver;
+    }
+    if (typeof resolver === "string" && resolver in resolvers) {
+        return resolvers[resolver];
+    }
+    return resolvers.google;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./get-dns-records";
+export * from "./get-resolver";
+export * from "./types";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./get-dns-records";
+export * from "./get-resolver";
+export * from "./types";

package/dist/resolvers/dig-resolver.d.ts

@@ -0,0 +1,2 @@
+import type { DNSResolver } from "../types";
+export declare function digResolver(server?: string): DNSResolver;

package/dist/resolvers/dig-resolver.js

@@ -0,0 +1,32 @@
+import { toDnsRecord } from "../utils/to-dns-record";
+export function digResolver(server) {
+    return async (host, type) => {
+        const args = [];
+        if (server) {
+            if (!server.startsWith("@")) {
+                server = `@${server}`;
+            }
+            args.push(server);
+        }
+        args.push(host, type);
+        const { spawnSync } = await import("node:child_process");
+        // Use spawnSync to run the dig command synchronously and capture the output
+        const dig = spawnSync("dig", [...args, "+noall", "+answer", "+cdflag"]);
+        const results = dig.stdout.toString();
+        const records = [];
+        // split lines & ignore comments or empty lines
+        results
+            .split("\n")
+            .filter((line) => line.length && !line.startsWith(";"))
+            .forEach((line) => {
+            const parts = line.replace(/\t+/g, " ").split(" ");
+            records.push(toDnsRecord({
+                name: parts[0] ?? "",
+                ttl: Number(parts[1]),
+                type: parts[3],
+                data: parts.slice(4).join(" "),
+            }));
+        });
+        return records;
+    };
+}

package/dist/resolvers/doh-resolver.d.ts

@@ -0,0 +1,2 @@
+import type { DNSResolver } from "../types";
+export declare function dohResolver(url: string): DNSResolver;

package/dist/resolvers/doh-resolver.js

@@ -0,0 +1,42 @@
+import { toDnsRecord } from "../utils/to-dns-record";
+const DNSTypeNumbers = new Map([
+    [1, "A"],
+    [2, "NS"],
+    [5, "CNAME"],
+    [6, "SOA"],
+    [12, "PTR"],
+    [15, "MX"],
+    [16, "TXT"],
+    [24, "SIG"],
+    [25, "KEY"],
+    [28, "AAAA"],
+    [33, "SRV"],
+    [35, "NAPTR"],
+    [43, "DS"],
+    [48, "DNSKEY"],
+    [257, "CAA"],
+]);
+export function dohResolver(url) {
+    const dnsUrl = new URL(url);
+    return async (host, type) => {
+        dnsUrl.searchParams.set("name", host);
+        dnsUrl.searchParams.set("type", type);
+        const re = await fetch(dnsUrl, {
+            headers: { accept: "application/dns-json" },
+        });
+        if (!re.ok) {
+            throw new Error(`Error fetching DNS records for ${host}: ${re.status} ${re.statusText}`);
+        }
+        const json = (await re.json());
+        if (!Array.isArray(json.Answer))
+            return []; // No records found
+        return json.Answer.map((record) => {
+            return toDnsRecord({
+                name: record.name,
+                type: DNSTypeNumbers.get(record.type) ?? "UNKNOWN",
+                ttl: record.TTL,
+                data: record.data,
+            });
+        });
+    };
+}

package/dist/resolvers/dot-resolver.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/resolvers/dot-resolver.js

@@ -0,0 +1,2 @@
+export {};
+// TODO: write a DNS Over TLS resolver :)

package/dist/resolvers/node-resolver.d.ts

@@ -0,0 +1,2 @@
+import { type DNSResolver } from "../types";
+export declare function nodeResolver(servers?: string[]): DNSResolver;

package/dist/resolvers/node-resolver.js

@@ -0,0 +1,45 @@
+import * as _dns from "node:dns/promises";
+import { DNSRecordType } from "../types";
+export function nodeResolver(servers = []) {
+    const dns = new _dns.Resolver();
+    if (servers.length > 0) {
+        dns.setServers(servers);
+    }
+    return async (host, type) => {
+        try {
+            // Handle special cases for A and AAAA records to include TTL
+            if (type === DNSRecordType.A || type === DNSRecordType.AAAA) {
+                const records = type === DNSRecordType.A
+                    ? await dns.resolve4(host, { ttl: true })
+                    : await dns.resolve6(host, { ttl: true });
+                return records.map(({ address, ttl }) => ({
+                    name: host,
+                    type: type,
+                    ttl: ttl,
+                    data: address,
+                }));
+            }
+            // Handle SOA (is not an array)
+            if (type === DNSRecordType.SOA) {
+                const record = await dns.resolveSoa(host);
+                return [
+                    {
+                        name: host,
+                        type: type,
+                        data: record,
+                    },
+                ];
+            }
+            // Handle CAA, MX, NAPTR, NS, PTR, SRV, TXT (all return arrays)
+            const records = (await dns.resolve(host, type));
+            return records.map((record) => ({
+                name: host,
+                type: type,
+                data: Array.isArray(record) ? record.join(" ") : record,
+            }));
+        }
+        catch {
+            return [];
+        }
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,54 @@
+export type DNSResolver = (host: string, type: DNSRecordType) => Promise<AnyDNSRecord[]>;
+export type BuildInDNSResolver = "nodejs" | "dig" | "google" | "cloudflare";
+export declare enum DNSRecordType {
+    A = "A",
+    AAAA = "AAAA",
+    CAA = "CAA",
+    CNAME = "CNAME",
+    NAPTR = "NAPTR",
+    MX = "MX",
+    NS = "NS",
+    PTR = "PTR",
+    SOA = "SOA",
+    SRV = "SRV",
+    TXT = "TXT"
+}
+export type MxRecordData = {
+    exchange: string;
+    priority: number;
+};
+export type SoaRecordData = {
+    nsname: string;
+    hostmaster: string;
+    serial: number;
+    refresh: number;
+    retry: number;
+    expire: number;
+    minttl: number;
+};
+export type CaaRecordData = {
+    flags: number;
+    tag: string;
+    value: string;
+};
+export type NaptrRecordData = {
+    order: number;
+    preference: number;
+    flags: string;
+    service: string;
+    regexp: string;
+    replacement: string;
+};
+export type SrvRecordData = {
+    priority: number;
+    weight: number;
+    port: number;
+    name: string;
+};
+export type DNSRecord<T = string | string[]> = {
+    name: string;
+    type: DNSRecordType;
+    ttl?: number;
+    data: T;
+};
+export type AnyDNSRecord = DNSRecord | DNSRecord<MxRecordData> | DNSRecord<SoaRecordData> | DNSRecord<CaaRecordData> | DNSRecord<NaptrRecordData> | DNSRecord<SrvRecordData>;

package/dist/types.js

@@ -0,0 +1,14 @@
+export var DNSRecordType;
+(function (DNSRecordType) {
+    DNSRecordType["A"] = "A";
+    DNSRecordType["AAAA"] = "AAAA";
+    DNSRecordType["CAA"] = "CAA";
+    DNSRecordType["CNAME"] = "CNAME";
+    DNSRecordType["NAPTR"] = "NAPTR";
+    DNSRecordType["MX"] = "MX";
+    DNSRecordType["NS"] = "NS";
+    DNSRecordType["PTR"] = "PTR";
+    DNSRecordType["SOA"] = "SOA";
+    DNSRecordType["SRV"] = "SRV";
+    DNSRecordType["TXT"] = "TXT";
+})(DNSRecordType || (DNSRecordType = {}));

package/dist/utils/resolve-all-records.d.ts

@@ -0,0 +1,2 @@
+import { type AnyDNSRecord, type DNSResolver } from "../types";
+export declare function resolveAllRecords(host: string, resolver: DNSResolver): Promise<AnyDNSRecord[]>;

package/dist/utils/resolve-all-records.js

@@ -0,0 +1,8 @@
+import { DNSRecordType } from "../types";
+export async function resolveAllRecords(host, resolver) {
+    const allTypes = Object.values(DNSRecordType);
+    const records = await Promise.allSettled(allTypes.map((t) => resolver(host, t)));
+    return records
+        .filter((record) => record.status === "fulfilled")
+        .flatMap((record) => record.value);
+}

package/dist/utils/to-dns-record.d.ts

@@ -0,0 +1,9 @@
+import { type AnyDNSRecord } from "../types";
+type InputData = string | string[];
+export declare function toDnsRecord({ name, type, ttl, data, }: {
+    name: string;
+    type: string;
+    ttl?: number;
+    data: InputData;
+}): AnyDNSRecord;
+export {};

package/dist/utils/to-dns-record.js

@@ -0,0 +1,53 @@
+import { DNSRecordType, } from "../types";
+function convertDataByType(type, data) {
+    switch (type) {
+        case DNSRecordType.SOA: {
+            const parts = String(data).split(" ");
+            if (parts.length < 7) {
+                throw new Error("Invalid SOA record format");
+            }
+            return {
+                nsname: (parts[0] ?? "").replace(/\.$/, ""),
+                hostmaster: (parts[1] ?? "").replace(/\.$/, ""),
+                serial: parseInt(parts[2] ?? "", 10),
+                refresh: parseInt(parts[3] ?? "", 10),
+                retry: parseInt(parts[4] ?? "", 10),
+                expire: parseInt(parts[5] ?? "", 10),
+                minttl: parseInt(parts[6] ?? "", 10),
+            };
+        }
+        case DNSRecordType.MX: {
+            const mx = String(data).split(" ");
+            if (mx.length < 2) {
+                throw new Error("Invalid MX record format");
+            }
+            return {
+                priority: parseInt(mx[0] ?? "", 10),
+                exchange: mx.slice(1).join(" ").replace(/\.$/, ""),
+            };
+        }
+        case DNSRecordType.TXT: {
+            const txt = String(data) ?? "";
+            // Cloudflare or dig returns TXT records as `"rec1" "rec2" "rec3 "` need to be parsed
+            if (txt.startsWith('"') && txt.endsWith('"')) {
+                const matches = txt.match(/"([^"]*)"/g);
+                return matches
+                    ? matches.map((part) => part.replace(/"/g, ""))
+                    : [];
+            }
+        }
+    }
+    return Array.isArray(data) ? data.join(" ") : data;
+}
+export function toDnsRecord({ name, type, ttl, data, }) {
+    return {
+        // remove trailing dot from name
+        name: name.replace(/\.$/, ""),
+        // ensure type is a valid DNSRecordType
+        type: type,
+        // default ttl to 0 if not provided
+        ttl: ttl ?? 0,
+        // convert data based on type
+        data: convertDataByType(type, data),
+    };
+}

package/dist/utils/to-dns-type.d.ts

@@ -0,0 +1,2 @@
+import { DNSRecordType } from "../types";
+export declare function toDnsType(type?: string): DNSRecordType | undefined;

package/dist/utils/to-dns-type.js

@@ -0,0 +1,9 @@
+import { DNSRecordType } from "../types";
+export function toDnsType(type) {
+    if (!type)
+        return undefined;
+    const typeUpper = type.toUpperCase();
+    return Object.values(DNSRecordType).includes(typeUpper)
+        ? typeUpper
+        : undefined;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+	"name": "diggy",
+	"version": "1.0.0",
+	"description": "Multi-backend DNS resolver for Node.js/Browser — supports dig, DNS over HTTPS, and native Node.js DNS.",
+	"repository": "git@github.com:OzzyCzech/diggy.git",
+	"author": "Roman Ožana <roman@ozana.cz>",
+	"keywords": [
+		"dns",
+		"dig",
+		"dns-over-https",
+		"DoH",
+		"nodejs",
+		"browser",
+		"dns-resolver",
+		"resolver",
+		"lookup",
+		"dns-client",
+		"dns-server",
+		"dns-tools",
+		"google-dns",
+		"cloudflare-dns",
+		"dns-over-tls",
+		"js-dns"
+	],
+	"license": "MIT",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"type": "module",
+	"exports": {
+		"types": "./dist/index.d.ts",
+		"default": "./dist/index.js"
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "rm -rf dist && tsc",
+		"release": "np",
+		"prepare": "npm run build",
+		"test": "tsc --noEmit && vitest",
+		"format": "biome check --write .",
+		"format:check": "biome check ."
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.1.4",
+		"@types/node": "^24.2.1",
+		"np": "^10.2.0",
+		"tsx": "^4.20.4",
+		"typescript": "^5.9.2",
+		"vitest": "^3.2.4"
+	}
+}

package/readme.md

@@ -0,0 +1,238 @@
+# 👾 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](https://linux.die.net/man/1/dig) directly from Node.js
+- **🛠️ Node.js Integration** - Use built-in Node.js [DNS functionality](https://nodejs.org/api/dns.html)
+- **📋 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
+
+```bash
+npm install diggy
+```
+
+```bash
+yarn add diggy
+```
+
+```bash
+pnpm add diggy
+```
+
+```bash
+bun add diggy
+```
+
+## 🚀 Quick Start
+
+### Basic Usage
+
+```javascript
+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');
+```
+
+### TypeScript Support
+
+```typescript
+import { type AnyDNSRecord, getDnsRecords } from 'diggy';
+
+const records: AnyDNSRecord[] = await getDnsRecords('example.com', 'A');
+```
+
+```typescript
+function getDnsRecords(
+  host: string,
+  type?: string,
+  resolver?: string | BuildInDNSResolver | DNSResolver,
+): Promise<AnyDNSRecord[]>
+```
+
+**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
+
+## 🌐 Available Resolvers
+
+### Built-in Resolvers
+
+Diggy includes several pre-configured resolvers:
+
+```javascript
+// 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");
+```
+
+| Resolver     | Description                 | Environment               |
+|--------------|-----------------------------|---------------------------|
+| `google`     | Google DNS over HTTPS       | Works in Browser          |
+| `cloudflare` | Cloudflare DNS over HTTPS   | Works in Browser          |
+| `nodejs`     | Node.js built-in DNS module | Node.js runtime           |
+| `dig`        | Native dig command          | `dig` installed on system |
+
+### Configure built-in resolvers
+
+Create your own DNS resolver for custom endpoints:
+
+```javascript
+import { getDnsRecords, dohResolver } from 'diggy';
+
+const customDohResolver = dohResolver("https://custom.dns.provider/resolve");
+const records = await getDnsRecords('example.com', 'TXT', customDohResolver);
+```
+
+> 💡 **Tip:** Find more public [DoH endpoints here](https://github.com/curl/curl/wiki/DNS-over-HTTPS)
+
+Just like with `dohResolver`, you can also use `digResolver` or `nodeResolver` and specify a custom DNS server:
+
+```javascript
+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);
+```
+
+> 💡 **Tip:** Find more public [DNS servers here](https://public-dns.info/)
+
+You can also **create your own custom resolver** by implementing the `DNSResolver` interface:
+
+```typescript
+export type DNSResolver = (
+  host: string,
+  type: DNSRecordType,
+) => Promise<AnyDNSRecord[]>;
+```
+
+## 📝 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:
+
+```typescript
+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;
+}
+```
+
+### Example Response
+
+```json
+[
+  {
+    "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"
+    }
+  }
+]
+```
+
+## 🔧 Requirements
+
+- **Node.js**: Version 14 or higher
+- **dig command**: Required only when using the 'dig' resolver
+- **Internet connection**: Required for DoH resolvers (google, cloudflare)
+
+## 📄 License
+
+[MIT License](LICENSE) - see the [LICENSE](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](https://ozana.cz)