@jnode/ip

Simple IP handling package for Node.js.

Installation

npm i @jnode/ip

Quick start

Import

const { IP, IPRange, IPRangeGroup } = require('@jnode/ip');

Basic IP parsing and formatting

const ipv4 = new IP('127.0.0.1');
console.log(ipv4.toString()); // '::ffff:127.0.0.1'

const ipv6 = new IP('2001:db8::1');
console.log(ipv6.toString()); // '2001:db8::1'

Check if an IP is within a range

const range = new IPRange('192.168.1.0/24');

// returns true
console.log(range.check('192.168.1.5'));

// using the IP instance method
const myIp = new IP('10.0.0.1');
console.log(myIp.within('10.0.0.0/8')); // true

How it works?

The package provides a high-performance way to handle IP addresses by converting them into BigInt representations.

1. BigInt Core: All IP addresses (IPv4 and IPv6) are stored as 128-bit integers.
2. Unified Handling: IPv4 addresses are automatically mapped to IPv6 (using the ::ffff:0:0/96 prefix) to allow seamless comparison and range checking across different protocols.
3. Standard Formatting: When converting back to a string, the package follows standard IPv6 compression rules (RFC 5952) to ensure the shortest valid representation.

This approach makes subnet calculations and IP comparisons extremely fast and reliable.

Reference

Class: ip.IP

Represents an IP address.

new ip.IP(address)

• address <string> | <bigint> | <ip.IP>
  • If a string, it can be an IPv4 (e.g., '127.0.0.1') or IPv6 (e.g., '::1').
  • If a bigint, it is treated as the raw 128-bit integer value.
  • If an IP instance, it clones the value.

ip.toString()

• Returns: <string>

Returns the string representation of the IP address. IPv4 addresses are returned in IPv4-mapped IPv6 format (e.g., ::ffff:1.2.3.4). IPv6 addresses are returned with zero compression where applicable.

ip.within(range)

• range <ip.IPRange> | <string>
• Returns: <boolean>

Checks if the IP address is within the specified CIDR range.

Class: ip.IPRange

Represents a CIDR range used for filtering or matching IP addresses.

new ip.IPRange(cidr)

• cidr <string> An IP address followed by a prefix length (e.g., '192.168.0.0/16' or '2001:db8::/32').

ipRange.check(ip)

• ip <ip.IP> | <string>
• Returns: <boolean>

Returns true if the provided IP address is within the CIDR range.

Class: ip.IPRangeGroup

A utility class to check an IP against multiple CIDR ranges simultaneously.

new ip.IPRangeGroup(ranges)

• ranges <Array> An array of CIDR strings or ip.IPRange instances.

ipRangeGroup.check(ip)

• ip <ip.IP> | <string>
• Returns: <boolean>

Returns true if the provided IP address matches any of the ranges in the group.