diff --git a/index.d.ts b/index.d.ts index 92ceccd..3ede336 100644 --- a/index.d.ts +++ b/index.d.ts @@ -1,31 +1,65 @@ -export interface Options { - /** - * A preferred port or an iterable of preferred ports to use. - */ - readonly port?: number | Iterable, +/// +import {Omit} from 'type-fest'; +import {ListenOptions} from 'net'; - /** - * The host on which port resolution should be performed. Can be either an IPv4 or IPv6 address. - */ - readonly host?: string; +declare namespace getPort { + interface Options extends Omit { + /** + A preferred port or an iterable of preferred ports to use. + */ + readonly port?: number | Iterable; + + /** + The host on which port resolution should be performed. Can be either an IPv4 or IPv6 address. + */ + readonly host?: string; + } } declare const getPort: { - /** - * Get an available TCP port number. - * - * @returns Port number. - */ - (options?: Options): Promise; - - /** - * Make a range of ports `from...to`. - * - * @param from - First port of the range. Must be in the range `1024...65535`. - * @param to - Last port of the range. Must be in the range `1024...65535` and must be greater than `from`. - * @returns The ports in the range. - */ - makeRange(from: number, to: number): Iterable; -} + /** + Get an available TCP port number. + + @returns Port number. + + @example + ``` + import getPort = require('get-port'); + + (async () => { + console.log(await getPort()); + //=> 51402 + + // Pass in a preferred port + console.log(await getPort({port: 3000})); + // Will use 3000 if available, otherwise fall back to a random port + + // Pass in an array of preferred ports + console.log(await getPort({port: [3000, 3001, 3002]})); + // Will use any element in the preferred ports array if available, otherwise fall back to a random port + })(); + ``` + */ + (options?: getPort.Options): Promise; + + /** + Make a range of ports `from`...`to`. + + @param from - First port of the range. Must be in the range `1024`...`65535`. + @param to - Last port of the range. Must be in the range `1024`...`65535` and must be greater than `from`. + @returns The ports in the range. + + @example + ``` + import getPort = require('get-port'); + + (async () => { + console.log(await getPort({port: getPort.makeRange(3000, 3100)})); + // Will use any port from 3000 to 3100, otherwise fall back to a random port + })(); + ``` + */ + makeRange(from: number, to: number): Iterable; +}; -export default getPort; +export = getPort; diff --git a/index.js b/index.js index 3352dc4..7451574 100644 --- a/index.js +++ b/index.js @@ -66,5 +66,3 @@ module.exports.makeRange = (from, to) => { return generator(from, to); }; - -module.exports.default = module.exports; diff --git a/index.test-d.ts b/index.test-d.ts index 0cbf934..f72bc46 100644 --- a/index.test-d.ts +++ b/index.test-d.ts @@ -1,9 +1,9 @@ -import {expectType} from 'tsd-check'; -import getPort from '.'; - -expectType(await getPort()); -expectType(await getPort({port: 3000})); -expectType(await getPort({port: [3000, 3001, 3002]})); -expectType(await getPort({host: 'https://localhost'})); +import {expectType} from 'tsd'; +import getPort = require('.'); +expectType>(getPort()); +expectType>(getPort({port: 3000})); +expectType>(getPort({port: [3000, 3001, 3002]})); +expectType>(getPort({host: 'https://localhost'})); +expectType>(getPort({ipv6Only: true})); expectType>(getPort.makeRange(1024, 1025)); diff --git a/package.json b/package.json index 08e7e95..83e9317 100644 --- a/package.json +++ b/package.json @@ -13,7 +13,7 @@ "node": ">=8" }, "scripts": { - "test": "xo && ava && tsd-check" + "test": "xo && ava && tsd" }, "files": [ "index.js", @@ -36,10 +36,13 @@ "preferred", "chosen" ], + "dependencies": { + "type-fest": "^0.3.0" + }, "devDependencies": { - "ava": "^1.2.1", - "pify": "^3.0.0", - "tsd-check": "^0.3.0", + "@types/node": "^11.13.0", + "ava": "^1.4.1", + "tsd": "^0.7.2", "xo": "^0.24.0" } } diff --git a/readme.md b/readme.md index c4b9a8f..d11b501 100644 --- a/readme.md +++ b/readme.md @@ -43,8 +43,8 @@ Use the `makeRange()` helper in case you need a port in a certain range: ```js (async () => { - console.log(await getPort({port: getPort.makeRange(3000, 3100)})); - // Will use any port from 3000 to 3100, otherwise fall back to a random port + console.log(await getPort({port: getPort.makeRange(3000, 3100)})); + // Will use any port from 3000 to 3100, otherwise fall back to a random port })(); ``` @@ -72,7 +72,7 @@ The host on which port resolution should be performed. Can be either an IPv4 or ### getPort.makeRange(from, to) -Make a range of ports `from...to`. +Make a range of ports `from`...`to`. Returns an `Iterable` for ports in the given range. @@ -80,13 +80,13 @@ Returns an `Iterable` for ports in the given range. Type: `number` -First port of the range. Must be in the range `1024...65535`. +First port of the range. Must be in the range `1024`...`65535`. #### to Type: `number` -Last port of the range. Must be in the range `1024...65535` and must be greater than `from`. +Last port of the range. Must be in the range `1024`...`65535` and must be greater than `from`. ## Beware diff --git a/test.js b/test.js index fbe2835..65f4ab7 100644 --- a/test.js +++ b/test.js @@ -1,6 +1,6 @@ +import {promisify} from 'util'; import net from 'net'; import test from 'ava'; -import pify from 'pify'; import getPort from '.'; test('port can be bound when promise resolves', async t => { @@ -9,7 +9,7 @@ test('port can be bound when promise resolves', async t => { t.true(port > 0); const server = net.createServer(); - await pify(server.listen.bind(server))(port); + await promisify(server.listen.bind(server))(port); t.is(server.address().port, port); }); @@ -24,7 +24,7 @@ test('preferred port', async t => { test('preferred port unavailable', async t => { const desiredPort = 8282; const server = net.createServer(); - await pify(server.listen.bind(server))(desiredPort); + await promisify(server.listen.bind(server))(desiredPort); const port = await getPort({port: desiredPort}); t.is(typeof port, 'number'); @@ -38,7 +38,7 @@ test('port can be bound to IPv4 host when promise resolves', async t => { t.true(port > 0); const server = net.createServer(); - await pify(server.listen.bind(server))(port, '0.0.0.0'); + await promisify(server.listen.bind(server))(port, '0.0.0.0'); t.is(server.address().port, port); }); @@ -67,7 +67,7 @@ test('first port in preferred ports array is unavailable', async t => { const desiredPorts = [9090, 9091]; const server = net.createServer(); - await pify(server.listen.bind(server))(desiredPorts[0]); + await promisify(server.listen.bind(server))(desiredPorts[0]); const port = await getPort({ port: desiredPorts @@ -80,9 +80,9 @@ test('all preferred ports in array are unavailable', async t => { const desiredPorts = [9990, 9991]; const server1 = net.createServer(); - await pify(server1.listen.bind(server1))(desiredPorts[0]); + await promisify(server1.listen.bind(server1))(desiredPorts[0]); const server2 = net.createServer(); - await pify(server2.listen.bind(server2))(desiredPorts[1]); + await promisify(server2.listen.bind(server2))(desiredPorts[1]); const port = await getPort({ port: desiredPorts