@go22/port0 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 go22
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# @go22/port0
+
+Check whether a TCP port is in use and find a random available port. Requires Node.js 18 or newer.
+
+## Install
+
+```sh
+npm install @go22/port0
+```
+
+## Usage
+
+```js
+import { genPort, isPortInUse } from '@go22/port0';
+
+await isPortInUse(3000); // true or false
+await isPortInUse('3000'); // true or false
+
+await genPort(); // random available port from 1024 through 65535
+await genPort(3000); // random available port from 3000 through 65535
+await genPort(3000, 4000); // random available port from 3000 through 4000
+```
+
+Both range boundaries are inclusive. `genPort` checks each candidate no more than once and rejects with a `RangeError` if every port in the range is in use.
+
+Availability is inherently a point-in-time check. Another process can claim a returned port before your application binds to it.
+
+Because of this race condition, the intended use is to bind or connect with the randomly generated port immediately, minimizing the risk of a collision.
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,3 @@
+export function isPortInUse(port: number | string): Promise<boolean>;
+
+export function genPort(pLower?: number, pUpper?: number): Promise<number>;

package/index.js

@@ -0,0 +1,87 @@
+import { createServer } from 'node:net';
+
+const PORT_LOWER = 1024;
+const PORT_UPPER = 65535;
+
+function parsePort(value, name) {
+  const port = typeof value === 'string' && /^(0|[1-9]\d*)$/.test(value)
+    ? Number(value)
+    : value;
+
+  if (!Number.isInteger(port) || port < 0 || port > PORT_UPPER) {
+    throw new RangeError(`${name} must be an integer between 0 and ${PORT_UPPER}`);
+  }
+
+  return port;
+}
+
+/**
+ * Determine whether a TCP port cannot be bound because it is already in use.
+ *
+ * @param {number|string} port
+ * @returns {Promise<boolean>}
+ */
+export async function isPortInUse(port) {
+  const parsedPort = parsePort(port, 'port');
+
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.unref();
+
+    server.once('error', (error) => {
+      if (error.code === 'EADDRINUSE') {
+        resolve(true);
+        return;
+      }
+
+      reject(error);
+    });
+
+    server.listen({ port: parsedPort, exclusive: true }, () => {
+      server.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+
+        resolve(false);
+      });
+    });
+  });
+}
+
+/**
+ * Find a random available TCP port in an inclusive range.
+ *
+ * @param {number} [pLower=1024]
+ * @param {number} [pUpper=65535]
+ * @returns {Promise<number>}
+ */
+export async function genPort(pLower = PORT_LOWER, pUpper = PORT_UPPER) {
+  const lower = parsePort(pLower, 'pLower');
+  const upper = parsePort(pUpper, 'pUpper');
+
+  if (lower > upper) {
+    throw new RangeError('pLower must be less than or equal to pUpper');
+  }
+
+  const size = upper - lower + 1;
+  const swaps = new Map();
+
+  // Lazily shuffle the range so each port is tested once without allocating it.
+  for (let index = 0; index < size; index += 1) {
+    const randomIndex = index + Math.floor(Math.random() * (size - index));
+    const candidateOffset = swaps.get(randomIndex) ?? randomIndex;
+    const currentOffset = swaps.get(index) ?? index;
+
+    swaps.set(randomIndex, currentOffset);
+    swaps.delete(index);
+
+    const candidate = lower + candidateOffset;
+    if (!(await isPortInUse(candidate))) {
+      return candidate;
+    }
+  }
+
+  throw new RangeError(`No available port found between ${lower} and ${upper}`);
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@go22/port0",
+  "version": "1.0.0",
+  "description": "Check whether a TCP port is in use and find a random available port.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "port",
+    "available",
+    "network",
+    "tcp"
+  ],
+  "license": "MIT"
+}