1 | # get-port [![Build Status](https://travis-ci.org/sindresorhus/get-port.svg?branch=master)](https://travis-ci.org/sindresorhus/get-port)
|
2 |
|
3 | > Get an available [TCP port](https://en.wikipedia.org/wiki/Port_(computer_networking))
|
4 |
|
5 | ## Install
|
6 |
|
7 | ```
|
8 | $ npm install get-port
|
9 | ```
|
10 |
|
11 | ## Usage
|
12 |
|
13 | ```js
|
14 | const getPort = require('get-port');
|
15 |
|
16 | (async () => {
|
17 | console.log(await getPort());
|
18 | //=> 51402
|
19 | })();
|
20 | ```
|
21 |
|
22 | Pass in a preferred port:
|
23 |
|
24 | ```js
|
25 | (async () => {
|
26 | console.log(await getPort({port: 3000}));
|
27 | // Will use 3000 if available, otherwise fall back to a random port
|
28 | })();
|
29 | ```
|
30 |
|
31 | Pass in an array of preferred ports:
|
32 |
|
33 | ```js
|
34 | (async () => {
|
35 | console.log(await getPort({port: [3000, 3001, 3002]}));
|
36 | // Will use any element in the preferred ports array if available, otherwise fall back to a random port
|
37 | })();
|
38 | ```
|
39 |
|
40 | Use the `makeRange()` helper in case you need a port in a certain range:
|
41 |
|
42 | ```js
|
43 | (async () => {
|
44 | console.log(await getPort({port: getPort.makeRange(3000, 3100)}));
|
45 | // Will use any port from 3000 to 3100, otherwise fall back to a random port
|
46 | })();
|
47 | ```
|
48 |
|
49 | ## API
|
50 |
|
51 | ### getPort(options?)
|
52 |
|
53 | Returns a `Promise` for a port number.
|
54 |
|
55 | #### options
|
56 |
|
57 | Type: `object`
|
58 |
|
59 | ##### port
|
60 |
|
61 | Type: `number | Iterable<number>`
|
62 |
|
63 | A preferred port or an iterable of preferred ports to use.
|
64 |
|
65 | ##### host
|
66 |
|
67 | Type: `string`
|
68 |
|
69 | The host on which port resolution should be performed. Can be either an IPv4 or IPv6 address.
|
70 |
|
71 | ### getPort.makeRange(from, to)
|
72 |
|
73 | Make a range of ports `from`...`to`.
|
74 |
|
75 | Returns an `Iterable` for ports in the given range.
|
76 |
|
77 | #### from
|
78 |
|
79 | Type: `number`
|
80 |
|
81 | First port of the range. Must be in the range `1024`...`65535`.
|
82 |
|
83 | #### to
|
84 |
|
85 | Type: `number`
|
86 |
|
87 | Last port of the range. Must be in the range `1024`...`65535` and must be greater than `from`.
|
88 |
|
89 | ## Beware
|
90 |
|
91 | There is a very tiny chance of a race condition if another process starts using the same port number as you in between the time you get the port number and you actually start using it.
|
92 |
|
93 | Race conditions in the same process are mitigated against by using a lightweight locking mechanism where a port will be held for a minimum of 15 seconds and a maximum of 30 seconds before being released again.
|
94 |
|
95 | ## Related
|
96 |
|
97 | - [get-port-cli](https://github.com/sindresorhus/get-port-cli) - CLI for this module
|
98 |
|
99 | ---
|
100 |
|
101 | <div align="center">
|
102 | <b>
|
103 | <a href="https://tidelift.com/subscription/pkg/npm-get-port?utm_source=npm-get-port&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
|
104 | </b>
|
105 | <br>
|
106 | <sub>
|
107 | Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
|
108 | </sub>
|
109 | </div>
|