https://github.com/josh-hemphill/maxminddb-wasm
A library that enables the usage of MaxmindDB geoIP databases by using the Rust library in a WASM module
https://github.com/josh-hemphill/maxminddb-wasm
deno geoip maxmind wasm
Last synced: 8 months ago
JSON representation
A library that enables the usage of MaxmindDB geoIP databases by using the Rust library in a WASM module
- Host: GitHub
- URL: https://github.com/josh-hemphill/maxminddb-wasm
- Owner: josh-hemphill
- License: mit
- Created: 2021-03-10T16:54:37.000Z (about 5 years ago)
- Default Branch: dev
- Last Pushed: 2025-03-29T02:44:16.000Z (about 1 year ago)
- Last Synced: 2025-10-09T10:05:03.892Z (8 months ago)
- Topics: deno, geoip, maxmind, wasm
- Language: TypeScript
- Homepage:
- Size: 460 KB
- Stars: 14
- Watchers: 2
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-deno - maxminddb - A library that enables the usage of MaxmindDB geoIP database files (Modules / Database)
README
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](https://crates.io/crates/maxminddb) 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](https://github.com/josh-hemphill/maxminddb-wasm/blob/main/.github/workflows/test.yml))
## Installation
### Node.js / Browser (npm)
```bash
npm install maxminddb-wasm
# or
pnpm add maxminddb-wasm
```
### Deno ([jsr](https://jsr.io/docs/introduction))
```ts
import { Maxmind } from "jsr:@josh-hemphill/maxminddb-wasm/bundler";
```
## Usage Examples
### Node.js
```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);
```
### Deno
```ts
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
```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');
```
### Cloudflare Workers
```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));
}
};
```
### Bun
```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
### `Maxmind` Class
#### 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.
### Response Types
#### `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
### Build Setup
For running the automated build (which includes compiling the rust wasm) you'll need the following tools installed:
- [node](https://nodejs.org/en/download/)
- [pnpm](https://pnpm.io/installation)
- [Rust](https://doc.rust-lang.org/cargo/getting-started/installation.html)
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.