https://github.com/dopecodez/pingman
Wrapper for ping module with node and no dependencies.
https://github.com/dopecodez/pingman
ava hacktoberfest node node-ping nodejs npm-package ping ping-server travis-ci typescript typescript-definitions
Last synced: about 1 year ago
JSON representation
Wrapper for ping module with node and no dependencies.
- Host: GitHub
- URL: https://github.com/dopecodez/pingman
- Owner: dopecodez
- License: mit
- Created: 2020-05-09T11:41:04.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2024-10-09T14:19:04.000Z (over 1 year ago)
- Last Synced: 2025-03-30T09:07:54.025Z (about 1 year ago)
- Topics: ava, hacktoberfest, node, node-ping, nodejs, npm-package, ping, ping-server, travis-ci, typescript, typescript-definitions
- Language: TypeScript
- Homepage:
- Size: 1.03 MB
- Stars: 35
- Watchers: 1
- Forks: 7
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# PINGMAN [](https://github.com/dopecodez/pingman/actions) [](https://github.com/dopecodez/pingman/issues) [](https://badge.fury.io/js/pingman) [](https://codeclimate.com/github/dopecodez/pingman/test_coverage)
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](#Usage)
- [Available options](#available-options)
- [Output Model](#output-model)
- [Types](#types)
- [Extended options(Platform-specific)](#extended-options)
- [Contributing](#contributing)
## Usage
```js
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
```js
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
```js
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](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/ping), and the `man` pages for [Mac](https://ss64.com/osx/ping.html) and [Linux](https://linux.die.net/man/8/ping).
There are options which are platform-specific across all three platforms. These are included in the `extendedPingOptions` available and can be found [here](#extended-options). 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
```js
/**
* 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} 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][1].
[1]: https://github.com/dopecodez/pingman/blob/master/CONTRIBUTING.md
## Contributors
The project would not be the way it is without these rockstars.
Govind S
Greeshma R
Jack Baron
JessC) Vermeulen
Sravanth C.
Foxxyz