dns: accept `'IPv4'` and `'IPv6'` for `family`

Refs: https://github.com/nodejs/node/issues/43014

PR-URL: https://github.com/nodejs/node/pull/43054
Fixes: https://github.com/nodejs/node/issues/43014
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Darshan Sen <raisinten@gmail.com>
Reviewed-By: Beth Griggs <bgriggs@redhat.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

5 files changed, 36 insertions, 15 deletions

diff --git a/doc/api/dgram.md b/doc/api/dgram.md
index f4045428d4d..da3c69ba168 100644
--- a/doc/api/dgram.md
+++ b/doc/api/dgram.md
@@ -114,6 +114,9 @@ exist and calls such as `socket.address()` and `socket.setTTL()` will fail.
 <!-- YAML
 added: v0.1.99
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/43054
+    description: The `family` property now returns a string instead of a number.
   - version: v18.0.0
     pr-url: https://github.com/nodejs/node/pull/41431
     description: The `family` property now returns a number instead of a string.
@@ -125,7 +128,7 @@ The event handler function is passed two arguments: `msg` and `rinfo`.
 * `msg` {Buffer} The message.
 * `rinfo` {Object} Remote address information.
   * `address` {string} The sender address.
-  * `family` {number} The address family (`4` for IPv4 or `6` for IPv6).
+  * `family` {string} The address family (`'IPv4'` or `'IPv6'`).
   * `port` {number} The sender port.
   * `size` {number} The message size.
 
diff --git a/doc/api/dns.md b/doc/api/dns.md
index c9e901da677..0d281fdffe0 100644
--- a/doc/api/dns.md
+++ b/doc/api/dns.md
@@ -179,6 +179,11 @@ section if a custom port is used.
 <!-- YAML
 added: v0.1.90
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/43054
+    description: For compatibility with `node:net`, when passing an option
+                 object the `family` option can be the string `'IPv4'` or the
+                 string `'IPv6'`.
   - version: v18.0.0
     pr-url: https://github.com/nodejs/node/pull/41678
     description: Passing an invalid callback to the `callback` argument
@@ -197,9 +202,10 @@ changes:
 
 * `hostname` {string}
 * `options` {integer | Object}
-  * `family` {integer} The record family. Must be `4`, `6`, or `0`. The value
-    `0` indicates that IPv4 and IPv6 addresses are both returned. **Default:**
-    `0`.
+  * `family` {integer|string} The record family. Must be `4`, `6`, or `0`. For
+    backward compatibility reasons,`'IPv4'` and `'IPv6'` are interpreted as `4`
+    and `6` respectively. The value `0` indicates that IPv4 and IPv6 addresses
+    are both returned. **Default:** `0`.
   * `hints` {number} One or more [supported `getaddrinfo` flags][]. Multiple
     flags may be passed by bitwise `OR`ing their values.
   * `all` {boolean} When `true`, the callback returns all resolved addresses in
@@ -219,8 +225,8 @@ changes:
 
 Resolves a host name (e.g. `'nodejs.org'`) into the first found A (IPv4) or
 AAAA (IPv6) record. All `option` properties are optional. If `options` is an
-integer, then it must be `4` or `6` – if `options` is not provided, then IPv4
-and IPv6 addresses are both returned if found.
+integer, then it must be `4` or `6` – if `options` is `0` or not provided, then
+IPv4 and IPv6 addresses are both returned if found.
 
 With the `all` option set to `true`, the arguments for `callback` change to
 `(err, addresses)`, with `addresses` being an array of objects with the
diff --git a/doc/api/net.md b/doc/api/net.md
index 82bff635c9b..a22b6c036ab 100644
--- a/doc/api/net.md
+++ b/doc/api/net.md
@@ -286,6 +286,9 @@ Emitted when the server has been bound after calling [`server.listen()`][].
 <!-- YAML
 added: v0.1.90
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/43054
+    description: The `family` property now returns a string instead of a number.
   - version: v18.0.0
     pr-url: https://github.com/nodejs/node/pull/41431
     description: The `family` property now returns a number instead of a string.
@@ -296,7 +299,7 @@ changes:
 Returns the bound `address`, the address `family` name, and `port` of the server
 as reported by the operating system if listening on an IP socket
 (useful to find which port was assigned when getting an OS-assigned address):
-`{ port: 12346, family: 4, address: '127.0.0.1' }`.
+`{ port: 12346, family: 'IPv4', address: '127.0.0.1' }`.
 
 For a server listening on a pipe or Unix domain socket, the name is returned
 as a string.
@@ -743,6 +746,9 @@ See also: [`socket.setTimeout()`][].
 <!-- YAML
 added: v0.1.90
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/43054
+    description: The `family` property now returns a string instead of a number.
   - version: v18.0.0
     pr-url: https://github.com/nodejs/node/pull/41431
     description: The `family` property now returns a number instead of a string.
@@ -752,7 +758,7 @@ changes:
 
 Returns the bound `address`, the address `family` name and `port` of the
 socket as reported by the operating system:
-`{ port: 12346, family: 4, address: '127.0.0.1' }`
+`{ port: 12346, family: 'IPv4', address: '127.0.0.1' }`
 
 ### `socket.bufferSize`
 
diff --git a/doc/api/os.md b/doc/api/os.md
index ad4d082d94d..370504d632e 100644
--- a/doc/api/os.md
+++ b/doc/api/os.md
@@ -225,6 +225,9 @@ always `[0, 0, 0]`.
 <!-- YAML
 added: v0.6.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/43054
+    description: The `family` property now returns a string instead of a number.
   - version: v18.0.0
     pr-url: https://github.com/nodejs/node/pull/41431
     description: The `family` property now returns a number instead of a string.
@@ -242,12 +245,12 @@ The properties available on the assigned network address object include:
 
 * `address` {string} The assigned IPv4 or IPv6 address
 * `netmask` {string} The IPv4 or IPv6 network mask
-* `family` {number} Either `4` (for IPv4) or `6` (for IPv6)
+* `family` {string} Either `IPv4` or `IPv6`
 * `mac` {string} The MAC address of the network interface
 * `internal` {boolean} `true` if the network interface is a loopback or
   similar interface that is not remotely accessible; otherwise `false`
 * `scopeid` {number} The numeric IPv6 scope ID (only specified when `family`
-  is `6`)
+  is `IPv6`)
 * `cidr` {string} The assigned IPv4 or IPv6 address with the routing prefix
   in CIDR notation. If the `netmask` is invalid, this property is set
   to `null`.
@@ -260,7 +263,7 @@ The properties available on the assigned network address object include:
     {
       address: '127.0.0.1',
       netmask: '255.0.0.0',
-      family: 4,
+      family: 'IPv4',
       mac: '00:00:00:00:00:00',
       internal: true,
       cidr: '127.0.0.1/8'
@@ -268,7 +271,7 @@ The properties available on the assigned network address object include:
     {
       address: '::1',
       netmask: 'ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff',
-      family: 6,
+      family: 'IPv6',
       mac: '00:00:00:00:00:00',
       scopeid: 0,
       internal: true,
@@ -279,7 +282,7 @@ The properties available on the assigned network address object include:
     {
       address: '192.168.1.108',
       netmask: '255.255.255.0',
-      family: 4,
+      family: 'IPv4',
       mac: '01:02:03:0a:0b:0c',
       internal: false,
       cidr: '192.168.1.108/24'
@@ -287,7 +290,7 @@ The properties available on the assigned network address object include:
     {
       address: 'fe80::a00:27ff:fe4e:66a1',
       netmask: 'ffff:ffff:ffff:ffff::',
-      family: 6,
+      family: 'IPv6',
       mac: '01:02:03:0a:0b:0c',
       scopeid: 1,
       internal: false,
diff --git a/doc/api/tls.md b/doc/api/tls.md
index 1621769d779..fd01f4cb9c5 100644
--- a/doc/api/tls.md
+++ b/doc/api/tls.md
@@ -956,6 +956,9 @@ tlsSocket.once('session', (session) => {
 <!-- YAML
 added: v0.11.4
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/43054
+    description: The `family` property now returns a string instead of a number.
   - version: v18.0.0
     pr-url: https://github.com/nodejs/node/pull/41431
     description: The `family` property now returns a number instead of a string.
@@ -965,7 +968,7 @@ changes:
 
 Returns the bound `address`, the address `family` name, and `port` of the
 underlying socket as reported by the operating system:
-`{ port: 12346, family: 4, address: '127.0.0.1' }`.
+`{ port: 12346, family: 'IPv4', address: '127.0.0.1' }`.
 
 ### `tlsSocket.authorizationError`