@oxog/port-terminator

    

Cross-platform utility to terminate processes running on specified ports with zero runtime dependencies.

🚀 Features

- Zero Dependencies: No runtime dependencies, only Node.js built-in modules
- Cross-Platform: Works on Windows, macOS, and Linux
- TypeScript First: Full TypeScript support with comprehensive type definitions
- CLI & Programmatic: Use as a CLI tool or import as a library
- Graceful & Force Kill: Supports both graceful shutdown and force termination
- Protocol Support: Target TCP, UDP, or both protocols
- Comprehensive API: Rich set of utility functions for port management
- Production Ready: 100% test coverage, robust error handling

📦 Installation

``bash


Install globally for CLI usage

The package provides both port-terminator and pt (short alias) commands:

`bash


Kill process on single port

`
-r, --range Kill processes in port range (e.g., 3000-3005)
-f, --force Force kill without graceful timeout
-t, --timeout Overall operation timeout (default: 30000)
-g, --graceful-timeout Graceful shutdown timeout (default: 5000)
-m, --method Protocol to target: tcp, udp, or both (default: both)
-n, --dry-run Show what would be killed without actually killing
-j, --json Output results in JSON format
-s, --silent Suppress all output except errors
-h, --help Show help message
-v, --version Show version number
`

📚 Programmatic Usage

$3

`typescript
import { PortTerminator, killPort, killPorts, getProcessOnPort } from '@oxog/port-terminator';

// Simple one-liner to kill a port
await killPort(3000);

// Kill multiple ports
await killPorts([3000, 8080, 9000]);

// Get process information
const process = await getProcessOnPort(3000);
console.log(process); // { pid: 1234, name: 'node', port: 3000, protocol: 'tcp', ... }
`

$3

`typescript
import { PortTerminator } from '@oxog/port-terminator';

const terminator = new PortTerminator({
method: 'tcp', // Only target TCP processes
force: false, // Try graceful shutdown first
gracefulTimeout: 5000, // Wait 5s for graceful shutdown
timeout: 30000, // Overall operation timeout
silent: false // Enable logging
});

// Terminate with detailed results
const results = await terminator.terminateWithDetails([3000, 8080]);
console.log(results);
/*
[
{
port: 3000,
success: true,
processes: [{ pid: 1234, name: 'node', ... }]
},
{
port: 8080,
success: false,
processes: [],
error: "Permission denied"
}
]
*/

// Check if port is available
const isAvailable = await terminator.isPortAvailable(3000);

// Wait for port to become available
await terminator.waitForPort(3000, 10000); // Wait up to 10 seconds

// Get all processes on a port
const processes = await terminator.getProcesses(3000);
`

$3

`typescript
import { PortScanner } from '@oxog/port-terminator';

const scanner = new PortScanner();

// Scan a single port
const result = await scanner.scanPort(3000);
console.log(result); // { port: 3000, available: false, processes: [...] }

// Scan multiple ports
const results = await scanner.scanPorts([3000, 8080, 9000]);

// Scan a port range
const rangeResult = await scanner.scanPortRange(3000, 3010);
console.log(rangeResult.availablePorts); // [3002, 3004, 3007, ...]

// Find next available port
const availablePort = await scanner.findAvailablePort(3000); // Returns 3001 if 3000 is busy

// Find multiple available ports
const availablePorts = await scanner.findAvailablePorts(5, 3000); // Find 5 available ports starting from 3000
`

🔍 API Reference

$3

`typescript
class PortTerminator {
constructor(options?: IPortTerminatorOptions);

// Terminate processes on port(s)
terminate(port: number | number[]): Promise;
terminateMultiple(ports: number[]): Promise>;
terminateWithDetails(ports: number[]): Promise;

// Query operations
getProcesses(port: number): Promise;
isPortAvailable(port: number): Promise;
waitForPort(port: number, timeout?: number): Promise;
}
`

$3

`typescript
// Simple termination functions
killPort(port: number, options?: IPortTerminatorOptions): Promise;
killPorts(ports: number[], options?: IPortTerminatorOptions): Promise>;

// Query functions
getProcessOnPort(port: number, options?: IPortTerminatorOptions): Promise;
getProcessesOnPort(port: number, options?: IPortTerminatorOptions): Promise;
isPortAvailable(port: number, options?: IPortTerminatorOptions): Promise;
waitForPort(port: number, timeout?: number, options?: IPortTerminatorOptions): Promise;
`

$3

`typescript
interface IPortTerminatorOptions {
method?: 'tcp' | 'udp' | 'both'; // Default: 'both'
timeout?: number; // Default: 30000
force?: boolean; // Default: false
silent?: boolean; // Default: false
gracefulTimeout?: number; // Default: 5000
}

interface IProcessInfo {
pid: number;
name: string;
port: number;
protocol: string;
command?: string;
user?: string;
}

interface ITerminationResult {
port: number;
success: boolean;
processes: IProcessInfo[];
error?: string;
}
`

🔧 Platform Support

$3