net package

Fast CIDR membership testing for IPv4 and IPv6, using sorted binary ranges rather than per-network comparison.

Build a Networks from a list of CIDR records and ask it whether an address is in any of them — that is the whole API for most callers, and it is what @imqueue/http-protect uses for its allow-list. NetworkList is the single-family layer underneath, and the cidrToRange() and ipToInt() helpers are exported for building something else on the same primitives.

Remarks

Each network is stored as a start/end address pair in a Buffer, sorted, and matched by binary search, so lookup is logarithmic in the number of networks instead of linear. Addresses are compared as bigint, which is what makes one code path cover both a 4-byte and a 16-byte address.

The two families never share a buffer, because an IPv6 record is 32 bytes against IPv4's 8 — Networks holds one NetworkList per NetworkType and dispatches on the address it is given.

Every CIDR record needs an explicit prefix length. A bare address is rejected, so a single host is 203.0.113.7/32 or 2001:db8::1/128; passing 203.0.113.7 throws while parsing. Anything that is not a valid record throws rather than being skipped, so one bad entry fails the whole list — validate with isValid() first if the input is untrusted.

Example 1

import { Networks } from '@imqueue/net';

const allowed = new Networks(['10.0.0.0/8', '192.168.0.0/16', '2001:db8::/32']);

allowed.includes('10.1.2.3');     // true
allowed.includes('8.8.8.8');      // false
allowed.includes('2001:db8::1');  // true

Example 2

import { isValid, Networks } from '@imqueue/net';

// Untrusted input: check before constructing, because a bad record throws.
const records = input.filter(r => isValid(r.split('/')[0]));
const networks = new Networks(records);

Classes

Class	Description
NetworkList	A single-family list of networks, stored as sorted binary ranges and searched in O(log n).
Networks	A CIDR membership set covering both address families — the entry point for most callers.

Enumerations

Enumeration	Description
NetworkType	Which address family a value belongs to.

Functions

Function	Description
binToDec(binStr)	Reads a string of `'0'` and `'1'` as an unsigned `bigint`.
cidrToRange(cidr, type, canonical)	Expands a CIDR record into the first and last address it covers, as text.
cidrToRangeInt(cidr, type)	Expands a CIDR record into the first and last address it covers, as integers.
getType(ip, type)	Determines an address's family, or verifies the one you claim it has.
intRangeToCidr(start, end, type, canonical)	Covers an integer address range with the fewest CIDR records that fit it exactly.
intToIp(intIp, type, canonical)	Renders an integer address back to text.
ipToInt(ip, type)	Converts an address to the unsigned `bigint` this package compares with.
ipv6Pack(ip)	Compresses an IPv6 address: drops leading zeros from each group and collapses the longest run of zero groups to `::`.
ipv6Unpack(ip)	Expands an IPv6 address to its full eight-group, four-digit form.
isValid(ip)	Whether a string is a valid IPv4 or IPv6 address.
isValid4(ip)	Whether a string is a valid IPv4 address.
isValid6(ip)	Whether a string is a valid IPv6 address.
masksOf(type)	The mask table for a family, indexable by prefix length.
rangeToCidr(start, end, type, canonical)	Covers an address range with the fewest CIDR records that fit it exactly.
sizeOf(type)	How many bytes one address of the given family occupies.
toBigIntLE(buf)	Reads a little-endian byte sequence as an unsigned `bigint`.
toBinaryList(networks, type)	Packs CIDR records into the sorted binary form that lookups binary-search over.
toBufferLE(value, size)	Writes an unsigned `bigint` as a little-endian buffer of an exact size.
toIntArray(list, type)	Unpacks a binary list back into integer address ranges.
toStringArray(list, type, canonical)	Unpacks a binary list back into CIDR text.
validate(ip)	Asserts that a string is a valid address of either family.
validate4(ip)	Asserts that a string is a valid IPv4 address.
validate6(ip)	Asserts that a string is a valid IPv6 address.

Interfaces

Interface	Description
NetworksIntRanges	Integer address ranges grouped by family, as returned by Networks.toIntRanges().

Variables

Variable	Description
IPV4_INT_SIZE	Bytes in a binary IPv4 address: 4.
IPV4_MASKS	The 33 IPv4 network masks, indexed by prefix length — `IPV4_MASKS[24]` is the mask for a `/24`.
IPv4_MAX_STR_LEN	Longest an IPv4 address can be as text: 15 characters, from four three-digit octets plus three dots.
IPV6_INT_SIZE	Bytes in a binary IPv6 address: 16.
IPV6_MASKS	The 129 IPv6 network masks, indexed by prefix length — `IPV6_MASKS[64]` is the mask for a `/64`.
IPV6_MAX_STR_LEN	Longest an IPv6 address can be as text: 39 characters, from eight groups of four hex digits plus seven colons.
NETWORK_TYPE_ENUM	The literal `"'ipv4' \| 'ipv6'"`, for embedding a union of the NetworkType values in an error message.

Read this page as plain markdown — no HTML, no navigation. For pasting into an LLM, or for an agent to fetch.