0
# Network Operations
1

2
Comprehensive subnet calculation, CIDR operations, and network masking functionality for network analysis and IP address manipulation with support for both IPv4 and IPv6 networks.
3

4
## Capabilities
5

6
### Subnet Mask Generation
7

8
#### fromPrefixLen
9

10
Creates a subnet mask from a CIDR prefix length, automatically detecting or accepting explicit address family specification.
11

12
```javascript { .api }
13
/**
14
 * Creates subnet mask from prefix length
15
 * @param {number} prefixlen - CIDR prefix length (0-32 for IPv4, 0-128 for IPv6)
16
 * @param {string|number} [family] - 'ipv4', 'ipv6', 4, 6, or auto-detect if omitted
17
 * @returns {string} String representation of subnet mask
18
 */
19
function fromPrefixLen(prefixlen, family);
20
```
21

22
**Usage Examples:**
23

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

27
// IPv4 subnet masks (auto-detected for prefixes <= 32)
28
console.log(ip.fromPrefixLen(24)); // '255.255.255.0'
29
console.log(ip.fromPrefixLen(16)); // '255.255.0.0'
30
console.log(ip.fromPrefixLen(8)); // '255.0.0.0'
31

32
// IPv6 subnet masks (auto-detected for prefixes > 32)
33
console.log(ip.fromPrefixLen(64)); // 'ffff:ffff:ffff:ffff::'
34
console.log(ip.fromPrefixLen(48)); // 'ffff:ffff:ffff::'
35

36
// Explicit family specification
37
console.log(ip.fromPrefixLen(24, 'ipv6')); // 'ffff:ff00::'
38
console.log(ip.fromPrefixLen(24, 6)); // 'ffff:ff00::'
39
console.log(ip.fromPrefixLen(24, 'IPV4')); // '255.255.255.0'
40
```
41

42
### Network Masking
43

44
#### mask
45

46
Applies a subnet mask to an IP address to extract the network address, supporting IPv4/IPv4, IPv6/IPv6, and mixed operations.
47

48
```javascript { .api }
49
/**
50
 * Applies subnet mask to IP address
51
 * @param {string} addr - IP address to mask
52
 * @param {string} mask - Subnet mask to apply
53
 * @returns {string} Masked IP address (network address)
54
 */
55
function mask(addr, mask);
56
```
57

58
**Usage Examples:**
59

60
```javascript
61
const ip = require('ip');
62

63
// IPv4 masking
64
console.log(ip.mask('192.168.1.134', '255.255.255.0')); // '192.168.1.0'
65
console.log(ip.mask('10.5.10.25', '255.255.0.0')); // '10.5.0.0'
66

67
// Mixed IPv4 address with IPv6 mask
68
console.log(ip.mask('192.168.1.134', '::ffff:ff00')); // '::ffff:c0a8:100'
69

70
// IPv6 masking
71
console.log(ip.mask('2001:db8:85a3::8a2e:370:7334', 'ffff:ffff:ffff::')); 
72
// '2001:db8:85a3::'
73
```
74

75
### CIDR Operations
76

77
#### cidr
78

79
Extracts the network address from CIDR notation by applying the appropriate subnet mask.
80

81
```javascript { .api }
82
/**
83
 * Extracts network address from CIDR notation
84
 * @param {string} cidrString - CIDR notation (e.g., '192.168.1.134/26')
85
 * @returns {string} Network address string
86
 * @throws {Error} Throws error for invalid CIDR format
87
 */
88
function cidr(cidrString);
89
```
90

91
**Usage Examples:**
92

93
```javascript
94
const ip = require('ip');
95

96
// IPv4 CIDR
97
console.log(ip.cidr('192.168.1.134/26')); // '192.168.1.128'
98
console.log(ip.cidr('10.0.5.100/8')); // '10.0.0.0'
99
console.log(ip.cidr('172.16.250.1/12')); // '172.16.0.0'
100

101
// IPv6 CIDR
102
console.log(ip.cidr('2607:f0d0:1002:51::4/56')); // '2607:f0d0:1002::'
103

104
// Invalid CIDR throws error
105
try {
106
  ip.cidr('192.168.1.134'); // Missing /prefix
107
} catch (error) {
108
  console.log(error.message); // 'invalid CIDR subnet: 192.168.1.134'
109
}
110
```
111

112
### Subnet Analysis
113

114
#### subnet
115

116
Calculates comprehensive subnet information including network boundaries, host counts, and contains function for range checking.
117

118
```javascript { .api }
119
/**
120
 * Calculates detailed subnet information
121
 * @param {string} addr - IP address within subnet
122
 * @param {string} mask - Subnet mask
123
 * @returns {SubnetInfo} Object with detailed subnet information
124
 */
125
function subnet(addr, mask);
126
```
127

128
## Types
129

130
```javascript { .api }
131
interface SubnetInfo {
132
  networkAddress: string;      // Network base address
133
  firstAddress: string;        // First usable host address  
134
  lastAddress: string;         // Last usable host address
135
  broadcastAddress: string;    // Broadcast address
136
  subnetMask: string;         // Subnet mask
137
  subnetMaskLength: number;   // CIDR prefix length
138
  numHosts: number;           // Number of usable host addresses
139
  length: number;             // Total number of addresses in subnet
140
  contains: (addr: string) => boolean; // Function to check if address is in subnet
141
}
142
```
143

144
**Usage Examples:**
145

146
```javascript
147
const ip = require('ip');
148

149
const subnet = ip.subnet('192.168.1.134', '255.255.255.192');
150

151
console.log(subnet.networkAddress);    // '192.168.1.128'
152
console.log(subnet.firstAddress);      // '192.168.1.129'
153
console.log(subnet.lastAddress);       // '192.168.1.190'
154
console.log(subnet.broadcastAddress);  // '192.168.1.191'
155
console.log(subnet.subnetMask);        // '255.255.255.192'
156
console.log(subnet.subnetMaskLength);  // 26
157
console.log(subnet.numHosts);          // 62
158
console.log(subnet.length);            // 64
159

160
// Check if addresses are in subnet
161
console.log(subnet.contains('192.168.1.150')); // true
162
console.log(subnet.contains('192.168.1.200')); // false
163

164
// Special cases for /31 and /32 networks
165
const pointToPoint = ip.subnet('192.168.1.134', '255.255.255.254'); // /31
166
console.log(pointToPoint.numHosts);     // 2
167
console.log(pointToPoint.firstAddress); // '192.168.1.134'
168
console.log(pointToPoint.lastAddress);  // '192.168.1.135'
169

170
const hostRoute = ip.subnet('192.168.1.134', '255.255.255.255'); // /32
171
console.log(hostRoute.numHosts);        // 1
172
console.log(hostRoute.firstAddress);    // '192.168.1.134'
173
console.log(hostRoute.lastAddress);     // '192.168.1.134'
174
```
175

176
#### cidrSubnet
177

178
Calculates subnet information from CIDR notation, providing the same detailed analysis as the `subnet` function.
179

180
```javascript { .api }
181
/**
182
 * Calculates subnet information from CIDR notation
183
 * @param {string} cidrString - CIDR notation (e.g., '192.168.1.134/26')
184
 * @returns {SubnetInfo} Same object as subnet() function
185
 * @throws {Error} Throws error for invalid CIDR format
186
 */
187
function cidrSubnet(cidrString);
188
```
189

190
**Usage Examples:**
191

192
```javascript
193
const ip = require('ip');
194

195
const subnet = ip.cidrSubnet('192.168.1.134/26');
196

197
console.log(subnet.networkAddress);    // '192.168.1.128'
198
console.log(subnet.broadcastAddress);  // '192.168.1.191'
199
console.log(subnet.numHosts);          // 62
200
console.log(subnet.subnetMaskLength);  // 26
201

202
// Range checking with CIDR subnet
203
console.log(subnet.contains('192.168.1.180')); // true
204
console.log(subnet.contains('192.168.1.195')); // false
205

206
// Common network sizes
207
const classC = ip.cidrSubnet('192.168.1.0/24');
208
console.log(classC.numHosts); // 254
209

210
const classB = ip.cidrSubnet('172.16.0.0/16');  
211
console.log(classB.numHosts); // 65534
212

213
const classA = ip.cidrSubnet('10.0.0.0/8');
214
console.log(classA.numHosts); // 16777214
215
```