ip-utilities 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dr. Skill Issue
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,238 @@
+# ip-utilities
+
+IP address parsing, validation, and CIDR operations for TypeScript.
+
+## Install
+
+```bash
+bun add ip-utilities
+# or
+npm install ip-utilities
+```
+
+## Quick Start
+
+```ts
+import {
+  parseIP, isIP, isIPOrCIDR,
+  isPrivateIP, isPublicIPOrCIDR,
+  parseCIDR, isIPInCIDR,
+  sortIPs,
+} from 'ip-utilities'
+
+isIP('192.168.1.1')              // true
+isIP('::1')                      // true
+isIPOrCIDR('10.0.0.0/8')        // true
+isPrivateIP('192.168.1.1')      // true
+isPublicIPOrCIDR('8.8.8.8')     // true
+isIPInCIDR('10.0.0.5', '10.0.0.0/8') // true
+
+const addr = parseIP('192.168.1.1')
+// { ip: 3232235777, kind: 4 }
+
+const cidr = parseCIDR('::1/128')
+// { addr: { w0: 0, w1: 0, w2: 0, w3: 1, kind: 6 }, prefix: 128, kind: 6 }
+
+sortIPs(['::1', '192.168.1.1', '10.0.0.1', '2001:db8::1'])
+// ['10.0.0.1', '192.168.1.1', '::1', '2001:db8::1']
+```
+
+## Sub-path Imports
+
+Each module is available as a separate entry point for tree-shaking:
+
+```ts
+import { parseIPv4, isIPv4 } from 'ip-utilities/ipv4'
+import { parseIPv6, ipv6ToString } from 'ip-utilities/ipv6'
+import { parseCIDR, ipInCIDR } from 'ip-utilities/cidr'
+import { ipv4Range, isPrivateIPv6 } from 'ip-utilities/ranges'
+import { sortIPs, compareIPs } from 'ip-utilities/sort'
+import ipRegex, { testV4 } from 'ip-utilities/regex'
+```
+
+## API
+
+### Validation
+
+| Function | Description |
+|---|---|
+| `isIP(s)` | Checks if a string is a valid IPv4 or IPv6 address |
+| `isIPv4(s)` | Checks if a string is a valid IPv4 address |
+| `isIPv6(s)` | Checks if a string is a valid IPv6 address |
+| `isCIDR(s)` | Checks if a string is valid CIDR notation |
+| `isIPOrCIDR(s)` | Checks if a string is a valid IP address or CIDR |
+| `isPrivateIP(s)` | Checks if a string is a valid IP in a private range |
+| `isPrivateIPOrCIDR(s)` | Checks if a valid IP/CIDR is in a private range |
+| `isPublicIPOrCIDR(s)` | Checks if a valid IP/CIDR is globally routable |
+| `detectIPType(s)` | Returns `4`, `6`, or `null` |
+
+### Parsing
+
+| Function | Returns | Description |
+|---|---|---|
+| `parseIP(s)` | `IPAddr \| null` | Auto-detects and parses IPv4 or IPv6 |
+| `parseIPv4(s)` | `IPv4Addr \| null` | Parses strict dotted-decimal IPv4 |
+| `parseIPv4Loose(s)` | `IPv4Addr \| null` | Parses IPv4 with hex, octal, and classful shorthand |
+| `parseIPv6(s)` | `IPv6Addr \| null` | Parses IPv6 with `::`, embedded IPv4, and zone IDs |
+| `parseCIDR(s)` | `CIDR \| null` | Auto-detects and parses IPv4 or IPv6 CIDR |
+| `parseCIDRv4(s)` | `CIDRv4 \| null` | Parses IPv4 CIDR notation |
+| `parseCIDRv6(s)` | `CIDRv6 \| null` | Parses IPv6 CIDR notation |
+
+### String Conversion
+
+| Function | Returns | Description |
+|---|---|---|
+| `ipv4ToString(ip)` | `string` | Packed uint32 to dotted-decimal (e.g. `"192.168.1.1"`) |
+| `ipv4ToOctets(ip)` | `[n, n, n, n]` | Packed uint32 to four octets |
+| `ipv6ToString(addr)` | `string` | Compressed RFC 5952 notation (e.g. `"::1"`) |
+| `ipv6ToNormalizedString(addr)` | `string` | Uncompressed without padding (e.g. `"0:0:0:0:0:0:0:1"`) |
+| `ipv6ToFixedString(addr)` | `string` | Zero-padded groups (e.g. `"0000:0000:...:0001"`) |
+
+### Range Classification
+
+| Function | Returns | Description |
+|---|---|---|
+| `ipv4Range(ip)` | `IPv4RangeName` | Classifies into IANA range (e.g. `"private"`, `"unicast"`) |
+| `ipv6Range(addr)` | `IPv6RangeName` | Classifies into IANA range (e.g. `"uniqueLocal"`, `"unicast"`) |
+| `isPrivateIPv4(ip)` | `boolean` | Checks RFC 1918 ranges (10/8, 172.16/12, 192.168/16) |
+| `isPrivateIPv6(addr)` | `boolean` | Checks unique-local, multicast, link-local, loopback |
+| `isLoopbackIPv4(ip)` | `boolean` | Checks 127.0.0.0/8 |
+| `isLoopbackIPv6(addr)` | `boolean` | Checks ::1 |
+| `isLinkLocalIPv4(ip)` | `boolean` | Checks 169.254.0.0/16 |
+| `isLinkLocalIPv6(addr)` | `boolean` | Checks fe80::/10 |
+
+### CIDR Operations
+
+| Function | Returns | Description |
+|---|---|---|
+| `ipInCIDR(ip, cidr)` | `boolean` | Checks if a parsed IP is within a parsed CIDR range |
+| `ipInCIDRv4(ip, cidr)` | `boolean` | IPv4-specific CIDR containment check |
+| `ipInCIDRv6(ip, cidr)` | `boolean` | IPv6-specific CIDR containment check |
+| `isIPInCIDR(ipStr, cidrStr)` | `boolean` | Parses both strings and checks containment |
+| `networkAddressV4(cidr)` | `IPv4Addr` | First address in an IPv4 CIDR range |
+| `broadcastAddressV4(cidr)` | `IPv4Addr` | Last address in an IPv4 CIDR range |
+| `networkAddressV6(cidr)` | `IPv6Addr` | First address in an IPv6 CIDR range |
+| `broadcastAddressV6(cidr)` | `IPv6Addr` | Last address in an IPv6 CIDR range |
+| `subnetMaskV4(prefix)` | `number` | Subnet mask for a prefix length (0-32) |
+| `prefixFromSubnetMask(mask)` | `number \| null` | Prefix length from a contiguous subnet mask |
+
+### IPv6 Utilities
+
+| Function | Returns | Description |
+|---|---|---|
+| `isIPv4Mapped(addr)` | `boolean` | Checks if address is IPv4-mapped (::ffff:0:0/96) |
+| `ipv6ToIPv4(addr)` | `number` | Extracts the embedded IPv4 uint32 from lower 32 bits |
+| `ipv6ToWords(addr)` | `[x8 number]` | Expands to eight 16-bit groups |
+| `ipv6GetZoneId(addr)` | `string` | Retrieves the zone ID (e.g. `"eth0"`) or empty string |
+
+### Sorting
+
+| Function | Returns | Description |
+|---|---|---|
+| `sortIPs(ips)` | `string[]` | Sorts IP/CIDR strings in network order (new array) |
+| `compareIPs(a, b)` | `number` | Comparator for two IP/CIDR strings (cached) |
+| `clearSortCache()` | `void` | Clears the internal comparison cache |
+
+Sort order: IPv4 before IPv6, numeric within each version, invalid strings last (lexicographic among themselves), CIDR entries with the same network sort by prefix length.
+
+### Regex
+
+```ts
+import ipRegex, { testV4, testV6, testV46 } from 'ip-utilities/regex'
+```
+
+| Export | Description |
+|---|---|
+| `testV4(s)` | Fast exact IPv4 string test |
+| `testV6(s)` | Fast exact IPv6 string test |
+| `testV46(s)` | Fast exact IPv4-or-IPv6 string test |
+| `ipRegex(options?)` | Returns a RegExp matching IPv4 and IPv6 |
+| `ipRegex.v4(options?)` | Returns a RegExp matching IPv4 only |
+| `ipRegex.v6(options?)` | Returns a RegExp matching IPv6 only |
+| `ipRegex.scanAll(input, options?)` | Extracts all IP addresses from a string |
+| `ipRegex.scanAllV4(input, options?)` | Extracts all IPv4 addresses from a string |
+| `ipRegex.scanAllV6(input, options?)` | Extracts all IPv6 addresses from a string |
+
+**Options:**
+
+- `exact` -- Match the entire string only (anchored)
+- `includeBoundaries` -- Require whitespace or string boundaries around matches
+
+**ScanResult:**
+
+```ts
+{ value: string, index: number }
+```
+
+## Types
+
+```ts
+interface IPv4Addr {
+  readonly ip: number    // Packed uint32
+  readonly kind: 4
+}
+
+interface IPv6Addr {
+  readonly w0: number    // Bits 0-31
+  readonly w1: number    // Bits 32-63
+  readonly w2: number    // Bits 64-95
+  readonly w3: number    // Bits 96-127
+  readonly kind: 6
+}
+
+type IPAddr = IPv4Addr | IPv6Addr
+
+interface CIDRv4 {
+  readonly addr: IPv4Addr
+  readonly prefix: number
+  readonly kind: 4
+}
+
+interface CIDRv6 {
+  readonly addr: IPv6Addr
+  readonly prefix: number
+  readonly kind: 6
+}
+
+type CIDR = CIDRv4 | CIDRv6
+```
+
+All types use a `kind` discriminant for narrowing:
+
+```ts
+const addr = parseIP(input)
+if (addr?.kind === 4) {
+  // addr is IPv4Addr
+  console.log(ipv4ToString(addr.ip))
+} else if (addr?.kind === 6) {
+  // addr is IPv6Addr
+  console.log(ipv6ToString(addr))
+}
+```
+
+## Benchmarks
+
+Compared to ipaddr.js (v2.3.0) on AMD Ryzen 9 7950X, Bun 1.3:
+
+| Operation | ip-utilities | ipaddr.js | Speedup |
+|---|---|---|---|
+| IPv4 parse (10 addrs) | 180 ns | 1,910 ns | **10.6x** |
+| IPv6 parse (10 addrs) | 310 ns | 5,140 ns | **16.6x** |
+| isValid (20 mixed) | 533 ns | 8,310 ns | **15.6x** |
+| parse (20 mixed) | 593 ns | 15,960 ns | **26.9x** |
+| CIDR match (strings) | 53 ns | 2,140 ns | **40.8x** |
+| parseCIDR IPv4 | 26 ns | 1,930 ns | **74.4x** |
+| parseCIDR IPv6 | 33 ns | 896 ns | **27.2x** |
+| invalid IPv4 | 33 ns | 4,950 ns | **151.7x** |
+| invalid IPv6 | 52 ns | 5,280 ns | **101.8x** |
+
+Run benchmarks locally:
+
+```bash
+bun run test/bench/ip.bench.ts
+bun run test/bench/memory.bench.ts
+```
+
+## License
+
+MIT

package/dist/cidr.d.ts

@@ -0,0 +1,2 @@
+export { parseCIDR, parseCIDRv4, parseCIDRv6, isCIDR, isIPInCIDR, ipInCIDR, ipInCIDRv4, ipInCIDRv6, networkAddressV4, broadcastAddressV4, networkAddressV6, broadcastAddressV6, subnetMaskV4, prefixFromSubnetMask } from './internal/cidr.ts';
+//# sourceMappingURL=cidr.d.ts.map

package/dist/cidr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cidr.d.ts","sourceRoot":"","sources":["../src/cidr.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/cidr.js

@@ -0,0 +1 @@
+export { parseCIDR, parseCIDRv4, parseCIDRv6, isCIDR, isIPInCIDR, ipInCIDR, ipInCIDRv4, ipInCIDRv6, networkAddressV4, broadcastAddressV4, networkAddressV6, broadcastAddressV6, subnetMaskV4, prefixFromSubnetMask } from "./internal/cidr.js";

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+import type { IPAddr } from './types.ts';
+export { parseIPv4, isIPv4, parseIPv4Loose, ipv4ToOctets, ipv4ToString } from './ipv4.ts';
+export { parseIPv6, isIPv6, isIPv4Mapped, ipv6ToWords, ipv6ToString, ipv6ToNormalizedString, ipv6ToFixedString, ipv6ToIPv4, ipv6GetZoneId } from './ipv6.ts';
+export { ipv4Range, isPrivateIPv4, isLoopbackIPv4, isLinkLocalIPv4, ipv6Range, isPrivateIPv6, isLoopbackIPv6, isLinkLocalIPv6 } from './ranges.ts';
+export { parseCIDR, parseCIDRv4, parseCIDRv6, isCIDR, isIPInCIDR, ipInCIDR, ipInCIDRv4, ipInCIDRv6, networkAddressV4, broadcastAddressV4, networkAddressV6, broadcastAddressV6, subnetMaskV4, prefixFromSubnetMask } from './cidr.ts';
+export { compareIPs, sortIPs, clearSortCache } from './sort.ts';
+export { default as ipRegex, testV4, testV6, testV46 } from './regex.ts';
+export type { Options as RegexOptions, ScanResult, IpRegex } from './regex.ts';
+export type { IPv4Addr, IPv6Addr, IPAddr, CIDRv4, CIDRv6, CIDR, IPv4RangeName, IPv6RangeName } from './types.ts';
+/**
+ * Parses an IP address string, auto-detecting IPv4 or IPv6.
+ * @param s - The IP address string
+ * @returns The parsed address, or null if invalid
+ */
+export declare function parseIP(s: string): IPAddr | null;
+/**
+ * Checks whether a string is a valid IPv4 or IPv6 address.
+ * @param s - The string to validate
+ * @returns True if the string is a valid IP address
+ */
+export declare function isIP(s: string): boolean;
+/**
+ * Detects the IP version of a string.
+ * @param s - The string to check
+ * @returns 4 for IPv4, 6 for IPv6, or null if invalid
+ */
+export declare function detectIPType(s: string): 4 | 6 | null;
+/**
+ * Checks whether a string is a valid IP address or CIDR notation.
+ * @param s - The string to validate
+ * @returns True if the string is a valid IP or CIDR
+ */
+export declare function isIPOrCIDR(s: string): boolean;
+/**
+ * Checks whether a string is a valid IP address in a private range.
+ * @param s - The IP address string
+ * @returns True if the address is valid and private
+ */
+export declare function isPrivateIP(s: string): boolean;
+/**
+ * Checks whether a string is a valid IP or CIDR in a private range.
+ * For CIDR input, the address portion is checked.
+ * @param s - The IP or CIDR string
+ * @returns True if valid and private
+ */
+export declare function isPrivateIPOrCIDR(s: string): boolean;
+/**
+ * Checks whether a string is a valid IP or CIDR in a globally routable (unicast) range.
+ * For CIDR input, the address portion is checked.
+ * @param s - The IP or CIDR string
+ * @returns True if valid and publicly routable
+ */
+export declare function isPublicIPOrCIDR(s: string): boolean;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAExC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACzF,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAC5J,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,SAAS,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClJ,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AACrO,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC/D,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AACxE,YAAY,EAAE,OAAO,IAAI,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAC9E,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAEhH;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIhD;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAEvC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAIpD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAO9C;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAKpD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAKnD"}

package/dist/index.js

@@ -0,0 +1,89 @@
+import { parseIPv4Raw, isIPv4 } from "./internal/ipv4.js";
+import { parseIPv6, isIPv6 } from "./internal/ipv6.js";
+import { parseIPOrCIDR, parseIPOrCIDRv4, v6AddrFromBuf } from "./internal/cidr.js";
+import { ipv4Range, isPrivateIPv4 } from "./internal/ipv4-ranges.js";
+import { ipv6Range, isPrivateIPv6 } from "./internal/ipv6-ranges.js";
+export { parseIPv4, isIPv4, parseIPv4Loose, ipv4ToOctets, ipv4ToString } from "./ipv4.js";
+export { parseIPv6, isIPv6, isIPv4Mapped, ipv6ToWords, ipv6ToString, ipv6ToNormalizedString, ipv6ToFixedString, ipv6ToIPv4, ipv6GetZoneId } from "./ipv6.js";
+export { ipv4Range, isPrivateIPv4, isLoopbackIPv4, isLinkLocalIPv4, ipv6Range, isPrivateIPv6, isLoopbackIPv6, isLinkLocalIPv6 } from "./ranges.js";
+export { parseCIDR, parseCIDRv4, parseCIDRv6, isCIDR, isIPInCIDR, ipInCIDR, ipInCIDRv4, ipInCIDRv6, networkAddressV4, broadcastAddressV4, networkAddressV6, broadcastAddressV6, subnetMaskV4, prefixFromSubnetMask } from "./cidr.js";
+export { compareIPs, sortIPs, clearSortCache } from "./sort.js";
+export { default as ipRegex, testV4, testV6, testV46 } from "./regex.js";
+/**
+ * Parses an IP address string, auto-detecting IPv4 or IPv6.
+ * @param s - The IP address string
+ * @returns The parsed address, or null if invalid
+ */
+export function parseIP(s) {
+    if (s.indexOf(':') !== -1)
+        return parseIPv6(s);
+    const ip = parseIPv4Raw(s, 0, s.length);
+    return ip !== -1 ? { ip, kind: 4 } : null;
+}
+/**
+ * Checks whether a string is a valid IPv4 or IPv6 address.
+ * @param s - The string to validate
+ * @returns True if the string is a valid IP address
+ */
+export function isIP(s) {
+    return s.indexOf(':') === -1 ? isIPv4(s) : isIPv6(s);
+}
+/**
+ * Detects the IP version of a string.
+ * @param s - The string to check
+ * @returns 4 for IPv4, 6 for IPv6, or null if invalid
+ */
+export function detectIPType(s) {
+    return s.indexOf(':') === -1
+        ? (isIPv4(s) ? 4 : null)
+        : (isIPv6(s) ? 6 : null);
+}
+/**
+ * Checks whether a string is a valid IP address or CIDR notation.
+ * @param s - The string to validate
+ * @returns True if the string is a valid IP or CIDR
+ */
+export function isIPOrCIDR(s) {
+    return parseIPOrCIDR(s) !== 0;
+}
+/**
+ * Checks whether a string is a valid IP address in a private range.
+ * @param s - The IP address string
+ * @returns True if the address is valid and private
+ */
+export function isPrivateIP(s) {
+    if (s.indexOf(':') === -1) {
+        const ip = parseIPv4Raw(s, 0, s.length);
+        return ip !== -1 && isPrivateIPv4(ip);
+    }
+    const v6 = parseIPv6(s);
+    return v6 !== null && isPrivateIPv6(v6);
+}
+/**
+ * Checks whether a string is a valid IP or CIDR in a private range.
+ * For CIDR input, the address portion is checked.
+ * @param s - The IP or CIDR string
+ * @returns True if valid and private
+ */
+export function isPrivateIPOrCIDR(s) {
+    const kind = parseIPOrCIDR(s);
+    if (kind === 4)
+        return isPrivateIPv4(parseIPOrCIDRv4);
+    if (kind === 6)
+        return isPrivateIPv6(v6AddrFromBuf());
+    return false;
+}
+/**
+ * Checks whether a string is a valid IP or CIDR in a globally routable (unicast) range.
+ * For CIDR input, the address portion is checked.
+ * @param s - The IP or CIDR string
+ * @returns True if valid and publicly routable
+ */
+export function isPublicIPOrCIDR(s) {
+    const kind = parseIPOrCIDR(s);
+    if (kind === 4)
+        return ipv4Range(parseIPOrCIDRv4) === 'unicast';
+    if (kind === 6)
+        return ipv6Range(v6AddrFromBuf()) === 'unicast';
+    return false;
+}

package/dist/internal/cidr.d.ts

@@ -0,0 +1,112 @@
+import type { IPv4Addr, IPv6Addr, IPAddr, CIDRv4, CIDRv6, CIDR } from '../types.ts';
+export declare let parseIPOrCIDRv4: number;
+/**
+ * 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 declare function parsePrefixInline(s: string, start: number, end: number, max: number): number;
+/**
+ * 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 declare function parseCIDRv4(s: string): CIDRv4 | null;
+/**
+ * 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 declare function parseCIDRv6(s: string): CIDRv6 | null;
+/**
+ * Parses a CIDR string, auto-detecting IPv4 or IPv6.
+ * @param s - The CIDR string
+ * @returns The parsed CIDR, or null if invalid
+ */
+export declare function parseCIDR(s: string): CIDR | null;
+/**
+ * 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 declare function isCIDR(s: string): boolean;
+/**
+ * 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 declare function ipInCIDRv4(ip: IPv4Addr, cidr: CIDRv4): boolean;
+/**
+ * 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 declare function ipInCIDRv6(ip: IPv6Addr, cidr: CIDRv6): boolean;
+/**
+ * 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 declare function ipInCIDR(ip: IPAddr, cidr: CIDR): boolean;
+/**
+ * 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 declare function isIPInCIDR(ipStr: string, cidrStr: string): boolean;
+/**
+ * Computes the network address (first address) of an IPv4 CIDR range.
+ * @param cidr - The CIDRv4 range
+ * @returns The network address
+ */
+export declare function networkAddressV4(cidr: CIDRv4): IPv4Addr;
+/**
+ * Computes the broadcast address (last address) of an IPv4 CIDR range.
+ * @param cidr - The CIDRv4 range
+ * @returns The broadcast address
+ */
+export declare function broadcastAddressV4(cidr: CIDRv4): IPv4Addr;
+/**
+ * Computes the network address (first address) of an IPv6 CIDR range.
+ * @param cidr - The CIDRv6 range
+ * @returns The network address
+ */
+export declare function networkAddressV6(cidr: CIDRv6): IPv6Addr;
+/**
+ * Computes the broadcast address (last address) of an IPv6 CIDR range.
+ * @param cidr - The CIDRv6 range
+ * @returns The broadcast address
+ */
+export declare function broadcastAddressV6(cidr: CIDRv6): IPv6Addr;
+/**
+ * Returns the subnet mask for an IPv4 prefix length.
+ * @param prefix - Prefix length (0-32)
+ * @returns The uint32 subnet mask
+ */
+export declare function subnetMaskV4(prefix: number): number;
+/**
+ * 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 declare function prefixFromSubnetMask(mask: number): number | null;
+/**
+ * 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 declare function parseIPOrCIDR(s: string): number;
+/**
+ * Constructs an IPv6Addr from the shared ipv6RawBuf after a successful parseIPv6Raw call.
+ * @returns The IPv6Addr built from the raw buffer
+ */
+export declare function v6AddrFromBuf(): IPv6Addr;
+//# sourceMappingURL=cidr.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cidr.d.ts","sourceRoot":"","sources":["../../src/internal/cidr.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAiBnF,eAAO,IAAI,eAAe,QAAI,CAAA;AAI9B;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAW5F;AAID;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQpD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQpD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAYhD;AAID;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAczC;AAID;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAG9D;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAM9D;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAIxD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAWlE;AAID;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAGvD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAGzD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAUvD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAUzD;AAID;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKhE;AAID;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAyB/C;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,QAAQ,CAExC"}