diff --git a/index.d.ts b/index.d.ts index 765eb6c..08df0fe 100644 --- a/index.d.ts +++ b/index.d.ts @@ -60,3 +60,31 @@ console.log(await getPort({port: portNumbers(3000, 3100)})); ``` */ export function portNumbers(from: number, to: number): Iterable; + +/** +Clear the internal cache of locked ports. + +This can be useful when you want the results to be unaffected by previous calls. + +Please note that clearing the cache could cause [race conditions](https://github.com/sindresorhus/get-port#beware). + +@example +``` +import getPort, {clearLockedPorts} from 'get-port'; + +const port = [3000, 3001, 3002]; + +console.log(await getPort({port})); +//=> 3000 + +console.log(await getPort({port})); +//=> 3001 + +// If you want the results to be unaffected by previous calls, clear the cache. +clearLockedPorts(); + +console.log(await getPort({port})); +//=> 3000 +``` +*/ +export function clearLockedPorts(): void; diff --git a/index.js b/index.js index cbea1b0..7691d6f 100644 --- a/index.js +++ b/index.js @@ -178,3 +178,8 @@ export function portNumbers(from, to) { return generator(from, to); } + +export function clearLockedPorts() { + lockedPorts.old.clear(); + lockedPorts.young.clear(); +} diff --git a/readme.md b/readme.md index 7693df4..62e7025 100644 --- a/readme.md +++ b/readme.md @@ -94,6 +94,32 @@ Type: `number` The last port of the range. Must be in the range `1024`...`65535` and must be greater than `from`. +### clearLockedPorts() + +Clear the internal cache of locked ports. + +This can be useful when you want the results to be unaffected by previous calls. + +Please note that clearing the cache could cause [race conditions](#beware). + +```js +import getPort, {clearLockedPorts} from 'get-port'; + +const port = [3000, 3001, 3002]; + +console.log(await getPort({port})); +//=> 3000 + +console.log(await getPort({port})); +//=> 3001 + +// If you want the results to be unaffected by previous calls, clear the cache. +clearLockedPorts(); + +console.log(await getPort({port})); +//=> 3000 +``` + ## Beware 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. diff --git a/test.js b/test.js index 9ff8b63..fbea856 100644 --- a/test.js +++ b/test.js @@ -1,7 +1,7 @@ import {promisify} from 'node:util'; import net from 'node:net'; import test from 'ava'; -import getPort, {portNumbers} from './index.js'; +import getPort, {portNumbers, clearLockedPorts} from './index.js'; test('port can be bound when promise resolves', async t => { const port = await getPort(); @@ -193,3 +193,18 @@ test('preferred ports is bound up with different hosts', async t => { t.is(port, desiredPorts[3]); }); + +test('clearLockedPorts()', async t => { + const desiredPort = 8088; + const port1 = await getPort({port: desiredPort}); + t.is(port1, desiredPort); + + const port2 = await getPort({port: desiredPort}); + // Port1 is locked + t.not(port2, desiredPort); + + // Clear locked ports + clearLockedPorts(); + const port3 = await getPort({port: desiredPort}); + t.is(port3, desiredPort); +});