@stacksjs/dnsx/dist/types.d.ts

A command-line & library DNS client. Like dig & dog, but for TypeScript.

import type { TransportType } from './transport';
/**
 * Protocol-level tweaks for fine-tuning DNS queries.
 * These options modify the DNS header flags and EDNS parameters.
 */
export declare interface ProtocolTweaks {
  authoritative?: boolean
  authenticData?: boolean
  checkingDisabled?: boolean
  udpPayloadSize?: number
}
/**
 * Transport protocol configuration for DNS queries.
 * Supports multiple transport options with retry and timeout settings.
 */
export declare interface TransportConfig {
  type?: TransportType
  udp?: boolean
  tcp?: boolean
  tls?: boolean
  https?: boolean
  timeout?: number
  retries?: number
}
/**
 * Query configuration for DNS lookups.
 * Specifies what to query and how to query it.
 */
export declare interface QueryConfig {
  domains: string[]
  types?: (RecordType | string)[]
  classes?: (QClass | string)[]
  nameserver?: string
  recursive?: boolean
}
/**
 * Output formatting configuration.
 * Controls how DNS responses are formatted and displayed.
 */
export declare interface OutputConfig {
  short?: boolean
  json?: boolean
  color?: 'always' | 'auto' | 'never'
  seconds?: boolean
  time?: boolean
}
/**
 * Complete configuration options for the DNS client.
 * Combines all configuration aspects into a single interface.
 *
 * @example
 * ```ts
 * const options: DnsOptions = {
 *   domains: ['example.com'],
 *   type: 'A',
 *   nameserver: '1.1.1.1',
 *   edns: 'show',
 *   transport: {
 *     type: 'udp',
 *     timeout: 5000
 *   }
 * }
 * ```
 */
export declare interface DnsOptions {
  domains?: string[]
  type?: string | string[]
  nameserver?: string
  class?: string | string[]
  edns?: EDNSMode
  txid?: number
  Z?: string | string[]
  udp?: boolean
  tcp?: boolean
  tls?: boolean
  https?: boolean
  timeout?: number
  retries?: number
  short?: boolean
  json?: boolean
  color?: 'always' | 'auto' | 'never'
  seconds?: boolean
  time?: boolean
  tweaks?: ProtocolTweaks
  transport?: TransportConfig | TransportType
  query?: QueryConfig
  output?: OutputConfig
  verbose?: boolean
}
/**
 * Represents a single DNS resource record in the response.
 * Contains the record's name, type, class, TTL, and data.
 */
export declare interface DnsAnswer {
  name: string
  type: RecordType
  class: QClass
  ttl: number
  data: any
}
/**
 * Complete DNS response message structure.
 * Contains the message ID, flags, and all record sections.
 */
export declare interface DnsResponse {
  id: number
  flags: DnsFlags
  answers: DnsAnswer[]
  authorities: DnsAnswer[]
  additionals: DnsAnswer[]
}
/**
 * DNS message header flags as defined in RFC 1035.
 * Controls various aspects of DNS message processing.
 */
declare interface DnsFlags {
  response: boolean
  opcode: number
  authoritative: boolean
  truncated: boolean
  recursionDesired: boolean
  recursionAvailable: boolean
  authenticData: boolean
  checkingDisabled: boolean
  responseCode: number
}
/**
 * Structure of a DNS query message.
 * Contains the essential components needed to form a query.
 */
export declare interface DnsQuery {
  name: string
  type: RecordType
  class: QClass
}
/**
 * DNS Record Types as defined in various RFCs.
 * Each type represents a different kind of resource record.
 *
 * Common types:
 * - A (1): IPv4 address
 * - AAAA (28): IPv6 address
 * - MX (15): Mail exchange
 * - TXT (16): Text records
 * - CNAME (5): Canonical name
 * - NS (2): Nameserver
 */
export declare enum RecordType {
  A = 1,
  NS = 2,
  CNAME = 5,
  SOA = 6,
  PTR = 12,
  MX = 15,
  TXT = 16,
  AAAA = 28,
  SRV = 33,
  NAPTR = 35,
  OPT = 41,
  SSHFP = 44,
  TLSA = 52,
  DNSKEY = 48,
  CAA = 257,
}
/**
 * DNS Query Classes as defined in RFC 1035.
 * The class specifies the protocol group of the record.
 */
export declare enum QClass {
  IN = 1, // Internet - Most commonly used
  CH = 3, // CHAOS - Rarely used, mainly for server identification
  HS = 4, // Hesiod - Rarely used, for Hesiod directory service
}
/**
 * EDNS (Extension Mechanisms for DNS) Mode Configuration.
 * Controls how EDNS records are handled in queries and responses.
 */
export declare enum EDNSMode {
  Disable = 'disable', // Don't use EDNS
  Hide = 'hide', // Use EDNS but hide OPT records in output
  Show = 'show', // Use EDNS and show OPT records in output
}
/**
 * Standard DNS response codes as defined in RFC 1035 and others.
 * Indicates the status of the response message.
 */
export declare enum DnsResponseCode {
  NoError = 0, // No error
  FormErr = 1, // Format error
  ServFail = 2, // Server failure
  NXDomain = 3, // Non-existent domain
  NotImp = 4, // Not implemented
  Refused = 5, // Query refused
  YXDomain = 6, // Name exists
  YXRRSet = 7, // RR set exists
  NXRRSet = 8, // RR set does not exist
  NotAuth = 9, // Server not authoritative
  NotZone = 10, // Name not contained in zone
}
/**
 * Error types that can occur during DNS wire format processing.
 * Used for detailed error reporting in protocol handling.
 */
export declare enum WireError {
  TruncatedPacket = 'TRUNCATED_PACKET',
  InvalidLength = 'INVALID_LENGTH',
  InvalidFormat = 'INVALID_FORMAT',
  InvalidName = 'INVALID_NAME',
  InvalidLabel = 'INVALID_LABEL',
  InvalidPointer = 'INVALID_POINTER',
  InvalidType = 'INVALID_TYPE',
  InvalidClass = 'INVALID_CLASS',
  NetworkError = 'NETWORK_ERROR',
}