@sdxc/ip 0.0.0-pre.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio Xalambrí
+
+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,179 @@
+# @sdxc/ip
+
+IPv4 and IPv6 addresses and ranges as value objects that classify against the IANA special-purpose registries.
+
+An `IP` is one parsed, valid address. A function that takes one cannot be handed `"unknown"`, `"10.0.0"` or a hostname, and the address can say whether it is on the public internet, which network it sits in, and how it is spelled canonically. Nothing performs I/O, so it runs wherever an address arrives as text: a URL host, a DNS answer, a request header.
+
+## Installation
+
+```bash
+npm add @sdxc/ip
+```
+
+Parsing answers a `Result` from [`@sdxc/result`](https://www.npmjs.com/package/@sdxc/result), installed with this package.
+
+## Usage
+
+### Parsing An Address
+
+```typescript
+import { IP } from "@sdxc/ip";
+import { isFailure } from "@sdxc/result";
+
+let parsed = IP.parse("2001:DB8::0:1");
+if (isFailure(parsed)) return parsed; // IP.Error { code: "invalid-address" }
+
+let ip = parsed.data;
+ip.version; // 6
+ip.toString(); // "2001:db8::1"
+ip.isPublic; // false: documentation range
+```
+
+### Refusing A URL That Points Inside The Network
+
+```typescript
+import { IP } from "@sdxc/ip";
+import { isSuccess } from "@sdxc/result";
+
+function isPublicHost(url: URL): boolean {
+	let ip = IP.parse(url.hostname);
+	return isSuccess(ip) && ip.data.isPublic;
+}
+
+isPublicHost(new URL("http://169.254.169.254/")); // false
+isPublicHost(new URL("http://[::ffff:10.0.0.1]/")); // false
+isPublicHost(new URL("http://[::ffff:8.8.8.8]/")); // true
+```
+
+### Testing A Range
+
+```typescript
+let office = IP.Range.parse("203.0.113.0/24");
+if (isSuccess(office)) office.data.contains(ip); // false across versions
+
+IP.Range.parse("10.0.0.1/8"); // failure: IP.Error { code: "host-bits-set" }
+```
+
+### Keying A Rate Limit On The Client's Network
+
+An IPv6 client is normally assigned a whole `/64`, so a key on the full address counts each address it rotates through separately.
+
+```typescript
+ip.network({ v4: 32, v6: 64 }).toString(); // "2001:db8:1:2::/64" or "203.0.113.7/32"
+```
+
+## API
+
+### `IP.parse(text): Result<IP, IP.Error>`
+
+Parses an IPv4 or IPv6 address. Brackets around IPv6 are accepted (`[::1]`), the way a URL host spells it. IPv4 must be canonical dotted decimal: `URL` already normalizes octal, hex and bare-integer hosts, and refusing them here keeps any other input from naming a different address than it appears to. Zone identifiers (`fe80::1%eth0`) are refused.
+
+### `IP`
+
+Immutable, and only obtainable from `IP.parse`.
+
+- `version` — `4` or `6`.
+- `classification` — what the IANA special-purpose registries say the address is for: `"public"`, `"unspecified"`, `"loopback"`, `"private"`, `"shared"`, `"link-local"`, `"documentation"`, `"benchmarking"`, `"multicast"`, `"reserved"`, `"unique-local"`, `"teredo"` or `"discard"`. IPv6 outside `2000::/3` and not otherwise assigned is `"reserved"`.
+- `isPublic` — `classification === "public"`.
+- `embeddedIPv4` — the IPv4 address inside an IPv4-mapped (`::ffff:0:0/96`), NAT64 (`64:ff9b::/96`) or 6to4 (`2002::/16`) address, or `null`. `classification` and `isPublic` judge those addresses by the IPv4 inside, so `::ffff:10.0.0.1` is `"private"`.
+- `network({ v4, v6 })` — the `IP.Range` the address sits in at the prefix length for its version. A length outside the version's width is clamped into it.
+- `equals(other)` — same version and same address. `===` compares object identity, so compare two `IP`s with this.
+- `toString()` — canonical text: dotted decimal, or [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952) IPv6 (lowercase, longest zero run compressed, IPv4-mapped ending in a dotted quad), without brackets. Every spelling of one address prints one string, so it is the key for a `Map`, a rate limit, a log field or a database column.
+- `toJSON()` — the same string, so `JSON.stringify({ ip })` writes `{"ip":"2001:db8::1"}`.
+
+A structured clone (Durable Object storage, `postMessage`) drops the methods. Store `toString()` and parse it back on read.
+
+### `IP.Range.parse(text): Result<IP.Range, IP.Error>`
+
+Parses `network/prefix` text. A network address with bits set past the prefix fails with `host-bits-set`; anything else malformed fails with `invalid-range`.
+
+### `IP.Range`
+
+Immutable, and only obtainable from `IP.Range.parse` or `ip.network`.
+
+- `network` — the first address, as an `IP`.
+- `prefix` — the prefix length.
+- `version` — `4` or `6`.
+- `contains(ip)` — whether the address shares the range's leading bits. An address of the other version is never a member.
+- `equals(other)`, `toString()`, `toJSON()` — as on `IP`; the text is `network/prefix`, such as `2001:db8::/32`.
+
+### `IP.Error`
+
+The failure both parsers answer, never thrown. `code` is `"invalid-address"`, `"invalid-range"` or `"host-bits-set"`, and `input` is the rejected text. It is a class, so `error instanceof IP.Error` narrows.
+
+### Types
+
+`IP.Range`, `IP.Error`, `IP.ErrorCode`, `IP.Classification` and `IP.Prefixes` (`{ v4: number; v6: number }`) are types under the same `IP` name.
+
+## Pattern: An Allowlist Of Networks
+
+```typescript
+import { IP } from "@sdxc/ip";
+import { isSuccess } from "@sdxc/result";
+
+const OFFICE_RANGES = ["203.0.113.0/24", "2001:db8:42::/48"];
+
+function isOffice(ip: IP): boolean {
+	return OFFICE_RANGES.some((text) => {
+		let range = IP.Range.parse(text);
+		return isSuccess(range) && range.data.contains(ip);
+	});
+}
+```
+
+## Pattern: Checking Every Address A Name Resolves To
+
+A literal check only stops `http://127.0.0.1`. A public name whose `A` record points at an internal address is caught by classifying every answer before fetching:
+
+```typescript
+import { IP } from "@sdxc/ip";
+import { isSuccess } from "@sdxc/result";
+
+function allPublic(answers: string[]): boolean {
+	return (
+		answers.length > 0 &&
+		answers.every((answer) => {
+			let ip = IP.parse(answer);
+			return isSuccess(ip) && ip.data.isPublic;
+		})
+	);
+}
+```
+
+## Pattern: A Function That Only Accepts A Checked Address
+
+```typescript
+import type { IP } from "@sdxc/ip";
+
+function recordProbe(target: IP, at: number) {
+	return { target: target.toString(), at };
+}
+
+recordProbe("10.0.0.1", Date.now()); // type error: a string is not an IP
+```
+
+## Versioning
+
+Releases are dated rather than semantic. A version is the UTC date it was published, written `YYYY.M.D`, so `2026.9.4` is the release from 4 September 2026. At most one release goes out per day.
+
+Those numbers say when, not what: a later date means a later release and carries no compatibility promise. Any release may change or remove an export.
+
+Depend on one exact date, and move it when you are ready to take the change:
+
+```json
+{
+	"dependencies": {
+		"@sdxc/ip": "2026.9.4"
+	}
+}
+```
+
+A caret or tilde range reads the date as major, minor and patch, so it accepts every later release in the same year. An exact version keeps the upgrade yours to schedule.
+
+## License
+
+MIT
+
+## Author
+
+[Sergio Xalambrí](https://sergiodxa.com)

package/dist/address.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The numeric form every address and range in the package is built on: a version
+ * and the address as one unsigned integer. Parsing text into it and printing it as
+ * RFC 5952 canonical text live here, so both classes agree on a single spelling.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * An address as a number: 32 bits for IPv4, 128 for IPv6. A `bigint` for both
+ * versions, so masking and comparison are the same operations whatever the width.
+ */
+export interface Address {
+    version: 4 | 6;
+    value: bigint;
+}
+/** How many bits an address of each version holds. */
+export declare const ADDRESS_BITS: {
+    readonly 4: 32;
+    readonly 6: 128;
+};
+/**
+ * Reads the text a URL host, a header or a DNS answer carries into an address.
+ * Brackets are accepted around IPv6 only, the way a URL host spells it.
+ *
+ * @param text - The address as written.
+ * @returns The address, or `null` when the text is not one.
+ */
+export declare function parseAddress(text: string): Address | null;
+/**
+ * Prints an address as its one canonical spelling, so two spellings of the same
+ * address always print the same string.
+ *
+ * @param address - The address to print.
+ * @returns Dotted decimal for IPv4, RFC 5952 text for IPv6, without brackets.
+ */
+export declare function formatAddress(address: Address): string;
+/**
+ * Clears every bit past the first `prefix`, giving the first address of the network
+ * an address sits in.
+ *
+ * @param address - The address to mask.
+ * @param prefix - How many leading bits to keep, already within the version's width.
+ * @returns The network address.
+ */
+export declare function maskAddress(address: Address, prefix: number): Address;

package/dist/address.js

@@ -0,0 +1,178 @@
+/**
+ * The numeric form every address and range in the package is built on: a version
+ * and the address as one unsigned integer. Parsing text into it and printing it as
+ * RFC 5952 canonical text live here, so both classes agree on a single spelling.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** How many bits an address of each version holds. */
+export const ADDRESS_BITS = { 4: 32, 6: 128 };
+/**
+ * A decimal octet as `URL` prints one: no leading zero, so `010` is refused rather
+ * than read as decimal ten by one parser and octal eight by another.
+ */
+const IPV4_OCTET = /^(?:0|[1-9]\d{0,2})$/;
+/** One IPv6 group: up to four hex digits, either case. */
+const IPV6_GROUP = /^[\da-f]{1,4}$/i;
+/** The first 80 bits of every IPv4-mapped address are zero, then sixteen ones. */
+const IPV4_MAPPED_PREFIX = 0xffffn << 32n;
+/**
+ * Reads a dotted quad into its 32-bit value.
+ *
+ * @param text - Four decimal octets.
+ * @returns The value, or `null` for any other spelling, octal, hex and bare integers included.
+ */
+function parseIPv4(text) {
+    let parts = text.split(".");
+    if (parts.length !== 4)
+        return null;
+    let value = 0n;
+    for (let part of parts) {
+        if (!IPV4_OCTET.test(part))
+            return null;
+        let octet = Number(part);
+        if (octet > 255)
+            return null;
+        value = (value << 8n) | BigInt(octet);
+    }
+    return value;
+}
+/**
+ * Converts colon-separated groups into 16-bit numbers, expanding a trailing dotted
+ * quad into the two groups it occupies.
+ *
+ * @param parts - The groups on one side of a `::`, or all of them when there is none.
+ * @param last - Whether these groups end the address, the only place a dotted quad may sit.
+ * @returns The groups, or `null` when any of them is malformed.
+ */
+function parseGroups(parts, last) {
+    let groups = [];
+    for (let [index, part] of parts.entries()) {
+        if (part.includes(".")) {
+            if (!last || index !== parts.length - 1)
+                return null;
+            let embedded = parseIPv4(part);
+            if (embedded === null)
+                return null;
+            groups.push(Number(embedded >> 16n), Number(embedded & 0xffffn));
+            continue;
+        }
+        if (!IPV6_GROUP.test(part))
+            return null;
+        groups.push(Number.parseInt(part, 16));
+    }
+    return groups;
+}
+/**
+ * Reads IPv6 text into its 128-bit value. A `::` must stand for at least one group,
+ * and a zone identifier (`%eth0`) fails, since no URL a Worker fetches carries one.
+ *
+ * @param text - An IPv6 address without brackets.
+ * @returns The value, or `null` when the text is not an address.
+ */
+function parseIPv6(text) {
+    let halves = text.split("::");
+    if (halves.length > 2)
+        return null;
+    let [rawHead = "", rawTail] = halves;
+    let head = parseGroups(rawHead === "" ? [] : rawHead.split(":"), rawTail === undefined);
+    let tail = parseGroups(rawTail === undefined || rawTail === "" ? [] : rawTail.split(":"), true);
+    if (head === null || tail === null)
+        return null;
+    let groups = head;
+    if (rawTail !== undefined) {
+        let missing = 8 - head.length - tail.length;
+        if (missing < 1)
+            return null;
+        groups = [...head, ...Array.from({ length: missing }, () => 0), ...tail];
+    }
+    if (groups.length !== 8)
+        return null;
+    return groups.reduce((value, group) => (value << 16n) | BigInt(group), 0n);
+}
+/**
+ * Reads the text a URL host, a header or a DNS answer carries into an address.
+ * Brackets are accepted around IPv6 only, the way a URL host spells it.
+ *
+ * @param text - The address as written.
+ * @returns The address, or `null` when the text is not one.
+ */
+export function parseAddress(text) {
+    if (text.startsWith("[") && text.endsWith("]")) {
+        let value = parseIPv6(text.slice(1, -1));
+        return value === null ? null : { version: 6, value };
+    }
+    if (text.includes(":")) {
+        let value = parseIPv6(text);
+        return value === null ? null : { version: 6, value };
+    }
+    let value = parseIPv4(text);
+    return value === null ? null : { version: 4, value };
+}
+/**
+ * Prints a 32-bit value as a dotted quad.
+ *
+ * @param value - The IPv4 address.
+ * @returns Four decimal octets.
+ */
+function formatIPv4(value) {
+    return [24n, 16n, 8n, 0n].map((shift) => String((value >> shift) & 0xffn)).join(".");
+}
+/**
+ * Prints a 128-bit value as RFC 5952 text: lowercase, no leading zeros, and the
+ * longest run of two or more zero groups compressed, the first one on a tie. An
+ * IPv4-mapped address ends in a dotted quad, as section 5 of the RFC recommends.
+ *
+ * @param value - The IPv6 address.
+ * @returns The canonical text.
+ */
+function formatIPv6(value) {
+    if (value >> 32n === IPV4_MAPPED_PREFIX >> 32n) {
+        return `::ffff:${formatIPv4(value & 0xffffffffn)}`;
+    }
+    let groups = Array.from({ length: 8 }, (_, index) => Number((value >> BigInt(112 - index * 16)) & 0xffffn));
+    let bestStart = -1;
+    let bestLength = 1;
+    let runStart = -1;
+    for (let [index, group] of [...groups, 1].entries()) {
+        if (group === 0) {
+            if (runStart === -1)
+                runStart = index;
+            continue;
+        }
+        if (runStart !== -1 && index - runStart > bestLength) {
+            bestStart = runStart;
+            bestLength = index - runStart;
+        }
+        runStart = -1;
+    }
+    let hex = groups.map((group) => group.toString(16));
+    if (bestStart === -1)
+        return hex.join(":");
+    let head = hex.slice(0, bestStart).join(":");
+    let tail = hex.slice(bestStart + bestLength).join(":");
+    return `${head}::${tail}`;
+}
+/**
+ * Prints an address as its one canonical spelling, so two spellings of the same
+ * address always print the same string.
+ *
+ * @param address - The address to print.
+ * @returns Dotted decimal for IPv4, RFC 5952 text for IPv6, without brackets.
+ */
+export function formatAddress(address) {
+    return address.version === 4 ? formatIPv4(address.value) : formatIPv6(address.value);
+}
+/**
+ * Clears every bit past the first `prefix`, giving the first address of the network
+ * an address sits in.
+ *
+ * @param address - The address to mask.
+ * @param prefix - How many leading bits to keep, already within the version's width.
+ * @returns The network address.
+ */
+export function maskAddress(address, prefix) {
+    let hostBits = BigInt(ADDRESS_BITS[address.version] - prefix);
+    return { version: address.version, value: (address.value >> hostBits) << hostBits };
+}

package/dist/error.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The failure parsing returns for text that is not an address or a range. It keeps
+ * a machine-readable code and the rejected text, so a caller can answer with its
+ * own wording and a log can show what arrived.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Why text was refused: not an address, not a `network/prefix` range, or a range
+ * whose address has bits set past its prefix (`10.0.0.1/8`), which names a host
+ * where a network was meant.
+ */
+export type IPErrorCode = "invalid-address" | "invalid-range" | "host-bits-set";
+/** Returned inside a `Failure` by `IP.parse` and `IP.Range.parse`, never thrown. */
+export declare class IPError extends Error {
+    /** Machine-readable cause, for a caller that maps it to its own message. */
+    readonly code: IPErrorCode;
+    /** The rejected text, verbatim. */
+    readonly input: string;
+    /**
+     * @param code - Why the text was refused.
+     * @param input - The text as it was given.
+     */
+    constructor(code: IPErrorCode, input: string);
+}

package/dist/error.js

@@ -0,0 +1,25 @@
+/**
+ * The failure parsing returns for text that is not an address or a range. It keeps
+ * a machine-readable code and the rejected text, so a caller can answer with its
+ * own wording and a log can show what arrived.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Returned inside a `Failure` by `IP.parse` and `IP.Range.parse`, never thrown. */
+export class IPError extends Error {
+    /** Machine-readable cause, for a caller that maps it to its own message. */
+    code;
+    /** The rejected text, verbatim. */
+    input;
+    /**
+     * @param code - Why the text was refused.
+     * @param input - The text as it was given.
+     */
+    constructor(code, input) {
+        super(`${code}: ${JSON.stringify(input)}`);
+        this.name = "IPError";
+        this.code = code;
+        this.input = input;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The package entrypoint: one `IP` export carrying the address value object, the
+ * `IP.Range` network class, the `IP.Error` failure, and the types merged under the
+ * same name. It performs no I/O, so it runs wherever an address arrives as text.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export { IP } from "./ip.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * The package entrypoint: one `IP` export carrying the address value object, the
+ * `IP.Range` network class, the `IP.Error` failure, and the types merged under the
+ * same name. It performs no I/O, so it runs wherever an address arrives as text.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export { IP } from "./ip.js";

package/dist/ip.d.ts

@@ -0,0 +1,179 @@
+/**
+ * The `IP` value object and the `IP.Range` it carries: parsed, valid, immutable
+ * addresses and networks that classify themselves, test membership and print as
+ * canonical text. Parsing returns a `Result`, so nothing here throws.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { IPErrorCode } from "./error.js";
+import type { Classification as IPClassification } from "./special-purpose.js";
+import { IPError } from "./error.js";
+/**
+ * A network: the first address and how many leading bits every member shares.
+ * Its address never has bits set past the prefix, so one network has one spelling.
+ *
+ * @example
+ * let range = IP.Range.parse("10.0.0.0/8");
+ * if (isSuccess(range)) range.data.contains(ip);
+ */
+declare class IPRange {
+    /**
+     * Parses `network/prefix` text, IPv4 or IPv6.
+     *
+     * @param text - The range as written, such as `10.0.0.0/8` or `2001:db8::/32`.
+     * @returns The range, or an `IP.Error` coded `invalid-range` for malformed text and
+     * `host-bits-set` when the address names a host inside the network.
+     *
+     * @example
+     * IP.Range.parse("10.0.0.0/8"); // success
+     * @example
+     * IP.Range.parse("10.0.0.1/8"); // failure: host-bits-set
+     */
+    static parse(text: string): Result<IPRange, IPError>;
+    /** The first address of the network. */
+    readonly network: IP;
+    /** How many leading bits every member shares. */
+    readonly prefix: number;
+    /**
+     * @param network - The network's first address, host bits already cleared.
+     * @param prefix - The prefix length, within the address's width.
+     */
+    private constructor();
+    /** `4` or `6`, the version of every address in the range. */
+    get version(): 4 | 6;
+    /**
+     * Whether an address is a member. An address of the other version is never one,
+     * so an IPv4-mapped IPv6 address is outside every IPv4 range.
+     *
+     * @param ip - The address to test.
+     * @returns `true` when the address shares the range's leading bits.
+     */
+    contains(ip: IP): boolean;
+    /**
+     * Compares by value, since two ranges parsed from the same text are two objects.
+     *
+     * @param other - The range to compare with.
+     * @returns `true` for the same network and prefix.
+     */
+    equals(other: IPRange): boolean;
+    /**
+     * The canonical `network/prefix` text, the same for every spelling of one range,
+     * which makes it the key for a map, a rate limit or a database column.
+     *
+     * @returns Such as `10.0.0.0/8` or `2001:db8::/32`.
+     */
+    toString(): string;
+    /**
+     * Serializes as the canonical text, so a range goes into a log or a response as is.
+     *
+     * @returns The same string as {@link IPRange.toString}.
+     */
+    toJSON(): string;
+}
+/**
+ * One parsed, valid IPv4 or IPv6 address. A function that takes an `IP` holds an
+ * address that was checked, never `"unknown"`, `"10.0.0"` or a hostname. Compare two
+ * with {@link IP.equals}, and key a map or a column on {@link IP.toString}.
+ *
+ * @example
+ * let parsed = IP.parse("2001:DB8::0:1");
+ * if (isFailure(parsed)) return parsed;
+ * parsed.data.toString(); // "2001:db8::1"
+ */
+export declare class IP {
+    #private;
+    /**
+     * The network class: `IP.Range.parse("10.0.0.0/8")`, and `IP.Range` as the type.
+     */
+    static readonly Range: typeof IPRange;
+    /**
+     * The failure parsing returns, so `error instanceof IP.Error` narrows it.
+     */
+    static readonly Error: typeof IPError;
+    /**
+     * Parses the text a URL host, a header or a DNS answer carries. Brackets around
+     * IPv6 are accepted (`[::1]`). IPv4 must be canonical dotted decimal, so octal,
+     * hex and bare integers fail rather than naming a different address than they
+     * appear to; zone identifiers (`fe80::1%eth0`) fail too.
+     *
+     * @param text - The address as written.
+     * @returns The address, or an `IP.Error` coded `invalid-address`.
+     *
+     * @example
+     * IP.parse("[::1]"); // success
+     * @example
+     * IP.parse("010.0.0.1"); // failure: invalid-address
+     */
+    static parse(text: string): Result<IP, IPError>;
+    /** `4` or `6`. */
+    readonly version: 4 | 6;
+    /**
+     * @param address - An address the parser produced.
+     */
+    private constructor();
+    /**
+     * What the IANA special-purpose registries say the address is for, judging an
+     * IPv4-mapped, NAT64 or 6to4 address by the IPv4 inside it.
+     */
+    get classification(): IPClassification;
+    /**
+     * Whether the address is on the public internet: `classification === "public"`,
+     * so `::ffff:10.0.0.1` is not and `::ffff:8.8.8.8` is.
+     */
+    get isPublic(): boolean;
+    /**
+     * The IPv4 address an IPv4-mapped (`::ffff:0:0/96`), NAT64 (`64:ff9b::/96`) or
+     * 6to4 (`2002::/16`) address carries, or `null` for any other address.
+     */
+    get embeddedIPv4(): IP | null;
+    /**
+     * The network this address sits in, at the prefix length given for its version.
+     * A length outside the version's width is clamped into it.
+     *
+     * @param prefixes - The prefix length to use for each version.
+     * @returns The range, whose text keys a rate limit on a client's network.
+     *
+     * @example
+     * ip.network({ v4: 32, v6: 64 }).toString(); // "2001:db8:1:2::/64"
+     */
+    network(prefixes: IP.Prefixes): IPRange;
+    /**
+     * Compares by value, since two `IP`s parsed from the same text are two objects.
+     *
+     * @param other - The address to compare with.
+     * @returns `true` for the same version and the same address.
+     */
+    equals(other: IP): boolean;
+    /**
+     * The canonical text: dotted decimal, or RFC 5952 IPv6 without brackets. Every
+     * spelling of one address prints the same string.
+     *
+     * @returns Such as `203.0.113.7` or `2001:db8::1`.
+     */
+    toString(): string;
+    /**
+     * Serializes as the canonical text, so an address goes into a log or a response
+     * as is. A structured clone drops the methods; store the text and parse it back.
+     *
+     * @returns The same string as {@link IP.toString}.
+     */
+    toJSON(): string;
+}
+export declare namespace IP {
+    /** A network, as `IP.Range.parse` and `ip.network` answer it. */
+    type Range = IPRange;
+    /** The failure `IP.parse` and `IP.Range.parse` return. */
+    type Error = IPError;
+    /** Why parsing failed. */
+    type ErrorCode = IPErrorCode;
+    /** What an address is for, as the special-purpose registries name it. */
+    type Classification = IPClassification;
+    /** A prefix length per version, since the same length means different things for each. */
+    interface Prefixes {
+        v4: number;
+        v6: number;
+    }
+}
+export {};

package/dist/ip.js

@@ -0,0 +1,241 @@
+/**
+ * The `IP` value object and the `IP.Range` it carries: parsed, valid, immutable
+ * addresses and networks that classify themselves, test membership and print as
+ * canonical text. Parsing returns a `Result`, so nothing here throws.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, success } from "@sdxc/result";
+import { ADDRESS_BITS, formatAddress, maskAddress, parseAddress } from "./address.js";
+import { IPError } from "./error.js";
+import { classify, embeddedIPv4 } from "./special-purpose.js";
+/** A prefix length: `0`, or a decimal integer without a leading zero. */
+const PREFIX_LENGTH = /^(?:0|[1-9]\d{0,2})$/;
+/**
+ * Builds an `IP` from a parsed address. Assigned by the class itself, so the
+ * constructor stays private and every instance still comes from parsed text.
+ */
+let createIP;
+/** Reads the address an `IP` holds, assigned by the class for the same reason. */
+let addressOf;
+/** Builds an `IP.Range`, assigned by the range class so its constructor stays private. */
+let createRange;
+/**
+ * A network: the first address and how many leading bits every member shares.
+ * Its address never has bits set past the prefix, so one network has one spelling.
+ *
+ * @example
+ * let range = IP.Range.parse("10.0.0.0/8");
+ * if (isSuccess(range)) range.data.contains(ip);
+ */
+class IPRange {
+    /**
+     * Parses `network/prefix` text, IPv4 or IPv6.
+     *
+     * @param text - The range as written, such as `10.0.0.0/8` or `2001:db8::/32`.
+     * @returns The range, or an `IP.Error` coded `invalid-range` for malformed text and
+     * `host-bits-set` when the address names a host inside the network.
+     *
+     * @example
+     * IP.Range.parse("10.0.0.0/8"); // success
+     * @example
+     * IP.Range.parse("10.0.0.1/8"); // failure: host-bits-set
+     */
+    static parse(text) {
+        let slash = text.lastIndexOf("/");
+        let address = slash === -1 ? null : parseAddress(text.slice(0, slash));
+        let length = text.slice(slash + 1);
+        if (address === null || !PREFIX_LENGTH.test(length)) {
+            return failure(new IPError("invalid-range", text));
+        }
+        let prefix = Number(length);
+        if (prefix > ADDRESS_BITS[address.version])
+            return failure(new IPError("invalid-range", text));
+        if (maskAddress(address, prefix).value !== address.value) {
+            return failure(new IPError("host-bits-set", text));
+        }
+        return success(new IPRange(createIP(address), prefix));
+    }
+    /** The first address of the network. */
+    network;
+    /** How many leading bits every member shares. */
+    prefix;
+    /**
+     * @param network - The network's first address, host bits already cleared.
+     * @param prefix - The prefix length, within the address's width.
+     */
+    constructor(network, prefix) {
+        this.network = network;
+        this.prefix = prefix;
+        Object.freeze(this);
+    }
+    static {
+        createRange = (network, prefix) => new IPRange(network, prefix);
+    }
+    /** `4` or `6`, the version of every address in the range. */
+    get version() {
+        return this.network.version;
+    }
+    /**
+     * Whether an address is a member. An address of the other version is never one,
+     * so an IPv4-mapped IPv6 address is outside every IPv4 range.
+     *
+     * @param ip - The address to test.
+     * @returns `true` when the address shares the range's leading bits.
+     */
+    contains(ip) {
+        let address = addressOf(ip);
+        if (address.version !== this.version)
+            return false;
+        return maskAddress(address, this.prefix).value === addressOf(this.network).value;
+    }
+    /**
+     * Compares by value, since two ranges parsed from the same text are two objects.
+     *
+     * @param other - The range to compare with.
+     * @returns `true` for the same network and prefix.
+     */
+    equals(other) {
+        return this.prefix === other.prefix && this.network.equals(other.network);
+    }
+    /**
+     * The canonical `network/prefix` text, the same for every spelling of one range,
+     * which makes it the key for a map, a rate limit or a database column.
+     *
+     * @returns Such as `10.0.0.0/8` or `2001:db8::/32`.
+     */
+    toString() {
+        return `${this.network.toString()}/${this.prefix}`;
+    }
+    /**
+     * Serializes as the canonical text, so a range goes into a log or a response as is.
+     *
+     * @returns The same string as {@link IPRange.toString}.
+     */
+    toJSON() {
+        return this.toString();
+    }
+}
+/**
+ * One parsed, valid IPv4 or IPv6 address. A function that takes an `IP` holds an
+ * address that was checked, never `"unknown"`, `"10.0.0"` or a hostname. Compare two
+ * with {@link IP.equals}, and key a map or a column on {@link IP.toString}.
+ *
+ * @example
+ * let parsed = IP.parse("2001:DB8::0:1");
+ * if (isFailure(parsed)) return parsed;
+ * parsed.data.toString(); // "2001:db8::1"
+ */
+export class IP {
+    /**
+     * The network class: `IP.Range.parse("10.0.0.0/8")`, and `IP.Range` as the type.
+     */
+    static Range = IPRange;
+    /**
+     * The failure parsing returns, so `error instanceof IP.Error` narrows it.
+     */
+    static Error = IPError;
+    /**
+     * Parses the text a URL host, a header or a DNS answer carries. Brackets around
+     * IPv6 are accepted (`[::1]`). IPv4 must be canonical dotted decimal, so octal,
+     * hex and bare integers fail rather than naming a different address than they
+     * appear to; zone identifiers (`fe80::1%eth0`) fail too.
+     *
+     * @param text - The address as written.
+     * @returns The address, or an `IP.Error` coded `invalid-address`.
+     *
+     * @example
+     * IP.parse("[::1]"); // success
+     * @example
+     * IP.parse("010.0.0.1"); // failure: invalid-address
+     */
+    static parse(text) {
+        let address = parseAddress(text);
+        if (address === null)
+            return failure(new IPError("invalid-address", text));
+        return success(new IP(address));
+    }
+    /** The parsed address, the whole state of an `IP`. */
+    #address;
+    /** `4` or `6`. */
+    version;
+    /**
+     * @param address - An address the parser produced.
+     */
+    constructor(address) {
+        this.#address = address;
+        this.version = address.version;
+        Object.freeze(this);
+    }
+    static {
+        createIP = (address) => new IP(address);
+        addressOf = (ip) => ip.#address;
+    }
+    /**
+     * What the IANA special-purpose registries say the address is for, judging an
+     * IPv4-mapped, NAT64 or 6to4 address by the IPv4 inside it.
+     */
+    get classification() {
+        return classify(this.#address);
+    }
+    /**
+     * Whether the address is on the public internet: `classification === "public"`,
+     * so `::ffff:10.0.0.1` is not and `::ffff:8.8.8.8` is.
+     */
+    get isPublic() {
+        return this.classification === "public";
+    }
+    /**
+     * The IPv4 address an IPv4-mapped (`::ffff:0:0/96`), NAT64 (`64:ff9b::/96`) or
+     * 6to4 (`2002::/16`) address carries, or `null` for any other address.
+     */
+    get embeddedIPv4() {
+        let inner = embeddedIPv4(this.#address);
+        return inner === null ? null : new IP(inner);
+    }
+    /**
+     * The network this address sits in, at the prefix length given for its version.
+     * A length outside the version's width is clamped into it.
+     *
+     * @param prefixes - The prefix length to use for each version.
+     * @returns The range, whose text keys a rate limit on a client's network.
+     *
+     * @example
+     * ip.network({ v4: 32, v6: 64 }).toString(); // "2001:db8:1:2::/64"
+     */
+    network(prefixes) {
+        let width = ADDRESS_BITS[this.version];
+        let requested = this.version === 4 ? prefixes.v4 : prefixes.v6;
+        let prefix = Math.min(width, Math.max(0, Math.trunc(requested) || 0));
+        return createRange(new IP(maskAddress(this.#address, prefix)), prefix);
+    }
+    /**
+     * Compares by value, since two `IP`s parsed from the same text are two objects.
+     *
+     * @param other - The address to compare with.
+     * @returns `true` for the same version and the same address.
+     */
+    equals(other) {
+        let address = addressOf(other);
+        return this.#address.version === address.version && this.#address.value === address.value;
+    }
+    /**
+     * The canonical text: dotted decimal, or RFC 5952 IPv6 without brackets. Every
+     * spelling of one address prints the same string.
+     *
+     * @returns Such as `203.0.113.7` or `2001:db8::1`.
+     */
+    toString() {
+        return formatAddress(this.#address);
+    }
+    /**
+     * Serializes as the canonical text, so an address goes into a log or a response
+     * as is. A structured clone drops the methods; store the text and parse it back.
+     *
+     * @returns The same string as {@link IP.toString}.
+     */
+    toJSON() {
+        return this.toString();
+    }
+}

package/dist/special-purpose.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The IANA IPv4 and IPv6 Special-Purpose Address Registries as one table, each row
+ * citing the RFC it comes from, plus the three IPv6 forms that carry an IPv4 address
+ * inside. Classifying an address is a longest-prefix match against this table.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Address } from "./address.js";
+/**
+ * What a special-purpose range is for. `public` is every address no row claims, and
+ * the few rows inside a reserved block that the registry marks globally reachable.
+ */
+export type Classification = "public" | "unspecified" | "loopback" | "private" | "shared" | "link-local" | "documentation" | "benchmarking" | "multicast" | "reserved" | "unique-local" | "teredo" | "discard";
+/** One registry row, as written in the RFC that defines it. */
+interface Row {
+    range: string;
+    classification: Classification;
+    rfc: string;
+}
+/**
+ * Every special-purpose range, both versions in one list. Where rows nest, the
+ * longest prefix decides, so `::1/128` is loopback inside the reserved `::/0`, and
+ * the globally reachable anycast addresses inside `192.0.0.0/24` stay public.
+ * Multicast and the IPv6 space outside `2000::/3` come from the address
+ * architecture rather than the special-purpose registries, and are listed here so one
+ * table answers for every address.
+ */
+export declare const SPECIAL_PURPOSE_RANGES: readonly Row[];
+/**
+ * The IPv6 prefixes that carry an IPv4 address, and the bit offset it starts at:
+ * IPv4-mapped (RFC 4291), NAT64 (RFC 6052) and 6to4 (RFC 3056).
+ */
+export declare const EMBEDDING_RANGES: readonly {
+    range: string;
+    offset: number;
+}[];
+/**
+ * The IPv4 address an IPv6 address carries inside it, so an address like
+ * `::ffff:169.254.169.254` is judged by the IPv4 it reaches.
+ *
+ * @param address - Any address.
+ * @returns The embedded IPv4, or `null` for IPv4 and for IPv6 outside the three prefixes.
+ */
+export declare function embeddedIPv4(address: Address): Address | null;
+/**
+ * Classifies an address by its most specific row, after unwrapping an embedded
+ * IPv4, so `::ffff:10.0.0.1` is `private` and `::ffff:8.8.8.8` is `public`.
+ *
+ * @param address - Any address.
+ * @returns The classification of the most specific row, or `public` when none matches.
+ */
+export declare function classify(address: Address): Classification;
+export {};

package/dist/special-purpose.js

@@ -0,0 +1,142 @@
+/**
+ * The IANA IPv4 and IPv6 Special-Purpose Address Registries as one table, each row
+ * citing the RFC it comes from, plus the three IPv6 forms that carry an IPv4 address
+ * inside. Classifying an address is a longest-prefix match against this table.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { ADDRESS_BITS, maskAddress, parseAddress } from "./address.js";
+/**
+ * Every special-purpose range, both versions in one list. Where rows nest, the
+ * longest prefix decides, so `::1/128` is loopback inside the reserved `::/0`, and
+ * the globally reachable anycast addresses inside `192.0.0.0/24` stay public.
+ * Multicast and the IPv6 space outside `2000::/3` come from the address
+ * architecture rather than the special-purpose registries, and are listed here so one
+ * table answers for every address.
+ */
+export const SPECIAL_PURPOSE_RANGES = [
+    { range: "0.0.0.0/8", classification: "reserved", rfc: "RFC 791" },
+    { range: "0.0.0.0/32", classification: "unspecified", rfc: "RFC 1122" },
+    { range: "10.0.0.0/8", classification: "private", rfc: "RFC 1918" },
+    { range: "100.64.0.0/10", classification: "shared", rfc: "RFC 6598" },
+    { range: "127.0.0.0/8", classification: "loopback", rfc: "RFC 1122" },
+    { range: "169.254.0.0/16", classification: "link-local", rfc: "RFC 3927" },
+    { range: "172.16.0.0/12", classification: "private", rfc: "RFC 1918" },
+    { range: "192.0.0.0/24", classification: "reserved", rfc: "RFC 6890" },
+    { range: "192.0.0.9/32", classification: "public", rfc: "RFC 7723" },
+    { range: "192.0.0.10/32", classification: "public", rfc: "RFC 8155" },
+    { range: "192.0.2.0/24", classification: "documentation", rfc: "RFC 5737" },
+    { range: "192.88.99.0/24", classification: "reserved", rfc: "RFC 7526" },
+    { range: "192.168.0.0/16", classification: "private", rfc: "RFC 1918" },
+    { range: "198.18.0.0/15", classification: "benchmarking", rfc: "RFC 2544" },
+    { range: "198.51.100.0/24", classification: "documentation", rfc: "RFC 5737" },
+    { range: "203.0.113.0/24", classification: "documentation", rfc: "RFC 5737" },
+    { range: "224.0.0.0/4", classification: "multicast", rfc: "RFC 5771" },
+    { range: "240.0.0.0/4", classification: "reserved", rfc: "RFC 1112" },
+    { range: "255.255.255.255/32", classification: "reserved", rfc: "RFC 919" },
+    { range: "::/0", classification: "reserved", rfc: "RFC 4291" },
+    { range: "::/128", classification: "unspecified", rfc: "RFC 4291" },
+    { range: "::1/128", classification: "loopback", rfc: "RFC 4291" },
+    { range: "64:ff9b:1::/48", classification: "reserved", rfc: "RFC 8215" },
+    { range: "100::/64", classification: "discard", rfc: "RFC 6666" },
+    { range: "100:0:0:1::/64", classification: "reserved", rfc: "RFC 9780" },
+    { range: "2000::/3", classification: "public", rfc: "RFC 4291" },
+    { range: "2001::/23", classification: "reserved", rfc: "RFC 2928" },
+    { range: "2001::/32", classification: "teredo", rfc: "RFC 4380" },
+    { range: "2001:1::1/128", classification: "public", rfc: "RFC 7723" },
+    { range: "2001:1::2/128", classification: "public", rfc: "RFC 8155" },
+    { range: "2001:1::3/128", classification: "public", rfc: "RFC 9665" },
+    { range: "2001:2::/48", classification: "benchmarking", rfc: "RFC 5180" },
+    { range: "2001:3::/32", classification: "public", rfc: "RFC 7450" },
+    { range: "2001:4:112::/48", classification: "public", rfc: "RFC 7535" },
+    { range: "2001:20::/28", classification: "public", rfc: "RFC 7343" },
+    { range: "2001:30::/28", classification: "public", rfc: "RFC 9374" },
+    { range: "2001:db8::/32", classification: "documentation", rfc: "RFC 3849" },
+    { range: "3fff::/20", classification: "documentation", rfc: "RFC 9637" },
+    { range: "5f00::/16", classification: "reserved", rfc: "RFC 9602" },
+    { range: "fc00::/7", classification: "unique-local", rfc: "RFC 4193" },
+    { range: "fe80::/10", classification: "link-local", rfc: "RFC 4291" },
+    { range: "ff00::/8", classification: "multicast", rfc: "RFC 4291" },
+];
+/**
+ * The IPv6 prefixes that carry an IPv4 address, and the bit offset it starts at:
+ * IPv4-mapped (RFC 4291), NAT64 (RFC 6052) and 6to4 (RFC 3056).
+ */
+export const EMBEDDING_RANGES = [
+    { range: "::ffff:0:0/96", offset: 96 },
+    { range: "64:ff9b::/96", offset: 96 },
+    { range: "2002::/16", offset: 16 },
+];
+/**
+ * The parsed table, longest prefix first so the first match is the most specific.
+ * Filled on first use, keeping module evaluation free of work.
+ */
+const PARSED_ROWS = [];
+/** The parsed embedding prefixes, filled on first use. */
+const PARSED_EMBEDDINGS = [];
+/**
+ * Splits a table row's `network/prefix` text. The tables are written by hand and
+ * their tests classify the first and last address of every row, which fails for a
+ * row this drops.
+ *
+ * @param range - A range from one of the tables.
+ * @returns The network and prefix length, or an empty list for a malformed row.
+ */
+function parseRow(range) {
+    let [text = "", prefix = ""] = range.split("/");
+    let network = parseAddress(text);
+    return network === null ? [] : [{ network, prefix: Number(prefix) }];
+}
+/**
+ * Whether an address sits inside a network.
+ *
+ * @param address - The address to test.
+ * @param network - The network's first address.
+ * @param prefix - The network's prefix length.
+ * @returns `true` for the same version and the same leading `prefix` bits.
+ */
+function inNetwork(address, network, prefix) {
+    return (address.version === network.version && maskAddress(address, prefix).value === network.value);
+}
+/**
+ * The IPv4 address an IPv6 address carries inside it, so an address like
+ * `::ffff:169.254.169.254` is judged by the IPv4 it reaches.
+ *
+ * @param address - Any address.
+ * @returns The embedded IPv4, or `null` for IPv4 and for IPv6 outside the three prefixes.
+ */
+export function embeddedIPv4(address) {
+    if (address.version === 4)
+        return null;
+    if (PARSED_EMBEDDINGS.length === 0) {
+        for (let row of EMBEDDING_RANGES) {
+            PARSED_EMBEDDINGS.push(...parseRow(row.range).map((parsed) => ({ ...parsed, offset: row.offset })));
+        }
+    }
+    for (let { network, prefix, offset } of PARSED_EMBEDDINGS) {
+        if (!inNetwork(address, network, prefix))
+            continue;
+        let shift = BigInt(ADDRESS_BITS[6] - offset - ADDRESS_BITS[4]);
+        return { version: 4, value: (address.value >> shift) & 0xffffffffn };
+    }
+    return null;
+}
+/**
+ * Classifies an address by its most specific row, after unwrapping an embedded
+ * IPv4, so `::ffff:10.0.0.1` is `private` and `::ffff:8.8.8.8` is `public`.
+ *
+ * @param address - Any address.
+ * @returns The classification of the most specific row, or `public` when none matches.
+ */
+export function classify(address) {
+    let inner = embeddedIPv4(address);
+    if (inner !== null)
+        return classify(inner);
+    if (PARSED_ROWS.length === 0) {
+        let rows = SPECIAL_PURPOSE_RANGES.flatMap((row) => parseRow(row.range).map((parsed) => ({ ...parsed, classification: row.classification })));
+        PARSED_ROWS.push(...rows.sort((a, b) => b.prefix - a.prefix));
+    }
+    let row = PARSED_ROWS.find(({ network, prefix }) => inNetwork(address, network, prefix));
+    return row?.classification ?? "public";
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+	"name": "@sdxc/ip",
+	"version": "0.0.0-pre.1",
+	"description": "IPv4 and IPv6 addresses and ranges as value objects that classify against the IANA special-purpose registries",
+	"license": "MIT",
+	"type": "module",
+	"exports": {
+		".": "./dist/index.js"
+	},
+	"dependencies": {
+		"@sdxc/result": "2026.10.2"
+	},
+	"gitHead": "780589b65576d3aa4014c6bcd448b33b4931705a",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/sergiodxa/monorepo.git",
+		"directory": "packages/ip"
+	}
+}