Node.js API

/**
 * Wait for resources to become available before calling callback
 * 
 * Polls file, http(s), tcp ports, sockets for availability.
 * Resource types are distinguished by their prefix with default being 'file:'
 * 
 * @param opts - Configuration object
 * @param cb - Optional callback function with signature cb(err)
 * @returns Promise<void> when callback not provided, undefined otherwise
 */
function waitOn(opts, cb?): Promise<void> | void;

const waitOn = require('wait-on');

// Promise API
try {
  await waitOn({ resources: ['file:/tmp/myfile'] });
  console.log('File is available');
} catch (err) {
  console.error('Timeout or error:', err);
}

// Callback API
waitOn({ resources: ['tcp:3000'] }, (err) => {
  if (err) {
    console.error('TCP port not available:', err);
  } else {
    console.log('TCP port is listening');
  }
});

interface RequiredOptions {
  /** Array of resource strings to wait for */
  resources: string[];
}

interface TimingOptions {
  /** Initial delay in ms before checking resources, default 0 */
  delay?: number;
  
  /** Poll resource interval in ms, default 250 */
  interval?: number;
  
  /** Overall timeout in ms, default Infinity. Aborts with error */
  timeout?: number;
  
  /** Stabilization time in ms, default 750. Waits this amount of time for file sizes to stabilize. If less than interval, it will be reset to the value of interval */
  window?: number;
  
  /** HTTP HEAD/GET timeout in ms, default undefined */
  httpTimeout?: number;
  
  /** TCP connect timeout in ms, default 300 */
  tcpTimeout?: number;
}

// Wait up to 30 seconds, checking every 2 seconds
await waitOn({
  resources: ['http://localhost:3000'],
  timeout: 30000,
  interval: 2000
});

// Wait for file with stability window
await waitOn({
  resources: ['file:/tmp/output.log'],
  window: 1000  // File size must be stable for 1 second
});

interface BehaviorOptions {
  /** Enable logging to stdout, default false */
  log?: boolean;
  
  /** Enable debug logging, default false. Also enables log */
  verbose?: boolean;
  
  /** Reverse mode - wait for resources to become unavailable, default false */
  reverse?: boolean;
  
  /** Limit concurrent connections to a resource, default Infinity */
  simultaneous?: number;
}

// Reverse mode - wait for service to shut down
await waitOn({
  resources: ['tcp:8080'],
  reverse: true,
  log: true
});

// Limit concurrent connections
await waitOn({
  resources: ['http://api.example.com/health'],
  simultaneous: 2
});

interface HttpOptions {
  /** Custom HTTP status validation function */
  validateStatus?: (status: number) => boolean;
  
  /** Certificate authority (string, Buffer, or array of strings/Buffers) */
  ca?: string | Buffer | (string | Buffer)[];
  
  /** Client certificate (string, Buffer, or array of strings/Buffers) */
  cert?: string | Buffer | (string | Buffer)[];
  
  /** Private key (string, Buffer, object, or array of strings/Buffers/objects) */
  key?: string | Buffer | object | (string | Buffer | object)[];
  
  /** Private key passphrase */
  passphrase?: string;
  
  /** Proxy configuration (false to disable, undefined for auto-detection from env vars, or proxy object) */
  proxy?: boolean | {
    host: string;
    port: number;
    auth?: {
      username: string;
      password: string;
    };
  };
  
  /** HTTP authentication */
  auth?: {
    username: string;
    password: string;
  };
  
  /** Strict SSL verification, default false */
  strictSSL?: boolean;
  
  /** Follow HTTP redirects, default true */
  followRedirect?: boolean;
  
  /** Custom HTTP headers */
  headers?: object;
}

// Custom status validation
await waitOn({
  resources: ['http://localhost:3000/api'],
  validateStatus: (status) => status === 401 || (status >= 200 && status < 300)
});

// HTTP authentication
await waitOn({
  resources: ['https://api.example.com/secure'],
  auth: {
    username: 'admin',
    password: 'secret'
  },
  headers: {
    'User-Agent': 'wait-on/8.0.4'
  }
});

// SSL configuration
await waitOn({
  resources: ['https://self-signed.example.com'],
  strictSSL: false,
  ca: fs.readFileSync('./ca-cert.pem')
});

try {
  await waitOn({
    resources: ['tcp:9999'],
    timeout: 5000
  });
} catch (err) {
  if (err.message.startsWith('Timed out waiting for')) {
    console.log('Timeout error:', err.message);
    // Example: "Timed out waiting for: tcp:9999"
  }
}

try {
  await waitOn({ resources: [] }); // Empty resources array
} catch (err) {
  console.log('Validation error:', err.message);
  // Example: '"resources" does not contain 1 required value(s)'
}

try {
  await waitOn({}); // Missing resources property
} catch (err) {
  console.log('Validation error:', err.message);
  // Example: '"resources" is required'
}

interface WaitOnOptions {
  // Required
  resources: string[];
  
  // Timing
  delay?: number;
  interval?: number;
  timeout?: number;
  window?: number;
  httpTimeout?: number;
  tcpTimeout?: number;
  
  // Behavior
  log?: boolean;
  verbose?: boolean;
  reverse?: boolean;
  simultaneous?: number;
  
  // HTTP/HTTPS
  validateStatus?: (status: number) => boolean;
  ca?: string | Buffer | (string | Buffer)[];
  cert?: string | Buffer | (string | Buffer)[];
  key?: string | Buffer | object | (string | Buffer | object)[];
  passphrase?: string;
  proxy?: boolean | {
    host: string;
    port: number;
    auth?: {
      username: string;
      password: string;
    };
  };
  auth?: {
    username: string;
    password: string;
  };
  strictSSL?: boolean;
  followRedirect?: boolean;
  headers?: object;
}