IP Range Converter & Lookup Utility (BigInt Optimized)

A high-performance Node.js / JavaScript utility designed to convert IPv4 ranges into BigInt formats, compute subnet blocks, and seamlessly fetch ISP/Provider telemetry data once a match is found.

By converting IP addresses and ranges into BigInt integers, this library enables rapid database lookups (e.g., WHERE ip_bigint BETWEEN start_bigint AND end_bigint) instead of expensive and slow string-based regular expression matches.

Key Features

• BigInt Conversion: Fast conversion of IPv4 strings (192.168.1.1) to BigInt numerical representations.
• Block Calculation: Automatically aggregates raw IP ranges into CIDR blocks (e.g., /24, /16) and computes total available host counts.
• High-Performance Search: Optimized range lookup using binary search or structured SQL indexing.
• Enrichment API Integration: Automated fallbacks to fetch real-time metadata (ISP, Organization, ASN, Location) via ipapi.is once an IP space is resolved.

Database Optimization Concept

Searching IP ranges using strings or CIDR notations inside a large dataset can heavily degrade query times. Converting to BigInt flattens the range into an efficient numerical continuum:

| IP Notation | Start (BigInt) | End (BigInt) | Total IPs | | :--- | :--- | :--- | :--- | | 41.61.0.0 - 41.61.255.255 | 691863552n | 691929087n | 65,536 (256 x /24) | | 196.43.195.0 - 196.43.195.255| 3291136768n | 3291137023n | 256 (1 x /24) |

Installation

npm install ip-range-bigint-lookup

Quick Start

1. Parsing Ranges & Calculating Blocks

const { ipToBigInt, calculateBlocks } = require('ip-range-bigint-lookup');

const range = {
  start: '196.220.32.0',
  end: '196.220.63.255'
};

const startBigInt = ipToBigInt(range.start); // 3296043008n
const endBigInt = ipToBigInt(range.end);     // 3296051199n

console.log(`BigInt Range: ${startBigInt}n to ${endBigInt}n`);

const analysis = calculateBlocks(range.start, range.end);
console.log(analysis);
// Output: { totalBlocks24: 32, totalAddresses: 8192 }

2. Matching and Fetching Provider Details

When a query target hits a pre-calculated internal range, the utility extracts full context by integrating with the ipapi.is live data stream.

const { LookupEngine } = require('ip-range-bigint-lookup');

const engine = new LookupEngine();

// Seed your local internal ranges
engine.addRange('41.61.0.0', '41.61.255.255', { providerId: 'ISP-ALPHA' });

async function checkAndEnrich(targetIp) {
  const match = engine.find(targetIp);
  
  if (match) {
    console.log(`Match Found locally! Fetching comprehensive provider data...`);
    
    // Fetch live intelligence data from ipapi.is
    const response = await fetch(`https://api.ipapi.is/?q=${targetIp}`);
    const data = await response.json();
    
    console.log('--- Provider Intel ---');
    console.log(`ASN: ${data.asn.asn}`);
    console.log(`Org: ${data.asn.org}`);
    console.log(`ISP: ${data.company.name}`);
    console.log(`Location: ${data.location.country}, ${data.location.city}`);
  } else {
    console.log('IP is outside tracked blocks.');
  }
}

checkAndEnrich('41.61.5.12');

API Reference

ipToBigInt(ipString)

Converts an IPv4 string into a safe mathematical BigInt.

calculateBlocks(startIp, endIp)

Parses the difference between two IP thresholds and returns the total count of /24 sub-allocations along with raw address metrics.

LookupEngine.find(ipString)

Executes an in-memory binary search against configured range boundaries using BigInt logic. Returns the matching context or null.

STRUCTURE PROJECT

ip-bigint-lookup/ ├── src/ │ ├── utils.js # Fungsi konversi BigInt & hitung blok │ ├── engine.js # Class untuk pencarian/matching IP │ └── index.js # Entry point utama library ├── example/ │ └── test.js # Contoh implementasi & uji coba kode ├── package.json # Konfigurasi project npm └── README.md # Dokumentasi (yang sudah dibuat sebelumnya)

License

MIT