Class IP

The IP class. Unlike the static IPUtil class, this class provides several instance methods that can be used to perform validations on the same IP or CIDR address multiple times.

To initialize a new instance, use IP.newFromText or IP.newFromRange:

const ip = IP.newFromText('fd12:3456:789a:1::1');
if (!ip) return;
console.log(ip.stringify()); // fd12:3456:789a:1:0:0:0:1

Hierarchy

  • IPBase
    • IP

Constructors

constructor

Properties

bitLen first isCidr last

Accessors

version

Methods

abbreviate contains containsAll containsAny equals equalsAll equalsAny getBitLength getProperties getRange getVersion isCIDR isIPv4 isIPv4CIDR isIPv6 isIPv6CIDR isInAllRanges isInAnyRange isInRange lengthen sanitize stringify toString checkEquality clean compareRanges getRangeObject newFromRange newFromText parse parseAndStringify parseRange stringify

Constructors

Protectedconstructor

Properties

Protected ReadonlybitLen

bitLen: number

Protected Readonlyfirst

first: number[]

Protected ReadonlyisCidr

isCidr: boolean

Protected Readonlylast

last: number[]

Accessors

version

  • get version(): 4 | 6

  • Returns the IP version as a number.

    Returns 4 | 6

    The IP version: 4 for IPv4 or 6 for IPv6.

Methods

abbreviate

  • abbreviate(capitalize?): string

  • Returns the stringified form of this IP or CIDR block in an abbreviated format.

    This is a shorthand method of stringify with the mode option set to 'short'.

    Parameters

    • Optionalcapitalize: boolean = false

      Whether to capitalize the output.

    Returns string

    A properly formatted string representation of the IP or CIDR.

contains

  • contains(ipStr): null | boolean

  • Checks whether the CIDR range associated with this instance contains the specified IP address.

    Parameters

    • ipStr: string | IP

      The target IP address to check.

    Returns null | boolean

    true if the CIDR range contains ipStr, false if not, or null if ipStr is invalid.

containsAll

  • containsAll(ipArr): null | boolean

  • Checks whether the CIDR range associated with this instance contains all of the IP addresses in the array.

    Parameters

    • ipArr: (string | IP)[]

      An array of IP or CIDR strings or IP instances to test.

    Returns null | boolean

    true if all IPs are contained, false if any are not, or null if ipArr is not an array or an empty array.

containsAny

  • containsAny(ipArr): number

  • Checks whether the CIDR range associated with this instance contains any of the IP addresses in the array.

    Parameters

    • ipArr: (string | IP)[]

      An array of IP or CIDR strings or IP instances to test.

    Returns number

    The index of the first match in ipArr, or -1 if none match.

equals

  • equals(ipStr): null | boolean

  • Checks whether the IP address associated with this intance is equal to a given IP address.

    Parameters

    • ipStr: string | IP

      The IP address to compare.

    Returns null | boolean

    true if the IPs are equal, false if not, or null if ipStr is invalid.

equalsAll

  • equalsAll(ipArr): null | boolean

  • Checks whether the IP address associated with this intance is equal to all addresses in a given array.

    Parameters

    • ipArr: (string | IP)[]

      An array of IP or CIDR strings or IP instances to compare against.

    Returns null | boolean

    true if all addresses are equal to this IP instance, false otherwise, or null if ipArr is not an array or an empty array.

equalsAny

  • equalsAny(ipArr): number

  • Checks whether the IP address associated with this intance is equal to any address in a given array.

    Parameters

    • ipArr: (string | IP)[]

      An array of IP or CIDR strings or IP instances to check against.

    Returns number

    The index of the first match in ipArr, or -1 if none match.

getBitLength

  • getBitLength(): number

  • Gets the bit length of the current instance.

    This always returns a number between 0-32 for IPv4 and 0-128 for IPv6. To check whether the current instance represents a CIDR address, use IP.isCIDR.

    Returns number

    The bit length as a number.

getProperties

  • getProperties(): RangeObject

  • Gets a copy of the internal CIDR-related properties.

    Returns RangeObject

    An object containing first, last, bitLen, and isCidr.

getRange

  • getRange(getInstance?, options?): {
        bitLen: number;
        cidr: string;
        first: string;
        last: string;
    }

  • Gets range information of the IP instance.

    Parameters

    • OptionalgetInstance: false

      Whether to get the start and end IP addresses as IP instances.

    • Optionaloptions: StringifyOptions

      Optional formatting options for the cidr, first, and last properties.

    Returns {
        bitLen: number;
        cidr: string;
        first: string;
        last: string;
    }

    • bitLen: number
    • cidr: string
    • first: string
    • last: string
  • getRange(getInstance, options?): {
        bitLen: number;
        cidr: string;
        first: IP;
        last: IP;
    }

  • Gets range information of the IP instance.

    Parameters

    • getInstance: true

      Whether to get the start and end IP addresses as IP instances.

    • Optionaloptions: StringifyOptions

      Optional formatting options for the cidr property.

    Returns {
        bitLen: number;
        cidr: string;
        first: IP;
        last: IP;
    }

    • bitLen: number
    • cidr: string
    • first: IP
    • last: IP

getVersion

  • getVersion(): string

  • Gets the IP version as a string in the format IPv4 or IPv6.

    Returns string

    A string representation of the IP version.

isCIDR

  • isCIDR(): boolean

  • Checks whether the current instance represents a CIDR address.

    Returns boolean

    A boolean indicating whether the current instance represents a CIDR address.

isIPv4

  • isIPv4(allowCidr?): boolean

  • Checks whether the current instance represents an IPv4 address.

    Parameters

    • OptionalallowCidr: boolean = false

      Whether to allow a CIDR address.

    Returns boolean

    A boolean indicating whether the current instance represents an IPv4 address.

isIPv4CIDR

  • isIPv4CIDR(): boolean

  • Checks whether the current instance represents an IPv4 CIDR address.

    Returns boolean

    A boolean indicating whether the current instance represents an IPv4 CIDR address.

isIPv6

  • isIPv6(allowCidr?): boolean

  • Checks whether the current instance represents an IPv6 address.

    Parameters

    • OptionalallowCidr: boolean = false

      Whether to allow a CIDR address.

    Returns boolean

    A boolean indicating whether the current instance represents an IPv6 address.

isIPv6CIDR

  • isIPv6CIDR(): boolean

  • Checks whether the current instance represents an IPv6 CIDR address.

    Returns boolean

    A boolean indicating whether the current instance represents an IPv6 CIDR address.

isInAllRanges

  • isInAllRanges(cidrArr): null | boolean

  • Checks whether the IP address associated with this instance is within all CIDR ranges in the array.

    Parameters

    • cidrArr: (string | IP)[]

      An array of CIDR strings or IP instances to check against.

    Returns null | boolean

    true if the IP is within all CIDRs, false if not, or null if cidrArr is not an array or an empty array.

isInAnyRange

  • isInAnyRange(cidrArr): number

  • Checks whether the IP address associated with this instance is within any of the CIDR ranges in the array.

    Parameters

    • cidrArr: (string | IP)[]

      An array of CIDR strings or IP instances to check against.

    Returns number

    The index of the first matching CIDR in the array, or -1 if none match.

isInRange

  • isInRange(cidrStr): null | boolean

  • Checks whether the IP address associated with this instance is within the CIDR range of another.

    Parameters

    • cidrStr: string | IP

      The CIDR string or IP instance representing the range.

    Returns null | boolean

    A boolean indicating whether the IP address is within the CIDR range, or null if cidrStr is invalid.

lengthen

  • lengthen(capitalize?): string

  • Returns the stringified form of this IP or CIDR block in a lengthened format.

    This is a shorthand method of stringify with the mode option set to 'long'.

    Parameters

    • Optionalcapitalize: boolean = false

      Whether to capitalize the output.

    Returns string

    A properly formatted string representation of the IP or CIDR.

sanitize

  • sanitize(capitalize?): string

  • Returns the stringified form of this IP or CIDR block in a sanitized format.

    This is a shorthand method of stringify with the mode option unset.

    Parameters

    • Optionalcapitalize: boolean = false

      Whether to capitalize the output.

    Returns string

    A properly formatted string representation of the IP or CIDR.

stringify

  • stringify(options?): string

  • Returns the stringified form of this IP or CIDR block.

    Parameters

    • Optionaloptions: StringifyOptions = {}

      Optional formatting options. If omitted, a default "sanitized" format will be used.

    Returns string

    A properly formatted string representation of the IP or CIDR.

    Note: If the instance was initialized from an imprecise CIDR string, the output will reflect the corrected internal format.

    const ip = IP.newFromText('fd12:3456:789a:1::1/64');
    ip.stringify(); // fd12:3456:789a:1:0:0:0:0/64

toString

  • toString(): string

  • Alias for IP.stringify with default options.

    Returns string

    A stringified representation of the IP.

Protected StaticcheckEquality

  • checkEquality(ipObj, ipStr): null | boolean
  • Protected

    Checks if two IP addresses are equal.

    Parameters

    • ipObj: RangeObject

      Range object of the first IP.

    • ipStr: string | IP

      IP or CIDR string, or IP instance.

    Returns null | boolean

    null if the second input is invalid.

Staticclean

  • clean(str): string

  • Returns a trimmed string with all Unicode bidirectional characters removed.

    Unicode bidirectional characters are special invisible characters that can slip into cut-and-pasted strings, which are shown as red dots in WikiEditor. They can cause issues when parsing IP addresses.

    Parameters

    • str: string

    Returns string

    See

    MediaWikiTitleCodec::splitTitleString in MediaWiki core

Protected StaticcompareRanges

  • compareRanges(ip1, ip2, comparator): null | boolean
  • Protected

    Compares two IP address ranges to check for inclusion.

    Parameters

    • ip1: RangeObject

      Range object of the first IP.

    • ip2: string | IP

      IP string or IP instance to compare against.

    • comparator: "<" | ">"

      Use < if ip2 should contain ip1, or > if ip1 should contain ip2.

    Returns null | boolean

    null if ip2 is not a valid IP address.

Protected StaticgetRangeObject

  • getRangeObject(ip): null | RangeObject
  • Protected

    Parses an IP string or instance into a range object.

    Parameters

    • ip: string | IP

      An IP/CIDR string or IP instance.

    Returns null | RangeObject

    Range object, or null if the input is not a valid IP.

StaticnewFromRange

  • newFromRange(ipStr, range): null | IP

  • Initializes an IP instance from a string and a range (aka. a bit length).

    Parameters

    • ipStr: string

      An IP- or CIDR-representing string. If a CIDR string is passed, the /XX part will be overridden by range.

    • range: number

      The desired CIDR bit length (0–32 for IPv4, 0–128 for IPv6).

    Returns null | IP

    A new IP instance if parsing succeeds, or null if the input or range is invalid.

    Throws

    If range is not a number.

StaticnewFromText

  • newFromText(ipStr): null | IP

  • Initializes an IP instance from a string.

    Parameters

    • ipStr: string

      An IP- or CIDR-representing string.

    Returns null | IP

    A new IP instance if parsing succeeds, or null if the input is invalid.

Protected Staticparse

  • parse(ipStr, bitLen?): null | Parsed
  • Protected

    Parses a string potentially representing an IP or CIDR address.

    Parameters

    • ipStr: string

      The string to parse.

    • OptionalbitLen: number

      Optional bit length for CIDR parsing.

    Returns null | Parsed

    A parsed object, or null if:

    • ipStr is not a string.
    • It does not represent a valid IP address.
    • It contains an invalid CIDR bit length.

Protected StaticparseAndStringify

  • parseAndStringify(ipStr, options, conditionPredicate?): null | string
  • Protected

    Parses and stringifies an IP string with optional filtering.

    Parameters

    • ipStr: string

      IP or CIDR string to parse.

    • options: StringifyOptions

      Options for formatting.

    • OptionalconditionPredicate: ConditionPredicate

      A predicate to filter addresses by version and CIDR.

    Returns null | string

    null if:

    • The input string does not represent an IP address.
    • The parsed IP address does not meet the conditions specified by conditionPredicate

Protected StaticparseRange

  • parseRange(parts, bitLen): RangeObject
  • Protected

    Returns the first and last IPs in the given range.

    Parameters

    • parts: number[]

      Decimal parts of the IP address.

    • bitLen: null | number

      Optional CIDR bit length.

    Returns RangeObject

Protected Staticstringify

  • stringify(decimals, suffix, options?): string
  • Protected

    Converts an array of decimal IP parts into a string.

    Parameters

    • decimals: number[]

      Array of decimal parts.

    • suffix: string

      Suffix to append (e.g., /24).

    • Optionaloptions: StringifyOptions = {}

    Returns string

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods