Add `Bun.dns` to the README

1 files changed, 42 insertions, 0 deletions

diff --git a/README.md b/README.md
index 1d8345086..fd9755adf 100644
--- a/README.md
+++ b/README.md
@@ -175,6 +175,7 @@ bun upgrade --canary
   - [`Bun.Transpiler.scan`](#buntranspilerscan)
   - [`Bun.Transpiler.scanImports`](#buntranspilerscanimports)
 - [`Bun.peek` - read a promise same-tick](#bunpeek---read-a-promise-without-resolving-it)
+- [`Bun.dns` - lookup a domain](#bundns---lookup-a-domain)
 - [Module resolution in Bun](#module-resolution-in-bun)
 - [Environment variables](#environment-variables)
 - [Credits](#credits)
@@ -2823,6 +2824,47 @@ queueMicrotask(() => {
 
 Builtin buffering is planned in a future version of Bun.
 
+## `Bun.dns` - lookup a domain
+
+`Bun.dns` includes utilities to make DNS requests, similar to `node:dns`. As of Bun v0.5.0, the only implemented function is `dns.lookup`, though more will be implemented soon.
+
+You can lookup the IP addresses of a hostname by using `dns.lookup`.
+
+```ts
+import { dns } from "bun";
+
+const [{ address }] = await dns.lookup("example.com");
+console.log(address); // "93.184.216.34"
+```
+
+If you need to limit IP addresses to either IPv4 or IPv6, you can specify the `family` as an option.
+
+```ts
+import { dns } from "bun";
+
+const [{ address }] = await dns.lookup("example.com", { family: 6 });
+console.log(address); // "2606:2800:220:1:248:1893:25c8:1946"
+```
+
+Bun supports three backends for DNS resolution:
+  - `c-ares` - This is the default on Linux, and it uses the [c-ares](https://c-ares.org/) library to perform DNS resolution.
+  - `system` - Uses the system's non-blocking DNS resolver, if available. Otherwise, falls back to `getaddrinfo`. This is the default on macOS, and the same as `getaddrinfo` on Linux.
+  - `getaddrinfo` - Uses the POSIX standard `getaddrinfo` function, which may cause performance issues under concurrent load.
+  
+You can choose a particular backend by specifying `backend` as an option.
+
+```ts
+import { dns } from "bun";
+
+const [{ address, ttl }] = await dns.lookup("example.com", { backend: "c-ares" });
+console.log(address); // "93.184.216.34"
+console.log(ttl); // 21237
+```
+
+Note: the `ttl` property is only accurate when the `backend` is c-ares. Otherwise, `ttl` will be `0`. 
+
+This was added in Bun v0.5.0.
+
 ## `Bun.peek` - read a promise without resolving it
 
 `Bun.peek` is a utility function that lets you read a promise's result without `await` or `.then`, but only if the promise has already fulfilled or rejected.