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