ip-num

ip-num is a zero-dependency TypeScript library that models IPv4 addresses, IPv6 addresses, and ASN (autonomous system) numbers as strongly-typed value objects rather than plain strings. Each number type supports construction from multiple formats (dotted-decimal, hexadecatet, binary string, plain integer, ASDot/ASDot+ for ASNs), comparison operators, and iteration via next/previous, so consumers get compile-time safety instead of ad-hoc regex parsing scattered across an application.

Beyond individual numbers, the library provides IPv4CidrRange and IPv6CidrRange for CIDR-notation subnets (with splitting, containment checks, and prefix conversion), a RangedSet abstraction for arbitrary contiguous ranges that don’t align to CIDR boundaries, and a Pool type for managing collections of ranges — supporting operations like finding available subnets of a given size. It runs identically in Node.js, in a bundled browser build, or via a plain script tag, making it a drop-in replacement for hand-rolled IP arithmetic in networking tools, IPAM systems, and firewall/ACL generators.

What You Get

• Typed IPv4, IPv6, and Asn classes with multi-format construction (dotted-decimal, hexadecatet, binary string, plain number, ASDot/ASDot+)
• IPv4CidrRange and IPv6CidrRange for CIDR-notation subnets with splitting, merging checks, and containment (inside/contains) operations
• RangedSet for continuous IP ranges that don’t need to align to CIDR boundaries, constructible from a single IP, a CIDR range, or a range string
• Pool abstraction for working with collections of IP ranges, including locating available subnets of a requested size
• A Validator class exposing the regex- and bit-level checks the library uses internally, for callers who want to validate input before constructing typed instances
• Zero runtime dependencies and builds for Node.js (CommonJS), ES modules, and a bundled browser script

Common Use Cases

• Validating and normalizing user- or config-supplied IP addresses and CIDR blocks before storing or comparing them
• Building IP address management (IPAM) tooling that needs to split, merge, or check containment of subnets
• Generating or auditing firewall/ACL/routing rules that reference CIDR ranges
• Converting between ASN string formats (asplain, asdot, asdot+) in network-automation scripts
• Iterating or enumerating addresses within a range for scanning or allocation logic

Under The Hood

Architecture The library is organized as a flat set of cooperating modules under src/ rather than a deep directory tree: IPNumber.ts defines the abstract AbstractIPNum base class (shared bit-size, comparison, and multicast/loopback predicates) that IPv4, IPv6, Asn, and their mask variants extend; IPRange.ts builds IPv4CidrRange/IPv6CidrRange and the range-agnostic RangedSet on top of those number types; and IPPool.ts aggregates ranges into a Pool backed by a sorted-set index for subnet allocation. Parsing and formatting are deliberately factored out into standalone modules (BinaryUtils, HexadecimalUtils, IPv6Utils) and a single Validator class that centralizes every regex/bit-range check, so the number classes stay thin wrappers around validated bigint values rather than duplicating parsing logic. Because every numeric operation routes through BigInt rather than native numbers, the core abstraction (AbstractIPNum) is the one thing the rest of the library depends on directly — changing its comparison or bit-size contract would ripple into every range and pool type built on it.

Tech Stack ip-num is a zero-runtime-dependency TypeScript project (strict mode enabled in tsconfig.json) targeting ES2020, compiled with tsc for the published CommonJS/ESM output and separately bundled with Webpack 5 (ts-loader, source-map-loader) into a single UMD ip-num.js for direct browser script-tag use. There is no web framework, ORM, or database involved — it is a pure computation library — and its only “integration” surface is the three module-loading mechanisms it documents (ES modules, CommonJS require, and a global ipnum browser variable). API docs are generated with TypeDoc and published to GitHub Pages as the project’s website.

Code Quality Tests live under spec/ as one Jasmine spec file per source module (e.g. IPv4Test.ts, IPv6CidrRangeTest.ts, PoolTest.ts), run via jasmine-ts/ts-node and measured with nyc for coverage (reported through Coveralls, referenced at the top of the README); the spec suite is large relative to the source (several spec files exceed their corresponding source file in size), indicating deliberate edge-case coverage of formats like abbreviated IPv6 and asdot+ ASN notation. Error handling is explicit and typed: the Validator class throws with named, reusable message constants rather than generic exceptions, and the compiler is run with strict, noImplicitReturns, and noFallthroughCasesInSwitch enabled. GitHub Actions runs CodeQL static analysis on every push/PR; there is no separate lint step (ESLint/TSLint) configured, so style consistency relies on TypeScript’s compiler checks alone.

API Design The public surface favors named static factory methods (fromNumber, fromString, fromBinaryString, fromCidr, fromRangeString) over overloaded constructors, which makes the intended construction path for each format explicit at the call site and is documented with a runnable example for every one in the README. Getting started requires zero configuration — import { IPv4 } from "ip-num/IPNumber" and call a factory method — and the same import surface works unchanged across ES modules, CommonJs, and the browser global, which keeps onboarding friction low despite the library covering three distinct numeric domains (IPv4, IPv6, ASN) and two range abstractions (CIDR-bound and arbitrary) side by side.