feat: export waitForPort

README.md

@@ -19,15 +19,16 @@ or npm install get-port-please
 
 ```js
 // ESM
-import { getPort, checkPort, getRandomPort } from 'get-port-please'
+import { getPort, checkPort, getRandomPort, waitForPort } from 'get-port-please'
 
 // CommonJS
-const { getPort, checkPort, getRandomPort } = require('get-port-please')
+const { getPort, checkPort, getRandomPort, waitForPort } = require('get-port-please')
 ```
 
 ```ts
-function getPort(options?: GetPortOptions): Promise<number>
-function checkPort(port: number, host?: string): Promise<number | false>
+getPort(options?: GetPortOptions): Promise<number>
+checkPort(port: number, host?: string): Promise<number | false>
+waitForPort(port: number, options): Promise<number | false>
 ```
 
 Try sequence is: port > ports > memo > random

src/index.ts

@@ -67,7 +67,7 @@ export async function getRandomPort (host: HostAddress) {
   return port
 }
 
-export async function checkPort (port: PortNumber, host: HostAddress | HostAddress[] | undefined = process.env.HOST): Promise<PortNumber|false> {
+export async function checkPort (port: PortNumber, host: HostAddress | HostAddress[] = process.env.HOST): Promise<PortNumber|false> {
   if (!host) {
     host = getLocalHosts([undefined /* default */, '0.0.0.0'])
   }
@@ -86,6 +86,22 @@ export async function checkPort (port: PortNumber, host: HostAddress | HostAddre
   return port
 }
 
+export interface WaitForPortOptions {
+  host?: HostAddress
+  delay?: number
+  retries?: number
+}
+export async function waitForPort (port: PortNumber, opts: WaitForPortOptions = {}) {
+  const delay = opts.delay || 500
+  const retries = opts.retries || 4
+  for (let i = retries; i > 0; i--) {
+    if (await _checkPort(port, opts.host) === false) {
+      return
+    }
+  }
+  throw new Error(`Timeout waiting for port ${port} after ${retries} retries with ${delay}ms interval.`)
+}
+
 // ----- Internal -----
 
 function _checkPort (port: PortNumber, host: HostAddress): Promise<PortNumber|false> {