ip-address
Advanced tools
ip-address is a library for validating and manipulating IPv4 and IPv6 addresses in JavaScript and TypeScript.
npm install ip-address
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
Address6.fromURL(url)isInSubnet) and range queries (startAddress / endAddress)in-addr.arpa / ip6.arpaA few terms used throughout the API can be confusing if you haven't worked deeply with IPv6 before:
::, and hex digits lowercased (e.g. 2001:db8::1). This is what most software displays.:: collapsing (e.g. 2001:0db8:0000:0000:0000:0000:0000:0001). Useful for sorting and byte-exact comparison./24 for IPv4, /64 for IPv6). startAddress() / endAddress() return the bounds of the subnet's range.%, used to disambiguate link-local addresses across interfaces (e.g. fe80::1%eth0).::ffff:192.168.0.1. Used for IPv4-mapped IPv6 addresses.2001::/32 IPv6 address. inspectTeredo() decodes those fields.2002::/16 IPv6 address. inspect6to4() decodes the embedded v4 address.Constructor
new AddressError(message: string, parseMessage?: string): AddressErrorProperties
parseMessage: string — srcRepresents an IPv4 address
Constructor
new Address4(address: string): Address4Static 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(). srcstatic 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). srcstatic 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). srcstatic 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. srcstatic 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. srcstatic 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. srcstatic fromArpa(arpaFormAddress: string): Address4 — Return an address from in-addr.arpa form srcstatic 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. srcstatic fromByteArray(bytes: number[]): Address4 — Convert a byte array to an Address4 object. To convert from a Node.js Buffer, spread it: Address4.fromByteArray([...buf]). srcstatic fromUnsignedByteArray(bytes: number[]): Address4 — Convert an unsigned byte array to an Address4 object srcInstance 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. srccorrectForm(): 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. srctoHex(): string — Converts an IPv4 address object to a hex string srctoArray(): number[] — Converts an IPv4 address object to an array of bytes. To get a Node.js Buffer, wrap the result: Buffer.from(address.toArray()). srctoGroup6(): string — Converts an IPv4 address object to an IPv6 address group srcbigInt(): bigint — Returns the address as a bigint srcstartAddress(): Address4 — The first address in the range given by this address' subnet. Often referred to as the Network Address. srcstartAddressExclusive(): Address4 — The first host address in the range given by this address's subnet ie the first address after the Network Address srcendAddress(): Address4 — The last address in the range given by this address' subnet Often referred to as the Broadcast srcendAddressExclusive(): Address4 — The last host address in the range given by this address's subnet ie the last address prior to the Broadcast Address srcsubnetMaskAddress(): 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. srcwildcardMask(): 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. srcnetworkForm(): 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. srcmask(mask?: number): string — Returns the first n bits of the address, defaulting to the subnet mask srcgetBitsBase2(start: number, end: number): string — Returns the bits in the given range as a base-2 string srcreverseForm(options?: ReverseFormOptions): string — Return the reversed ip6.arpa form of the address srcisMulticast(): boolean — Returns true if the given address is a multicast address srcisPrivate(): 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). srcisLoopback(): boolean — Returns true if the address is in the loopback range 127.0.0.0/8 (RFC 1122). srcisLinkLocal(): boolean — Returns true if the address is in the link-local range 169.254.0.0/16 (RFC 3927). srcisUnspecified(): boolean — Returns true if the address is the unspecified address 0.0.0.0. srcisBroadcast(): boolean — Returns true if the address is the limited broadcast address 255.255.255.255 (RFC 919). srcisCGNAT(): boolean — Returns true if the address is in the carrier-grade NAT range 100.64.0.0/10 (RFC 6598). srcbinaryZeroPad(): string — Returns a zero-padded base-2 string representation of the address srcgroupForV6(): string — Groups an IPv4 address for inclusion at the end of an IPv6 address srcProperties
address: string — srcaddressMinusSuffix: string — srcgroups: number — srcparsedAddress: string[] — srcparsedSubnet: string — srcsubnet: string — srcsubnetMask: number — srcv4: boolean — srcisCorrect: (this: Address4 | Address6) => boolean — Returns true if the address is correct, false otherwise srcisInSubnet: (this: Address4 | Address6, address: Address4 | Address6) => boolean — Returns true if the given address is in the subnet of the current address srcisHostInSubnet: (this: Address4 | Address6, address: Address4 | Address6) => boolean — Returns true if this address's host bits fall inside the given subnet, ignoring this address's own subnet mask. See common.isHostInSubnet. srcRepresents an IPv6 address
Constructor
new Address6(address: string, optionalGroups?: number): Address6Static 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(). srcstatic 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. srcstatic 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). srcstatic 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). srcstatic 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. srcstatic 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. srcstatic fromAddress4(address: string): Address6 — Create an IPv6-mapped address given an IPv4 address srcstatic fromArpa(arpaFormAddress: string): Address6 — Return an address from ip6.arpa form srcstatic 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. srcstatic fromByteArray(bytes: any[]): Address6 — Convert a byte array to an Address6 object. To convert from a Node.js Buffer, spread it: Address6.fromByteArray([...buf]). srcstatic 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]). srcInstance methods
microsoftTranscription(): string — Return the Microsoft UNC transcription of the address srcmask(mask?: number): string — Return the first n bits of the address, defaulting to the subnet mask srcpossibleSubnets(subnetSize?: number): string — Return the number of possible subnets of a given size in the address srcstartAddress(): Address6 — The first address in the range given by this address' subnet Often referred to as the Network Address. srcstartAddressExclusive(): Address6 — The first host address in the range given by this address's subnet ie the first address after the Network Address srcendAddress(): Address6 — The last address in the range given by this address' subnet Often referred to as the Broadcast srcendAddressExclusive(): Address6 — The last host address in the range given by this address's subnet ie the last address prior to the Broadcast Address srcsubnetMaskAddress(): 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. srcwildcardMask(): 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. srcnetworkForm(): 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. srcgetScope(): 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. srcgetType(): string — Return the type of the address srcgetBits(start: number, end: number): bigint — Return the bits in the given range as a BigInt srcgetBitsBase2(start: number, end: number): string — Return the bits in the given range as a base-2 string srcgetBitsBase16(start: number, end: number): string — Return the bits in the given range as a base-16 string srcgetBitsPastSubnet(): string — Return the bits that are set past the subnet mask length srcreverseForm(options?: ReverseFormOptions): string — Return the reversed ip6.arpa form of the address srccorrectForm(): 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. srcbinaryZeroPad(): string — Return a zero-padded base-2 string representation of the address srcparse4in6(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(). srcparse(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. srccanonicalForm(): 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. srcdecimal(): string — Return the decimal form of the address srcbigInt(): bigint — Return the address as a BigInt srcto4(): 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. srcto4in6(): string — Return the v4-in-v6 form of the address srcinspectTeredo(): 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. srcinspect6to4(): 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. srcto6to4(): Address6 | null — Return a v6 6to4 address from a v6 v4inv6 address srctoAddress4Nat64(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. srctoByteArray(): number[] — Return a byte array. To get a Node.js Buffer, wrap the result: Buffer.from(address.toByteArray()). srctoUnsignedByteArray(): number[] — Return an unsigned byte array. To get a Node.js Buffer, wrap the result: Buffer.from(address.toUnsignedByteArray()). srcisCanonical(): boolean — Returns true if the address is in the canonical form, false otherwise srcisLinkLocal(): boolean — Returns true if the address is a link local address, false otherwise srcisMulticast(): boolean — Returns true if the address is a multicast address, false otherwise srcis4(): 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. srcisMapped4(): 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. srcembeddedIPv4(): Address4 | null — If this address embeds a routable IPv4 address — i.e. it is IPv4-mapped (::ffff:0:0/96) or sits in the NAT64 well-known prefix (64:ff9b::/96, RFC 6052) — return that embedded address as an Address4; otherwise return null. The special-property checks (isLoopback, isLinkLocal, isMulticast, isUnspecified, isPrivate, isCGNAT, isBroadcast) call this first and delegate to the embedded Address4 when present, so a literal such as ::ffff:127.0.0.1 is classified by what it actually reaches (loopback) rather than by its IPv6 wrapper (which getType() reports as IPv4-mapped). This matters wherever the checks back a trust-boundary decision (e.g. an SSRF allow/deny filter): without normalization, ::ffff:10.0.0.1, ::ffff:169.254.169.254, 64:ff9b::7f00:1, etc. would all read as non-internal. srcisTeredo(): boolean — Returns true if the address is a Teredo address, false otherwise srcis6to4(): boolean — Returns true if the address is a 6to4 address, false otherwise srcisLoopback(): boolean — Returns true if the address is a loopback address, false otherwise srcisULA(): 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. srcisPrivate(): boolean — Returns true if the address is private, i.e. a Unique Local Address in fc00::/7 (RFC 4193) or an IPv4-mapped / NAT64 address whose embedded IPv4 address is in one of the RFC 1918 private ranges (e.g. ::ffff:10.0.0.1). This is the IPv6 counterpart to Address4.isPrivate; use it instead of isULA when you need to catch mapped RFC 1918 addresses as well as native ULAs. srcisCGNAT(): boolean — Returns true if the address is an IPv4-mapped / NAT64 address whose embedded IPv4 address is in the carrier-grade NAT range 100.64.0.0/10 (RFC 6598), false otherwise. There is no native IPv6 CGNAT range, so this only ever returns true for an embedded IPv4 address (e.g. ::ffff:100.64.0.1). srcisBroadcast(): boolean — Returns true if the address is an IPv4-mapped / NAT64 address whose embedded IPv4 address is the limited broadcast address 255.255.255.255 (RFC 919), false otherwise. There is no IPv6 broadcast, so this only ever returns true for an embedded IPv4 address (e.g. ::ffff:255.255.255.255). srcisUnspecified(): boolean — Returns true if the address is the unspecified address ::. srcisDocumentation(): boolean — Returns true if the address is in the documentation prefix 2001:db8::/32 (RFC 3849). srchref(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/. srclink(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. srcgroup(): string — Groups an address srcregularExpressionString(this: Address6, substringSearch: boolean): string — Generate a regular expression string that can be used to find or validate all variations of this address srcregularExpression(this: Address6, substringSearch: boolean): RegExp — Generate a regular expression that can be used to find or validate all variations of this address. srcProperties
address4: Address4 — srcaddress: string — srcaddressMinusSuffix: string — srcelidedGroups: number — srcelisionBegin: number — srcelisionEnd: number — srcgroups: number — srcparsedAddress4: string — srcparsedAddress: string[] — srcparsedSubnet: string — srcsubnet: string — srcsubnetMask: number — srcv4: boolean — srczone: string — srcisInSubnet: (this: Address4 | Address6, address: Address4 | Address6) => boolean — Returns true if the given address is in the subnet of the current address srcisHostInSubnet: (this: Address4 | Address6, address: Address4 | Address6) => boolean — Returns true if this address's host bits fall inside the given subnet, ignoring this address's own subnet mask. See common.isHostInSubnet. srcisCorrect: (this: Address4 | Address6) => boolean — Returns true if the address is correct, false otherwise srcip-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:
ip-address directly. The single biggest source of downloads.http.Agent for SOCKS proxies; depends on socks. Bundled by virtually every CLI that respects HTTPS_PROXY.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/browsers uses proxy-agent for browser-binary downloads, which routes through socks-proxy-agent → socks → ip-address.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.
The 'ip' package provides basic utilities for IP address manipulation, including subnet calculations and IP version checking. It's simpler and has fewer features compared to 'ip-address', which offers more comprehensive IPv6 support and address parsing capabilities.
The 'cidr-js' package is focused on CIDR (Classless Inter-Domain Routing) block calculations, such as checking if an IP address is within a CIDR block. While it overlaps with some functionalities of 'ip-address', it doesn't provide as extensive support for individual IP address manipulations or validations.
FAQs
A library for parsing IPv4 and IPv6 IP addresses in node and the browser.
The npm package ip-address receives a total of 47,713,496 weekly downloads. As such, ip-address popularity was classified as popular.
We found that ip-address demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Benign-looking npm packages split malicious functionality across a dependency chain that deploys a cross-platform RAT targeting Alibaba developers.
Research
/Security News
Two Joyfill npm beta releases contain an import-time implant that uses blockchain transactions to retrieve a remote-access trojan.
Security News
Socket releases free Certified Patches for high-severity Nuxt vulnerabilities, including server-side remote code execution through server island props.