0
# Address Validation
1

2
Functions for validating IP address formats and classifying addresses as private, public, or loopback with support for both IPv4 and IPv6 addresses.
3

4
## Capabilities
5

6
### Format Validation
7

8
#### isV4Format
9

10
Checks if a string is in valid IPv4 format using regex validation.
11

12
```javascript { .api }
13
/**
14
 * Checks if string is valid IPv4 format
15
 * @param {string} ip - IP address string to validate
16
 * @returns {boolean} True if valid IPv4 format, false otherwise
17
 */
18
function isV4Format(ip);
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
const ip = require('ip');
25

26
console.log(ip.isV4Format('127.0.0.1')); // true
27
console.log(ip.isV4Format('192.168.1.1')); // true
28
console.log(ip.isV4Format('255.255.255.255')); // true
29
console.log(ip.isV4Format('256.1.1.1')); // false (invalid octet)
30
console.log(ip.isV4Format('::1')); // false (IPv6)
31
console.log(ip.isV4Format('not-an-ip')); // false
32
```
33

34
#### isV6Format
35

36
Checks if a string is in valid IPv6 format using regex validation.
37

38
```javascript { .api }
39
/**
40
 * Checks if string is valid IPv6 format
41
 * @param {string} ip - IP address string to validate  
42
 * @returns {boolean} True if valid IPv6 format, false otherwise
43
 */
44
function isV6Format(ip);
45
```
46

47
**Usage Examples:**
48

49
```javascript
50
const ip = require('ip');
51

52
console.log(ip.isV6Format('::1')); // true
53
console.log(ip.isV6Format('::ffff:127.0.0.1')); // true (IPv4-mapped)
54
console.log(ip.isV6Format('2001:db8::1')); // true
55
console.log(ip.isV6Format('fe80::1')); // true
56
console.log(ip.isV6Format('127.0.0.1')); // false (IPv4)
57
console.log(ip.isV6Format('invalid')); // false
58
```
59

60
### Address Comparison
61

62
#### isEqual
63

64
Compares two IP addresses for equality, supporting IPv4, IPv6, and mixed comparisons with IPv6-mapped IPv4 addresses.
65

66
```javascript { .api }
67
/**
68
 * Compares two IP addresses for equality
69
 * @param {string} a - First IP address
70
 * @param {string} b - Second IP address  
71
 * @returns {boolean} True if addresses are equal, false otherwise
72
 */
73
function isEqual(a, b);
74
```
75

76
**Usage Examples:**
77

78
```javascript
79
const ip = require('ip');
80

81
// IPv4 comparisons
82
console.log(ip.isEqual('127.0.0.1', '127.0.0.1')); // true
83
console.log(ip.isEqual('127.0.0.1', '127.0.0.2')); // false
84

85
// IPv6 comparisons
86
console.log(ip.isEqual('::1', '::1')); // true
87
console.log(ip.isEqual('::1', '::2')); // false
88

89
// Mixed IPv4/IPv6 comparisons (IPv6-mapped IPv4)
90
console.log(ip.isEqual('127.0.0.1', '::ffff:127.0.0.1')); // true
91
console.log(ip.isEqual('127.0.0.1', '::7f00:1')); // true
92
console.log(ip.isEqual('127.0.0.1', '::ffaf:7f00:1')); // false
93
```
94

95
### Address Classification
96

97
#### isPrivate
98

99
Checks if an IP address is in a private address range, including loopback addresses.
100

101
```javascript { .api }
102
/**
103
 * Checks if IP address is in private range
104
 * @param {string} addr - IP address to check
105
 * @returns {boolean} True if address is private, false otherwise
106
 * @throws {Error} Throws error for invalid IPv4 address
107
 */
108
function isPrivate(addr);
109
```
110

111
**Supported Private Ranges:**
112
- IPv4: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16 (link-local)
113
- IPv6: fc00::/7 (unique local), fe80::/10 (link-local)
114
- Loopback: 127.0.0.0/8 (IPv4), ::1, fe80::1 (IPv6)
115

116
**Usage Examples:**
117

118
```javascript
119
const ip = require('ip');
120

121
// IPv4 private ranges
122
console.log(ip.isPrivate('10.0.0.1')); // true (10.x.x.x)
123
console.log(ip.isPrivate('172.16.0.1')); // true (172.16-31.x.x)
124
console.log(ip.isPrivate('192.168.1.1')); // true (192.168.x.x)
125
console.log(ip.isPrivate('169.254.1.1')); // true (link-local)
126
console.log(ip.isPrivate('127.0.0.1')); // true (loopback)
127

128
// IPv4 public addresses
129
console.log(ip.isPrivate('8.8.8.8')); // false
130
console.log(ip.isPrivate('1.1.1.1')); // false
131

132
// IPv6 addresses
133
console.log(ip.isPrivate('::1')); // true (loopback)
134
console.log(ip.isPrivate('fe80::1')); // true (link-local)
135
console.log(ip.isPrivate('fd12:3456:789a:1::1')); // true (unique local)
136

137
// IPv6-mapped IPv4
138
console.log(ip.isPrivate('::ffff:192.168.1.1')); // true
139

140
// Special formats (hex, octal)
141
console.log(ip.isPrivate('0x7f.1')); // true (127.0.0.1 in hex)
142
```
143

144
#### isPublic
145

146
Checks if an IP address is public (not private). This is the logical inverse of `isPrivate`.
147

148
```javascript { .api }
149
/**
150
 * Checks if IP address is public (not private)
151
 * @param {string} addr - IP address to check
152
 * @returns {boolean} True if address is public, false otherwise
153
 */
154
function isPublic(addr);
155
```
156

157
**Usage Examples:**
158

159
```javascript
160
const ip = require('ip');
161

162
console.log(ip.isPublic('8.8.8.8')); // true
163
console.log(ip.isPublic('1.1.1.1')); // true
164
console.log(ip.isPublic('192.168.1.1')); // false (private)
165
console.log(ip.isPublic('127.0.0.1')); // false (loopback)
166
```
167

168
#### isLoopback
169

170
Checks if an IP address is a loopback address, supporting various input formats including decimal, octal, hexadecimal, and long integer representations.
171

172
```javascript { .api }
173
/**
174
 * Checks if IP address is loopback address
175
 * @param {string} addr - IP address to check (supports various formats)
176
 * @returns {boolean} True if address is loopback, false otherwise
177
 */
178
function isLoopback(addr);
179
```
180

181
**Supported Loopback Ranges:**
182
- IPv4: 127.0.0.0/8 (any address starting with 127)
183
- IPv6: ::1, fe80::1, ::
184

185
**Usage Examples:**
186

187
```javascript
188
const ip = require('ip');
189

190
// Standard IPv4 loopback
191
console.log(ip.isLoopback('127.0.0.1')); // true
192
console.log(ip.isLoopback('127.8.8.8')); // true (any 127.x.x.x)
193

194
// IPv6 loopback
195
console.log(ip.isLoopback('::1')); // true
196
console.log(ip.isLoopback('fe80::1')); // true
197
console.log(ip.isLoopback('::')); // true
198

199
// Various IPv4 formats
200
console.log(ip.isLoopback('0177.0.0.1')); // true (octal)
201
console.log(ip.isLoopback('0x7f.0.0.1')); // true (hex)
202
console.log(ip.isLoopback('2130706433')); // true (long integer)
203

204
// Non-loopback addresses
205
console.log(ip.isLoopback('8.8.8.8')); // false
206
console.log(ip.isLoopback('192.168.1.1')); // false
207
```