bandeng-ip

English | 中文

English

A simple and easy-to-use IPv4 address toolkit that provides IP address validation, conversion, network segment determination, CIDR parsing, and more.

Requirements

• Node.js: >= 10.0.0
• Platform: Node.js runtime environment

This package is designed for Node.js only and does not support browser environments.

Installation

npm install bandeng-ip

Usage

const {
    getHttpRealIpv4String,
    getLocalIpv4String,
    isValidIpv4String,
    ipv4ToNumber,
    numberToIpv4,
    isPrivateIpv4,
    isPublicIpv4,
    isIpv4InNetwork,
    getIpv4NetworkInfo,
    compareIpv4,
    parseCidr,
    isIpv4InCidr,
    getSubnetMask,
    getAllLocalIpv4Strings,
    getAllLocalIpv4StringsIncludingInternal
} = require('bandeng-ip')

API Documentation

getHttpRealIpv4String(request)

Extract the real client IPv4 string, supporting Express and Koa frameworks.

Parameters:

• request (Object): Request object (Koa ctx or Express req)

Returns:

• string: Client IPv4 string, returns "-" if not found

Example:

// Express
app.get('/', (req, res) => {
    const clientIP = getHttpRealIpv4String(req)
    console.log('Client IP:', clientIP)
})

// Koa
app.use(async (ctx, next) => {
    const clientIP = getHttpRealIpv4String(ctx)
    console.log('Client IP:', clientIP)
    await next()
})

getLocalIpv4String()

Get the local machine IPv4 string.

Returns:

• string: Local machine IPv4 string, returns "-" if not found

Example:

const localIP = getLocalIpv4String()
console.log('Local IP:', localIP) // e.g.: "192.168.1.100"

isValidIpv4String(ip)

Validate IPv4 address format.

Parameters:

• ip (string): IPv4 address string

Returns:

• boolean: Whether it is a valid IPv4 address

Example:

isValidIpv4String('192.168.1.1') // true
isValidIpv4String('256.1.1.1') // false
isValidIpv4String('invalid') // false

ipv4ToNumber(ip)

Convert IPv4 address to 32-bit integer.

Parameters:

• ip (string): IPv4 address string

Returns:

• number|null: 32-bit integer, returns null for invalid IP

Example:

ipv4ToNumber('192.168.1.1') // 3232235777
ipv4ToNumber('0.0.0.0') // 0
ipv4ToNumber('255.255.255.255') // 4294967295

numberToIpv4(num)

Convert 32-bit integer to IPv4 address string.

Parameters:

• num (number): 32-bit integer

Returns:

• string|null: IPv4 address string, returns null for invalid number

Example:

numberToIpv4(3232235777) // "192.168.1.1"
numberToIpv4(0) // "0.0.0.0"
numberToIpv4(4294967295) // "255.255.255.255"

isPrivateIpv4(ip)

Determine if an IPv4 address is a private address (including 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8, 169.254.0.0/16).

Parameters:

• ip (string): IPv4 address string

Returns:

• boolean: Whether it is a private address

Example:

isPrivateIpv4('192.168.1.1') // true
isPrivateIpv4('10.0.0.1') // true
isPrivateIpv4('127.0.0.1') // true
isPrivateIpv4('8.8.8.8') // false

isPublicIpv4(ip)

Determine if an IPv4 address is a public address.

Parameters:

• ip (string): IPv4 address string

Returns:

• boolean: Whether it is a public address

Example:

isPublicIpv4('8.8.8.8') // true
isPublicIpv4('192.168.1.1') // false

isIpv4InNetwork(ip, network, mask)

Determine if an IPv4 address is within a specified network segment.

Parameters:

• ip (string): IPv4 address to check
• network (string): Network address (e.g.: 192.168.1.0)
• mask (number): Subnet mask bits (e.g.: 24)

Returns:

• boolean: Whether it is within the network segment

Example:

isIpv4InNetwork('192.168.1.100', '192.168.1.0', 24) // true
isIpv4InNetwork('192.168.2.100', '192.168.1.0', 24) // false

getIpv4NetworkInfo(ip, mask)

Get network segment information for an IPv4 address.

Parameters:

• ip (string): IPv4 address string
• mask (number): Subnet mask bits (e.g.: 24)

Returns:

• Object|null: Network segment information object {network, broadcast, first, last}, returns null for invalid parameters

Example:

getIpv4NetworkInfo('192.168.1.100', 24)
// {
//   network: "192.168.1.0",
//   broadcast: "192.168.1.255",
//   first: "192.168.1.1",
//   last: "192.168.1.254"
// }

compareIpv4(ip1, ip2)

Compare the size of two IPv4 addresses.

Parameters:

• ip1 (string): First IPv4 address
• ip2 (string): Second IPv4 address

Returns:

• number|null: -1 means ip1 < ip2, 0 means ip1 = ip2, 1 means ip1 > ip2, returns null for invalid IP

Example:

compareIpv4('192.168.1.1', '192.168.1.2') // -1
compareIpv4('192.168.1.1', '192.168.1.1') // 0
compareIpv4('192.168.1.2', '192.168.1.1') // 1

parseCidr(cidr)

Convert CIDR format to network segment information.

Parameters:

• cidr (string): CIDR format string (e.g.: 192.168.1.0/24)

Returns:

• Object|null: Network segment information object {ip, mask, network, broadcast, first, last}, returns null for invalid CIDR

Example:

parseCidr('192.168.1.0/24')
// {
//   ip: "192.168.1.0",
//   mask: 24,
//   network: "192.168.1.0",
//   broadcast: "192.168.1.255",
//   first: "192.168.1.1",
//   last: "192.168.1.254"
// }

isIpv4InCidr(ip, cidr)

Determine if an IPv4 address is within a CIDR network segment.

Parameters:

• ip (string): IPv4 address to check
• cidr (string): CIDR format string (e.g.: 192.168.1.0/24)

Returns:

• boolean: Whether it is within the network segment

Example:

isIpv4InCidr('192.168.1.100', '192.168.1.0/24') // true
isIpv4InCidr('192.168.2.100', '192.168.1.0/24') // false

getSubnetMask(mask)

Get the subnet mask string for an IPv4 address.

Parameters:

• mask (number): Subnet mask bits (0-32)

Returns:

• string|null: Subnet mask string (e.g.: 255.255.255.0), returns null for invalid parameters

Example:

getSubnetMask(24) // "255.255.255.0"
getSubnetMask(16) // "255.255.0.0"
getSubnetMask(8) // "255.0.0.0"

getAllLocalIpv4Strings()

Get all local machine IPv4 addresses (excluding private addresses).

Returns:

• Array<string>: Array of all local machine IPv4 addresses

Example:

const ips = getAllLocalIpv4Strings()
console.log(ips) // ["192.168.1.100", "10.0.0.5"]

getAllLocalIpv4StringsIncludingInternal()

Get all local machine IPv4 addresses (including private addresses).

Returns:

• Array<string>: Array of all local machine IPv4 addresses (including private addresses)

Example:

const ips = getAllLocalIpv4StringsIncludingInternal()
console.log(ips) // ["192.168.1.100", "127.0.0.1", "10.0.0.5"]

Use Cases

• Web Server: Extract real client IP addresses from HTTP requests
• Network Management: Determine IP address types (private/public)
• Security Control: Access control based on IP address ranges
• Network Configuration: Parse CIDR format and get network segment information
• System Monitoring: Get local machine network interface information

License

MIT

Author

lizhi

中文

一个简单易用的 IPv4 地址工具集，提供 IP 地址验证、转换、网段判断、CIDR 解析等功能。

环境要求

• Node.js: >= 10.0.0
• 平台: Node.js 运行时环境

本包专为 Node.js 设计，不支持浏览器环境。

安装

npm install bandeng-ip

使用方法

const {
    getHttpRealIpv4String,
    getLocalIpv4String,
    isValidIpv4String,
    ipv4ToNumber,
    numberToIpv4,
    isPrivateIpv4,
    isPublicIpv4,
    isIpv4InNetwork,
    getIpv4NetworkInfo,
    compareIpv4,
    parseCidr,
    isIpv4InCidr,
    getSubnetMask,
    getAllLocalIpv4Strings,
    getAllLocalIpv4StringsIncludingInternal
} = require('bandeng-ip')

API 文档

getHttpRealIpv4String(request)

提取真实的客户端 IPv4 字符串，支持 Express 和 Koa 框架。

参数：

• request (Object): 请求对象（Koa ctx 或 Express req）

返回：

• string: 客户端 IPv4 字符串，未获取到则返回 "-"

示例：

// Express
app.get('/', (req, res) => {
    const clientIP = getHttpRealIpv4String(req)
    console.log('客户端IP:', clientIP)
})

// Koa
app.use(async (ctx, next) => {
    const clientIP = getHttpRealIpv4String(ctx)
    console.log('客户端IP:', clientIP)
    await next()
})

getLocalIpv4String()

获取本机 IPv4 字符串。

返回：

• string: 本机 IPv4 字符串，未获取到则返回 "-"

示例：

const localIP = getLocalIpv4String()
console.log('本机IP:', localIP) // 例如: "192.168.1.100"

isValidIpv4String(ip)

验证 IPv4 地址格式。

参数：

• ip (string): IPv4 地址字符串

返回：

• boolean: 是否为有效的 IPv4 地址

示例：

isValidIpv4String('192.168.1.1') // true
isValidIpv4String('256.1.1.1') // false
isValidIpv4String('invalid') // false

ipv4ToNumber(ip)

将 IPv4 地址转换为 32 位整数。

参数：

• ip (string): IPv4 地址字符串

返回：

• number|null: 32 位整数，无效 IP 返回 null

示例：

ipv4ToNumber('192.168.1.1') // 3232235777
ipv4ToNumber('0.0.0.0') // 0
ipv4ToNumber('255.255.255.255') // 4294967295

numberToIpv4(num)

将 32 位整数转换为 IPv4 地址字符串。

参数：

• num (number): 32 位整数

返回：

• string|null: IPv4 地址字符串，无效数字返回 null

示例：

numberToIpv4(3232235777) // "192.168.1.1"
numberToIpv4(0) // "0.0.0.0"
numberToIpv4(4294967295) // "255.255.255.255"

isPrivateIpv4(ip)

判断 IPv4 地址是否为内网地址（包括 10.0.0.0/8、172.16.0.0/12、192.168.0.0/16、127.0.0.0/8、169.254.0.0/16）。

参数：

• ip (string): IPv4 地址字符串

返回：

• boolean: 是否为内网地址

示例：

isPrivateIpv4('192.168.1.1') // true
isPrivateIpv4('10.0.0.1') // true
isPrivateIpv4('127.0.0.1') // true
isPrivateIpv4('8.8.8.8') // false

isPublicIpv4(ip)

判断 IPv4 地址是否为公网地址。

参数：

• ip (string): IPv4 地址字符串

返回：

• boolean: 是否为公网地址

示例：

isPublicIpv4('8.8.8.8') // true
isPublicIpv4('192.168.1.1') // false

isIpv4InNetwork(ip, network, mask)

判断 IPv4 地址是否在指定网段内。

参数：

• ip (string): 要检查的 IPv4 地址
• network (string): 网段地址（如：192.168.1.0）
• mask (number): 子网掩码位数（如：24）

返回：

• boolean: 是否在网段内

示例：

isIpv4InNetwork('192.168.1.100', '192.168.1.0', 24) // true
isIpv4InNetwork('192.168.2.100', '192.168.1.0', 24) // false

getIpv4NetworkInfo(ip, mask)

获取 IPv4 地址的网段信息。

参数：

• ip (string): IPv4 地址字符串
• mask (number): 子网掩码位数（如：24）

返回：

• Object|null: 网段信息对象 {network, broadcast, first, last}，无效参数返回 null

示例：

getIpv4NetworkInfo('192.168.1.100', 24)
// {
//   network: "192.168.1.0",
//   broadcast: "192.168.1.255",
//   first: "192.168.1.1",
//   last: "192.168.1.254"
// }

compareIpv4(ip1, ip2)

比较两个 IPv4 地址的大小。

参数：

• ip1 (string): 第一个 IPv4 地址
• ip2 (string): 第二个 IPv4 地址

返回：

• number|null: -1 表示 ip1 < ip2，0 表示 ip1 = ip2，1 表示 ip1 > ip2，无效 IP 返回 null

示例：

compareIpv4('192.168.1.1', '192.168.1.2') // -1
compareIpv4('192.168.1.1', '192.168.1.1') // 0
compareIpv4('192.168.1.2', '192.168.1.1') // 1

parseCidr(cidr)

将 CIDR 格式转换为网段信息。

参数：

• cidr (string): CIDR 格式字符串（如：192.168.1.0/24）

返回：

• Object|null: 网段信息对象 {ip, mask, network, broadcast, first, last}，无效 CIDR 返回 null

示例：

parseCidr('192.168.1.0/24')
// {
//   ip: "192.168.1.0",
//   mask: 24,
//   network: "192.168.1.0",
//   broadcast: "192.168.1.255",
//   first: "192.168.1.1",
//   last: "192.168.1.254"
// }

isIpv4InCidr(ip, cidr)

判断 IPv4 地址是否在 CIDR 网段内。

参数：

• ip (string): 要检查的 IPv4 地址
• cidr (string): CIDR 格式字符串（如：192.168.1.0/24）

返回：

• boolean: 是否在网段内

示例：

isIpv4InCidr('192.168.1.100', '192.168.1.0/24') // true
isIpv4InCidr('192.168.2.100', '192.168.1.0/24') // false

getSubnetMask(mask)

获取 IPv4 地址的子网掩码字符串。

参数：

• mask (number): 子网掩码位数（0-32）

返回：

• string|null: 子网掩码字符串（如：255.255.255.0），无效参数返回 null

示例：

getSubnetMask(24) // "255.255.255.0"
getSubnetMask(16) // "255.255.0.0"
getSubnetMask(8) // "255.0.0.0"

getAllLocalIpv4Strings()

获取本机所有 IPv4 地址（不包括内网地址）。

返回：

• Array<string>: 本机所有 IPv4 地址数组

示例：

const ips = getAllLocalIpv4Strings()
console.log(ips) // ["192.168.1.100", "10.0.0.5"]

getAllLocalIpv4StringsIncludingInternal()

获取本机所有 IPv4 地址（包括内网地址）。

返回：

• Array<string>: 本机所有 IPv4 地址数组（包括内网地址）

示例：

const ips = getAllLocalIpv4StringsIncludingInternal()
console.log(ips) // ["192.168.1.100", "127.0.0.1", "10.0.0.5"]

使用场景

• Web 服务器：从 HTTP 请求中提取客户端真实 IP 地址
• 网络管理：判断 IP 地址类型（内网/公网）
• 安全控制：根据 IP 地址范围进行访问控制
• 网络配置：解析 CIDR 格式，获取网段信息
• 系统监控：获取本机网络接口信息

许可证

MIT

作者

lizhi