https://github.com/versatica/pick-port
Get a free TCP or UDP port for the given IP address
https://github.com/versatica/pick-port
Last synced: 10 months ago
JSON representation
Get a free TCP or UDP port for the given IP address
- Host: GitHub
- URL: https://github.com/versatica/pick-port
- Owner: versatica
- License: isc
- Created: 2018-01-30T14:09:49.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2024-06-21T10:09:58.000Z (almost 2 years ago)
- Last Synced: 2025-04-24T07:54:19.055Z (11 months ago)
- Language: TypeScript
- Size: 477 KB
- Stars: 14
- Watchers: 3
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# pick-port
[![][npm-shield-pick-port]][npm-pick-port]
[![][github-actions-shield-pick-port]][github-actions-pick-port]
Get an available TCP or UDP port for the given IP address.
```bash
$ npm install pick-port
```
## Usage
```ts
import { pickPort } from 'pick-port';
```
Get a random UDP port in IP 0.0.0.0:
```ts
const port = await pickPort({ type: 'udp' });
```
Get a TCP port in a specific IP and port range:
```ts
const port = await pickPort({
type: 'tcp',
ip: '192.168.10.111',
minPort: 8000,
maxPort: 9000,
});
```
## API
### async pickPort({ type, ip, minPort, maxPort, reserveTimeout }): Promise
Resolves with an available port or rejects with an error otherwise.
| Option | Type | Description | Required | Default |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------: | --------- |
| `type` | String | 'udp' or 'tcp'. | Yes | |
| `ip` | String | IPv4 or IPv6 address for which a free port is requested. | No | '0.0.0.0' |
| `minPort` | Number | Minimum port. | No | 10000 |
| `maxPort` | Number | Maximum port. | No | 20000 |
| `reserveTimeout` | Number | Timeout in seconds during which a returned port will be internally reserved and prevented of being returned on a future call before the timeout has elapsed. | No | 5 |
- `@returns` {Number} A free port.
The `reserveTimeout` option provides the application with the required time to bind the free port before it is given again on a future call to this library.
## Authors
- José Luis Millán [[github](https://github.com/jmillan/)]
- Iñaki Baz Castillo [[website](https://inakibaz.me)|[github](https://github.com/ibc/)]
## License
[ISC](./LICENSE)
[npm-shield-pick-port]: https://img.shields.io/npm/v/pick-port.svg
[npm-pick-port]: https://npmjs.org/package/pick-port
[github-actions-shield-pick-port]: https://github.com/versatica/pick-port/actions/workflows/pick-port.yaml/badge.svg
[github-actions-pick-port]: https://github.com/versatica/pick-port/actions/workflows/pick-port.yaml