DNS APIs: Bun.dns.lookup, Bun.dns.prefetch, Bun.dns.getCacheStats
Bun provides DNS utilities: Bun.dns.lookup() for DNS lookups, Bun.dns.prefetch() for DNS prefetching, and Bun.dns.getCacheStats() for cache statistics.
bun apis/dns
15 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
DNS caching behavior
By default, Bun caches and deduplicates DNS queries in-memory for up to 30 seconds. Call `dns.getCacheStats()` to return cache statistics.
DNS prefetching with dns.prefetch
Import `dns` from `bun` and call `dns.prefetch(hostname)` to resolve DNS for a host before making requests to it, avoiding the initial DNS lookup delay.
Bun implements both dns and node:dns modules
Bun has its own dns module and also implements the node:dns module for compatibility. Both can be used for DNS resolution.
dns.resolve4 with ttl option example
The node:dns.promises.resolve4 function resolves IPv4 addresses and accepts a ttl option. When ttl is true, it returns an array of objects with address and ttl properties. Example: await dns.promises.resolve4('bun.com', { ttl: true }) returns [{ address: '172.67.161.226', ttl: 0 }, ...]
dns.prefetch signature
dns.prefetch(hostname: string, port?: number): void resolves a hostname before you need it. The port parameter is optional.
dns.lookup backend option values
Bun.dns.lookup() accepts a backend option that can be 'c-ares' (asynchronous resolver reading /etc/resolv.conf directly, default on Linux), 'system' (platform's own resolver, default on macOS/Windows/Android), or 'getaddrinfo'/'libc' (POSIX getaddrinfo on thread pool).
node:dns.lookup always uses system backend
node:dns.lookup() always uses the 'system' backend to match Node.js behavior, where it calls getaddrinfo(3). The node:dns.resolve*() functions use c-ares, as they do in Node.js.
DNS cache holds up to 256 entries for max 30 seconds
Bun's DNS cache stores up to 256 entries with a maximum TTL of 30 seconds each. If a connection to a host fails, that host's entry is removed from the cache. Simultaneous connections to the same host share one DNS lookup.
DNS cache automatically used by various Bun APIs
The DNS cache is automatically used by: bun install, fetch(), node:http client, Bun.connect, node:net, and node:tls.
dns.getCacheStats return object structure
dns.getCacheStats() returns an object with properties: cacheHitsCompleted (number of cache hits completed), cacheHitsInflight (cache hits in flight), cacheMisses (number of cache misses), size (number of items in cache), errors (times a connection failed), and totalCount (total times a connection was requested).
dns.getCacheStats example
Example of dns.getCacheStats(): import { dns } from 'bun'; const stats = dns.getCacheStats(); console.log(stats); // => { cacheHitsCompleted: 0, cacheHitsInflight: 0, cacheMisses: 0, size: 0, errors: 0, totalCount: 0 }
Configure DNS cache TTL with environment variable
Set the BUN_CONFIG_DNS_TIME_TO_LIVE_SECONDS environment variable to change DNS cache TTL. Default is 30 seconds. Example: BUN_CONFIG_DNS_TIME_TO_LIVE_SECONDS=5 bun run my-script.ts sets TTL to 5 seconds.
dns.prefetch example usage
Example of prefetching DNS: import { dns } from 'bun'; dns.prefetch('bun.com', 443); // ... sometime later ... await fetch('https://bun.com');
When to use dns.prefetch
Use dns.prefetch when you know you'll connect to a host soon and want to avoid the initial DNS lookup delay. A good example is prefetching a database host's DNS entry when the application starts, so the lookup may complete by the time the rest of the application loads.