or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdport-detection.mdport-waiting.md
tile.json

tessl/npm-detect-port

Node.js implementation of port detector that finds available network ports automatically

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/detect-port@2.1.x

To install, run

npx @tessl/cli install tessl/npm-detect-port@2.1.0

index.mddocs/

Detect Port

Detect Port is a Node.js library that automatically finds available network ports when specified ports are occupied. It provides both programmatic APIs with full TypeScript support and command-line interfaces for detecting open ports, with the core functionality being the ability to suggest alternative ports when the requested port is unavailable.

Package Information

  • Package Name: detect-port
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install detect-port

Core Imports

import { detect, detectPort, waitPort } from "detect-port";

For CommonJS:

const { detect, detectPort, waitPort } = require("detect-port");

Default import (same as detectPort):

import detect from "detect-port";

Basic Usage

import { detect } from "detect-port";

// Check if port 3000 is available
const availablePort = await detect(3000);

if (availablePort === 3000) {
  console.log("Port 3000 is available");
} else {
  console.log(`Port 3000 is occupied, suggested port: ${availablePort}`);
}

// Get a random available port
const randomPort = await detect();
console.log(`Random available port: ${randomPort}`);

Architecture

Detect Port is built around several key components:

  • Port Detection Engine: Core functionality that systematically checks port availability across different network interfaces (localhost, 0.0.0.0, 127.0.0.1, current IP)
  • Flexible API: Supports both Promise-based and callback-based usage patterns
  • Type Safety: Full TypeScript support with comprehensive type definitions
  • Port Waiting: Additional utility to wait for ports to become available (occupied by other processes)
  • CLI Interface: Command-line tools for port detection with verbose logging options

Capabilities

Port Detection

Core port detection functionality that finds available ports by trying the specified port and incrementing if occupied.

function detectPort(port?: number | PortConfig | string): Promise<number>;
function detectPort(callback: DetectPortCallback): void;
function detectPort(port: number | PortConfig | string | undefined, callback: DetectPortCallback): void;

// Alias for detectPort
const detect: typeof detectPort;

interface PortConfig {
  port?: number | string;
  hostname?: string | undefined;
  callback?: DetectPortCallback;
}

type DetectPortCallback = (err: Error | null, port?: number) => void;

Port Detection

Port Waiting

Utility for waiting until a specified port becomes available (occupied by another process).

function waitPort(port: number, options?: WaitPortOptions): Promise<boolean>;

interface WaitPortOptions {
  retryInterval?: number;
  retries?: number;
}

Port Waiting

Error Handling

class IPAddressNotAvailableError extends Error {
  constructor(options?: ErrorOptions);
}

class WaitPortRetryError extends Error {
  retries: number;
  count: number;
  constructor(message: string, retries: number, count: number, options?: ErrorOptions);
}

CLI Usage

The package includes command-line tools for port detection (available as both detect and detect-port commands):

# Get a random available port
detect
# or
detect-port

# Check a specific port
detect 3000
detect-port 3000

# Verbose output
detect 3000 --verbose

# Show version
detect --version
detect -v

# Show help
detect --help
detect -h