tessl/npm-wait-on

Cross-platform command line utility and Node.js API which will wait for files, ports, sockets, and http(s) resources to become available

—

Pending

Overview

Eval results

Files

Resource Types

Name: tessl/npm-wait-on
Author: tessl

Support for multiple resource types including files, HTTP endpoints, TCP ports, and Unix domain sockets. Each resource type has specific behavior and configuration options.

Capabilities

File Resources

Monitor file system resources for existence and stability.

// File resource formats
'file:/path/to/file'      // Explicit file prefix
'/path/to/file'           // Default type (no prefix)
'./relative/path'         // Relative paths supported
'file:C:\\path\\file.txt' // Windows paths

Behavior:

Waits for file to exist and size to stabilize
Uses window option for stability checking (default 750ms)
In reverse mode, waits for file to not exist
Monitors file size changes over the stability window

Usage Examples:

// Wait for log file to be created and stabilize
await waitOn({
  resources: ['file:/var/log/app.log'],
  window: 2000  // Wait 2 seconds for size stability
});

// Wait for multiple files
await waitOn({
  resources: [
    '/tmp/ready.flag',
    'file:/data/output.json',
    './build/bundle.js'
  ]
});

// Reverse mode - wait for temporary file to be removed
await waitOn({
  resources: ['file:/tmp/lock.pid'],
  reverse: true
});

HTTP/HTTPS Resources

Monitor HTTP endpoints for successful responses.

// HTTP resource formats
'http://hostname:port/path'        // HTTP HEAD request (default)
'https://hostname:port/path'       // HTTPS HEAD request  
'http-get://hostname:port/path'    // HTTP GET request
'https-get://hostname:port/path'   // HTTPS GET request

Behavior:

HEAD requests by default, GET requests with -get suffix
Expects 2XX response codes (customizable with validateStatus)
Follows redirects by default (controlled by followRedirect)
Supports authentication, custom headers, SSL options
Uses httpTimeout for individual request timeout

Usage Examples:

// Basic HTTP health check
await waitOn({
  resources: ['http://localhost:3000/health']
});

// HTTPS with custom validation
await waitOn({
  resources: ['https://api.example.com/status'],
  validateStatus: (status) => status === 503 || (status >= 200 && status < 300),
  strictSSL: false
});

// HTTP GET request with authentication
await waitOn({
  resources: ['http-get://api.internal.com/ready'],
  auth: {
    username: 'monitor',
    password: 'secret'
  },
  headers: {
    'User-Agent': 'HealthCheck/1.0'
  }
});

// Multiple endpoints with timeout
await waitOn({
  resources: [
    'https://service1.com/health',
    'https://service2.com/health',
    'http://localhost:8080/ready'
  ],
  httpTimeout: 5000,
  simultaneous: 2
});

TCP Port Resources

Monitor TCP ports for active listeners.

// TCP resource formats
'tcp:hostname:port'    // Specific host and port
'tcp:port'             // Port on localhost
'tcp:localhost:port'   // Explicit localhost
'tcp:127.0.0.1:port'   // IP address

Behavior:

Attempts TCP connection to specified host:port
Uses tcpTimeout for connection timeout (default 300ms)
Success when connection established (immediately closed)
Supports both hostnames and IP addresses
Defaults to localhost when host omitted

Usage Examples:

// Wait for database
await waitOn({
  resources: ['tcp:localhost:5432'],
  tcpTimeout: 1000
});

// Multiple services with different hosts
await waitOn({
  resources: [
    'tcp:redis:6379',
    'tcp:postgres:5432', 
    'tcp:elasticsearch:9200'
  ]
});

// Local development ports
await waitOn({
  resources: [
    'tcp:3000',  // Web server
    'tcp:3001',  // API server
    'tcp:9229'   // Debug port
  ]
});

// Wait for service to stop listening (reverse mode)
await waitOn({
  resources: ['tcp:8080'],
  reverse: true,
  timeout: 10000
});

Unix Socket Resources

Monitor Unix domain socket files for active listeners.

// Socket resource format
'socket:/path/to/socket'       // Unix domain socket
'socket:/var/run/app.sock'     // Typical socket location
'socket:./relative/socket'     // Relative path

Behavior:

Attempts connection to Unix domain socket
Success when connection established (immediately closed)
Works only on Unix-like systems (Linux, macOS)
Socket file must exist and be accepting connections

Usage Examples:

// Wait for application socket
await waitOn({
  resources: ['socket:/var/run/myapp.sock']
});

// Multiple socket services
await waitOn({
  resources: [
    'socket:/tmp/redis.sock',
    'socket:/var/lib/mysql/mysql.sock'
  ]
});

// Development socket
await waitOn({
  resources: ['socket:./tmp/dev.sock'],
  timeout: 15000
});

HTTP over Unix Socket

Special format for HTTP requests over Unix domain sockets.

// HTTP over Unix socket formats
'http://unix:/path/to/socket:/url/path'      // HTTP HEAD over socket
'http-get://unix:/path/to/socket:/url/path'  // HTTP GET over socket
'https://unix:/path/to/socket:/url/path'     // HTTPS over socket (rare)

Behavior:

Makes HTTP request over Unix domain socket
Socket path and URL path are separated by colons
Supports all HTTP options (headers, auth, etc.)
Useful for containerized applications

Usage Examples:

// Docker daemon API
await waitOn({
  resources: ['http://unix:/var/run/docker.sock:/version']
});

// Application health check over socket
await waitOn({
  resources: ['http-get://unix:/tmp/app.sock:/health'],
  headers: {
    'Host': 'localhost'
  }
});

// Multiple socket endpoints
await waitOn({
  resources: [
    'http://unix:/var/run/app.sock:/status',
    'http://unix:/tmp/worker.sock:/health'
  ]
});

Resource Prefix Detection

wait-on automatically detects resource types based on prefixes:

// Prefix detection rules
'file:'      → File resource
'http:'      → HTTP HEAD resource  
'https:'     → HTTPS HEAD resource
'http-get:'  → HTTP GET resource
'https-get:' → HTTPS GET resource
'tcp:'       → TCP port resource
'socket:'    → Unix socket resource
(no prefix)  → File resource (default)

Cross-Platform Considerations

// Platform compatibility
'file:'    → All platforms (Windows, macOS, Linux)
'http:'    → All platforms
'https:'   → All platforms  
'tcp:'     → All platforms
'socket:'  → Unix-like only (Linux, macOS)

Usage Examples:

// Cross-platform file waiting
const isWindows = process.platform === 'win32';
const configFile = isWindows 
  ? 'C:\\app\\config.json'
  : '/etc/app/config.json';

await waitOn({
  resources: [`file:${configFile}`]
});

// Multi-platform service detection
await waitOn({
  resources: [
    'tcp:3306',                    // MySQL (all platforms)
    'tcp:5432',                    // PostgreSQL (all platforms)
    ...(isWindows ? [] : ['socket:/tmp/redis.sock'])  // Redis socket (Unix only)
  ]
});

Install with Tessl CLI