feat: add type define

.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'
+    ]
+  }
 };

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

index.d.ts

@@ -0,0 +1,119 @@
+/// <reference types="node" />
+
+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;

index.test-d.ts

@@ -0,0 +1,5 @@
+import { expectType } from 'tsd';
+import ip, { isV4Format } from '.';
+
+expectType<string>(ip.address());
+expectType<boolean>(isV4Format('127.0.0.1'));

lib/ip.js

@@ -1,5 +1,4 @@
 const ip = exports;
-const { Buffer } = require('buffer');
 const os = require('os');
 const net = require('net');
 

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"
 }