@apislash/ip

Dependency-free IPv4 / IPv6 address utilities for any TypeScript project.

• Exact. IPv4 is a 32-bit integer, IPv6 a single 128-bit BigInt — comparison, ranges and subnetting are arithmetic, never string games.
• Strict & safe. Only canonical addresses parse. Ambiguous legacy forms (127.1, 012.0.0.1, 0x7f.0.0.1, 2130706433) are rejected, and IPv4-mapped IPv6 (::ffff:127.0.0.1) classifies by its embedded IPv4 — so the SSRF mis-classification class of looser libraries simply cannot occur.
• Zero dependencies. Pure TypeScript, ESM + CJS, full types.

Install

npm install @apislash/ip

Quick start

import { parse, isPublic, cidrContains, compare } from "@apislash/ip";

parse("2001:db8::1").toString();        // "2001:db8::1"  (canonical RFC 5952)
isPublic("10.0.0.1");                   // false (private)
isPublic("::ffff:127.0.0.1");           // false (loopback — embedded v4)
cidrContains("192.168.0.0/16", "192.168.5.5"); // true
compare("1.2.3.4", "1.2.3.5");          // -1

API

Parse / validate / get

• parse(str) / tryParse(str) → Ip (throws / null)
• isValid(str), version(str) → 4 | 6 | null
• fromBytes(bytes), fromValue(bigint, version)

The Ip object

• .version, .value (bigint), .bitLength
• .toString() (canonical), .toBytes(), .toBigInt()
• .toV6() / .toV4() (IPv4-mapped conversions)
• .equals(other), .compare(other) → -1 | 0 | 1
• .kind() → IANA classification; .isPublic(), .isPrivate(), .isLoopback(), .isLinkLocal(), .isMulticast(), .isUnspecified()

Compare

• compare(a, b), isEqual(a, b) — accept strings or Ip

Range / CIDR / subnet

• parseCidr(str) / tryParseCidr(str) → Cidr
• Cidr: .network(), .broadcast(), .size(), .contains(ip), .toString(), .info()
• cidrContains(cidr, ip), within(ip, start, end)

Classification shortcuts

• isPublic(x), isPrivate(x), isLoopback(x) — string or Ip

License

MIT © Apislash