TCP Ping Utility

0.1.1 · abandoned · verified Sun Apr 19

This Node.js utility provides TCP-based ping functionality, enabling users to test the availability and measure the latency of specific services on given addresses and ports. Unlike traditional ICMP `ping` tools, `tcp-ping` avoids issues with ICMP-blocked servers and offers faster results by immediately dropping connections after acceptance. It's particularly useful for verifying service-level availability rather than just general network connectivity. The package's current and only documented version is 0.1.1, indicating a very early stage of development or a project that is no longer actively maintained. Its release cadence is effectively non-existent. Key differentiators include its speed, the ability to target specific ports and services, and its resilience to ICMP filtering, making it more effective for certain server monitoring scenarios.

Common errors

```
ReferenceError: require is not defined
```
cause Attempting to use `require()` in an ES module context (`type: "module"` in package.json or `.mjs` file).

fix For ES module environments, use `import tcpp from 'tcp-ping';` or `import * as tcpp from 'tcp-ping';`. Alternatively, ensure your file is treated as CommonJS (e.g., `.js` file without `type: "module"`).
```
Error: connect ECONNREFUSED
```
cause The target server actively refused the connection, likely because no service is listening on the specified port, a firewall is blocking the connection, or the server is not running.

fix Verify that the target service is running, the port is correct, and network configurations (including firewalls) allow connections from the origin machine.
```
Error: connect ETIMEDOUT
```
cause The connection attempt timed out, meaning the server did not respond within the specified `timeout` period (or default 5s). This can be due to network congestion, a firewall silently dropping packets, or the host being down/unreachable.

fix Increase the `timeout` option in the `ping` function (e.g., `timeout: 10000` for 10 seconds) or check network connectivity and firewalls between the client and server.
```
TypeError: tcpp.ping is not a function
```
cause The `tcpp` object was not correctly imported, or the variable name `tcpp` is misspelled, preventing access to its `ping` method.

fix Ensure `const tcpp = require('tcp-ping');` or `import tcpp from 'tcp-ping';` is at the top of your file and the `tcpp` variable is used consistently.

Warnings

breaking The package is at version 0.1.1 and has not seen updates since its initial release. This implies potential compatibility issues with newer Node.js versions or dependencies, and a lack of security patches for any discovered vulnerabilities.
Fix: Consider using a more actively maintained TCP ping utility or implement custom socket-based checks for critical applications. Evaluate thoroughly if compatibility issues arise with modern Node.js environments.
gotcha The API is entirely callback-based, which is common for older Node.js libraries. It does not provide Promise-based interfaces or support `async/await` directly, leading to potential 'callback hell' in complex asynchronous flows.
Fix: Wrap `tcp-ping` calls in Promises using `util.promisify` (if applicable for `(err, data)` callback structure) or manual Promise constructors to integrate with `async/await` patterns.
gotcha The package uses Node.js's `net` module internally. Incorrect usage of `address` or `port` options, or attempting to ping non-routable/firewalled addresses, will result in network errors (e.g., `ECONNREFUSED`, `ETIMEDOUT`, `EHOSTUNREACH`) rather than simple `true`/`false` responses.
Fix: Always implement robust error handling in the callback function. Ensure the target address is reachable and the port is open to receive connections for accurate results.

Install

npm install tcp-ping npm
yarn add tcp-ping yarn
pnpm add tcp-ping pnpm

Imports

tcpp
```
const tcpp = require('tcp-ping');
```
This is the canonical CommonJS import method for this package, typical for older Node.js projects.
tcpp
wrong:
```
import { ping, probe } from 'tcp-ping';
```
correct:
```
import tcpp from 'tcp-ping';
```
While Node.js's interoperability allows default ES module imports for CommonJS modules, named imports for 'ping' or 'probe' will fail as the package exports a single object, not individual functions.
tcpp (namespace import)
```
import * as tcpp from 'tcp-ping';
```
This ES module 'namespace' import bundles all CommonJS exports into a single 'tcpp' object, ensuring compatibility in modern module contexts.

Quickstart

This example demonstrates how to use `tcp-ping` to both probe for service availability and measure latency statistics for a given address and port.

const tcpp = require('tcp-ping');

const targetAddress = '46.28.246.123'; // Replace with a real IP or hostname
const targetPort = 80;

tcpp.probe(targetAddress, targetPort, function(err, available) {
    if (err) {
        console.error(`Probe error for ${targetAddress}:${targetPort}:`, err.message);
    } else {
        console.log(`Service at ${targetAddress}:${targetPort} available: ${available}`);
    }
});

tcpp.ping({ address: targetAddress, port: targetPort, attempts: 5, timeout: 2000 }, function(err, data) {
    if (err) {
        console.error(`Ping error for ${targetAddress}:${targetPort}:`, err.message);
    } else {
        console.log(`Ping results for ${targetAddress}:${targetPort}:`);
        console.log(`  Attempts: ${data.attempts}`);
        console.log(`  Average latency: ${data.avg.toFixed(2)}ms`);
        console.log(`  Min latency: ${data.min.toFixed(2)}ms`);
        console.log(`  Max latency: ${data.max.toFixed(2)}ms`);
        // console.log('  Raw results:', data.results);
    }
});

view raw JSON →