feat: expanded IP address format conversion functions

* added conversions from V4 to V6 mapped, both Dec and hex types.
* Added isX for mappedV4 dec and hex.
added a helper toCanonicalIp to convert all format types to the canonical form.

* Related #18

[ci skip]

Author: tegefaulkes

src/utils.ts

@@ -54,17 +54,52 @@ function isIPv4MappedIPv6(host: string): host is Host {
   return false;
 }
 
+function isIPv4MappedIPv6Hex(host: string): host is Host {
+  if (host.startsWith('::ffff:')) {
+    try {
+      // The `ip-num` package understands `::ffff:7f00:1`
+      IPv6.fromString(host);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+function isIPv4MappedIPv6Dec(host: string): host is Host {
+  if (host.startsWith('::ffff:')) {
+    // But it does not understand `::ffff:127.0.0.1`
+    const ipv4 = host.slice('::ffff:'.length);
+    if (isIPv4(ipv4)) {
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Takes an IPv4 address and returns the IPv4 mapped IPv6 address.
  * This produces the dotted decimal variant.
  */
-function toIPv4MappedIPv6(host: string): Host {
+function toIPv4MappedIPv6Dec(host: string): Host {
   if (!isIPv4(host)) {
     throw new TypeError('Invalid IPv4 address');
   }
   return ('::ffff:' + host) as Host;
 }
 
+/**
+ * Takes an IPv4 address and returns the IPv4 mapped IPv6 address.
+ * This produces the dotted Hexidecimal variant.
+ */
+function toIPv4MappedIPv6Hex(host: string): Host {
+  if (!isIPv4(host)) {
+    throw new TypeError('Invalid IPv4 address');
+  }
+  return IPv4.fromString(host).toIPv4MappedIPv6().toString() as Host;
+}
+
 /**
  * Extracts the IPv4 portion out of the IPv4 mapped IPv6 address.
  * Can handle both the dotted decimal and hex variants.
@@ -87,6 +122,20 @@ function fromIPv4MappedIPv6(host: string): Host {
   return ipv4Decs.join('.') as Host;
 }
 
+/**
+ * This converts all `IPv4` formats to the `IPv4` decimal format.
+ * `IPv4` decimal and `IPv6` hex formatted IPs are left unchanged.
+ */
+function toCanonicalIp(host: string) {
+  if (isIPv4MappedIPv6(host)) {
+    return fromIPv4MappedIPv6(host);
+  }
+  if (isIPv4(host) || isIPv6(host)) {
+    return host;
+  }
+  throw new TypeError('Invalid IP address');
+}
+
 /**
  * This will resolve a hostname to the first host.
  * It could be an IPv6 address or IPv4 address.
@@ -226,7 +275,7 @@ function resolvesZeroIP(host: Host): Host {
   if (isIPv4MappedIPv6(host)) {
     const ipv4 = fromIPv4MappedIPv6(host);
     if (new IPv4(ipv4).isEquals(zeroIPv4)) {
-      return toIPv4MappedIPv6('127.0.0.1');
+      return toIPv4MappedIPv6Dec('127.0.0.1');
     } else {
       return host;
     }
@@ -273,8 +322,12 @@ export {
   isIPv4,
   isIPv6,
   isIPv4MappedIPv6,
-  toIPv4MappedIPv6,
+  isIPv4MappedIPv6Hex,
+  isIPv4MappedIPv6Dec,
+  toIPv4MappedIPv6Dec,
+  toIPv4MappedIPv6Hex,
   fromIPv4MappedIPv6,
+  toCanonicalIp,
   resolveHostname,
   resolveHost,
   promisify,

tests/utils.test.ts

@@ -12,13 +12,45 @@ describe('utils', () => {
     expect(utils.isIPv4MappedIPv6('::ffff:7f00:800')).toBe(true);
     expect(utils.isIPv4MappedIPv6('::ffff:255.255.255.255')).toBe(true);
   });
-  test('to and from IPv4 mapped IPv6 addresses', () => {
-    expect(utils.toIPv4MappedIPv6('127.0.0.1')).toBe('::ffff:127.0.0.1');
-    expect(utils.toIPv4MappedIPv6('0.0.0.0')).toBe('::ffff:0.0.0.0');
-    expect(utils.toIPv4MappedIPv6('255.255.255.255')).toBe(
+  test('detect IPv4 mapped IPv6 Dec addresses', () => {
+    expect(utils.isIPv4MappedIPv6Dec('::ffff:127.0.0.1')).toBe(true);
+    expect(utils.isIPv4MappedIPv6Dec('::ffff:7f00:1')).toBe(false);
+    expect(utils.isIPv4MappedIPv6Dec('::')).toBe(false);
+    expect(utils.isIPv4MappedIPv6Dec('::1')).toBe(false);
+    expect(utils.isIPv4MappedIPv6Dec('127.0.0.1')).toBe(false);
+    expect(utils.isIPv4MappedIPv6Dec('::ffff:4a7d:2b63')).toBe(false);
+    expect(utils.isIPv4MappedIPv6Dec('::ffff:7f00:800')).toBe(false);
+    expect(utils.isIPv4MappedIPv6Dec('::ffff:255.255.255.255')).toBe(true);
+  });
+  test('detect IPv4 mapped IPv6 Hex addresses', () => {
+    expect(utils.isIPv4MappedIPv6Hex('::ffff:127.0.0.1')).toBe(false);
+    expect(utils.isIPv4MappedIPv6Hex('::ffff:7f00:1')).toBe(true);
+    expect(utils.isIPv4MappedIPv6Hex('::')).toBe(false);
+    expect(utils.isIPv4MappedIPv6Hex('::1')).toBe(false);
+    expect(utils.isIPv4MappedIPv6Hex('127.0.0.1')).toBe(false);
+    expect(utils.isIPv4MappedIPv6Hex('::ffff:4a7d:2b63')).toBe(true);
+    expect(utils.isIPv4MappedIPv6Hex('::ffff:7f00:800')).toBe(true);
+    expect(utils.isIPv4MappedIPv6Hex('::ffff:255.255.255.255')).toBe(false);
+  });
+  test('to IPv4 mapped IPv6 addresses Dec', () => {
+    expect(utils.toIPv4MappedIPv6Dec('127.0.0.1')).toBe('::ffff:127.0.0.1');
+    expect(utils.toIPv4MappedIPv6Dec('0.0.0.0')).toBe('::ffff:0.0.0.0');
+    expect(utils.toIPv4MappedIPv6Dec('255.255.255.255')).toBe(
       '::ffff:255.255.255.255',
     );
-    expect(utils.toIPv4MappedIPv6('74.125.43.99')).toBe('::ffff:74.125.43.99');
+    expect(utils.toIPv4MappedIPv6Dec('74.125.43.99')).toBe(
+      '::ffff:74.125.43.99',
+    );
+  });
+  test('to IPv4 mapped IPv6 addresses Hex', () => {
+    expect(utils.toIPv4MappedIPv6Hex('127.0.0.1')).toBe('::ffff:7f00:1');
+    expect(utils.toIPv4MappedIPv6Hex('0.0.0.0')).toBe('::ffff:0:0');
+    expect(utils.toIPv4MappedIPv6Hex('255.255.255.255')).toBe(
+      '::ffff:ffff:ffff',
+    );
+    expect(utils.toIPv4MappedIPv6Hex('74.125.43.99')).toBe('::ffff:4a7d:2b63');
+  });
+  test('from IPv4 mapped IPv6 addresses', () => {
     expect(utils.fromIPv4MappedIPv6('::ffff:7f00:1')).toBe('127.0.0.1');
     expect(utils.fromIPv4MappedIPv6('::ffff:127.0.0.1')).toBe('127.0.0.1');
     expect(utils.fromIPv4MappedIPv6('::ffff:0.0.0.0')).toBe('0.0.0.0');
@@ -35,9 +67,33 @@ describe('utils', () => {
     expect(utils.fromIPv4MappedIPv6('::ffff:0:0')).toBe('0.0.0.0');
     // Converting from ::ffff:7f00:1 to ::ffff:127.0.0.1
     expect(
-      utils.toIPv4MappedIPv6(utils.fromIPv4MappedIPv6('::ffff:7f00:1')),
+      utils.toIPv4MappedIPv6Dec(utils.fromIPv4MappedIPv6('::ffff:7f00:1')),
     ).toBe('::ffff:127.0.0.1');
   });
+  test('to canonical IP address', () => {
+    // IPv4 -> IPv4
+    expect(utils.toCanonicalIp('127.0.0.1')).toBe('127.0.0.1');
+    expect(utils.toCanonicalIp('0.0.0.0')).toBe('0.0.0.0');
+    expect(utils.toCanonicalIp('255.255.255.255')).toBe('255.255.255.255');
+    expect(utils.toCanonicalIp('74.125.43.99')).toBe('74.125.43.99');
+    // IPv4 mapped hex -> IPv4
+    expect(utils.toCanonicalIp('::ffff:7f00:1')).toBe('127.0.0.1');
+    expect(utils.toCanonicalIp('::ffff:0:0')).toBe('0.0.0.0');
+    expect(utils.toCanonicalIp('::ffff:ffff:ffff')).toBe('255.255.255.255');
+    expect(utils.toCanonicalIp('::ffff:4a7d:2b63')).toBe('74.125.43.99');
+    // IPv4 mapped dec -> IPv4
+    expect(utils.toCanonicalIp('::ffff:127.0.0.1')).toBe('127.0.0.1');
+    expect(utils.toCanonicalIp('::ffff:0.0.0.0')).toBe('0.0.0.0');
+    expect(utils.toCanonicalIp('::ffff:255.255.255.255')).toBe(
+      '255.255.255.255',
+    );
+    expect(utils.toCanonicalIp('::ffff:74.125.43.99')).toBe('74.125.43.99');
+    // IPv6 -> IPv6
+    expect(utils.toCanonicalIp('::1234:7f00:1')).toBe('::1234:7f00:1');
+    expect(utils.toCanonicalIp('::1234:0:0')).toBe('::1234:0:0');
+    expect(utils.toCanonicalIp('::1234:ffff:ffff')).toBe('::1234:ffff:ffff');
+    expect(utils.toCanonicalIp('::1234:4a7d:2b63')).toBe('::1234:4a7d:2b63');
+  });
   test('resolves zero IP to local IP', () => {
     expect(utils.resolvesZeroIP('0.0.0.0' as Host)).toBe('127.0.0.1');
     expect(utils.resolvesZeroIP('::' as Host)).toBe('::1');