node-ip

ip is a long-running npm utility library that gives Node.js code a small, synchronous toolkit for working with IPv4 and IPv6 addresses without pulling in any runtime dependencies. It converts addresses between dotted/colon string notation and raw Buffers, validates address formats, performs bitwise mask/OR/NOT operations, and computes CIDR/subnet ranges including network address, broadcast address, host count, and a contains() range-membership check.

Beyond address math, it classifies addresses as private, public, or loopback against RFC1918 and link-local ranges, and can read the host machine’s own address via os.networkInterfaces(). First published in 2012 and still pulling millions of weekly downloads, it has become a de facto low-level building block that higher-level networking, proxy, and access-control code in the Node.js ecosystem reaches for instead of hand-rolling address parsing.

What You Get

• Buffer <-> string conversion for both IPv4 and IPv6 addresses, including in-place writes at a byte offset
• Regex-based format validators (isV4Format, isV6Format) that check syntax without throwing
• CIDR and subnet arithmetic: network/broadcast address, host count, and a contains() membership predicate
• Bitwise address operations (mask, not, or) that work correctly across mixed IPv4/IPv6 buffer lengths
• Private/public/loopback classification against RFC1918, link-local, and loopback ranges
• Local network interface address lookup via os.networkInterfaces(), filterable by family or interface name

Common Use Cases

• Classifying inbound request IPs as private or public to apply different rate-limit or auth tiers
• Validating X-Forwarded-For / proxy headers before trusting a client-supplied IP
• Restricting an internal admin surface to a corporate VPN or LAN CIDR range
• Having a service advertise its own LAN address to a registry or discovery system at startup

Under The Hood

Architecture The entire library is one flat CommonJS module (lib/ip.js, under 500 lines) that attaches every function directly to the exported ip object — there is no internal layering, class hierarchy, or plugin system. Buffer conversion (toBuffer/toString) is the load-bearing primitive that nearly every other function (mask, or, not, isEqual, subnet) builds on, so a change to its offset/length handling would ripple through the whole API surface; the only external dependency is Node’s built-in buffer and os modules.

Tech Stack Plain, dependency-free JavaScript targeting Node’s CommonJS module system with no build step — the package ships lib/ip.js directly as main. Its only devDependencies are eslint (^8) for linting and mocha (^10) for tests; there is no bundler, transpiler, or TypeScript layer, and the published package is exactly what’s checked into lib/.

Code Quality A single test/api-test.js file (500+ lines) exercises nearly every exported function with mocha/assert, and npm test runs eslint before mocha so lint failures fail CI; GitHub Actions runs the suite across Node 12/14/16/18. Error handling is explicit in a few hot paths (toBuffer throws on an unparseable address, isPrivate throws on an invalid IPv4) but most functions rely on regex validation rather than typed guards, and the project has no TypeScript definitions of its own. Naming is consistent and the code favors small, single-purpose functions over abstraction.

What Makes It Unique The library isn’t attempting anything novel — IP parsing, CIDR math, and private-range checks are well-trodden problems with several comparable packages in the ecosystem. Its value is being a minimal, dependency-free, long-stable implementation that many other packages depend on transitively, rather than any distinctive algorithmic approach.