Subnet Operations

/**
 * Get the first address in the subnet (Network Address)
 * Available on both Address4 and Address6 instances
 * @returns Address instance representing the network address
 */
startAddress(): Address4 | Address6;

/**
 * Get the first host address in the subnet (after Network Address)
 * Available on both Address4 and Address6 instances
 * @returns Address instance representing the first usable host address
 */
startAddressExclusive(): Address4 | Address6;

/**
 * Get the last address in the subnet (Broadcast Address for IPv4)
 * Available on both Address4 and Address6 instances
 * @returns Address instance representing the last address in range
 */
endAddress(): Address4 | Address6;

/**
 * Get the last host address in the subnet (before Broadcast for IPv4)
 * Available on both Address4 and Address6 instances
 * @returns Address instance representing the last usable host address
 */
endAddressExclusive(): Address4 | Address6;

import { Address4 } from "ip-address";

const network = new Address4("192.168.1.0/24");

console.log(network.startAddress().correctForm()); // "192.168.1.0" (Network)
console.log(network.startAddressExclusive().correctForm()); // "192.168.1.1" (First host)
console.log(network.endAddress().correctForm()); // "192.168.1.255" (Broadcast)
console.log(network.endAddressExclusive().correctForm()); // "192.168.1.254" (Last host)

// Smaller subnet
const smallNet = new Address4("10.0.0.0/30");
console.log(smallNet.startAddress().correctForm()); // "10.0.0.0"
console.log(smallNet.startAddressExclusive().correctForm()); // "10.0.0.1"
console.log(smallNet.endAddress().correctForm()); // "10.0.0.3"
console.log(smallNet.endAddressExclusive().correctForm()); // "10.0.0.2"

import { Address6 } from "ip-address";

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

console.log(network.startAddress().correctForm()); // "2001:db8::" (Network)
console.log(network.startAddressExclusive().correctForm()); // "2001:db8::1" (First host)
console.log(network.endAddress().correctForm()); // "2001:db8::ffff:ffff:ffff:ffff" (Last)
console.log(network.endAddressExclusive().correctForm()); // "2001:db8::ffff:ffff:ffff:fffe" (Last host)

// Smaller IPv6 subnet
const smallNet = new Address6("2001:db8:1234::/126");
console.log(smallNet.startAddress().correctForm()); // "2001:db8:1234::"
console.log(smallNet.endAddress().correctForm()); // "2001:db8:1234::3"

/**
 * Check if another address is contained within this address's subnet
 * Available on both Address4 and Address6 instances
 * @param address - Address to test for containment
 * @returns true if the address is within this subnet
 */
isInSubnet(address: Address4 | Address6): boolean;

const network = new Address4("192.168.1.0/24");
const host1 = new Address4("192.168.1.100");
const host2 = new Address4("192.168.2.100");

console.log(network.isInSubnet(host1)); // true (within 192.168.1.0/24)
console.log(network.isInSubnet(host2)); // false (different network)

// Test with different subnet sizes
const largeNet = new Address4("10.0.0.0/8");
const mediumNet = new Address4("10.1.0.0/16");
const host = new Address4("10.1.2.3");

console.log(largeNet.isInSubnet(host)); // true
console.log(largeNet.isInSubnet(mediumNet)); // true (subnet within subnet)
console.log(mediumNet.isInSubnet(largeNet)); // false (larger subnet not in smaller)

const network = new Address6("2001:db8::/32");
const host1 = new Address6("2001:db8:1234::1");
const host2 = new Address6("2001:db9::1");

console.log(network.isInSubnet(host1)); // true (within 2001:db8::/32)
console.log(network.isInSubnet(host2)); // false (different prefix)

// IPv6 with different prefix lengths
const site = new Address6("2001:db8:1000::/48");
const subnet = new Address6("2001:db8:1000:1::/64");
const host = new Address6("2001:db8:1000:1::100");

console.log(site.isInSubnet(subnet)); // true
console.log(site.isInSubnet(host)); // true
console.log(subnet.isInSubnet(host)); // true

/**
 * Get the first n bits of the address as a binary string
 * Defaults to the subnet mask length if no parameter provided
 * Available on both Address4 and Address6 instances
 * @param mask - Number of bits to include in mask (optional)
 * @returns Binary string representing the masked portion
 */
mask(mask?: number): string;

/**
 * Get bits in specified range as binary string
 * Available on both Address4 and Address6 instances
 * @param start - Starting bit position (0-based)
 * @param end - Ending bit position (exclusive)
 * @returns Binary string of the specified bit range
 */
getBitsBase2(start: number, end: number): string;

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

const addr = new Address4("192.168.1.100/24");

console.log(addr.mask()); // First 24 bits: "110000001010100000000001"
console.log(addr.mask(16)); // First 16 bits: "1100000010101000"
console.log(addr.getBitsBase2(0, 8)); // First octet: "11000000"
console.log(addr.getBitsBase2(24, 32)); // Last octet: "01100100"

// Network portion vs host portion
const network = new Address4("10.1.2.0/24");
console.log(network.mask(24)); // Network portion (24 bits)
console.log(network.getBitsBase2(24, 32)); // Host portion (8 bits)

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

console.log(addr.mask()); // First 64 bits (network portion)
console.log(addr.mask(48)); // First 48 bits (site prefix)
console.log(addr.getBitsBase2(0, 16)); // First group
console.log(addr.getBitsBase2(64, 128)); // Host portion (interface ID)

// IPv6 with getBitsPastSubnet for host portion
console.log(addr.getBitsPastSubnet()); // Host bits beyond subnet mask

/**
 * Calculate the number of possible subnets of a given size
 * Available on Address6 instances only
 * @param subnetSize - Target subnet size (default: 128)
 * @returns String representation of the number of possible subnets
 */
possibleSubnets(subnetSize?: number): string;

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

// How many /64 subnets can fit in a /32?
console.log(prefix.possibleSubnets(64)); // "4,294,967,296" (2^32)

// How many /48 subnets can fit in a /32?
console.log(prefix.possibleSubnets(48)); // "65,536" (2^16)

// How many /128 addresses can fit in a /64?
const subnet = new Address6("2001:db8:1::/64");
console.log(subnet.possibleSubnets(128)); // "18,446,744,073,709,551,616" (2^64)

// Edge case: subnet size larger than available space
console.log(subnet.possibleSubnets(48)); // "0" (can't fit /48 in /64)

// CIDR block analysis
const block = new Address4("203.0.113.0/24");

console.log(`Network: ${block.startAddress().correctForm()}`);
console.log(`First Host: ${block.startAddressExclusive().correctForm()}`);
console.log(`Last Host: ${block.endAddressExclusive().correctForm()}`);
console.log(`Broadcast: ${block.endAddress().correctForm()}`);

// Check if specific IPs are in range
const ips = ["203.0.113.1", "203.0.113.100", "203.0.113.255", "203.0.114.1"];
ips.forEach(ip => {
  const addr = new Address4(ip);
  console.log(`${ip} in subnet: ${block.isInSubnet(addr)}`);
});

// ISP allocation to customer
const ispBlock = new Address6("2001:db8::/32");
const customerPrefix = new Address6("2001:db8:1234::/48");
const customerSubnet = new Address6("2001:db8:1234:1::/64");
const host = new Address6("2001:db8:1234:1::100");

console.log(`Customer prefix in ISP block: ${ispBlock.isInSubnet(customerPrefix)}`);
console.log(`Subnet in customer prefix: ${customerPrefix.isInSubnet(customerSubnet)}`);
console.log(`Host in subnet: ${customerSubnet.isInSubnet(host)}`);

// Calculate how many /64s the customer can create
console.log(`Available /64 subnets: ${customerPrefix.possibleSubnets(64)}`);

// IPv6-mapped IPv4 addresses in subnets
const mappedAddr = Address6.fromAddress4("192.168.1.100/24");
console.log(mappedAddr.correctForm()); // "::ffff:c0a8:164"

// Extract IPv4 from mapped address and test subnet
const ipv4Net = new Address4("192.168.1.0/24");
const extractedV4 = mappedAddr.to4();
console.log(`IPv4 ${extractedV4.correctForm()} in subnet: ${ipv4Net.isInSubnet(extractedV4)}`);