ip-bigint

April 2, 2026 · View on GitHub

Convert IPv4 and IPv6 addresses to and from BigInt. Compliant with RFC 5952 and RFC 4291.

Usage

import {parseIp, stringifyIp, normalizeIp} from "ip-bigint";

const parsedIp = parseIp("2001:db8::");
// => {number: 42540766411282592856903984951653826560n, version: 6}

stringifyIp(parsedIp);
// => "2001:db8::"

normalizeIp("2001:db8::0:0:1");
// => "2001:db8::1"

API

parseIp(ip: string)

Parse an IP address string to a ParsedIP object.

For IPv4 returns {number, version}. For IPv6 returns {number, version, [ipv4mapped], [scopeid]}.

There is only rudimentary validation that the passed string is actually an IP address. You are encouraged to validate yourself using modules like ip-regex.

stringifyIp({number, version, [ipv4mapped], [scopeid]}: ParsedIP, opts?: StringifyOpts)

Convert a ParsedIP object back to an IP address string.

opts: Options StringifyOpts

compress: boolean - Whether to compress the IP. For IPv6, this means the "best representation" all-lowercase shortest possible form. Default: true.
hexify: boolean - Whether to convert IPv4-Mapped IPv6 addresses to hex. Default: false.
mapv4: boolean - Whether to convert IPv4-Mapped IPv6 addresses (e.g. ::ffff:127.0.0.1) to plain IPv4 (e.g. 127.0.0.1). Default: false.

normalizeIp(ip: string, opts?: StringifyOpts)

Round-trip an IP address through parseIp and stringifyIp, effectively normalizing its representation.

opts: Options StringifyOpts

compress: boolean - Whether to compress the IP. For IPv6, this means the "best representation" all-lowercase shortest possible form. Default: true.
hexify: boolean - Whether to convert IPv4-Mapped IPv6 addresses to hex. Default: false.
mapv4: boolean - Whether to convert IPv4-Mapped IPv6 addresses (e.g. ::ffff:127.0.0.1) to plain IPv4 (e.g. 127.0.0.1). Default: false.

max4

A bigint value that holds the biggest possible IPv4 address.

max6

A bigint value that holds the biggest possible IPv6 address.

ipVersion(ip: string)

Returns a integer of the IP version, 4, 6 or 0 if it's not an IP. Very rudimentary and should not be used for validation.

ip-regex - Regular expression for matching IP addresses
is-cidr - Check if a string is an IP address in CIDR notation
is-ip - Check if a string is an IP address
cidr-regex - Regular expression for matching IP addresses in CIDR notation
cidr-tools - Tools to work with IPv4 and IPv6 CIDR network lists