Add clearLockedPorts() method (#70)

Co-authored-by: Sindre Sorhus <sindresorhus@gmail.com>

index.d.ts

@@ -60,3 +60,31 @@ console.log(await getPort({port: portNumbers(3000, 3100)}));
 ```
 */
 export function portNumbers(from: number, to: number): Iterable<number>;
+
+/**
+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;

index.js

@@ -178,3 +178,8 @@ export function portNumbers(from, to) {
 
 	return generator(from, to);
 }
+
+export function clearLockedPorts() {
+	lockedPorts.old.clear();
+	lockedPorts.young.clear();
+}

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.

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);
+});