@economist/netparser

netparser

Parse and manipulate IPv4 and IPv6 network addresses

Installation

npm install netparser

Examples

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

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

Function baseAddress

BaseAddress returns the base address for a given subnet address
Source code: <>

baseAddress( ) ^{⇒ null | string} <>
 ▪ networkAddress ^string - A network address like 192.168.0.4/24
 ▫ throwErrors_? ^{undefined | true | false} - Stop the library from failing silently

Function broadcastAddress

BroadcastAddress returns the broadcast address for an IPv4 address.
Please note that IPv6 does not have broadcast addresses.
Source code: <>

broadcastAddress( ) ^{⇒ null | string} <>
 ▪ network ^string - A network like 192.168.0.0/24
 ▫ throwErrors_? ^{undefined | true | false} - Stop the library from failing silently

Function findUnusedSubnets

FindUnusedSubnets returns array of unused subnets given the aggregate and sibling subnets
Source code: <>

findUnusedSubnets( ) ^{⇒ null | string[]} <>
 ▪ 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

Parse an IP address
Source code: <>

ip( ) ^{⇒ null | string} <>
 ▪ 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

Parse a network address
Source code: <>

network( ) ^{⇒ null | string} <>
 ▪ networkAddress ^string - A network like 192.168.0.0/24
 ▫ throwErrors_? ^{undefined | true | false} - Stop the library from failing silently

Function 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: <>

networkComesBefore( ) ^{⇒ null | true | false} <>
 ▪ 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

NetworkContainsAddress validates that the address is inside the network
Source code: <>

networkContainsAddress( ) ^{⇒ null | true | false} <>
 ▪ 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

NetworkContainsSubnet validates that the network is a valid supernet
Source code: <>

networkContainsSubnet( ) ^{⇒ null | true | false} <>
 ▪ 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

NetworksIntersect returns a bool showing if the networks overlap
Source code: <>

networksIntersect( ) ^{⇒ null | true | false} <>
 ▪ 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

NextAddress returns the next address
Source code: <>

nextAddress( ) ^{⇒ null | string} <>
 ▪ address ^string - An address like 192.168.0.0
 ▫ throwErrors_? ^{undefined | true | false} - Stop the library from failing silently

Function nextNetwork

NextNetwork returns the next network of the same size.
Source code: <>

nextNetwork( ) ^{⇒ null | string} <>
 ▪ 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

RangeOfNetworks returns an array of networks given a range of addresses
Source code: <>

rangeOfNetworks( ) ^{⇒ null | string[]} <>
 ▪ 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

Sort returns an array of sorted networks
Source code: <>

sort( ) ^{⇒ null | string[]} <>
 ▪ networkAddresses ^string[] - An array of addresses or subnets
 ▫ throwErrors_? ^{undefined | true | false} - Stop the library from failing silently

Function summarize

Summarize returns an array of aggregates given a list of networks
Source code: <>

summarize( ) ^{⇒ null | string[]} <>
 ▪ 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