doc: add esm examples to node:dns

mfdebian · targos · commit 62bf03b5f1a1 · 2024-10-02T07:57:29.000+02:00
PR-URL: #54172 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
diff --git a/doc/api/dns.md b/doc/api/dns.md
@@ -15,13 +15,22 @@ facilities to perform name resolution. It may not need to perform any network
 communication. To perform name resolution the way other applications on the same
 system do, use [`dns.lookup()`][].
 
-```js
+```mjs
+import dns from 'node:dns';
+
+dns.lookup('example.org', (err, address, family) => {
+  console.log('address: %j family: IPv%s', address, family);
+});
+// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6
+```
+
+```cjs
 const dns = require('node:dns');
 
 dns.lookup('example.org', (err, address, family) => {
   console.log('address: %j family: IPv%s', address, family);
 });
-// address: "93.184.216.34" family: IPv4
+// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6
 ```
 
 All other functions in the `node:dns` module connect to an actual DNS server to
@@ -30,7 +39,26 @@ queries. These functions do not use the same set of configuration files used by
 [`dns.lookup()`][] (e.g. `/etc/hosts`). Use these functions to always perform
 DNS queries, bypassing other name-resolution facilities.
 
-```js
+```mjs
+import dns from 'node:dns';
+
+dns.resolve4('archive.org', (err, addresses) => {
+  if (err) throw err;
+
+  console.log(`addresses: ${JSON.stringify(addresses)}`);
+
+  addresses.forEach((a) => {
+    dns.reverse(a, (err, hostnames) => {
+      if (err) {
+        throw err;
+      }
+      console.log(`reverse for ${a}: ${JSON.stringify(hostnames)}`);
+    });
+  });
+});
+```
+
+```cjs
 const dns = require('node:dns');
 
 dns.resolve4('archive.org', (err, addresses) => {
@@ -64,7 +92,18 @@ the servers used for a resolver using
 [`resolver.setServers()`][`dns.setServers()`] does not affect
 other resolvers:
 
-```js
+```mjs
+import { Resolver } from 'node:dns';
+const resolver = new Resolver();
+resolver.setServers(['4.4.4.4']);
+
+// This request will use the server at 4.4.4.4, independent of global settings.
+resolver.resolve4('example.org', (err, addresses) => {
+  // ...
+});
+```
+
+```cjs
 const { Resolver } = require('node:dns');
 const resolver = new Resolver();
 resolver.setServers(['4.4.4.4']);
@@ -260,21 +299,38 @@ time to consult the [Implementation considerations section][] before using
 
 Example usage:
 
-```js
+```mjs
+import dns from 'node:dns';
+const options = {
+  family: 6,
+  hints: dns.ADDRCONFIG | dns.V4MAPPED,
+};
+dns.lookup('example.org', options, (err, address, family) =>
+  console.log('address: %j family: IPv%s', address, family));
+// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6
+
+// When options.all is true, the result will be an Array.
+options.all = true;
+dns.lookup('example.org', options, (err, addresses) =>
+  console.log('addresses: %j', addresses));
+// addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]
+```
+
+```cjs
 const dns = require('node:dns');
 const options = {
   family: 6,
   hints: dns.ADDRCONFIG | dns.V4MAPPED,
 };
-dns.lookup('example.com', options, (err, address, family) =>
+dns.lookup('example.org', options, (err, address, family) =>
   console.log('address: %j family: IPv%s', address, family));
-// address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6
+// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6
 
 // When options.all is true, the result will be an Array.
 options.all = true;
-dns.lookup('example.com', options, (err, addresses) =>
+dns.lookup('example.org', options, (err, addresses) =>
   console.log('addresses: %j', addresses));
-// addresses: [{"address":"2606:2800:220:1:248:1893:25c8:1946","family":6}]
+// addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]
 ```
 
 If this method is invoked as its [`util.promisify()`][]ed version, and `all`
@@ -331,7 +387,15 @@ will be thrown.
 
 On an error, `err` is an [`Error`][] object, where `err.code` is the error code.
 
-```js
+```mjs
+import dns from 'node:dns';
+dns.lookupService('127.0.0.1', 22, (err, hostname, service) => {
+  console.log(hostname, service);
+  // Prints: localhost ssh
+});
+```
+
+```cjs
 const dns = require('node:dns');
 dns.lookupService('127.0.0.1', 22, (err, hostname, service) => {
   console.log(hostname, service);
@@ -898,7 +962,16 @@ the servers used for a resolver using
 [`resolver.setServers()`][`dnsPromises.setServers()`] does not affect
 other resolvers:
 
-```js
+```mjs
+import { Resolver } from 'node:dns/promises';
+const resolver = new Resolver();
+resolver.setServers(['4.4.4.4']);
+
+// This request will use the server at 4.4.4.4, independent of global settings.
+const addresses = await resolver.resolve4('example.org');
+```
+
+```cjs
 const { Resolver } = require('node:dns').promises;
 const resolver = new Resolver();
 resolver.setServers(['4.4.4.4']);
@@ -1028,24 +1101,45 @@ using `dnsPromises.lookup()`.
 
 Example usage:
 
-```js
+```mjs
+import dns from 'node:dns';
+const dnsPromises = dns.promises;
+const options = {
+  family: 6,
+  hints: dns.ADDRCONFIG | dns.V4MAPPED,
+};
+
+await dnsPromises.lookup('example.org', options).then((result) => {
+  console.log('address: %j family: IPv%s', result.address, result.family);
+  // address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6
+});
+
+// When options.all is true, the result will be an Array.
+options.all = true;
+await dnsPromises.lookup('example.org', options).then((result) => {
+  console.log('addresses: %j', result);
+  // addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]
+});
+```
+
+```cjs
 const dns = require('node:dns');
 const dnsPromises = dns.promises;
 const options = {
   family: 6,
   hints: dns.ADDRCONFIG | dns.V4MAPPED,
 };
 
-dnsPromises.lookup('example.com', options).then((result) => {
+dnsPromises.lookup('example.org', options).then((result) => {
   console.log('address: %j family: IPv%s', result.address, result.family);
-  // address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6
+  // address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6
 });
 
 // When options.all is true, the result will be an Array.
 options.all = true;
-dnsPromises.lookup('example.com', options).then((result) => {
+dnsPromises.lookup('example.org', options).then((result) => {
   console.log('addresses: %j', result);
-  // addresses: [{"address":"2606:2800:220:1:248:1893:25c8:1946","family":6}]
+  // addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]
 });
 ```
 
@@ -1068,7 +1162,14 @@ will be thrown.
 On error, the `Promise` is rejected with an [`Error`][] object, where `err.code`
 is the error code.
 
-```js
+```mjs
+import dnsPromises from 'node:dns/promises';
+const result = await dnsPromises.lookupService('127.0.0.1', 22);
+
+console.log(result.hostname, result.service); // Prints: localhost ssh
+```
+
+```cjs
 const dnsPromises = require('node:dns').promises;
 dnsPromises.lookupService('127.0.0.1', 22).then((result) => {
   console.log(result.hostname, result.service);
