advanced-js-kit/dist/node/network/index.d.ts

Modern TypeScript utility library with tree-shaking support - Array, String, Number, Network, Sleep, and JWT utilities for JavaScript and TypeScript projects

/**
 * Options for port checking operations
 */
interface PortCheckOptions {
    /** The host to check (default: 'localhost') */
    host?: string;
    /** Timeout in milliseconds (default: 5000) */
    timeout?: number;
}
/**
 * Options for finding an available port
 */
interface FindPortOptions extends PortCheckOptions {
    /** The starting port number to search from */
    startPort?: number;
    /** The ending port number to search until */
    endPort?: number;
    /** Maximum number of ports to try (default: 100) */
    maxTries?: number;
}
/**
 * Custom error class for port-related operations
 */
declare class PortError extends Error {
    readonly port?: number | undefined;
    readonly host?: string | undefined;
    constructor(message: string, port?: number | undefined, host?: string | undefined);
}
/**
 * Checks if a specific port is currently in use
 *
 * @param port - The port number to check (1-65535)
 * @param options - Configuration options for the port check
 * @returns Promise that resolves to true if the port is in use, false otherwise
 *
 * @throws {PortError} When port number is invalid or check fails
 *
 * @example
 * ```typescript
 * // Check if port 3000 is in use on localhost
 * const inUse = await isPortInUse(3000);
 * console.log(`Port 3000 is ${inUse ? 'in use' : 'available'}`);
 *
 * // Check a port on a different host with custom timeout
 * const inUse = await isPortInUse(8080, { host: '192.168.1.100', timeout: 3000 });
 * ```
 */
declare const isPortInUse: (port: number, options?: PortCheckOptions) => Promise<boolean>;
/**
 * Checks if a specific port is available (not in use)
 *
 * @param port - The port number to check (1-65535)
 * @param options - Configuration options for the port check
 * @returns Promise that resolves to true if the port is available, false otherwise
 *
 * @throws {PortError} When port number is invalid or check fails
 *
 * @example
 * ```typescript
 * // Check if port 3000 is available
 * const available = await isPortAvailable(3000);
 * if (available) {
 *   console.log('Port 3000 is ready to use!');
 * }
 * ```
 */
declare const isPortAvailable: (port: number, options?: PortCheckOptions) => Promise<boolean>;
/**
 * Finds the next available port starting from a given port number
 *
 * @param options - Configuration options for finding an available port
 * @returns Promise that resolves to an available port number
 *
 * @throws {PortError} When no available port is found within the specified range
 *
 * @example
 * ```typescript
 * // Find any available port starting from 3000
 * const port = await findAvailablePort({ startPort: 3000 });
 * console.log(`Found available port: ${port}`);
 *
 * // Find port within a specific range
 * const port = await findAvailablePort({
 *   startPort: 8000,
 *   endPort: 8100,
 *   host: '0.0.0.0'
 * });
 * ```
 */
declare const findAvailablePort: (options?: FindPortOptions) => Promise<number>;
/**
 * Checks multiple ports and returns their availability status
 *
 * @param ports - Array of port numbers to check
 * @param options - Configuration options for the port checks
 * @returns Promise that resolves to a Map with port numbers as keys and availability status as values
 *
 * @example
 * ```typescript
 * // Check multiple ports at once
 * const results = await checkMultiplePorts([3000, 3001, 3002, 8080]);
 * results.forEach((available, port) => {
 *   console.log(`Port ${port}: ${available ? 'available' : 'in use'}`);
 * });
 * ```
 */
declare const checkMultiplePorts: (ports: readonly number[], options?: PortCheckOptions) => Promise<Map<number, boolean>>;
/**
 * Waits for a port to become available or in use
 *
 * @param port - The port number to monitor
 * @param targetState - Whether to wait for 'available' or 'in-use' state
 * @param options - Configuration options including polling interval and timeout
 * @returns Promise that resolves when the port reaches the target state
 *
 * @throws {PortError} When timeout is reached or port validation fails
 *
 * @example
 * ```typescript
 * // Wait for a service to start on port 3000
 * await waitForPort(3000, 'in-use', { timeout: 30000 });
 * console.log('Service is now running on port 3000');
 *
 * // Wait for a port to be freed up
 * await waitForPort(3000, 'available');
 * console.log('Port 3000 is now available');
 * ```
 */
declare const waitForPort: (port: number, targetState: "available" | "in-use", options?: PortCheckOptions & {
    /** Polling interval in milliseconds (default: 1000) */
    pollInterval?: number;
    /** Overall timeout in milliseconds (default: 30000) */
    overallTimeout?: number;
}) => Promise<void>;

export { type FindPortOptions, type PortCheckOptions, PortError, checkMultiplePorts, findAvailablePort, isPortAvailable, isPortInUse, waitForPort };