constructor

net.BoundSocket.constructor

Not implemented in Bun

constructor BoundSocket(
options?: BoundSocketOptions

Referenced types

interface BoundSocketOptions

  • host?: string

    Local address to bind. Must be a numeric IP literal; no DNS resolution is performed. Default: '0.0.0.0', or '::' when ipv6Only is true.

  • ipv6Only?: boolean

    Sets IPV6_V6ONLY, disabling dual-stack support so the socket binds IPv6 only. Only meaningful for IPv6 binds. Default: false.

  • port?: number

    Local port. 0 requests an OS-assigned ephemeral port. Default: 0.

  • reusePort?: boolean

    Sets SO_REUSEPORT, allowing multiple sockets to bind the same address and port for kernel-level load balancing. Support is platform-dependent. Default: false.

class BoundSocket

Allows for the synchronous creation of a pre-bound socket, that can be passed to listen() or new net.Socket() later on. For listen() this enables synchronous port reservation, while for new net.Socket(), it allows control over the local egress port/IP, via bind(2) semantics.

Adoption transfers ownership of the socket; afterwards address() and close() throw ERR_SOCKET_HANDLE_ADOPTED. A handle that is never adopted must be closed to avoid leaking the socket.

import net from 'node:net';

const bound = new net.BoundSocket();
const { port } = bound.address();
console.log(`Reserved port ${port} for server`);

const server = net.createServer();
server.listen(bound); // Adopt as a server, or pass to new net.Socket() instead.

  • Closes the handle if it has not been adopted or closed; otherwise a no-op.

  • Returns the bound local address. When bound with port: 0, port is the OS-assigned ephemeral port.

    @returns

    An object with address, family, and port properties, as server.address() returns.

  • close(): void;

    Releases the bound socket. Only needed when the handle is never adopted.

  • fd(): number;

    Returns the file descriptor of the bound socket. Ownership remains with the BoundSocket, so the descriptor must not be closed by the caller. The descriptor is only available before the handle is adopted; afterwards it belongs to the adopting net.Server or net.Socket and fd() throws ERR_SOCKET_HANDLE_ADOPTED.

    @returns

    The underlying OS file descriptor, or -1 on platforms that do not expose one for sockets (such as Windows).