0
# IP Address
1

2
A comprehensive library for validating, parsing, and manipulating IPv4 and IPv6 addresses in JavaScript and TypeScript. It provides extensive IPv6 notation parsing capabilities, URL-based address extraction, subnet validation, Teredo tunneling information decoding, and special address property detection.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { Address4, Address6, AddressError } from "ip-address";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { Address4, Address6, AddressError } = require("ip-address");
21
```
22

23
For IPv6 helper functions:
24

25
```typescript
26
import { v6 } from "ip-address";
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { Address4, Address6, AddressError } from "ip-address";
33

34
// IPv4 addresses
35
const ipv4 = new Address4("192.168.1.1/24");
36
console.log(ipv4.correctForm()); // "192.168.1.1"
37
console.log(ipv4.subnet); // "/24"
38

39
// IPv6 addresses
40
const ipv6 = new Address6("2001:4860:4001:803::1011");
41
console.log(ipv6.correctForm()); // "2001:4860:4001:803::1011"
42
console.log(ipv6.canonicalForm()); // "2001:4860:4001:0803:0000:0000:0000:1011"
43

44
// Validation
45
console.log(Address4.isValid("192.168.1.1")); // true
46
console.log(Address6.isValid("::1")); // true
47

48
// URL parsing
49
const result = Address6.fromURL("http://[2001:db8::1]:8080/path");
50
console.log(result.address.correctForm()); // "2001:db8::1"
51
console.log(result.port); // 8080
52
```
53

54
## Architecture
55

56
The library is built around several key components:
57

58
- **Address Classes**: `Address4` and `Address6` classes that encapsulate IP address parsing, validation, and manipulation
59
- **Static Constructors**: Multiple creation methods from different formats (hex, binary, arpa, URLs)
60
- **Conversion System**: Comprehensive conversion between different representations (hex, binary, decimal, canonical forms)
61
- **Subnet Analysis**: Advanced subnet operations including range calculations and containment checks
62
- **Special Address Detection**: Identification of multicast, loopback, Teredo, 6to4, and other special address types
63
- **Error Handling**: Custom `AddressError` class for detailed error reporting
64

65
## Capabilities
66

67
### IPv4 Address Handling
68

69
Complete IPv4 address parsing, validation, and manipulation including subnet operations, format conversions, and range calculations.
70

71
```typescript { .api }
72
class Address4 {
73
  constructor(address: string);
74
  static isValid(address: string): boolean;
75
  static fromHex(hex: string): Address4;
76
  static fromInteger(integer: number): Address4;
77
  static fromArpa(arpaFormAddress: string): Address4;
78
  static fromBigInt(bigInt: bigint): Address4;
79
  
80
  correctForm(): string;
81
  isCorrect(): boolean;
82
  toHex(): string;
83
  bigInt(): bigint;
84
}
85
```
86

87
[IPv4 Address Operations](./ipv4.md)
88

89
### IPv6 Address Handling
90

91
Comprehensive IPv6 address parsing with support for all notation formats, IPv4-in-IPv6 addresses, URL parsing, and advanced address analysis.
92

93
```typescript { .api }
94
class Address6 {
95
  constructor(address: string, optionalGroups?: number);
96
  static isValid(address: string): boolean;
97
  static fromBigInt(bigInt: bigint): Address6;
98
  static fromURL(url: string): { address: Address6; port: number | null };
99
  static fromAddress4(address: string): Address6;
100
  static fromArpa(arpaFormAddress: string): Address6;
101
  
102
  correctForm(): string;
103
  canonicalForm(): string;
104
  bigInt(): bigint;
105
  getType(): string;
106
  getScope(): string;
107
  
108
  // Subnet operations
109
  startAddress(): Address6;
110
  endAddress(): Address6;
111
  isInSubnet(address: Address6): boolean;
112
  
113
  // Special analysis
114
  inspectTeredo(): TeredoProperties;
115
  inspect6to4(): SixToFourProperties;
116
}
117
```
118

119
[IPv6 Address Operations](./ipv6.md)
120

121
### Subnet and Range Operations
122

123
Advanced subnet analysis including network/broadcast address calculation, host range determination, and subnet containment testing.
124

125
```typescript { .api }
126
// Available on both Address4 and Address6
127
interface SubnetOperations {
128
  startAddress(): Address4 | Address6;
129
  endAddress(): Address4 | Address6;
130
  startAddressExclusive(): Address4 | Address6;
131
  endAddressExclusive(): Address4 | Address6;
132
  isInSubnet(address: Address4 | Address6): boolean;
133
  mask(mask?: number): string;
134
}
135
```
136

137
[Subnet Operations](./subnet-operations.md)
138

139
### Address Type Detection
140

141
Identification and analysis of special address types including multicast, loopback, Teredo, 6to4, and other reserved address ranges.
142

143
```typescript { .api }
144
// IPv4 type detection
145
interface IPv4Types {
146
  isMulticast(): boolean;
147
}
148

149
// IPv6 type detection  
150
interface IPv6Types {
151
  isMulticast(): boolean;
152
  isLoopback(): boolean;
153
  isLinkLocal(): boolean;
154
  isTeredo(): boolean;
155
  is6to4(): boolean;
156
  is4(): boolean;
157
}
158
```
159

160
[Address Type Detection](./address-types.md)
161

162
### Format Conversion
163

164
Conversion between different address representations including hexadecimal, binary, decimal, canonical, and reverse DNS formats.
165

166
```typescript { .api }
167
// Common conversion methods
168
interface FormatConversion {
169
  toHex(): string;
170
  binaryZeroPad(): string;
171
  reverseForm(options?: ReverseFormOptions): string;
172
  toArray(): number[]; // IPv4 only
173
  toByteArray(): number[]; // IPv6 only
174
}
175
```
176

177
[Format Conversion](./format-conversion.md)
178

179
### Special Address Analysis
180

181
Advanced analysis of specialized address formats including Teredo tunneling and 6to4 transition mechanisms.
182

183
```typescript { .api }
184
// IPv6 specialized analysis
185
interface SpecialAnalysis {
186
  inspectTeredo(): TeredoProperties;
187
  inspect6to4(): SixToFourProperties;
188
  microsoftTranscription(): string;
189
}
190
```
191

192
[Special Address Analysis](./special-analysis.md)
193

194
## Error Handling
195

196
```typescript { .api }
197
class AddressError extends Error {
198
  name: "AddressError";
199
  parseMessage?: string;
200
  
201
  constructor(message: string, parseMessage?: string);
202
}
203
```
204

205
The library throws `AddressError` instances for invalid addresses, malformed subnets, and other parsing errors. The optional `parseMessage` property may contain additional context for debugging.
206

207
## Types
208

209
```typescript { .api }
210
interface ReverseFormOptions {
211
  omitSuffix?: boolean;
212
}
213

214
interface TeredoProperties {
215
  prefix: string;
216
  server4: string;
217
  client4: string;
218
  flags: string;
219
  coneNat: boolean;
220
  microsoft: {
221
    reserved: boolean;
222
    universalLocal: boolean;
223
    groupIndividual: boolean;
224
    nonce: string;
225
  };
226
  udpPort: string;
227
}
228

229
interface SixToFourProperties {
230
  prefix: string;
231
  gateway: string;
232
}
233
```