@uptime.link/detector

Documentation for @uptime.link/detector

readme.md for @uptime.link/detector

a detector for answering network questions locally. It does not rely on any online services.

Availabililty and Links

Installation

npm install @uptime.link/detector

Usage

Use TypeScript for best in class intellisense

Basic Port Detection

import { Detector } from '@uptime.link/detector';

const detector = new Detector();

// Check if a port is active (returns detailed result)
const result = await detector.isActive('https://example.com');
console.log(result.isActive); // true

// Simple boolean check (backward compatible)
const isActive = await detector.isActiveSimple('https://example.com');
console.log(isActive); // true

Service Type Detection

The detector can identify what service is running on a port:

// Detect service type along with port check
const result = await detector.isActive('https://github.com', {
  detectServiceType: true,
});

console.log(result.isActive); // true
console.log(result.serviceType); // 'https'

// Direct service type detection
const serviceType = await detector.detectType('ssh://github.com:22');
console.log(serviceType); // 'ssh'

Supported Service Types

The detector can identify the following services:

Advanced Examples

// Check localhost ports
const localResult = await detector.isActive('http://localhost:3000', {
  detectServiceType: true,
});

if (localResult.isActive) {
  console.log(`Local service detected: ${localResult.serviceType}`);
}

// Check multiple services
const urls = ['https://api.github.com', 'http://example.com', 'ssh://gitlab.com:22'];

for (const url of urls) {
  const result = await detector.isActive(url, { detectServiceType: true });
  console.log(`${url}: ${result.isActive ? result.serviceType : 'offline'}`);
}

// Handle different URL schemes with automatic port detection
const sshDetection = await detector.detectType('ssh://github.com');
// Automatically uses port 22 for SSH

const mysqlDetection = await detector.detectType('mysql://localhost');
// Automatically uses port 3306 for MySQL

API Reference

Detector

The main class for network detection.

Methods

Interfaces

interface IDetectorResult {
  isActive: boolean;
  serviceType?: ServiceType;
  protocol?: 'tcp' | 'udp';
  responseTime?: number;
  tlsVersion?: string;
  serviceBanner?: string;
  error?: string;
}

interface IDetectorOptions {
  timeout?: number;
  includeNetworkDiagnostics?: boolean;
  detectServiceType?: boolean;
}

enum ServiceType {
  HTTP = 'http',
  HTTPS = 'https',
  SSH = 'ssh',
  FTP = 'ftp',
  SMTP = 'smtp',
  POP3 = 'pop3',
  IMAP = 'imap',
  MYSQL = 'mysql',
  POSTGRESQL = 'postgresql',
  MONGODB = 'mongodb',
  REDIS = 'redis',
  UNKNOWN = 'unknown',
}

Features

Contribution

We are always happy for code contributions. If you are not the code contributing type that is ok. Still, maintaining Open Source repositories takes considerable time and thought. If you like the quality of what we do and our modules are useful to you we would appreciate a little monthly contribution: You can contribute one time or contribute monthly. :)

For further information read the linked docs at the top of this readme.

MIT licensed | © Lossless GmbH | By using this npm module you agree to our privacy policy

repo-footer

changelog.md for @uptime.link/detector

2025-05-26 - 2.1.2 - fix(documentation)

Improve documentation formatting and code consistency across project files

2025-05-26 - 2.1.1 - fix(detector)

Improve test coverage and adjust detection result handling

2025-05-26 - 2.1.0 - feat(detector)

Enhance port detection and service fingerprinting with improved HTTP/HTTPS and SSH checks, update test scripts for verbose output, and revise documentation with new hints and a detailed improvement plan.

2025-05-26 - 2.0.2 - fix(ci)

Update CI workflows, dependency paths, and project configuration

2022-07-16 - 2.0.1 - no significant changes

This release was a version update only and did not include any relevant changes.

2022-07-16 - 2.0.0 - core

fix(core): update

2022-07-16 - 1.0.5 - core

BREAKING CHANGE(core): switch to esm

2022-07-16 - 1.0.4 - core

fix(core): update

2021-04-14 - 1.0.3 - core

fix(core): update

2021-04-13 - 1.0.2 - core

fix(core): update

2021-04-12 - 1.0.1 - core

fix(core): update

Other releases that were simple version bumps have been omitted from detailed descriptions.