Free up a TCP port by killing all processes listening on it, properly

unbind.js

/**
 * Free-up a TCP port by killing all processes listening on it.
 * License: The MIT-0 License; no attribution required
 * 
 * - Finds all processes listening on specified port,
 *   sends a SIGTERM signal to each, then polls until all die,
 *.  or the grace period expires, SIGKILL-ing all survivors.
 * - Returns: array of killed PIDs, empty if none
 *
 * await unbind(3000)                     // => [] or [pid, ...]
 * await unbind(3000, { timeout: 5000 })  // longer grace period
 * await unbind(3000, {                   // slower polling
 *   poll: { interval: 100 }
 * })
 */

import { execFile } from 'node:child_process'
import { promisify } from 'node:util'
import { setTimeout as wait } from 'node:timers/promises'

export const unbind = (port, {
  timeout = 3000,
  poll: { interval = 50 } = {}
} = {}) =>
  Promise.resolve(port)
    .then(port => Number.isFinite(port) && port >= 1 && port <= 65535
      ? port
      : Promise.reject(new RangeError(`port: ${port}, must be 1 - 65535`)))
    .then(port => promisify(execFile)('lsof', ['-ti', `tcp:${port}`, '-sTCP:LISTEN']))
    .then(({ stdout }) => stdout.trim().split('\n').map(Number).filter(Boolean))
    .then(pids => pids.map(pid => (process.kill(pid, 'SIGTERM'), pid)))
    .then(function poll(pids, start = Date.now()) {
      const live = pids.filter(pid => {
        try { return process.kill(pid, 0), true }
        catch (err) {
          if (err.code === 'ESRCH') return false
          throw err
        }
      })

      return !live.length ? pids :
        Date.now() - start >= timeout
          ? (live.forEach(pid => process.kill(pid, 'SIGKILL')), pids)
          : wait(Math.max(10, interval)).then(() => poll(pids, start))
    })
    .catch(err => err.code === 1 ? [] : Promise.reject(err))