docs: add use-case

index.d.ts

@@ -63,5 +63,23 @@ export function portNumbers(from: number, to: number): Iterable<number>;
 
 /**
 Clear the internal cache of locked ports.
+
+When you want your results to be unaffected by previous calls.
+
+Of course, this carries potential risks as you are disrupting the internal cache.
+
+Therefore, you need to be absolutely certain about this decision.
+
+Example:
+
+```
+import getPort, {clearLockedPorts} from 'get-port';
+
+// Before using it, clear the cache.
+clearLockedPorts();
+const port = await getPort();
+
+```
+
  */
 export function clearLockedPorts(): void;

readme.md

@@ -44,6 +44,16 @@ console.log(await getPort({port: portNumbers(3000, 3100)}));
 // Will use any port from 3000 to 3100, otherwise fall back to a random port
 ```
 
+Use the `clearLockedPorts()` to clear the internal cache of locked ports.
+
+```js
+import getPort, {clearLockedPorts} from 'get-port';
+
+// Before using it, clear the cache.
+clearLockedPorts();
+const port = await getPort();
+```
+
 ## API
 
 ### getPort(options?)
@@ -94,6 +104,10 @@ 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.
+
 ## 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

@@ -194,7 +194,7 @@ test('preferred ports is bound up with different hosts', async t => {
 	t.is(port, desiredPorts[3]);
 });
 
-test('clear locked ports by lockedPorts', async t => {
+test('clear locked ports', async t => {
 	const desiredPort = 8088;
 	const port1 = await getPort({port: desiredPort});
 	t.is(port1, desiredPort);