or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

address-types.mdformat-conversion.mdindex.mdipv4.mdipv6.mdspecial-analysis.mdsubnet-operations.md
tile.json

tessl/npm-ip-address

A library for parsing IPv4 and IPv6 IP addresses in node and the browser.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/ip-address@10.0.x

To install, run

npx @tessl/cli install tessl/npm-ip-address@10.0.0

index.mddocs/

IP Address

A comprehensive library for validating, parsing, and manipulating IPv4 and IPv6 addresses in JavaScript and TypeScript. It provides extensive IPv6 notation parsing capabilities, URL-based address extraction, subnet validation, Teredo tunneling information decoding, and special address property detection.

Package Information

  • Package Name: ip-address
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install ip-address

Core Imports

import { Address4, Address6, AddressError } from "ip-address";

For CommonJS:

const { Address4, Address6, AddressError } = require("ip-address");

For IPv6 helper functions:

import { v6 } from "ip-address";

Basic Usage

import { Address4, Address6, AddressError } from "ip-address";

// IPv4 addresses
const ipv4 = new Address4("192.168.1.1/24");
console.log(ipv4.correctForm()); // "192.168.1.1"
console.log(ipv4.subnet); // "/24"

// IPv6 addresses
const ipv6 = new Address6("2001:4860:4001:803::1011");
console.log(ipv6.correctForm()); // "2001:4860:4001:803::1011"
console.log(ipv6.canonicalForm()); // "2001:4860:4001:0803:0000:0000:0000:1011"

// Validation
console.log(Address4.isValid("192.168.1.1")); // true
console.log(Address6.isValid("::1")); // true

// URL parsing
const result = Address6.fromURL("http://[2001:db8::1]:8080/path");
console.log(result.address.correctForm()); // "2001:db8::1"
console.log(result.port); // 8080

Architecture

The library is built around several key components:

  • Address Classes: Address4 and Address6 classes that encapsulate IP address parsing, validation, and manipulation
  • Static Constructors: Multiple creation methods from different formats (hex, binary, arpa, URLs)
  • Conversion System: Comprehensive conversion between different representations (hex, binary, decimal, canonical forms)
  • Subnet Analysis: Advanced subnet operations including range calculations and containment checks
  • Special Address Detection: Identification of multicast, loopback, Teredo, 6to4, and other special address types
  • Error Handling: Custom AddressError class for detailed error reporting

Capabilities

IPv4 Address Handling

Complete IPv4 address parsing, validation, and manipulation including subnet operations, format conversions, and range calculations.

class Address4 {
  constructor(address: string);
  static isValid(address: string): boolean;
  static fromHex(hex: string): Address4;
  static fromInteger(integer: number): Address4;
  static fromArpa(arpaFormAddress: string): Address4;
  static fromBigInt(bigInt: bigint): Address4;
  
  correctForm(): string;
  isCorrect(): boolean;
  toHex(): string;
  bigInt(): bigint;
}

IPv4 Address Operations

IPv6 Address Handling

Comprehensive IPv6 address parsing with support for all notation formats, IPv4-in-IPv6 addresses, URL parsing, and advanced address analysis.

class Address6 {
  constructor(address: string, optionalGroups?: number);
  static isValid(address: string): boolean;
  static fromBigInt(bigInt: bigint): Address6;
  static fromURL(url: string): { address: Address6; port: number | null };
  static fromAddress4(address: string): Address6;
  static fromArpa(arpaFormAddress: string): Address6;
  
  correctForm(): string;
  canonicalForm(): string;
  bigInt(): bigint;
  getType(): string;
  getScope(): string;
  
  // Subnet operations
  startAddress(): Address6;
  endAddress(): Address6;
  isInSubnet(address: Address6): boolean;
  
  // Special analysis
  inspectTeredo(): TeredoProperties;
  inspect6to4(): SixToFourProperties;
}

IPv6 Address Operations

Subnet and Range Operations

Advanced subnet analysis including network/broadcast address calculation, host range determination, and subnet containment testing.

// Available on both Address4 and Address6
interface SubnetOperations {
  startAddress(): Address4 | Address6;
  endAddress(): Address4 | Address6;
  startAddressExclusive(): Address4 | Address6;
  endAddressExclusive(): Address4 | Address6;
  isInSubnet(address: Address4 | Address6): boolean;
  mask(mask?: number): string;
}

Subnet Operations

Address Type Detection

Identification and analysis of special address types including multicast, loopback, Teredo, 6to4, and other reserved address ranges.

// IPv4 type detection
interface IPv4Types {
  isMulticast(): boolean;
}

// IPv6 type detection  
interface IPv6Types {
  isMulticast(): boolean;
  isLoopback(): boolean;
  isLinkLocal(): boolean;
  isTeredo(): boolean;
  is6to4(): boolean;
  is4(): boolean;
}

Address Type Detection

Format Conversion

Conversion between different address representations including hexadecimal, binary, decimal, canonical, and reverse DNS formats.

// Common conversion methods
interface FormatConversion {
  toHex(): string;
  binaryZeroPad(): string;
  reverseForm(options?: ReverseFormOptions): string;
  toArray(): number[]; // IPv4 only
  toByteArray(): number[]; // IPv6 only
}

Format Conversion

Special Address Analysis

Advanced analysis of specialized address formats including Teredo tunneling and 6to4 transition mechanisms.

// IPv6 specialized analysis
interface SpecialAnalysis {
  inspectTeredo(): TeredoProperties;
  inspect6to4(): SixToFourProperties;
  microsoftTranscription(): string;
}

Special Address Analysis

Error Handling

class AddressError extends Error {
  name: "AddressError";
  parseMessage?: string;
  
  constructor(message: string, parseMessage?: string);
}

The library throws AddressError instances for invalid addresses, malformed subnets, and other parsing errors. The optional parseMessage property may contain additional context for debugging.

Types

interface ReverseFormOptions {
  omitSuffix?: boolean;
}

interface TeredoProperties {
  prefix: string;
  server4: string;
  client4: string;
  flags: string;
  coneNat: boolean;
  microsoft: {
    reserved: boolean;
    universalLocal: boolean;
    groupIndividual: boolean;
    nonce: string;
  };
  udpPort: string;
}

interface SixToFourProperties {
  prefix: string;
  gateway: string;
}