Host-Aware Port Selection

A utility that finds an available TCP port by scanning hosts in priority order, combining caller-provided hosts with the dependency's default host detection while skipping invalid entries.

Capabilities

Finds open port across custom and default hosts

• Without custom hosts, returns the first available port within the default scan range using the dependency's discovered host list. @test

Prunes invalid hosts but honors valid entries

• Given a hosts array containing both valid and invalid addresses, ignores invalid entries and returns a port bound to the first valid host. @test

Errors when only invalid hosts are provided

• When all supplied hosts are invalid or unbindable, fails with a clear error identifying the rejected hosts. @test

Optional bounded search

• Respects provided start/stop port bounds and surfaces a dependency error when the range is exhausted without finding a port. @test

Implementation

@generates

API

export interface PortRequestOptions {
  startPort?: number;
  stopPort?: number;
  hosts?: Array<string | null>;
}

export interface PortAssignment {
  port: number;
  host: string | null;
}

/**
 * Locate the first available TCP port within the provided bounds, scanning hosts in order.
 * Custom hosts (if provided) are merged with the dependency's default host detection.
 * Invalid or unbindable hosts are skipped unless all hosts are invalid, in which case an error is thrown.
 */
export function findAvailablePort(options?: PortRequestOptions): Promise<PortAssignment>;

Dependencies { .dependencies }

portfinder { .dependency }

Discovers available TCP ports by scanning host lists and port ranges, including default host detection and invalid-host pruning. @satisfied-by