@fnet/free-port

The @fnet/free-port project is a straightforward utility designed to help users identify available network ports on their local machine. This tool is useful for developers and system administrators who need to quickly find open ports for running applications or services without conflicts.

How It Works

The utility operates by checking specified ports or ranges of ports on a local computer to determine whether they are in use. It uses platform-specific commands to verify port availability, supporting both Windows and Unix-like systems. Users can request a certain number of free ports, and the tool will return a list of available ports up to that specified count.

Key Features

• Port Range Checking: Allows users to specify individual ports or a range of ports to check for availability.
• Adjustable Count: Users can request multiple available ports by specifying the desired count.
• Cross-Platform Support: Compatible with both Windows and Unix-based systems.

Conclusion

The @fnet/free-port utility provides a simple and effective way to find available network ports on your machine, aiding in tasks such as setting up new services or applications that require free port assignments. It contributes to a smoother workflow by quickly resolving port availability issues.

@fnet/free-port Developer Guide

Overview

The @fnet/free-port library is designed to help developers find available network ports on a local machine. It checks specific ports or port ranges and returns the specified number of available ports. This is especially useful in applications where dynamic port allocation is necessary, such as during testing or when deploying network services on a machine with limited port resources.

Installation

You can install the @fnet/free-port package using either npm or yarn. Below are the commands for installation:

Using npm:

npm install @fnet/free-port

Using yarn:

yarn add @fnet/free-port

Usage

The primary function provided by this library is an asynchronous method to find available ports. Here’s how you can use it in a typical setup:

import findFreePorts from '@fnet/free-port';

async function getAvailablePorts() {
  try {
    const availablePorts = await findFreePorts({
      ports: [[3000, 3010]], // Optionally specify port ranges or lists
      count: 3,              // Specify how many available ports you need
      shuffle: true          // Optionally shuffle the order before checking
    });
    console.log('Available Ports:', availablePorts);
  } catch (error) {
    console.error('Error finding available ports:', error);
  }
}

getAvailablePorts();

Examples

Below are examples demonstrating how to use the library to find available ports.

Example 1: Basic Usage

Find a single available port within the default range (32767 to 65535).

import findFreePorts from '@fnet/free-port';

findFreePorts().then((ports) => {
  console.log('Available Port:', ports[0]);  // Output: [port_number]
});

Example 2: Specify Port Range and Count

Find five available ports within a specific port range.

import findFreePorts from '@fnet/free-port';

findFreePorts({ ports: [[8080, 8090]], count: 5 }).then((ports) => {
  console.log('Available Ports:', ports);  // Output: [port_number1, port_number2, ...]
});

Example 3: Disable Shuffling

Find two available ports without shuffling, which checks ports sequentially as specified.

import findFreePorts from '@fnet/free-port';

findFreePorts({ ports: [3000, 3001, 3002, 3003], count: 2, shuffle: false }).then((ports) => {
  console.log('Available Ports:', ports);  // Output: [port_number1, port_number2]
});

Acknowledgement

We would like to acknowledge the contributors who have helped in the development and maintenance of this library. Their efforts in providing a reliable tool for port availability checking enhance the developer experience significantly.

Input Schema

$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
  ports:
    description: List of specific ports or ranges to check for availability. If a
      range is specified, ports within that range are checked.
    type: array
    items:
      oneOf:
        - type: number
        - type: array
          items:
            type: number
          minItems: 2
          maxItems: 2
    default:
      - - 32767
        - 65535
  count:
    description: The number of available ports to find.
    type: number
    default: 1
  shuffle:
    description: Shuffle the list of ports before checking availability.
    type: boolean
    default: true
required: []