node-port-check
v2.0.1
Published
Check if a TCP port is in use and tries to return an incremented version of your port if it's found available.
Downloads
2,772
Maintainers
Readme
Node Port Check
Check if a port is in use. Simple as that!
npm install node-port-check --save
Update
2.0.1 :
- Cleanup: source and test files can be found on github
- Cleanup: source and test files have been removed from the npm package
2.0.0 :
- As of 2.0 this package has been rewritten to use Promises.
- These 3 promises are all there is to it: getFreePorts, isFreePort, nextAvailable .
- Let {getFreePorts, isFreePort, nextAvailable} = require('node-port-check');
- Read the examples below to see how to use them.
Options
Options | Default Values | Returns ------- | -------------- | ----------- isFreePort | (port: number = 80, host: string = '0.0.0.0') | Promise<[port, host, status]> getFreePorts | (howMany: number = 1, host: string = "0.0.0.0", freePorts: number[] = []) | Promise<port[]> nextAvailable | (port: number = 80, host: string = '0.0.0.0') | Promise<number>
Demos
Example 1 - Simple
/**
* Demo use case:
* We'll bind ports 3010 and 3011 with mockServer
* It will check the availability for ports 3010, 3011 and 3012
* The returning port will be 3012 ( assuming you don't have that port bound by another application
* or else a higher port will be returned )
*
* #1 - this lines won't exist in your code, their purpose it's just for testing
*/
let mockServer = require('./mockServer.js'); // #1
mockServer(3010); // #1
mockServer(3011); // #1
/**
* EXAMPLE 1
*/
/**
* Returns the current port if available or the next one available by incrementing the port
* @param {number} port
* @param {string} host
* @returns {Promise<number>}
*/
let {nextAvailable} = require('node-port-check');
nextAvailable(3010, '0.0.0.0').then((nextAvailablePort) => {
console.log('Available port:', nextAvailablePort);
process.exit(0);
});
Output:
Mock Server started on port 3010
Mock Server started on port 3011
Available port: 3012
Example 2 - Multiple Ports
/**
* Demo use case:
* We'll bind ports 3010, 4500 and 9921 with mockServer
* Since we have maxRetries = 0 now in 'yourConfig' no incrementation will be done ( see example 3 for multiple ports and maxRetries > 0 )
* the returning port will be the first encountered free port, that is 5195
* ( assuming you don't have that port bound by another application )
*
*/
/**
* EXAMPLE 2
*/
/**
* Get a number of guaranteed free ports available for a host
* @param {number} howMany
* @param {string} host
* @param {number[]} freePorts
* @returns {Promise<number[]>}
*/
let {getFreePorts} = require('node-port-check');
getFreePorts(10, '0.0.0.0').then((freePortsList) => {
console.log('Free ports:', freePortsList);
process.exit(0);
});
Output:
Free ports: [ 5187, 15281, 18800, 26123, 32221, 36763, 45031, 53605, 61096, 63011 ]
Example 3 - Multiple Ports - Part 2
/**
* Demo use case:
* These demo will generate 10 ports.
* If you use the third parameter the returned free ports will contain the reserved list of ports.
*
* NOTE: When you reserve ports, "free ports" is not valid anymore because
* the reserved ports won't be checked if they are free or in use,
* only the ports that ARE NOT in your reserved list are the free ports.
*/
/**
* EXAMPLE 3
*/
/**
* Get a number of guaranteed free ports available for a host
* @param {number} howMany
* @param {string} host
* @param {number[]} freePorts
* @returns {Promise<number[]>}
*/
let {getFreePorts} = require('node-port-check');
/**
* Use the third parameter to reserve your port.
*/
getFreePorts(10, '0.0.0.0', [3000, 3001, 3002, 3003, 3009]).then((freePortsList) => {
console.log('Free ports:', freePortsList);
process.exit(0);
});
Output:
Free ports: [ 3000, 3001, 3002, 3003, 3009, 8185, 9240, 10462, 35187, 47349 ]
Example 4 - Check for a free port
/**
* Demo use case:
* We'll bind ports 3010, 4500 and 9921 with mockServer
* We want 10 free ports and we want to reserve the ports 2018, 3010, 4500 and 9921
* This example will show you how to check if your ports are in use.
*
* NOTE: When you reserve ports, "free ports" is not valid anymore because
* the reserved ports won't be checked if they are free or in use,
* only the ports that ARE NOT in your reserved list are the free ports.
*/
/**
* EXAMPLE 4
*/
let mockServer = require('./mockServer.js'); // #4
mockServer(3010); // #4
mockServer(4500); // #4
mockServer(9921); // #4
/**
* Get a number of guaranteed free ports available for a host
* @param {number} howMany
* @param {string} host
* @param {number[]} freePorts
* @returns {Promise<number[]>}
*/
let {getFreePorts, isFreePort} = require('node-port-check');
/**
* Use the third parameter to reserve your port.
*/
getFreePorts(10, '0.0.0.0', [2018, 3010, 4500, 9921]).then((freePortsList) => {
console.log('Free ports:', freePortsList);
let checkPorts = freePortsList.map(item => isFreePort(item));
Promise
.all(checkPorts)
.then(list => {
list.forEach(portStatus => {
let port = portStatus[0];
let host = portStatus[1];
let status = portStatus[2];
console.log('Status ' + (status ? 'available' : 'unavailable') + ':', port, host, status);
});
process.exit(0);
});
});
Output:
Mock Server started on port 3010
Mock Server started on port 4500
Mock Server started on port 9921
Free ports: [ 2018, 3010, 4500, 9921, 3985, 5890, 15367, 19661, 22715, 36543 ]
Status available: 2018 0.0.0.0 true
Status unavailable: 3010 0.0.0.0 false
Status unavailable: 4500 0.0.0.0 false
Status unavailable: 9921 0.0.0.0 false
Status available: 3985 0.0.0.0 true
Status available: 5890 0.0.0.0 true
Status available: 15367 0.0.0.0 true
Status available: 19661 0.0.0.0 true
Status available: 22715 0.0.0.0 true
Status available: 36543 0.0.0.0 true