is-localhost-ip 2.0.0 → 3.0.1

package/README.md

@@ -1,12 +1,16 @@
-[![codecov](https://codecov.io/gh/tinovyatkin/is-localhost-ip/branch/master/graph/badge.svg)](https://codecov.io/gh/tinovyatkin/is-localhost-ip) ![node](https://img.shields.io/node/v/is-localhost-ip)
+[![codecov](https://codecov.io/gh/tinovyatkin/is-localhost-ip/branch/master/graph/badge.svg)](https://codecov.io/gh/tinovyatkin/is-localhost-ip)
+![node](https://img.shields.io/node/v/is-localhost-ip)
 
 # is-localhost-ip
 
-Comprehensive and robust library to checks whether given host name or IPv4/IPv6 address belongs to the local machine
+Zero-dependency Node.js utility that checks whether a hostname or IPv4/IPv6 address refers to the local machine.
 
-Main difference from other libraries here is comprehensiveness: we start from strict RegExp checks (for IP address first, and then for correctness to be a host name), then fallback to DNS resolver (so it works with something like `john.dev` remapped locally in `hosts` or with local resolver).
+This package aims to be strict and comprehensive:
 
-All this in just _~100 lines of code_ without external dependencies.
+- Validates input as an IP address or a syntactically valid hostname (including bracketed IPv6).
+- Treats private/loopback/link-local ranges as local.
+- Optionally verifies the address exists on the current machine by attempting to bind to it.
+- Falls back to DNS resolution, so it works with hostnames mapped in `/etc/hosts` or a local resolver.
 
 ## Installation
 
@@ -14,37 +18,55 @@ All this in just _~100 lines of code_ without external dependencies.
 npm i is-localhost-ip
 # or
 yarn add is-localhost-ip
+# or
+pnpm add is-localhost-ip
 ```
 
-## Example
+Requires Node.js `>=18`.
+
+## Usage
 
 ```js
-const isLocalhost = require('is-localhost-ip');
+const isLocalhost = require("is-localhost-ip");
 
 (async () => {
-  await isLocalhost('127.0.0.1'); // true
-  await isLocalhost('::ffff:127.0.0.1'); // true
-  await isLocalhost('192.168.0.12'); // true
-  await isLocalhost('192.168.0.12', true); // true only if the local machine has an interface with that address
-  await isLocalhost('184.55.123.2'); // false
-
-  await isLocalhost('tino.local'); // true
-  await isLocalhost('localhost'); // true
-  await isLocalhost('microsoft.com'); // false
+  await isLocalhost("127.0.0.1"); // true
+  await isLocalhost("::ffff:127.0.0.1"); // true
+  await isLocalhost("192.168.0.12"); // true
+  await isLocalhost("192.168.0.12", true); // true only if an interface has this address
+  await isLocalhost("184.55.123.2"); // false
+
+  await isLocalhost("tino.local"); // true if it resolves to a local address
+  await isLocalhost("localhost"); // true
+  await isLocalhost("microsoft.com"); // false
 })();
 ```
 
+## API
+
+### `isLocalhost(ipOrHostname, canBind?)`
+
+Returns a `Promise<boolean>`.
+
+- `ipOrHostname` (`string`): IP address (v4/v6) or a hostname.
+- `canBind` (`boolean`, default `false`): when `true`, additionally checks that the local machine can bind to the
+  address (i.e., it is configured on a local interface).
+
+The function throws for invalid inputs (non-string values or syntactically invalid hostnames).
+
 ## Caveats
 
-Doesn't work with internationalized ([RFC 3492](https://tools.ietf.org/html/rfc3492) or [RFC 5891](https://tools.ietf.org/html/rfc5891)) domain names. If you need that please use wonderful [Punycode.js](https://github.com/bestiejs/punycode.js) to convert the string before passing to this library:
+Internationalized domain names (IDNs) are not supported. If you need IDNs, use
+[Punycode.js](https://github.com/bestiejs/punycode.js) (or another punycode implementation) to convert the input
+to ASCII before calling this function:
 
 ```js
-const isLocalhost = require('is-localhost-ip');
-const punycode = require('punycode');
+const isLocalhost = require("is-localhost-ip");
+const punycode = require("punycode");
 
 (async () => {
-  await isLocalhost(punycode.toASCII('свобода.рф')); // false
-  await isLocalhost(punycode.toASCII('私の.家')); // true
+  await isLocalhost(punycode.toASCII("свобода.рф")); // false
+  await isLocalhost(punycode.toASCII("私の.家")); // true
 })();
 ```
 

package/index.js

@@ -1,9 +1,9 @@
-'use strict';
+"use strict";
 
-const { isIP, isIPv4 } = require('net');
-const { createSocket } = require('dgram');
-const { ADDRCONFIG } = require('dns');
-const { lookup } = require('dns').promises;
+const { isIP, isIPv4 } = require("node:net");
+const { createSocket } = require("node:dgram");
+const { ADDRCONFIG } = require("node:dns");
+const { lookup } = require("node:dns").promises;
 
 /**
  * Addresses reserved for private networks
@@ -22,15 +22,13 @@ const IP_RANGES = [
   // 192.168.0.0 - 192.168.255.255
   /^(:{2}f{4}:)?192\.168(?:\.\d{1,3}){2}$/,
   // fc00::/7
-  /^f[cd][\da-f]{2}(::1$|:[\da-f]{1,4}){1,7}$/,
+  /^f[cd][\da-f]{2}(::1?$|:[\da-f]{1,4}){1,7}$/,
   // fe80::/10
-  /^fe[89ab][\da-f](::1$|:[\da-f]{1,4}){1,7}$/,
+  /^fe[89ab][\da-f](::1?$|:[\da-f]{1,4}){1,7}$/,
 ];
 
 // Concat all RegExes from above into one
-const IP_TESTER_RE = new RegExp(
-  `^(${IP_RANGES.map((re) => re.source).join('|')})$`,
-);
+const IP_TESTER_RE = new RegExp(`^(${IP_RANGES.map((re) => re.source).join("|")})$`);
 
 /**
  * Syntax validation RegExp for possible valid host names. Permits underscore.
@@ -47,12 +45,12 @@ const VALID_HOSTNAME =
  * @returns {Promise<boolean>}
  */
 async function canBindToIp(ip) {
-  const socket = createSocket(isIPv4(ip) ? 'udp4' : 'udp6');
+  const socket = createSocket(isIPv4(ip) ? "udp4" : "udp6");
   return new Promise((resolve) => {
     try {
       socket
-        .once('error', () => socket.close(() => resolve(false)))
-        .once('listening', () => socket.close(() => resolve(true)))
+        .once("error", () => socket.close(() => resolve(false)))
+        .once("listening", () => socket.close(() => resolve(true)))
         .unref()
         .bind(0, ip);
     } catch {
@@ -69,31 +67,40 @@ async function canBindToIp(ip) {
  * @returns {Promise.<boolean>} - true, if given strings is a local IP address or DNS names that resolves to local IP
  */
 async function isLocalhost(ipOrHostname, canBind = false) {
-  if (typeof ipOrHostname !== 'string') return false;
+  if (typeof ipOrHostname !== "string") {
+    throw new TypeError("Invalid ip or hostname provided");
+  }
+
+  // Removes [ and ] around ipv6 hostnames
+  const normalizedIpOrHostname = ipOrHostname.replaceAll(/^\[|\]$/g, "");
 
   // Check if given string is an IP address
-  if (isIP(ipOrHostname)) {
-    if (IP_TESTER_RE.test(ipOrHostname) && !canBind) return true;
-    return canBindToIp(ipOrHostname);
+  if (isIP(normalizedIpOrHostname)) {
+    if (IP_TESTER_RE.test(normalizedIpOrHostname) && !canBind) return true;
+    return canBindToIp(normalizedIpOrHostname);
   }
 
   // May it be a hostname?
-  if (!VALID_HOSTNAME.test(ipOrHostname)) return false;
+  if (!VALID_HOSTNAME.test(normalizedIpOrHostname)) {
+    throw new Error("Invalid ip or hostname provided");
+  }
 
   // it's a DNS name
-  try {
-    const addresses = await lookup(ipOrHostname, {
-      all: true,
-      family: 0,
-      verbatim: true,
-      hints: ADDRCONFIG,
-    });
-    if (!Array.isArray(addresses)) return false;
-    for (const { address } of addresses) {
-      if (await isLocalhost(address, canBind)) return true;
-    }
-    // eslint-disable-next-line no-empty
-  } catch {}
+  const addresses = await lookup(normalizedIpOrHostname, {
+    all: true,
+    family: 0,
+    verbatim: true,
+    hints: ADDRCONFIG,
+  });
+
+  if (!Array.isArray(addresses)) {
+    throw new TypeError("DNS Lookup failed.");
+  }
+
+  for (const { address } of addresses) {
+    if (await isLocalhost(address, canBind)) return true;
+  }
+
   return false;
 }
 

package/package.json

@@ -1,59 +1,46 @@
 {
   "name": "is-localhost-ip",
-  "version": "2.0.0",
+  "version": "3.0.1",
   "description": "Checks whether given DNS name or IPv4/IPv6 address belongs to a local machine",
-  "main": "index.js",
-  "files": [
-    "index.js",
-    "index.d.ts"
+  "keywords": [
+    "check-localhost",
+    "dns",
+    "ip",
+    "is-local-ip",
+    "is-localhost",
+    "is-loopback",
+    "localhost"
   ],
-  "types": "index.d.ts",
-  "engines": {
-    "node": ">=12"
-  },
-  "scripts": {
-    "test": "jest --coverage --verbose",
-    "lint": "eslint ."
+  "homepage": "https://github.com/tinovyatkin/is-localhost-ip#readme",
+  "bugs": {
+    "url": "https://github.com/tinovyatkin/is-localhost-ip/issues"
   },
+  "license": "MIT",
+  "author": "Konstantin Vyatkin <tino@vtkn.io>",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/tinovyatkin/is-localhost-ip.git"
   },
-  "keywords": [
-    "localhost",
-    "is-localhost",
-    "check-localhost",
-    "is-loopback",
-    "is-local-ip",
-    "ip",
-    "dns"
+  "files": [
+    "index.d.ts",
+    "index.js"
   ],
-  "author": "Konstantin Vyatkin <tino@vtkn.io>",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/tinovyatkin/is-localhost-ip/issues"
+  "main": "index.js",
+  "browser": false,
+  "types": "index.d.ts",
+  "scripts": {
+    "test": "node --test --experimental-test-module-mocks --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage/lcov.info __tests__/*.test.js",
+    "lint": "oxlint --fix --fix-suggestions",
+    "format": "oxfmt --write .",
+    "prepare": "lefthook install"
   },
-  "homepage": "https://github.com/tinovyatkin/is-localhost-ip#readme",
   "devDependencies": {
-    "@types/jest": "28.1.6",
-    "@types/node": "~12",
-    "eslint": "8.21.0",
-    "eslint-config-prettier": "8.5.0",
-    "eslint-plugin-node": "11.1.0",
-    "eslint-plugin-prettier": "4.2.1",
-    "eslint-plugin-regexp": "^1.8.0",
-    "jest": "28.1.3",
-    "prettier": "2.7.1"
+    "@types/node": "22.15.21",
+    "lefthook": "^2.0.15",
+    "oxfmt": "^0.24.0",
+    "oxlint": "^1.39.0"
   },
-  "jest": {
-    "coverageReporters": [
-      "text",
-      "json",
-      "cobertura",
-      "lcov"
-    ],
-    "coverageProvider": "v8",
-    "testEnvironment": "node",
-    "collectCoverage": true
+  "engines": {
+    "node": ">=18"
   }
 }