0
# IPv6 Address Operations
1

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

4
## Capabilities
5

6
### Address6 Class
7

8
The main class for handling IPv6 addresses with support for all IPv6 notations and embedded IPv4 addresses.
9

10
```typescript { .api }
11
/**
12
 * Represents an IPv6 address with optional subnet mask and zone identifier
13
 * @param address - IPv6 address string (e.g., "2001:db8::1" or "2001:db8::1/64")
14
 * @param optionalGroups - Number of groups to parse (default: 8)
15
 */
16
class Address6 {
17
  constructor(address: string, optionalGroups?: number);
18
  
19
  // Properties
20
  address4?: Address4;          // IPv4 component if v4-in-v6
21
  address: string;              // Original address string
22
  addressMinusSuffix: string;   // Address without suffix
23
  elidedGroups?: number;        // Number of elided groups (::)
24
  elisionBegin?: number;        // Start position of elision
25
  elisionEnd?: number;          // End position of elision
26
  groups: number;               // Number of groups (8 for IPv6)
27
  parsedAddress4?: string;      // Parsed IPv4 component
28
  parsedAddress: string[];      // Array of address groups
29
  parsedSubnet: string;         // Subnet portion as string
30
  subnet: string;               // Subnet string (default "/128")
31
  subnetMask: number;           // Subnet mask length (0-128)
32
  v4: boolean;                  // True if contains IPv4 component
33
  zone: string;                 // Zone identifier (%zone)
34
}
35
```
36

37
### Static Creation Methods
38

39
Create Address6 instances from various formats and sources.
40

41
```typescript { .api }
42
/**
43
 * Validate an IPv6 address string without creating an instance
44
 * @param address - IPv6 address string to validate
45
 * @returns true if valid, false otherwise
46
 */
47
static isValid(address: string): boolean;
48

49
/**
50
 * Create Address6 from BigInt representation
51
 * @param bigInt - 128-bit BigInt representation
52
 * @returns Address6 instance
53
 */
54
static fromBigInt(bigInt: bigint): Address6;
55

56
/**
57
 * Parse IPv6 address and port from URL
58
 * @param url - URL containing IPv6 address (e.g., "http://[2001:db8::1]:8080/path")
59
 * @returns Object with address and port properties
60
 */
61
static fromURL(url: string): { address: Address6; port: number | null };
62

63
/**
64
 * Create IPv6-mapped IPv4 address from IPv4 string
65
 * @param address - IPv4 address string
66
 * @returns Address6 instance (::ffff:x.x.x.x format)
67
 */
68
static fromAddress4(address: string): Address6;
69

70
/**
71
 * Create Address6 from reverse DNS (ip6.arpa) format
72
 * @param arpaFormAddress - Reverse DNS string
73
 * @returns Address6 instance
74
 */
75
static fromArpa(arpaFormAddress: string): Address6;
76

77
/**
78
 * Create Address6 from byte array
79
 * @param bytes - Array of bytes representing the address
80
 * @returns Address6 instance
81
 */
82
static fromByteArray(bytes: Array<any>): Address6;
83

84
/**
85
 * Create Address6 from unsigned byte array
86
 * @param bytes - Array of unsigned bytes
87
 * @returns Address6 instance
88
 */
89
static fromUnsignedByteArray(bytes: Array<any>): Address6;
90
```
91

92
**Usage Examples:**
93

94
```typescript
95
import { Address6 } from "ip-address";
96

97
// From string
98
const addr1 = new Address6("2001:db8::1/64");
99

100
// From BigInt
101
const bigIntAddr = Address6.fromBigInt(BigInt("42540766411282592856903984951653826561"));
102

103
// From URL
104
const urlResult = Address6.fromURL("http://[2001:db8::1]:8080/path");
105
console.log(urlResult.address.correctForm()); // "2001:db8::1"
106
console.log(urlResult.port); // 8080
107

108
// IPv6-mapped IPv4
109
const mapped = Address6.fromAddress4("192.168.1.1");
110
console.log(mapped.correctForm()); // "::ffff:c0a8:101"
111

112
// From reverse DNS
113
const arpa = Address6.fromArpa("1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa.");
114

115
// Validation
116
console.log(Address6.isValid("2001:db8::1")); // true
117
console.log(Address6.isValid("invalid")); // false
118
```
119

120
### Form and Parsing Methods
121

122
Methods for address parsing, validation, and canonical representation.
123

124
```typescript { .api }
125
/**
126
 * Parse IPv6 address string into components
127
 * @param address - IPv6 address string
128
 * @returns Array of address groups as strings
129
 */
130
parse(address: string): string[];
131

132
/**
133
 * Parse IPv4-in-IPv6 component if present
134
 * @param address - Address string potentially containing IPv4
135
 * @returns Modified address string with IPv4 converted to IPv6 groups
136
 */
137
parse4in6(address: string): string;
138

139
/**
140
 * Return the correct compressed form of the address
141
 * @returns Correctly compressed IPv6 address string
142
 */
143
correctForm(): string;
144

145
/**
146
 * Return the canonical (uncompressed) form of the address
147
 * @returns Full 32-character hex representation with colons
148
 */
149
canonicalForm(): string;
150

151
/**
152
 * Return decimal representation of the address
153
 * @returns Colon-separated decimal groups
154
 */
155
decimal(): string;
156

157
/**
158
 * Check if address is in correct form
159
 * @returns true if address is correctly formatted
160
 */
161
isCorrect(): boolean;
162

163
/**
164
 * Check if address is in canonical form
165
 * @returns true if address is in canonical form
166
 */
167
isCanonical(): boolean;
168
```
169

170
**Usage Examples:**
171

172
```typescript
173
const addr = new Address6("2001:0db8:0000:0000:0000:0000:0000:0001");
174

175
console.log(addr.correctForm()); // "2001:db8::1"
176
console.log(addr.canonicalForm()); // "2001:0db8:0000:0000:0000:0000:0000:0001"
177
console.log(addr.decimal()); // "08193:03512:00000:00000:00000:00000:00000:00001"
178

179
console.log(addr.isCorrect()); // false (not compressed)
180
console.log(addr.isCanonical()); // true
181

182
const compressed = new Address6("2001:db8::1");
183
console.log(compressed.isCorrect()); // true
184
```
185

186
### Conversion Methods
187

188
Convert IPv6 addresses to different representations and extract components.
189

190
```typescript { .api }
191
/**
192
 * Convert address to BigInt representation
193
 * @returns 128-bit BigInt value
194
 */
195
bigInt(): bigint;
196

197
/**
198
 * Convert address to zero-padded binary string
199
 * @returns 128-character binary string
200
 */
201
binaryZeroPad(): string;
202

203
/**
204
 * Extract IPv4 address from last 32 bits
205
 * @returns Address4 instance from last 32 bits
206
 */
207
to4(): Address4;
208

209
/**
210
 * Return IPv4-in-IPv6 representation
211
 * @returns String with IPv4 notation in last group
212
 */
213
to4in6(): string;
214

215
/**
216
 * Convert to 6to4 address format
217
 * @returns Address6 instance in 6to4 format, or null if not applicable
218
 */
219
to6to4(): Address6 | null;
220

221
/**
222
 * Convert address to byte array
223
 * @returns Array of bytes representing the address
224
 */
225
toByteArray(): number[];
226

227
/**
228
 * Convert address to unsigned byte array
229
 * @returns Array of unsigned bytes
230
 */
231
toUnsignedByteArray(): number[];
232
```
233

234
**Usage Examples:**
235

236
```typescript
237
const addr = new Address6("2001:db8:1234:5678::abcd");
238

239
console.log(addr.bigInt()); // BigInt representation
240
console.log(addr.binaryZeroPad()); // 128-bit binary string
241

242
// IPv4 extraction (from embedded IPv4)
243
const mapped = new Address6("::ffff:192.168.1.1");
244
console.log(mapped.to4().correctForm()); // "192.168.1.1"
245
console.log(mapped.to4in6()); // "::ffff:192.168.1.1"
246

247
// Byte arrays
248
console.log(addr.toByteArray()); // [32, 1, 13, 184, 18, 52, 86, 120, ...]
249
```
250

251
### Bit Manipulation Methods
252

253
Advanced methods for working with specific bit ranges and masks.
254

255
```typescript { .api }
256
/**
257
 * Get first n bits as binary string (defaults to subnet mask)
258
 * @param mask - Number of bits to mask (optional)
259
 * @returns Binary string of masked bits
260
 */
261
mask(mask?: number): string;
262

263
/**
264
 * Get bits in specified range as BigInt
265
 * @param start - Start bit position (0-127)
266
 * @param end - End bit position (0-127)
267
 * @returns BigInt value of specified bits
268
 */
269
getBits(start: number, end: number): bigint;
270

271
/**
272
 * Get bits in specified range as binary string
273
 * @param start - Start bit position
274
 * @param end - End bit position
275
 * @returns Binary string of specified bits
276
 */
277
getBitsBase2(start: number, end: number): string;
278

279
/**
280
 * Get bits in specified range as hexadecimal string
281
 * @param start - Start bit position (must be divisible by 4)
282
 * @param end - End bit position (must be divisible by 4)
283
 * @returns Hex string of specified bits
284
 */
285
getBitsBase16(start: number, end: number): string;
286

287
/**
288
 * Get bits beyond the subnet mask
289
 * @returns Binary string of host portion
290
 */
291
getBitsPastSubnet(): string;
292
```
293

294
**Usage Examples:**
295

296
```typescript
297
const addr = new Address6("2001:db8::1/64");
298

299
console.log(addr.mask()); // First 64 bits as binary
300
console.log(addr.getBits(0, 16)); // First 16 bits as BigInt
301
console.log(addr.getBitsBase2(0, 16)); // First 16 bits as binary
302
console.log(addr.getBitsBase16(0, 16)); // First 16 bits as hex
303
console.log(addr.getBitsPastSubnet()); // Host portion (last 64 bits)
304
```
305

306
### Address Type and Properties
307

308
Methods for identifying address types, scopes, and special properties.
309

310
```typescript { .api }
311
/**
312
 * Get the scope of the address
313
 * @returns Scope string (e.g., "Global", "Link local", "Site local")
314
 */
315
getScope(): string;
316

317
/**
318
 * Get the type/category of the address
319
 * @returns Type string (e.g., "Global unicast", "Multicast", "Loopback")
320
 */
321
getType(): string;
322

323
/**
324
 * Check if address is link-local (fe80::/10 with zero padding)
325
 * @returns true if link-local address
326
 */
327
isLinkLocal(): boolean;
328

329
/**
330
 * Check if address is multicast
331
 * @returns true if multicast address (ff00::/8)
332
 */
333
isMulticast(): boolean;
334

335
/**
336
 * Check if address contains IPv4 component
337
 * @returns true if address has IPv4-in-IPv6 format
338
 */
339
is4(): boolean;
340

341
/**
342
 * Check if address is Teredo address
343
 * @returns true if Teredo address (2001::/32)
344
 */
345
isTeredo(): boolean;
346

347
/**
348
 * Check if address is 6to4 address
349
 * @returns true if 6to4 address (2002::/16)
350
 */
351
is6to4(): boolean;
352

353
/**
354
 * Check if address is loopback (::1)
355
 * @returns true if loopback address
356
 */
357
isLoopback(): boolean;
358
```
359

360
**Usage Examples:**
361

362
```typescript
363
const global = new Address6("2001:db8::1");
364
console.log(global.getType()); // "Global unicast"
365
console.log(global.getScope()); // "Global"
366

367
const linkLocal = new Address6("fe80::1");
368
console.log(linkLocal.isLinkLocal()); // true
369
console.log(linkLocal.getScope()); // "Link local"
370

371
const multicast = new Address6("ff02::1");
372
console.log(multicast.isMulticast()); // true
373
console.log(multicast.getType()); // "Multicast (All nodes on this link)"
374

375
const teredo = new Address6("2001:0:ce49:7601:e866:efff:62c3:fffe");
376
console.log(teredo.isTeredo()); // true
377
```
378

379
### Reverse DNS Methods
380

381
Generate reverse DNS representations for IPv6 addresses.
382

383
```typescript { .api }
384
/**
385
 * Return reverse DNS (ip6.arpa) form
386
 * @param options - Options for reverse form generation
387
 * @returns Reverse DNS string
388
 */
389
reverseForm(options?: ReverseFormOptions): string;
390

391
/**
392
 * Return Microsoft UNC transcription
393
 * @returns Microsoft-compatible IPv6 literal format
394
 */
395
microsoftTranscription(): string;
396
```
397

398
**Usage Examples:**
399

400
```typescript
401
const addr = new Address6("2001:db8::1/64");
402

403
console.log(addr.reverseForm());
404
// "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa."
405

406
console.log(addr.reverseForm({ omitSuffix: true }));
407
// "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0"
408

409
console.log(addr.microsoftTranscription());
410
// "2001-db8-0-0-0-0-0-1.ipv6-literal.net"
411
```
412

413
### HTML and Display Methods
414

415
Methods for generating HTML representations and styled output.
416

417
```typescript { .api }
418
/**
419
 * Generate HTTP URL with IPv6 address in brackets
420
 * @param optionalPort - Port number (optional)
421
 * @returns HTTP URL string
422
 */
423
href(optionalPort?: number | string): string;
424

425
/**
426
 * Generate HTML link with customizable formatting
427
 * @param options - Link generation options
428
 * @returns HTML anchor tag string
429
 */
430
link(options?: {
431
  className?: string;
432
  prefix?: string;
433
  v4?: boolean;
434
}): string;
435

436
/**
437
 * Generate HTML representation with styling classes
438
 * @returns HTML string with span elements and CSS classes
439
 */
440
group(): string;
441
```
442

443
**Usage Examples:**
444

445
```typescript
446
const addr = new Address6("2001:db8::1");
447

448
console.log(addr.href()); // "http://[2001:db8::1]/"
449
console.log(addr.href(8080)); // "http://[2001:db8::1]:8080/"
450

451
console.log(addr.link());
452
// '<a href="/#address=2001:db8::1">2001:db8::1</a>'
453

454
console.log(addr.link({ className: "ipv6-link", prefix: "/ip/" }));
455
// '<a href="/ip/2001:db8::1" class="ipv6-link">2001:db8::1</a>'
456
```
457

458
### Regular Expression Methods
459

460
Generate regular expressions for pattern matching and validation.
461

462
```typescript { .api }
463
/**
464
 * Generate regular expression string for matching address variations
465
 * @param substringSearch - Whether to generate for substring search
466
 * @returns Regular expression string
467
 */
468
regularExpressionString(substringSearch?: boolean): string;
469

470
/**
471
 * Generate RegExp object for matching address variations
472
 * @param substringSearch - Whether to generate for substring search
473
 * @returns RegExp object
474
 */
475
regularExpression(substringSearch?: boolean): RegExp;
476
```
477

478
**Usage Examples:**
479

480
```typescript
481
const addr = new Address6("2001:db8::1");
482

483
const regex = addr.regularExpression();
484
console.log(regex.test("2001:0db8::1")); // true
485
console.log(regex.test("2001:db8:0:0:0:0:0:1")); // true
486

487
const regexStr = addr.regularExpressionString(true);
488
// Use for custom pattern matching
489
```
490

491
### Subnet and Range Operations
492

493
Advanced subnet analysis and range calculations for IPv6 networks.
494

495
```typescript { .api }
496
/**
497
 * Calculate number of possible subnets of given size
498
 * @param subnetSize - Target subnet size (default: 128)
499
 * @returns String representation of possible subnet count
500
 */
501
possibleSubnets(subnetSize?: number): string;
502

503
/**
504
 * Get the first address (network address) in this subnet
505
 * @returns Address6 instance of network address
506
 */
507
startAddress(): Address6;
508

509
/**
510
 * Get the first host address in this subnet
511
 * @returns Address6 instance of first host address
512
 */
513
startAddressExclusive(): Address6;
514

515
/**
516
 * Get the last address (broadcast address) in this subnet  
517
 * @returns Address6 instance of broadcast address
518
 */
519
endAddress(): Address6;
520

521
/**
522
 * Get the last host address in this subnet
523
 * @returns Address6 instance of last host address
524
 */
525
endAddressExclusive(): Address6;
526

527
/**
528
 * Check if given address is within this address's subnet
529
 * @param address - Address6 instance to check
530
 * @returns true if address is in subnet
531
 */
532
isInSubnet(address: Address6): boolean;
533
```
534

535
**Usage Examples:**
536

537
```typescript
538
const network = new Address6("2001:db8::/32");
539

540
console.log(network.startAddress().correctForm()); // "2001:db8::"
541
console.log(network.endAddress().correctForm()); // "2001:db8:ffff:ffff:ffff:ffff:ffff:ffff"
542

543
const host = new Address6("2001:db8::1");
544
console.log(network.isInSubnet(host)); // true
545

546
console.log(network.possibleSubnets(64)); // Number of /64 subnets in /32
547
```
548

549
### Special Address Analysis
550

551
Extract properties from specialized IPv6 address formats including tunneling mechanisms.
552

553
```typescript { .api }
554
/**
555
 * Extract Teredo tunnel properties from address
556
 * @returns Object containing Teredo configuration details
557
 */
558
inspectTeredo(): TeredoProperties;
559

560
/**
561
 * Extract 6to4 tunnel properties from address
562
 * @returns Object containing 6to4 configuration details  
563
 */
564
inspect6to4(): SixToFourProperties;
565
```
566

567
**Usage Examples:**
568

569
```typescript
570
// Teredo address analysis
571
const teredo = new Address6("2001:0:ce49:7601:e866:efff:62c3:fffe");
572
const teredoInfo = teredo.inspectTeredo();
573
console.log(teredoInfo.server4); // "206.73.118.1"
574
console.log(teredoInfo.client4); // "157.60.0.1"
575

576
// 6to4 address analysis  
577
const sixToFour = new Address6("2002:c000:0204::1");
578
const info = sixToFour.inspect6to4();
579
console.log(info.gateway); // "192.0.2.4"
580
```
581

582
## Types
583

584
```typescript { .api }
585
interface ReverseFormOptions {
586
  omitSuffix?: boolean;
587
}
588

589
interface TeredoProperties {
590
  prefix: string;
591
  server4: string;
592
  client4: string;
593
  flags: string;
594
  coneNat: boolean;
595
  microsoft: {
596
    reserved: boolean;
597
    universalLocal: boolean;
598
    groupIndividual: boolean;
599
    nonce: string;
600
  };
601
  udpPort: string;
602
}
603

604
interface SixToFourProperties {
605
  prefix: string;
606
  gateway: string;
607
}
608
```