Port Search Defaults

Configure dependency-wide search defaults for ports and socket paths, then allocate free resources using those defaults without per-call overrides.

Capabilities

Configure global port bounds

• After configuring search bounds to base 4100 and ceiling 4102, first call to reservePorts(1) returns [4100] and a second call returns [4101], both without passing per-call overrides. @test

Reject invalid ranges

• Configuring with a ceiling lower than the base fails with a descriptive error and leaves prior defaults unchanged. @test

Exhaustive multi-port reservation

• With bounds set to 5010-5012, reservePorts(3) yields the three unique ports in ascending order; requesting a fourth port afterwards rejects due to exhaustion of the configured window. @test

Configure socket base path

• After setting the socket base path to /tmp/app.sock and pre-creating that path to simulate a collision, reserveSocket() resolves to the next free path using the same prefix. @test

Implementation

@generates

API

export async function configureSearch(options);
/**
 * @param {{ basePort?: number, highestPort?: number, basePath?: string }} options
 * Applies global search defaults for ports and sockets. Rejects on invalid bounds.
 */

export async function reservePorts(count);
/**
 * @param {number} count - Number of ports to obtain using the configured defaults.
 * @returns {Promise<number[]>} - Unique available ports in ascending order.
 */

export async function reserveSocket();
/**
 * @returns {Promise<string>} - Available socket path derived from the configured base path.
 */

Dependencies { .dependencies }

portfinder { .dependency }

Locates free TCP ports and socket paths using configurable global defaults.