@network-utils/tcp-ping
Version:
A simple TCP ping util, written in Typescript, to test the reachability and latency of a host.
119 lines (92 loc) • 3.45 kB
Markdown
[](https://github.com/justintaddei/tcp-ping/actions/workflows/tests.yml)
[](https://github.com/prettier/prettier)
A simple promise-based TCP ping util, written in Typescript, to test the reachability and latency of a host.
```bash
$ npm install @network-utils/tcp-ping --save
```
Pings the given host and returns an object containing the latency of the connection
and any errors that may have occured.
> **NOTE:** Attempts are not concurrent. As such if a host is unreachable and you provide options { attempts: 60, timeout: 1000 } then `ping` will not resolve for a full minute!
```typescript
import { ping } from '@network/tcp-ping'
ping({
// The IP address or hostname of the host you want
// to ping. Defaults to 127.0.0.1 (localhost)
address: '192.168.1.47',
// How many times do you want want to
// attempt to reach the host? Default is 10
attempts: 10,
// What port do you want to connect on?
// Default is 80
port: 80,
// How long do you want to wait (in milliseconds)
// before assuming an attempt has failed?
// Default is 3000 (3 seconds)
timeout: 3000
}, update).then(result => {
console.log('ping result:', result)
// ping result:
{
averageLatency: 19.2753,
errors: [
{
// Which attempt failed
attempt: 3,
error: Error('Request timeout')
}
],
maximumLatency: 35.1978,
minimumLatency: 3.7716,
options: {
address: '192.168.1.47',
attempts: 10,
port: 80,
timeout: 3000
}
}
})
function update(progress, total) {
console.log(progress, '/', total)
/*
1 / 10
2 / 10
3 / 10
...
*/
}
```
Makes one attempt to reach the host and returns a `boolean` indicating whether or not it was successful.
If `address` is not provided it will default to `'127.0.0.1'`.
If `timeout` is not provided it will default to `3000`.
```typescript
import { probe } from '@network/tcp-ping'
probe(80, '192.168.1.47', 500).then(hostReachable => {
if (hostReachable) console.log('The host is reachable 🙌')
else console.log('The host is not reachable 🤐')
})
// Or
const hostReachable = await probe(80, '192.168.1.47', 500)
```
- All methods will throw a `"Negative port"` error if `port < 1`.
---
```bash
$ git clone https://github.com/justintaddei/tcp-ping.git
$ cd tcp-ping
$ npm install
$ npm test
```
MIT