`maxminddb` WASM

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

Node.js
Deno
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/bundler";

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/bundler";

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

`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:

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.

maxminddb WASM