PINGMAN

Human-friendly node wrapper for ping utility across platforms.

Add ping utility to your projects with zero dependencies. Build with latest ES6 features with native support for async/await and promises.

Newly released and actively maintained. Small unpacked size.

INSTALLATION

$ npm install pingman

Highlights

Usage
Available options
Output Model
Types
Extended options(Platform-specific)
Contributing

Usage

const ping = require('pingman');

(async () => {
	try {
		const response = await ping('127.0.0.1');
		console.log(response);
		if(response.alive){
		//=>if pinged ip is available and responds
		}	
	} catch (error) {
		console.log(error);
		//=> 'Internal server error ...'
	}
})();

Usage with options and TypeScript

import ping, {pingResponse, pingOptions} from 'pingman'

(async () => {
	try {
		const options: pingOptions = {logToFile:true, numberOfEchos: 6, timeout: 2, IPV4: true};
		const response: pingResponse = await ping('www.github.com', {logToFile:true, numberOfEchos: 6, timeout: 2, IPV4: true});
		console.log(response);
		if(response.alive){
		//=>if pinged ip is available and responds
		}
	} catch (error) {
		console.log(error);
		//=> 'Internal server error ...'
	}
})();

Available options

let response = await ping(TargetIp, {options})

TargetIp can be any valid IPV4 host, IPV6 host or domain name.

The options available are based on the docs available for Windows, and the man pages for Mac and Linux.

There are options which are platform-specific across all three platforms. These are included in the extendedPingOptions available and can be found here. The general options available are abstracted across platforms and should work on all platforms. They can be found in the pingOptions object available in types.

option	Type	On Windows	On Unix
numeric	boolean	-a	-n
bufferSize	number	-l	-s
numberOfEchos	number	-n	-c
TTL	number	-i	-t(-m for Mac)
timeout	number	-w	-w(-W for Mac)
IPV6	boolean	-6	ping6
IPV4	boolean	-4	ping

Note : The above options are the general options across platforms

Please specify the IPV6 option in case the target is an IPV6 address. While in windows it is not required, it is required in unix systems so as to invoke ping6 command.

There are two further options available: logToFile and logFilePath. If logToFile is set to true, it will log the command and output to a default log.txt file at your project root. This is helpful in case you are trying to debug or want a more detailed idea of the output. logFilePath can be used in case you want a custom log file path relative to your project root.

Output Model

/**
 * Parsed response
 * @typedef {pingResponse} pingResponse
 * @param {string} host - The input IP address or HOST
 * @param {string} numeric_host - Target IP address
 * @param {boolean} alive - True for existed host
 * @param {string} output - Raw stdout from system ping
 * @param {number} time - Time (float) in ms for first successful ping response
 * @param {Array<number>} times - Array of Time (float) in ms for each ping response
 * @param {number} min - Minimum time for collection records
 * @param {number} max - Maximum time for collection records
 * @param {number} avg - Average time for collection records
 * @param {number} bufferSize - Buffer size of each packet sent to target
 * @param {string} packetLoss - Packet Losses in percent (100% -> "100.000")
 * @param {string} number - Standard deviation time for collected records
 */

Types

Pingman exports some handy TypeScript types and interfaces. See the type definition for all the exported types.

Extended options

Note : Using the below options could cause your code to behave unexpectedly in some platforms

option	Type	On Windows	On Unix
recordRouteHops	number	-r	N/A
hopTimestamp	number	-s	N/A
interval	number	N/A	-i
soDebugOption	boolean	N/A	-d
floodPing	boolean	N/A	-f
interfaceAddress	string	N/A	-I
suppressLoopback	boolean	N/A	-L
pattern	string	N/A	-p
quiet	boolean	N/A	-q
timeBeforeExit	number	N/A	-W(-t for Mac)
verboseOutput	boolean	N/A	-v
doNotFragment	boolean	-f	-D for Mac
srcAddr	string	-S	-S for Mac