0
# Range Check
1

2
Range Check is a comprehensive IP address validation and manipulation library for TypeScript/JavaScript that handles both IPv4 and IPv6 addresses. It provides utilities for validation, version detection, CIDR range checking, private IP detection, address normalization, and IP fingerprinting for analytics and security applications.
3

4
## Package Information
5

6
- **Package Name**: range_check
7
- **Package Type**: npm
8
- **Language**: TypeScript (compiled to JavaScript)
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
  IPFingerprint,
27
  IPFingerprintHashed
28
} from "range_check";
29
```
30

31
For CommonJS:
32

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

51
## Basic Usage
52

53
```typescript
54
import { isIP, version, inRange, isPrivateIP } from "range_check";
55

56
// Basic IP validation
57
console.log(isIP('192.168.1.1')); // true
58
console.log(isIP('invalid')); // false
59

60
// IP version detection
61
console.log(version('192.168.1.1')); // 4
62
console.log(version('2001:db8::1')); // 6
63

64
// Range checking
65
console.log(inRange('192.168.1.1', '192.168.0.0/16')); // true
66
console.log(inRange('10.0.1.5', ['10.0.0.0/8', '192.168.0.0/16'])); // true
67

68
// Private IP detection
69
console.log(isPrivateIP('192.168.1.1')); // true
70
console.log(isPrivateIP('8.8.8.8')); // false
71
```
72

73
## Capabilities
74

75
### IP Address Validation
76

77
Core IP address validation functionality for checking if strings are valid IP addresses.
78

79
```typescript { .api }
80
/**
81
 * Checks if a string is a valid IP address (IPv4 or IPv6)
82
 * @param addr - IP address string to validate
83
 * @returns True if valid IP address, false otherwise
84
 */
85
function isIP(addr: string): boolean;
86
```
87

88
### IP Version Detection
89

90
Functions for determining IP address versions and checking specific versions.
91

92
```typescript { .api }
93
/**
94
 * Returns the IP version number
95
 * @param addr - IP address string to check
96
 * @returns 4 for IPv4, 6 for IPv6, 0 for invalid IP
97
 */
98
function version(addr: string): number;
99

100
/**
101
 * Checks if IP address is IPv4
102
 * @param addr - IP address string to check
103
 * @returns True if IPv4, false otherwise
104
 */
105
function isV4(addr: string): boolean;
106

107
/**
108
 * Checks if IP address is IPv6
109
 * @param addr - IP address string to check
110
 * @returns True if IPv6, false otherwise
111
 */
112
function isV6(addr: string): boolean;
113
```
114

115
### CIDR Range Operations
116

117
Functions for validating CIDR ranges and checking if IP addresses fall within specific ranges.
118

119
```typescript { .api }
120
/**
121
 * Validates if string is a valid CIDR range
122
 * @param range - CIDR range string to validate (e.g., "10.0.0.0/8")
123
 * @returns True if valid CIDR range, false otherwise
124
 */
125
function isRange(range: string): boolean;
126

127
/**
128
 * Checks if IP address is within specified range(s)
129
 * @param addr - IP address to check
130
 * @param range - CIDR range, single IP, or array of ranges
131
 * @returns True if IP is within any specified range, false otherwise
132
 */
133
function inRange(addr: string, range: string | string[]): boolean;
134
```
135

136
### Private IP Detection
137

138
Advanced private IP detection with support for IPv4 private ranges, IPv6 unique local addresses, and IPv4-mapped IPv6 addresses.
139

140
```typescript { .api }
141
/**
142
 * Checks if IP address is private (RFC 1918, RFC 4193, loopback)
143
 * @param ip - IP address to check
144
 * @returns True if private IP address, false otherwise
145
 */
146
function isPrivateIP(ip: string): boolean;
147

148
/**
149
 * Checks if IP is in specified ranges or is private
150
 * @param ip - IP address to check
151
 * @param options - Configuration options
152
 * @returns True if IP matches criteria, false otherwise
153
 */
154
function isIPInRangeOrPrivate(
155
  ip: string,
156
  options?: {
157
    ranges?: string[] | string;
158
    allowAnyPrivate?: boolean;
159
  }
160
): boolean;
161
```
162

163
The `isIPInRangeOrPrivate` function supports flexible configuration:
164
- `ranges`: String or array of CIDR ranges to check against
165
- `allowAnyPrivate`: Whether to allow any private IP (default: true)
166

167
### IP Address Normalization
168

169
Functions for normalizing IP addresses for consistent storage and display across different representations.
170

171
```typescript { .api }
172
/**
173
 * Normalizes IP address for consistent storage
174
 * @param addr - IP address to normalize
175
 * @returns Normalized IP for storage, null if invalid
176
 */
177
function storeIP(addr: string): string | null;
178

179
/**
180
 * Alias for storeIP - normalizes IP address for search operations
181
 * @param addr - IP address to normalize
182
 * @returns Normalized IP for search, null if invalid
183
 */
184
function searchIP(addr: string): string | null;
185

186
/**
187
 * Formats IP address for display (expands IPv6, converts IPv4-mapped)
188
 * @param addr - IP address to format
189
 * @returns Formatted IP for display, empty string if invalid
190
 */
191
function displayIP(addr: string): string;
192
```
193

194
**Storage vs Display Behavior:**
195
- `storeIP`/`searchIP`: IPv6 addresses are abbreviated, IPv4-mapped IPv6 converted to IPv4
196
- `displayIP`: IPv6 addresses are normalized (expanded), IPv4-mapped IPv6 converted to IPv4
197

198
### IP Fingerprinting
199

200
Advanced IP fingerprinting capabilities for bot tracking, analytics, and rate limiting applications.
201

202
```typescript { .api }
203
/**
204
 * Generates consistent fingerprint for IP addresses
205
 * @param addr - IP address to fingerprint
206
 * @returns Fingerprint in format "v4:ADDRESS" or "v6:PREFIX::"
207
 * @throws Error if invalid IP address
208
 */
209
function IPFingerprint(addr: string): string;
210

211
/**
212
 * Generates SHA-256 hashed fingerprint using Web Crypto API
213
 * @param addr - IP address to fingerprint
214
 * @returns Promise resolving to hashed fingerprint "v4:HASH" or "v6:HASH"
215
 * @throws Error if invalid IP or Web Crypto API unavailable
216
 */
217
function IPFingerprintHashed(addr: string): Promise<string>;
218
```
219

220
**Fingerprinting Behavior:**
221
- **IPv4**: Uses full address (e.g., `v4:192.168.1.1`)
222
- **IPv6**: Uses /64 network prefix (e.g., `v6:2001:db8:1234:5678::`)
223
- **IPv4-mapped IPv6**: Converted to IPv4 format
224
- **Hashed version**: SHA-256 hash of IP portion only, preserving prefix format
225

226
**Usage Examples:**
227

228
```typescript
229
// Basic fingerprinting
230
const fp1 = IPFingerprint('192.168.1.1'); // "v4:192.168.1.1"
231
const fp2 = IPFingerprint('2001:db8::1'); // "v6:2001:db8:0:0::"
232

233
// Hashed fingerprinting for privacy
234
const hashedFp = await IPFingerprintHashed('192.168.1.1');
235
// "v4:c5eb5a4cc76a5cdb16e79864b9ccd26c3553f0c396d0a21bafb7be71c1efcd8c"
236

237
// Rate limiting example
238
const userKey = await IPFingerprintHashed(clientIP);
239
if (tooManyRequests(userKey)) {
240
  throw new Error('Rate limit exceeded');
241
}
242
```
243

244
## Types
245

246
```typescript { .api }
247
// Options interface for isIPInRangeOrPrivate function
248
interface IPRangeOptions {
249
  ranges?: string[] | string;
250
  allowAnyPrivate?: boolean;
251
}
252
```
253

254
## Error Handling
255

256
Functions return `false`, `null`, `0`, or empty string for invalid inputs rather than throwing exceptions, except for:
257
- `IPFingerprint`: Throws `Error` for invalid IP addresses
258
- `IPFingerprintHashed`: Throws `Error` for invalid IP addresses or when Web Crypto API is unavailable
259

260
## Browser and Node.js Compatibility
261

262
- **Core functions**: Work in all JavaScript environments
263
- **IPFingerprintHashed**: Requires Web Crypto API support (modern browsers, Node.js 15.0+, Bun)
264
- **Dependencies**: Uses `ipaddr.js` for parsing and `ip6` for IPv6 normalization
265

266
## Common Use Cases
267

268
**Form Validation:**
269
```typescript
270
if (!isIP(userInput)) {
271
  throw new Error('Invalid IP address');
272
}
273
```
274

275
**Security Filtering:**
276
```typescript
277
if (isPrivateIP(clientIP) || inRange(clientIP, allowedRanges)) {
278
  // Allow request
279
} else {
280
  // Block request
281
}
282
```
283

284
**Database Storage:**
285
```typescript
286
const normalizedIP = storeIP(clientIP);
287
if (normalizedIP) {
288
  await db.users.update({ lastIP: normalizedIP });
289
}
290
```
291

292
**Rate Limiting:**
293
```typescript
294
const fingerprint = await IPFingerprintHashed(clientIP);
295
if (await rateLimiter.isExceeded(fingerprint)) {
296
  throw new Error('Too many requests');
297
}
298
```