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
• [/] Browser (tests are flaky, so not certain)
• [?] Cloudflare Workers (have not been able to get them to work locally, you can see the tests here)

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);

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);

Browser

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

// Fetch the database file
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 { Maxmind } from 'maxminddb-wasm/browser';

export default {
  async fetch(request, env) {
    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.

lookup_prefix(ip: string): PrefixResponse

Looks up network prefix information for the given IP address.

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

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

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 will download the test database from the Maxmind github repo.