ipaddr.js

ipaddr.js is a small, dependency-free library for working with IPv4 and IPv6 addresses in JavaScript, running equally well in Node.js and the browser. It parses and validates addresses, matches them against CIDR ranges, classifies them into named ranges such as loopback, private, and reserved, and converts freely between string, byte-array, and IPv4/IPv6 representations.

With over 100 million weekly downloads it is one of the most widely relied-upon networking primitives in the JavaScript ecosystem, used under the hood by Express, proxies, and countless server frameworks to interpret client addresses and enforce trusted-network rules.

What You Get

• Safe validation helpers (isValid, isValidCIDR) that never throw, plus strict parse functions for both IPv4 and IPv6
• CIDR-aware parsing and matching via parseCIDR and match, including network and broadcast address derivation
• Built-in range classification (loopback, private, linkLocal, multicast, reserved, carrierGradeNat, and more) through range() and subnetMatch
• Conversion between string, byte-array, and normalized/RFC 5952 forms, plus IPv4-mapped IPv6 handling via process()
• Bundled TypeScript declarations and zero runtime dependencies for use in Node.js or the browser

Common Use Cases

• Validating and normalizing user- or client-supplied IP addresses in web servers and APIs
• Enforcing allow/deny lists by matching request addresses against trusted CIDR ranges
• Resolving real client IPv4 addresses from IPv4-mapped IPv6 connections on dual-stack sockets
• Classifying addresses as private, loopback, or public to drive security and routing decisions

Under The Hood

Architecture - The entire library lives in a single UMD module, lib/ipaddr.js (~1,100 lines), wrapped in an IIFE that exports to CommonJS, AMD, or a browser global. It defines two peer classes, IPv4 and IPv6, each carrying static factory/validation methods (parse, isValid, parseCIDR, broadcastAddressFromCIDR) and instance methods (match, range, toByteArray, toString). A shared matchCIDR helper drives all subnet comparisons at the byte level, while regular expressions precompiled at module load (fourOctet, native, transitional) recognise the many legal notations before parsing normalizes them into fixed octet or part arrays.

Tech Stack - Pure JavaScript targeting Node.js 10+ with no runtime dependencies. It ships CommonJS (“type”: “commonjs”) with a hand-written TypeScript declaration file (lib/ipaddr.d.ts). Tooling is minimal: ESLint 10 for linting and the built-in node —test runner with experimental coverage for tests; there is no build step, bundler, or transpiler since the source is published as-is.

Code Quality - The code is disciplined and well-factored: strict mode throughout, const/let, small single-purpose functions, and named range tables kept as declarative data rather than branching logic. Errors are surfaced by throwing on invalid parse input while validation entry points stay non-throwing. Test coverage is thorough - test/ipaddr.test.js is roughly 41 KB, comparable in size to the source itself, exercising parsing edge cases, CIDR math, range classification, and the exotic inet_aton notations.

API Design - The public surface is small, symmetric, and highly ergonomic: the same verbs (parse, isValid, match, range, toString) appear on the global namespace and on both address classes, so knowledge transfers directly between IPv4 and IPv6. parseCIDR returns a tuple that plugs straight into match, minimising boilerplate. The README is extensive with per-method examples, and bundled type declarations give first-class editor support, keeping the learning curve gentle for anyone who has worked with IP addresses before.