node-await-server/README.md

await-server

Waits for a TCP server of some kind to become available, using Promises. Useful for things like build tooling and testing scripts.

Currently you can only watch ports on localhost - this is unlikely to change, since hammering a server with repeated connection attempts over the network is not generally appreciated :)

Be aware that this library will keep polling constantly, and there is no limit to its attempts. You should therefore only ever use it in scenarios where you're certain that the server will come online at some point, such as buildscripts.

License

WTFPL or CC0, whichever you prefer. A donation and/or attribution are appreciated, but not required.

Donate

Maintaining open-source projects takes a lot of time, and the more donations I receive, the more time I can dedicate to open-source. If this module is useful to you, consider making a donation!

You can donate using Bitcoin, PayPal, Flattr, cash-in-mail, SEPA transfers, and pretty much anything else. Thank you!

Contributing

Pull requests welcome. Please make sure your modifications are in line with the overall code style, and ensure that you're editing the files in src/, not those in lib/.

Build tool of choice is gulp; simply run gulp while developing, and it will watch for changes.

Be aware that by making a pull request, you agree to release your modifications under the licenses stated above.

Usage

A simple usage example:

const Promise = require("bluebird");
const awaitServer = require("await-server");

Promise.try(() => {
	return awaitServer(3000);
}).then(() => {
	console.log("Server has started!");
});

By default, this library uses a timeout of 50ms, which translates to roughly 20 polling attempts per second.

If you want to specify a custom timeout - for example, to reduce attempts per second or to get a faster response time, you can do so:

const Promise = require("bluebird");
const awaitServer = require("await-server");

Promise.try(() => {
	return awaitServer(3000, {
		timeout: 300 // in milliseconds
	});
}).then(() => {
	console.log("Server has started!");
});

API

awaitServer(port, [options])

Returns a Promise, that resolves when a TCP server comes online on the specified port.

• port: The port to check.
• options: Optional.
  • timeout: Defaults to 50. The timeout in milliseconds for each connection attempt. Setting this too low may result in never detecting the server coming online.