From cc9fbf4c653ebfd2b22964e8a55ba10d440f17db Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alfredo=20Gonz=C3=A1lez?= Date: Thu, 1 Aug 2024 19:00:22 -0400 Subject: [PATCH 1/2] doc: add esm examples to node:dns --- doc/api/dns.md | 143 +++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 126 insertions(+), 17 deletions(-) diff --git a/doc/api/dns.md b/doc/api/dns.md index 128780ce26daa0..8cfaaa6fac8ac2 100644 --- 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']); @@ -262,21 +301,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` @@ -333,7 +389,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); @@ -904,7 +968,23 @@ 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. +resolver.resolve4('example.org').then((addresses) => { + // ... +}); + +// Alternatively, the same code can be written using async-await style. +(async function() { + const addresses = await resolver.resolve4('example.org'); +})(); +``` + +```cjs const { Resolver } = require('node:dns').promises; const resolver = new Resolver(); resolver.setServers(['4.4.4.4']); @@ -1036,7 +1116,28 @@ 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, +}; + +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; +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 = { @@ -1044,16 +1145,16 @@ const options = { 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}] }); ``` @@ -1076,7 +1177,15 @@ 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'; +dnsPromises.lookupService('127.0.0.1', 22).then((result) => { + 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); From 99dab200b6da4f9887470c90e65a4c31c65c4180 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alfredo=20Gonz=C3=A1lez?= <12631491+mfdebian@users.noreply.github.com> Date: Sat, 3 Aug 2024 14:05:27 -0400 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Antoine du Hamel --- doc/api/dns.md | 20 ++++++-------------- 1 file changed, 6 insertions(+), 14 deletions(-) diff --git a/doc/api/dns.md b/doc/api/dns.md index 8cfaaa6fac8ac2..af71918496a883 100644 --- a/doc/api/dns.md +++ b/doc/api/dns.md @@ -974,14 +974,7 @@ 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').then((addresses) => { - // ... -}); - -// Alternatively, the same code can be written using async-await style. -(async function() { - const addresses = await resolver.resolve4('example.org'); -})(); +const addresses = await resolver.resolve4('example.org'); ``` ```cjs @@ -1124,14 +1117,14 @@ const options = { hints: dns.ADDRCONFIG | dns.V4MAPPED, }; -dnsPromises.lookup('example.org', options).then((result) => { +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; -dnsPromises.lookup('example.org', options).then((result) => { +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}] }); @@ -1179,10 +1172,9 @@ is the error code. ```mjs import dnsPromises from 'node:dns/promises'; -dnsPromises.lookupService('127.0.0.1', 22).then((result) => { - console.log(result.hostname, result.service); - // Prints: localhost ssh -}); +const result = await dnsPromises.lookupService('127.0.0.1', 22); + +console.log(result.hostname, result.service); // Prints: localhost ssh ``` ```cjs