Ephemeral Port Allocator

Create a small helper module that finds a single free TCP port. Provide both Promise-based and callback-based entry points so it can be used in asynchronous workflows that prefer either style. The lookup should start from a configurable base port and stop when the first available port is found within the allowed range.

Capabilities

Promise-based port lookup

• Resolves with an available TCP port at or above startPort (default 8000) and within stopPort when provided. @test
• Rejects when no free port exists within the inclusive range from startPort to stopPort. @test

Callback-based port lookup

• Invokes the callback with a free TCP port and no error when search parameters are valid. @test
• Invokes the callback with an error when stopPort is lower than startPort. @test

Host-specific lookup

• Returns a port that can be bound on a specified host when one is provided. @test

Implementation

@generates

API

export interface PortSearchOptions {
  startPort?: number; // default 8000
  stopPort?: number;  // inclusive upper bound; optional
  host?: string;      // optional target host to target during lookup
}

export function findAvailablePort(options?: PortSearchOptions): Promise<number>;

export function findAvailablePortCallback(
  options: PortSearchOptions,
  callback: (err: Error | null, port?: number) => void
): void;

Dependencies { .dependencies }

portfinder { .dependency }

Locates available TCP ports.