feat(validation): enhance isPort function and add isHostname validation utility

Author: cyber-hari

src/validation/validation.utils.ts

@@ -18,18 +18,21 @@ const TLD_REGEX = /^[A-Za-z]{2,63}$/;
 /**
  * Checks if a string is a valid port number.
  *
- * @param str - The input string or number.
+ * @param value - The input string or number.
+ * @param allowZero - Whether to allow zero as a valid port number.
  * @returns True if valid port number, else false.
  */
-export function isPort(value: string | number): boolean {
-  if (typeof value === 'number') return Number.isInteger(value) && value > 0 && value <= 65535;
+export function isPort(value: string | number, allowZero: boolean = false): boolean {
+  const minPort = allowZero ? 0 : 1;
+  const maxPort = 65535;
+  if (typeof value === 'number') return Number.isInteger(value) && value >= minPort && value <= maxPort;
   if (!value || typeof value !== 'string') return false;
 
   const str = value.trim();
   if (!PORT_REGEX.test(str)) return false;
 
   const port = Number(str);
-  return Number.isInteger(port) && port > 0 && port <= 65535;
+  return Number.isInteger(port) && port >= minPort && port <= maxPort;
 }
 
 /**
@@ -232,7 +235,7 @@ export function isIPv4(str: string): boolean {
   const parts = str.split('.');
   if (parts.length !== 4) return false;
   return parts.every(p => {
-    if (p.length > 3 || (p.startsWith('0') && p.length > 1)) return false;
+    if (!p || p.length > 3 || (p.startsWith('0') && p.length > 1)) return false;
     const n = Number(p);
     return Number.isInteger(n) && n >= 0 && n <= 255;
   });
@@ -253,6 +256,69 @@ export function isIPv6(str: string): boolean {
   }
 }
 
+/**
+ * Checks if a string is a valid hostname or IP address.
+ *
+ * Validates:
+ * - IPv4 addresses (e.g., '192.168.1.1')
+ * - IPv6 addresses (e.g., '::1', '2001:db8::1')
+ * - Domain names (e.g., 'example.com', 'sub.example.com')
+ * - Localhost variants ('localhost', '0.0.0.0', '127.0.0.1')
+ *
+ * @param {string} str - The hostname or IP address to validate.
+ * @returns {boolean} True if valid hostname or IP address.
+ *
+ * @example
+ * ```typescript
+ * isHostname('localhost');        // true
+ * isHostname('0.0.0.0');          // true
+ * isHostname('192.168.1.1');      // true
+ * isHostname('example.com');      // true
+ * isHostname('sub.example.com');  // true
+ * isHostname('::1');              // true
+ * isHostname('invalid..com');     // false
+ * isHostname('');                 // false
+ * ```
+ */
+export function isHostname(str: string): boolean {
+  if (!str || typeof str !== 'string') return false;
+
+  let input = str.trim();
+  if (!input || input.length > 255) return false;
+
+  // Normalize trailing dot (FQDN)
+  if (input.endsWith('.')) {
+    input = input.slice(0, -1);
+  }
+
+  // IPv4
+  if (isIPv4(input)) return true;
+
+  // IPv6
+  if (isIPv6(input)) return true;
+
+  // Localhost
+  if (input === 'localhost') return true;
+
+  // Reject IPv4-like numeric patterns
+  if (/^\d+(\.\d+){3,}$/.test(input)) {
+    return false;
+  }
+
+  // Reject consecutive dots
+  if (input.includes('..')) return false;
+
+  const labels = input.split('.');
+  if (labels.length === 0) return false;
+
+  const labelRegex = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/i;
+
+  return labels.every(label => {
+    if (!label || label.length > 63) return false;
+    return labelRegex.test(label);
+  });
+}
+
 /**
  * Validates a credit card number using the Luhn algorithm.
  *

tests/utils/validation.utils.test.ts

@@ -13,6 +13,7 @@ import {
   isStrongPassword,
   isIPv4,
   isIPv6,
+  isHostname,
   isCreditCard,
   isValidJSON,
   isArray,
@@ -302,6 +303,231 @@ describe('ValidationUtils', () => {
     });
   });
 
+  describe('isHostname', () => {
+    describe('IPv4 addresses', () => {
+      it('accepts valid IPv4 addresses', () => {
+        expect(isHostname('127.0.0.1')).toBe(true);
+        expect(isHostname('0.0.0.0')).toBe(true);
+        expect(isHostname('192.168.1.1')).toBe(true);
+        expect(isHostname('10.0.0.1')).toBe(true);
+        expect(isHostname('255.255.255.255')).toBe(true);
+        expect(isHostname('8.8.8.8')).toBe(true);
+      });
+
+      it('rejects invalid IPv4 addresses', () => {
+        expect(isHostname('256.0.0.1')).toBe(false);
+        expect(isHostname('192.168.1.256')).toBe(false);
+        expect(isHostname('192.168.1.1.1')).toBe(false);
+      });
+    });
+
+    describe('IPv6 addresses', () => {
+      it('accepts valid IPv6 addresses', () => {
+        expect(isHostname('::1')).toBe(true);
+        expect(isHostname('::')).toBe(true);
+        expect(isHostname('2001:0db8:85a3:0000:0000:8a2e:0370:7334')).toBe(true);
+        expect(isHostname('2001:db8::1')).toBe(true);
+        expect(isHostname('fe80::1')).toBe(true);
+        expect(isHostname('::ffff:192.0.2.1')).toBe(true); // IPv4-mapped IPv6
+      });
+
+      it('rejects invalid IPv6 addresses', () => {
+        expect(isHostname('gggg::1')).toBe(false);
+        expect(isHostname(':::')).toBe(false);
+        expect(isHostname('not:valid:ipv6')).toBe(false);
+      });
+    });
+
+    describe('localhost', () => {
+      it('accepts localhost', () => {
+        expect(isHostname('localhost')).toBe(true);
+      });
+    });
+
+    describe('valid domain names', () => {
+      it('accepts standard domain names', () => {
+        expect(isHostname('example.com')).toBe(true);
+        expect(isHostname('sub.example.com')).toBe(true);
+        expect(isHostname('deep.sub.example.com')).toBe(true);
+        expect(isHostname('api.github.com')).toBe(true);
+        expect(isHostname('test-server.example.org')).toBe(true);
+      });
+
+      it('accepts single-label hostnames', () => {
+        expect(isHostname('server1')).toBe(true);
+        expect(isHostname('my-server')).toBe(true);
+        expect(isHostname('app123')).toBe(true);
+      });
+
+      it('accepts hostnames with numbers', () => {
+        expect(isHostname('server1.example.com')).toBe(true);
+        expect(isHostname('api2.example.com')).toBe(true);
+        expect(isHostname('123server.com')).toBe(true);
+      });
+
+      it('accepts maximum length labels (63 chars)', () => {
+        const maxLabel = 'a'.repeat(63);
+        expect(isHostname(`${maxLabel}.com`)).toBe(true);
+      });
+
+      it('accepts exactly 255 character hostname', () => {
+        const label = 'a'.repeat(63);
+        const hostname = `${label}.${label}.${label}.${label}`;
+        expect(hostname.length).toBe(255);
+        expect(isHostname(hostname)).toBe(true);
+      });
+
+      it('accepts trailing dot (FQDN)', () => {
+        expect(isHostname('example.com.')).toBe(true);
+      });
+
+      it('accepts punycode domains', () => {
+        expect(isHostname('xn--d1acpjx3f.xn--p1ai')).toBe(true);
+      });
+
+      it('handles IPv6 with zone index', () => {
+        expect(isHostname('fe80::1%eth0')).toBe(true);
+      });
+
+      it('accepts uppercase domains', () => {
+        expect(isHostname('EXAMPLE.COM')).toBe(true);
+        expect(isHostname('Sub.Domain.COM')).toBe(true);
+      });
+    });
+
+    describe('invalid cases', () => {
+      it('rejects empty or whitespace strings', () => {
+        expect(isHostname('')).toBe(false);
+        expect(isHostname(' ')).toBe(false);
+        expect(isHostname('  ')).toBe(false);
+        expect(isHostname('\t')).toBe(false);
+      });
+
+      it('rejects null and undefined', () => {
+        expect(isHostname(null as any)).toBe(false);
+        expect(isHostname(undefined as any)).toBe(false);
+      });
+
+      it('rejects non-string values', () => {
+        expect(isHostname(123 as any)).toBe(false);
+        expect(isHostname({} as any)).toBe(false);
+        expect(isHostname([] as any)).toBe(false);
+      });
+
+      it('rejects hostnames with consecutive dots', () => {
+        expect(isHostname('example..com')).toBe(false);
+        expect(isHostname('..example.com')).toBe(false);
+        expect(isHostname('example.com..')).toBe(false);
+        expect(isHostname('sub..example.com')).toBe(false);
+      });
+
+      it('rejects hostnames starting or ending with hyphen', () => {
+        expect(isHostname('-example.com')).toBe(false);
+        expect(isHostname('example-.com')).toBe(false);
+        expect(isHostname('sub.-example.com')).toBe(false);
+        expect(isHostname('sub.example-.com')).toBe(false);
+      });
+
+      it('rejects hostnames with invalid characters', () => {
+        expect(isHostname('exa_mple.com')).toBe(false);
+        expect(isHostname('exa!mple.com')).toBe(false);
+        expect(isHostname('exa@mple.com')).toBe(false);
+        expect(isHostname('exa#mple.com')).toBe(false);
+        expect(isHostname('exa$mple.com')).toBe(false);
+        expect(isHostname('exa%mple.com')).toBe(false);
+        expect(isHostname('exa mple.com')).toBe(false);
+        expect(isHostname('exa\tmple.com')).toBe(false);
+      });
+
+      it('rejects hostnames exceeding 255 characters', () => {
+        const tooLong = 'a'.repeat(256);
+        expect(isHostname(tooLong)).toBe(false);
+
+        const longHostname = 'a'.repeat(200) + '.com';
+        expect(isHostname(longHostname)).toBe(false);
+      });
+
+      it('rejects labels exceeding 63 characters', () => {
+        const tooLongLabel = 'a'.repeat(64);
+        expect(isHostname(`${tooLongLabel}.com`)).toBe(false);
+        expect(isHostname(`sub.${tooLongLabel}.com`)).toBe(false);
+      });
+
+      it('rejects double hyphen edge misuse (optional strict)', () => {
+        expect(isHostname('a--.com')).toBe(false);
+      });
+
+      it('rejects hostnames starting with dots', () => {
+        expect(isHostname('.example.com')).toBe(false);
+        expect(isHostname('.com')).toBe(false);
+      });
+
+      it('rejects hostnames ending with more than one dot', () => {
+        expect(isHostname('example.com..')).toBe(false);
+        expect(isHostname('sub.example.com..')).toBe(false);
+      });
+
+      it('rejects empty labels', () => {
+        expect(isHostname('example..com')).toBe(false);
+        expect(isHostname('.com')).toBe(false);
+        expect(isHostname('example..')).toBe(false);
+      });
+
+      it('rejects hostnames with only special characters', () => {
+        expect(isHostname('...')).toBe(false);
+        expect(isHostname('___')).toBe(false);
+        expect(isHostname('-')).toBe(false);
+        expect(isHostname('a-')).toBe(false); // ends with hyphen
+        expect(isHostname('-a')).toBe(false); // starts with hyphen
+      });
+
+      it('rejects invalid IPv4-like but numeric hostnames', () => {
+        expect(isHostname('256.256.256.256')).toBe(false);
+        expect(isHostname('999.1.1.1')).toBe(false);
+      });
+    });
+
+    describe('edge cases', () => {
+      it('handles trimmed whitespace', () => {
+        expect(isHostname(' example.com ')).toBe(true);
+        expect(isHostname('\tlocalhost\t')).toBe(true);
+        expect(isHostname(' 192.168.1.1 ')).toBe(true);
+      });
+
+      it('accepts single character labels', () => {
+        expect(isHostname('a.b.c')).toBe(true);
+        expect(isHostname('x')).toBe(true);
+      });
+
+      it('accepts all-numeric single label (hostname, not domain)', () => {
+        expect(isHostname('123')).toBe(true);
+        expect(isHostname('456789')).toBe(true);
+      });
+
+      it('rejects label with only hyphens', () => {
+        expect(isHostname('a-b')).toBe(true); // valid
+        expect(isHostname('-')).toBe(false); // only hyphen
+      });
+    });
+
+    describe('real-world examples', () => {
+      it('accepts common server hostnames', () => {
+        expect(isHostname('web-server-01')).toBe(true);
+        expect(isHostname('db1.prod.internal')).toBe(true);
+        expect(isHostname('api-gateway.eu-west-1.aws.com')).toBe(true);
+      });
+
+      it('accepts common TLDs', () => {
+        expect(isHostname('example.com')).toBe(true);
+        expect(isHostname('example.org')).toBe(true);
+        expect(isHostname('example.net')).toBe(true);
+        expect(isHostname('example.io')).toBe(true);
+        expect(isHostname('example.dev')).toBe(true);
+        expect(isHostname('example.app')).toBe(true);
+      });
+    });
+  });
+
   describe('isCreditCard', () => {
     it('returns true for valid credit card numbers', () => {
       expect(isCreditCard('4111 1111 1111 1111')).toBe(true);