@juit/lib-ping NPM

Ping library for NodeJS

Does it work?

it seems to...

Does it require root?

nope!

This library simply pings a host, and tracks the latency over time.

Simply construct a Pinger with a host name / address and start() it!

const pinger = await createPinger(`${addr}`)

pinger.start()

// wait for some time... then collect stats
const stats = pinger.stats()

// `stats` will now contain
// {
//   sent: 123,     // the number of ECHO Requests sent since the last call to `stats()`
//   received: 120, // the number of ECHO Responses received since the last call to `stats()`
//   latency: 98,   // the average PING latency since the last call to `stats()`
// }

ping.close()

Creating a `Pinger`

A Pinger instance can be created calling the asynchronous createPinger(...) method. This method takes two parameters:

to: an IPv4 or IPv6 IP address to ping, or a host name. By default host names will be resolved as IPv4 (A records), unless the options.protocol value is set to ipv6, in which case it will be resolved as an IPv6 (AAAA record).
options: an optional object containing options for the Pinger.

Options

protocol: (either ipv4 or ipv6) the protocol to use. if the to address is an IPv6 address the protocol will default to ipv6, in all other cases it will default to ipv4.
from: the IP address ping from; this is useful when
source: the interface name used as the source of our ICMP packages.
timeout: (default: 30000 or 30 seconds) the timeout in milliseconds after which a packet is considered lost.
interval: (default: 1000 or 1 second) the interval in milliseconds used to ping the remote host.

The `Pinger` interface

Methods

ping(): that's it... send an ICMP Echo Request packet.
start(): starts the Pinger, collecting stats and emitting events.
stop(): stops the Pinger, but keeps the underlying socket open.
close(): stops the Pinger and closes the underlying socket.
stats(): collect and reset statistics.

Properties

target: the target IP address to ping to.
from: the source IP address used to ping from or undefined.
source: the name of the source interface being used or undefined.
timeout: the timeout in milliseconds after which a packet is considered lost.
interval: the iterval in milliseconds at which ECHO requests are sent.
protocol: the IP protocol, either ipv4 or ipv6.
running: whether the Pinger is running or not.
closed: whether the socket is closed or not.

Events

pong(latency): when an ECHO Reply packet is received (latency is in milliseconds).
warning(code, message): when a warning occurred it includes an error code and relative message.
error: when an error occurred; in this case the pinger is automatically closed.