IPv4 address parsing and stringifying utilities.

This module provides functions to convert between IPv4 dotted decimal notation and number representation, enabling arithmetic operations on IP addresses.

Examples

Basic IPv4 operations

import { assertEquals } from "@std/assert";
import { parseAddressv4, stringifyAddressv4 } from "@hertzg/ip/addressv4";

const { address } = parseAddressv4("192.168.1.1");
assertEquals(address, 3232235777);

const next = address + 1;
assertEquals(stringifyAddressv4(next), "192.168.1.2");

Zone IDs are carried, not applied

import { assertEquals } from "@std/assert";
import { parseAddressv4, stringifyAddressv4 } from "@hertzg/ip/addressv4";

const gateway = parseAddressv4("10.155.101.1%ether1");
assertEquals(gateway, { address: 177956097, zoneId: "ether1" });
assertEquals(stringifyAddressv4(gateway), "10.155.101.1%ether1");
assertEquals(stringifyAddressv4(gateway.address), "10.155.101.1");

Bitwise operations on IPv4 addresses

Since IPv4 addresses are plain numbers, you can use standard JavaScript bitwise operators directly instead of library functions. Use >>> 0 to keep results as unsigned 32-bit integers.

import { assertEquals } from "@std/assert";
import { parseAddressv4, stringifyAddressv4 } from "@hertzg/ip/addressv4";
import { cidrv4Mask } from "@hertzg/ip/cidrv4";

const ip = parseAddressv4("192.168.1.100").address;
const mask = cidrv4Mask(24);

// Bitwise NOT (invert all bits)
const inverted = (~ip >>> 0);
assertEquals(stringifyAddressv4(inverted), "63.87.254.155");

// Bitwise AND (apply network mask to get network address)
const network = ((ip & mask) >>> 0);
assertEquals(stringifyAddressv4(network), "192.168.1.0");

// Bitwise OR (combine network with host bits for broadcast)
const broadcast = ((network | (~mask >>> 0)) >>> 0);
assertEquals(stringifyAddressv4(broadcast), "192.168.1.255");

// Direct comparison (no isEqual() needed)
assertEquals(parseAddressv4("10.0.0.1").address === parseAddressv4("10.0.0.1").address, true);
assertEquals(parseAddressv4("10.0.0.1").address === parseAddressv4("10.0.0.2").address, false);

Functions

f
compareAddressv4(
a: Addressv4,
b: Addressv4
): -1 | 0 | 1

Compares two IPv4 addresses for sorting, numerically ascending.

f
parseAddressv4(address: string): ParsedAddressv4

Parses an IPv4 address in dotted decimal notation, with an optional zone ID, to its numeric value.

f
stringifyAddressv4(address: Addressv4 | ParsedAddressv4): string

Stringifies an IPv4 address to dotted decimal notation.

Type Aliases

T
Addressv4 = number

An IPv4 address as a 32-bit unsigned integer, 0 to 4294967295. The primitive type is what carries the version: a number is IPv4, a bigint is IPv6 (ADR 0001).

T
ParsedAddressv4 = { readonly address: Addressv4; readonly zoneId?: ZoneId; }

What parseAddressv4 returns and what stringifyAddressv4 accepts: the address, plus the zone ID if the notation had one. Read .address for the bare Addressv4; the zone never touches the value, and no operation in this package reads it.

T
ZoneId = string

The zone ID of an address, the interface tail after % in fe80::1%eth0 (RFC 4007 section 11). Carried verbatim by the Parsed* types; never percent-decoded, so %25eth0 is the zone 25eth0.

Usage

import * as mod from "addressv4.ts";