ip-utilities 1.0.0

package/dist/internal/cidr.js

@@ -0,0 +1,297 @@
+import { parseIPv4, parseIPv4Raw, maskV4LUT } from "./ipv4.js";
+import { parseIPv6, parseIPv6Raw, ipv6RawBuf } from "./ipv6.js";
+import { matchesCidr, prefixMaskV6 } from "./ipv6-ranges.js";
+// --- Constants & lookup tables ---
+// Prebuilt IPv6 prefix masks for all prefix lengths 0-128, four uint32 words each
+const V6_MASK_LUT = new Uint32Array(129 * 4);
+for (let p = 0; p <= 128; p++) {
+    const base = p * 4;
+    for (let w = 0; w < 4; w++)
+        V6_MASK_LUT[base + w] = prefixMaskV6(p, w);
+}
+// --- Mutable state ---
+// Last parsed IPv4 raw value from parseIPOrCIDR
+export let parseIPOrCIDRv4 = 0;
+// --- Exports: prefix parsing ---
+/**
+ * Parses a decimal prefix length from a substring.
+ * @param s - Source string
+ * @param start - Start index of the prefix digits
+ * @param end - End index (exclusive)
+ * @param max - Maximum allowed prefix value
+ * @returns The prefix length, or -1 if invalid
+ */
+export function parsePrefixInline(s, start, end, max) {
+    const len = end - start;
+    if (len === 0 || len > 3)
+        return -1;
+    if (len > 1 && s.charCodeAt(start) === 48)
+        return -1;
+    let v = 0;
+    for (let i = start; i < end; i++) {
+        const ch = s.charCodeAt(i) - 48;
+        if (ch < 0 || ch > 9)
+            return -1;
+        v = v * 10 + ch;
+    }
+    return v > max ? -1 : v;
+}
+// --- Exports: CIDR parsing ---
+/**
+ * Parses a CIDR string in IPv4 notation (e.g. "192.168.1.0/24").
+ * @param s - The CIDR string
+ * @returns The parsed CIDRv4, or null if invalid
+ */
+export function parseCIDRv4(s) {
+    const slashIdx = s.indexOf('/');
+    if (slashIdx === -1)
+        return null;
+    const addr = parseIPv4(s, slashIdx);
+    if (addr === null)
+        return null;
+    const prefix = parsePrefixInline(s, slashIdx + 1, s.length, 32);
+    if (prefix === -1)
+        return null;
+    return { addr, prefix, kind: 4 };
+}
+/**
+ * Parses a CIDR string in IPv6 notation (e.g. "::1/128").
+ * @param s - The CIDR string
+ * @returns The parsed CIDRv6, or null if invalid
+ */
+export function parseCIDRv6(s) {
+    const slashIdx = s.indexOf('/');
+    if (slashIdx === -1)
+        return null;
+    const addr = parseIPv6(s, slashIdx);
+    if (addr === null)
+        return null;
+    const prefix = parsePrefixInline(s, slashIdx + 1, s.length, 128);
+    if (prefix === -1)
+        return null;
+    return { addr, prefix, kind: 6 };
+}
+/**
+ * Parses a CIDR string, auto-detecting IPv4 or IPv6.
+ * @param s - The CIDR string
+ * @returns The parsed CIDR, or null if invalid
+ */
+export function parseCIDR(s) {
+    const c0 = s.charCodeAt(0);
+    if (c0 >= 48 && c0 <= 57) {
+        let hasColon = false;
+        for (let i = 1, len = s.length; i < len; i++) {
+            const ch = s.charCodeAt(i);
+            if (ch === 58) {
+                hasColon = true;
+                break;
+            }
+            if (ch === 47)
+                break;
+        }
+        if (!hasColon)
+            return parseCIDRv4(s);
+    }
+    return parseCIDRv6(s);
+}
+// --- Exports: validation ---
+/**
+ * Checks whether a string is valid CIDR notation (IPv4 or IPv6).
+ * @param s - The string to validate
+ * @returns True if the string is valid CIDR
+ */
+export function isCIDR(s) {
+    const slashIdx = s.indexOf('/');
+    if (slashIdx === -1)
+        return false;
+    const c0 = s.charCodeAt(0);
+    if (c0 >= 48 && c0 <= 57) {
+        let hasColon = false;
+        for (let i = 1; i < slashIdx; i++) {
+            if (s.charCodeAt(i) === 58) {
+                hasColon = true;
+                break;
+            }
+        }
+        if (!hasColon) {
+            return parseIPv4Raw(s, 0, slashIdx) !== -1 && parsePrefixInline(s, slashIdx + 1, s.length, 32) !== -1;
+        }
+    }
+    return parseIPv6Raw(s, slashIdx) && parsePrefixInline(s, slashIdx + 1, s.length, 128) !== -1;
+}
+// --- Exports: containment ---
+/**
+ * Checks whether an IPv4 address is within a CIDRv4 range.
+ * @param ip - The IPv4 address
+ * @param cidr - The CIDRv4 range
+ * @returns True if the address is within the range
+ */
+export function ipInCIDRv4(ip, cidr) {
+    const m = maskV4LUT[cidr.prefix];
+    return ((ip.ip & m) >>> 0) === ((cidr.addr.ip & m) >>> 0);
+}
+/**
+ * Checks whether an IPv6 address is within a CIDRv6 range.
+ * @param ip - The IPv6 address
+ * @param cidr - The CIDRv6 range
+ * @returns True if the address is within the range
+ */
+export function ipInCIDRv6(ip, cidr) {
+    return matchesCidr(ip.w0, ip.w1, ip.w2, ip.w3, cidr.addr.w0, cidr.addr.w1, cidr.addr.w2, cidr.addr.w3, cidr.prefix);
+}
+/**
+ * Checks whether an IP address is within a CIDR range. Both must be the same version.
+ * @param ip - The IP address (IPv4 or IPv6)
+ * @param cidr - The CIDR range (IPv4 or IPv6)
+ * @returns True if the address is within the range, false if mismatched versions
+ */
+export function ipInCIDR(ip, cidr) {
+    if (ip.kind === 4 && cidr.kind === 4)
+        return ipInCIDRv4(ip, cidr);
+    if (ip.kind === 6 && cidr.kind === 6)
+        return ipInCIDRv6(ip, cidr);
+    return false;
+}
+/**
+ * Parses an IP string and CIDR string, then checks containment.
+ * @param ipStr - The IP address string
+ * @param cidrStr - The CIDR range string
+ * @returns True if the IP is within the CIDR range
+ */
+export function isIPInCIDR(ipStr, cidrStr) {
+    const cidr = parseCIDR(cidrStr);
+    if (cidr === null)
+        return false;
+    if (cidr.kind === 4) {
+        const ip = parseIPv4(ipStr);
+        if (ip === null)
+            return false;
+        return ipInCIDRv4(ip, cidr);
+    }
+    const ip = parseIPv6(ipStr);
+    if (ip === null)
+        return false;
+    return ipInCIDRv6(ip, cidr);
+}
+// --- Exports: network & broadcast ---
+/**
+ * Computes the network address (first address) of an IPv4 CIDR range.
+ * @param cidr - The CIDRv4 range
+ * @returns The network address
+ */
+export function networkAddressV4(cidr) {
+    const m = maskV4LUT[cidr.prefix];
+    return { ip: (cidr.addr.ip & m) >>> 0, kind: 4 };
+}
+/**
+ * Computes the broadcast address (last address) of an IPv4 CIDR range.
+ * @param cidr - The CIDRv4 range
+ * @returns The broadcast address
+ */
+export function broadcastAddressV4(cidr) {
+    const m = maskV4LUT[cidr.prefix];
+    return { ip: (cidr.addr.ip | ~m) >>> 0, kind: 4 };
+}
+/**
+ * Computes the network address (first address) of an IPv6 CIDR range.
+ * @param cidr - The CIDRv6 range
+ * @returns The network address
+ */
+export function networkAddressV6(cidr) {
+    const base = cidr.prefix << 2;
+    const a = cidr.addr;
+    return {
+        w0: (a.w0 & V6_MASK_LUT[base]) >>> 0,
+        w1: (a.w1 & V6_MASK_LUT[base + 1]) >>> 0,
+        w2: (a.w2 & V6_MASK_LUT[base + 2]) >>> 0,
+        w3: (a.w3 & V6_MASK_LUT[base + 3]) >>> 0,
+        kind: 6,
+    };
+}
+/**
+ * Computes the broadcast address (last address) of an IPv6 CIDR range.
+ * @param cidr - The CIDRv6 range
+ * @returns The broadcast address
+ */
+export function broadcastAddressV6(cidr) {
+    const base = cidr.prefix << 2;
+    const a = cidr.addr;
+    return {
+        w0: (a.w0 | ~V6_MASK_LUT[base]) >>> 0,
+        w1: (a.w1 | ~V6_MASK_LUT[base + 1]) >>> 0,
+        w2: (a.w2 | ~V6_MASK_LUT[base + 2]) >>> 0,
+        w3: (a.w3 | ~V6_MASK_LUT[base + 3]) >>> 0,
+        kind: 6,
+    };
+}
+// --- Exports: subnet utilities ---
+/**
+ * Returns the subnet mask for an IPv4 prefix length.
+ * @param prefix - Prefix length (0-32)
+ * @returns The uint32 subnet mask
+ */
+export function subnetMaskV4(prefix) {
+    return maskV4LUT[prefix];
+}
+/**
+ * Converts a subnet mask to its prefix length.
+ * @param mask - The uint32 subnet mask (must be contiguous)
+ * @returns The prefix length, or null if the mask is not contiguous
+ */
+export function prefixFromSubnetMask(mask) {
+    if (mask === 0)
+        return 0;
+    const inv = (~mask) >>> 0;
+    if ((inv & (inv + 1)) !== 0)
+        return null;
+    return Math.clz32(inv);
+}
+// --- Exports: IP/CIDR routing ---
+/**
+ * Parses an IP or CIDR string, routing v4/v6 in a single forward scan.
+ * On success, the v4 result is in {@link parseIPOrCIDRv4} and v6 result in ipv6RawBuf.
+ * @param s - The IP or CIDR string
+ * @returns 4 for valid IPv4, 6 for valid IPv6, 0 for invalid
+ */
+export function parseIPOrCIDR(s) {
+    const len = s.length;
+    const c0 = s.charCodeAt(0);
+    if (c0 >= 48 && c0 <= 57) {
+        let hasColon = false;
+        let slashIdx = -1;
+        for (let i = 1; i < len; i++) {
+            const ch = s.charCodeAt(i);
+            if (ch === 58) {
+                hasColon = true;
+                break;
+            }
+            if (ch === 47) {
+                slashIdx = i;
+                break;
+            }
+        }
+        if (!hasColon) {
+            if (slashIdx === -1) {
+                parseIPOrCIDRv4 = parseIPv4Raw(s, 0, len);
+                return parseIPOrCIDRv4 !== -1 ? 4 : 0;
+            }
+            parseIPOrCIDRv4 = parseIPv4Raw(s, 0, slashIdx);
+            if (parseIPOrCIDRv4 === -1 || parsePrefixInline(s, slashIdx + 1, len, 32) === -1)
+                return 0;
+            return 4;
+        }
+    }
+    const slashIdx = s.indexOf('/');
+    if (slashIdx === -1)
+        return parseIPv6Raw(s, len) ? 6 : 0;
+    if (!parseIPv6Raw(s, slashIdx) || parsePrefixInline(s, slashIdx + 1, len, 128) === -1)
+        return 0;
+    return 6;
+}
+/**
+ * Constructs an IPv6Addr from the shared ipv6RawBuf after a successful parseIPv6Raw call.
+ * @returns The IPv6Addr built from the raw buffer
+ */
+export function v6AddrFromBuf() {
+    return { w0: ipv6RawBuf[0], w1: ipv6RawBuf[1], w2: ipv6RawBuf[2], w3: ipv6RawBuf[3], kind: 6 };
+}

package/dist/internal/ipv4-ranges.d.ts

@@ -0,0 +1,26 @@
+import type { IPv4RangeName } from '../types.ts';
+/**
+ * Classifies a packed uint32 IPv4 address into its IANA-assigned range.
+ * @param ip - Packed uint32 IP address
+ * @returns The range name (e.g. "private", "loopback", "unicast")
+ */
+export declare function ipv4Range(ip: number): IPv4RangeName;
+/**
+ * Checks whether a packed uint32 IPv4 address is in a private range (RFC 1918).
+ * @param ip - Packed uint32 IP address
+ * @returns True if the address is in 10.0.0.0/8, 172.16.0.0/12, or 192.168.0.0/16
+ */
+export declare function isPrivateIPv4(ip: number): boolean;
+/**
+ * Checks whether a packed uint32 IPv4 address is a loopback address (127.0.0.0/8).
+ * @param ip - Packed uint32 IP address
+ * @returns True if the address is in the loopback range
+ */
+export declare function isLoopbackIPv4(ip: number): boolean;
+/**
+ * Checks whether a packed uint32 IPv4 address is link-local (169.254.0.0/16).
+ * @param ip - Packed uint32 IP address
+ * @returns True if the address is in the link-local range
+ */
+export declare function isLinkLocalIPv4(ip: number): boolean;
+//# sourceMappingURL=ipv4-ranges.d.ts.map

package/dist/internal/ipv4-ranges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ipv4-ranges.d.ts","sourceRoot":"","sources":["../../src/internal/ipv4-ranges.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAwChD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,CAMnD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAMjD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEnD"}

package/dist/internal/ipv4-ranges.js

@@ -0,0 +1,73 @@
+const RANGE_MASK = new Uint32Array([
+    0xFFFFFFFF, 0xFFFFFF00, 0xFFFFFF00, 0xFFFFFF00,
+    0xFFFFFF00, 0xFFFFFF00, 0xFFFFFF00, 0xFFFFFF00,
+    0xFFFFFF00, 0xFFFF0000, 0xFFFF0000, 0xFFFE0000,
+    0xFFF00000, 0xFFC00000, 0xFF000000, 0xFF000000,
+    0xFF000000, 0xF0000000, 0xF0000000,
+]);
+const RANGE_MASKED = new Uint32Array([
+    0xFFFFFFFF, 0xC0AF3000, 0xC01FC400, 0xC034C100,
+    0xC0000000, 0xC0000200, 0xC0586300, 0xC6336400,
+    0xCB007100, 0xC0A80000, 0xA9FE0000, 0xC6120000,
+    0xAC100000, 0x64400000, 0x0A000000, 0x7F000000,
+    0x00000000, 0xE0000000, 0xF0000000,
+]);
+const RANGE_NAMES = [
+    'broadcast', 'as112', 'as112', 'amt',
+    'reserved', 'reserved', 'reserved', 'reserved',
+    'reserved', 'private', 'linkLocal', 'reserved',
+    'private', 'carrierGradeNat', 'private', 'loopback',
+    'unspecified', 'multicast', 'reserved',
+];
+const RANGE_COUNT = RANGE_MASK.length;
+// First-octet filter: 0 = may belong to a special range, 0xFF = unicast
+const FIRST_OCTET = new Uint8Array(256);
+FIRST_OCTET.fill(0xFF);
+for (let i = 0; i < RANGE_COUNT; i++) {
+    const lo = RANGE_MASKED[i] >>> 24;
+    const maskBits = Math.clz32(~RANGE_MASK[i] >>> 0);
+    const span = maskBits <= 8 ? 1 << (8 - maskBits) : 1;
+    for (let o = lo; o < lo + span && o < 256; o++) {
+        FIRST_OCTET[o] = 0;
+    }
+}
+/**
+ * Classifies a packed uint32 IPv4 address into its IANA-assigned range.
+ * @param ip - Packed uint32 IP address
+ * @returns The range name (e.g. "private", "loopback", "unicast")
+ */
+export function ipv4Range(ip) {
+    if (FIRST_OCTET[ip >>> 24] === 0xFF)
+        return 'unicast';
+    for (let i = 0; i < RANGE_COUNT; i++) {
+        if (((ip & RANGE_MASK[i]) >>> 0) === RANGE_MASKED[i])
+            return RANGE_NAMES[i];
+    }
+    return 'unicast';
+}
+/**
+ * Checks whether a packed uint32 IPv4 address is in a private range (RFC 1918).
+ * @param ip - Packed uint32 IP address
+ * @returns True if the address is in 10.0.0.0/8, 172.16.0.0/12, or 192.168.0.0/16
+ */
+export function isPrivateIPv4(ip) {
+    return ((ip >>> 24) === 10 ||
+        (ip >>> 20) === 0xAC1 ||
+        (ip >>> 16) === 0xC0A8);
+}
+/**
+ * Checks whether a packed uint32 IPv4 address is a loopback address (127.0.0.0/8).
+ * @param ip - Packed uint32 IP address
+ * @returns True if the address is in the loopback range
+ */
+export function isLoopbackIPv4(ip) {
+    return (ip >>> 24) === 127;
+}
+/**
+ * Checks whether a packed uint32 IPv4 address is link-local (169.254.0.0/16).
+ * @param ip - Packed uint32 IP address
+ * @returns True if the address is in the link-local range
+ */
+export function isLinkLocalIPv4(ip) {
+    return (ip >>> 16) === 0xA9FE;
+}

package/dist/internal/ipv4.d.ts

@@ -0,0 +1,44 @@
+import type { IPv4Addr } from '../types.ts';
+declare const maskV4LUT: Uint32Array<ArrayBuffer>;
+export { maskV4LUT };
+/**
+ * Parses a strict dotted-decimal IPv4 string into a raw uint32.
+ * @param s - Source string
+ * @param start - Start index within the string
+ * @param end - End index (exclusive) within the string
+ * @returns The packed uint32 IP address, or -1 if invalid
+ */
+export declare function parseIPv4Raw(s: string, start: number, end: number): number;
+/**
+ * Parses a strict dotted-decimal IPv4 string into an IPv4Addr.
+ * @param s - The IPv4 string (e.g. "192.168.1.1")
+ * @param end - Optional end index for parsing a substring
+ * @returns The parsed address, or null if invalid
+ */
+export declare function parseIPv4(s: string, end?: number): IPv4Addr | null;
+/**
+ * Checks whether a string is a valid strict dotted-decimal IPv4 address.
+ * @param s - The string to validate
+ * @returns True if the string is a valid IPv4 address
+ */
+export declare function isIPv4(s: string): boolean;
+/**
+ * Parses an IPv4 string with relaxed rules: hex (0x), octal (0), and
+ * classful shorthand (e.g. "10.1" = "10.0.0.1") are accepted.
+ * @param s - The IPv4 string in any accepted notation
+ * @returns The parsed address, or null if invalid
+ */
+export declare function parseIPv4Loose(s: string): IPv4Addr | null;
+/**
+ * Extracts the four octets of a packed uint32 IPv4 address.
+ * @param ip - Packed uint32 IP address
+ * @returns Tuple of four octets [a, b, c, d]
+ */
+export declare function ipv4ToOctets(ip: number): [number, number, number, number];
+/**
+ * Converts a packed uint32 IPv4 address to dotted-decimal string.
+ * @param ip - Packed uint32 IP address
+ * @returns Dotted-decimal string (e.g. "192.168.1.1")
+ */
+export declare function ipv4ToString(ip: number): string;
+//# sourceMappingURL=ipv4.d.ts.map

package/dist/internal/ipv4.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ipv4.d.ts","sourceRoot":"","sources":["../../src/internal/ipv4.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAa3C,QAAA,MAAM,SAAS,0BAAsB,CAAA;AAErC,OAAO,EAAE,SAAS,EAAE,CAAA;AA4CpB;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAgC1E;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAGlE;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAEzC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAoCzD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEzE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE/C"}

package/dist/internal/ipv4.js

@@ -0,0 +1,183 @@
+// --- Constants & lookup tables ---
+// Prebuilt "a.b" strings for all 16-bit values, indexed by (hi_octet << 8 | lo_octet)
+const PAIR_CACHE = new Array(65536);
+for (let i = 0; i < 65536; i++)
+    PAIR_CACHE[i] = String((i >>> 8) & 0xFF) + '.' + String(i & 0xFF);
+// Same as PAIR_CACHE but with trailing dot for concatenation in ipv4ToString
+const PAIR_DOT_CACHE = new Array(65536);
+for (let i = 0; i < 65536; i++)
+    PAIR_DOT_CACHE[i] = PAIR_CACHE[i] + '.';
+// Subnet masks for prefix lengths 0..32
+const maskV4LUT = new Uint32Array(33);
+for (let i = 1; i <= 32; i++)
+    maskV4LUT[i] = (0xFFFFFFFF << (32 - i)) >>> 0;
+export { maskV4LUT };
+// Character classification table: maps charCode to digit value (0-9), dot (0xFE), or invalid (0xFF)
+const V4_CHAR = new Uint8Array(128);
+V4_CHAR.fill(0xFF);
+for (let i = 0; i < 10; i++)
+    V4_CHAR[48 + i] = i;
+V4_CHAR[46] = 0xFE;
+// --- Non-exported helpers ---
+function parseAutoInt(s, start, end) {
+    if (start >= end)
+        return -1;
+    const c0 = s.charCodeAt(start);
+    if (c0 === 48 && end - start > 1) {
+        const c1 = s.charCodeAt(start + 1) | 0x20;
+        if (c1 === 0x78) {
+            let v = 0;
+            for (let i = start + 2; i < end; i++) {
+                const ch = s.charCodeAt(i) | 0x20;
+                if (ch >= 48 && ch <= 57)
+                    v = v * 16 + (ch - 48);
+                else if (ch >= 97 && ch <= 102)
+                    v = v * 16 + (ch - 87);
+                else
+                    return -1;
+            }
+            return v;
+        }
+        let v = 0;
+        for (let i = start; i < end; i++) {
+            const ch = s.charCodeAt(i);
+            if (ch < 48 || ch > 55)
+                return -1;
+            v = (v << 3) + (ch - 48);
+        }
+        return v;
+    }
+    let v = 0;
+    for (let i = start; i < end; i++) {
+        const ch = s.charCodeAt(i);
+        if (ch < 48 || ch > 57)
+            return -1;
+        v = v * 10 + (ch - 48);
+    }
+    return v;
+}
+// --- Exports ---
+/**
+ * Parses a strict dotted-decimal IPv4 string into a raw uint32.
+ * @param s - Source string
+ * @param start - Start index within the string
+ * @param end - End index (exclusive) within the string
+ * @returns The packed uint32 IP address, or -1 if invalid
+ */
+export function parseIPv4Raw(s, start, end) {
+    const len = end - start;
+    if (len < 7 || len > 15)
+        return -1;
+    let ip = 0;
+    let octet = 0;
+    let oStart = start;
+    let dot = 0;
+    for (let i = start; i < end; i++) {
+        const ch = s.charCodeAt(i);
+        if (ch >= 128)
+            return -1;
+        const v = V4_CHAR[ch];
+        if (v <= 9) {
+            octet = (octet * 10 + v) | 0;
+        }
+        else if (v === 0xFE) {
+            const dLen = i - oStart;
+            if (dLen === 0 || dLen > 3 || octet > 255)
+                return -1;
+            if (dLen > 1 && s.charCodeAt(oStart) === 48)
+                return -1;
+            ip = ip | (octet << (24 - (dot << 3)));
+            octet = 0;
+            oStart = i + 1;
+            if (++dot > 3)
+                return -1;
+        }
+        else {
+            return -1;
+        }
+    }
+    const dLen = end - oStart;
+    if (dot !== 3 || dLen === 0 || dLen > 3 || octet > 255)
+        return -1;
+    if (dLen > 1 && s.charCodeAt(oStart) === 48)
+        return -1;
+    return (ip | octet) >>> 0;
+}
+/**
+ * Parses a strict dotted-decimal IPv4 string into an IPv4Addr.
+ * @param s - The IPv4 string (e.g. "192.168.1.1")
+ * @param end - Optional end index for parsing a substring
+ * @returns The parsed address, or null if invalid
+ */
+export function parseIPv4(s, end) {
+    const ip = parseIPv4Raw(s, 0, end !== undefined ? end : s.length);
+    return ip !== -1 ? { ip, kind: 4 } : null;
+}
+/**
+ * Checks whether a string is a valid strict dotted-decimal IPv4 address.
+ * @param s - The string to validate
+ * @returns True if the string is a valid IPv4 address
+ */
+export function isIPv4(s) {
+    return parseIPv4Raw(s, 0, s.length) !== -1;
+}
+/**
+ * Parses an IPv4 string with relaxed rules: hex (0x), octal (0), and
+ * classful shorthand (e.g. "10.1" = "10.0.0.1") are accepted.
+ * @param s - The IPv4 string in any accepted notation
+ * @returns The parsed address, or null if invalid
+ */
+export function parseIPv4Loose(s) {
+    const len = s.length;
+    if (len === 0)
+        return null;
+    const dot1 = s.indexOf('.');
+    if (dot1 === -1) {
+        const v = parseAutoInt(s, 0, len);
+        if (v < 0 || v > 0xFFFFFFFF)
+            return null;
+        return { ip: v >>> 0, kind: 4 };
+    }
+    const dot2 = s.indexOf('.', dot1 + 1);
+    if (dot2 === -1) {
+        const a = parseAutoInt(s, 0, dot1);
+        const b = parseAutoInt(s, dot1 + 1, len);
+        if (a < 0 || a > 255 || b < 0 || b > 0xFFFFFF)
+            return null;
+        return { ip: ((a << 24) | (b & 0xFFFFFF)) >>> 0, kind: 4 };
+    }
+    const dot3 = s.indexOf('.', dot2 + 1);
+    if (dot3 === -1) {
+        const a = parseAutoInt(s, 0, dot1);
+        const b = parseAutoInt(s, dot1 + 1, dot2);
+        const c = parseAutoInt(s, dot2 + 1, len);
+        if (a < 0 || a > 255 || b < 0 || b > 255 || c < 0 || c > 0xFFFF)
+            return null;
+        return { ip: ((a << 24) | (b << 16) | (c & 0xFFFF)) >>> 0, kind: 4 };
+    }
+    if (s.indexOf('.', dot3 + 1) !== -1)
+        return null;
+    const a = parseAutoInt(s, 0, dot1);
+    const b = parseAutoInt(s, dot1 + 1, dot2);
+    const c = parseAutoInt(s, dot2 + 1, dot3);
+    const d = parseAutoInt(s, dot3 + 1, len);
+    if (a < 0 || a > 255 || b < 0 || b > 255 || c < 0 || c > 255 || d < 0 || d > 255)
+        return null;
+    return { ip: ((a << 24) | (b << 16) | (c << 8) | d) >>> 0, kind: 4 };
+}
+/**
+ * Extracts the four octets of a packed uint32 IPv4 address.
+ * @param ip - Packed uint32 IP address
+ * @returns Tuple of four octets [a, b, c, d]
+ */
+export function ipv4ToOctets(ip) {
+    return [ip >>> 24, (ip >>> 16) & 0xFF, (ip >>> 8) & 0xFF, ip & 0xFF];
+}
+/**
+ * Converts a packed uint32 IPv4 address to dotted-decimal string.
+ * @param ip - Packed uint32 IP address
+ * @returns Dotted-decimal string (e.g. "192.168.1.1")
+ */
+export function ipv4ToString(ip) {
+    return PAIR_DOT_CACHE[ip >>> 16] + PAIR_CACHE[ip & 0xFFFF];
+}

package/dist/internal/ipv6-ranges.d.ts

@@ -0,0 +1,47 @@
+import type { IPv6Addr, IPv6RangeName } from '../types.ts';
+/**
+ * Tests whether an IPv6 address matches a CIDR prefix using raw uint32 words.
+ * @param aw0 - Address word 0 (bits 0-31)
+ * @param aw1 - Address word 1 (bits 32-63)
+ * @param aw2 - Address word 2 (bits 64-95)
+ * @param aw3 - Address word 3 (bits 96-127)
+ * @param nw0 - Network word 0
+ * @param nw1 - Network word 1
+ * @param nw2 - Network word 2
+ * @param nw3 - Network word 3
+ * @param prefix - Prefix length (0-128)
+ * @returns True if the address is within the network prefix
+ */
+export declare function matchesCidr(aw0: number, aw1: number, aw2: number, aw3: number, nw0: number, nw1: number, nw2: number, nw3: number, prefix: number): boolean;
+/**
+ * Computes the bitmask for a specific 32-bit word of an IPv6 prefix.
+ * @param prefix - Prefix length (0-128)
+ * @param wordOffset - Which 32-bit word (0-3)
+ * @returns The uint32 mask for that word
+ */
+export declare function prefixMaskV6(prefix: number, wordOffset: number): number;
+/**
+ * Classifies an IPv6 address into its IANA-assigned range.
+ * @param addr - The IPv6 address
+ * @returns The range name (e.g. "uniqueLocal", "loopback", "unicast")
+ */
+export declare function ipv6Range(addr: IPv6Addr): IPv6RangeName;
+/**
+ * Checks whether an IPv6 address is private (unique-local, multicast, link-local, or loopback).
+ * @param addr - The IPv6 address
+ * @returns True if the address is non-globally-routable
+ */
+export declare function isPrivateIPv6(addr: IPv6Addr): boolean;
+/**
+ * Checks whether an IPv6 address is the loopback address (::1).
+ * @param addr - The IPv6 address
+ * @returns True if the address is ::1
+ */
+export declare function isLoopbackIPv6(addr: IPv6Addr): boolean;
+/**
+ * Checks whether an IPv6 address is link-local (fe80::/10).
+ * @param addr - The IPv6 address
+ * @returns True if the address is in the link-local range
+ */
+export declare function isLinkLocalIPv6(addr: IPv6Addr): boolean;
+//# sourceMappingURL=ipv6-ranges.d.ts.map

package/dist/internal/ipv6-ranges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ipv6-ranges.d.ts","sourceRoot":"","sources":["../../src/internal/ipv6-ranges.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AA2C1D;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAClD,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAClD,MAAM,EAAE,MAAM,GACb,OAAO,CA0BT;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAMvE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,aAAa,CAqBvD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAOrD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAEvD"}