cidr-block
Version:
IPv4 and IPv6 address and cidr range utilities
407 lines • 13.3 kB
TypeScript
import { Ipv6Address } from './ipv6-address';
import type { Ipv6CidrLiteral } from './ipv6-types';
/**
* Represents an IPv6 CIDR block with utility methods for subnet operations.
*
* While you can instantiate this class directly, it is recommended to use the
* {@link ipv6.cidr} shorthand method from the `ipv6` namespace instead.
*
* @example Creating CIDR blocks (prefer the shorthand)
* ```ts
* import { ipv6 } from 'cidr-block';
*
* // Recommended: use the ipv6 namespace shorthand
* const cidr1 = ipv6.cidr("2001:db8::/32");
* const cidr2 = ipv6.cidr({ address: "2001:db8::", range: 32 });
* const cidr3 = ipv6.cidr(["2001:db8::", 32]);
* ```
*
* @example Getting CIDR properties
* ```ts
* import { ipv6 } from 'cidr-block';
*
* const cidr = ipv6.cidr("2001:db8::/32");
* cidr.baseAddress().toString(); // "2001:db8::"
* cidr.range(); // 32
* cidr.netmask().toString(); // "ffff:ffff::"
* cidr.network().toString(); // "2001:db8::"
* cidr.addressCount(); // 79228162514264337593543950336n
* ```
*
* @example Working with usable addresses
* ```ts
* import { ipv6 } from 'cidr-block';
*
* const cidr = ipv6.cidr("2001:db8::/126");
* cidr.getFirstUsableAddress()?.toString(); // "2001:db8::1"
* cidr.getLastUsableAddress()?.toString(); // "2001:db8::2"
* ```
*
* @example Checking containment and overlap
* ```ts
* import { ipv6 } from 'cidr-block';
*
* const cidr = ipv6.cidr("2001:db8::/32");
* cidr.includes(ipv6.address("2001:db8::1")); // true
* cidr.includes(ipv6.address("2001:db9::1")); // false
* cidr.overlaps("2001:db8::/48"); // true
* cidr.overlaps("2001:db9::/32"); // false
* ```
*
* @example Splitting into subranges
* ```ts
* import { ipv6 } from 'cidr-block';
*
* const cidr = ipv6.cidr("2001:db8::/32");
*
* // Split into equal /48 subnets
* cidr.subnet(34).map(s => s.toString());
* // ["2001:db8::/34", "2001:db8:4000::/34", "2001:db8:8000::/34", "2001:db8:c000::/34"]
* ```
*
* @example Navigating sequential CIDRs
* ```ts
* import { ipv6 } from 'cidr-block';
*
* const cidr = ipv6.cidr("2001:db8::/32");
* cidr.nextCIDR()?.toString(); // "2001:db9::/32"
* cidr.previousCIDR()?.toString(); // "2001:db7::/32"
* ```
*/
export declare class Ipv6Cidr {
#private;
constructor(address: Ipv6CidrLiteral);
/**
* Gets the base IPv6 address of the CIDR.
*
* @example
* ```ts
* import { ipv6 } from 'cidr-block';
*
* const cidr = ipv6.cidr("2001:db8::/32");
* cidr.baseAddress().toString(); // "2001:db8::"
* ```
*
* @returns The base IPv6 address.
*/
baseAddress(): Ipv6Address;
/**
* Gets the CIDR range.
*
* @example
* ```ts
* import { ipv6 } from 'cidr-block';
*
* const cidr = ipv6.cidr("2001:db8::/32");
* cidr.range(); // 32
* ```
*
* @returns The CIDR range as a number.
*/
range(): number;
/**
* Calculates the netmask for the CIDR range.
*
* @example
* ```ts
* import { ipv6 } from 'cidr-block';
*
* ipv6.cidr("2001:db8::/32").netmask().toString(); // "ffff:ffff::"
* ipv6.cidr("2001:db8::/64").netmask().toString(); // "ffff:ffff:ffff:ffff::"
* ipv6.cidr("2001:db8::/128").netmask().toString(); // "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff"
* ```
*
* @returns The netmask as an Ipv6Address.
*/
netmask(): Ipv6Address;
/**
* Calculates the hostmask (inverse of the netmask) for the CIDR range.
*
* @example
* ```ts
* import { ipv6 } from 'cidr-block';
*
* ipv6.cidr("2001:db8::/32").hostmask().toString(); // "::ffff:ffff:ffff:ffff:ffff:ffff"
* ipv6.cidr("2001:db8::/64").hostmask().toString(); // "::ffff:ffff:ffff:ffff"
* ipv6.cidr("2001:db8::/48").hostmask().toString(); // "::ffff:ffff:ffff:ffff:ffff"
* ```
*
* @returns The hostmask as an Ipv6Address.
*/
hostmask(): Ipv6Address;
/**
* Calculates the network address by applying the netmask to the base address.
*
* @example
* ```ts
* import { ipv6 } from 'cidr-block';
*
* ipv6.cidr("2001:db8::1234/32").network().toString(); // "2001:db8::"
* ipv6.cidr("2001:db8:1:2:3:4:5:6/64").network().toString(); // "2001:db8:1:2::"
* ipv6.cidr("2001:db8:abcd::/48").network().toString(); // "2001:db8:abcd::"
* ```
*
* @returns The network address as an Ipv6Address.
*/
network(): Ipv6Address;
/**
* Calculates the network CIDR by applying the netmask to the base address and returning a CIDR with the network address.
*
* @example
* ```ts
* import { ipv6 } from 'cidr-block';
*
* ipv6.cidr("2001:db8::1234/32").networkCIDR().toString(); // "2001:db8::/32"
* ipv6.cidr("2001:db8:1:2:3:4:5:6/64").networkCIDR().toString(); // "2001:db8:1:2::/64"
* ipv6.cidr("2001:db8:abcd::/48").networkCIDR().toString(); // "2001:db8:abcd::/48"
* ```
*
* @returns The network CIDR as an Ipv6Cidr.
*/
networkCIDR(): Ipv6Cidr;
/**
* Returns the string representation of the IPv6 CIDR.
*
* @example
* ```ts
* import { ipv6 } from 'cidr-block';
*
* const cidr = ipv6.cidr({ address: "2001:db8::", range: 32 });
* cidr.toString(); // "2001:db8::/32"
* ```
*
* @returns The IPv6 CIDR as a string (example: "2001:db8::/32").
*/
toString(): string;
/**
* Gets the address and range parts of the IPv6 CIDR.
*
* @example
* ```ts
* import { ipv6 } from 'cidr-block';
*
* const [address, range] = ipv6.cidr("2001:db8::/32").rangeParts();
* address.toString(); // "2001:db8::"
* range; // 32
* ```
*
* @returns A tuple containing the IPv6 address and the CIDR range.
*/
rangeParts(): [Ipv6Address, number];
/**
* Calculates the total number of addresses in the CIDR range.
*
* @example
* ```ts
* import { ipv6 } from 'cidr-block';
*
* ipv6.cidr("2001:db8::/64").addressCount(); // 18446744073709551616n
* ipv6.cidr("2001:db8::/128").addressCount(); // 1n
* ipv6.cidr("2001:db8::/126").addressCount(); // 4n
* ```
*
* @returns The total number of addresses in the CIDR range as a BigInt.
*/
addressCount(): bigint;
/**
* Generates IPv6 addresses within the CIDR range.
* Note: For large CIDR ranges, this may generate an extremely large number of addresses.
* Use with caution and consider using a limit parameter.
*
* @example
* ```ts
* import { ipv6 } from 'cidr-block';
*
* const cidr = ipv6.cidr("2001:db8::/126");
* for (const addr of cidr.addresses()) {
* console.log(addr.toString());
* }
* // Output: "2001:db8::", "2001:db8::1", "2001:db8::2", "2001:db8::3"
* ```
*
* @param limit - Optional maximum number of addresses to generate (defaults to all addresses).
* @returns A generator that yields each IPv6 address in the CIDR range.
*/
addresses(limit?: bigint): Generator<Ipv6Address>;
/**
* Checks if this CIDR is equal to another CIDR.
*
* @example
* ```ts
* import { ipv6 } from 'cidr-block';
*
* const cidr = ipv6.cidr("2001:db8::/32");
* cidr.equals("2001:db8::/32"); // true
* cidr.equals({ address: "2001:db8::", range: 32 }); // true
* cidr.equals("2001:db8::/48"); // false
* ```
*
* @param other - The other IPv6 CIDR to compare with.
* @returns True if both CIDRs have the same base address and range; otherwise, false.
*/
equals(other: Ipv6Cidr | Ipv6CidrLiteral): boolean;
/**
* Checks if there is a next sequential CIDR.
*
* @example
* ```ts
* import { ipv6 } from 'cidr-block';
*
* ipv6.cidr("2001:db8::/32").hasNextCIDR(); // true
* ipv6.cidr("ffff:ffff:ffff:ffff:ffff:ffff:ffff:ff00/120").hasNextCIDR(); // false
* ```
*
* @returns true if there is a next CIDR.
*/
hasNextCIDR(): boolean;
/**
* Gets the next sequential CIDR.
*
* @example
* ```ts
* import { ipv6 } from 'cidr-block';
*
* const cidr = ipv6.cidr("2001:db8::/32");
* cidr.nextCIDR()?.toString(); // "2001:db9::/32"
* ```
*
* @returns The next CIDR, or undefined if there is no next CIDR.
*/
nextCIDR(): Ipv6Cidr | undefined;
/**
* Checks if there is a previous sequential CIDR.
*
* @example
* ```ts
* import { ipv6 } from 'cidr-block';
*
* ipv6.cidr("2001:db8::/32").hasPreviousCIDR(); // true
* ipv6.cidr("::/32").hasPreviousCIDR(); // false
* ```
*
* @returns true if there is a previous CIDR.
*/
hasPreviousCIDR(): boolean;
/**
* Gets the previous sequential CIDR.
*
* @example
* ```ts
* import { ipv6 } from 'cidr-block';
*
* const cidr = ipv6.cidr("2001:db8::/32");
* cidr.previousCIDR()?.toString(); // "2001:db7::/32"
*
* const firstCidr = ipv6.cidr("::/32");
* firstCidr.previousCIDR(); // undefined
* ```
*
* @returns The previous CIDR, or undefined if there is no previous CIDR.
*/
previousCIDR(): Ipv6Cidr | undefined;
/**
* Gets the first usable address in the CIDR range.
*
* @example
* ```ts
* import { ipv6 } from 'cidr-block';
*
* const cidr = ipv6.cidr("2001:db8::/64");
* cidr.getFirstUsableAddress()?.toString(); // "2001:db8::1"
*
* const hostCidr = ipv6.cidr("2001:db8::1/128");
* hostCidr.getFirstUsableAddress(); // undefined (no usable addresses in /128)
* ```
*
* @returns The first usable IPv6 address, or undefined if the range is /128.
*/
getFirstUsableAddress(): Ipv6Address | undefined;
/**
* Gets the last usable address in the CIDR range.
*
* @example
* ```ts
* import { ipv6 } from 'cidr-block';
*
* const cidr = ipv6.cidr("2001:db8::/126");
* cidr.getLastUsableAddress()?.toString(); // "2001:db8::2"
*
* const hostCidr = ipv6.cidr("2001:db8::1/128");
* hostCidr.getLastUsableAddress(); // undefined (no usable addresses in /128)
* ```
*
* @returns The last usable IPv6 address, or undefined if the range is /128.
*/
getLastUsableAddress(): Ipv6Address | undefined;
/**
* Checks if the given IPv6 address is within the CIDR range.
*
* @example
* ```ts
* import { ipv6 } from 'cidr-block';
*
* const cidr = ipv6.cidr("2001:db8::/32");
* cidr.includes(ipv6.address("2001:db8::1")); // true
* cidr.includes(ipv6.address("2001:db9::1")); // false
* ```
*
* @param ip - The IPv6 address to check.
* @returns True if the address is within the CIDR range; otherwise, false.
*/
includes(ip: Ipv6Address): boolean;
/**
* Checks if this CIDR overlaps with another CIDR.
*
* @example
* ```ts
* import { ipv6 } from 'cidr-block';
*
* const cidr = ipv6.cidr("2001:db8::/32");
* cidr.overlaps("2001:db8::/48"); // true (subset)
* cidr.overlaps("2001:db8:8000::/33"); // true (partial overlap)
* cidr.overlaps("2001:db9::/32"); // false (no overlap)
* ```
*
* @param other - The other IPv6 CIDR to check for overlap.
* @returns True if the CIDRs overlap; otherwise, false.
*/
overlaps(other: Ipv6Cidr | Ipv6CidrLiteral): boolean;
/**
* Splits the CIDR into smaller subranges of the specified new range.
*
* @example
* ```ts
* import { ipv6 } from 'cidr-block';
*
* const cidr = ipv6.cidr("2001:db8::/32");
* const subnets = cidr.subnet(34);
* subnets.map(s => s.toString());
* // ["2001:db8::/34", "2001:db8:4000::/34", "2001:db8:8000::/34", "2001:db8:c000::/34"]
* ```
*
* @param newRange - The new CIDR range for the subnets.
* @returns An array of Ipv6Cidr instances representing the subnets.
* @throws InvalidIpv6CidrRangeError if the new range is less than the current range or greater than the maximum range.
*/
subnet(newRange: number): Ipv6Cidr[];
/**
* Splits the CIDR into sequential subranges with the specified CIDR ranges.
* Each range in the input array creates a subrange starting where the previous one ended.
*
* @example
* ```ts
* import { ipv6 } from 'cidr-block';
*
* const cidr = ipv6.cidr("2001:db8::/32");
* const subnets = cidr.subnetBy([48, 36, 48]);
* subnets.map(s => s.toString());
* // ["2001:db8::/48", "2001:db8:1::/36", "2001:db8:1100::/48"]
* ```
*
* @param ranges - An array of CIDR range values (e.g., [48, 36, 48]).
* @returns An array of Ipv6Cidr instances representing the subnets.
* @throws InvalidIpv6CidrRangeError if any range is less than the current range or greater than 128.
*/
subnetBy(ranges: number[]): Ipv6Cidr[];
}
//# sourceMappingURL=ipv6-cidr.d.ts.map