Can I bind to a specific host? How is the host option passed through?

Yes, you can bind to a specific host using the host option in the getPort() function.

How the host option works

The host option is passed directly to the underlying Node.js server listening mechanism. According to the API documentation [index.d.ts:L37-L42], the host parameter:

The host on which port resolution should be performed. Can be either an IPv4 or IPv6 address. By default, it checks availability on all local addresses defined in OS network interfaces. If this option is set, it will only check the given host.

How it's passed through

The host option is part of the Options type [index.d.ts:L3-L65] and is passed through to Node.js's ListenOptions via the spread operator (...Omit<ListenOptions, 'port'>). This means the option flows directly to the underlying server.listen() call.

In the implementation, when a host is specified, the code takes a shortcut path in getAvailablePort() [index.js:L61-L78]:

if (options.host || options.port === 0) {
    return checkAvailablePort(options);
}

When options.host is set, it skips iterating through all local addresses and instead calls checkAvailablePort(options) directly [index.js:L47-L60], which creates a server and listens on that specific host.

Example from tests

The test suite demonstrates this with IPv4 hosts [test.js:L51-L59]:

const port = await getPort({
    port: desiredPort,
    host: '0.0.0.0',
});

FOLLOW_UPS:

• What happens when host is not specified?
• How does ipv6Only option affect host checking?
• What are the valid host address formats?