ip-cidr

ip-cidr is a small, dependency-light Node.js library (with a prebuilt browser bundle) for working with IPv4 and IPv6 CIDR notation. It parses a CIDR string into a range object, resolves the first and last address in the range, checks whether a given address falls inside it, and iterates every address in the range using BigInt arithmetic so it holds up even on very large IPv6 blocks.

It is built directly on top of the ip-address package for the underlying address parsing, and adds range-specific operations on top: start/end resolution, containment checks, chunked iteration with from/to/limit paging, and static validation helpers that let callers reject malformed CIDR strings before doing any range math.

What You Get

• A single IPCIDR class with static validation helpers (isValidCIDR, isValidAddress, createAddress) and instance methods for range math.
• BigInt-backed iteration (toArray, loop) with from/to/limit chunking so large ranges can be paged instead of loaded all at once.
• Hand-written TypeScript definitions (index.d.ts) shipped alongside the JS, no separate @types package needed.
• A prebuilt browser bundle (dist/ip-cidr.js) for client-side use via window.IPCIDR.

Common Use Cases

• Validating and normalizing CIDR ranges submitted through APIs or config files
• Checking whether a client IP is inside an allow/deny list block
• Enumerating hosts in a subnet for scanning or provisioning tools
• Converting a CIDR block into start/end boundaries for database range queries

Under The Hood

Architecture The entire library is a single ESM module (index.js) built around one IPCIDR class: the constructor delegates address parsing to a static createAddress() helper that wraps ip-address’s Address4/Address6 classes, then derives addressStart/addressEnd and a BigInt size up front. Range iteration (toArray, loop) and pagination (getChunkInfo, loopInfo) are implemented purely with BigInt arithmetic and have no external state or I/O, so the whole module is a thin, self-contained bridge over ip-address’s address objects — if that dependency’s API shifted, formatIP/createAddress are the only two places that would need to change.

Tech Stack The package is plain ESM JavaScript ("type": "module") targeting Node >=16.14 for native BigInt support, with a single runtime dependency, ip-address ^9.0.5, for IPv4/IPv6 parsing. A browserify+esmify build step produces the dist/ip-cidr.js bundle for browser use, tests run under mocha+chai, and a husky pre-commit hook chains npm run test && npm run build so the bundle can’t drift from source. Hand-authored index.d.ts types ship directly rather than being generated by tsc.

Code Quality test/test.js uses mocha+chai in BDD style and covers the main surface: v4/v6 validity, IPv4-mapped IPv6 addresses, formatIP in string/BigInt/object modes, and range/array generation — a reasonable spread for a library this size, though there’s no CI workflow config in the repo, so tests only run locally or via the pre-commit hook. Error handling is minimal: contains() wraps its logic in a try/catch and just returns false on any failure, and there’s no linter or formatter configuration checked in.

API Design The public surface is small and consistent: static helpers (isValidCIDR, isValidAddress, createAddress, formatIP) let callers validate input before ever constructing a range, and instance methods (start, end, contains, toArray, loop, toRange, toObject) all accept the same { type, from, to, limit } options shape. That consistency keeps day-to-day use simple, but the chunked-pagination mechanics (getChunkInfo/loopInfo, mixing string/BigInt/number inputs for from/to/limit) require reading the source to fully understand, since the README documents the options but not their internal resolution rules.