package
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
npm install wait-onGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
kevinold
kevinold@gmail.com
wait-on is a cross-platform command line utility which will wait for files, ports, sockets, and http(s) resources to become available (or not available using reverse mode). Functionality is also available via a Node.js API. Cross-platform - runs everywhere Node.js runs (linux, unix, mac OS X, windows)
wait-on will wait for period of time for a file to stop growing before triggering availability which is good for monitoring files that are being built. Likewise wait-on will wait for period of time for other resources to remain available before triggering success.
For http(s) resources wait-on will check that the requests return a 2XX (success) status (after following any redirects); use --status-codes to accept other statuses, e.g. --status-codes 200-499 for a server whose probe path answers 404. The http: and https: prefixes send an HTTP HEAD request; the http-get: and https-get: prefixes send an HTTP GET request. Use the -get: forms when a server does not implement HEAD (many respond 404/405 to HEAD), or when success depends on the response body.
wait-on can also be used in reverse mode which waits for resources to NOT be available. This is useful in waiting for services to shutdown before continuing. (Thanks @skarbovskiy for adding this feature)
wait-on supports the Node.js versions that are active or in maintenance. See the list here: https://nodejs.org/en/about/releases/
npm install wait-on # local version
OR
npm install -g wait-on # global versionUse from command line or using Node.js programmatic API.
Assuming NEXT_CMD is the command to run when resources are available, then wait-on will wait and then exit with a successful exit code (0) once all resources are available, causing NEXT_CMD to be run.
wait-on can also be used in reverse mode, which waits for resources to NOT be available. This is useful in waiting for services to shutdown before continuing. (Thanks @skarbovskiy for adding)
If wait-on is interrupted before all resources are available, it will exit with a non-zero exit code and thus NEXT_CMD will not be run.
wait-on file1 && NEXT_CMD # wait for file1, then exec NEXT_CMD
wait-on f1 f2 && NEXT_CMD # wait for both f1 and f2, the exec NEXT_CMD
wait-on http://localhost:8000/foo && NEXT_CMD # wait for http 2XX HEAD
wait-on https://myserver/foo && NEXT_CMD # wait for https 2XX HEAD
wait-on http-get://localhost:8000/foo && NEXT_CMD # wait for http 2XX GET
wait-on https-get://myserver/foo && NEXT_CMD # wait for https 2XX GET
wait-on tcp:4000 && NEXT_CMD # wait for service to listen on a TCP port
wait-on socket:/path/mysock # wait for service to listen on domain socket
wait-on http://unix:/var/SOCKPATH:http://server/a/foo # wait for http HEAD on domain socket
wait-on http-get://unix:/var/SOCKPATH:http://server/a/foo # wait for http GET on domain socket
wait-on command:./health-check.shUsage: wait-on {OPTIONS} resource [...resource]
Description:
wait-on is a command line utility which will wait for files, ports,
sockets, and http(s) resources to become available (or not available
using reverse flag). Exits with success code (0) when all resources
are ready. Non-zero exit code if interrupted or timed out.
Options may also be specified in a config file (js or json). For
example --config configFile.js would result in configFile.js being
required and the resulting object will be merged with any
command line options before wait-on is called. See exampleConfig.js
In shell combine with && to conditionally run another command
once resources are available. ex: wait-on f1 && NEXT_CMD
resources types are defined by their prefix, if no prefix is
present, the resource is assumed to be of type 'file'. Resources
can also be provided in the config file.
resource prefixes are:
file: - regular file (also default type). ex: file:/path/to/file
http: - HTTP HEAD returns 2XX response. ex: http://m.com:90/foo
https: - HTTPS HEAD returns 2XX response. ex: https://my/bar
http-get: - HTTP GET returns 2XX response. ex: http-get://m.com:90/foo
https-get: - HTTPS GET returns 2XX response. ex: https-get://my/bar
tcp: - TCP port is listening. ex: 1.2.3.4:9000 or foo.com:700
var waitOn = require('wait-on');
var opts = {
resources: [
'file1',
'http://foo.com:8000/bar',
'https://my.com/cat',
'http-get://foo.com:8000/bar',
'https-get://my.com/cat',
'tcp:foo.com:8000',
'socket:/my/sock',
'http://unix:/my/sock:http://server/my/url',
'http-get://unix:/my/sock:http://server/my/url'
],
delay: 1000, // initial delay in ms, default 0
interval: 100, // poll interval in ms, default 250ms
simultaneous: 1, // limit to 1 connection per resource at a time
timeout: 30000, // timeout in ms, default Infinity
tcpTimeout:
waitOn(opts, [cb]) - function which triggers resource checks
opts.resources - array of string resources to wait for. prefix determines the type of resource with the default type of file:
opts.delay - optional initial delay in ms, default 0
opts.interval - optional poll resource interval in ms, default 250ms
opts.log - optional flag which outputs to stdout, remaining resources waited on and when complete or errored
opts.resources - optional array of string resources to wait for if none are specified via command line
opts.reverse - optional flag to reverse operation so checks are for resources being NOT available, default false
opts.simultaneous - optional count to limit concurrent connections per resource at a time, setting to 1 waits for previous connection to succeed, fail, or timeout before sending another, default infinity
opts.timeout - optional timeout in ms, default Infinity. Aborts with error.
opts.tcpTimeout - optional tcp timeout in ms, default 300ms
opts.commandTimeout - optional per-attempt timeout in ms for command: resources. A command still running at this bound is killed and the next poll retries. Default 0 (no limit). A command: resource never runs more than one process at a time regardless of simultaneous.
opts.verbose - optional flag which outputs debug output, default false
opts.window - optional stabilization time in ms, default 750ms. Waits this amount of time for file sizes to stabilize or other resource availability to remain unchanged.
http(s) specific options, see https://nodejs.org/api/tls.html#tls_tls_connect_options_callback for specific details
// example proxy object
{
host: '127.0.0.1',
port: 9000,
auth: {
username: 'mikeymike',
password: 'rapunz3l'
}
}opts.auth: { user, pass }
opts.strictSSL: optional flag, when false (the default) invalid or self-signed certificates are accepted; set true to reject them
opts.followRedirect: false, // defaults to true
opts.headers: { 'x-custom': 'headers' }, also settable from the CLI with the repeatable -H, --header "Name: value" flag (CLI headers win over config-file headers on a name conflict)
opts.validateStatus: optional function (status) => boolean deciding which HTTP status codes count as success, default accepts 2XX. Because it is a function it can only be set via the Node API or a .js config file, not a JSON config. From the CLI, --status-codes 200-499 (a code, a range, or a comma-separated list) sets it and overrides a config-file validateStatus.
cb(err) - if err is provided then, resource checks did not succeed
On Node.js 20+ localhost resolves to both IPv4 and IPv6 and wait-on connects to whichever address the service is actually listening on, because Node enables autoSelectFamily (Happy Eyeballs) by default. On older Node.js versions localhost may resolve to ::1 (IPv6) only, so a service bound to 127.0.0.1 (IPv4) can appear unavailable. If that happens, use 127.0.0.1 explicitly or upgrade to Node.js 20+.
I frequently need to wait on build tasks to complete or services to be available before starting next command, so this project makes that easier and is portable to everywhere Node.js runs.
If you have input or ideas or would like to get involved, you may: