@oschwald/maxminddb 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-14
+
+### Added
+
+- Initial Rust-backed Node.js module for MaxMind DB files, published as
+  `@oschwald/maxminddb`.
+- Added a `node-maxmind`-compatible API with `open()`, `Reader`, `get()`,
+  `getWithPrefixLength()`, `load()`, `metadata`, `validate()`, and legacy
+  `init()`/`openSync()` error behavior.
+- Added file-backed and buffer-backed readers with `MODE_AUTO`, `MODE_MMAP`,
+  `MODE_MEMORY`, and `MODE_BUFFER` open modes.
+- Added optional watched reloads with serialized reload handling,
+  `lastReloadError`, and explicit watcher cleanup on `reader.close()`.
+- Added native LRU caching of materialized records with `cacheStats()` and
+  `clearCache()`.
+- Added path lookup extensions with `getPath()`, `getManyPath()`, and compiled
+  `reader.path()` lookups.
+- Added batch lookup support with `getMany()`.
+- Added lazy network iteration via native cursors, including `networks()`,
+  `within()`, `networkPages()`, `withinPages()`, and `NetworkIterator#nextPage()`.
+- Added TypeScript declarations for the public API.
+- Added benchmark tooling for comparing throughput against `node-maxmind`.
+- Added npm trusted publishing with prebuilt native binaries for Linux x64 GNU,
+  Linux arm64 GNU, macOS x64, macOS arm64, Windows x64 MSVC, and Windows arm64
+  MSVC.
+
+### Changed
+
+- The npm package is scoped as `@oschwald/maxminddb`; the Rust crate package is named
+  `maxminddb-node` to avoid colliding with the upstream Rust `maxminddb` crate.
+- Package metadata includes repository, homepage, bugs, author, export map, and
+  ISC license metadata.
+- Requires Node.js 20 or newer.
+
+### Fixed
+
+- Rejected gzip database inputs before opening.
+- Hardened watched reloads so failed reloads keep the existing reader active.
+- Hardened streamed large-file reads so truncated or growing files are rejected
+  instead of returning partially initialized buffers.
+- Added decode corpus regressions for mixed MaxMind DB value types.
+
+### Performance
+
+- Used memory-mapped file reads by default for fast opens and low RSS.
+- Added direct N-API decoding paths, cached property descriptor names, and an
+  IPv4 parser fast path for hot lookups.
+- Added batch lookup and native cursor APIs to reduce JavaScript/native boundary
+  crossings.
+
+### Development
+
+- Added CI for Node 20, 22, and 24, plus macOS and Windows coverage.
+- Added Rust formatting, `cargo check`, clippy, TypeScript, Node test, npm pack,
+  and packed-package smoke-test validation.
+
+[0.1.0]: https://github.com/oschwald/maxminddb-node/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2015, Gregory J. Oschwald <oschwald@gmail.com>
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# @oschwald/maxminddb
+
+Rust-backed Node.js reader for MaxMind DB files.
+
+The public API is compatible with the commonly used `maxmind` package from
+`node-maxmind` and adds Rust-backed extensions for path lookup, batch lookup,
+and network iteration.
+
+## Install
+
+Node.js 20 or newer is required.
+
+```sh
+npm install @oschwald/maxminddb
+```
+
+## Usage
+
+```js
+const maxmind = require('@oschwald/maxminddb');
+
+const reader = await maxmind.open('/path/to/GeoIP2-City.mmdb');
+
+console.log(reader.get('8.8.8.8'));
+console.log(reader.getWithPrefixLength('8.8.8.8'));
+console.log(reader.getPath('8.8.8.8', ['country', 'iso_code']));
+```
+
+## Compatibility API
+
+- `open(filepath, options?)`
+- `new Reader(buffer, options?)`
+- `reader.get(ipAddress)`
+- `reader.getWithPrefixLength(ipAddress)`
+- `reader.load(buffer)`
+- `reader.metadata`
+- `validate(ipAddress)`
+- `init()` and `openSync()` keep the legacy `node-maxmind` error behavior.
+
+`open()` accepts the existing `node-maxmind` options:
+
+- `cache`
+- `watchForUpdates`
+- `watchForUpdatesNonPersistent`
+- `watchForUpdatesHook`
+
+`cache` controls a native LRU cache of materialized records keyed by MaxMind DB
+data offset. The default is 10,000 records, matching `node-maxmind`. Pass
+`cache: { max: 1000 }` to tune the cache size or `cache: false` to disable it.
+Use `reader.cacheStats()` to inspect hit/miss counters and `reader.clearCache()`
+to release cached record references.
+
+The record cache stores JavaScript objects, not compressed database bytes. Large
+cache sizes can therefore retain significant heap memory when the database
+records are large or lookups touch many distinct data offsets. Cached records
+are returned by reference, so mutating a cached record can affect later lookups
+for the same data offset until that entry is evicted, `reader.clearCache()` is
+called, or the reader is closed. `getPath()`, `getManyPath()`, and compiled
+`reader.path()` lookups decode only the requested path and do not populate the
+full-record cache.
+
+When `watchForUpdates` is enabled, file-change reloads run serially. A failed
+watched reload leaves the existing reader active, stores the failure on
+`reader.lastReloadError`, and skips `watchForUpdatesHook`. The next successful
+reload clears `lastReloadError` and calls the hook. Close watched readers with
+`reader.close()` to remove the file watcher.
+
+## Extensions
+
+```js
+reader.getPath('8.8.8.8', ['country', 'iso_code']);
+reader.getMany(['8.8.8.8', '1.1.1.1']);
+reader.getManyPath(['8.8.8.8', '1.1.1.1'], ['country', 'iso_code']);
+
+const countryCode = reader.path(['country', 'iso_code']);
+countryCode.get('8.8.8.8');
+countryCode.getMany(['8.8.8.8', '1.1.1.1']);
+
+for (const [network, record] of reader.within('81.2.69.142/31')) {
+  console.log(network, record);
+}
+
+for (const page of reader.withinPages('81.2.69.0/24', { pageSize: 100 })) {
+  for (const [network, record] of page) {
+    console.log(network, record);
+  }
+}
+```
+
+Path elements are strings for map keys and numbers for array indexes. Negative
+indexes count from the end of an array.
+
+Create compiled path lookups once and reuse them in hot paths. `reader.path()`
+parses and stores the path, and the returned `PathLookup` avoids reparsing the
+path array on each lookup.
+
+For high-volume lookup workloads, prefer `getMany()` or `getManyPath()` when
+you can batch IPs. They cross the native boundary once for the whole batch and
+are significantly faster than calling `get()` in a JavaScript loop.
+
+`networks()` and `within()` return lazy iterators backed by native cursors.
+For large network walks, use `networkPages()`, `withinPages()`, or
+`NetworkIterator#nextPage()` to cross the native boundary once per page rather
+than once per network.
+
+## Open Modes
+
+Path-based `open()` defaults to memory-mapped reads:
+
+- `MODE_AUTO`
+- `MODE_MMAP`
+- `MODE_MEMORY`
+- `MODE_BUFFER`
+
+Use `MODE_BUFFER` if you want `open()` to read the file into a Node `Buffer`
+before constructing the reader.
+
+```js
+const reader = await maxmind.open('/path/to/db.mmdb', {
+  mode: maxmind.MODE_MEMORY,
+});
+```
+
+Mode tradeoffs:
+
+- `MODE_MMAP`/`MODE_AUTO` opens quickly and keeps RSS low by mapping the
+  database file. Replace database files atomically when using watched reloads.
+- `MODE_MEMORY` reads the database into Rust-owned memory. It costs more memory
+  at open time but is independent of the source file after open.
+- `MODE_BUFFER` reads the database into a Node `Buffer` before constructing the
+  native reader. Use it when you need Node-side file loading behavior or when
+  tests need to mutate a watched temporary file safely.
+
+## Performance Notes
+
+Performance depends on database size, record shape, cache hit rate, CPU, Node
+version, and whether the database is warm in the OS page cache. On one local
+run with 200,000 generated IPv4 lookups against `/var/lib/GeoIP`, this module
+had much faster open times and lower RSS than `node-maxmind`, while cached
+single-record lookup throughput was still lower:
+
+| Database | maxminddb default cache | node-maxmind default cache | maxminddb cache:100k | node-maxmind cache:100k |
+| --- | ---: | ---: | ---: | ---: |
+| GeoIP2-City | 370k/s | 441k/s | 632k/s | 869k/s |
+| GeoLite2-City | 452k/s | 498k/s | 715k/s | 1.07M/s |
+
+The same run opened mapped readers in sub-millisecond to low single-digit
+milliseconds after warmup, while `node-maxmind` open times were tens of
+milliseconds and retained tens to hundreds of MB of RSS. Batch lookups were
+faster than JavaScript loops over `get()`, reaching roughly 3.0-3.4M IPs/s in
+that run.
+
+Run local benchmarks with:
+
+```sh
+npm run bench -- --compare-node-maxmind --db /path/to/db.mmdb
+```
+
+## Supported Platforms
+
+The npm package is set up to ship prebuilt native modules for Linux x64 GNU,
+Linux arm64 GNU, macOS x64, macOS arm64, Windows x64 MSVC, and Windows arm64
+MSVC. The loader also knows platform-specific filenames for additional Linux,
+Windows, and FreeBSD targets, but those artifacts are not part of the default
+trusted publishing workflow yet. See [RELEASE.md](./RELEASE.md) for the native
+artifact strategy.
+
+## Development
+
+```sh
+npm install
+npm run build
+npm test
+npm run typecheck
+npm run bench -- --compare-node-maxmind
+npm run release
+npm run bench -- --save-baseline /tmp/maxminddb-baseline.json
+npm run bench -- --baseline /tmp/maxminddb-baseline.json --min-ratio 0.9
+npm run --silent bench -- --json > bench-results.json
+```
+
+See [RELEASE.md](./RELEASE.md) for packaging expectations and the native
+prebuild release strategy.
+
+## License
+
+ISC License. See [LICENSE](./LICENSE) for details.

package/RELEASE.md

@@ -0,0 +1,93 @@
+# Release Notes
+
+This package loads a native N-API addon at runtime. A publishable npm tarball
+must therefore include built `.node` files for the platforms it supports.
+
+## Current Artifact Shape
+
+`index.js` probes for platform-specific native bindings first, then falls back
+to `index.node`:
+
+- Linux: `index.linux-*-*.node`
+- macOS: `index.darwin-*.node`
+- Windows: `index.win32-*-*.node`
+- FreeBSD: `index.freebsd-x64.node`
+- Generic fallback: `index.node`
+
+`package.json` includes `*.node` files in the tarball, but it does not build a
+native addon during package installation. For local packaging checks, build the
+addon before packing:
+
+```sh
+npm ci
+npm run build
+npm pack --dry-run
+```
+
+The dry run should show `index.js`, `index.d.ts`, `package.json`, `README.md`,
+and one or more `.node` files.
+
+The trusted publishing workflow assembles one npm package containing these
+prebuilt native modules:
+
+- Linux x64 GNU: `index.linux-x64-gnu.node`
+- Linux arm64 GNU: `index.linux-arm64-gnu.node`
+- macOS x64: `index.darwin-x64.node`
+- macOS arm64: `index.darwin-arm64.node`
+- Windows x64 MSVC: `index.win32-x64-msvc.node`
+- Windows arm64 MSVC: `index.win32-arm64-msvc.node`
+
+The workflow does not currently build Linux musl/Alpine, Linux armv7, Linux
+ppc64/s390x/riscv64, Windows ia32, or FreeBSD artifacts. The loader supports
+platform-specific filenames for several of those targets, so adding them is a
+release automation task rather than a runtime API change.
+
+## Publishing Strategy
+
+The repository currently publishes `@oschwald/maxminddb` as one package
+containing every supported `index.<triple>.node` file. This keeps installation
+simple and avoids install-time native builds. If the tarball becomes too large,
+the next packaging shape to consider is separate optional dependency packages
+per target triple:
+
+- Publish separate optional dependency packages per target triple, each
+  containing one `index.<triple>.node`.
+
+That model keeps install size small while preserving install-time reliability.
+Publishing source only and building during package installation is intentionally
+not the default release strategy.
+
+The package is scoped and public. `package.json` sets `publishConfig.access` to
+`public`, and local bootstrap publishes should also pass `--access public`.
+
+## Trusted Publishing
+
+Publishing is configured through `.github/workflows/publish.yml` and npm trusted
+publishing. The workflow does not use an `NPM_TOKEN`; it grants GitHub Actions
+`id-token: write` permission so npm can authenticate the publish through OIDC.
+
+Before the first publish, configure the package on npmjs.com:
+
+- Publisher: GitHub Actions
+- Organization or user: the GitHub owner of this repository
+- Repository: the GitHub repository name
+- Workflow filename: `publish.yml`
+- Allowed action: `npm publish`
+
+The workflow uses Node 24 and upgrades npm before publishing so the npm CLI
+meets trusted publishing requirements. It builds native modules on hosted
+Linux, macOS, and Windows runners, smoke-tests that each native module loads on
+its build runner, downloads those artifacts into the package root, runs the same
+validation as CI, and verifies the package with `npm pack --dry-run`. GitHub
+release events then run `npm publish`. Manual `workflow_dispatch` runs are
+validation-only unless the `publish` input is set to `true`.
+
+## Release Checklist
+
+1. Configure npm trusted publishing for `.github/workflows/publish.yml`.
+2. Add a top entry to `CHANGELOG.md` with today's date.
+3. Run `npm run release`.
+4. Run `npm run bench -- --compare-node-maxmind` when benchmark databases are
+   available.
+5. Verify the `build-binaries` matrix completed for every supported target
+   before the `publish` job runs `npm publish`.

package/index.d.ts

@@ -0,0 +1,272 @@
+export type Names = {
+  readonly de?: string;
+  readonly en: string;
+  readonly es?: string;
+  readonly fr?: string;
+  readonly ja?: string;
+  readonly 'pt-BR'?: string;
+  readonly ru?: string;
+  readonly 'zh-CN'?: string;
+};
+
+export interface CityRecord {
+  readonly confidence?: number;
+  readonly geoname_id: number;
+  readonly names: Names;
+}
+
+export interface ContinentRecord {
+  readonly code: 'AF' | 'AN' | 'AS' | 'EU' | 'NA' | 'OC' | 'SA';
+  readonly geoname_id: number;
+  readonly names: Names;
+}
+
+export interface RegisteredCountryRecord {
+  readonly geoname_id: number;
+  readonly is_in_european_union?: boolean;
+  readonly iso_code: string;
+  readonly names: Names;
+}
+
+export interface CountryRecord extends RegisteredCountryRecord {
+  readonly confidence?: number;
+}
+
+export interface LocationRecord {
+  readonly accuracy_radius: number;
+  readonly average_income?: number;
+  readonly latitude: number;
+  readonly longitude: number;
+  readonly metro_code?: number;
+  readonly population_density?: number;
+  readonly time_zone?: string;
+}
+
+export interface PostalRecord {
+  readonly code: string;
+  readonly confidence?: number;
+}
+
+export interface RepresentedCountryRecord extends RegisteredCountryRecord {
+  readonly type: string;
+}
+
+export interface SubdivisionsRecord {
+  readonly confidence?: number;
+  readonly geoname_id: number;
+  readonly iso_code: string;
+  readonly names: Names;
+}
+
+export interface TraitsRecord {
+  readonly autonomous_system_number?: number;
+  readonly autonomous_system_organization?: string;
+  readonly connection_type?: string;
+  readonly domain?: string;
+  ip_address?: string;
+  readonly is_anonymous?: boolean;
+  readonly is_anonymous_proxy?: boolean;
+  readonly is_anonymous_vpn?: boolean;
+  readonly is_anycast?: boolean;
+  readonly is_hosting_provider?: boolean;
+  readonly is_legitimate_proxy?: boolean;
+  readonly is_public_proxy?: boolean;
+  readonly is_residential_proxy?: boolean;
+  readonly is_satellite_provider?: boolean;
+  readonly is_tor_exit_node?: boolean;
+  readonly isp?: string;
+  readonly mobile_country_code?: string;
+  readonly mobile_network_code?: string;
+  readonly organization?: string;
+  readonly static_ip_score?: number;
+  readonly user_count?: number;
+  readonly user_type?: string;
+}
+
+export interface CountryResponse {
+  readonly continent?: ContinentRecord;
+  readonly country?: CountryRecord;
+  readonly registered_country?: RegisteredCountryRecord;
+  readonly represented_country?: RepresentedCountryRecord;
+  readonly traits?: TraitsRecord;
+}
+
+export interface CityResponse extends CountryResponse {
+  readonly city?: CityRecord;
+  readonly location?: LocationRecord;
+  readonly postal?: PostalRecord;
+  readonly subdivisions?: SubdivisionsRecord[];
+}
+
+export interface AnonymousIPResponse {
+  ip_address?: string;
+  readonly is_anonymous?: boolean;
+  readonly is_anonymous_proxy?: boolean;
+  readonly is_anonymous_vpn?: boolean;
+  readonly is_hosting_provider?: boolean;
+  readonly is_public_proxy?: boolean;
+  readonly is_residential_proxy?: boolean;
+  readonly is_tor_exit_node?: boolean;
+}
+
+export interface AnonymousPlusResponse extends AnonymousIPResponse {
+  readonly anonymizer_confidence?: number;
+  readonly network_last_seen?: string;
+  readonly provider_name?: string;
+}
+
+export interface AsnResponse {
+  readonly autonomous_system_number: number;
+  readonly autonomous_system_organization: string;
+  ip_address?: string;
+}
+
+export interface ConnectionTypeResponse {
+  readonly connection_type: string;
+  ip_address?: string;
+}
+
+export interface DomainResponse {
+  readonly domain: string;
+  ip_address?: string;
+}
+
+export interface IspResponse extends AsnResponse {
+  readonly isp: string;
+  readonly mobile_country_code?: string;
+  readonly mobile_network_code?: string;
+  readonly organization: string;
+}
+
+export type Response =
+  | CountryResponse
+  | CityResponse
+  | AnonymousIPResponse
+  | AnonymousPlusResponse
+  | AsnResponse
+  | ConnectionTypeResponse
+  | DomainResponse
+  | IspResponse;
+
+export interface Metadata {
+  readonly binaryFormatMajorVersion: number;
+  readonly binaryFormatMinorVersion: number;
+  readonly buildEpoch: Date;
+  readonly databaseType: string;
+  readonly languages: string[];
+  readonly description: Record<string, string>;
+  readonly ipVersion: number;
+  readonly nodeCount: number;
+  readonly recordSize: number;
+  readonly nodeByteSize: number;
+  readonly searchTreeSize: number;
+  readonly treeDepth: number;
+}
+
+export interface OpenOpts {
+  cache?: false | {
+    max: number;
+  };
+  watchForUpdates?: boolean;
+  watchForUpdatesNonPersistent?: boolean;
+  watchForUpdatesHook?: () => void;
+  mode?: typeof MODE_AUTO | typeof MODE_MMAP | typeof MODE_MEMORY | typeof MODE_BUFFER;
+}
+
+export interface NetworkIterationOptions {
+  includeAliasedNetworks?: boolean;
+  includeNetworksWithoutData?: boolean;
+  skipEmptyValues?: boolean;
+}
+
+export interface NetworkPagesOptions extends NetworkIterationOptions {
+  pageSize?: number;
+}
+
+export interface CacheStats {
+  readonly enabled: boolean;
+  readonly size: number;
+  readonly capacity: number;
+  readonly hits: number;
+  readonly misses: number;
+  readonly inserts: number;
+  readonly evictions: number;
+}
+
+export declare class PathLookup<TValue = unknown> {
+  readonly path: ReadonlyArray<string | number>;
+  get(ipAddress: string): TValue | null;
+  getMany(ipAddresses: ReadonlyArray<string>): Array<TValue | null>;
+}
+
+export declare class NetworkIterator<T extends Response = Response>
+  implements IterableIterator<[string, T | null]> {
+  next(): IteratorResult<[string, T | null]>;
+  nextPage(pageSize?: number): Array<[string, T | null]>;
+  pages(pageSize?: number): IterableIterator<Array<[string, T | null]>>;
+  close(): void;
+  [Symbol.iterator](): IterableIterator<[string, T | null]>;
+}
+
+export declare const MODE_AUTO: 'auto';
+export declare const MODE_MMAP: 'mmap';
+export declare const MODE_MEMORY: 'memory';
+export declare const MODE_BUFFER: 'buffer';
+
+export declare class Reader<T extends Response = Response> {
+  constructor(database: Buffer, options?: OpenOpts);
+  readonly closed: boolean;
+  readonly lastReloadError: Error | null;
+  metadata: Metadata;
+  load(database: Buffer): void;
+  reload(): void;
+  close(): void;
+  clearCache(): void;
+  cacheStats(): CacheStats;
+  get(ipAddress: string): T | null;
+  getPath(ipAddress: string, path: ReadonlyArray<string | number>): unknown;
+  path<TValue = unknown>(
+    path: ReadonlyArray<string | number>,
+  ): PathLookup<TValue>;
+  getWithPrefixLength(ipAddress: string): [T | null, number];
+  getMany(ipAddresses: ReadonlyArray<string>): Array<T | null>;
+  getManyPath(
+    ipAddresses: ReadonlyArray<string>,
+    path: ReadonlyArray<string | number>,
+  ): unknown[];
+  networks(options?: NetworkPagesOptions): NetworkIterator<T>;
+  within(cidr: string, options?: NetworkPagesOptions): NetworkIterator<T>;
+  networkPages(
+    options?: NetworkPagesOptions,
+  ): IterableIterator<Array<[string, T | null]>>;
+  withinPages(
+    cidr: string,
+    options?: NetworkPagesOptions,
+  ): IterableIterator<Array<[string, T | null]>>;
+}
+
+export declare function open<T extends Response = Response>(
+  filepath: string,
+  options?: OpenOpts,
+): Promise<Reader<T>>;
+
+export declare function openSync(): never;
+export declare function init(): never;
+export declare function validate(ipAddress: string): boolean;
+export declare function nativeVersion(): string;
+
+declare const maxmind: {
+  PathLookup: typeof PathLookup;
+  Reader: typeof Reader;
+  open: typeof open;
+  openSync: typeof openSync;
+  init: typeof init;
+  validate: typeof validate;
+  nativeVersion: typeof nativeVersion;
+  MODE_AUTO: typeof MODE_AUTO;
+  MODE_MMAP: typeof MODE_MMAP;
+  MODE_MEMORY: typeof MODE_MEMORY;
+  MODE_BUFFER: typeof MODE_BUFFER;
+};
+
+export default maxmind;

package/index.js

@@ -0,0 +1,547 @@
+'use strict';
+
+const assert = require('node:assert');
+const fs = require('node:fs');
+const net = require('node:net');
+const { join } = require('node:path');
+
+const platformTriples = {
+  linux: {
+    x64: ['linux-x64-gnu', 'linux-x64-musl'],
+    arm64: ['linux-arm64-gnu', 'linux-arm64-musl'],
+    arm: ['linux-arm-gnueabihf', 'linux-arm-musleabihf'],
+    ppc64: ['linux-ppc64-gnu'],
+    s390x: ['linux-s390x-gnu'],
+    riscv64: ['linux-riscv64-gnu'],
+  },
+  darwin: {
+    x64: ['darwin-x64'],
+    arm64: ['darwin-arm64'],
+    universal: ['darwin-universal'],
+  },
+  win32: {
+    x64: ['win32-x64-msvc', 'win32-x64-gnu'],
+    arm64: ['win32-arm64-msvc'],
+    ia32: ['win32-ia32-msvc'],
+  },
+  freebsd: {
+    x64: ['freebsd-x64'],
+  },
+};
+
+function nativeCandidates() {
+  const triples = platformTriples[process.platform]?.[process.arch] ?? [];
+  return [
+    ...triples.map((triple) => `index.${triple}.node`),
+    'index.node',
+  ].map((name) => join(__dirname, name));
+}
+
+function loadNativeBinding() {
+  const attempted = [];
+  for (const candidate of nativeCandidates()) {
+    attempted.push(candidate);
+    if (fs.existsSync(candidate)) {
+      return require(candidate);
+    }
+  }
+
+  const error = new Error(
+    `Unable to load maxminddb native binding. Tried:\n${attempted.join('\n')}`
+  );
+  error.code = 'ERR_MAXMINDDB_NATIVE_BINDING_NOT_FOUND';
+  throw error;
+}
+
+const native = loadNativeBinding();
+
+const DEFAULT_LARGE_FILE_THRESHOLD = 512 * 1024 * 1024;
+const LARGE_FILE_THRESHOLD = normalizeLargeFileThreshold(
+  process.env.MAXMINDDB_LARGE_FILE_THRESHOLD_BYTES
+);
+const STREAM_WATERMARK = 8 * 1024 * 1024;
+const DEFAULT_CACHE_MAX = 10_000;
+const MAX_CACHE_MAX = 0xffffffff;
+const legacyErrorMessage = `Maxmind v2 module has changed API.
+Please use:
+    maxmind.open(dbfile).then(function(lookup) {
+        lookup.get(ip);
+    });
+`;
+
+const MODE_AUTO = 'auto';
+const MODE_MMAP = 'mmap';
+const MODE_MEMORY = 'memory';
+const MODE_BUFFER = 'buffer';
+
+function normalizeLargeFileThreshold(value) {
+  if (value == null || value === '') {
+    return DEFAULT_LARGE_FILE_THRESHOLD;
+  }
+
+  const threshold = Number(value);
+  return Number.isSafeInteger(threshold) && threshold >= 0
+    ? threshold
+    : DEFAULT_LARGE_FILE_THRESHOLD;
+}
+
+function isGzipBuffer(buffer) {
+  return buffer.length >= 2 && buffer[0] === 0x1f && buffer[1] === 0x8b;
+}
+
+async function assertNotGzipFile(filepath) {
+  const handle = await fs.promises.open(filepath, 'r');
+  try {
+    const buffer = Buffer.alloc(2);
+    const { bytesRead } = await handle.read(buffer, 0, 2, 0);
+    if (bytesRead === 2 && isGzipBuffer(buffer)) {
+      throw new Error(
+        'Looks like you are passing in a file in gzip format, please use mmdb database instead.'
+      );
+    }
+  } finally {
+    await handle.close();
+  }
+}
+
+function normalizeMode(mode) {
+  if (mode == null || mode === MODE_AUTO) {
+    return MODE_MMAP;
+  }
+  if (mode === MODE_MMAP || mode === MODE_MEMORY || mode === MODE_BUFFER) {
+    return mode;
+  }
+  throw new Error(`Unsupported open mode: ${mode}`);
+}
+
+function normalizeMetadata(metadata) {
+  return {
+    ...metadata,
+    buildEpoch: new Date(Number(metadata.buildEpoch) * 1000),
+  };
+}
+
+function normalizeCacheCapacity(options = {}) {
+  if (options.cache === false) {
+    return 0;
+  }
+
+  const max = options.cache?.max ?? DEFAULT_CACHE_MAX;
+  if (!Number.isSafeInteger(max) || max <= 0 || max > MAX_CACHE_MAX) {
+    throw new Error('opts.cache.max should be a positive 32-bit integer');
+  }
+  return max;
+}
+
+function normalizeNetworkOptions(options = {}) {
+  return [
+    Boolean(options.includeAliasedNetworks),
+    Boolean(options.includeNetworksWithoutData),
+    Boolean(options.skipEmptyValues),
+  ];
+}
+
+function normalizeNetworkPageSize(value = 1000) {
+  if (!Number.isSafeInteger(value) || value <= 0 || value > MAX_CACHE_MAX) {
+    throw new Error('page size should be a positive 32-bit integer');
+  }
+  return value;
+}
+
+function normalizeNetworkIteratorOptions(options = {}) {
+  return [
+    normalizeNetworkOptions(options),
+    normalizeNetworkPageSize(options.pageSize ?? 1000),
+  ];
+}
+
+function waitForFile(filepath) {
+  for (let i = 0; i < 3; i++) {
+    if (fs.existsSync(filepath)) {
+      return Promise.resolve(true);
+    }
+  }
+
+  return new Promise((resolve) => {
+    let attempts = 0;
+    const retry = () => {
+      attempts += 1;
+      if (fs.existsSync(filepath)) {
+        resolve(true);
+      } else if (attempts >= 3) {
+        resolve(false);
+      } else {
+        setTimeout(retry, 500);
+      }
+    };
+    retry();
+  });
+}
+
+async function readLargeFile(filepath, size) {
+  return new Promise((resolve, reject) => {
+    const buffer = Buffer.allocUnsafe(size);
+    let offset = 0;
+    let settled = false;
+    const stream = fs.createReadStream(filepath, {
+      highWaterMark: STREAM_WATERMARK,
+    });
+
+    const finish = (error, value) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (error) {
+        stream.destroy();
+        reject(error);
+      } else {
+        resolve(value);
+      }
+    };
+
+    stream.on('data', (chunk) => {
+      const bufferChunk = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      if (offset + bufferChunk.length > size) {
+        finish(
+          new Error(
+            `File changed while reading ${filepath}: expected ${size} bytes but read more`
+          )
+        );
+        return;
+      }
+      bufferChunk.copy(buffer, offset);
+      offset += bufferChunk.length;
+    });
+    stream.on('end', () => {
+      if (offset !== size) {
+        finish(
+          new Error(
+            `File changed while reading ${filepath}: expected ${size} bytes but read ${offset}`
+          )
+        );
+        return;
+      }
+      finish(null, buffer);
+    });
+    stream.on('error', (error) => finish(error));
+  });
+}
+
+async function readFile(filepath) {
+  const stat = await fs.promises.stat(filepath);
+  return stat.size < LARGE_FILE_THRESHOLD
+    ? fs.promises.readFile(filepath)
+    : readLargeFile(filepath, stat.size);
+}
+
+class PathLookup {
+  constructor(reader, path) {
+    this._reader = reader;
+    this._pathId = reader._reader.compilePath(path);
+    this.path = Object.freeze([...path]);
+  }
+
+  get(ipAddress) {
+    return this._reader._reader.getCompiledPath(ipAddress, this._pathId);
+  }
+
+  getMany(ipAddresses) {
+    return this._reader._reader.getManyCompiledPath(ipAddresses, this._pathId);
+  }
+}
+
+class NetworkIterator {
+  constructor(reader, cidr, options = {}) {
+    const [networkOptions, pageSize] = normalizeNetworkIteratorOptions(options);
+    this._cursor = reader._reader.networkCursor(cidr, ...networkOptions);
+    this._pageSize = pageSize;
+    this._page = [];
+    this._index = 0;
+    this._done = false;
+  }
+
+  [Symbol.iterator]() {
+    return this;
+  }
+
+  next() {
+    if (this._done) {
+      return { done: true, value: undefined };
+    }
+
+    if (this._index >= this._page.length) {
+      this._page = this._cursor.nextPage(this._pageSize);
+      this._index = 0;
+      if (this._page.length === 0) {
+        this.close();
+        return { done: true, value: undefined };
+      }
+    }
+
+    const value = this._page[this._index];
+    this._index += 1;
+    return { done: false, value };
+  }
+
+  nextPage(pageSize = this._pageSize) {
+    pageSize = normalizeNetworkPageSize(pageSize);
+    if (this._done) {
+      return [];
+    }
+
+    const page = [];
+    while (page.length < pageSize && this._index < this._page.length) {
+      page.push(this._page[this._index]);
+      this._index += 1;
+    }
+
+    if (page.length < pageSize) {
+      const nativePage = this._cursor.nextPage(pageSize - page.length);
+      page.push(...nativePage);
+      if (nativePage.length === 0) {
+        this.close();
+      }
+    }
+
+    return page;
+  }
+
+  *pages(pageSize = this._pageSize) {
+    pageSize = normalizeNetworkPageSize(pageSize);
+    while (true) {
+      const page = this.nextPage(pageSize);
+      if (page.length === 0) {
+        return;
+      }
+      yield page;
+    }
+  }
+
+  close() {
+    if (!this._done) {
+      this._cursor.close();
+      this._done = true;
+      this._page = [];
+      this._index = 0;
+    }
+  }
+}
+
+class Reader {
+  constructor(database, options = {}) {
+    if (!Buffer.isBuffer(database)) {
+      throw new Error(`maxminddb expects an instance of Buffer, got: ${typeof database}`);
+    }
+    this._mode = MODE_BUFFER;
+    this._filepath = null;
+    this._watchFilepath = null;
+    this._watchListener = null;
+    this._watchReloadPromise = Promise.resolve();
+    this._lastReloadError = null;
+    this._cacheCapacity = normalizeCacheCapacity(options);
+    this._reader = new native.NativeReader(database, this._cacheCapacity);
+    this.metadata = normalizeMetadata(this._reader.metadata());
+    this.options = options;
+  }
+
+  static open(filepath, options = {}) {
+    const mode = normalizeMode(options.mode);
+    const reader = Object.create(Reader.prototype);
+    reader._mode = mode;
+    reader._filepath = filepath;
+    reader._watchFilepath = null;
+    reader._watchListener = null;
+    reader._watchReloadPromise = Promise.resolve();
+    reader._lastReloadError = null;
+    reader._cacheCapacity = normalizeCacheCapacity(options);
+    reader._reader = native.openReader(filepath, mode, reader._cacheCapacity);
+    reader.metadata = normalizeMetadata(reader._reader.metadata());
+    reader.options = options;
+    return reader;
+  }
+
+  get closed() {
+    return this._reader.closed;
+  }
+
+  get lastReloadError() {
+    return this._lastReloadError;
+  }
+
+  load(database) {
+    try {
+      this._reader.load(database);
+      this.metadata = normalizeMetadata(this._reader.metadata());
+      this._lastReloadError = null;
+    } catch (error) {
+      this._lastReloadError = error;
+      throw error;
+    }
+  }
+
+  reload() {
+    if (!this._filepath) {
+      throw new Error('Cannot reload a buffer-backed Reader');
+    }
+    try {
+      this._reader.reloadFromFile(this._filepath, this._mode);
+      this.metadata = normalizeMetadata(this._reader.metadata());
+      this._lastReloadError = null;
+    } catch (error) {
+      this._lastReloadError = error;
+      throw error;
+    }
+  }
+
+  close() {
+    if (this._watchFilepath && this._watchListener) {
+      fs.unwatchFile(this._watchFilepath, this._watchListener);
+      this._watchFilepath = null;
+      this._watchListener = null;
+    }
+    this._reader.close();
+  }
+
+  _queueWatchedReload(filepath, mode, hook) {
+    const reload = () => this._reloadWatchedFile(filepath, mode, hook);
+    this._watchReloadPromise = this._watchReloadPromise.then(reload, reload);
+  }
+
+  async _reloadWatchedFile(filepath, mode, hook) {
+    if (!(await waitForFile(filepath))) {
+      return;
+    }
+    if (this.closed || this._watchFilepath !== filepath) {
+      return;
+    }
+
+    try {
+      if (mode === MODE_BUFFER) {
+        const database = await readFile(filepath);
+        if (this.closed || this._watchFilepath !== filepath) {
+          return;
+        }
+        this.load(database);
+      } else {
+        this.reload();
+      }
+      if (!this.closed && this._watchFilepath === filepath && hook) {
+        hook();
+      }
+    } catch (error) {
+      this._lastReloadError = error;
+    }
+  }
+
+  clearCache() {
+    this._reader.clearCache();
+  }
+
+  cacheStats() {
+    return this._reader.cacheStats();
+  }
+
+  get(ipAddress) {
+    return this._reader.get(ipAddress);
+  }
+
+  getPath(ipAddress, path) {
+    return this._reader.getPath(ipAddress, path);
+  }
+
+  path(path) {
+    return new PathLookup(this, path);
+  }
+
+  getWithPrefixLength(ipAddress) {
+    return this._reader.getWithPrefixLength(ipAddress);
+  }
+
+  getMany(ipAddresses) {
+    return this._reader.getMany(ipAddresses);
+  }
+
+  getManyPath(ipAddresses, path) {
+    return this._reader.getManyPath(ipAddresses, path);
+  }
+
+  networks(options = {}) {
+    return new NetworkIterator(this, null, options);
+  }
+
+  within(cidr, options = {}) {
+    return new NetworkIterator(this, cidr, options);
+  }
+
+  *networkPages(options = {}) {
+    yield* this.networks(options).pages(options.pageSize ?? 1000);
+  }
+
+  *withinPages(cidr, options = {}) {
+    yield* this.within(cidr, options).pages(options.pageSize ?? 1000);
+  }
+}
+
+async function open(filepath, opts, cb) {
+  assert(!cb, legacyErrorMessage);
+  const options = opts || {};
+  await assertNotGzipFile(filepath);
+
+  const mode = normalizeMode(options.mode);
+  const reader =
+    mode === MODE_BUFFER
+      ? new Reader(await readFile(filepath), options)
+      : Reader.open(filepath, options);
+
+  if (options.watchForUpdates) {
+    if (
+      options.watchForUpdatesHook &&
+      typeof options.watchForUpdatesHook !== 'function'
+    ) {
+      throw new Error('opts.watchForUpdatesHook should be a function');
+    }
+
+    const watcherOptions = {
+      persistent: options.watchForUpdatesNonPersistent !== true,
+    };
+
+    const watchListener = () => {
+      reader._queueWatchedReload(filepath, mode, options.watchForUpdatesHook);
+    };
+
+    fs.watchFile(filepath, watcherOptions, watchListener);
+    reader._watchFilepath = filepath;
+    reader._watchListener = watchListener;
+  }
+
+  return reader;
+}
+
+function init() {
+  throw new Error(legacyErrorMessage);
+}
+
+function openSync() {
+  throw new Error(legacyErrorMessage);
+}
+
+function validate(ipAddress) {
+  const version = net.isIP(ipAddress);
+  return version === 4 || version === 6;
+}
+
+module.exports = {
+  ...native,
+  NetworkIterator,
+  PathLookup,
+  Reader,
+  init,
+  open,
+  openSync,
+  validate,
+  MODE_AUTO,
+  MODE_MMAP,
+  MODE_MEMORY,
+  MODE_BUFFER,
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@oschwald/maxminddb",
+  "version": "0.1.0",
+  "description": "Rust-backed Node.js reader for MaxMind DB files",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "require": "./index.js",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "CHANGELOG.md",
+    "LICENSE",
+    "RELEASE.md",
+    "*.node"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oschwald/maxminddb-node.git"
+  },
+  "bugs": {
+    "url": "https://github.com/oschwald/maxminddb-node/issues"
+  },
+  "homepage": "https://github.com/oschwald/maxminddb-node#readme",
+  "author": "Gregory J. Oschwald <oschwald@gmail.com>",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "napi build --platform --release --no-js --dts native.d.ts",
+    "build:debug": "napi build --platform --no-js --dts native.d.ts",
+    "bench": "node --expose-gc bench/lookup.js",
+    "release": "dev-bin/release.sh",
+    "test": "node --test test/*.test.js",
+    "test:pack": "node test/pack-smoke.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "maxmind",
+    "mmdb",
+    "geoip",
+    "geoip2"
+  ],
+  "license": "ISC",
+  "devDependencies": {
+    "@napi-rs/cli": "^3.7.2",
+    "@types/node": "^25.9.3",
+    "typescript": "^5.9.2"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}