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 |

Contributing

Before opening a pull request please make sure your changes follow the contribution guidelines.

Contributors

The project would not be the way it is without these rockstars.