IPGeolocation MMDB Reader for Node.js

A fast, minimal, dependency-free Node.js reader for MMDB database files.

• Zero runtime dependencies
• Supports IPv4 and IPv6 lookups
• Works with IPGeolocation.io MMDB databases and other MaxMind DB format files
• CommonJS package
• TypeScript declarations included

Requirements

• Node.js 16 or later
• An MMDB database file

Installation

npm install ipgeolocation-mmdb-reader

Getting a Database

To use this package, you need an MMDB file. You can use your own MMDB database or download database samples from IPGeolocation.io:

https://ipgeolocation.io/ip-geolocation-database.html

Downloaded database files may be compressed, so unzip them before passing the .mmdb file path to the reader.

Quick Start

const { IPGeolocationMMDBReader } = require("ipgeolocation-mmdb-reader");

const reader = new IPGeolocationMMDBReader("db-ip-city-company-asn.mmdb");

const result = reader.lookup("1.1.1.1");

if (result === null) {
  console.log("No match");
} else {
  console.log(JSON.stringify(result, null, 2));
}

reader.close();

Metadata

const { IPGeolocationMMDBReader } = require("ipgeolocation-mmdb-reader");

const reader = new IPGeolocationMMDBReader("db-ip-city-company-asn.mmdb");

console.log(JSON.stringify(reader.getMetadata(), null, 2));

reader.close();

API

new IPGeolocationMMDBReader(filename)

Loads an MMDB file from disk and parses its metadata.

lookup(ip)

Looks up a single IPv4 or IPv6 address.

Returns the decoded database record, or null if no matching record exists.

const result = reader.lookup("8.8.8.8");

lookupMany(ips)

Looks up multiple IP addresses and returns an array of [ip, result] pairs.

Each result is either the decoded database record or null if no matching record exists.

const results = reader.lookupMany(["1.1.1.1", "8.8.8.8"]);

for (const [ip, result] of results) {
  console.log(ip, result);
}

getMetadata()

Returns a shallow copy of the MMDB metadata object.

close()

Clears internal caches.

The reader loads the file into memory, so there is no open file descriptor after construction.

Errors

The package exports custom error classes so callers can distinguish invalid input, invalid database files, and unsupported MMDB layouts.

MMDBError

Base error for reader-specific failures.

This is also raised when an IP address string is invalid, or when an IPv6 address is queried against an IPv4-only database.

MetadataError

Raised when the file does not look like a valid MMDB database, the metadata marker cannot be found, or required metadata fields are missing.

CorruptDatabaseError

Raised when the database structure is inconsistent, such as invalid map keys, invalid boolean encoding, container length mismatch, or overlapping data and metadata sections.

UnsupportedRecordSizeError

Raised when the database uses an unsupported MMDB record size. This reader supports record sizes 24, 28, and 32.

const {
  IPGeolocationMMDBReader,
  MMDBError,
  MetadataError,
  CorruptDatabaseError,
  UnsupportedRecordSizeError,
} = require("ipgeolocation-mmdb-reader");

try {
  const reader = new IPGeolocationMMDBReader("database.mmdb");
  const result = reader.lookup("1.1.1.1");
  console.log(result);
  reader.close();
} catch (error) {
  if (error instanceof MetadataError) {
    console.error("The MMDB file metadata is missing or invalid.");
  } else if (error instanceof CorruptDatabaseError) {
    console.error("The MMDB file appears to be corrupt.");
  } else if (error instanceof UnsupportedRecordSizeError) {
    console.error("The MMDB record size is not supported.");
  } else if (error instanceof MMDBError) {
    console.error(error.message);
  } else {
    throw error;
  }
}

TypeScript

Type declarations are included.

import { IPGeolocationMMDBReader } from "ipgeolocation-mmdb-reader";

const reader = new IPGeolocationMMDBReader("database.mmdb");
const result = reader.lookup("1.1.1.1");
reader.close();

License

MIT