cidr-block
Version:
IPv4 and IPv6 address and cidr range utilities
221 lines • 7.96 kB
TypeScript
import type { Ipv4AddressLiteral, Ipv4AddressOctets, Ipv4CidrLiteral } from './ipv4-types';
import { Ipv4Address } from './ipv4-address';
import { Ipv4Cidr } from './ipv4-cidr';
export * from './ipv4-address';
export * from './ipv4-cidr';
export * from './ipv4-types';
export * from './ipv4-errors';
export declare namespace ipv4 {
/**
* The maximum possible value for an IPv4 address.
*/
const MAX_SIZE = 4294967295;
/**
* The minimum possible value for an IPv4 address.
*/
const MIN_SIZE = 0;
/**
* The maximum CIDR range for IPv4 addresses.
*/
const MAX_RANGE = 32;
/**
* The minimum CIDR range for IPv4 addresses.
*/
const MIN_RANGE = 0;
/**
* Creates a new Ipv4Address instance from the given literal.
* Valid formats include string, number, or octet array.
*
* @example Creating addresses
* ```ts
* import { ipv4 } from 'cidr-block';
*
* const addr1 = ipv4.address("192.168.1.1");
* const addr2 = ipv4.address(3232235777);
* const addr3 = ipv4.address([192, 168, 1, 1]);
* ```
*
* @example Converting between formats
* ```ts
* import { ipv4 } from 'cidr-block';
*
* const addr = ipv4.address("192.168.1.1");
* addr.toString(); // "192.168.1.1"
* addr.toNumber(); // 3232235777
* addr.octets(); // [192, 168, 1, 1]
* addr.toBinaryString(); // "11000000.10101000.00000001.00000001"
* ```
*
* @example Comparing addresses
* ```ts
* import { ipv4 } from 'cidr-block';
*
* const addr = ipv4.address("192.168.1.1");
* addr.equals("192.168.1.1"); // true
* addr.isGreaterThan("192.168.1.0"); // true
* addr.isLessThan("192.168.1.2"); // true
* ```
*
* @example Navigating sequential addresses
* ```ts
* import { ipv4 } from 'cidr-block';
*
* const addr = ipv4.address("192.168.1.1");
* addr.nextAddress()?.toString(); // "192.168.1.2"
* addr.previousAddress()?.toString(); // "192.168.1.0"
* ```
*
* @example Checking address types
* ```ts
* import { ipv4 } from 'cidr-block';
*
* ipv4.address("127.0.0.1").isLoopbackAddress(); // true
* ipv4.address("10.0.0.1").isPrivateAddress(); // true
* ipv4.address("169.254.1.1").isLocalLinkAddress(); // true
* ipv4.address("224.0.0.1").isMulticastAddress(); // true
* ```
*
* @param ip - The IPv4 address in string, number, or octet array format.
* @returns A new Ipv4Address instance.
* @throws {InvalidIpv4AddressError} If the input is not a valid IPv4 address.
*/
function address(ip: Ipv4AddressLiteral): Ipv4Address;
/**
* Creates a new Ipv4Cidr instance from the given literal.
* Valid formats include string, object, or tuple.
*
* @example Creating CIDR blocks
* ```ts
* import { ipv4 } from 'cidr-block';
*
* 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.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"
* ```
*
* @param cidr - The IPv4 CIDR in string, object, or tuple format.
* @returns A new Ipv4Cidr instance.
* @throws {InvalidIpv4CidrError} If the input is not a valid IPv4 CIDR.
*/
function cidr(cidr: Ipv4CidrLiteral): Ipv4Cidr;
/**
* Validates whether the given input is a valid IPv4 address.
*
* @example
* ```ts
* import { ipv4 } from 'cidr-block';
*
* ipv4.isValidAddress("192.168.1.1"); // true
* ipv4.isValidAddress("256.0.0.1"); // false (octet out of range)
* ipv4.isValidAddress(3232235777); // true
* ipv4.isValidAddress([192, 168, 1, 1]); // true
* ipv4.isValidAddress("invalid"); // false
* ```
*
* @param ip - The IPv4 address to validate, which can be in string, number, or octet array format.
* @returns True if the input is a valid IPv4 address; otherwise, false.
*/
function isValidAddress(ip: Ipv4AddressLiteral): boolean;
/**
* Validates whether the given input is a valid IPv4 CIDR.
*
* @example
* ```ts
* import { ipv4 } from 'cidr-block';
*
* ipv4.isValidCIDR("192.168.0.0/24"); // true
* ipv4.isValidCIDR("192.168.0.0/33"); // false (range out of bounds)
* ipv4.isValidCIDR({ address: "10.0.0.0", range: 8 }); // true
* ipv4.isValidCIDR([[172, 16, 0, 0], 12]); // true
* ipv4.isValidCIDR("invalid/24"); // false
* ```
*
* @param cidr - The IPv4 CIDR to validate, which can be in string, object, or tuple format.
* @returns True if the input is a valid IPv4 CIDR; otherwise, false.
*/
function isValidCIDR(cidr: Ipv4CidrLiteral): boolean;
/**
* Parses the given IPv4 address into its octet representation.
*
* @example
* ```ts
* import { ipv4 } from 'cidr-block';
*
* ipv4.parseOctets("192.168.1.1"); // [192, 168, 1, 1]
* ipv4.parseOctets(3232235777); // [192, 168, 1, 1]
* ipv4.parseOctets([10, 0, 0, 1]); // [10, 0, 0, 1]
* ```
*
* @param ip - The IPv4 address to parse, which can be in string, number, or octet array format.
* @returns {Ipv4AddressOctets} An array of four numbers representing the octets of the IPv4 address.
* @throws {InvalidIpv4AddressError} If the input is not a valid IPv4 address.
*/
function parseOctets(ip: Ipv4AddressLiteral): Ipv4AddressOctets;
}
//# sourceMappingURL=ipv4.d.ts.map