Deterministic Port and Socket Planner

Build a tiny utility that orchestrates deterministic selection of free TCP ports and Unix socket paths. It should mirror the dependency's candidate-ordering behavior while allowing callers to tune defaults.

Capabilities

Sequential port allocation

• With a starting port of 4200 and an upper bound of 4203, requesting 2 ports returns two free ports in ascending order within that range, and a second call continues from the last allocated port without reusing earlier values. @test
• After setting defaults to start at 5000 with a stop at 5001, the next port reservation uses that window and the updated defaults persist for subsequent requests. @test

Socket path suggestion

• Given a base path /tmp/demo.sock that already exists, requesting 2 socket paths skips the existing path, returns the next deterministic candidate, and provides a second unique path derived from the same sequence. @test

Implementation

@generates

API

export interface PortRange {
  start?: number;
  stop?: number;
  host?: string;
}

export function configureDefaults(options: { basePort?: number; highestPort?: number; basePath?: string }): void;

/**
 * Find a run of available TCP ports.
 * Returns the first `count` free ports in ascending order, starting from the configured defaults unless overridden.
 */
export async function reservePorts(count: number, range?: PortRange): Promise<number[]>;

/**
 * Suggest available local socket paths.
 * Returns `count` unique, unused Unix socket (or Windows pipe) identifiers derived from the configured base path.
 */
export async function suggestSocketPaths(count: number, basePath?: string): Promise<string[]>;

Dependencies { .dependencies }

portfinder { .dependency }

Uses the dependency's deterministic next-candidate search for both ports and socket paths to mirror its allocation order.