doc: esm/fetchModule (and DNS.lookup)

nodejs · nodejs-github-bot · Sep 19, 2023 · Sep 6, 2023 · Sep 8, 2023 · Sep 10, 2023
commit 1f2ecf2e347002d30899605e90e80f772ad76c6d
diff --git a/lib/internal/dns/promises.js b/lib/internal/dns/promises.js
@@ -113,6 +113,19 @@ function onlookupall(err, addresses) {
   }
 }
 
+/**
+ * Creates a promise that resolves with the IP address of the given hostname.
+ * @param {0 | 4 | 6} family - The IP address family (4 or 6, or 0 for both).
+ * @param {string} hostname - The hostname to resolve.
+ * @param {boolean} all - Whether to resolve with all IP addresses for the hostname.
+ * @param {number} hints - One or more supported getaddrinfo flags (supply multiple via
+ * bitwise OR).
+ * @param {boolean} verbatim - Whether to use the hostname verbatim.
+ * @returns {Promise<DNSLookupResult | DNSLookupResult[]>} The IP address(es) of the hostname.
+ * @typedef {object} DNSLookupResult
+ * @property {string} address - The IP address.
+ * @property {0 | 4 | 6} family - The IP address type. 4 for IPv4 or 6 for IPv6, or 0 (for both).
+ */
 function createLookupPromise(family, hostname, all, hints, verbatim) {
   return new Promise((resolve, reject) => {
     if (!hostname) {
@@ -154,6 +167,17 @@ function createLookupPromise(family, hostname, all, hints, verbatim) {
 }
 
 const validFamilies = [0, 4, 6];
+/**
+ * Get the IP address for a given hostname.
+ * @param {string} hostname - The hostname to resolve (ex. 'nodejs.org').
+ * @param {object} [options] - Optional settings.
+ * @param {boolean} [options.all=false] - Whether to return all or just the first resolved address.
+ * @param {0 | 4 | 6} [options.family=0] - The record family. Must be 4, 6, or 0 (for both).
+ * @param {number} [options.hints] - One or more supported getaddrinfo flags (supply multiple via
+ * bitwise OR).
+ * @param {boolean} [options.verbatim=false] - Return results in same order DNS resolved them;
+ * otherwise IPv4 then IPv6. New code should supply `true`.
+ */
 function lookup(hostname, options) {
   let hints = 0;
   let family = 0;

diff --git a/lib/internal/modules/esm/fetch_module.js b/lib/internal/modules/esm/fetch_module.js
@@ -44,44 +44,67 @@ const cacheForGET = new SafeMap();
 // [2] Creating a new agent instead of using the gloabl agent improves
 // performance and precludes the agent becoming tainted.
 
+/** @type {import('https').Agent} The Cached HTTP Agent for **secure** HTTP requests. */
 let HTTPSAgent;
-function HTTPSGet(url, opts) {
+/**
+ * Make a **secure** HTTP GET request (handling agent setup if needed, caching the agent to avoid
+ * redudant instantiations).
+ * @param {Parameters<import('https').get>[0]} input - The URI to fetch.
+ * @param {Parameters<import('https').get>[1]} options - See https.get() options.
+ */
+function HTTPSGet(input, options) {
   const https = require('https'); // [1]
   HTTPSAgent ??= new https.Agent({ // [2]
     keepAlive: true,
   });
-  return https.get(url, {
+  return https.get(input, {
     agent: HTTPSAgent,
-    ...opts,
+    ...options,
   });
 }
 
+/** @type {import('https').Agent} The Cached HTTP Agent for **insecure** HTTP requests. */
 let HTTPAgent;
-function HTTPGet(url, opts) {
+/**
+ * Make a **insecure** HTTP GET request (handling agent setup if needed, caching the agent to avoid
+ * redudant instantiations).
+ * @param {Parameters<import('https').get>[0]} input - The URI to fetch.
+ * @param {Parameters<import('https').get>[1]} options - See http.get() options.
+ */
+function HTTPGet(input, options) {
   const http = require('http'); // [1]
   HTTPAgent ??= new http.Agent({ // [2]
     keepAlive: true,
   });
-  return http.get(url, {
+  return http.get(input, {
     agent: HTTPAgent,
-    ...opts,
+    ...options,
   });
 }
 
-function dnsLookup(name, opts) {
+/** @type {import('../../dns/promises.js').lookup} */
+function dnsLookup(hostname, options) {
   // eslint-disable-next-line no-func-assign
   dnsLookup = require('dns/promises').lookup;
-  return dnsLookup(name, opts);
+  return dnsLookup(hostname, options);
 }
 
 let zlib;
+/**
+ * Create a decompressor for the Brotli format.
+ * @returns {import('../../../zlib.js').BrotliDecompress}
+ */
 function createBrotliDecompress() {
   zlib ??= require('zlib'); // [1]
   // eslint-disable-next-line no-func-assign
   createBrotliDecompress = zlib.createBrotliDecompress;
   return createBrotliDecompress();
 }
 
+/**
+ * Create an unzip handler.
+ * @returns {import('../../../zlib.js').Unzip}
+ */
 function createUnzip() {
   zlib ??= require('zlib'); // [1]
   // eslint-disable-next-line no-func-assign