About

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

$3

- [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

$3

``bash
npm install maxminddb-wasm


or

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

Usage Examples

$3

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

$3

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

$3

`ts
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');
`

$3

`ts
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));
}
};
`

$3

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

$3

#### Constructor

`ts
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.

$3

#### CityResponse

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

#### CityRecord

`ts
interface CityRecord {
geoname_id?: number;
names?: Record;
}
`

#### ContinentRecord

`ts
interface ContinentRecord {
code?: string;
geoname_id?: number;
names?: Record;
}
`

#### CountryRecord

`ts
interface CountryRecord {
geoname_id?: number;
iso_code?: string;
names?: Record;
}
`

#### SubdivisionRecord

`ts
interface SubdivisionRecord {
geoname_id?: number;
iso_code?: string;
names?: Record;
}
`

#### LocationRecord

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

#### PrefixResponse

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

#### Metadata

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

Contributing

$3

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

$3

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.