# netparser
## Parse and manipulate IPv4 and IPv6 network addresses
[](https://travis-ci.org/demskie/netparser) [](https://coveralls.io/github/demskie/netparser?branch=master)
[](https://david-dm.org/demskie/netparser#info=dependencies&view=table)
## Installation
```bash
npm install netparser
```
## Examples
```js
import * as netparser from 'netparser';
netparser.baseAddress('b011:a2c2:7328:cc01:4ee7:e2ec:6269:babf/73');
// returns 'b011:a2c2:7328:cc01:4e80::'
netparser.broadcastAddress('192.168.0.50/24');
// returns '192.168.0.255'
netparser.findUnusedSubnets('192.168.0.0/22', ['192.168.1.0/24', '192.168.2.32/30']);
// returns ['192.168.0.0/24', '192.168.2.0/27', '192.168.2.36/30', '192.168.2.40/29', '192.168.2.48/28', '192.168.2.64/26', '192.168.2.128/25', '192.168.3.0/24']
netparser.ip(' [2001:db8:122:344:0:0:0::0:0:0:1] ');
// returns '2001:db8:122:344::1'
netparser.network(' 192.168.000.000/24 ');
// returns '192.168.0.0/24'
netparser.networkComesBefore('192.168.0.0/24', '10.0.0.0/8');
// returns false
netparser.networkContainsSubnet('192.168.0.0/16', '192.168.0.0/24');
// returns true
netparser.networksIntersect('192.168.0.0/23', '192.168.1.0/24');
// returns true
netparser.nextAddress('192.168.0.0');
// returns '192.168.0.1'
netparser.nextNetwork('192.168.0.0/24');
// returns '192.168.1.0/24'
netparser.rangeOfNetworks('192.168.1.2', '192.168.2.2');
// returns ['192.168.1.2/31', '192.168.1.4/30', '192.168.1.8/29', '192.168.1.16/28', '192.168.1.32/27', '192.168.1.64/26', '192.168.1.128/25', '192.168.2.0/31', '192.168.2.2/32']
netparser.sort(['255.255.255.255', '192.168.0.0/16', '192.168.2.3/31']);
// returns ['192.168.0.0/16', '192.168.2.3/31', '255.255.255.255/32']
netparser.summarize(['192.168.1.1', '192.168.0.0/16', '192.168.2.3/31']);
// returns ['192.168.0.0/16']
var matcher = new netparser.Matcher(['192.168.0.0/24', '192.168.2.0/23', '192.168.4.0/24']);
matcher.has('192.168.3.0');
// returns true
```
## FYI
- For simplicity, all functions will only ever return `String, String[], boolean, or null`.
- By default the library will fail silently and `null` is returned when errors are encountered. To override this setting set the optional `throwErrors` parameter to `True`.
- By default the library will conveniently mask out provided `network` values to their base address when such an operation makes sense. To override this setting set the optional `strict` parameter to `True` where applicable.
## Benchmarks
```bash
npm run bench
'index.bench.ts' output:
baseAddress (netparser) x 1,881,378 ops/sec ±0.66% (95 runs sampled)
baseAddress (ip-address) x 1,355,975 ops/sec ±0.64% (88 runs sampled)
baseAddress (ipaddr.js) x 509,825 ops/sec ±2.07% (89 runs sampled)
baseAddress (netmask) x 326,042 ops/sec ±3.84% (82 runs sampled)
contains (netparser) x 883,418 ops/sec ±1.53% (84 runs sampled)
contains (ip-address) x 901,704 ops/sec ±1.44% (90 runs sampled)
contains (ipaddr.js) x 59,005 ops/sec ±13.38% (65 runs sampled)
contains (netmask) x 304,785 ops/sec ±1.77% (88 runs sampled)
'match.bench.ts' output:
create (netparser) x 11.91 ops/sec ±5.55% (34 runs sampled)
create (cidr-matcher) x 5.13 ops/sec ±5.43% (17 runs sampled)
create (ipaddr.js) x 28.78 ops/sec ±4.83% (50 runs sampled)
query (netparser) x 145,604 ops/sec ±1.25% (91 runs sampled)
query (cidr-matcher) x 1,035 ops/sec ±3.74% (83 runs sampled)
query (ipaddr.js) x 16.22 ops/sec ±1.76% (44 runs sampled)
```
## API
Docs generated using [`docts`](https://github.com/charto/docts)
>
>
> ### Function [`baseAddress`](#api-baseAddress)
> BaseAddress returns the base address for a given subnet address
> Source code: [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L22-L27)
> > **baseAddress( )** ⇒ null | string [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L22-L27)
> > ▪ networkAddress string - A network address like 192.168.0.4/24
> > ▫ throwErrors? undefined | true | false - Stop the library from failing silently
>
>
> ### Function [`broadcastAddress`](#api-broadcastAddress)
> BroadcastAddress returns the broadcast address for an IPv4 address.
> Please note that IPv6 does not have broadcast addresses.
> Source code: [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L41-L46)
> > **broadcastAddress( )** ⇒ null | string [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L41-L46)
> > ▪ network string - A network like 192.168.0.0/24
> > ▫ throwErrors? undefined | true | false - Stop the library from failing silently
>
>
> ### Function [`findUnusedSubnets`](#api-findUnusedSubnets)
> FindUnusedSubnets returns array of unused subnets given the aggregate and sibling subnets
> Source code: [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L61-L78)
> > **findUnusedSubnets( )** ⇒ null | string[] [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L61-L78)
> > ▪ aggregate string - An aggregate network like 192.168.0.0/24
> > ▪ subnets string[] - Array of subnetworks like ["192.168.0.0/24", "192.168.0.128/26"]
> > ▫ strict? undefined | true | false - Do not automatically mask addresses to baseAddresses
> > ▫ throwErrors? undefined | true | false - Stop the library from failing silently
>
>
> ### Function [`ip`](#api-ip)
> Parse an IP address
> Source code: [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L91-L94)
> > **ip( )** ⇒ null | string [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L91-L94)
> > ▪ address string - Either an address like 192.168.0.0 or subnet 192.168.0.0/24
> > ▫ throwErrors? undefined | true | false - Stop the library from failing silently
>
>
> ### Function [`network`](#api-network)
> Parse a network address
> Source code: [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L107-L110)
> > **network( )** ⇒ null | string [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L107-L110)
> > ▪ networkAddress string - A network like 192.168.0.0/24
> > ▫ throwErrors? undefined | true | false - Stop the library from failing silently
>
>
> ### Function [`networkComesBefore`](#api-networkComesBefore)
> NetworkComesBefore returns a bool with regards to numerical network order.
> Please note that IPv4 comes before IPv6 and larger networks come before smaller ones.
> Source code: [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L126-L139)
> > **networkComesBefore( )** ⇒ null | true | false [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L126-L139)
> > ▪ network string - A network like 192.168.0.0/24
> > ▪ otherNetwork string - A network like 192.168.1.0/24
> > ▫ strict? undefined | true | false - Do not automatically mask addresses to baseAddresses
> > ▫ throwErrors? undefined | true | false - Stop the library from failing silently
>
>
> ### Function [`networkContainsAddress`](#api-networkContainsAddress)
> NetworkContainsAddress validates that the address is inside the network
> Source code: [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L154-L164)
> > **networkContainsAddress( )** ⇒ null | true | false [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L154-L164)
> > ▪ network string - A network like 192.168.0.0/24
> > ▪ address string - A network like 192.168.0.100
> > ▫ strict? undefined | true | false - Do not automatically mask addresses to baseAddresses
> > ▫ throwErrors? undefined | true | false - Stop the library from failing silently
>
>
> ### Function [`networkContainsSubnet`](#api-networkContainsSubnet)
> NetworkContainsSubnet validates that the network is a valid supernet
> Source code: [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L179-L185)
> > **networkContainsSubnet( )** ⇒ null | true | false [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L179-L185)
> > ▪ network string - A network like 192.168.0.0/16
> > ▪ subnet string - A network like 192.168.0.0/24
> > ▫ strict? undefined | true | false - Do not automatically mask addresses to baseAddresses
> > ▫ throwErrors? undefined | true | false - Stop the library from failing silently
>
>
> ### Function [`networksIntersect`](#api-networksIntersect)
> NetworksIntersect returns a bool showing if the networks overlap
> Source code: [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L200-L206)
> > **networksIntersect( )** ⇒ null | true | false [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L200-L206)
> > ▪ network string - A network like 192.168.0.0/23
> > ▪ otherNetwork string - A network like 192.168.1.0/24
> > ▫ strict? undefined | true | false - Do not automatically mask addresses to baseAddresses
> > ▫ throwErrors? undefined | true | false - Stop the library from failing silently
>
>
> ### Function [`nextAddress`](#api-nextAddress)
> NextAddress returns the next address
> Source code: [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L219-L227)
> > **nextAddress( )** ⇒ null | string [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L219-L227)
> > ▪ address string - An address like 192.168.0.0
> > ▫ throwErrors? undefined | true | false - Stop the library from failing silently
>
>
> ### Function [`nextNetwork`](#api-nextNetwork)
> NextNetwork returns the next network of the same size.
> Source code: [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L241-L249)
> > **nextNetwork( )** ⇒ null | string [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L241-L249)
> > ▪ network string - A network like 192.168.0.0/24
> > ▫ strict? undefined | true | false - Do not automatically mask addresses to baseAddresses
> > ▫ throwErrors? undefined | true | false - Stop the library from failing silently
>
>
> ### Function [`rangeOfNetworks`](#api-rangeOfNetworks)
> RangeOfNetworks returns an array of networks given a range of addresses
> Source code: [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L263-L288)
> > **rangeOfNetworks( )** ⇒ null | string[] [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L263-L288)
> > ▪ startAddress string - An address like 192.168.1.2
> > ▪ stopAddress string - An address like 192.168.1.5
> > ▫ throwErrors? undefined | true | false - Stop the library from failing silently
>
>
> ### Function [`sort`](#api-sort)
> Sort returns an array of sorted networks
> Source code: [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L301-L329)
> > **sort( )** ⇒ null | string[] [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L301-L329)
> > ▪ networkAddresses string[] - An array of addresses or subnets
> > ▫ throwErrors? undefined | true | false - Stop the library from failing silently
>
>
> ### Function [`summarize`](#api-summarize)
> Summarize returns an array of aggregates given a list of networks
> Source code: [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L343-L363)
> > **summarize( )** ⇒ null | string[] [`<>`](http://github.com/demskie/netparser/blob/63db838/src/index.ts#L343-L363)
> > ▪ networks string[] - An array of addresses or subnets
> > ▫ strict? undefined | true | false - Do not automatically mask addresses to baseAddresses
> > ▫ throwErrors? undefined | true | false - Stop the library from failing silently