@nodesonar/core

A TypeScript network scanning and monitoring toolkit for Node.js. Discover devices on your network, ping hosts, and poll devices at configurable intervals — all with a clean, typed API.

Features

• 📡 Host Pinging — Ping any host or IP address and get structured results
• 🔄 Device Polling — Poll one or more hosts at configurable intervals with live callbacks
• 🔍 IP Range Scanning — Discover reachable devices across CIDR, dash, and wildcard ranges
• 🧠 Flexible IP Range Parsing — Supports CIDR, dash ranges, full IP-to-IP ranges, and wildcards
• 💪 Fully Typed — Written in TypeScript with declaration files included

Installation

npm install @nodesonar/core

Usage

Poller — Poll hosts at a configurable interval

import { Poller } from '@nodesonar/core';

const poller = new Poller({ timeout: 2 });

// Poll a single host every 5 seconds
poller.pollHost({ host: '192.168.1.1', interval: 5000 }, (res) => {
  console.log(`${res.host} is ${res.status}`);
  console.log(`Packets — sent: ${res.count}, received: ${res.packetsReceived}, loss: ${res.packetLoss * 100}%`);

  if (res.latency) {
    console.log(`Latency — avg: ${res.latency.average}ms, fastest: ${res.latency.fastest}ms, slowest: ${res.latency.slowest}ms`);
  }
});

// Poll multiple hosts simultaneously
poller.pollHost({ host: '192.168.1.2', interval: 2000 }, (res) => {
  console.log(res);
});

// Check which hosts are currently being polled
console.log(poller.activeHosts); // ['192.168.1.1', '192.168.1.2']

// Stop polling a specific host
poller.stopPolling('192.168.1.1');

// Stop all polling
poller.stopAll();

Ping a host directly

import { Poller } from '@nodesonar/core';

const poller = new Poller();

const result = await poller.pingHost('192.168.1.1');
console.log(result);
// {
//   host: '192.168.1.1',
//   isReachable: true,
//   status: 'Online',
//   count: 4,
//   packetsReceived: 4,
//   latency: {
//     average: 4.2,
//     fastest: 3.1,
//     slowest: 5.8
//   },
//   packetLoss: 0,
//   output: '...'
// }

// When host is unreachable
// {
//   host: '192.168.1.1',
//   isReachable: false,
//   status: 'Offline',
//   count: 4,
//   packetsReceived: 0,
//   latency: null,
//   packetLoss: 1,
//   output: '...'
// }

IPScanner — Discover devices on your network

import { IPScanner } from '@nodesonar/core';

const scanner = new IPScanner({ timeout: 2 });

// Scan a range and get all discovered devices
const devices = await scanner.discover('192.168.1.0/24');
console.log(devices);

// Stream devices as they are found
const devices = await scanner.discover('192.168.1.0-255', (device) => {
  console.log(`Found: ${device.host}`);
});

Supported range formats:

| Format | Example | |---|---| | CIDR | 192.168.1.0/24 | | Short dash | 192.168.1.0-255 | | Full IP range | 192.168.1.0-192.168.1.100 | | Wildcard | 192.168.1.* | | Single IP | 192.168.1.1 |

API

Poller

| Method | Description | |---|---| | pollHost(config, cb) | Polls a host at the specified interval, invoking the callback with each result. | | stopPolling(host) | Stops polling the specified host. | | stopAll() | Stops all active polling intervals. | | pingHost(host) | Pings a host once and returns the result. | | activeHosts | Returns a list of hosts currently being polled. | | config | Returns the current poller configuration. |

IPScanner

| Method | Description | |---|---| | discover(range, onDeviceFound?) | Scans the given IP range and returns all reachable devices. Optionally streams results via callback. |

Types

PingHost.Response

interface Response {
  host: string;
  status: 'Online' | 'Offline';
  isReachable: boolean;
  count: number;
  packetsReceived: number;
  latency: {
    average: number;
    fastest: number;
    slowest: number;
  } | null;
  packetLoss: number; // 0–1 (e.g. 0.75 = 75% loss)
  output: string;
}

PingHost.Options

interface Options {
  count?: number;
  timeout?: number;
  packetSize?: number;
  extra?: string[];
}

PingHost.PollHostConfig

interface PollHostConfig {
  host: string;
  interval?: number; // ms, default 1000
}

IPScan.Discovered

type Discovered = Pick<PingHost.Response, 'host' | 'latency'>;

Requirements

• Node.js 22+
• On Linux, raw socket access may require running with sudo or granting cap_net_raw capabilities

License

ISC