maxmind

maxmind is a TypeScript-first Node.js library for performing IP geolocation lookups against MaxMind’s binary MMDB database format (GeoIP2 and GeoLite2). It reads the .mmdb file directly rather than converting it to CSV or another intermediate format, which keeps lookups fast and memory-efficient — the project claims lookups up to 17,000% faster than comparable libraries that rely on format conversions.

The library exposes both an async open() API for loading databases from disk and a synchronous Reader class for cases where the database buffer is already available (e.g. fetched over the network or read manually). It fully supports IPv4 and IPv6 lookups through the same API, ships with an in-memory LRU cache for repeated lookups, and can optionally watch the database file on disk and hot-reload it when MaxMind publishes updates — useful for long-running services that need fresh geolocation data without a restart.

What You Get

• Async open() and sync Reader APIs for loading MMDB databases from disk or a buffer
• Typed response interfaces for CityResponse, CountryResponse, AsnResponse, IspResponse, ConnectionTypeResponse, DomainResponse, and AnonymousIPResponse
• Built-in IPv4/IPv6 validation helpers via maxmind.validate()
• An in-memory LRU cache (via tiny-lru) to speed up repeated lookups
• Optional watchForUpdates support to hot-reload the database file when it changes on disk

Common Use Cases

• Geo-targeting or content localization based on a visitor’s IP address
• Fraud detection and risk scoring using ASN/ISP/anonymous-IP data
• Analytics pipelines that enrich request logs with country/city-level location data
• Access control or compliance systems that need to restrict or flag requests by geography

Under The Hood

Architecture — The library is thin by design: src/index.ts orchestrates file reads (src/fs.ts, a promisified wrapper around Node’s fs), gzip-file detection (src/is-gzip.ts) to reject mis-supplied files, and IP parsing/validation (src/ip.ts, with manual IPv4/IPv6 octet parsing), while delegating the actual MMDB binary decoding to the companion mmdb-lib package (re-exported as Reader/Response). For files over 512MB it switches from fs.readFile to a manual streaming buffer-fill (readLargeFile) to work around Node’s ~2GB readFileSync limit. The optional watchForUpdates mode uses fs.watchFile polling plus an existence-retry loop to survive atomic file swaps, then calls reader.load() to hot-swap the in-memory database and clears the LRU cache.

Tech Stack — Written almost entirely in TypeScript (95% of the codebase), with just two runtime dependencies: mmdb-lib (an environment-agnostic MMDB binary decoder by the same maintainer) and tiny-lru (the LRU cache). Dev tooling includes Jest with @swc/jest for fast TS test transpilation, Prettier for formatting, and semantic-release for automated npm publishing; a leftover tslint.json sits alongside the modern tsconfig.json as a dual-tooling relic. Targets Node >=12.

Code Quality — The test suite spans four files (614 lines total): unit tests for index (open/watch/cache behavior), ip (IPv4/IPv6 parsing and validation), is-gzip (magic-byte detection), plus an integration test that runs real lookups against a bundled GeoIP2-City-Test.mmdb.gz fixture, alongside deliberately broken and legacy-format fixtures for error-path coverage. The README claims 100% test coverage. Code is small and mostly pure functions with clear naming, though the hand-rolled IPv6 parser in ip.ts duplicates functionality Node’s built-in net module partially covers, which is a modest maintenance/edge-case risk.

API Design — The public surface is minimal and idiomatic: a single open() async factory, a Reader class for synchronous use, and typed generics (Reader<T extends Response>) so consumers get compile-time-typed lookup results per MaxMind response type. Getting started takes one line (const lookup = await maxmind.open(...)), and the README clearly documents sync vs. async usage, IPv6 support, and the browser-incompatibility caveat (pointing to the companion mmdb-lib for browser use). A dedicated legacy-API error message helps v1/v2 users migrate safely across breaking changes.