1# ipaddr.js — an IPv6 and IPv4 address manipulation library [![Build Status](https://travis-ci.org/whitequark/ipaddr.js.svg)](https://travis-ci.org/whitequark/ipaddr.js)
  2
  3ipaddr.js is a small (1.9K minified and gzipped) library for manipulating
  4IP addresses in JavaScript environments. It runs on both CommonJS runtimes
  5(e.g. [nodejs]) and in a web browser.
  6
  7ipaddr.js allows you to verify and parse string representation of an IP
  8address, match it against a CIDR range or range list, determine if it falls
  9into some reserved ranges (examples include loopback and private ranges),
 10and convert between IPv4 and IPv4-mapped IPv6 addresses.
 11
 12[nodejs]: http://nodejs.org
 13
 14## Installation
 15
 16`npm install ipaddr.js`
 17
 18## API
 19
 20ipaddr.js defines one object in the global scope: `ipaddr`. In CommonJS,
 21it is exported from the module:
 22
 23```js
 24var ipaddr = require('ipaddr.js');
 25```
 26
 27The API consists of several global methods and two classes: ipaddr.IPv6 and ipaddr.IPv4.
 28
 29### Global methods
 30
 31There are three global methods defined: `ipaddr.isValid`, `ipaddr.parse` and
 32`ipaddr.process`. All of them receive a string as a single parameter.
 33
 34The `ipaddr.isValid` method returns `true` if the address is a valid IPv4 or
 35IPv6 address, and `false` otherwise. It does not throw any exceptions.
 36
 37The `ipaddr.parse` method returns an object representing the IP address,
 38or throws an `Error` if the passed string is not a valid representation of an
 39IP address.
 40
 41The `ipaddr.process` method works just like the `ipaddr.parse` one, but it
 42automatically converts IPv4-mapped IPv6 addresses to their IPv4 couterparts
 43before returning. It is useful when you have a Node.js instance listening
 44on an IPv6 socket, and the `net.ivp6.bindv6only` sysctl parameter (or its
 45equivalent on non-Linux OS) is set to 0. In this case, you can accept IPv4
 46connections on your IPv6-only socket, but the remote address will be mangled.
 47Use `ipaddr.process` method to automatically demangle it.
 48
 49### Object representation
 50
 51Parsing methods return an object which descends from `ipaddr.IPv6` or
 52`ipaddr.IPv4`. These objects share some properties, but most of them differ.
 53
 54#### Shared properties
 55
 56One can determine the type of address by calling `addr.kind()`. It will return
 57either `"ipv6"` or `"ipv4"`.
 58
 59An address can be converted back to its string representation with `addr.toString()`.
 60Note that this method:
 61 * does not return the original string used to create the object (in fact, there is
 62   no way of getting that string)
 63 * returns a compact representation (when it is applicable)
 64
 65A `match(range, bits)` method can be used to check if the address falls into a
 66certain CIDR range.
 67Note that an address can be (obviously) matched only against an address of the same type.
 68
 69For example:
 70
 71```js
 72var addr = ipaddr.parse("2001:db8:1234::1");
 73var range = ipaddr.parse("2001:db8::");
 74
 75addr.match(range, 32); // => true
 76```
 77
 78Alternatively, `match` can also be called as `match([range, bits])`. In this way,
 79it can be used together with the `parseCIDR(string)` method, which parses an IP
 80address together with a CIDR range.
 81
 82For example:
 83
 84```js
 85var addr = ipaddr.parse("2001:db8:1234::1");
 86
 87addr.match(ipaddr.parseCIDR("2001:db8::/32")); // => true
 88```
 89
 90A `range()` method returns one of predefined names for several special ranges defined
 91by IP protocols. The exact names (and their respective CIDR ranges) can be looked up
 92in the source: [IPv6 ranges] and [IPv4 ranges]. Some common ones include `"unicast"`
 93(the default one) and `"reserved"`.
 94
 95You can match against your own range list by using
 96`ipaddr.subnetMatch(address, rangeList, defaultName)` method. It can work with both
 97IPv6 and IPv4 addresses, and accepts a name-to-subnet map as the range list. For example:
 98
 99```js
100var rangeList = {
101  documentationOnly: [ ipaddr.parse('2001:db8::'), 32 ],
102  tunnelProviders: [
103    [ ipaddr.parse('2001:470::'), 32 ], // he.net
104    [ ipaddr.parse('2001:5c0::'), 32 ]  // freenet6
105  ]
106};
107ipaddr.subnetMatch(ipaddr.parse('2001:470:8:66::1'), rangeList, 'unknown'); // => "he.net"
108```
109
110The addresses can be converted to their byte representation with `toByteArray()`.
111(Actually, JavaScript mostly does not know about byte buffers. They are emulated with
112arrays of numbers, each in range of 0..255.)
113
114```js
115var bytes = ipaddr.parse('2a00:1450:8007::68').toByteArray(); // ipv6.google.com
116bytes // => [42, 0x00, 0x14, 0x50, 0x80, 0x07, 0x00, <zeroes...>, 0x00, 0x68 ]
117```
118
119The `ipaddr.IPv4` and `ipaddr.IPv6` objects have some methods defined, too. All of them
120have the same interface for both protocols, and are similar to global methods.
121
122`ipaddr.IPvX.isValid(string)` can be used to check if the string is a valid address
123for particular protocol, and `ipaddr.IPvX.parse(string)` is the error-throwing parser.
124
125[IPv6 ranges]: https://github.com/whitequark/ipaddr.js/blob/master/src/ipaddr.coffee#L186
126[IPv4 ranges]: https://github.com/whitequark/ipaddr.js/blob/master/src/ipaddr.coffee#L71
127
128#### IPv6 properties
129
130Sometimes you will want to convert IPv6 not to a compact string representation (with
131the `::` substitution); the `toNormalizedString()` method will return an address where
132all zeroes are explicit.
133
134For example:
135
136```js
137var addr = ipaddr.parse("2001:0db8::0001");
138addr.toString(); // => "2001:db8::1"
139addr.toNormalizedString(); // => "2001:db8:0:0:0:0:0:1"
140```
141
142The `isIPv4MappedAddress()` method will return `true` if this address is an IPv4-mapped
143one, and `toIPv4Address()` will return an IPv4 object address.
144
145To access the underlying binary representation of the address, use `addr.parts`.
146
147```js
148var addr = ipaddr.parse("2001:db8:10::1234:DEAD");
149addr.parts // => [0x2001, 0xdb8, 0x10, 0, 0, 0, 0x1234, 0xdead]
150```
151
152#### IPv4 properties
153
154`toIPv4MappedAddress()` will return a corresponding IPv4-mapped IPv6 address.
155
156To access the underlying representation of the address, use `addr.octets`.
157
158```js
159var addr = ipaddr.parse("192.168.1.1");
160addr.octets // => [192, 168, 1, 1]
161```