0
# wait-on
1

2
wait-on is a cross-platform command line utility and Node.js API which will wait for files, ports, sockets, and http(s) resources to become available. It provides both a command line interface and programmatic Node.js API with extensive configuration options for monitoring various resource types with customizable timeouts, intervals, and retry logic.
3

4
## Package Information
5

6
- **Package Name**: wait-on
7
- **Package Type**: npm
8
- **Language**: JavaScript (CommonJS)
9
- **Installation**: `npm install wait-on`
10
- **Node.js Version**: 12.0.0+
11

12
## Core Imports
13

14
```javascript
15
const waitOn = require('wait-on');
16
```
17

18
For ES modules:
19
```javascript
20
import waitOn from 'wait-on';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const waitOn = require('wait-on');
27

28
// Simple file waiting
29
await waitOn({ resources: ['file:/path/to/file'] });
30

31
// Wait for HTTP endpoints
32
await waitOn({ 
33
  resources: ['http://localhost:3000', 'https://api.example.com/health'] 
34
});
35

36
// Wait for multiple resource types
37
await waitOn({
38
  resources: [
39
    'file:/tmp/app.log',
40
    'tcp:localhost:3000',
41
    'http://localhost:3000/health'
42
  ],
43
  timeout: 30000,
44
  interval: 1000
45
});
46

47
// Using callback style
48
waitOn({
49
  resources: ['http://localhost:8080']
50
}, (err) => {
51
  if (err) {
52
    console.error('Resource failed to become available:', err);
53
  } else {
54
    console.log('Resources are now available!');
55
  }
56
});
57
```
58

59
## Architecture
60

61
wait-on is built around several key components:
62

63
- **Resource Monitoring**: Supports file, HTTP/HTTPS, TCP port, and Unix socket monitoring
64
- **Observable Streams**: Uses RxJS for reactive resource polling and state management
65
- **Timeout Management**: Configurable timeout handling with detailed error reporting
66
- **Cross-platform**: Runs on Linux, Unix, macOS, and Windows
67
- **Reverse Mode**: Can wait for resources to become unavailable
68
- **CLI Interface**: Command-line wrapper with full feature parity
69

70
## Capabilities
71

72
### Node.js API
73

74
Core programmatic interface for waiting on resources with Promise and callback support. Includes comprehensive configuration options for timeouts, intervals, and HTTP-specific settings.
75

76
```javascript { .api }
77
/**
78
 * Wait for resources to become available
79
 * @param opts - Configuration options
80
 * @param cb - Optional callback function (err) => void
81
 * @returns Promise<void> when cb not provided
82
 */
83
function waitOn(opts, cb?): Promise<void> | void;
84
```
85

86
[Node.js API](./api.md)
87

88
### Command Line Interface
89

90
Command-line utility with full access to all wait-on functionality through CLI arguments and configuration files. Supports time interval parsing and environment-specific options.
91

92
```bash
93
wait-on [options] resource1 [resource2 ...]
94
```
95

96
[Command Line Interface](./cli.md)
97

98
### Resource Types
99

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

102
```javascript { .api }
103
// File resources (default)
104
'file:/path/to/file'
105
'/path/to/file'
106

107
// HTTP resources  
108
'http://hostname:port/path'
109
'https://hostname:port/path'
110
'http-get://hostname:port/path'
111
'https-get://hostname:port/path'
112

113
// TCP port resources
114
'tcp:hostname:port'
115
'tcp:port'  // defaults to localhost
116

117
// Unix socket resources
118
'socket:/path/to/socket'
119

120
// HTTP over Unix socket
121
'http://unix:/path/to/socket:/url/path'
122
'http-get://unix:/path/to/socket:/url/path'
123
```
124

125
[Resource Types](./resources.md)
126

127
## Types
128

129
```javascript { .api }
130
interface WaitOnOptions {
131
  resources: string[];
132
  delay?: number;
133
  httpTimeout?: number;
134
  interval?: number;
135
  log?: boolean;
136
  reverse?: boolean;
137
  simultaneous?: number;
138
  timeout?: number;
139
  validateStatus?: (status: number) => boolean;
140
  verbose?: boolean;
141
  window?: number;
142
  tcpTimeout?: number;
143
  
144
  // HTTP/HTTPS options
145
  ca?: string | Buffer | (string | Buffer)[];
146
  cert?: string | Buffer | (string | Buffer)[];
147
  key?: string | Buffer | object | (string | Buffer | object)[];
148
  passphrase?: string;
149
  proxy?: boolean | {
150
    host: string;
151
    port: number;
152
    auth?: {
153
      username: string;
154
      password: string;
155
    };
156
  };
157
  auth?: {
158
    username: string;
159
    password: string;
160
  };
161
  strictSSL?: boolean;
162
  followRedirect?: boolean;
163
  headers?: object;
164
}
165
```