# @imqueue/net 3.0.2 · API reference

Source: https://imqueue.org/api/net/latest/
Published: 2026-08-01
Author: @imqueue maintainers (https://github.com/imqueue)
Package: @imqueue/net 3.0.2 — generated reference, not hand-written

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

Build a [Networks](https://imqueue.org/api/net/latest/net.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](https://imqueue.org/api/net/latest/net.networklist/) is the single-family layer underneath, and the [cidrToRange()](https://imqueue.org/api/net/latest/net.cidrtorange/) and [ipToInt()](https://imqueue.org/api/net/latest/net.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](https://imqueue.org/api/net/latest/net.networks/) holds one [NetworkList](https://imqueue.org/api/net/latest/net.networklist/) per [NetworkType](https://imqueue.org/api/net/latest/net.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()](https://imqueue.org/api/net/latest/net.isvalid/) first if the input is untrusted.

## Example 1


```typescript
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


```typescript
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](https://imqueue.org/api/net/latest/net.networklist/) | A single-family list of networks, stored as sorted binary ranges and searched in O(log n). |
| [Networks](https://imqueue.org/api/net/latest/net.networks/) | A CIDR membership set covering both address families — the entry point for most callers. |


## Enumerations


| Enumeration | Description |
| --- | --- |
| [NetworkType](https://imqueue.org/api/net/latest/net.networktype/) | Which address family a value belongs to. |


## Functions


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


## Interfaces


| Interface | Description |
| --- | --- |
| [NetworksIntRanges](https://imqueue.org/api/net/latest/net.networksintranges/) | Integer address ranges grouped by family, as returned by [Networks.toIntRanges()](https://imqueue.org/api/net/latest/net.networks.tointranges/). |


## Variables


| Variable | Description |
| --- | --- |
| [IPV4\_INT\_SIZE](https://imqueue.org/api/net/latest/net.ipv4_int_size/) | Bytes in a binary IPv4 address: 4. |
| [IPV4\_MASKS](https://imqueue.org/api/net/latest/net.ipv4_masks/) | The 33 IPv4 network masks, indexed by prefix length — `IPV4_MASKS[24]` is the mask for a `/24`. |
| [IPv4\_MAX\_STR\_LEN](https://imqueue.org/api/net/latest/net.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](https://imqueue.org/api/net/latest/net.ipv6_int_size/) | Bytes in a binary IPv6 address: 16. |
| [IPV6\_MASKS](https://imqueue.org/api/net/latest/net.ipv6_masks/) | The 129 IPv6 network masks, indexed by prefix length — `IPV6_MASKS[64]` is the mask for a `/64`. |
| [IPV6\_MAX\_STR\_LEN](https://imqueue.org/api/net/latest/net.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](https://imqueue.org/api/net/latest/net.network_type_enum/) | The literal `"'ipv4' \| 'ipv6'"`, for embedding a union of the [NetworkType](https://imqueue.org/api/net/latest/net.networktype/) values in an error message. |