# node-port-check > Check if a TCP port is in use and tries to return an incremented version of your port if it's found available. Latest version **2.0.1** (published 2018-09-17) · MIT license · 0 weekly downloads ## Install ```sh npm install node-port-check pnpm add node-port-check yarn add node-port-check bun add node-port-check ``` ## Health **Score 20/100 (F)** — status: abandoned. Positive: has types; no vulnerabilities. Warnings: low downloads; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 2.0.1 | | Published | 2018-09-17 | | First published | 2017-06-07 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | CommonJS | | Dependencies | 0 | | Unpacked size | 23 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 3 | | Author | darklightcode | | Maintainers | darklightcode | | Keywords | node, port check, check port, free port, available port | ## Links - npm: https://www.npmjs.com/package/node-port-check - Repository: https://github.com/darklightcode/node-port-check - Homepage: https://github.com/darklightcode/node-port-check#readme - Issues: https://github.com/darklightcode/node-port-check/issues - npm.io page: https://npm.io/package/node-port-check ## Alternatives - [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads - [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads - [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads - [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads - [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads ## Recent versions - 2.0.1 (latest) — 2018-09-17 - 2.0.0 — 2018-06-21 - 1.0.2 — 2017-06-07 - 1.0.1 — 2017-06-07 - 1.0.0 — 2017-06-07 ## 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\ nextAvailable | (port: number = 80, host: string = '0.0.0.0') | Promise\ # Demos ### Example 1 - Simple ```javascript /** * 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} */ 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 ```javascript /** * 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} */ 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 ```javascript /** * 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} */ 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 ```javascript /** * 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} */ 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 ``` --- _Source: https://npm.io/package/node-port-check · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._