github.com/beaugunderson/ip-address @v10.2.0

ip-address

ip-address is a library for validating and manipulating IPv4 and IPv6 addresses in JavaScript and TypeScript.

Install

npm install ip-address

Examples

import { Address4, Address6 } from 'ip-address';

// Validation
Address4.isValid('192.168.1.1');           // true
Address6.isValid('2001:db8::1');           // true
Address6.isValid('not an address');        // false

// Parsing (throws AddressError on invalid input)
const v4 = new Address4('192.168.1.1/24');
const v6 = new Address6('2001:db8::1/64');

// Subnet membership
const host = new Address4('192.168.1.42');
const network = new Address4('192.168.1.0/24');
host.isInSubnet(network);                  // true

// Subnet range
network.startAddress().correctForm();      // '192.168.1.0'
network.endAddress().correctForm();        // '192.168.1.255'

// Strict network-address check (host bits must be zero).
// isValid() accepts CIDRs with host bits set — '192.168.1.5/24' is a valid
// host-with-subnet, but it isn't a network address.
const cidr = new Address4('192.168.1.5/24');
Address4.isValid('192.168.1.5/24');                                // true
cidr.correctForm() === cidr.startAddress().correctForm();          // false

// Address properties
const link = new Address6('fe80::1');
link.isLinkLocal();                        // true
link.isMulticast();                        // false
link.isLoopback();                         // false

new Address4('192.168.1.1').isPrivate();   // true (RFC 1918)
new Address6('fc00::1').isULA();           // true (RFC 4193)

// Numeric and byte representations
v4.bigInt();                               // 3232235777n
v4.toArray();                              // [192, 168, 1, 1]
v6.canonicalForm();                        // '2001:0db8:0000:0000:0000:0000:0000:0001'

// Embedded IPv4 + Teredo
const teredo = new Address6('2001:0:ce49:7601:e866:efff:62c3:fffe');
teredo.inspectTeredo().client4;            // '157.60.0.1'

// Parse host + port from a URL
Address6.fromURL('http://[2001:db8::1]:8080/').port;  // 8080

Features

• Written in TypeScript with full type definitions; usable from CommonJS and ESM
• Zero runtime dependencies
• Parses all standard IPv4 and IPv6 notations, including subnets and zones
• Parses IPv6 hosts (and ports) from URLs via Address6.fromURL(url)
• Subnet membership checks (isInSubnet) and range queries (startAddress / endAddress)
• Special-property checks: private (RFC 1918) / ULA (RFC 4193), loopback, link-local, multicast, broadcast, unspecified, CGNAT, documentation, Teredo, 6to4, v4-in-v6
• Decodes Teredo and 6to4 tunneling information
• Conversions: canonical/correct form, hex, binary, decimal, byte arrays, BigInt, in-addr.arpa / ip6.arpa
• Runs in Node.js and the browser
• Thousands of test cases

Terminology

A few terms used throughout the API can be confusing if you haven't worked deeply with IPv6 before:

• Correct form — the shortest valid representation, per RFC 5952: leading zeros stripped, the longest run of zero groups collapsed to ::, and hex digits lowercased (e.g. 2001:db8::1). This is what most software displays.
• Canonical form — the fully expanded representation: all 8 groups, each padded to 4 hex digits, no :: collapsing (e.g. 2001:0db8:0000:0000:0000:0000:0000:0001). Useful for sorting and byte-exact comparison.
• Subnet — the network portion of an address expressed as a CIDR prefix length (e.g. /24 for IPv4, /64 for IPv6). startAddress() / endAddress() return the bounds of the subnet's range.
• Zone — the IPv6 scope identifier appended after %, used to disambiguate link-local addresses across interfaces (e.g. fe80::1%eth0).
• v4-in-v6 — mixed notation that embeds an IPv4 address as the last 32 bits of an IPv6 address, e.g. ::ffff:192.168.0.1. Used for IPv4-mapped IPv6 addresses.
• Teredo — a tunneling protocol that encodes an IPv4 endpoint, port, and flags inside a 2001::/32 IPv6 address. inspectTeredo() decodes those fields.
• 6to4 — a tunneling protocol that embeds an IPv4 address as the second 16 bits of a 2002::/16 IPv6 address. inspect6to4() decodes the embedded v4 address.

API

AddressError

Constructor

• new AddressError(message: string, parseMessage?: string): AddressError

Properties

• parseMessage: string — src

Address4

Represents an IPv4 address

Constructor

• new Address4(address: string): Address4

Static methods

• static isValid(address: string): boolean — Returns true if the given string is a valid IPv4 address (with optional CIDR subnet), false otherwise. Host bits in the subnet portion are allowed (e.g. 192.168.1.5/24 is valid); for strict network-address validation compare correctForm() to startAddress().correctForm(), or use networkForm(). src
• static fromAddressAndMask(address: string, mask: string): Address4 — Construct an Address4 from an address and a dotted-decimal subnet mask given as separate strings (e.g. as returned by Node's os.networkInterfaces()). Throws AddressError if the mask is non-contiguous (e.g. 255.0.255.0). src
• static fromAddressAndWildcardMask(address: string, wildcardMask: string): Address4 — Construct an Address4 from an address and a Cisco-style wildcard mask given as separate strings (e.g. 0.0.0.255 for a /24). The wildcard mask is the bitwise inverse of the subnet mask. Throws AddressError if the mask is non-contiguous (e.g. 0.255.0.255). src
• static fromWildcard(input: string): Address4 — Construct an Address4 from a wildcard pattern with trailing * octets. The number of trailing wildcards determines the prefix length: each * represents 8 bits. Only trailing whole-octet wildcards are supported. Partial-octet wildcards (e.g. 192.168.0.1*) and interior wildcards (e.g. 192.*.0.1) throw AddressError. src
• static fromHex(hex: string): Address4 — Converts a hex string to an IPv4 address object. Accepts 8 hex digits with optional : separators (e.g. '7f000001' or '7f:00:00:01'). Throws AddressError for any other length or for non-hex characters. src
• static fromInteger(integer: number): Address4 — Converts an integer into a IPv4 address object. The integer must be a non-negative safe integer in the range [0, 2**32 - 1]; otherwise AddressError is thrown. src
• static fromArpa(arpaFormAddress: string): Address4 — Return an address from in-addr.arpa form src
• static fromBigInt(bigInt: bigint): Address4 — Converts a BigInt to a v4 address object. The value must be in the range [0, 2**32 - 1]; otherwise AddressError is thrown. src
• static fromByteArray(bytes: number[]): Address4 — Convert a byte array to an Address4 object. To convert from a Node.js Buffer, spread it: Address4.fromByteArray([...buf]). src
• static fromUnsignedByteArray(bytes: number[]): Address4 — Convert an unsigned byte array to an Address4 object src

Instance methods

• parse(address: string): string[] — Parses an IPv4 address string into its four octet groups and stores the result on this.parsedAddress. Called automatically by the constructor; you typically don't need to call it directly. Throws AddressError if the input is not a valid IPv4 address. src
• correctForm(): string — Returns the address in correct form: octets joined with . and any leading zeros stripped (e.g. 192.168.1.1). For IPv4 this matches the canonical dotted-decimal representation. src
• toHex(): string — Converts an IPv4 address object to a hex string src
• toArray(): number[] — Converts an IPv4 address object to an array of bytes. To get a Node.js Buffer, wrap the result: Buffer.from(address.toArray()). src
• toGroup6(): string — Converts an IPv4 address object to an IPv6 address group src
• bigInt(): bigint — Returns the address as a bigint src
• startAddress(): Address4 — The first address in the range given by this address' subnet. Often referred to as the Network Address. src
• startAddressExclusive(): Address4 — The first host address in the range given by this address's subnet ie the first address after the Network Address src
• endAddress(): Address4 — The last address in the range given by this address' subnet Often referred to as the Broadcast src
• endAddressExclusive(): Address4 — The last host address in the range given by this address's subnet ie the last address prior to the Broadcast Address src
• subnetMaskAddress(): Address4 — The dotted-decimal form of the subnet mask, e.g. 255.255.240.0 for a /20. Returns an Address4; call .correctForm() for the string. src
• wildcardMask(): Address4 — The Cisco-style wildcard mask, e.g. 0.0.0.255 for a /24. This is the bitwise inverse of subnetMaskAddress(). Returns an Address4; call .correctForm() for the string. src
• networkForm(): string — The network address in CIDR string form, e.g. 192.168.1.0/24 for 192.168.1.5/24. For an address with no explicit subnet the prefix is /32, e.g. networkForm() on 192.168.1.5 returns 192.168.1.5/32. src
• mask(mask?: number): string — Returns the first n bits of the address, defaulting to the subnet mask src
• getBitsBase2(start: number, end: number): string — Returns the bits in the given range as a base-2 string src
• reverseForm(options?: ReverseFormOptions): string — Return the reversed ip6.arpa form of the address src
• isMulticast(): boolean — Returns true if the given address is a multicast address src
• isPrivate(): boolean — Returns true if the address is in one of the RFC 1918 private address ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16). src
• isLoopback(): boolean — Returns true if the address is in the loopback range 127.0.0.0/8 (RFC 1122). src
• isLinkLocal(): boolean — Returns true if the address is in the link-local range 169.254.0.0/16 (RFC 3927). src
• isUnspecified(): boolean — Returns true if the address is the unspecified address 0.0.0.0. src
• isBroadcast(): boolean — Returns true if the address is the limited broadcast address 255.255.255.255 (RFC 919). src
• isCGNAT(): boolean — Returns true if the address is in the carrier-grade NAT range 100.64.0.0/10 (RFC 6598). src
• binaryZeroPad(): string — Returns a zero-padded base-2 string representation of the addr