ip6addr

ip6addr

ip6addr is a small library for manipulating IP addresses in JavaScript. Inspired by ipaddr.js, ip6addr focuses on better IPv6 support, particularly in cases where IPv4 and IPv6 addresses are used together.

If you want to also parse and manipulate MAC addresses, see macaddr.

Installation

npm install ip6addr

API

parse(input)

Parse the input IP address, which can be either a string or an integer, and return a representative Addr. When the address is invalid, an explanatory Error is thrown.

> var addr1 = ip6addr.parse('fd00::0123')
> addr1.toString()
'fd00::123'
> var addr2 = ip6addr.parse('1.2.3.4')
> addr2.toString()
'1.2.3.4'
> var addr3 = ip6addr.parse('::ffff:127.0.0.1')
> addr3.toString()
'::ffff:127.0.0.1'

createCIDR(cidr, [plen])

Either parse a string in CIDR notation, such as '192.168.1.0/24', or, when given an address and a prefix length, create the representative CIDR. When it fails to parse, it throws an Error.

> var sub1 = ip6addr.createCIDR('fe80::/10')
> sub1.toString()
'fe80::/10'
> var sub2 = ip6addr.createCIDR('fc00::', 7)
> sub2.toString()
'fc00::/7'
> var sub3 = ip6addr.createCIDR('10.0.0.0', 8)
> sub3.toString()
'10.0.0.0/8'

createAddrRange(first, last)

Create an inclusive range of addresses from first address to last address, represented by an AddrRange. The first address must come before or be the same as the last address.

> var r1 = ip6addr.createAddrRange('fd00::123', 'fd00::ea00')
> r1.first().toString()
'fd00::123'
> r1.last().toString()
'fd00::ea00'

compare(addr1, addr2)

Compares one address with another, and returns:

• A negative number when addr1 comes before addr2
• A positive number when addr1 comes after addr2
• 0 when the two addresses are the same

IPv4 addresses are compared against IPv6 addresses in their IPv4-mapped form.

> [ 'fc00::123', '192.168.1.50', '10.0.1.76', '8.8.8.8', '::1' ].sort(ip6addr.compare)
[ '::1',
  '8.8.8.8',
  '10.0.1.76',
  '192.168.1.50',
  'fc00::123' ]

compareCIDR(cidr1, cidr2)

Compares one subnet with another. Subnets are compared first by their address component, and then by their prefix length. The network with the smaller prefix length (the larger subnet) is considered greater than the network with the larger prefix (the smaller subnet). Like compare(), this method returns:

• A negative number when subnet cidr1 comes before cidr2
• A positive number when subnet cidr1 comes after cidr2
• 0 when the two subnets are the same

> [ 'fc00::/7', '192.168.0.0/24', '192.168.0.0/16', '127.0.0.0/8', '::ffff:0.0.0.0/96' ].sort(ip6addr.compareCIDR)
[ '::ffff:0.0.0.0/96',
  '127.0.0.0/8',
  '192.168.0.0/24',
  '192.168.0.0/16',
  'fc00::/7' ]

Addr

An immutable representation of an IP address.

Addr#kind()

Returns the address family of the object, ipv4 or ipv6.

> ip6addr.parse('::1').kind()
'ipv6'
> ip6addr.parse('127.0.0.1').kind()
'ipv4'
> ip6addr.parse('::ffff:127.0.0.1').kind()
'ipv4'

Addr#toString([opts])

Return the string representation of this address. An options object can be passed to control how the address is formatted. Valid options are:

• format (default: auto), select the notation style to use when printing. Available options are:

  • 'auto', format using the notation style the address was parsed as
  • 'v4', format as an IPv4 address
  • 'v4-mapped', format as an IPv4-mapped IPv6 address
  • 'v6', format the string as IPv6 address

  Attempts to format an IPv6 address with 'v4' or 'v4-mapped' will throw an Error.

• zeroElide (default: true), whether to elide the longest run of zeros in IPv6 addresses as :: (e.g., '0:0:0:0:0:0:0:1' becomes '::1').

• zeroPad (default: false), if a field (also referred to as a "group" or "hextet") would print as less than four characters in an IPv6 address, whether or not to pad it with leading zeros (e.g., '::1' becomes '::0001')

> var addr = ip6addr.parse('::ffff:127.0.0.1')
> addr.toString({ format: 'auto' })
'::ffff:127.0.0.1'
> addr.toString({ format: 'v4' })
'127.0.0.1'
> addr.toString({ format: 'v4-mapped' })
'::ffff:127.0.0.1'
> addr.toString({ format: 'v6' })
'::ffff:7f00:1'
> addr.toString({ zeroElide: false })
'0:0:0:0:0:ffff:127.0.0.1'
> addr.toString({ zeroElide: false, zeroPad: true })
'0000:0000:0000:0000:0000:ffff:127.0.0.1'

Addr#toBuffer([buf])

Convert the address to a buffer of sixteen 16-bit integers, representing the IPv6 representation of this address. An alternate buffer to write to may be passed in instead, rather than creating a new one.

Addr#toLong()

Return the address represented as a 32-bit integer. If this address cannot be represented as a 32-bit integer (i.e., it's an IPv6 address), then this method will throw an Error.

> var addr = ip6addr.parse('127.0.0.1')
> addr.toLong()
2130706433

Addr#offset(num)

Calculate the offset by num from this address. If the offset would result in wrap-around, then this method returns null.

> var addr1 = ip6addr.parse('fd20::5')
> addr1.offset(1).toString()
'fd20::6'
> addr1.offset(-1).toString()
'fd20::4'
> addr1.offset(20).toString()
'fd20::19'
> addr1.offset(-20).toString()
'fd1f:ffff:ffff:ffff:ffff:ffff:ffff:fff1'
> ip6addr.parse('255.255.255.255').offset(1)
null
> ip6addr.parse('0.0.0.0').offset(-1)
null
> ip6addr.parse('::').offset(-1)
null

Addr#compare(other)

Compare another address to this one in the same manner as compare().

CIDR

An immutable representation of a subnet.

CIDR#contains(input)

Checks if this subnet contains the address input.

> var sub = ip6addr.createCIDR('fe80::', 10)
> sub.contains('fe80::92b8:d0ff:fe81:f590')
true
> sub.contains('fe80::507f:baff:fe85:92eb')
true
> sub.contains('2001:4860:4860::8888')
false
> sub.contains('172.16.20.5')
false
> sub.contains('::ffff:127.0.0.1')
false

CIDR#first()

Returns the first address in this subnet.

> var sub = ip6addr.createCIDR('fe80::', 10)
> sub.first().toString()
'fe80::1'

CIDR#last()

Returns the last address in this subnet. For IPv4 subnets, this is the address just before the broadcast address.

> var sub1 = ip6addr.createCIDR('fe80::', 10)
> sub1.last().toString()
'febf:ffff:ffff:ffff:ffff:ffff:ffff:ffff'
> var sub2 = ip6addr.createCIDR('192.168.1.0', 24)
> sub2.last().toString()
'192.168.1.254'

CIDR#broadcast()

Returns the broadcast address for this subnet. If the subnet doesn't have a broadcast address (i.e., it's an IPv6 subnet and therefore uses multicast), then this method throws an Error.

> var sub1 = ip6addr.createCIDR('192.168.1.0', 24)
> sub1.broadcast().toString()
'192.168.1.255'
> var sub2 = ip6addr.createCIDR('192.168.0.0', 16)
> sub2.broadcast().toString()
'192.168.255.255'

CIDR#compare(other)

Compare another subnet to this one in the same manner as compareCIDR().

CIDR#prefixLength()

Returns the prefix length of this subnet.

CIDR#address()

Returns the address component of this subnet.

CIDR#toString([opts])

Returns the string representation of this subnet. An options object can be passed to control how the subnet is formatted, using the same options that Addr#toString() takes.

AddrRange

An immutable representation of a range of addresses.

AddrRange#contains(addr)

Determines whether the input address falls within this address range.

> var range = ip6addr.createAddrRange('fd00::123', 'fd00::ea00')
undefined
> range.contains('fd00::123')
true
> range.contains('fd00::ea00')
true
> range.contains('fd00::b000')
true
> range.contains('fd00::122')
false
> range.contains('fd00::ea01')
false
> range.contains('8.8.8.8')
false

AddrRange#first()

Returns the first address in this range.

AddrRange#last()

Returns the last address in this range.

License

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. For the full license text see LICENSE, or http://mozilla.org/MPL/2.0/.

Copyright (c) 2019, Joyent, Inc.