README.md

May 1, 2026 · View on GitHub

CircleCI codecov downloads npm

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 address src
  • groupForV6(): string — Groups an IPv4 address for inclusion at the end of an IPv6 address src

Properties

  • address: string — src
  • addressMinusSuffix: string — src
  • groups: number — src
  • parsedAddress: string[] — src
  • parsedSubnet: string — src
  • subnet: string — src
  • subnetMask: number — src
  • v4: boolean — src
  • isCorrect: (this: Address4 | Address6) => boolean — Returns true if the address is correct, false otherwise src
  • isInSubnet: (this: Address4 | Address6, address: Address4 | Address6) => boolean — Returns true if the given address is in the subnet of the current address src

Address6

Represents an IPv6 address

Constructor

  • new Address6(address: string, optionalGroups?: number): Address6

Static methods

  • static isValid(address: string): boolean — Returns true if the given string is a valid IPv6 address (with optional CIDR subnet and zone identifier), false otherwise. Host bits in the subnet portion are allowed (e.g. 2001:db8::1/32 is valid); for strict network-address validation compare correctForm() to startAddress().correctForm(), or use networkForm(). src
  • static fromBigInt(bigInt: bigint): Address6 — Convert a BigInt to a v6 address object. The value must be in the range [0, 2**128 - 1]; otherwise AddressError is thrown. src
  • static fromURL(url: string): { error: string; address: null; port: null } | { error?: undefined; address: Address6; port: number | null } — Parse a URL (with optional bracketed host and port) into an address and port. Returns either { address, port } on success or { error, address: null, port: null } if the URL could not be parsed. Ports are returned as numbers (or null if absent or out of range). src
  • static fromAddressAndMask(address: string, mask: string): Address6 — Construct an Address6 from an address and a hex 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. ffff::ffff). src
  • static fromAddressAndWildcardMask(address: string, wildcardMask: string): Address6 — Construct an Address6 from an address and a Cisco-style wildcard mask given as separate strings (e.g. ::ffff:ffff:ffff:ffff for a /64). The wildcard mask is the bitwise inverse of the subnet mask. Throws AddressError if the mask is non-contiguous. src
  • static fromWildcard(input: string): Address6 — Construct an Address6 from a wildcard pattern with trailing * groups. The number of trailing wildcards determines the prefix length: each * represents 16 bits. :: is expanded to zero groups (not wildcards) before evaluating trailing wildcards. Only trailing whole-group wildcards are supported. Partial-group wildcards (e.g. 2001:db8::0*) and interior wildcards (e.g. *::1) throw AddressError. src
  • static fromAddress4(address: string): Address6 — Create an IPv6-mapped address given an IPv4 address src
  • static fromArpa(arpaFormAddress: string): Address6 — Return an address from ip6.arpa form src
  • static fromAddress4Nat64(address: string, prefix: string): Address6 — Embed an IPv4 address into a NAT64 IPv6 address using the encoding defined by RFC 6052. The default prefix is the well-known prefix 64:ff9b::/96. The prefix length must be one of 32, 40, 48, 56, 64, or 96; for prefixes shorter than /64 the IPv4 octets are split around the reserved bits 64–71. src
  • static fromByteArray(bytes: any[]): Address6 — Convert a byte array to an Address6 object. To convert from a Node.js Buffer, spread it: Address6.fromByteArray([...buf]). src
  • static fromUnsignedByteArray(bytes: any[]): Address6 — Convert an unsigned byte array to an Address6 object. To convert from a Node.js Buffer, spread it: Address6.fromUnsignedByteArray([...buf]). src

Instance methods

  • microsoftTranscription(): string — Return the Microsoft UNC transcription of the address src
  • mask(mask?: number): string — Return the first n bits of the address, defaulting to the subnet mask src
  • possibleSubnets(subnetSize?: number): string — Return the number of possible subnets of a given size in the address src
  • startAddress(): Address6 — The first address in the range given by this address' subnet Often referred to as the Network Address. src
  • startAddressExclusive(): Address6 — The first host address in the range given by this address's subnet ie the first address after the Network Address src
  • endAddress(): Address6 — The last address in the range given by this address' subnet Often referred to as the Broadcast src
  • endAddressExclusive(): Address6 — The last host address in the range given by this address's subnet ie the last address prior to the Broadcast Address src
  • subnetMaskAddress(): Address6 — The hex form of the subnet mask, e.g. ffff:ffff:ffff:ffff:: for a /64. Returns an Address6; call .correctForm() for the string. src
  • wildcardMask(): Address6 — The Cisco-style wildcard mask, e.g. ::ffff:ffff:ffff:ffff for a /64. This is the bitwise inverse of subnetMaskAddress(). Returns an Address6; call .correctForm() for the string. src
  • networkForm(): string — The network address in CIDR string form, e.g. 2001:db8::/32 for 2001:db8::1/32. For an address with no explicit subnet the prefix is /128, e.g. networkForm() on 2001:db8::1 returns 2001:db8::1/128. src
  • getScope(): string — Return the scope of the address. The 4-bit scope field (RFC 4291 §2.7) is only defined for multicast addresses; for unicast addresses the scope is derived from the address type per RFC 4007 §6. src
  • getType(): string — Return the type of the address src
  • getBits(start: number, end: number): bigint — Return the bits in the given range as a BigInt src
  • getBitsBase2(start: number, end: number): string — Return the bits in the given range as a base-2 string src
  • getBitsBase16(start: number, end: number): string — Return the bits in the given range as a base-16 string src
  • getBitsPastSubnet(): string — Return the bits that are set past the subnet mask length src
  • reverseForm(options?: ReverseFormOptions): string — Return the reversed ip6.arpa form of the address src
  • correctForm(): string — Returns the address in correct form, 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 the recommended form for display. src
  • binaryZeroPad(): string — Return a zero-padded base-2 string representation of the address src
  • parse4in6(address: string): string — Parses a v4-in-v6 string (e.g. ::ffff:192.168.0.1) by extracting the trailing IPv4 address into this.address4 / this.parsedAddress4 and returning the address with the v4 portion converted to two v6 groups. Used internally by parse(). src
  • parse(address: string): string[] — Parses an IPv6 address string into its 8 hexadecimal groups (expanding any :: elision and any trailing v4-in-v6 portion) 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 malformed. src
  • canonicalForm(): string — Returns the canonical (fully expanded) form of the address: all 8 groups, each padded to 4 hex digits, with no :: collapsing (e.g. 2001:0db8:0000:0000:0000:0000:0000:0001). Useful for sorting and byte-exact comparison. src
  • decimal(): string — Return the decimal form of the address src
  • bigInt(): bigint — Return the address as a BigInt src
  • to4(): Address4 — Return the last two groups of this address as an IPv4 address string. If this address carries a CIDR prefix that covers the trailing 32 bits (i.e. subnetMask >= 96), the resulting Address4 inherits the corresponding v4 prefix (subnetMask - 96); otherwise it defaults to /32. src
  • to4in6(): string — Return the v4-in-v6 form of the address src
  • inspectTeredo(): TeredoProperties — Decodes the Teredo tunneling fields embedded in this address. Returns the Teredo prefix, server IPv4, client IPv4, raw flag bits, cone-NAT flag, UDP port, and Microsoft-format flag breakdown (reserved, universal/local, group/individual, nonce). Only meaningful for addresses in 2001::/32. src
  • inspect6to4(): SixToFourProperties — Decodes the 6to4 tunneling fields embedded in this address. Returns the 6to4 prefix and the embedded IPv4 gateway address. Only meaningful for addresses in 2002::/16. src
  • to6to4(): Address6 | null — Return a v6 6to4 address from a v6 v4inv6 address src
  • toAddress4Nat64(prefix: string): Address4 | null — Extract the embedded IPv4 address from a NAT64 IPv6 address using the encoding defined by RFC 6052. The default prefix is the well-known prefix 64:ff9b::/96. Returns null if this address is not contained within the given prefix. src
  • toByteArray(): number[] — Return a byte array. To get a Node.js Buffer, wrap the result: Buffer.from(address.toByteArray()). src
  • toUnsignedByteArray(): number[] — Return an unsigned byte array. To get a Node.js Buffer, wrap the result: Buffer.from(address.toUnsignedByteArray()). src
  • isCanonical(): boolean — Returns true if the address is in the canonical form, false otherwise src
  • isLinkLocal(): boolean — Returns true if the address is a link local address, false otherwise src
  • isMulticast(): boolean — Returns true if the address is a multicast address, false otherwise src
  • is4(): boolean — Returns true if the address was written in v4-in-v6 dotted-quad notation (e.g. ::ffff:127.0.0.1), false otherwise. This is a notation-level flag and does not reflect whether the address bits lie in the IPv4-mapped (::ffff:0:0/96) subnet — for that, see isMapped4. src
  • isMapped4(): boolean — Returns true if the address is an IPv4-mapped IPv6 address in ::ffff:0:0/96 (RFC 4291 §2.5.5.2), false otherwise. Unlike is4, this checks the underlying address bits rather than the textual notation, so ::ffff:127.0.0.1 and ::ffff:7f00:1 both return true. src
  • isTeredo(): boolean — Returns true if the address is a Teredo address, false otherwise src
  • is6to4(): boolean — Returns true if the address is a 6to4 address, false otherwise src
  • isLoopback(): boolean — Returns true if the address is a loopback address, false otherwise src
  • isULA(): boolean — Returns true if the address is a Unique Local Address in fc00::/7 (RFC 4193). ULAs are the IPv6 equivalent of IPv4 RFC 1918 private addresses. src
  • isUnspecified(): boolean — Returns true if the address is the unspecified address ::. src
  • isDocumentation(): boolean — Returns true if the address is in the documentation prefix 2001:db8::/32 (RFC 3849). src
  • href(optionalPort?: string | number): string — Returns the address as an HTTP URL with the host bracketed, e.g. http://[2001:db8::1]/. If optionalPort is provided it is appended, e.g. http://[2001:db8::1]:8080/. src
  • link(options?: { className?: string; prefix?: string; v4?: boolean }): string — Returns an HTML <a> element whose href encodes the address in a URL hash fragment (default prefix /#address=). Useful for linking between pages of an address-inspector UI. src
  • group(): string — Groups an address src
  • regularExpressionString(this: Address6, substringSearch: boolean): string — Generate a regular expression string that can be used to find or validate all variations of this address src
  • regularExpression(this: Address6, substringSearch: boolean): RegExp — Generate a regular expression that can be used to find or validate all variations of this address. src

Properties

  • address4: Address4 — src
  • address: string — src
  • addressMinusSuffix: string — src
  • elidedGroups: number — src
  • elisionBegin: number — src
  • elisionEnd: number — src
  • groups: number — src
  • parsedAddress4: string — src
  • parsedAddress: string[] — src
  • parsedSubnet: string — src
  • subnet: string — src
  • subnetMask: number — src
  • v4: boolean — src
  • zone: string — src
  • isInSubnet: (this: Address4 | Address6, address: Address4 | Address6) => boolean — Returns true if the given address is in the subnet of the current address src
  • isCorrect: (this: Address4 | Address6) => boolean — Returns true if the address is correct, false otherwise src

Used by

ip-address is downloaded ~66 million times per week, mostly via the Node proxy/agent ecosystem. The dependency chain runs through a handful of widely-used packages:

  • socks (~53M weekly) — SOCKS4/5 client for Node; depends on ip-address directly. The single biggest source of downloads.
  • socks-proxy-agent (~57M weekly) — http.Agent for SOCKS proxies; depends on socks. Bundled by virtually every CLI that respects HTTPS_PROXY.
  • npm and pnpm — both bundle socks-proxy-agent through their HTTP fetch stack (make-fetch-happen → @npmcli/agent), so every Node install on the planet pulls in ip-address as a transitive dependency.
  • Puppeteer — @puppeteer/browsers uses proxy-agent for browser-binary downloads, which routes through socks-proxy-agent → socks → ip-address.
  • proxy-agent (~28M weekly) and pac-proxy-agent (~27M weekly) — auto-detecting proxy agents (HTTP/HTTPS/SOCKS/PAC) used widely in scraping, headless-browser, and CI tooling.
  • cacache (~44M weekly) — npm's content-addressable cache; pulls in the same fetch stack.

Beyond the proxy chain, ip-address has been used by Juniper Networks' Contrail, Ably's proxy-protocol implementation, Rackspace's serialization framework, IPFS, and the SwitchyOmega Chrome extension, among many others.