0
# Range Check
1

2
Range Check is a comprehensive IP address validation and manipulation library for both IPv4 and IPv6 addresses. It provides essential functions for validating IP addresses, determining their version, checking if addresses fall within specific CIDR ranges, and handling private IP detection with specialized access control utilities.
3

4
## Package Information
5

6
- **Package Name**: range_check
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install range_check`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  isIP, 
16
  version, 
17
  isV4, 
18
  isV6, 
19
  isRange, 
20
  inRange, 
21
  isPrivateIP, 
22
  isIPInRangeOrPrivate, 
23
  storeIP, 
24
  searchIP, 
25
  displayIP 
26
} from "range_check";
27
```
28

29
For CommonJS:
30

31
```javascript
32
const { 
33
  isIP, 
34
  version, 
35
  isV4, 
36
  isV6, 
37
  isRange, 
38
  inRange, 
39
  isPrivateIP, 
40
  isIPInRangeOrPrivate, 
41
  storeIP, 
42
  searchIP, 
43
  displayIP 
44
} = require("range_check");
45
```
46

47
## Basic Usage
48

49
```typescript
50
import { isIP, version, inRange, isPrivateIP } from "range_check";
51

52
// Basic IP validation
53
console.log(isIP('10.0.1.5')); // true
54
console.log(isIP('foo')); // false
55

56
// Check IP version
57
console.log(version('10.0.1.5')); // 4
58
console.log(version('2001:4860:8006::62')); // 6
59

60
// Range checking
61
console.log(inRange('10.0.1.5', '10.0.0.0/8')); // true
62
console.log(inRange('192.168.1.1', ['10.0.0.0/8', '192.0.0.0/8'])); // true
63

64
// Private IP detection
65
console.log(isPrivateIP('192.168.1.1')); // true
66
console.log(isPrivateIP('8.8.8.8')); // false
67
```
68

69
## Capabilities
70

71
### IP Address Validation
72

73
Validates whether strings are valid IP addresses and determines their version.
74

75
```typescript { .api }
76
/**
77
 * Validates whether a string is a valid IP address (IPv4 or IPv6)
78
 * @param addr - IP address string to validate
79
 * @returns true if valid IP address, false otherwise
80
 */
81
function isIP(addr: string): boolean;
82

83
/**
84
 * Returns IP version number
85
 * @param addr - IP address string to check
86
 * @returns 4 for IPv4, 6 for IPv6, 0 for invalid IP
87
 */
88
function version(addr: string): number;
89

90
/**
91
 * Checks if address is a valid IPv4 address
92
 * @param addr - IP address string to check
93
 * @returns true if valid IPv4, false otherwise
94
 */
95
function isV4(addr: string): boolean;
96

97
/**
98
 * Checks if address is a valid IPv6 address
99
 * @param addr - IP address string to check
100
 * @returns true if valid IPv6, false otherwise
101
 */
102
function isV6(addr: string): boolean;
103
```
104

105
**Usage Examples:**
106

107
```typescript
108
import { isIP, version, isV4, isV6 } from "range_check";
109

110
// Validate IP addresses
111
console.log(isIP('10.0.1.5')); // true
112
console.log(isIP('123::123')); // true
113
console.log(isIP('foo')); // false
114

115
// Check IP versions
116
console.log(version('10.0.1.5')); // 4
117
console.log(version('2001:4860:8006::62')); // 6
118
console.log(version('foo')); // 0
119

120
// Specific version checks
121
console.log(isV4('10.0.1.5')); // true
122
console.log(isV4('123::123')); // false
123
console.log(isV6('123::123')); // true
124
console.log(isV6('10.0.1.5')); // false
125
```
126

127
### CIDR Range Operations
128

129
Validates CIDR ranges and checks if IP addresses fall within specified ranges.
130

131
```typescript { .api }
132
/**
133
 * Validates whether a string is a valid CIDR range
134
 * @param range - CIDR range string to validate (e.g., "10.0.0.0/8")
135
 * @returns true if valid CIDR range, false otherwise
136
 */
137
function isRange(range: string): boolean;
138

139
/**
140
 * Checks if IP address is within specified range(s)
141
 * @param addr - IP address to check
142
 * @param range - CIDR range string, exact IP, or array of ranges
143
 * @returns true if IP is in range, false otherwise
144
 */
145
function inRange(addr: string, range: string | string[]): boolean;
146
```
147

148
**Usage Examples:**
149

150
```typescript
151
import { isRange, inRange } from "range_check";
152

153
// Validate CIDR ranges
154
console.log(isRange('10.0.0.0/8')); // true
155
console.log(isRange('2001:db8::/32')); // true
156
console.log(isRange('qwerty')); // false
157

158
// Check if IP is in range
159
console.log(inRange('10.0.1.5', '10.0.0.0/8')); // true
160
console.log(inRange('192.0.1.5', '10.0.0.0/8')); // false
161
console.log(inRange('2001:db8:1234::1', '2001:db8::/32')); // true
162

163
// Multiple ranges
164
console.log(inRange('192.168.1.1', ['10.0.0.0/8', '192.0.0.0/8'])); // true
165

166
// Exact IP match
167
console.log(inRange('10.0.1.5', '10.0.1.5')); // true
168
```
169

170
### Private IP Detection
171

172
Identifies private/local IP addresses and provides flexible access control functions.
173

174
```typescript { .api }
175
/**
176
 * Checks if IP address is private/local - handles both IPv4 and IPv6
177
 * @param ip - IP address to check  
178
 * @returns true if private IP, false if public or invalid/unparseable
179
 */
180
function isPrivateIP(ip: string): boolean;
181

182
/**
183
 * Checks if IP is either within specified ranges or is a private IP
184
 * @param ip - IP address to check
185
 * @param options - Configuration options (defaults to allowing any private IP)
186
 * @returns true if IP is allowed (in range or private), false if blocked or invalid
187
 */
188
function isIPInRangeOrPrivate(
189
  ip: string, 
190
  options?: {
191
    ranges?: string[] | string;
192
    allowAnyPrivate?: boolean;
193
  }
194
): boolean;
195
```
196

197
**Private IP Ranges Detected:**
198

199
- **IPv4**: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8 (loopback)
200
- **IPv6**: fd00::/8 (ULA), ::1 (loopback)
201

202
**Usage Examples:**
203

204
```typescript
205
import { isPrivateIP, isIPInRangeOrPrivate } from "range_check";
206

207
// Basic private IP detection
208
console.log(isPrivateIP('10.0.0.1')); // true
209
console.log(isPrivateIP('192.168.1.1')); // true
210
console.log(isPrivateIP('172.16.0.1')); // true
211
console.log(isPrivateIP('127.0.0.1')); // true (loopback)
212
console.log(isPrivateIP('8.8.8.8')); // false
213
console.log(isPrivateIP('fd00::1')); // true (IPv6 ULA)
214
console.log(isPrivateIP('::1')); // true (IPv6 loopback)
215

216
// Flexible access control
217
console.log(isIPInRangeOrPrivate('192.168.1.1')); // true (private allowed by default)
218
console.log(isIPInRangeOrPrivate('8.8.8.8')); // false (public, no range specified)
219
console.log(isIPInRangeOrPrivate('8.8.8.8', { ranges: '8.8.8.0/24' })); // true
220
console.log(isIPInRangeOrPrivate('10.0.0.1', { allowAnyPrivate: false, ranges: '8.8.8.0/24' })); // false
221
```
222

223
### IP Storage and Display
224

225
Normalizes IP addresses for consistent storage and display formatting.
226

227
```typescript { .api }
228
/**
229
 * Normalizes IP address for consistent storage - handles both IPv4 and IPv6 addresses
230
 * @param addr - IP address to normalize
231
 * @returns normalized IP string or null for invalid/unparseable input
232
 */
233
function storeIP(addr: string): string | null;
234

235
/**
236
 * Alias of storeIP for clearer naming when used for search operations
237
 * @param addr - IP address to normalize  
238
 * @returns normalized IP string or null for invalid/unparseable input
239
 */
240
function searchIP(addr: string): string | null;
241

242
/**
243
 * Formats IP address for display purposes - expands IPv6 to full form
244
 * @param addr - IP address to format (accepts null/undefined gracefully)
245
 * @returns formatted IP string or empty string for invalid/null input
246
 */
247
function displayIP(addr: string): string;
248
```
249

250
**Normalization Behavior:**
251

252
- **IPv4**: Returns unchanged
253
- **IPv6**: Abbreviated form (e.g., `2001:0:111:0:11:0:1:0`)
254
- **IPv4-mapped IPv6**: Converted to IPv4 (e.g., `::ffff:127.0.0.1` → `127.0.0.1`)
255
- **Invalid**: Returns `null` (storeIP/searchIP) or `""` (displayIP)
256

257
**Display Behavior:**
258

259
- **IPv4**: Returns unchanged
260
- **IPv6**: Full normalized form (e.g., `2001:0000:0111:0000:0011:0000:0001:0000`)
261
- **IPv4-mapped IPv6**: Converted to IPv4
262
- **Invalid**: Returns empty string
263

264
**Usage Examples:**
265

266
```typescript
267
import { storeIP, searchIP, displayIP } from "range_check";
268

269
// Storage normalization (abbreviated IPv6)
270
console.log(storeIP('::ffff:127.0.0.1')); // "127.0.0.1" (IPv4-mapped converted)
271
console.log(storeIP('2001:0000:0111:0000:0011:0000:0001:0000')); // "2001:0:111:0:11:0:1:0" (abbreviated)
272
console.log(storeIP('127.0.0.1')); // "127.0.0.1" (IPv4 unchanged)
273
console.log(storeIP('foo')); // null (invalid input)
274

275
// Search alias (same as storeIP)  
276
console.log(searchIP('::ffff:127.0.0.1')); // "127.0.0.1"
277

278
// Display formatting (full normalized IPv6)
279
console.log(displayIP('::ffff:127.0.0.1')); // "127.0.0.1" (IPv4-mapped converted)
280
console.log(displayIP('2001:0:111:0:11:0:1:0')); // "2001:0000:0111:0000:0011:0000:0001:0000" (expanded)
281
console.log(displayIP('127.0.0.1')); // "127.0.0.1" (IPv4 unchanged)
282
console.log(displayIP('foo')); // "" (invalid input returns empty string)
283

284
// Note: displayIP handles null input gracefully (returns empty string)
285
console.log(displayIP(null as any)); // "" (graceful null handling)
286
```
287

288
## Types
289

290
```typescript { .api }
291
// Function parameter types
292
type IPAddress = string;
293
type CIDRRange = string;
294
type IPRanges = string | string[];
295

296
// isIPInRangeOrPrivate options
297
interface RangeOrPrivateOptions {
298
  ranges?: string[] | string;
299
  allowAnyPrivate?: boolean;
300
}
301
```