Bounded Port Allocator

Create a utility that locates an open TCP port within caller-provided bounds and reports clear validation or exhaustion errors when the search space is invalid or fully consumed.

Capabilities

Allocate port within bounds

• Given startPort: 3500 and stopPort: 3510, resolves to a free port within that inclusive range and never exceeds the upper bound. @test

Reject reversed bounds

• When startPort is greater than stopPort, rejects with a RangeError that echoes the provided bounds. @test

Guard against negative starts

• When startPort is negative, rejects with a RangeError describing the invalid lower bound. @test

Surface exhaustion details

• When every port from 3600 through 3602 is occupied, rejects with an error carrying code PORT_RANGE_EXHAUSTED and a message that names the attempted range. @test

Implementation

@generates

API

export interface PortRangeOptions {
  startPort: number;
  stopPort: number;
  host?: string;
}

export interface PortRangeError extends Error {
  code: 'INVALID_RANGE' | 'PORT_RANGE_EXHAUSTED';
  startPort: number;
  stopPort: number;
}

/**
 * Finds an available TCP port within the inclusive bounds.
 * Resolves with the discovered port number or rejects with a PortRangeError.
 */
export async function allocatePort(options: PortRangeOptions): Promise<number>;

Dependencies { .dependencies }

portfinder { .dependency }

Provides host-aware probing utilities for finding unused network ports within bounded ranges.