tcp-ping

tcp-ping is a minimal Node.js module that measures round-trip latency to a given host and port using raw TCP connections instead of ICMP echo requests. Because many servers and firewalls silently drop ICMP packets even when the underlying service is healthy, tcp-ping’s connect-and-destroy approach gives a more reliable signal for service-level availability checks than the traditional ping command.

The module exposes two functions: ping(), which runs a configurable number of connection attempts and returns detailed timing statistics (average, min, max, and per-attempt results), and probe(), a simpler boolean check for whether a single connection succeeds. Both use Node’s built-in net module with no external dependencies, making it easy to drop into monitoring scripts, health checks, or uptime dashboards.

What You Get

• A ping() function that runs multiple TCP connection attempts and returns average/min/max latency plus per-attempt results
• A probe() function that returns a simple true/false signal for whether a host:port is currently accepting connections
• Configurable address, port, timeout, and attempt count for tailoring checks to a specific service
• Zero external dependencies — built entirely on Node’s core net module

Common Use Cases

• Verifying a specific service (not just the host) is reachable when ICMP is blocked or dropped by firewalls
• Building custom uptime/health-check scripts for internal monitoring tools
• Measuring latency to a database, cache, or API endpoint before running dependent operations
• Scripting quick command-line diagnostics during incident response

Under The Hood

Architecture tcp-ping is a single-file CommonJS module (ping.js, ~90 lines) with no internal layering — module.exports directly exposes two functions, ping() and probe(), both implemented as closures over Node’s core net module. The core control flow is a hand-rolled recursive state machine: a check() function tests a mutable attempt counter i against options.attempts and either invokes connect() again or aggregates the results array into avg/min/max statistics; connect() opens a net.Socket, times the connection via process.hrtime, and calls back into check() on success, error, or timeout. probe() is a thin convenience wrapper that calls ping() with attempts=1 and derives a boolean from whether data.min is defined. Because probe() depends directly on ping()‘s output shape, any change to the aggregation logic in check() would silently propagate to both public entry points, with no shared interface or type boundary between them beyond the plain object contract.

Tech Stack The package has zero runtime dependencies, relying entirely on Node’s built-in net module for socket handling and process.hrtime for high-resolution timing — there is no HTTP framework, database, or build step involved. package.json declares no devDependencies either; the “test” script is a placeholder (echo 0) rather than an actual test runner, and there’s no bundler, transpiler, or TypeScript config, so the module ships as plain, unmodified JavaScript targeting whatever Node version supports its CommonJS require/module.exports pattern.

Code Quality No test files exist anywhere in the repository, and the package.json test script (echo 0) is a no-op rather than a real test suite, so there is no verification harness for the ping()/probe() logic. Error handling is present but coarse-grained — connection errors and timeouts are captured via the socket’s error and timeout callbacks and pushed into the results array as entries with an undefined time and an err field, rather than being surfaced distinctly to the caller. There is no TypeScript, no type annotations, no linter or formatter configuration, and no CI workflow. Naming is short and readable (ping, probe, connect, check), but the module offers no docstrings or inline documentation beyond the README’s usage examples.

API Design tcp-ping’s core idea — using an active TCP handshake instead of ICMP echo to probe service availability — was a genuinely useful workaround for the common problem of firewalls silently dropping ping packets, and it remains a reasonable pattern for service-level health checks. That said, the implementation itself is unremarkable: a callback-only API with no Promise/async support, no streaming or event-based interface, and a fixed statistics shape (avg/min/max) with no percentile or histogram options. Getting started requires almost no boilerplate — probe(address, port, callback) is effectively a one-liner — but the callback-only surface and lack of type definitions mean it doesn’t fit naturally into modern async/await codebases without a manual wrapper.