ip-addresses

An ES6 module to facilitate working with IP addresses, ranges, subnets and iterations.

1. Introduction
2. Installation
3. Usage
4. Errors
5. API
   5.1 Class: IPv4Address
       5.1.1 Property: value
       5.1.2 Property: class
       5.1.3 Property: private
       5.1.4 Method: toString
       5.1.5 Method: toBin
       5.1.6 Method: toArray
       5.1.7 Method: mask
   5.2 Class: IPv4Subnetmask
       5.2.1 Property: value
       5.2.2 Property: length
       5.2.3 Method: toString
       5.2.4 Method: toBin
       5.2.5 Method: toArray
       5.2.6 Method: invert
   5.3 Class: IPv4Range
       5.3.1 Property: firstAddress
       5.3.2 Property: lastAddress
       5.3.3 Property: length
       5.3.4 Method: contains
       5.3.5 Method: getIterator
   5.4 Class: IPv4Subnet
       5.4.1 Property: subnetMask
       5.4.2 Property: networkAddress
       5.4.3 Property: broadcastAddress
       5.4.4 Property: hosts
       5.3.5 Method: getHostsIterator
   

Introduction

This module facilitates working with IP addresses (v4 only).

Installation

$ npm install ip-addresses

Usage

IPv4 Addresses

All IPv4Address instances are created through IPAddresses.ipv4.address().

let IPAddresses = require('../index.js');

// Create an IPv4 address
let ip1 = IPAddresses.v4.address('192.168.1.1');
let ip2 = IPAddresses.v4.address([192, 168, 1, 1]);
let ip3 = IPAddresses.v4.address(ip1); // creates a duplicate

// Get the value for an addres
console.log(ip1.value);                 // yields 3232235777
console.log(ip1.toString());            // yields 192.168.1.1
console.log(ip1.toString(true));        // yields 192.168.001.001
console.log(ip1.toBin());               // yields 11000000101010000000000100000001
console.log(ip1.toBin(' '));            // yields 11000000 10101000 00000001 00000001
console.log(ip1.toBin('.'));            // yields 11000000.10101000.00000001.00000001
console.log(ip1.toArray());             // yields [192,168,1,1]

console.log(IPAddresses.v4.address('10.0.0.0').class);       // yields A
console.log(IPAddresses.v4.address('128.0.0.0').class);      // yields B
console.log(IPAddresses.v4.address('192.0.0.0').class);      // yields C
console.log(IPAddresses.v4.address('224.0.0.0').class);      // yields D
console.log(IPAddresses.v4.address('240.0.0.0').class);      // yields E

console.log(IPAddresses.v4.address('10.0.0.0').private);     // yields true
console.log(IPAddresses.v4.address('11.0.0.0').private);     // yields false
console.log(IPAddresses.v4.address('192.168.0.0').private);  // yields true
console.log(IPAddresses.v4.address('172.25.0.0').private);   // yields true
console.log(IPAddresses.v4.address('172.32.0.0').private);   // yields false

IPv4 Subnet masks

All IPv4Subnetmask instances are created through IPAddresses.ipv4.subnetmask().

let IPAddresses = require('../index.js');

// Create an IPv4 subnet mask
let sm1 = IPAddresses.v4.subnetmask('255.255.255.0');
let sm2 = IPAddresses.v4.subnetmask([255, 255, 255, 0]);
let sm3 = IPAddresses.v4.subnetmask(24);
let sm4 = IPAddresses.v4.subnetmask(sm1); // creates a duplicate

// Get the value for an addres
console.log(sm1.value);          // yields 4294967040
console.log(sm1.toString());     // yields 255.255.255.0
console.log(sm1.toString(true)); // yields 255.255.255.000
console.log(sm1.toBin());        // yields 11111111111111111111111100000000
console.log(sm1.toBin(' '));     // yields 11111111 11111111 11111111 00000000
console.log(sm1.toBin('.'));     // yields 11111111.11111111.11111111.00000000
console.log(sm1.toArray());      // yields [255,255,255,0]
console.log(sm1.length);         // yields 24

IPv4 Ranges

All IPv4Range instances are created through IPAddresses.ipv4.range().

let IPAddresses = require('../index.js');

// Create an IPv4 range
let range1 = IPAddresses.v4.range('192.168.1.10-192.168.1.19');
let range2 = IPAddresses.v4.range(range1); // creates a duplicate

// Get the value for an addres
console.log(range1.firstAddress.toString());  // yields 192.168.1.10
console.log(range1.lastAddress.toString());   // yields 192.168.1.19
console.log(range1.length);                   // yields 10
console.log(range1.contains('192.168.1.9'));  // yields false
console.log(range1.contains('192.168.1.11')); // yields true

let iterator = range1.getIterator();
let item;
while(!(item = iterator.next()).done)
    console.log(item.value.toString());
// yields 192.168.1.10
// yields 192.168.1.11
// yields 192.168.1.12
// yields 192.168.1.13
// yields 192.168.1.14
// yields 192.168.1.15
// yields 192.168.1.16
// yields 192.168.1.17
// yields 192.168.1.18
// yields 192.168.1.19

IPv4 Subnets

All IPv4Subnet instances are created through IPAddresses.ipv4.subnet().

let IPAddresses = require('../index.js');

// Create an IPv4 range
let sn1 = IPAddresses.v4.subnet('192.168.1.10/24');
let sn2 = IPAddresses.v4.subnet('192.168.1.10/255.255.255.0');
let sn3 = IPAddresses.v4.range(sn1); // creates a duplicate

// Get the value for an addres
console.log(sn1.firstAddress.toString());      // yields 192.168.1.0
console.log(sn1.networkAddress.toString());    // yields 192.168.1.0
console.log(sn1.lastAddress.toString());       // yields 192.168.1.255
console.log(sn1.broadcastAddress.toString());  // yields 192.168.1.255
console.log(sn1.length);                       // yields 256
console.log(sn1.hosts);                        // yields 254
console.log(sn1.contains('192.168.2.9'));      // yields false
console.log(sn1.contains('192.168.1.11'));     // yields true

let iterator = sn1.getHostsIterator();
let item;
while(!(item = iterator.next()).done)
    console.log(item.value.toString());
// yields 192.168.1.1
// yields 192.168.1.2
// yields 192.168.1.3
// ...
// yields 192.168.1.252
// yields 192.168.1.253
// yields 192.168.1.254

Errors

The API throws IPv4Error objects during the creation of new instances if the specification for a new address, subnet mask, range or subnet is invalid. IPv4Error is an extention of Error. IPv4Error is further extended into IPv4AddressError, IPv4SubnetmaskError, IPv4RangeError and IPv4SubnetError.

let IPAddresses = require('../index.js');

try {
    let ip0 = IPAddresses.v4.address('192.168.1');
}
catch(e) {
    console.log(e.constructor.name);    // yields IPv4AddressError
}

try {
    let sm0 = IPAddresses.v4.subnetmask('255.255.255.1');
}
catch(e) {
    console.log(e.constructor.name);    // yields IPv4SubnetmaskError
}

try {
    let range0 = IPAddresses.v4.range('192.168.1.0-192.168.1.2.3');
}
catch(e) {
    console.log(e.constructor.name);    // yields IPv4RangeError
}

try {
    let sn0 = IPAddresses.v4.subnet('192.168.1.1/65');
}
catch(e) {
    console.log(e.constructor.name);    // yields IPv4SubnetError
}

API

Class: IPv4Address

This class represents an IPv4 address, typically defined by a single 32bit unsigned integer.

Property: value

Readonly. The 32bit unsigned integer that representst the address.

Property: class

Readonly. The class of the IP address, A through E.

Property: private

Readonly. True if the IP address is in a private range. False otherwise.

Method: toString(use3Digits)

Returns the address in octet format, e.g. 192.168.1.1. If use3Digits is true toString() returns all octets left padded with zeros, e.g. 192.168.001.001.

Method: toBin(separator)

Returns the address in binary format, e.g. 11000000101010000000000100000001. If separator is set then its first character is used as a separator between the octets, e.g. 11000000 10101000 00000001 00000001 for a space character or 11000000.10101000.00000001.00000001 for a dot.

Method: toArray()

Returns the address as an array, e.g. [ 192, 168, 1, 1 ].

Method: mask(subnetmask)

Returns a new IPv4Address object with its address set to that of the original address masked against the given subnet mask, e.g. 192.168.0.0 for a subnet mask 255.255.0.0. The subnetmask may be specified as an IPv4Subnetmask, a string e.g. 255.255.0.0 or an integer specifying the number of bits occupied by the mask.

Class: IPv4Subnetmask

This class represents an IPv4 subnet mask, typically defined by a single 32bit unsigned integer.

Property: value

Readonly. The 32bit unsigned integer that representst the mask.

Property: length

Readonly. The length of the subnet mask (the number of 1's in the binary representation).

Method: toString(use3Digits)

Returns the mask in octet format, e.g. 255.255.255.0. If use3Digits is true toString() returns all octets left padded with zeros, e.g. 255.255.255.000.

Method: toBin(separator)

Returns the mask in binary format, e.g. 11111111111111111111111100000000. If separator is set then its first character is used as a separator between the octets, e.g. 11111111 11111111 11111111 00000000 for a space character or 11111111.11111111.11111111.00000000 for a dot.

Method: toArray()

Returns the mask as an array, e.g. [ 192, 168, 1, 1 ].

Method: invert()

Returns a new Subnet mask with its mask set to be the inversion of the original mask.

Class: IPv4Range

This class represents a range typically used for iteration. It is also the base class for IPv4Subnetmask.

Property: firstAddress

Readonly. An IPv4Address representing the first address in the range.

Property: lastAddress

Readonly. An IPv4Address representing the last address in the range.

Property: length

Readonly. The number of addresses that exist in the range.

Method: contains(ip)

Returns true if the given ip address is inside the range. false otherwise. The ip address can be specified as an IPv4Address, a string or an array.

Method: getIterator()

Returns an ES6 Generator object to iterate over all addresses in the range. Used like so to list all hosts in the 192.168.1.0 subnet:

let iterator = range1.getIterator();
let item;
while(!(item = iterator.next()).done)
    console.log(item.value.toString());

Class: IPv4Subnet

This is an extention of IPv4Range with specific data to represent a subnet. All properties and methods from IPv4Range are available.

Property: subnetMask

Readonly. An IPv4Subnetmask that specifies the mask used for this subnet.

Property: networkAddress

Readonly. An IPv4Address that specifies the network address of the subnet. This is identical to firstAddress.

Property: broadcastAddress

Readonly. An IPv4Address that specifies the broadcast address of the subnet. This is identical to lastAddress.

Property: hosts

Readonly. The number of hosts present in the subnet. This is always equal to length - 2.

Method: getHostsIterator()

Similar to getIterator() except that this specific iterator skips the networkAddress and broadcastAddress to as only to iterate hosts.