A library that enables the usage of MaxmindDB geoIP databases by using the Rust library in a WebAssembly module

About

Uses the Rust MaxmindDB library to create a WASM binary that lets you query MaxMind databases directly in JavaScript/TypeScript.

Status

• [x] Node.js
• [x] Deno
• [x] Bun
• [x] Browser
• [x] Cloudflare Workers

Installation

Node.js / Browser (npm)

npm install maxminddb-wasm
# or
pnpm add maxminddb-wasm

Deno (jsr)

import { Maxmind } from "jsr:@josh-hemphill/maxminddb-wasm";

Usage Examples

Node.js

import { readFile } from 'node:fs/promises';
import { Maxmind } from 'maxminddb-wasm/node-module';

const dbFile = await readFile('./GeoLite2-City.mmdb');
const maxmind = new Maxmind(dbFile);
const result = maxmind.lookup_city('8.8.8.8');
console.log(result);

// ASN / ISP database (separate .mmdb file from MaxMind)
const asnDb = await readFile('./GeoLite2-ASN.mmdb');
const asnReader = new Maxmind(asnDb);
console.log(asnReader.lookup_isp('8.8.8.8'));

// Country database
const countryDb = await readFile('./GeoLite2-Country.mmdb');
console.log(new Maxmind(countryDb).lookup_country('8.8.8.8'));

Deno

import { Maxmind } from "jsr:@josh-hemphill/maxminddb-wasm";

const dbFile = await Deno.readFile('./GeoLite2-City.mmdb');
const maxmind = new Maxmind(dbFile);
const result = maxmind.lookup_city('8.8.8.8');
console.log(result);

const asnDb = await Deno.readFile('./GeoLite2-ASN.mmdb');
console.log(new Maxmind(asnDb).lookup_isp('8.8.8.8'));

Browser

import init, { Maxmind } from 'maxminddb-wasm/browser';

await init();

const response = await fetch('/GeoLite2-City.mmdb');
const dbFile = new Uint8Array(await response.arrayBuffer());
const maxmind = new Maxmind(dbFile);
const result = maxmind.lookup_city('8.8.8.8');

Cloudflare Workers

import init, { Maxmind } from 'maxminddb-wasm/browser';
import wasmModule from 'maxminddb-wasm/browser/index_bg.wasm';

export default {
  async fetch(request, env) {
    await init({ module_or_path: wasmModule });
    const maxmind = new Maxmind(new Uint8Array(env.MAXMIND_DB));
    const ip = request.headers.get('cf-connecting-ip');
    const result = maxmind.lookup_city(ip);
    return new Response(JSON.stringify(result));
  }
};

Bun

import { Maxmind } from 'maxminddb-wasm/node-module';

const dbFile = await Bun.file('./GeoLite2-City.mmdb').arrayBuffer();
const maxmind = new Maxmind(new Uint8Array(dbFile));
const result = maxmind.lookup_city('8.8.8.8');

API Reference

Maxmind Class

Constructor

new Maxmind(dbFile: Uint8Array)

Creates a new Maxmind instance with the provided database file.

Methods

lookup_city(ip: string): CityResponse

Looks up city information for the given IP address. Also works with GeoLite2-Country databases for the overlapping country/continent fields; prefer lookup_country when you only need country data.

lookup_country(ip: string): CountryResponse

Looks up country/continent information for the given IP address. Intended for GeoLite2-Country / GeoIP2-Country databases (also works with City databases).

lookup_prefix(ip: string): PrefixResponse

Looks up network prefix information for the given IP address.

lookup_isp(ip: string): IspResponse

Looks up ISP and ASN fields for the given IP address. The loaded database must be a compatible product (for example GeoLite2-ASN or GeoIP2-ISP). City databases do not contain these records.

lookup_isp_prefix(ip: string): IspPrefixResponse

Same as lookup_isp, plus the network prefix length for the matched entry (mirrors lookup_prefix for city data).

metadata: Metadata

Read-only property that returns database metadata.

Response Types

CityResponse

interface CityResponse {
    city?: CityRecord;
    continent?: ContinentRecord;
    country?: CountryRecord;
    subdivisions?: SubdivisionRecord[];
    location?: LocationRecord;
}

CityRecord

interface CityRecord {
    geoname_id?: number;
    names?: Record<string, string>;
}

ContinentRecord

interface ContinentRecord {
    code?: string;
    geoname_id?: number;
    names?: Record<string, string>;
}

CountryRecord

interface CountryRecord {
    geoname_id?: number;
    iso_code?: string;
    names?: Record<string, string>;
}

CountryResponse

interface CountryResponse {
    continent?: ContinentRecord;
    country?: CountryRecord;
}

SubdivisionRecord

interface SubdivisionRecord {
    geoname_id?: number;
    iso_code?: string;
    names?: Record<string, string>;
}

LocationRecord

interface LocationRecord {
    latitude?: number;
    longitude?: number;
    time_zone?: string;
}

PrefixResponse

interface PrefixResponse {
    city: CityResponse;
    prefix_length: number;
}

IspResponse

interface IspResponse {
    asn?: AsnResponse;
    isp?: string;
    organization?: string;
    mobile_country_code?: string;
    mobile_network_code?: string;
}

AsnResponse

interface AsnResponse {
    as_num?: number;
    as_organization?: string;
}

IspPrefixResponse

interface IspPrefixResponse {
    isp: IspResponse;
    prefix_length: number;
}

Metadata

interface Metadata {
    binary_format_major_version: number;
    binary_format_minor_version: number;
    build_epoch: number;
    database_type: string;
    description: Record<string, string>;
    ip_version: number;
    languages: string[];
    node_count: number;
    record_size: number;
}

Contributing

Build Setup

For running the automated build (which includes compiling the rust wasm) you'll need the following tools installed:

• node
• pnpm
• Rust

Once you have all the necessary tools installed, you can just run pnpm build

Testing

Under tests/*, there are tests for each platform that can be run with the pnpm test command. On first run, it downloads the City, Country, and ASN MaxMind test databases.