0
# Node.js API
1

2
Core programmatic interface for waiting on resources with Promise and callback support. Provides comprehensive configuration options for timeouts, intervals, and resource-specific settings.
3

4
## Capabilities
5

6
### Main Function
7

8
The primary export that waits for resources to become available.
9

10
```javascript { .api }
11
/**
12
 * Wait for resources to become available before calling callback
13
 * 
14
 * Polls file, http(s), tcp ports, sockets for availability.
15
 * Resource types are distinguished by their prefix with default being 'file:'
16
 * 
17
 * @param opts - Configuration object
18
 * @param cb - Optional callback function with signature cb(err)
19
 * @returns Promise<void> when callback not provided, undefined otherwise
20
 */
21
function waitOn(opts, cb?): Promise<void> | void;
22
```
23

24
**Usage Examples:**
25

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

29
// Promise API
30
try {
31
  await waitOn({ resources: ['file:/tmp/myfile'] });
32
  console.log('File is available');
33
} catch (err) {
34
  console.error('Timeout or error:', err);
35
}
36

37
// Callback API
38
waitOn({ resources: ['tcp:3000'] }, (err) => {
39
  if (err) {
40
    console.error('TCP port not available:', err);
41
  } else {
42
    console.log('TCP port is listening');
43
  }
44
});
45
```
46

47
## Configuration Options
48

49
### Required Options
50

51
```javascript { .api }
52
interface RequiredOptions {
53
  /** Array of resource strings to wait for */
54
  resources: string[];
55
}
56
```
57

58
### Timing Options
59

60
Control polling behavior and timeouts.
61

62
```javascript { .api }
63
interface TimingOptions {
64
  /** Initial delay in ms before checking resources, default 0 */
65
  delay?: number;
66
  
67
  /** Poll resource interval in ms, default 250 */
68
  interval?: number;
69
  
70
  /** Overall timeout in ms, default Infinity. Aborts with error */
71
  timeout?: number;
72
  
73
  /** 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 */
74
  window?: number;
75
  
76
  /** HTTP HEAD/GET timeout in ms, default undefined */
77
  httpTimeout?: number;
78
  
79
  /** TCP connect timeout in ms, default 300 */
80
  tcpTimeout?: number;
81
}
82
```
83

84
**Usage Examples:**
85

86
```javascript
87
// Wait up to 30 seconds, checking every 2 seconds
88
await waitOn({
89
  resources: ['http://localhost:3000'],
90
  timeout: 30000,
91
  interval: 2000
92
});
93

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

101
### Behavior Options
102

103
Control logging and operation mode.
104

105
```javascript { .api }
106
interface BehaviorOptions {
107
  /** Enable logging to stdout, default false */
108
  log?: boolean;
109
  
110
  /** Enable debug logging, default false. Also enables log */
111
  verbose?: boolean;
112
  
113
  /** Reverse mode - wait for resources to become unavailable, default false */
114
  reverse?: boolean;
115
  
116
  /** Limit concurrent connections to a resource, default Infinity */
117
  simultaneous?: number;
118
}
119
```
120

121
**Usage Examples:**
122

123
```javascript
124
// Reverse mode - wait for service to shut down
125
await waitOn({
126
  resources: ['tcp:8080'],
127
  reverse: true,
128
  log: true
129
});
130

131
// Limit concurrent connections
132
await waitOn({
133
  resources: ['http://api.example.com/health'],
134
  simultaneous: 2
135
});
136
```
137

138
### HTTP/HTTPS Options
139

140
Configuration for HTTP resource monitoring.
141

142
```javascript { .api }
143
interface HttpOptions {
144
  /** Custom HTTP status validation function */
145
  validateStatus?: (status: number) => boolean;
146
  
147
  /** Certificate authority (string, Buffer, or array of strings/Buffers) */
148
  ca?: string | Buffer | (string | Buffer)[];
149
  
150
  /** Client certificate (string, Buffer, or array of strings/Buffers) */
151
  cert?: string | Buffer | (string | Buffer)[];
152
  
153
  /** Private key (string, Buffer, object, or array of strings/Buffers/objects) */
154
  key?: string | Buffer | object | (string | Buffer | object)[];
155
  
156
  /** Private key passphrase */
157
  passphrase?: string;
158
  
159
  /** Proxy configuration (false to disable, undefined for auto-detection from env vars, or proxy object) */
160
  proxy?: boolean | {
161
    host: string;
162
    port: number;
163
    auth?: {
164
      username: string;
165
      password: string;
166
    };
167
  };
168
  
169
  /** HTTP authentication */
170
  auth?: {
171
    username: string;
172
    password: string;
173
  };
174
  
175
  /** Strict SSL verification, default false */
176
  strictSSL?: boolean;
177
  
178
  /** Follow HTTP redirects, default true */
179
  followRedirect?: boolean;
180
  
181
  /** Custom HTTP headers */
182
  headers?: object;
183
}
184
```
185

186
**Usage Examples:**
187

188
```javascript
189
// Custom status validation
190
await waitOn({
191
  resources: ['http://localhost:3000/api'],
192
  validateStatus: (status) => status === 401 || (status >= 200 && status < 300)
193
});
194

195
// HTTP authentication
196
await waitOn({
197
  resources: ['https://api.example.com/secure'],
198
  auth: {
199
    username: 'admin',
200
    password: 'secret'
201
  },
202
  headers: {
203
    'User-Agent': 'wait-on/8.0.4'
204
  }
205
});
206

207
// SSL configuration
208
await waitOn({
209
  resources: ['https://self-signed.example.com'],
210
  strictSSL: false,
211
  ca: fs.readFileSync('./ca-cert.pem')
212
});
213
```
214

215
## Error Handling
216

217
wait-on throws or passes specific error types to callbacks:
218

219
**Timeout Errors:**
220
```javascript
221
try {
222
  await waitOn({
223
    resources: ['tcp:9999'],
224
    timeout: 5000
225
  });
226
} catch (err) {
227
  if (err.message.startsWith('Timed out waiting for')) {
228
    console.log('Timeout error:', err.message);
229
    // Example: "Timed out waiting for: tcp:9999"
230
  }
231
}
232
```
233

234
**Validation Errors:**
235
```javascript
236
try {
237
  await waitOn({ resources: [] }); // Empty resources array
238
} catch (err) {
239
  console.log('Validation error:', err.message);
240
  // Example: '"resources" does not contain 1 required value(s)'
241
}
242

243
try {
244
  await waitOn({}); // Missing resources property
245
} catch (err) {
246
  console.log('Validation error:', err.message);
247
  // Example: '"resources" is required'
248
}
249
```
250

251
## Complete Options Interface
252

253
```javascript { .api }
254
interface WaitOnOptions {
255
  // Required
256
  resources: string[];
257
  
258
  // Timing
259
  delay?: number;
260
  interval?: number;
261
  timeout?: number;
262
  window?: number;
263
  httpTimeout?: number;
264
  tcpTimeout?: number;
265
  
266
  // Behavior
267
  log?: boolean;
268
  verbose?: boolean;
269
  reverse?: boolean;
270
  simultaneous?: number;
271
  
272
  // HTTP/HTTPS
273
  validateStatus?: (status: number) => boolean;
274
  ca?: string | Buffer | (string | Buffer)[];
275
  cert?: string | Buffer | (string | Buffer)[];
276
  key?: string | Buffer | object | (string | Buffer | object)[];
277
  passphrase?: string;
278
  proxy?: boolean | {
279
    host: string;
280
    port: number;
281
    auth?: {
282
      username: string;
283
      password: string;
284
    };
285
  };
286
  auth?: {
287
    username: string;
288
    password: string;
289
  };
290
  strictSSL?: boolean;
291
  followRedirect?: boolean;
292
  headers?: object;
293
}
294
```