dns-sd-browser 1.0.0

package/dist/browser.d.ts

@@ -0,0 +1,145 @@
+export class ServiceBrowser {
+    /**
+     * @param {MdnsTransport} transport
+     * @param {object} options
+     * @param {string} options.queryName - e.g. "_http._tcp.local"
+     * @param {string} options.serviceType - e.g. "_http._tcp"
+     * @param {string} options.domain - e.g. "local"
+     * @param {string} options.protocol - e.g. "tcp"
+     * @param {boolean} [options.isTypeEnumeration] - true for browseAll
+     * @param {AbortSignal} [options.signal]
+     * @param {() => void} [options.onDestroy] - Called when the browser is destroyed
+     * @param {number} [options.reconfirmTimeoutMs] - Reconfirmation timeout (ms), default 10000
+     * @param {number} [options.poofTimeoutMs=10000] - POOF window (RFC 6762 §10.5)
+     * @param {number} [options.poofResponseWaitMs=2000] - Time to wait for response before counting as unanswered
+     */
+    constructor(transport: MdnsTransport, { queryName, serviceType, domain, protocol, isTypeEnumeration, signal, onDestroy, reconfirmTimeoutMs, poofTimeoutMs, poofResponseWaitMs }: {
+        queryName: string;
+        serviceType: string;
+        domain: string;
+        protocol: string;
+        isTypeEnumeration?: boolean | undefined;
+        signal?: AbortSignal | undefined;
+        onDestroy?: (() => void) | undefined;
+        reconfirmTimeoutMs?: number | undefined;
+        poofTimeoutMs?: number | undefined;
+        poofResponseWaitMs?: number | undefined;
+    });
+    /**
+     * Currently discovered services, keyed by FQDN.
+     * @type {Map<string, Service>}
+     */
+    services: Map<string, Service>;
+    /**
+     * Manually remove a service by FQDN, emitting a `serviceDown` event.
+     *
+     * Use this when your application detects that a service is unreachable
+     * (e.g. via a health check) before its TTL expires. The service is removed
+     * from the `services` Map and its known-answer record is cleared, so it
+     * will be re-discovered if the advertiser announces it again.
+     *
+     * @param {string} fqdn - Fully qualified service name (e.g. "My Service._http._tcp.local")
+     * @returns {boolean} true if the service was found and removed, false otherwise
+     */
+    removeService(fqdn: string): boolean;
+    /**
+     * Request reconfirmation of a service record (RFC 6762 §10.4).
+     * Sends verification queries and removes the service if no response
+     * is received within the timeout.
+     * @param {string} fqdn - The service FQDN to reconfirm
+     */
+    reconfirm(fqdn: string): void;
+    /**
+     * Flush all discovered services and restart querying from scratch.
+     *
+     * Call this after a network interface change (e.g. WiFi reconnect).
+     * All current services are emitted as `serviceDown` events, caches are
+     * cleared, and querying restarts with the initial rapid schedule.
+     */
+    resetNetwork(): void;
+    /**
+     * Stop browsing and end the async iterator.
+     * @param {any} [reason] - If provided, the iterator throws this instead of
+     *   returning done: true (matching Node.js convention for AbortSignal).
+     */
+    destroy(reason?: any): void;
+    /** @returns {Promise<void>} */
+    [Symbol.asyncDispose](): Promise<void>;
+    /** @returns {AsyncIterableIterator<BrowseEvent>} */
+    [Symbol.asyncIterator](): AsyncIterableIterator<BrowseEvent>;
+    #private;
+}
+/**
+ * AllServiceBrowser — discovers all service instances on the network by
+ * first enumerating service types (RFC 6763 §9), then spawning a
+ * ServiceBrowser for each discovered type.
+ *
+ * Presents the same async iterable interface as ServiceBrowser, yielding
+ * fully resolved BrowseEvents with real host, port, and addresses.
+ */
+export class AllServiceBrowser {
+    /**
+     * @param {MdnsTransport} transport
+     * @param {object} options
+     * @param {string} options.domain
+     * @param {AbortSignal} [options.signal]
+     * @param {() => void} [options.onDestroy]
+     */
+    constructor(transport: MdnsTransport, { domain, signal, onDestroy }: {
+        domain: string;
+        signal?: AbortSignal | undefined;
+        onDestroy?: (() => void) | undefined;
+    });
+    /**
+     * Merged live map of all discovered service instances across all types.
+     * @type {Map<string, Service>}
+     */
+    services: Map<string, Service>;
+    /**
+     * Get the first discovered service. Resolves as soon as any service
+     * instance emits a serviceUp event.
+     * @returns {Promise<Service>}
+     */
+    first(): Promise<Service>;
+    /**
+     * Flush all discovered services and restart querying from scratch.
+     *
+     * Call this after a network interface change (e.g. WiFi reconnect).
+     * Delegates to each internal ServiceBrowser and clears the merged
+     * services map.
+     */
+    resetNetwork(): void;
+    /**
+     * Stop all sub-browsers and end the async iterator.
+     * @param {any} [reason] - If provided, the iterator throws this instead of
+     *   returning done: true (matching Node.js convention for AbortSignal).
+     */
+    destroy(reason?: any): void;
+    /** @returns {Promise<void>} */
+    [Symbol.asyncDispose](): Promise<void>;
+    /** @returns {AsyncIterableIterator<BrowseEvent>} */
+    [Symbol.asyncIterator](): AsyncIterableIterator<BrowseEvent>;
+    #private;
+}
+export type Service = import("./service.js").Service;
+export type DnsPacket = import("./dns.js").DnsPacket;
+export type DnsRecord = import("./dns.js").DnsRecord;
+export type MdnsTransport = import("./transport.js").MdnsTransport;
+export type BrowseEvent = {
+    type: "serviceUp";
+    service: Service;
+} | {
+    type: "serviceDown";
+    service: Service;
+} | {
+    type: "serviceUpdated";
+    service: Service;
+};
+/**
+ * Resolves a promise externally — used for the async iterator's event queue.
+ */
+export type Deferred<T> = {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (reason?: unknown) => void;
+};

package/dist/constants.d.ts

@@ -0,0 +1,12 @@
+/** mDNS multicast IPv4 address (RFC 6762 §3) */
+export const MDNS_ADDRESS: "224.0.0.251";
+/** mDNS multicast IPv6 address (RFC 6762 §3) */
+export const MDNS_ADDRESS_V6: "FF02::FB";
+/** mDNS default port (RFC 6762 §3) */
+export const MDNS_PORT: 5353;
+/** mDNS multicast TTL — must be 255 per RFC 6762 §11 */
+export const MDNS_TTL: 255;
+/** Meta-query name for service type enumeration (RFC 6763 §9) */
+export const SERVICE_TYPE_ENUMERATION: "_services._dns-sd._udp.local";
+/** Default domain for mDNS */
+export const DEFAULT_DOMAIN: "local";

package/dist/dns.d.ts

@@ -0,0 +1,155 @@
+/**
+ * @typedef {object} DnsFlags
+ * @property {boolean} qr - true for response, false for query
+ * @property {number} opcode
+ * @property {boolean} aa - Authoritative Answer
+ * @property {boolean} tc - Truncated
+ * @property {boolean} rd - Recursion Desired
+ * @property {boolean} ra - Recursion Available
+ * @property {number} rcode - Response code
+ */
+/**
+ * @typedef {object} DnsQuestion
+ * @property {string} name
+ * @property {number} type - RecordType value
+ * @property {boolean} [qu] - QU (unicast-response) bit (RFC 6762 §5.4)
+ */
+/**
+ * @typedef {object} SrvData
+ * @property {number} priority
+ * @property {number} weight
+ * @property {number} port
+ * @property {string} target
+ */
+/**
+ * @typedef {object} DnsRecord
+ * @property {string} name
+ * @property {number} type - RecordType value
+ * @property {number} class - Usually 1 (IN)
+ * @property {boolean} cacheFlush - mDNS cache-flush bit
+ * @property {number} ttl
+ * @property {string | SrvData | Uint8Array[]} data - Type-specific data
+ */
+/**
+ * @typedef {object} DnsPacket
+ * @property {number} id
+ * @property {DnsFlags} flags
+ * @property {DnsQuestion[]} questions
+ * @property {DnsRecord[]} answers
+ * @property {DnsRecord[]} authorities
+ * @property {DnsRecord[]} additionals
+ */
+/**
+ * Decode a DNS packet from a buffer.
+ * @param {Uint8Array} buf
+ * @returns {DnsPacket}
+ */
+export function decode(buf: Uint8Array): DnsPacket;
+/**
+ * @typedef {object} QueryOptions
+ * @property {DnsQuestion[]} questions
+ * @property {DnsRecord[]} [answers] - Known answers for suppression (RFC 6762 §7.1)
+ */
+/**
+ * Encode an mDNS query into one or more packets.
+ * If the known-answer list is too large for a single packet, splits across
+ * multiple packets per RFC 6762 §7.2: the first packet contains the question
+ * and sets the TC bit, continuation packets contain only answers (QDCOUNT=0).
+ * @param {QueryOptions} options
+ * @returns {Buffer[]} - Array of encoded packets (usually 1)
+ */
+export function encodeQueryPackets({ questions, answers }: QueryOptions): Buffer[];
+/**
+ * Encode a single mDNS query packet.
+ * @param {QueryOptions} options
+ * @returns {Buffer}
+ */
+export function encodeQuery({ questions, answers }: QueryOptions): Buffer;
+export type RecordType = number;
+export namespace RecordType {
+    let A: 1;
+    let PTR: 12;
+    let TXT: 16;
+    let AAAA: 28;
+    let SRV: 33;
+    let ANY: 255;
+}
+export type DnsFlags = {
+    /**
+     * - true for response, false for query
+     */
+    qr: boolean;
+    opcode: number;
+    /**
+     * - Authoritative Answer
+     */
+    aa: boolean;
+    /**
+     * - Truncated
+     */
+    tc: boolean;
+    /**
+     * - Recursion Desired
+     */
+    rd: boolean;
+    /**
+     * - Recursion Available
+     */
+    ra: boolean;
+    /**
+     * - Response code
+     */
+    rcode: number;
+};
+export type DnsQuestion = {
+    name: string;
+    /**
+     * - RecordType value
+     */
+    type: number;
+    /**
+     * - QU (unicast-response) bit (RFC 6762 §5.4)
+     */
+    qu?: boolean | undefined;
+};
+export type SrvData = {
+    priority: number;
+    weight: number;
+    port: number;
+    target: string;
+};
+export type DnsRecord = {
+    name: string;
+    /**
+     * - RecordType value
+     */
+    type: number;
+    /**
+     * - Usually 1 (IN)
+     */
+    class: number;
+    /**
+     * - mDNS cache-flush bit
+     */
+    cacheFlush: boolean;
+    ttl: number;
+    /**
+     * - Type-specific data
+     */
+    data: string | SrvData | Uint8Array[];
+};
+export type DnsPacket = {
+    id: number;
+    flags: DnsFlags;
+    questions: DnsQuestion[];
+    answers: DnsRecord[];
+    authorities: DnsRecord[];
+    additionals: DnsRecord[];
+};
+export type QueryOptions = {
+    questions: DnsQuestion[];
+    /**
+     * - Known answers for suppression (RFC 6762 §7.1)
+     */
+    answers?: DnsRecord[] | undefined;
+};

package/dist/index.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @typedef {import('./service.js').Service} Service
+ * @typedef {import('./browser.js').BrowseEvent} BrowseEvent
+ */
+export class DnsSdBrowser {
+    /**
+     * @param {object} [options]
+     * @param {number} [options.port=5353] - mDNS port
+     * @param {string} [options.interface] - Network interface IP to bind to
+     */
+    constructor(options?: {
+        port?: number | undefined;
+        interface?: string | undefined;
+    });
+    /**
+     * Start browsing for a specific service type.
+     *
+     * Returns a ServiceBrowser that is an async iterable yielding BrowseEvents
+     * as services appear, disappear, or update on the network.
+     *
+     * @param {string | { name: string, protocol?: string }} serviceType
+     *   Service type to browse for. Either a string like "_http._tcp" or
+     *   an object like `{ name: 'http', protocol: 'tcp' }`.
+     * @param {object} [options]
+     * @param {AbortSignal} [options.signal] - Signal to cancel browsing
+     * @param {string} [options.subtype] - Browse a service subtype (RFC 6763 §7.1).
+     *   e.g. `browse('_http._tcp', { subtype: '_printer' })` queries
+     *   `_printer._sub._http._tcp.local`.
+     * @param {number} [options.reconfirmTimeoutMs] - Reconfirmation timeout (ms) per RFC 6762 §10.4
+     * @param {number} [options.poofTimeoutMs] - POOF window (ms) per RFC 6762 §10.5
+     * @param {number} [options.poofResponseWaitMs] - POOF response wait (ms) per RFC 6762 §10.5
+     * @returns {ServiceBrowser}
+     */
+    browse(serviceType: string | {
+        name: string;
+        protocol?: string;
+    }, options?: {
+        signal?: AbortSignal | undefined;
+        subtype?: string | undefined;
+        reconfirmTimeoutMs?: number | undefined;
+        poofTimeoutMs?: number | undefined;
+        poofResponseWaitMs?: number | undefined;
+    }): ServiceBrowser;
+    /**
+     * Browse for all service instances on the network, regardless of type.
+     *
+     * Discovers service types via `_services._dns-sd._udp.local` (RFC 6763 §9),
+     * then automatically browses each discovered type for instances. Returns
+     * fully resolved BrowseEvents with real host, port, and addresses — the
+     * same as `browse()` but across all types.
+     *
+     * @param {object} [options]
+     * @param {AbortSignal} [options.signal]
+     * @returns {AllServiceBrowser}
+     */
+    browseAll(options?: {
+        signal?: AbortSignal | undefined;
+    }): AllServiceBrowser;
+    /**
+     * Browse for service types on the network.
+     *
+     * Queries `_services._dns-sd._udp.local` (RFC 6763 §9) to discover
+     * which service types are being advertised. Returns lightweight
+     * Service objects representing types (not instances) — `host`, `port`,
+     * and `addresses` will be empty.
+     *
+     * For discovering fully resolved service instances across all types,
+     * use `browseAll()` instead.
+     *
+     * @param {object} [options]
+     * @param {AbortSignal} [options.signal]
+     * @returns {ServiceBrowser}
+     */
+    browseTypes(options?: {
+        signal?: AbortSignal | undefined;
+    }): ServiceBrowser;
+    /**
+     * Re-join multicast groups and restart all browsers.
+     *
+     * Call this after a network interface change (e.g. WiFi reconnect,
+     * Ethernet re-plug). The OS drops multicast group membership when an
+     * interface goes down; this method re-establishes it and flushes stale
+     * service state.
+     *
+     * All current services are emitted as `serviceDown` events, and
+     * querying restarts with the initial rapid schedule so services on
+     * the new network are discovered quickly.
+     */
+    rejoin(): void;
+    /**
+     * Stop all browsers and close the mDNS transport.
+     * @returns {Promise<void>}
+     */
+    destroy(): Promise<void>;
+    /**
+     * Returns a promise that resolves when the mDNS transport is ready
+     * to send and receive packets. Useful for tests or when you need
+     * to ensure the socket is bound before external interaction.
+     *
+     * Note: the transport is started lazily on the first `browse()` or
+     * `browseAll()` call. Calling `ready()` before any browse will throw.
+     * @returns {Promise<void>}
+     */
+    ready(): Promise<void>;
+    /** @returns {Promise<void>} */
+    [Symbol.asyncDispose](): Promise<void>;
+    #private;
+}
+export type Service = import("./service.js").Service;
+export type BrowseEvent = import("./browser.js").BrowseEvent;
+import { ServiceBrowser } from './browser.js';
+import { AllServiceBrowser } from './browser.js';
+export { ServiceBrowser, AllServiceBrowser } from "./browser.js";

package/dist/service.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Service data type for discovered DNS-SD services.
+ * @module
+ */
+/**
+ * @typedef {object} Service
+ * @property {string} name - Instance name (e.g. "My Printer")
+ * @property {string} type - Service type (e.g. "_http._tcp")
+ * @property {string} protocol - Transport protocol ("tcp" or "udp")
+ * @property {string} domain - Domain (default "local")
+ * @property {string} host - Target hostname (e.g. "printer.local")
+ * @property {number} port - Port number
+ * @property {string[]} addresses - IPv4 and IPv6 addresses
+ * @property {Record<string, string | true>} txt - Parsed TXT key-value pairs
+ * @property {Record<string, Uint8Array>} txtRaw - Raw TXT record values
+ * @property {string} fqdn - Fully qualified service name
+ * @property {string[]} subtypes - Service subtypes
+ * @property {number} updatedAt - Timestamp of last update (ms)
+ */
+/**
+ * Parse TXT record data (array of Uint8Array strings) into key-value pairs.
+ *
+ * Per RFC 6763 §6.3:
+ * - Format is "key=value" where value is the part after the first '='
+ * - Keys without '=' are boolean flags (value is `true`)
+ * - Duplicate keys: only the first occurrence is used
+ * - Keys are case-insensitive but we preserve original casing
+ *
+ * @param {Uint8Array[]} txtData
+ * @returns {{ txt: Record<string, string | true>, txtRaw: Record<string, Uint8Array> }}
+ */
+export function parseTxtData(txtData: Uint8Array[]): {
+    txt: Record<string, string | true>;
+    txtRaw: Record<string, Uint8Array>;
+};
+/**
+ * Parse a service type string into its components.
+ *
+ * Accepts either:
+ * - Full form: "_http._tcp" or "_http._tcp.local"
+ * - Object form: { name: "http", protocol: "tcp" }
+ *
+ * @param {string | { name: string, protocol?: string }} serviceType
+ * @returns {{ type: string, protocol: string, domain: string, queryName: string }}
+ */
+export function parseServiceType(serviceType: string | {
+    name: string;
+    protocol?: string;
+}): {
+    type: string;
+    protocol: string;
+    domain: string;
+    queryName: string;
+};
+/**
+ * Extract the instance name from a fully qualified service name.
+ *
+ * Given "My Service._http._tcp.local" and type "_http._tcp",
+ * returns "My Service".
+ *
+ * @param {string} fqdn
+ * @param {string} serviceType - e.g. "_http._tcp.local"
+ * @returns {string}
+ */
+export function extractInstanceName(fqdn: string, serviceType: string): string;
+export type Service = {
+    /**
+     * - Instance name (e.g. "My Printer")
+     */
+    name: string;
+    /**
+     * - Service type (e.g. "_http._tcp")
+     */
+    type: string;
+    /**
+     * - Transport protocol ("tcp" or "udp")
+     */
+    protocol: string;
+    /**
+     * - Domain (default "local")
+     */
+    domain: string;
+    /**
+     * - Target hostname (e.g. "printer.local")
+     */
+    host: string;
+    /**
+     * - Port number
+     */
+    port: number;
+    /**
+     * - IPv4 and IPv6 addresses
+     */
+    addresses: string[];
+    /**
+     * - Parsed TXT key-value pairs
+     */
+    txt: Record<string, string | true>;
+    /**
+     * - Raw TXT record values
+     */
+    txtRaw: Record<string, Uint8Array>;
+    /**
+     * - Fully qualified service name
+     */
+    fqdn: string;
+    /**
+     * - Service subtypes
+     */
+    subtypes: string[];
+    /**
+     * - Timestamp of last update (ms)
+     */
+    updatedAt: number;
+};

package/dist/transport.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @callback PacketHandler
+ * @param {dns.DnsPacket} packet
+ * @returns {void}
+ */
+export class MdnsTransport {
+    /**
+     * @param {object} [options]
+     * @param {number} [options.port] - mDNS port (default 5353)
+     * @param {string} [options.interface] - Network interface IP to bind to
+     */
+    constructor(options?: {
+        port?: number | undefined;
+        interface?: string | undefined;
+    });
+    /**
+     * Start the transport: bind sockets and join multicast groups.
+     * Always binds IPv4. Attempts IPv6 but does not fail if unavailable.
+     * @returns {Promise<void>}
+     */
+    start(): Promise<void>;
+    /**
+     * Send an mDNS query on IPv4 (and IPv6 if available).
+     * @param {dns.QueryOptions} queryOptions
+     * @returns {Promise<void>}
+     */
+    sendQuery(queryOptions: dns.QueryOptions): Promise<void>;
+    /**
+     * Register a handler for incoming mDNS response packets.
+     * @param {PacketHandler} handler
+     */
+    addHandler(handler: PacketHandler): void;
+    /**
+     * Remove a previously registered handler.
+     * @param {PacketHandler} handler
+     */
+    removeHandler(handler: PacketHandler): void;
+    /**
+     * Register a handler for incoming mDNS query packets (QR=0).
+     * Used for duplicate question suppression (RFC 6762 §7.3) and
+     * Passive Observation of Failures (RFC 6762 §10.5).
+     * @param {PacketHandler} handler
+     */
+    addQueryHandler(handler: PacketHandler): void;
+    /**
+     * Remove a previously registered query handler.
+     * @param {PacketHandler} handler
+     */
+    removeQueryHandler(handler: PacketHandler): void;
+    /**
+     * Re-join multicast groups on existing sockets.
+     *
+     * Call this after a network interface change (e.g. WiFi reconnect,
+     * Ethernet re-plug). The OS drops multicast group membership when an
+     * interface goes down; this method re-establishes it so the socket
+     * can receive multicast responses again.
+     */
+    rejoinMulticast(): void;
+    /**
+     * Close all sockets and clean up.
+     * @returns {Promise<void>}
+     */
+    destroy(): Promise<void>;
+    #private;
+}
+export type PacketHandler = (packet: dns.DnsPacket) => void;
+import * as dns from './dns.js';