diggy 1.0.1 → 1.0.2

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

@@ -1,2 +1,49 @@
-import type { AnyDNSRecord, BuildInDNSResolver, DNSResolver } from "./types";
+import { type BuildInDNSResolver } from "./get-resolver";
+import type { DNSResolver } from "./resolvers/DNSResolver";
+import type { AnyDNSRecord } from "./types";
+/**
+ * Fetches DNS records for a given `host` and type. When no `type` is specified,
+ * it retrieves all available DNS records for the host.
+ *
+ * @example Fetch all DNS records for a host
+ * ```ts
+ * import { getDnsRecords } from "diggy";
+ * const records = await getDnsRecords("example.com");
+ * console.log(records);
+ * ```
+ *
+ * @example Get A records for a host
+ * ```ts
+ * import { getDnsRecords } from "diggy";
+ * const aRecords = await getDnsRecords("example.com", "A");
+ * console.log(aRecords);
+ * ```
+ *
+ * @example Change the DNS resolver (built-in resolvers)
+ * ```ts
+ * import { getDnsRecords } from "diggy";
+ * const records = await getDnsRecords("example.com", "A", "google");
+ * console.log(records);
+ * ```
+ *
+ * @example Use Node.js DNS resolver
+ * ```ts
+ * import { getDnsRecords } from "diggy";
+ * const records = await getDnsRecords("example.com", "A", "nodejs");
+ * console.log(records);
+ * ```
+ *
+ * @example Use a custom DNS resolver
+ * ```ts
+ * import { getDnsRecords } from "diggy";
+ * import { customResolver } from "./my-custom-resolver";
+ * const records = await getDnsRecords("example.com", "A", customResolver);
+ * console.log(records);
+ * ```
+ *
+ * @param host - The domain or host for which to fetch DNS records e.g. "example.com".
+ * @param type - The type of DNS record to fetch (e.g., "A", "AAAA", "MX"). If not specified, all records will be fetched.
+ * @param resolver - The DNS resolver to use. It can be a built-in resolver name (like "google" or "cloudflare"), a custom resolver function, or a string URL for a DoH resolver.
+ * @group Main Functions
+ */
 export declare function getDnsRecords(host: string, type?: string, resolver?: string | BuildInDNSResolver | DNSResolver): Promise<AnyDNSRecord[]>;

package/dist/get-dns-records.js

@@ -1,6 +1,51 @@
 import { getResolver } from "./get-resolver";
 import { resolveAllRecords } from "./utils/resolve-all-records";
 import { toDnsType } from "./utils/to-dns-type";
+/**
+ * Fetches DNS records for a given `host` and type. When no `type` is specified,
+ * it retrieves all available DNS records for the host.
+ *
+ * @example Fetch all DNS records for a host
+ * ```ts
+ * import { getDnsRecords } from "diggy";
+ * const records = await getDnsRecords("example.com");
+ * console.log(records);
+ * ```
+ *
+ * @example Get A records for a host
+ * ```ts
+ * import { getDnsRecords } from "diggy";
+ * const aRecords = await getDnsRecords("example.com", "A");
+ * console.log(aRecords);
+ * ```
+ *
+ * @example Change the DNS resolver (built-in resolvers)
+ * ```ts
+ * import { getDnsRecords } from "diggy";
+ * const records = await getDnsRecords("example.com", "A", "google");
+ * console.log(records);
+ * ```
+ *
+ * @example Use Node.js DNS resolver
+ * ```ts
+ * import { getDnsRecords } from "diggy";
+ * const records = await getDnsRecords("example.com", "A", "nodejs");
+ * console.log(records);
+ * ```
+ *
+ * @example Use a custom DNS resolver
+ * ```ts
+ * import { getDnsRecords } from "diggy";
+ * import { customResolver } from "./my-custom-resolver";
+ * const records = await getDnsRecords("example.com", "A", customResolver);
+ * console.log(records);
+ * ```
+ *
+ * @param host - The domain or host for which to fetch DNS records e.g. "example.com".
+ * @param type - The type of DNS record to fetch (e.g., "A", "AAAA", "MX"). If not specified, all records will be fetched.
+ * @param resolver - The DNS resolver to use. It can be a built-in resolver name (like "google" or "cloudflare"), a custom resolver function, or a string URL for a DoH resolver.
+ * @group Main Functions
+ */
 export function getDnsRecords(host, type, resolver) {
     const dnsResolver = getResolver(resolver);
     const dnsType = toDnsType(type);

package/dist/get-resolver.d.ts

@@ -1,2 +1,35 @@
-import type { BuildInDNSResolver, DNSResolver } from "./types";
+import type { DNSResolver } from "./resolvers/DNSResolver";
+/**
+ * Represents the built-in DNS resolvers available in the library.
+ * @enum {string}
+ * @property {string} nodejs - Uses Node.js's built-in DNS resolver.
+ * @property {string} dig - Uses the `dig` command-line tool for DNS resolution.
+ * @property {string} google - Uses Google's DNS over HTTPS (DoH) resolver.
+ * @property {string} cloudflare - Uses Cloudflare's DNS over HTTPS (DoH) resolver.
+ * @group Resolvers
+ */
+export declare enum BuildInDNSResolver {
+    nodejs = "nodejs",
+    dig = "dig",
+    google = "google",
+    cloudflare = "cloudflare"
+}
+/**
+ * Returns a DNS resolver function based on the provided resolver name or function.
+ *
+ * If a `string` is provided, it must match one of the built-in resolvers.
+ * If a `function` is provided, it will be returned as is.
+ * If no resolver is provided, the default resolver (Google's DoH) will be used
+ *
+ * @example
+ * ```ts
+ * import { getResolver } from "diggy";
+ * const resolver = getResolver("google"); // Returns the Google DoH resolver
+ * ```
+ *
+ *
+ * @param {string | BuildInDNSResolver | DNSResolver} [resolver] - The name of the built-in resolver or a custom resolver function.
+ * @return {DNSResolver} The DNS resolver function.
+ * @group Main Functions
+ */
 export declare function getResolver(resolver?: string | BuildInDNSResolver | DNSResolver): DNSResolver;

package/dist/get-resolver.js

@@ -1,12 +1,46 @@
 import { digResolver } from "./resolvers/dig-resolver";
 import { dohResolver } from "./resolvers/doh-resolver";
 import { nodeResolver } from "./resolvers/node-resolver";
+/**
+ * Represents the built-in DNS resolvers available in the library.
+ * @enum {string}
+ * @property {string} nodejs - Uses Node.js's built-in DNS resolver.
+ * @property {string} dig - Uses the `dig` command-line tool for DNS resolution.
+ * @property {string} google - Uses Google's DNS over HTTPS (DoH) resolver.
+ * @property {string} cloudflare - Uses Cloudflare's DNS over HTTPS (DoH) resolver.
+ * @group Resolvers
+ */
+export var BuildInDNSResolver;
+(function (BuildInDNSResolver) {
+    BuildInDNSResolver["nodejs"] = "nodejs";
+    BuildInDNSResolver["dig"] = "dig";
+    BuildInDNSResolver["google"] = "google";
+    BuildInDNSResolver["cloudflare"] = "cloudflare";
+})(BuildInDNSResolver || (BuildInDNSResolver = {}));
 const resolvers = {
     nodejs: nodeResolver(),
     dig: digResolver(),
     google: dohResolver("https://dns.google/resolve"),
     cloudflare: dohResolver("https://cloudflare-dns.com/dns-query"),
 };
+/**
+ * Returns a DNS resolver function based on the provided resolver name or function.
+ *
+ * If a `string` is provided, it must match one of the built-in resolvers.
+ * If a `function` is provided, it will be returned as is.
+ * If no resolver is provided, the default resolver (Google's DoH) will be used
+ *
+ * @example
+ * ```ts
+ * import { getResolver } from "diggy";
+ * const resolver = getResolver("google"); // Returns the Google DoH resolver
+ * ```
+ *
+ *
+ * @param {string | BuildInDNSResolver | DNSResolver} [resolver] - The name of the built-in resolver or a custom resolver function.
+ * @return {DNSResolver} The DNS resolver function.
+ * @group Main Functions
+ */
 export function getResolver(resolver) {
     if (typeof resolver === "function") {
         return resolver;

package/dist/index.d.ts

@@ -1,3 +1,11 @@
 export * from "./get-dns-records";
 export * from "./get-resolver";
+export * from "./resolvers/DNSResolver";
+export * from "./resolvers/dig-resolver";
+export * from "./resolvers/doh-resolver";
+export * from "./resolvers/dot-resolver";
+export * from "./resolvers/node-resolver";
 export * from "./types";
+export * from "./utils/resolve-all-records";
+export * from "./utils/to-dns-record";
+export * from "./utils/to-dns-type";

package/dist/index.js

@@ -1,3 +1,11 @@
 export * from "./get-dns-records";
 export * from "./get-resolver";
+export * from "./resolvers/DNSResolver";
+export * from "./resolvers/dig-resolver";
+export * from "./resolvers/doh-resolver";
+export * from "./resolvers/dot-resolver";
+export * from "./resolvers/node-resolver";
 export * from "./types";
+export * from "./utils/resolve-all-records";
+export * from "./utils/to-dns-record";
+export * from "./utils/to-dns-type";

package/dist/resolvers/DNSResolver.d.ts

@@ -0,0 +1,11 @@
+import type { AnyDNSRecord, DNSRecordType } from "../types";
+/**
+ * DNSResolver is a function type that takes a host and a DNS record type,
+ * and returns a promise that resolves to an array of DNS records.
+ * It is used to fetch DNS records for a given host and type.
+ *
+ * @param host - The domain or host for which to fetch DNS records (e.g., "example.com").
+ * @param type - The type of DNS record to fetch (e.g., "A", "AAAA", "MX").
+ * @group Resolvers
+ */
+export type DNSResolver = (host: string, type: DNSRecordType) => Promise<AnyDNSRecord[]>;

package/dist/resolvers/DNSResolver.js

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

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

@@ -1,2 +1,24 @@
-import type { DNSResolver } from "../types";
+import type { DNSResolver } from "./DNSResolver";
+/**
+ * Returns a DNS resolver that uses the `dig` command to resolve DNS records.
+ *
+ * ```ts
+ * import { digResolver } from "diggy";
+ * const resolver = digResolver();
+ * const records = await resolver("example.com", "A");
+ * console.log(records);
+ * ```
+ *
+ * You can also specify the DNS server to use by passing it as an argument:
+ *
+ * ```ts
+ * import { digResolver } from "diggy";
+ * const resolver = digResolver("1.1.1.1");
+ * const records = await resolver("example.com", "A");
+ * console.log(records);
+ *```
+ *
+ * @param server - The DNS server to use (optional). If not provided, the default system resolver will be used.
+ * @group Resolvers
+ */
 export declare function digResolver(server?: string): DNSResolver;

package/dist/resolvers/dig-resolver.js

@@ -1,4 +1,26 @@
 import { toDnsRecord } from "../utils/to-dns-record";
+/**
+ * Returns a DNS resolver that uses the `dig` command to resolve DNS records.
+ *
+ * ```ts
+ * import { digResolver } from "diggy";
+ * const resolver = digResolver();
+ * const records = await resolver("example.com", "A");
+ * console.log(records);
+ * ```
+ *
+ * You can also specify the DNS server to use by passing it as an argument:
+ *
+ * ```ts
+ * import { digResolver } from "diggy";
+ * const resolver = digResolver("1.1.1.1");
+ * const records = await resolver("example.com", "A");
+ * console.log(records);
+ *```
+ *
+ * @param server - The DNS server to use (optional). If not provided, the default system resolver will be used.
+ * @group Resolvers
+ */
 export function digResolver(server) {
     return async (host, type) => {
         const args = [];

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

@@ -1,2 +1,17 @@
-import type { DNSResolver } from "../types";
+import type { DNSResolver } from "./DNSResolver";
+/**
+ * Returns a DNS resolver that uses DNS over HTTPS (DoH) to resolve DNS records.
+ *
+ * ```ts
+ * import { dohResolver } from "diggy";
+ * const resolver = dohResolver("https://dns.google/resolve");
+ * const records = await resolver("example.com", "A");
+ * console.log(records);
+ * ```
+ *
+ * > 💡 **Tip:** Find more public [DoH endpoints here](https://github.com/curl/curl/wiki/DNS-over-HTTPS)
+ *
+ * @param url - The URL of the DoH server to use (e.g., `https://dns.google/resolve`).
+ * @group Resolvers
+ */
 export declare function dohResolver(url: string): DNSResolver;

package/dist/resolvers/doh-resolver.js

@@ -1,21 +1,19 @@
 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"],
-]);
+/**
+ * Returns a DNS resolver that uses DNS over HTTPS (DoH) to resolve DNS records.
+ *
+ * ```ts
+ * import { dohResolver } from "diggy";
+ * const resolver = dohResolver("https://dns.google/resolve");
+ * const records = await resolver("example.com", "A");
+ * console.log(records);
+ * ```
+ *
+ * > 💡 **Tip:** Find more public [DoH endpoints here](https://github.com/curl/curl/wiki/DNS-over-HTTPS)
+ *
+ * @param url - The URL of the DoH server to use (e.g., `https://dns.google/resolve`).
+ * @group Resolvers
+ */
 export function dohResolver(url) {
     const dnsUrl = new URL(url);
     return async (host, type) => {
@@ -40,3 +38,20 @@ export function dohResolver(url) {
         });
     };
 }
+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"],
+]);

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

@@ -1,2 +1,26 @@
-import { type DNSResolver } from "../types";
+import type { DNSResolver } from "./DNSResolver";
+/**
+ * Returns a DNS resolver that uses Node.js's built-in DNS module.
+ *
+ * @example
+ * Without any additional configuration, it will use the system's default DNS servers.
+ *
+ *  ```ts
+ * import { nodeResolver } from "diggy";
+ * const resolver = nodeResolver();
+ * const records = await resolver("example.com", "A");
+ * ```
+ *
+ * @example
+ * You can specify a list of DNS servers to use.
+ *
+ * ```ts
+ * import { nodeResolver } from "diggy";
+ * const resolver = nodeResolver(["8.8.8.8", "1.1.1.1"]);
+ * const records = await resolver("example.com", "A");
+ * ```
+ *
+ * @param servers - An array of DNS server addresses to use. If empty, the system's default DNS servers will be used.
+ * @group Resolvers
+ */
 export declare function nodeResolver(servers?: string[]): DNSResolver;

package/dist/resolvers/node-resolver.js

@@ -1,5 +1,29 @@
 import * as _dns from "node:dns/promises";
 import { DNSRecordType } from "../types";
+/**
+ * Returns a DNS resolver that uses Node.js's built-in DNS module.
+ *
+ * @example
+ * Without any additional configuration, it will use the system's default DNS servers.
+ *
+ *  ```ts
+ * import { nodeResolver } from "diggy";
+ * const resolver = nodeResolver();
+ * const records = await resolver("example.com", "A");
+ * ```
+ *
+ * @example
+ * You can specify a list of DNS servers to use.
+ *
+ * ```ts
+ * import { nodeResolver } from "diggy";
+ * const resolver = nodeResolver(["8.8.8.8", "1.1.1.1"]);
+ * const records = await resolver("example.com", "A");
+ * ```
+ *
+ * @param servers - An array of DNS server addresses to use. If empty, the system's default DNS servers will be used.
+ * @group Resolvers
+ */
 export function nodeResolver(servers = []) {
     const dns = new _dns.Resolver();
     if (servers.length > 0) {

package/dist/types.d.ts

@@ -1,5 +1,21 @@
-export type DNSResolver = (host: string, type: DNSRecordType) => Promise<AnyDNSRecord[]>;
-export type BuildInDNSResolver = "nodejs" | "dig" | "google" | "cloudflare";
+/**
+ * Represents the type of DNS records that can be queried.
+ *
+ * @enum {string}
+ * @property {string} A - IPv4 address record.
+ * @property {string} AAAA - IPv6 address record.
+ * @property {string} CAA - Certification Authority Authorization record.
+ * @property {string} CNAME - Canonical Name record, used for aliasing one domain to another.
+ * @property {string} NAPTR - Naming Authority Pointer record, used for service discovery.
+ * @property {string} MX - Mail Exchange record, used for email routing.
+ * @property {string} NS - Name Server record, indicating the authoritative DNS servers for a domain.
+ * @property {string} PTR - Pointer record, used for reverse DNS lookups.
+ * @property {string} SOA - Start of Authority record, providing information about the DNS zone.
+ * @property {string} SRV - Service record, used to define the location of services.
+ * @property {string} TXT - Text record, used for arbitrary text data, often for verification purposes.
+ *
+ * @group DNS Records
+ */
 export declare enum DNSRecordType {
     A = "A",
     AAAA = "AAAA",
@@ -13,10 +29,27 @@ export declare enum DNSRecordType {
     SRV = "SRV",
     TXT = "TXT"
 }
+/**
+ * Represents the data for a DNS MX (Mail Exchange) record.
+ * @property exchange - The mail server that will handle emails for the domain.
+ * @property priority - The priority of the mail server, where lower values indicate higher priority.
+ * @group DNS Records
+ */
 export type MxRecordData = {
     exchange: string;
     priority: number;
 };
+/**
+ * Represents the data for a DNS SOA (Start of Authority) record.
+ * @property nsname - The name server for the domain.
+ * @property hostmaster - The email address of the domain administrator (formatted as a string with a dot instead of an '@').
+ * @property serial - The serial number of the SOA record.
+ * @property refresh - The time interval (in seconds) before the zone should be refreshed.
+ * @property retry - The time interval (in seconds) before a retry should be attempted if the refresh fails.
+ * @property expire - The time interval (in seconds) before the zone expires if it cannot be refreshed.
+ * @property minttl - The minimum time-to-live (TTL) for the zone, indicating how long the record should be cached by resolvers.
+ * @group DNS Records
+ */
 export type SoaRecordData = {
     nsname: string;
     hostmaster: string;
@@ -26,11 +59,28 @@ export type SoaRecordData = {
     expire: number;
     minttl: number;
 };
+/**
+ * Represents the data for a DNS CAA (Certification Authority Authorization) record.
+ * @property flags - The flags for the CAA record, indicating whether the record is critical or not.
+ * @property tag - The tag for the CAA record, indicating the type of authorization (e.g., "issue", "issuewild", "iodef").
+ * @property value - The value for the CAA record, which specifies the authorized certificate authority or other information.
+ * @group DNS Records
+ */
 export type CaaRecordData = {
     flags: number;
     tag: string;
     value: string;
 };
+/**
+ * Represents the data for a DNS NAPTR (Naming Authority Pointer) record.
+ * @property order - The order of the NAPTR record, used to determine the sequence in which records should be processed.
+ * @property preference - The preference of the NAPTR record, used to determine the order of preference among multiple records.
+ * @property flags - The flags for the NAPTR record, which can indicate various properties (e.g., "U" for URI, "S" for service).
+ * @property service - The service type for the NAPTR record, indicating the type of service provided (e.g., "SIP+D2U").
+ * @property regexp - The regular expression for the NAPTR record, which can be used to transform the domain name.
+ * @property replacement - The replacement string for the NAPTR record, which can be used to replace the domain name.
+ * @group DNS Records
+ */
 export type NaptrRecordData = {
     order: number;
     preference: number;
@@ -39,16 +89,32 @@ export type NaptrRecordData = {
     regexp: string;
     replacement: string;
 };
+/**
+ * Represents the data for a DNS SRV (Service) record.
+ * @property priority - The priority of the SRV record, used to determine the order in which services should be used.
+ * @property weight - The weight of the SRV record, used to distribute traffic among multiple services with the same priority.
+ * @property port - The port number on which the service is running.
+ * @property name - The target domain name of the service, which can be a hostname or an IP address.
+ * @group DNS Records
+ */
 export type SrvRecordData = {
     priority: number;
     weight: number;
     port: number;
     name: string;
 };
+/**
+ * @group DNS Records
+ */
 export type DNSRecord<T = string | string[]> = {
     name: string;
     type: DNSRecordType;
     ttl?: number;
     data: T;
 };
+/**
+ * Represents any DNS record type, including A, AAAA, CAA, CNAME, NAPTR, MX, NS, PTR, SOA, SRV, and TXT records.
+ * This type is a union of the generic DNSRecord type and specific record types like MxRecordData.
+ * @group DNS Records
+ */
 export type AnyDNSRecord = DNSRecord | DNSRecord<MxRecordData> | DNSRecord<SoaRecordData> | DNSRecord<CaaRecordData> | DNSRecord<NaptrRecordData> | DNSRecord<SrvRecordData>;

package/dist/types.js

@@ -1,3 +1,21 @@
+/**
+ * Represents the type of DNS records that can be queried.
+ *
+ * @enum {string}
+ * @property {string} A - IPv4 address record.
+ * @property {string} AAAA - IPv6 address record.
+ * @property {string} CAA - Certification Authority Authorization record.
+ * @property {string} CNAME - Canonical Name record, used for aliasing one domain to another.
+ * @property {string} NAPTR - Naming Authority Pointer record, used for service discovery.
+ * @property {string} MX - Mail Exchange record, used for email routing.
+ * @property {string} NS - Name Server record, indicating the authoritative DNS servers for a domain.
+ * @property {string} PTR - Pointer record, used for reverse DNS lookups.
+ * @property {string} SOA - Start of Authority record, providing information about the DNS zone.
+ * @property {string} SRV - Service record, used to define the location of services.
+ * @property {string} TXT - Text record, used for arbitrary text data, often for verification purposes.
+ *
+ * @group DNS Records
+ */
 export var DNSRecordType;
 (function (DNSRecordType) {
     DNSRecordType["A"] = "A";

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

@@ -1,2 +1,12 @@
-import { type AnyDNSRecord, type DNSResolver } from "../types";
+import type { DNSResolver } from "../resolvers/DNSResolver";
+import { type AnyDNSRecord } from "../types";
+/**
+ * Resolves all DNS records for a given host using the specified resolver.
+ * This function attempts to resolve all types of DNS records defined in `DNSRecordType`.
+ * If a record type cannot be resolved, it will be skipped.
+ *
+ * @param host - The domain or host for which to resolve DNS records (e.g., "example.com").
+ * @param resolver - The DNS resolver function to use. It should accept a host and a DNS record type,
+ * @group Utilities
+ */
 export declare function resolveAllRecords(host: string, resolver: DNSResolver): Promise<AnyDNSRecord[]>;

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

@@ -1,4 +1,13 @@
 import { DNSRecordType } from "../types";
+/**
+ * Resolves all DNS records for a given host using the specified resolver.
+ * This function attempts to resolve all types of DNS records defined in `DNSRecordType`.
+ * If a record type cannot be resolved, it will be skipped.
+ *
+ * @param host - The domain or host for which to resolve DNS records (e.g., "example.com").
+ * @param resolver - The DNS resolver function to use. It should accept a host and a DNS record type,
+ * @group Utilities
+ */
 export async function resolveAllRecords(host, resolver) {
     const allTypes = Object.values(DNSRecordType);
     const records = await Promise.allSettled(allTypes.map((t) => resolver(host, t)));

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

@@ -1,5 +1,16 @@
 import { type AnyDNSRecord } from "../types";
 type InputData = string | string[];
+/**
+ * Converts input data to a DNS record format.
+ * This function takes a name, type, optional TTL, and data,
+ * and returns an object representing a DNS record.
+ *
+ * @param name - The name of the DNS record, e.g., "example.com".
+ * @param type - The type of DNS record, e.g., "A", "AAAA", "MX", etc.
+ * @param ttl - The time-to-live (TTL) for the DNS record, in seconds. Defaults to 0 if not provided.
+ * @param data - The data associated with the DNS record, which can vary based on the type.
+ * @group Utilities
+ */
 export declare function toDnsRecord({ name, type, ttl, data, }: {
     name: string;
     type: string;

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

@@ -39,6 +39,17 @@ function convertDataByType(type, data) {
     }
     return Array.isArray(data) ? data.join(" ") : data;
 }
+/**
+ * Converts input data to a DNS record format.
+ * This function takes a name, type, optional TTL, and data,
+ * and returns an object representing a DNS record.
+ *
+ * @param name - The name of the DNS record, e.g., "example.com".
+ * @param type - The type of DNS record, e.g., "A", "AAAA", "MX", etc.
+ * @param ttl - The time-to-live (TTL) for the DNS record, in seconds. Defaults to 0 if not provided.
+ * @param data - The data associated with the DNS record, which can vary based on the type.
+ * @group Utilities
+ */
 export function toDnsRecord({ name, type, ttl, data, }) {
     return {
         // remove trailing dot from name

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

@@ -1,2 +1,16 @@
 import { DNSRecordType } from "../types";
+/**
+ * Converts a string representation of a DNS record type to the corresponding `DNSRecordType` enum value.
+ * If the input string does not match any valid DNS record type, it returns `undefined`.
+ *
+ * @example
+ * ```ts
+ * import { toDnsType } from "diggy";
+ * console.log(toDnsType("A")); // Output: "A"
+ * console.log(toDnsType("MX")); // Output: "MX"
+ * console.log(toDnsType("INVALID")); // Output: undefined
+ * ```
+ * @param type - The string representation of the DNS record type (e.g., "A", "AAAA", "MX").
+ * @group Utilities
+ */
 export declare function toDnsType(type?: string): DNSRecordType | undefined;

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

@@ -1,4 +1,18 @@
 import { DNSRecordType } from "../types";
+/**
+ * Converts a string representation of a DNS record type to the corresponding `DNSRecordType` enum value.
+ * If the input string does not match any valid DNS record type, it returns `undefined`.
+ *
+ * @example
+ * ```ts
+ * import { toDnsType } from "diggy";
+ * console.log(toDnsType("A")); // Output: "A"
+ * console.log(toDnsType("MX")); // Output: "MX"
+ * console.log(toDnsType("INVALID")); // Output: undefined
+ * ```
+ * @param type - The string representation of the DNS record type (e.g., "A", "AAAA", "MX").
+ * @group Utilities
+ */
 export function toDnsType(type) {
     if (!type)
         return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "diggy",
-	"version": "1.0.1",
+	"version": "1.0.2",
 	"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>",
@@ -39,13 +39,15 @@
 		"prepare": "npm run build",
 		"test": "tsc --noEmit && vitest",
 		"format": "biome check --write .",
-		"format:check": "biome check ."
+		"format:check": "biome check .",
+		"docs": "typedoc"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.1.4",
 		"@types/node": "^24.2.1",
 		"np": "^10.2.0",
 		"tsx": "^4.20.4",
+		"typedoc": "^0.28.10",
 		"typescript": "^5.9.2",
 		"vitest": "^3.2.4"
 	}

package/readme.md

@@ -60,15 +60,14 @@ const mxRecords = await getDnsRecords('example.com', 'MX');
 
 ```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,
+  host: string,
+  type?: string,
+  resolver?: string | BuildInDNSResolver | DNSResolver,
 ): Promise<AnyDNSRecord[]>
 ```
 
@@ -78,9 +77,9 @@ function getDnsRecords(
 - `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
+**Returns:** Promise resolving to an array of DNS records, see [Response format](#response-format) for details.
 
-## 🌍 Browser Usage
+### 🌍 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.
@@ -88,9 +87,8 @@ JavaScript. There are built-in resolvers for Google and Cloudflare DNS over HTTP
 ```html
 
 <script type="module">
-	import { getDnsRecords } from 'https://esm.sh/diggy';
-	
-	const records = await getDnsRecords('ozana.cz');
+  import { getDnsRecords } from 'https://esm.sh/diggy';
+  const records = await getDnsRecords('ozana.cz');
 </script>
 ```
 
@@ -154,8 +152,8 @@ You can also **create your own custom resolver** by implementing the `DNSResolve
 
 ```typescript
 export type DNSResolver = (
-	host: string,
-	type: DNSRecordType,
+  host: string,
+  type: DNSRecordType,
 ) => Promise<AnyDNSRecord[]>;
 ```
 
@@ -173,7 +171,7 @@ export type DNSResolver = (
 | CAA   | Certificate authority  | SSL/TLS security        |
 | NAPTR | Name authority pointer | ENUM, SIP routing       |
 
-## 📜 Response Format
+## Response Format
 
 DNS records are returned as an array of objects with the following structure:
 
@@ -181,19 +179,19 @@ 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;
+  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;
 }
 ```
 
@@ -201,41 +199,41 @@ interface AnyDNSRecord {
 
 ```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"
-		}
-	}
+  {
+    "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
+- **Node.js**: Version 22 or higher
 - **dig command**: Required only when using the 'dig' resolver
 - **Internet connection**: Required for DoH resolvers (google, cloudflare)