fix(node/net): return string family in server.address()

Aligns Deno's `server.address()` with Node.js v18.4.0+ behavior by
returning the `family` property as a string ("IPv4" or "IPv6") rather
than a number.

Node.js briefly changed `family` from string to number in v18.0.0
(nodejs/node#41431), but reverted in v18.4.0 (nodejs/node#43054) due
to ecosystem breakage (nodejs/node#43014).

This fix ensures compatibility with npm packages that rely on the
string format, which has been the stable API since Node.js v18.4.0.

Refs:
- nodejs/node#43054
- nodejs/node@70b516e

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: nrako

ext/node/polyfills/dns.ts

@@ -234,8 +234,19 @@ export function lookup(
     }
 
     if (options?.family != null) {
-      validateOneOf(options.family, "options.family", validFamilies);
-      family = options.family;
+      // Accept both numeric (0, 4, 6) and string ('IPv4', 'IPv6') family values
+      // to match Node.js behavior
+      switch (options.family) {
+        case "IPv4":
+          family = 4;
+          break;
+        case "IPv6":
+          family = 6;
+          break;
+        default:
+          validateOneOf(options.family, "options.family", validFamilies);
+          family = options.family;
+      }
     }
 
     if (options?.all != null) {

ext/node/polyfills/http.ts

@@ -68,6 +68,7 @@ import {
   ERR_UNESCAPED_CHARACTERS,
 } from "ext:deno_node/internal/errors.ts";
 import { getTimerDuration } from "ext:deno_node/internal/timers.mjs";
+import { isIP } from "ext:deno_node/internal/net.ts";
 import { serve, upgradeHttpRaw } from "ext:deno_http/00_serve.ts";
 import { headersEntries } from "ext:deno_fetch/20_headers.js";
 import { Response } from "ext:deno_fetch/23_response.js";
@@ -2232,9 +2233,12 @@ export class ServerImpl extends EventEmitter {
 
   address() {
     if (this.#addr === null) return null;
+    const addr = this.#addr.hostname;
+    const ipVersion = isIP(addr);
     return {
       port: this.#addr.port,
-      address: this.#addr.hostname,
+      address: addr,
+      family: ipVersion === 6 ? "IPv6" : "IPv4",
     };
   }
 }

ext/node/polyfills/internal/dns/promises.ts

@@ -194,8 +194,19 @@ export function lookup(
     }
 
     if (options?.family != null) {
-      validateOneOf(options.family, "options.family", validFamilies);
-      family = options.family;
+      // Accept both numeric (0, 4, 6) and string ('IPv4', 'IPv6') family values
+      // to match Node.js behavior
+      switch (options.family) {
+        case "IPv4":
+          family = 4;
+          break;
+        case "IPv6":
+          family = 6;
+          break;
+        default:
+          validateOneOf(options.family, "options.family", validFamilies);
+          family = options.family;
+      }
     }
 
     if (options?.all != null) {

ext/node/polyfills/internal_binding/tcp_wrap.ts

@@ -59,7 +59,7 @@ enum socketType {
 
 interface AddressInfo {
   address: string;
-  family?: number;
+  family?: string;
   port: number;
 }
 
@@ -95,7 +95,7 @@ export class TCP extends ConnectionWrap {
   #port?: number;
 
   #remoteAddress?: string;
-  #remoteFamily?: number;
+  #remoteFamily?: string;
   #remotePort?: number;
 
   #backlog?: number;
@@ -143,7 +143,8 @@ export class TCP extends ConnectionWrap {
       const remoteAddr = conn.remoteAddr as Deno.NetAddr;
       this.#remoteAddress = remoteAddr.hostname;
       this.#remotePort = remoteAddr.port;
-      this.#remoteFamily = isIP(remoteAddr.hostname);
+      const ipVersion = isIP(remoteAddr.hostname);
+      this.#remoteFamily = ipVersion === 6 ? "IPv6" : "IPv4";
     }
   }
 
@@ -279,7 +280,8 @@ export class TCP extends ConnectionWrap {
 
     sockname.address = this.#address;
     sockname.port = this.#port;
-    sockname.family = isIP(this.#address);
+    const ipVersion = isIP(this.#address);
+    sockname.family = ipVersion === 6 ? "IPv6" : "IPv4";
 
     return 0;
   }
@@ -375,7 +377,8 @@ export class TCP extends ConnectionWrap {
   #connect(req: TCPConnectWrap, address: string, port: number): number {
     this.#remoteAddress = address;
     this.#remotePort = port;
-    this.#remoteFamily = isIP(address);
+    const ipVersion = isIP(address);
+    this.#remoteFamily = ipVersion === 6 ? "IPv6" : "IPv4";
 
     op_net_connect_tcp(
       { hostname: address ?? "127.0.0.1", port },

ext/node/polyfills/net.ts

@@ -1531,9 +1531,7 @@ Object.defineProperty(Socket.prototype, "remoteAddress", {
 
 Object.defineProperty(Socket.prototype, "remoteFamily", {
   get: function () {
-    const { family } = this._getpeername();
-
-    return family ? `IPv${family}` : family;
+    return this._getpeername().family;
   },
 });
 

tests/unit_node/dns_test.ts

@@ -2,6 +2,7 @@
 import { assertEquals, fail } from "@std/assert";
 import dns, { lookupService } from "node:dns";
 import dnsPromises, {
+  lookup as lookupPromise,
   lookupService as lookupServicePromise,
 } from "node:dns/promises";
 import { ErrnoException } from "ext:deno_node/_global.d.ts";
@@ -88,3 +89,8 @@ Deno.test("lookupService not found", async () => {
     assertEquals((err as ErrnoException).syscall, "getnameinfo");
   });
 });
+
+Deno.test("[node/dns] lookup accepts string family values", async () => {
+  const result = await lookupPromise("localhost", { family: "IPv4" });
+  assertEquals(result.family, 4);
+});

tests/unit_node/http2_test.ts

@@ -462,3 +462,41 @@ Deno.test("internal/http2/util exports", () => {
   assert(typeof util.kProxySocket === "symbol");
   assert(typeof util.kRequest === "symbol");
 });
+
+Deno.test("[node/http2] Server.address() includes family property", async () => {
+  // Test IPv4
+  {
+    const { promise, resolve } = Promise.withResolvers<void>();
+    const server = http2.createServer((_req, res) => {
+      res.end("ok");
+    });
+
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address() as net.AddressInfo;
+      assertEquals(addr.address, "127.0.0.1");
+      assertEquals(addr.family, "IPv4");
+      assertEquals(typeof addr.port, "number");
+      server.close(() => resolve());
+    });
+
+    await promise;
+  }
+
+  // Test IPv6
+  {
+    const { promise, resolve } = Promise.withResolvers<void>();
+    const server = http2.createServer((_req, res) => {
+      res.end("ok");
+    });
+
+    server.listen(0, "::1", () => {
+      const addr = server.address() as net.AddressInfo;
+      assertEquals(addr.address, "::1");
+      assertEquals(addr.family, "IPv6");
+      assertEquals(typeof addr.port, "number");
+      server.close(() => resolve());
+    });
+
+    await promise;
+  }
+});

tests/unit_node/http_test.ts

@@ -2224,3 +2224,39 @@ Deno.test("[node/http] client request with empty write in chunked POST completes
   await promise;
   assertEquals(requestBody, "");
 });
+
+Deno.test("[node/http] Server.address() includes family property", async () => {
+  // Test IPv4
+  {
+    const { promise, resolve } = Promise.withResolvers<void>();
+    const server = http.createServer((_req, res) => res.end("ok"));
+
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      assert(addr !== null && typeof addr === "object");
+      assertEquals(addr.address, "127.0.0.1");
+      assertEquals(addr.family, "IPv4");
+      assertEquals(typeof addr.port, "number");
+      server.close(() => resolve());
+    });
+
+    await promise;
+  }
+
+  // Test IPv6
+  {
+    const { promise, resolve } = Promise.withResolvers<void>();
+    const server = http.createServer((_req, res) => res.end("ok"));
+
+    server.listen(0, "::1", () => {
+      const addr = server.address();
+      assert(addr !== null && typeof addr === "object");
+      assertEquals(addr.address, "::1");
+      assertEquals(addr.family, "IPv6");
+      assertEquals(typeof addr.port, "number");
+      server.close(() => resolve());
+    });
+
+    await promise;
+  }
+});

tests/unit_node/https_test.ts

@@ -1,7 +1,55 @@
 // Copyright 2018-2025 the Deno authors. MIT license.
 
 import https from "node:https";
-import { assert } from "../unit/test_util.ts";
+import { assert, assertEquals } from "../unit/test_util.ts";
+import type { AddressInfo } from "node:net";
+
+Deno.test("[node/https] Server.address() includes family property", async () => {
+  const certFile = "tests/testdata/tls/localhost.crt";
+  const keyFile = "tests/testdata/tls/localhost.key";
+
+  // Test IPv4
+  {
+    const { promise, resolve } = Promise.withResolvers<void>();
+    const server = https.createServer({
+      cert: Deno.readTextFileSync(certFile),
+      key: Deno.readTextFileSync(keyFile),
+    }, (_req, res) => {
+      res.end("ok");
+    });
+
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address() as AddressInfo;
+      assertEquals(addr.address, "127.0.0.1");
+      assertEquals(addr.family, "IPv4");
+      assertEquals(typeof addr.port, "number");
+      server.close(() => resolve());
+    });
+
+    await promise;
+  }
+
+  // Test IPv6
+  {
+    const { promise, resolve } = Promise.withResolvers<void>();
+    const server = https.createServer({
+      cert: Deno.readTextFileSync(certFile),
+      key: Deno.readTextFileSync(keyFile),
+    }, (_req, res) => {
+      res.end("ok");
+    });
+
+    server.listen(0, "::1", () => {
+      const addr = server.address() as AddressInfo;
+      assertEquals(addr.address, "::1");
+      assertEquals(addr.family, "IPv6");
+      assertEquals(typeof addr.port, "number");
+      server.close(() => resolve());
+    });
+
+    await promise;
+  }
+});
 
 Deno.test({
   name:

tests/unit_node/net_test.ts

@@ -303,3 +303,17 @@ Deno.test("[node/dns] resolve IPv6 addresses", async () => {
     await dnsPromises.lookup(address);
   }
 });
+
+Deno.test("[node/net] Socket.remoteFamily returns string", async () => {
+  const deferred = Promise.withResolvers<void>();
+  const server = net.createServer((socket) => {
+    assertEquals(socket.remoteFamily, "IPv4");
+    socket.end();
+    server.close(() => deferred.resolve());
+  });
+  server.listen(0, () => {
+    const { port } = server.address() as net.AddressInfo;
+    net.createConnection(port, "127.0.0.1");
+  });
+  await deferred.promise;
+});