IPv6 Address Operations

/**
 * Represents an IPv6 address with optional subnet mask and zone identifier
 * @param address - IPv6 address string (e.g., "2001:db8::1" or "2001:db8::1/64")
 * @param optionalGroups - Number of groups to parse (default: 8)
 */
class Address6 {
  constructor(address: string, optionalGroups?: number);
  
  // Properties
  address4?: Address4;          // IPv4 component if v4-in-v6
  address: string;              // Original address string
  addressMinusSuffix: string;   // Address without suffix
  elidedGroups?: number;        // Number of elided groups (::)
  elisionBegin?: number;        // Start position of elision
  elisionEnd?: number;          // End position of elision
  groups: number;               // Number of groups (8 for IPv6)
  parsedAddress4?: string;      // Parsed IPv4 component
  parsedAddress: string[];      // Array of address groups
  parsedSubnet: string;         // Subnet portion as string
  subnet: string;               // Subnet string (default "/128")
  subnetMask: number;           // Subnet mask length (0-128)
  v4: boolean;                  // True if contains IPv4 component
  zone: string;                 // Zone identifier (%zone)
}

/**
 * Validate an IPv6 address string without creating an instance
 * @param address - IPv6 address string to validate
 * @returns true if valid, false otherwise
 */
static isValid(address: string): boolean;

/**
 * Create Address6 from BigInt representation
 * @param bigInt - 128-bit BigInt representation
 * @returns Address6 instance
 */
static fromBigInt(bigInt: bigint): Address6;

/**
 * Parse IPv6 address and port from URL
 * @param url - URL containing IPv6 address (e.g., "http://[2001:db8::1]:8080/path")
 * @returns Object with address and port properties
 */
static fromURL(url: string): { address: Address6; port: number | null };

/**
 * Create IPv6-mapped IPv4 address from IPv4 string
 * @param address - IPv4 address string
 * @returns Address6 instance (::ffff:x.x.x.x format)
 */
static fromAddress4(address: string): Address6;

/**
 * Create Address6 from reverse DNS (ip6.arpa) format
 * @param arpaFormAddress - Reverse DNS string
 * @returns Address6 instance
 */
static fromArpa(arpaFormAddress: string): Address6;

/**
 * Create Address6 from byte array
 * @param bytes - Array of bytes representing the address
 * @returns Address6 instance
 */
static fromByteArray(bytes: Array<any>): Address6;

/**
 * Create Address6 from unsigned byte array
 * @param bytes - Array of unsigned bytes
 * @returns Address6 instance
 */
static fromUnsignedByteArray(bytes: Array<any>): Address6;

import { Address6 } from "ip-address";

// From string
const addr1 = new Address6("2001:db8::1/64");

// From BigInt
const bigIntAddr = Address6.fromBigInt(BigInt("42540766411282592856903984951653826561"));

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

// IPv6-mapped IPv4
const mapped = Address6.fromAddress4("192.168.1.1");
console.log(mapped.correctForm()); // "::ffff:c0a8:101"

// From reverse DNS
const arpa = Address6.fromArpa("1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa.");

// Validation
console.log(Address6.isValid("2001:db8::1")); // true
console.log(Address6.isValid("invalid")); // false

/**
 * Parse IPv6 address string into components
 * @param address - IPv6 address string
 * @returns Array of address groups as strings
 */
parse(address: string): string[];

/**
 * Parse IPv4-in-IPv6 component if present
 * @param address - Address string potentially containing IPv4
 * @returns Modified address string with IPv4 converted to IPv6 groups
 */
parse4in6(address: string): string;

/**
 * Return the correct compressed form of the address
 * @returns Correctly compressed IPv6 address string
 */
correctForm(): string;

/**
 * Return the canonical (uncompressed) form of the address
 * @returns Full 32-character hex representation with colons
 */
canonicalForm(): string;

/**
 * Return decimal representation of the address
 * @returns Colon-separated decimal groups
 */
decimal(): string;

/**
 * Check if address is in correct form
 * @returns true if address is correctly formatted
 */
isCorrect(): boolean;

/**
 * Check if address is in canonical form
 * @returns true if address is in canonical form
 */
isCanonical(): boolean;

const addr = new Address6("2001:0db8:0000:0000:0000:0000:0000:0001");

console.log(addr.correctForm()); // "2001:db8::1"
console.log(addr.canonicalForm()); // "2001:0db8:0000:0000:0000:0000:0000:0001"
console.log(addr.decimal()); // "08193:03512:00000:00000:00000:00000:00000:00001"

console.log(addr.isCorrect()); // false (not compressed)
console.log(addr.isCanonical()); // true

const compressed = new Address6("2001:db8::1");
console.log(compressed.isCorrect()); // true

/**
 * Convert address to BigInt representation
 * @returns 128-bit BigInt value
 */
bigInt(): bigint;

/**
 * Convert address to zero-padded binary string
 * @returns 128-character binary string
 */
binaryZeroPad(): string;

/**
 * Extract IPv4 address from last 32 bits
 * @returns Address4 instance from last 32 bits
 */
to4(): Address4;

/**
 * Return IPv4-in-IPv6 representation
 * @returns String with IPv4 notation in last group
 */
to4in6(): string;

/**
 * Convert to 6to4 address format
 * @returns Address6 instance in 6to4 format, or null if not applicable
 */
to6to4(): Address6 | null;

/**
 * Convert address to byte array
 * @returns Array of bytes representing the address
 */
toByteArray(): number[];

/**
 * Convert address to unsigned byte array
 * @returns Array of unsigned bytes
 */
toUnsignedByteArray(): number[];

const addr = new Address6("2001:db8:1234:5678::abcd");

console.log(addr.bigInt()); // BigInt representation
console.log(addr.binaryZeroPad()); // 128-bit binary string

// IPv4 extraction (from embedded IPv4)
const mapped = new Address6("::ffff:192.168.1.1");
console.log(mapped.to4().correctForm()); // "192.168.1.1"
console.log(mapped.to4in6()); // "::ffff:192.168.1.1"

// Byte arrays
console.log(addr.toByteArray()); // [32, 1, 13, 184, 18, 52, 86, 120, ...]

/**
 * Get first n bits as binary string (defaults to subnet mask)
 * @param mask - Number of bits to mask (optional)
 * @returns Binary string of masked bits
 */
mask(mask?: number): string;

/**
 * Get bits in specified range as BigInt
 * @param start - Start bit position (0-127)
 * @param end - End bit position (0-127)
 * @returns BigInt value of specified bits
 */
getBits(start: number, end: number): bigint;

/**
 * Get bits in specified range as binary string
 * @param start - Start bit position
 * @param end - End bit position
 * @returns Binary string of specified bits
 */
getBitsBase2(start: number, end: number): string;

/**
 * Get bits in specified range as hexadecimal string
 * @param start - Start bit position (must be divisible by 4)
 * @param end - End bit position (must be divisible by 4)
 * @returns Hex string of specified bits
 */
getBitsBase16(start: number, end: number): string;

/**
 * Get bits beyond the subnet mask
 * @returns Binary string of host portion
 */
getBitsPastSubnet(): string;

const addr = new Address6("2001:db8::1/64");

console.log(addr.mask()); // First 64 bits as binary
console.log(addr.getBits(0, 16)); // First 16 bits as BigInt
console.log(addr.getBitsBase2(0, 16)); // First 16 bits as binary
console.log(addr.getBitsBase16(0, 16)); // First 16 bits as hex
console.log(addr.getBitsPastSubnet()); // Host portion (last 64 bits)

/**
 * Get the scope of the address
 * @returns Scope string (e.g., "Global", "Link local", "Site local")
 */
getScope(): string;

/**
 * Get the type/category of the address
 * @returns Type string (e.g., "Global unicast", "Multicast", "Loopback")
 */
getType(): string;

/**
 * Check if address is link-local (fe80::/10 with zero padding)
 * @returns true if link-local address
 */
isLinkLocal(): boolean;

/**
 * Check if address is multicast
 * @returns true if multicast address (ff00::/8)
 */
isMulticast(): boolean;

/**
 * Check if address contains IPv4 component
 * @returns true if address has IPv4-in-IPv6 format
 */
is4(): boolean;

/**
 * Check if address is Teredo address
 * @returns true if Teredo address (2001::/32)
 */
isTeredo(): boolean;

/**
 * Check if address is 6to4 address
 * @returns true if 6to4 address (2002::/16)
 */
is6to4(): boolean;

/**
 * Check if address is loopback (::1)
 * @returns true if loopback address
 */
isLoopback(): boolean;

const global = new Address6("2001:db8::1");
console.log(global.getType()); // "Global unicast"
console.log(global.getScope()); // "Global"

const linkLocal = new Address6("fe80::1");
console.log(linkLocal.isLinkLocal()); // true
console.log(linkLocal.getScope()); // "Link local"

const multicast = new Address6("ff02::1");
console.log(multicast.isMulticast()); // true
console.log(multicast.getType()); // "Multicast (All nodes on this link)"

const teredo = new Address6("2001:0:ce49:7601:e866:efff:62c3:fffe");
console.log(teredo.isTeredo()); // true

/**
 * Return reverse DNS (ip6.arpa) form
 * @param options - Options for reverse form generation
 * @returns Reverse DNS string
 */
reverseForm(options?: ReverseFormOptions): string;

/**
 * Return Microsoft UNC transcription
 * @returns Microsoft-compatible IPv6 literal format
 */
microsoftTranscription(): string;

const addr = new Address6("2001:db8::1/64");

console.log(addr.reverseForm());
// "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa."

console.log(addr.reverseForm({ omitSuffix: true }));
// "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0"

console.log(addr.microsoftTranscription());
// "2001-db8-0-0-0-0-0-1.ipv6-literal.net"

/**
 * Generate HTTP URL with IPv6 address in brackets
 * @param optionalPort - Port number (optional)
 * @returns HTTP URL string
 */
href(optionalPort?: number | string): string;

/**
 * Generate HTML link with customizable formatting
 * @param options - Link generation options
 * @returns HTML anchor tag string
 */
link(options?: {
  className?: string;
  prefix?: string;
  v4?: boolean;
}): string;

/**
 * Generate HTML representation with styling classes
 * @returns HTML string with span elements and CSS classes
 */
group(): string;

const addr = new Address6("2001:db8::1");

console.log(addr.href()); // "http://[2001:db8::1]/"
console.log(addr.href(8080)); // "http://[2001:db8::1]:8080/"

console.log(addr.link());
// '<a href="/#address=2001:db8::1">2001:db8::1</a>'

console.log(addr.link({ className: "ipv6-link", prefix: "/ip/" }));
// '<a href="/ip/2001:db8::1" class="ipv6-link">2001:db8::1</a>'

/**
 * Generate regular expression string for matching address variations
 * @param substringSearch - Whether to generate for substring search
 * @returns Regular expression string
 */
regularExpressionString(substringSearch?: boolean): string;

/**
 * Generate RegExp object for matching address variations
 * @param substringSearch - Whether to generate for substring search
 * @returns RegExp object
 */
regularExpression(substringSearch?: boolean): RegExp;

const addr = new Address6("2001:db8::1");

const regex = addr.regularExpression();
console.log(regex.test("2001:0db8::1")); // true
console.log(regex.test("2001:db8:0:0:0:0:0:1")); // true

const regexStr = addr.regularExpressionString(true);
// Use for custom pattern matching

/**
 * Calculate number of possible subnets of given size
 * @param subnetSize - Target subnet size (default: 128)
 * @returns String representation of possible subnet count
 */
possibleSubnets(subnetSize?: number): string;

/**
 * Get the first address (network address) in this subnet
 * @returns Address6 instance of network address
 */
startAddress(): Address6;

/**
 * Get the first host address in this subnet
 * @returns Address6 instance of first host address
 */
startAddressExclusive(): Address6;

/**
 * Get the last address (broadcast address) in this subnet  
 * @returns Address6 instance of broadcast address
 */
endAddress(): Address6;

/**
 * Get the last host address in this subnet
 * @returns Address6 instance of last host address
 */
endAddressExclusive(): Address6;

/**
 * Check if given address is within this address's subnet
 * @param address - Address6 instance to check
 * @returns true if address is in subnet
 */
isInSubnet(address: Address6): boolean;

const network = new Address6("2001:db8::/32");

console.log(network.startAddress().correctForm()); // "2001:db8::"
console.log(network.endAddress().correctForm()); // "2001:db8:ffff:ffff:ffff:ffff:ffff:ffff"

const host = new Address6("2001:db8::1");
console.log(network.isInSubnet(host)); // true

console.log(network.possibleSubnets(64)); // Number of /64 subnets in /32

/**
 * Extract Teredo tunnel properties from address
 * @returns Object containing Teredo configuration details
 */
inspectTeredo(): TeredoProperties;

/**
 * Extract 6to4 tunnel properties from address
 * @returns Object containing 6to4 configuration details  
 */
inspect6to4(): SixToFourProperties;

// Teredo address analysis
const teredo = new Address6("2001:0:ce49:7601:e866:efff:62c3:fffe");
const teredoInfo = teredo.inspectTeredo();
console.log(teredoInfo.server4); // "206.73.118.1"
console.log(teredoInfo.client4); // "157.60.0.1"

// 6to4 address analysis  
const sixToFour = new Address6("2002:c000:0204::1");
const info = sixToFour.inspect6to4();
console.log(info.gateway); // "192.0.2.4"

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;
}