netmask

Netmask is a lightweight TypeScript library for parsing and working with IPv4 and IPv6 CIDR blocks. It understands the full range of legacy dotted-quad notations — octal, hex, and shorthand forms — alongside standard CIDR syntax, and normalizes IPv6 addresses per RFC 5952 (compressed :: notation, zone IDs, and IPv4-mapped addresses).

Beyond parsing, Netmask exposes base, broadcast, hostmask, and bitmask properties, a contains() predicate for testing whether an IP or a narrower block falls inside a range, and a next() method for walking to adjacent blocks of the same size — the building blocks for firewall rule evaluation, IP allowlisting, and subnet enumeration tools.

What You Get

• A single Netmask constructor that auto-detects IPv4 vs IPv6 from the address portion of the input.
• Support for every legacy IPv4 notation — dotted-quad, octal, hex, and shorthand (fewer than four octets).
• RFC 5952-compliant IPv6 text output, including zero-run compression and IPv4-mapped address handling.
• contains(), next(), and forEach() for range membership tests, block iteration, and address enumeration.
• Zero runtime dependencies, with 32-bit number math for IPv4 and 128-bit bigint math for IPv6.

Common Use Cases

• Validating that a request’s X-Forwarded-For or client IP falls inside a trusted proxy/CDN CIDR range.
• Evaluating firewall or ACL rules against allow/deny CIDR lists.
• Normalizing user-entered IP ranges (octal, hex, shorthand) into canonical CIDR form for storage.
• Enumerating or walking adjacent subnets during network/IP-allocation planning.

Under The Hood

Architecture The package has a small, three-file layered design under lib/: netmask.ts is a thin dispatcher class that inspects the address portion of the input for a : to decide, at construction time, whether to delegate to Netmask4Impl (netmask4.ts) or Netmask6Impl (netmask6.ts), then copies the resulting base/mask/hostmask/bitmask/first/last/broadcast properties onto itself. Each impl class is self-contained — IPv4 math is done with 32-bit number bitwise operators (>>> 0 normalizes to unsigned), IPv6 math is done entirely with native bigint (128-bit) arithmetic in netmask6.ts, with ip6bigint/parseIPv6Pure/bigint2ip6 handling parsing and RFC 5952-compliant zero-run compression on output. contains() on the outer class adds a family-mismatch guard (returning false for cross-family comparisons) before delegating to the matching impl, which is the one place the two implementations are reconciled. Changing the core Netmask4Impl/Netmask6Impl contracts would ripple into the public Netmask wrapper’s property copying and into every test file, since tests exercise the impls indirectly through the public class.

Tech Stack Pure TypeScript with tsconfig.json targeting ES2020/CommonJS, compiled via tsc to dist/ at prepublish time (the published npm package only ships build output, not source). No runtime dependencies at all — devDependencies are limited to typescript, mocha, ts-node, and @types/* for the test toolchain. Tests run directly against the TypeScript source via ts-node/register rather than compiled output, avoiding a separate test-build step.

Code Quality Testing uses Mocha with Node’s built-in assert module, organized as fixture-table-driven describe/it blocks (e.g. a table of [addr, mask, base, expectedMask, bitmask] tuples in tests/netmask.ts generates parameterized assertions per case) plus dedicated files for invalid-input cases (tests/badnets.ts) and IPv6-specific coverage (tests/netmask6.ts, tests/contains-cross-family.ts). tsconfig.json enables strict mode, and the public API is fully typed with explicit return types and a private _impl field enforcing encapsulation. There is no linter or CI config visible in the clone, but the .github directory suggests some GitHub Actions integration exists.

API Design The public surface is a single Netmask class with named properties (base, mask, bitmask, first, last, broadcast) mirroring how network engineers already talk about CIDR blocks, so there’s minimal learning curve for the target audience. contains() is overloaded to accept a plain IP string, a CIDR string, or another Netmask instance, reducing boilerplate for the common containment check. The README documents every property and method with inline comments showing example values, and the one deprecated method (forEach) is marked with a JSDoc @deprecated tag rather than silently discouraged.