diff --git a/.eslintrc.js b/.eslintrc.js index e325df1..18ccded 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -1,29 +1,30 @@ module.exports = { - 'env': { - 'browser': true, - 'commonjs': true, - 'es2021': true - }, - 'extends': 'eslint:recommended', - 'parserOptions': { - 'ecmaVersion': 'latest' - }, - 'rules': { - 'indent': [ - 'error', - 2 - ], - 'linebreak-style': [ - 'error', - 'unix' - ], - 'quotes': [ - 'error', - 'single' - ], - 'semi': [ - 'error', - 'always' - ] - } + 'env': { + 'node': true, + 'browser': true, + 'commonjs': true, + 'es2021': true + }, + 'extends': 'eslint:recommended', + 'parserOptions': { + 'ecmaVersion': 'latest' + }, + 'rules': { + 'indent': [ + 'error', + 2 + ], + 'linebreak-style': [ + 'error', + 'unix' + ], + 'quotes': [ + 'error', + 'single' + ], + 'semi': [ + 'error', + 'always' + ] + } }; diff --git a/README.md b/README.md index 402b0c6..7f3693e 100644 --- a/README.md +++ b/README.md @@ -84,6 +84,12 @@ var normalized = ip.normalizeLax('0x7f.1'); // 127.0.0.1 ip.isPrivate(normalized); // true ``` +## Contributors + +[![Contributors](https://contrib.rocks/image?repo=eggjs/node-ip)](https://github.com/eggjs/node-ip/graphs/contributors) + +Made with [contributors-img](https://contrib.rocks). + ### License ```txt diff --git a/index.d.ts b/index.d.ts new file mode 100644 index 0000000..b63de6d --- /dev/null +++ b/index.d.ts @@ -0,0 +1,119 @@ +/// + +export interface SubnetInfo { + networkAddress: string; + firstAddress: string; + lastAddress: string; + broadcastAddress: string; + subnetMask: string; + subnetMaskLength: number; + numHosts: number; + length: number; + contains(ip: string): boolean; +} + +/** +* Check two IP address are the same. +*/ +export function isEqual(ip1: string, ip2: string): boolean; + +/** +* Convert an IP string into a buffer. +*/ +export function toBuffer(ip: string, buffer?: Buffer, offset?: number): Buffer; + +/** +* Convert an IP buffer into a string. +*/ +export function toString(ip: Buffer, offset?: number, length?: number): string; + +/** +* Get the subnet mask from a CIDR prefix length. +* +* @param family The IP family is infered from the prefixLength, but can be explicity specified as either "ipv4" or "ipv6". +*/ +export function fromPrefixLen(prefixLength: number, family?: "ipv4" | "ipv6"): string; + +/** +* Get the network ID IP address from an IP address and its subnet mask. +*/ +export function mask(ip: string, mask: string): string; + +/** +* Get the network ID IP address from an IP address in CIDR notation. +*/ +export function cidr(cidr: string): string; + +/** +* Get the bitwise inverse (NOT every octet) of an IP address or subnet mask. +*/ +export function not(ip: string): string; + +/** +* Get the bitwise OR of two IP addresses (usually an IP address and a subnet mask). +*/ +export function or(ip: string, mask: string): string; + +/** +* Check whether an IP is within a private IP address range. +*/ +export function isPrivate(ip: string): boolean; + +/** +* Check whether an IP is within a public IP address range. +*/ +export function isPublic(ip: string): boolean; + +/** +* Check whether an IP is a loopback address. +*/ +export function isLoopback(ip: string): boolean; + +/** +* Check whether an IP is a IPv4 address. +*/ +export function isV4Format(ip: string): boolean; + +/** +* Check whether an IP is a IPv6 address. +*/ +export function isV6Format(ip: string): boolean; + +/** +* Get the loopback address for an IP family. +* +* @param family The family can be either "ipv4" or "ipv6". Default: "ipv4". +*/ +export function loopback(family?: "ipv4" | "ipv6"): string; + +/** +* Get the address for the network interface on the current system with the specified 'name'. +* If no interface name is specified, the first IPv4 address or loopback address is returned. +* +* @param name The name can be any named interface, or 'public' or 'private'. +* @param family The family can be either "ipv4" or "ipv6". Default: "ipv4". +*/ +export function address(name?: "public" | "private" | string, family?: "ipv4" | "ipv6"): string; + +/** +* Convert a string IPv4 IP address to the equivalent long numeric value. +*/ +export function toLong(ip: string): number; + +/** +* Convert an IPv4 IP address from its the long numeric value to a string. +*/ +export function fromLong(ip: number): string; + +/** +* Get the subnet information. +* @param ip IP address. +* @param subnet Subnet address. +*/ +export function subnet(ip: string, subnet: string): SubnetInfo; + +/** +* Get the subnet information. +* @param cidr CIDR address. +*/ +export function cidrSubnet(cidr: string): SubnetInfo; diff --git a/index.test-d.ts b/index.test-d.ts new file mode 100644 index 0000000..a3dc024 --- /dev/null +++ b/index.test-d.ts @@ -0,0 +1,5 @@ +import { expectType } from 'tsd'; +import ip, { isV4Format } from '.'; + +expectType(ip.address()); +expectType(isV4Format('127.0.0.1')); diff --git a/lib/ip.js b/lib/ip.js index 9850e17..4c8af1c 100644 --- a/lib/ip.js +++ b/lib/ip.js @@ -1,5 +1,4 @@ const ip = exports; -const { Buffer } = require('buffer'); const os = require('os'); const net = require('net'); diff --git a/package.json b/package.json index 62df946..56605f5 100644 --- a/package.json +++ b/package.json @@ -15,18 +15,23 @@ }, "files": [ "lib", + "index.d.ts", "README.md" ], "main": "lib/ip", + "types": "index.d.ts", "devDependencies": { + "@types/node": "^22.10.5", "egg-bin": "^6.10.0", - "eslint": "^8.15.0" + "eslint": "^8.15.0", + "tsd": "^0.31.2" }, "scripts": { "lint": "eslint lib test", - "test": "npm run lint && egg-bin test --ts false", - "fix": "npm run lint -- --fix", - "ci": "npm run lint && egg-bin cov --ts false" + "pretest": "npm run lint -- --fix && tsd", + "test": "egg-bin test --ts false", + "preci": "npm run lint && tsd", + "ci": "egg-bin cov --ts false" }, "license": "MIT" }