cidr-block
Version:
IPv4 and IPv6 address and cidr range utilities
422 lines • 13.4 kB
TypeScript
import { Ipv4Address } from './ipv4-address';
import type { Ipv4CidrLiteral, Ipv4CidrString } from './ipv4-types';
/**
* Represents an IPv4 CIDR block with utility methods for subnet operations.
*
* While you can instantiate this class directly, it is recommended to use the
* {@link ipv4.cidr} shorthand method from the `ipv4` namespace instead.
*
* @example Creating CIDR blocks (prefer the shorthand)
* ```ts
* import { ipv4 } from 'cidr-block';
*
* // Recommended: use the ipv4 namespace shorthand
* const cidr1 = ipv4.cidr("192.168.0.0/24");
* const cidr2 = ipv4.cidr({ address: "10.0.0.0", range: 8 });
* const cidr3 = ipv4.cidr([[172, 16, 0, 0], 12]);
* ```
*
* @example Getting CIDR properties
* ```ts
* import { ipv4 } from 'cidr-block';
*
* const cidr = ipv4.cidr("192.168.0.0/24");
* cidr.baseAddress().toString(); // "192.168.0.0"
* cidr.range(); // 24
* cidr.netmask().toString(); // "255.255.255.0"
* cidr.network().toString(); // "192.168.0.0"
* cidr.addressCount(); // 256
* ```
*
* @example Working with usable addresses
* ```ts
* import { ipv4 } from 'cidr-block';
*
* const cidr = ipv4.cidr("192.168.0.0/24");
* cidr.getFirstUsableAddress()?.toString(); // "192.168.0.1"
* cidr.getLastUsableAddress()?.toString(); // "192.168.0.254"
* ```
*
* @example Iterating over addresses
* ```ts
* import { ipv4 } from 'cidr-block';
*
* const cidr = ipv4.cidr("192.168.1.0/30");
* for (const addr of cidr.addresses()) {
* console.log(addr.toString());
* }
* // "192.168.1.0", "192.168.1.1", "192.168.1.2", "192.168.1.3"
* ```
*
* @example Checking containment and overlap
* ```ts
* import { ipv4 } from 'cidr-block';
*
* const cidr = ipv4.cidr("192.168.0.0/24");
* cidr.includes(ipv4.address("192.168.0.100")); // true
* cidr.includes(ipv4.address("192.168.1.1")); // false
* cidr.overlaps("192.168.0.0/25"); // true
* cidr.overlaps("10.0.0.0/8"); // false
* ```
*
* @example Splitting into subranges
* ```ts
* import { ipv4 } from 'cidr-block';
*
* const cidr = ipv4.cidr("192.168.0.0/24");
*
* // Split into equal /26 subnets
* cidr.subnet(26).map(s => s.toString());
* // ["192.168.0.0/26", "192.168.0.64/26", "192.168.0.128/26", "192.168.0.192/26"]
*
* // Split by specific ranges
* cidr.subnetBy([25, 26, 27, 27]).map(s => s.toString());
* // ["192.168.0.0/25", "192.168.0.128/26", "192.168.0.192/27", "192.168.0.224/27"]
* ```
*
* @example Navigating sequential CIDRs
* ```ts
* import { ipv4 } from 'cidr-block';
*
* const cidr = ipv4.cidr("192.168.0.0/24");
* cidr.nextCIDR()?.toString(); // "192.168.1.0/24"
* cidr.previousCIDR()?.toString(); // "192.167.255.0/24"
* ```
*/
export declare class Ipv4Cidr {
#private;
constructor(address: Ipv4CidrLiteral);
/**
* Gets the base IPv4 address of the CIDR.
*
* @example
* ```ts
* import { ipv4 } from 'cidr-block';
*
* const cidr = ipv4.cidr("192.168.0.0/24");
* cidr.baseAddress().toString(); // "192.168.0.0"
* ```
*
* @returns The base IPv4 address.
*/
baseAddress(): Ipv4Address;
/**
* Gets the CIDR range.
*
* @example
* ```ts
* import { ipv4 } from 'cidr-block';
*
* const cidr = ipv4.cidr("192.168.0.0/24");
* cidr.range(); // 24
* ```
*
* @returns The CIDR range as a number.
*/
range(): number;
/**
* Calculates the netmask for the CIDR range.
*
* @example
* ```ts
* import { ipv4 } from 'cidr-block';
*
* ipv4.cidr("192.168.0.0/24").netmask().toString(); // "255.255.255.0"
* ipv4.cidr("10.0.0.0/8").netmask().toString(); // "255.0.0.0"
* ipv4.cidr("172.16.0.0/16").netmask().toString(); // "255.255.0.0"
* ```
*
* @returns The netmask as an Ipv4Address.
*/
netmask(): Ipv4Address;
/**
* Calculates the hostmask (inverse of the netmask) for the CIDR range.
*
* @example
* ```ts
* import { ipv4 } from 'cidr-block';
*
* ipv4.cidr("192.168.0.0/24").hostmask().toString(); // "0.0.0.255"
* ipv4.cidr("10.0.0.0/8").hostmask().toString(); // "0.255.255.255"
* ipv4.cidr("172.16.0.0/16").hostmask().toString(); // "0.0.255.255"
* ```
*
* @returns The hostmask as an Ipv4Address.
*/
hostmask(): Ipv4Address;
/**
* Calculates the network address by applying the netmask to the base address.
*
* @example
* ```ts
* import { ipv4 } from 'cidr-block';
*
* ipv4.cidr("192.168.1.5/24").network().toString(); // "192.168.1.0"
* ipv4.cidr("10.5.10.20/8").network().toString(); // "10.0.0.0"
* ipv4.cidr("172.16.5.1/16").network().toString(); // "172.16.0.0"
* ```
*
* @returns The network address as an Ipv4Address.
*/
network(): Ipv4Address;
/**
* Calculates the network CIDR by applying the netmask to the base address and returning a CIDR with the network address.
*
* @example
* ```ts
* import { ipv4 } from 'cidr-block';
*
* ipv4.cidr("192.168.1.5/24").networkCIDR().toString(); // "192.168.1.0/24"
* ipv4.cidr("10.5.10.20/8").networkCIDR().toString(); // "10.0.0.0/8"
* ipv4.cidr("172.16.5.1/16").networkCIDR().toString(); // "172.16.0.0/16"
* ```
*
* @returns The network CIDR as an Ipv4Cidr.
*/
networkCIDR(): Ipv4Cidr;
/**
* Returns the string representation of the IPv4 CIDR.
*
* @example
* ```ts
* import { ipv4 } from 'cidr-block';
*
* const cidr = ipv4.cidr({ address: "10.0.0.0", range: 8 });
* cidr.toString(); // "10.0.0.0/8"
* ```
*
* @returns The IPv4 CIDR as a string (example: "192.0.0.0/24").
*/
toString(): Ipv4CidrString;
/**
* Gets the address and range parts of the IPv4 CIDR.
*
* @example
* ```ts
* import { ipv4 } from 'cidr-block';
*
* const [address, range] = ipv4.cidr("192.168.0.0/24").rangeParts();
* address.toString(); // "192.168.0.0"
* range; // 24
* ```
*
* @returns A tuple containing the IPv4 address and the CIDR range.
*/
rangeParts(): [Ipv4Address, number];
/**
* Calculates the total number of addresses in the CIDR range.
*
* @example
* ```ts
* import { ipv4 } from 'cidr-block';
*
* ipv4.cidr("192.168.0.0/24").addressCount(); // 256
* ipv4.cidr("10.0.0.0/8").addressCount(); // 16777216
* ipv4.cidr("192.168.1.0/32").addressCount(); // 1
* ```
*
* @returns The total number of addresses in the CIDR range.
*/
addressCount(): number;
/**
* Generates all IPv4 addresses within the CIDR range.
*
* @example
* ```ts
* import { ipv4 } from 'cidr-block';
*
* const cidr = ipv4.cidr("192.168.1.0/30");
* for (const addr of cidr.addresses()) {
* console.log(addr.toString());
* }
* // Output: "192.168.1.0", "192.168.1.1", "192.168.1.2", "192.168.1.3"
* ```
*
* @returns A generator that yields each IPv4 address in the CIDR range.
*/
addresses(): Generator<Ipv4Address>;
/**
* Checks if this CIDR is equal to another CIDR.
*
* @example
* ```ts
* import { ipv4 } from 'cidr-block';
*
* const cidr = ipv4.cidr("192.168.0.0/24");
* cidr.equals("192.168.0.0/24"); // true
* cidr.equals({ address: "192.168.0.0", range: 24 }); // true
* cidr.equals("10.0.0.0/8"); // false
* ```
*
* @param other - The other IPv4 CIDR to compare with.
* @returns True if both CIDRs have the same base address and range; otherwise, false.
*/
equals(other: Ipv4Cidr | Ipv4CidrLiteral): boolean;
/**
* Checks if there is a next sequential CIDR.
*
* @example
* ```ts
* import { ipv4 } from 'cidr-block';
*
* ipv4.cidr("192.168.0.0/24").hasNextCIDR(); // true
* ipv4.cidr("255.255.255.0/24").hasNextCIDR(); // false
* ```
*
* @returns true if there is a next CIDR.
*/
hasNextCIDR(): boolean;
/**
* Gets the next sequential CIDR.
*
* @example
* ```ts
* import { ipv4 } from 'cidr-block';
*
* const cidr = ipv4.cidr("192.168.0.0/24");
* cidr.nextCIDR()?.toString(); // "192.168.1.0/24"
*
* const lastCidr = ipv4.cidr("255.255.255.0/24");
* lastCidr.nextCIDR(); // undefined
* ```
*
* @returns The next CIDR, or undefined if there is no next CIDR.
*/
nextCIDR(): Ipv4Cidr | undefined;
/**
* Checks if there is a previous sequential CIDR.
*
* @example
* ```ts
* import { ipv4 } from 'cidr-block';
*
* ipv4.cidr("192.168.1.0/24").hasPreviousCIDR(); // true
* ipv4.cidr("0.0.0.0/24").hasPreviousCIDR(); // false
* ```
*
* @returns true if there is a previous CIDR.
*/
hasPreviousCIDR(): boolean;
/**
* Gets the previous sequential CIDR.
*
* @example
* ```ts
* import { ipv4 } from 'cidr-block';
*
* const cidr = ipv4.cidr("192.168.1.0/24");
* cidr.previousCIDR()?.toString(); // "192.168.0.0/24"
*
* const firstCidr = ipv4.cidr("0.0.0.0/24");
* firstCidr.previousCIDR(); // undefined
* ```
*
* @returns The previous CIDR, or undefined if there is no previous CIDR.
*/
previousCIDR(): Ipv4Cidr | undefined;
/**
* Gets the first usable address in the CIDR range.
*
* @example
* ```ts
* import { ipv4 } from 'cidr-block';
*
* const cidr = ipv4.cidr("192.168.0.0/24");
* cidr.getFirstUsableAddress()?.toString(); // "192.168.0.1"
*
* const hostCidr = ipv4.cidr("192.168.1.1/32");
* hostCidr.getFirstUsableAddress(); // undefined (no usable addresses in /32)
* ```
*
* @returns The first usable IPv4 address, or undefined if the range is /32.
*/
getFirstUsableAddress(): Ipv4Address | undefined;
/**
* Gets the last usable address in the CIDR range.
*
* @example
* ```ts
* import { ipv4 } from 'cidr-block';
*
* const cidr = ipv4.cidr("192.168.0.0/24");
* cidr.getLastUsableAddress()?.toString(); // "192.168.0.254"
*
* const hostCidr = ipv4.cidr("192.168.1.1/32");
* hostCidr.getLastUsableAddress(); // undefined (no usable addresses in /32)
* ```
*
* @returns The last usable IPv4 address, or undefined if the range is /32.
*/
getLastUsableAddress(): Ipv4Address | undefined;
/**
* Checks if the given IPv4 address is within the CIDR range.
*
* @example
* ```ts
* import { ipv4 } from 'cidr-block';
*
* const cidr = ipv4.cidr("192.168.0.0/24");
* cidr.includes(ipv4.address("192.168.0.100")); // true
* cidr.includes(ipv4.address("192.168.1.1")); // false
* ```
*
* @param ip - The IPv4 address to check.
* @returns True if the address is within the CIDR range; otherwise, false.
*/
includes(ip: Ipv4Address): boolean;
/**
* Checks if this CIDR overlaps with another CIDR.
*
* @example
* ```ts
* import { ipv4 } from 'cidr-block';
*
* const cidr = ipv4.cidr("192.168.0.0/24");
* cidr.overlaps("192.168.0.0/25"); // true (subset)
* cidr.overlaps("192.168.0.128/25"); // true (partial overlap)
* cidr.overlaps("10.0.0.0/8"); // false (no overlap)
* ```
*
* @param other - The other IPv4 CIDR to check for overlap.
* @returns True if the CIDRs overlap; otherwise, false.
*/
overlaps(other: Ipv4Cidr | Ipv4CidrLiteral): boolean;
/**
* Splits the CIDR into smaller subranges of the specified new range.
*
* @example
* ```ts
* import { ipv4 } from 'cidr-block';
*
* const cidr = ipv4.cidr("192.168.0.0/24");
* const subnets = cidr.subnet(26);
* subnets.map(s => s.toString());
* // ["192.168.0.0/26", "192.168.0.64/26", "192.168.0.128/26", "192.168.0.192/26"]
* ```
*
* @param newRange - The new CIDR range for the subnets.
* @returns An array of Ipv4Cidr instances representing the subnets.
* @throws InvalidIpv4CidrRangeError if the new range is less than the current range or greater than the maximum range.
*/
subnet(newRange: number): Ipv4Cidr[];
/**
* 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 { ipv4 } from 'cidr-block';
*
* const cidr = ipv4.cidr("10.0.0.0/16");
* const subnets = cidr.subnetBy([24, 20, 24]);
* subnets.map(s => s.toString());
* // ["10.0.0.0/24", "10.0.1.0/20", "10.0.17.0/24"]
* ```
*
* @param ranges - An array of CIDR range values (e.g., [24, 20, 24]).
* @returns An array of Ipv4Cidr instances representing the subnets.
* @throws InvalidIpv4CidrRangeError if any range is less than the current range or greater than 32.
*/
subnetBy(ranges: number[]): Ipv4Cidr[];
}
//# sourceMappingURL=ipv4-cidr.d.ts.map