Get-open-port NPM

Port Manager Utility

This Node.js utility helps manage and check the availability of ports on a machine. It supports features like locking ports, excluding specific ports, and managing port ranges, making it ideal for network-related applications and server setups.

Features

Port Availability Check: Ensures a port is available on local network interfaces.
Port Locking: Temporarily locks ports to prevent simultaneous usage.
Custom Port Ranges: Defines and iterates over specific port ranges.
Exclusions: Excludes certain ports from being used.
Timeout Handling: Configures timeouts for port checks.

Installation

npm install get-open-port

Usage

Get a Free Port

Retrieve an available port, optionally specifying preferred ports or exclusions:

const { getOpenPort } = require("get-open-port");

(async () => {
    try {
        const port = await getOpenPort({
            port: [3000, 4000], // Optional preferred ports
            exclude: [8080],    // Ports to exclude
            timeout: 2000       // Optional timeout (ms)
        });
        console.log(`Available port: ${port}`);
    } catch (error) {
        console.error("Error getting a free port:", error);
    }
})();

Lock Ports

Prevent specific ports from being reused until unlocked or cleaned up:

const { portManager } = require("get-open-port");

// Lock port 3000
portManager.locked.set(3000, Date.now());

Clear Locked Ports

Unlock all previously locked ports:

const { clearLockedPorts } = require("get-open-port");

clearLockedPorts();

Port Range Utility

Generate a range of port numbers:

const { getPortRange } = require("get-open-port");

const range = getPortRange(3000, 3010);
console.log(range); // [3000, 3001, 3002, ..., 3010]

Handle Port Lock Errors

Handle errors related to locked ports:

const { getOpenPort, LockedPortError } = require("get-open-port");

(async () => {
    try {
        const port = await getOpenPort({ port: [3000] });
        console.log(`Available port: ${port}`);
    } catch (error) {
        if (error instanceof LockedPortError) {
            console.error(`Port ${error.port} is locked.`);
        } else {
            console.error("An error occurred:", error);
        }
    }
})();

Configuration

The utility uses the following default settings:

Minimum Port: 1024
Maximum Port: 65535
Cleanup Interval: 15 seconds (locked ports are cleared after this duration)

These settings can be adjusted by modifying the portManager object:

const { portManager } = require("get-open-port");

portManager.minPort = 2000;
portManager.maxPort = 60000;
portManager.cleanupInterval = 10_000; // 10 seconds