Aktueller Stand

This commit is contained in:
2026-01-22 19:05:45 +01:00
parent 85dee61a4d
commit e280e4eadb
1967 changed files with 397327 additions and 74093 deletions

View File

@@ -1,4 +1,6 @@
# ipaddr.js — an IPv6 and IPv4 address manipulation library [![Build Status](https://travis-ci.org/whitequark/ipaddr.js.svg)](https://travis-ci.org/whitequark/ipaddr.js)
# ipaddr.js — an IPv6 and IPv4 address manipulation library
[![Build Status](https://github.com/whitequark/ipaddr.js/workflows/CI%20Tests/badge.svg)](https://github.com/whitequark/ipaddr.js/actions?query=workflow%3A%22CI+Tests%22)
ipaddr.js is a small (1.9K minified and gzipped) library for manipulating
IP addresses in JavaScript environments. It runs on both CommonJS runtimes
@@ -19,25 +21,34 @@ or
`bower install ipaddr.js`
## Older Node support
Use 2.x release for nodejs versions 10+.
Use the 1.x release for versions of nodejs older than 10.
## API
ipaddr.js defines one object in the global scope: `ipaddr`. In CommonJS,
it is exported from the module:
```js
var ipaddr = require('ipaddr.js');
const ipaddr = require('ipaddr.js');
```
The API consists of several global methods and two classes: ipaddr.IPv6 and ipaddr.IPv4.
### Global methods
There are three global methods defined: `ipaddr.isValid`, `ipaddr.parse` and
`ipaddr.process`. All of them receive a string as a single parameter.
There are four global methods defined: `ipaddr.isValid`, `ipaddr.isValidCIDR`,
`ipaddr.parse`, and `ipaddr.process`. All of them receive a string as a single
parameter.
The `ipaddr.isValid` method returns `true` if the address is a valid IPv4 or
IPv6 address, and `false` otherwise. It does not throw any exceptions.
The `ipaddr.isValidCIDR` method returns `true` if the address is a valid IPv4 or
IPv6 address in CIDR notation, and `false` otherwise. It does not throw any exceptions.
The `ipaddr.parse` method returns an object representing the IP address,
or throws an `Error` if the passed string is not a valid representation of an
IP address.
@@ -67,40 +78,34 @@ Note that this method:
* returns a compact representation (when it is applicable)
A `match(range, bits)` method can be used to check if the address falls into a
certain CIDR range.
Note that an address can be (obviously) matched only against an address of the same type.
certain CIDR range. Note that an address can be (obviously) matched only against an address of the same type.
For example:
```js
var addr = ipaddr.parse("2001:db8:1234::1");
var range = ipaddr.parse("2001:db8::");
const addr = ipaddr.parse('2001:db8:1234::1');
const range = ipaddr.parse('2001:db8::');
addr.match(range, 32); // => true
```
Alternatively, `match` can also be called as `match([range, bits])`. In this way,
it can be used together with the `parseCIDR(string)` method, which parses an IP
address together with a CIDR range.
Alternatively, `match` can also be called as `match([range, bits])`. In this way, it can be used together with the `parseCIDR(string)` method, which parses an IP address together with a CIDR range.
For example:
```js
var addr = ipaddr.parse("2001:db8:1234::1");
const addr = ipaddr.parse('2001:db8:1234::1');
addr.match(ipaddr.parseCIDR("2001:db8::/32")); // => true
addr.match(ipaddr.parseCIDR('2001:db8::/32')); // => true
```
A `range()` method returns one of predefined names for several special ranges defined
by IP protocols. The exact names (and their respective CIDR ranges) can be looked up
in the source: [IPv6 ranges] and [IPv4 ranges]. Some common ones include `"unicast"`
(the default one) and `"reserved"`.
A `range()` method returns one of predefined names for several special ranges defined by IP protocols. The exact names (and their respective CIDR ranges) can be looked up in the source: [IPv6 ranges] and [IPv4 ranges]. Some common ones include `"unicast"` (the default one) and `"reserved"`.
You can match against your own range list by using
`ipaddr.subnetMatch(address, rangeList, defaultName)` method. It can work with a mix of IPv6 or IPv4 addresses, and accepts a name-to-subnet map as the range list. For example:
```js
var rangeList = {
const rangeList = {
documentationOnly: [ ipaddr.parse('2001:db8::'), 32 ],
tunnelProviders: [
[ ipaddr.parse('2001:470::'), 32 ], // he.net
@@ -110,38 +115,33 @@ var rangeList = {
ipaddr.subnetMatch(ipaddr.parse('2001:470:8:66::1'), rangeList, 'unknown'); // => "tunnelProviders"
```
The addresses can be converted to their byte representation with `toByteArray()`.
(Actually, JavaScript mostly does not know about byte buffers. They are emulated with
arrays of numbers, each in range of 0..255.)
The addresses can be converted to their byte representation with `toByteArray()`. (Actually, JavaScript mostly does not know about byte buffers. They are emulated with arrays of numbers, each in range of 0..255.)
```js
var bytes = ipaddr.parse('2a00:1450:8007::68').toByteArray(); // ipv6.google.com
const bytes = ipaddr.parse('2a00:1450:8007::68').toByteArray(); // ipv6.google.com
bytes // => [42, 0x00, 0x14, 0x50, 0x80, 0x07, 0x00, <zeroes...>, 0x00, 0x68 ]
```
The `ipaddr.IPv4` and `ipaddr.IPv6` objects have some methods defined, too. All of them
have the same interface for both protocols, and are similar to global methods.
The `ipaddr.IPv4` and `ipaddr.IPv6` objects have some methods defined, too. All of them have the same interface for both protocols, and are similar to global methods.
`ipaddr.IPvX.isValid(string)` can be used to check if the string is a valid address
for particular protocol, and `ipaddr.IPvX.parse(string)` is the error-throwing parser.
`ipaddr.IPvX.isValid(string)` can be used to check if the string is a valid address for particular protocol, and `ipaddr.IPvX.parse(string)` is the error-throwing parser.
`ipaddr.IPvX.isValid(string)` uses the same format for parsing as the POSIX `inet_ntoa` function, which accepts unusual formats like `0xc0.168.1.1` or `0x10000000`. The function `ipaddr.IPv4.isValidFourPartDecimal(string)` validates the IPv4 address and also ensures that it is written in four-part decimal format.
`ipaddr.IPv4.isValidCIDRFourPartDecimal(string)` validates an IPv4 address in CIDR notation and also ensures that its address portion is written in four-part decimal format.
[IPv6 ranges]: https://github.com/whitequark/ipaddr.js/blob/master/src/ipaddr.coffee#L186
[IPv4 ranges]: https://github.com/whitequark/ipaddr.js/blob/master/src/ipaddr.coffee#L71
[IPv6 ranges]: https://github.com/whitequark/ipaddr.js/blob/master/lib/ipaddr.js#L530
[IPv4 ranges]: https://github.com/whitequark/ipaddr.js/blob/master/lib/ipaddr.js#L182
#### IPv6 properties
Sometimes you will want to convert IPv6 not to a compact string representation (with
the `::` substitution); the `toNormalizedString()` method will return an address where
all zeroes are explicit.
Sometimes you will want to convert IPv6 not to a compact string representation (with the `::` substitution); the `toNormalizedString()` method will return an address where all zeroes are explicit.
For example:
```js
var addr = ipaddr.parse("2001:0db8::0001");
addr.toString(); // => "2001:db8::1"
addr.toNormalizedString(); // => "2001:db8:0:0:0:0:0:1"
const addr = ipaddr.parse('2001:0db8::0001');
addr.toString(); // => '2001:db8::1'
addr.toNormalizedString(); // => '2001:db8:0:0:0:0:0:1'
```
The `isIPv4MappedAddress()` method will return `true` if this address is an IPv4-mapped
@@ -150,14 +150,14 @@ one, and `toIPv4Address()` will return an IPv4 object address.
To access the underlying binary representation of the address, use `addr.parts`.
```js
var addr = ipaddr.parse("2001:db8:10::1234:DEAD");
const addr = ipaddr.parse('2001:db8:10::1234:DEAD');
addr.parts // => [0x2001, 0xdb8, 0x10, 0, 0, 0, 0x1234, 0xdead]
```
A IPv6 zone index can be accessed via `addr.zoneId`:
```js
var addr = ipaddr.parse("2001:db8::%eth0");
const addr = ipaddr.parse('2001:db8::%eth0');
addr.zoneId // => 'eth0'
```
@@ -168,7 +168,7 @@ addr.zoneId // => 'eth0'
To access the underlying representation of the address, use `addr.octets`.
```js
var addr = ipaddr.parse("192.168.1.1");
const addr = ipaddr.parse('192.168.1.1');
addr.octets // => [192, 168, 1, 1]
```
@@ -183,17 +183,17 @@ ipaddr.IPv4.parse('255.192.164.0').prefixLengthFromSubnetMask() == null
`subnetMaskFromPrefixLength()` will return an IPv4 netmask for a valid CIDR prefix length.
```js
ipaddr.IPv4.subnetMaskFromPrefixLength(24) == "255.255.255.0"
ipaddr.IPv4.subnetMaskFromPrefixLength(29) == "255.255.255.248"
ipaddr.IPv4.subnetMaskFromPrefixLength(24) == '255.255.255.0'
ipaddr.IPv4.subnetMaskFromPrefixLength(29) == '255.255.255.248'
```
`broadcastAddressFromCIDR()` will return the broadcast address for a given IPv4 interface and netmask in CIDR notation.
```js
ipaddr.IPv4.broadcastAddressFromCIDR("172.0.0.1/24") == "172.0.0.255"
ipaddr.IPv4.broadcastAddressFromCIDR('172.0.0.1/24') == '172.0.0.255'
```
`networkAddressFromCIDR()` will return the network address for a given IPv4 interface and netmask in CIDR notation.
```js
ipaddr.IPv4.networkAddressFromCIDR("172.0.0.1/24") == "172.0.0.0"
ipaddr.IPv4.networkAddressFromCIDR('172.0.0.1/24') == '172.0.0.0'
```
#### Conversion
@@ -206,28 +206,28 @@ while for IPv6 it has to be an array of sixteen 8-bit values.
For example:
```js
var addr = ipaddr.fromByteArray([0x7f, 0, 0, 1]);
addr.toString(); // => "127.0.0.1"
const addr = ipaddr.fromByteArray([0x7f, 0, 0, 1]);
addr.toString(); // => '127.0.0.1'
```
or
```js
var addr = ipaddr.fromByteArray([0x20, 1, 0xd, 0xb8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1])
addr.toString(); // => "2001:db8::1"
const addr = ipaddr.fromByteArray([0x20, 1, 0xd, 0xb8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1])
addr.toString(); // => '2001:db8::1'
```
Both objects also offer a `toByteArray()` method, which returns an array in network byte order (MSB).
For example:
```js
var addr = ipaddr.parse("127.0.0.1");
const addr = ipaddr.parse('127.0.0.1');
addr.toByteArray(); // => [0x7f, 0, 0, 1]
```
or
```js
var addr = ipaddr.parse("2001:db8::1");
const addr = ipaddr.parse('2001:db8::1');
addr.toByteArray(); // => [0x20, 1, 0xd, 0xb8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1]
```

File diff suppressed because one or more lines are too long

File diff suppressed because it is too large Load Diff

View File

@@ -1,6 +1,7 @@
declare module "ipaddr.js" {
type IPv4Range = 'unicast' | 'unspecified' | 'broadcast' | 'multicast' | 'linkLocal' | 'loopback' | 'carrierGradeNat' | 'private' | 'reserved';
type IPv6Range = 'unicast' | 'unspecified' | 'linkLocal' | 'multicast' | 'loopback' | 'uniqueLocal' | 'ipv4Mapped' | 'rfc6145' | 'rfc6052' | '6to4' | 'teredo' | 'reserved';
type IPvXRangeDefaults = 'unicast' | 'unspecified' | 'multicast' | 'linkLocal' | 'loopback' | 'reserved' | 'benchmarking' | 'amt';
type IPv4Range = IPvXRangeDefaults | 'broadcast' | 'carrierGradeNat' | 'private' | 'as112';
type IPv6Range = IPvXRangeDefaults | 'uniqueLocal' | 'ipv4Mapped' | 'rfc6145' | 'rfc6052' | '6to4' | 'teredo' | 'as112v6' | 'orchid2' | 'droneRemoteIdProtocolEntityTags';
interface RangeList<T> {
[name: string]: [T, number] | [T, number][];
@@ -15,19 +16,21 @@ declare module "ipaddr.js" {
}
namespace Address {
export function isValid(addr: string): boolean;
export function fromByteArray(bytes: number[]): IPv4 | IPv6;
export function isValid(addr: string): boolean;
export function isValidCIDR(addr: string): boolean;
export function parse(addr: string): IPv4 | IPv6;
export function parseCIDR(mask: string): [IPv4 | IPv6, number];
export function process(addr: string): IPv4 | IPv6;
export function subnetMatch(addr: IPv4, rangeList: RangeList<IPv4>, defaultName?: string): string;
export function subnetMatch(addr: IPv6, rangeList: RangeList<IPv6>, defaultName?: string): string;
export function subnetMatch(addr: IPv4 | IPv6, rangeList: RangeList<IPv4 | IPv6>, defaultName?: string): string;
export class IPv4 extends IP {
static broadcastAddressFromCIDR(addr: string): IPv4;
static isIPv4(addr: string): boolean;
static isValidFourPartDecimal(addr: string): boolean;
static isValid(addr: string): boolean;
static isValidCIDR(addr: string): boolean;
static isValidFourPartDecimal(addr: string): boolean;
static isValidCIDRFourPartDecimal(addr: string): boolean;
static networkAddressFromCIDR(addr: string): IPv4;
static parse(addr: string): IPv4;
static parseCIDR(addr: string): [IPv4, number];
@@ -36,8 +39,7 @@ declare module "ipaddr.js" {
octets: number[]
kind(): 'ipv4';
match(addr: IPv4, bits: number): boolean;
match(mask: [IPv4, number]): boolean;
match(what: IPv4 | IPv6 | [IPv4 | IPv6, number], bits?: number): boolean;
range(): IPv4Range;
subnetMatch(rangeList: RangeList<IPv4>, defaultName?: string): string;
toIPv4MappedAddress(): IPv6;
@@ -47,6 +49,8 @@ declare module "ipaddr.js" {
static broadcastAddressFromCIDR(addr: string): IPv6;
static isIPv6(addr: string): boolean;
static isValid(addr: string): boolean;
static isValidCIDR(addr: string): boolean;
static networkAddressFromCIDR(addr: string): IPv6;
static parse(addr: string): IPv6;
static parseCIDR(addr: string): [IPv6, number];
static subnetMaskFromPrefixLength(prefix: number): IPv6;
@@ -56,11 +60,11 @@ declare module "ipaddr.js" {
isIPv4MappedAddress(): boolean;
kind(): 'ipv6';
match(addr: IPv6, bits: number): boolean;
match(mask: [IPv6, number]): boolean;
match(what: IPv4 | IPv6 | [IPv4 | IPv6, number], bits?: number): boolean;
range(): IPv6Range;
subnetMatch(rangeList: RangeList<IPv6>, defaultName?: string): string;
toIPv4Address(): IPv4;
toRFC5952String(): string;
}
}

View File

@@ -1,23 +1,24 @@
{
"name": "ipaddr.js",
"description": "A library for manipulating IPv4 and IPv6 addresses in JavaScript.",
"version": "1.9.1",
"version": "2.3.0",
"author": "whitequark <whitequark@whitequark.org>",
"directories": {
"lib": "./lib"
},
"dependencies": {},
"devDependencies": {
"coffee-script": "~1.12.6",
"nodeunit": "^0.11.3",
"uglify-js": "~3.0.19"
"eslint": "^9.19.0",
"uglify-es": "*"
},
"scripts": {
"test": "cake build test"
"lint": "npx eslint lib",
"lintfix": "npx eslint --fix lib test",
"build": "npx uglifyjs --compress --mangle --wrap=window -o ipaddr.min.js lib/ipaddr.js",
"test": "node --test"
},
"files": [
"lib/",
"LICENSE",
"lib",
"ipaddr.min.js"
],
"keywords": [
@@ -28,7 +29,7 @@
"repository": "git://github.com/whitequark/ipaddr.js",
"main": "./lib/ipaddr.js",
"engines": {
"node": ">= 0.10"
"node": ">= 10"
},
"license": "MIT",
"types": "./lib/ipaddr.js.d.ts"