Class: IPv4

The IPv4 toolkit: validate and convert the addresses (dotted decimal notation, integer, binary, hexadecimal, IPv4-mapped IPv6), parse the CIDR blocks and the subnet masks, compare the addresses and subnets, and build address ranges (IPv4.ipRange). The class is not instantiated. The invalid inputs give false rather than throwing.

Example

import {IPv4, type IPv4Subnet} from 'lakutata/utils'

const subnet: IPv4Subnet | false = IPv4.parseCIDR('192.168.0.1/24')
if (subnet) console.log(subnet.networkAddress, subnet.broadcastAddress, subnet.usableCount)
//192.168.0.0 192.168.0.255 254
console.log(IPv4.isPrivate('10.1.2.3'), IPv4.isSameSubnet('192.168.1.10', '192.168.2.10', '255.255.0.0'))
//true true
console.log(IPv4.toSubnetMask(20), IPv4.toInverseMask(20))
//255.255.240.0 0.0.15.255
console.log(IPv4.ipRange.fromString('192.168.1.1', '192.168.1.100').ipCount())
//100

Constructors

Constructor

new IPv4(): IPv4

Returns

IPv4

Properties

ipRange

static ipRange: typeof IPv4Range

The class of the IPv4 address ranges: create a range with IPv4.ipRange.fromString(start, end) or IPv4.ipRange.fromLong(start, end), then count its addresses or test whether it contains one.

Methods

contains()

static contains(cidr, ip): boolean

Tell whether an IPv4 address is in a CIDR block, its network and broadcast addresses included ('192.168.1.5' is in '192.168.1.0/24').

Parameters

cidr

string

The CIDR block (see IPv4.isCIDR).

ip

string

The address, in dotted decimal notation.

Returns

boolean

true when the address is in the block, false otherwise or when either is invalid.

---

ip2long()

static ip2long(ip): number | false

Convert an IPv4 address into its integer form, an unsigned 32-bit integer ('192.168.0.1' gives 3232235521). The leading zeros of its numbers are read as decimal ('192.168.01.1' is 192.168.1.1), not as octal.

Parameters

ip

string

The address, in dotted decimal notation.

Returns

number | false

The integer, from 0 to 4294967295, or false when the address is invalid (see IPv4.isValidIP).

---

isCIDR()

static isCIDR(cidr): boolean

Tell whether a string is a valid IPv4 CIDR block: a valid address (see IPv4.isValidIP), / and a prefix length from 0 to 32 ('192.168.1.0/24'). The address need not be the network address ('192.168.1.7/24' is valid). The prefix length is decimal digits only: '/8.5', '/ 8', '/0x8' and a second / ('/24/3') are invalid.

Parameters

cidr

string

The string to test.

Returns

boolean

true when it is a valid CIDR block, false otherwise or when it is not a string.

---

isConflict()

static isConflict(cidrs): boolean

Tell whether two IPv4 CIDR blocks in a list overlap (['192.168.1.0/24', '192.168.0.0/16'] do). The invalid entries, IPv6 blocks included, are ignored.

Parameters

cidrs

string[]

The CIDR blocks.

Returns

boolean

true when two blocks overlap, false otherwise or when the list is empty or not an array.

---

isEqual()

static isEqual(ip1, ip2): boolean

Tell whether two IPv4 addresses are the same, each given in dotted decimal notation or as its integer form ('192.168.0.1' equals 3232235521, and '192.168.01.10' equals '192.168.1.010').

Parameters

ip1

string | number

The first address: a string, or an integer from 0 to 4294967295.

ip2

string | number

The second address: a string, or an integer from 0 to 4294967295.

Returns

boolean

true when both are valid and equal, false otherwise.

---

isPrivate()

static isPrivate(ip): boolean

Tell whether an IPv4 address is in a range not routed on the internet: the private networks of RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), the loopback (127.0.0.0/8) and the link-local addresses (169.254.0.0/16). The shared address space of the carrier-grade NAT (100.64.0.0/10) and 0.0.0.0/8 are not included.

Parameters

ip

string

The address, in dotted decimal notation.

Returns

boolean

true when the address is in one of these ranges, false otherwise or when it is invalid.

---

isSameSubnet()

static isSameSubnet(ip1, ip2, mask): boolean

Tell whether two IPv4 addresses are in the same subnet: whether their bits under a mask are equal ('192.168.1.10' and '192.168.1.100' are under 24 and '255.255.255.0', not under 32).

Parameters

ip1

string

The first address, in dotted decimal notation.

ip2

string

The second address, in dotted decimal notation.

mask

string | number

The subnet mask: a prefix length, an integer from 0 to 32, or a mask in dotted decimal notation.

Returns

boolean

true when the addresses are in the same subnet, false otherwise or when an address or the mask is invalid.

---

isValidIP()

static isValidIP(ip, options?): boolean

Tell whether a string is a valid IPv4 address in dotted decimal notation: four numbers from 0 to 255 of 1 to 3 digits, separated by dots, without spaces. By default the leading zeros are allowed ('192.168.01.99').

Parameters

ip

string

The string to test; a value which is not a string gives false.

options?

strict: true rejects the leading zeros ('192.168.01.99'), and also a first number 0 ('0.0.0.0'); false by default.

strict?

boolean

Returns

boolean

true when the address is valid, false otherwise.

---

isValidMask()

static isValidMask(mask): boolean

Tell whether a value is a valid IPv4 subnet mask: a prefix length from 0 to 32, or a mask in dotted decimal notation whose bits are ones then zeros ('255.255.255.0', but not '255.0.255.0').

Parameters

mask

string | number

The mask: a number of bits, an integer, or a string.

Returns

boolean

true when the mask is valid, false otherwise (NaN and a fraction, 24.5, included).

---

long2ip()

static long2ip(ip): string | false

Convert the integer form of an IPv4 address into dotted decimal notation (3232235521 gives '192.168.0.1').

Parameters

ip

number

The integer, from 0 to 4294967295; its fraction is dropped.

Returns

string | false

The address, or false when the integer is out of range, NaN or not a number.

---

parseCIDR()

static parseCIDR(cidr): false | IPv4Subnet

Describe the subnet of an IPv4 CIDR block: its addresses and counts (see IPv4Subnet). The address of the block may be any address of the subnet ('192.168.0.1/24' describes 192.168.0.0/24). A /31 or a /32 has no network nor broadcast address: they are '', and all of its addresses are hosts.

Parameters

cidr

string

The CIDR block (see IPv4.isCIDR), such as '192.168.0.1/24'.

Returns

false | IPv4Subnet

The subnet (for '192.168.0.1/24': ipCount 256, usableCount 254, subnetMask'255.255.255.0', firstHost '192.168.0.1', lastHost '192.168.0.254', networkAddress '192.168.0.0', broadcastAddress '192.168.0.255'), or false when the block is invalid (see IPv4.isCIDR) or not a string.

---

parseSubnet()

static parseSubnet(ip, mask): false | IPv4Subnet

Describe the subnet of an IPv4 address and a subnet mask, as IPv4.parseCIDR does for a CIDR block (parseSubnet('192.168.0.1', '255.255.255.0') equals parseCIDR('192.168.0.1/24')).

Parameters

ip

string

The address, in dotted decimal notation.

mask

string | number

The subnet mask: in dotted decimal notation with contiguous ones ('255.255.255.0'), or a prefix length, an integer from 0 to 32 (24), as IPv4.isValidMask accepts.

Returns

false | IPv4Subnet

The subnet, or false when the address or the mask is invalid.

---

toBinHex()

static toBinHex(ip): false | IPBinHex

Convert an IPv4 address into its numeric forms ('192.168.0.1' gives the hexadecimal '0xc0a80001', the decimal 3232235521 and the binary '11000000101010000000000000000001').

Parameters

ip

string

The address, in dotted decimal notation.

Returns

false | IPBinHex

The numeric forms, or false when the address is invalid.

---

toInverseMask()

static toInverseMask(mask): string | false

Compute the inverse mask (the wildcard mask of the access lists) of a subnet mask: its bits flipped (24 and '255.255.255.0' give '0.0.0.255', 0 gives '255.255.255.255').

Parameters

mask

string | number

The subnet mask: a prefix length, an integer from 0 to 32, or a mask in dotted decimal notation.

Returns

string | false

The inverse mask in dotted decimal notation, or false when the mask is invalid.

---

toIPv6Format()

static toIPv6Format(ip): false | IPv6Result

Convert an IPv4 address into the forms of its IPv4-mapped IPv6 address ('192.168.1.1' gives mapped'::ffff:192.168.1.1', compressed '::ffff:c0a8:101' and expanded'0000:0000:0000:0000:0000:ffff:c0a8:0101'). The leading zeros of the address are dropped.

Parameters

ip

string

The address, in dotted decimal notation (the leading zeros are accepted).

Returns

false | IPv6Result

The IPv6 forms, or false when the address is invalid.

---

toMaskLength()

static toMaskLength(mask): number | false

Convert a subnet mask in dotted decimal notation into its prefix length ('255.255.255.0' gives 24, '0.0.0.0' gives 0).

Parameters

mask

string

The subnet mask, its bits ones then zeros.

Returns

number | false

The prefix length, from 0 to 32, or false when the mask is invalid ('255.0.255.0') or not a string.

---

toSubnetMask()

static toSubnetMask(length): string | false

Convert a prefix length into its subnet mask in dotted decimal notation (0 gives '0.0.0.0', 24 gives '255.255.255.0', 32 gives '255.255.255.255').

Parameters

length

number

The prefix length, an integer from 0 to 32.

Returns

string | false

The subnet mask, or false when the length is out of range, a fraction, NaN or not a number.