{"id":25684713,"url":"https://github.com/josh-hemphill/maxminddb-wasm","last_synced_at":"2025-10-10T19:37:58.694Z","repository":{"id":62421977,"uuid":"346428096","full_name":"josh-hemphill/maxminddb-wasm","owner":"josh-hemphill","description":"A library that enables the usage of MaxmindDB geoIP databases by using the Rust library in a WASM module","archived":false,"fork":false,"pushed_at":"2025-03-29T02:44:16.000Z","size":471,"stargazers_count":14,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"dev","last_synced_at":"2025-10-09T10:05:03.892Z","etag":null,"topics":["deno","geoip","maxmind","wasm"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/josh-hemphill.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-03-10T16:54:37.000Z","updated_at":"2025-09-28T09:10:20.000Z","dependencies_parsed_at":"2025-02-18T09:24:31.109Z","dependency_job_id":"55a9adc8-643c-4232-bf11-7cedf9e7d4dc","html_url":"https://github.com/josh-hemphill/maxminddb-wasm","commit_stats":null,"previous_names":["josh-hemphill/maxminddb-wasm","josh-hemphill/maxminddb-deno"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/josh-hemphill/maxminddb-wasm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josh-hemphill%2Fmaxminddb-wasm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josh-hemphill%2Fmaxminddb-wasm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josh-hemphill%2Fmaxminddb-wasm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josh-hemphill%2Fmaxminddb-wasm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/josh-hemphill","download_url":"https://codeload.github.com/josh-hemphill/maxminddb-wasm/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josh-hemphill%2Fmaxminddb-wasm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005032,"owners_count":26083827,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deno","geoip","maxmind","wasm"],"created_at":"2025-02-24T17:32:35.206Z","updated_at":"2025-10-10T19:37:58.661Z","avatar_url":"https://github.com/josh-hemphill.png","language":"TypeScript","funding_links":[],"categories":["Modules"],"sub_categories":["Database"],"readme":"\u003cdiv align=\"center\"\u003e\n\n  \u003ch1\u003e\u003ccode\u003emaxminddb\u003c/code\u003e WASM\u003c/h1\u003e\n\n  \u003cstrong\u003eA library that enables the usage of MaxmindDB geoIP databases by using the Rust library in a WebAssembly module\u003c/strong\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"https://github.com/josh-hemphill/maxminddb-wasm/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/tag/josh-hemphill/maxminddb-wasm?sort=semver\u0026style=flat-square\" alt=\"version\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/josh-hemphill/maxminddb-wasm/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/josh-hemphill/maxminddb-wasm/ci.yml?label=CI\u0026style=flat-square\" alt=\"CI Status\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://www.npmjs.com/package/maxminddb-wasm\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/maxminddb-wasm?label=NPM\u0026message=NPM\u0026logo=nodedotjs\u0026color=informational\" alt=\"NPM\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://jsr.io/@josh-hemphill/maxminddb-wasm\"\u003e\u003cimg src=\"https://img.shields.io/jsr/v/%40josh-hemphill/maxminddb-wasm?label=JSR\u0026message=JSR\u0026logo=jsr\u0026color=informational\u0026style=flat-square\" alt=\"jsr.io\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://deno.land/x/maxminddb/mod.ts\"\u003e\u003cimg src=\"https://img.shields.io/static/v1?label=\u0026message=Deno.Land\u0026logo=deno\u0026color=informational\u0026style=flat-square\" alt=\"Deno Land\" /\u003e\u003c/a\u003e\n  \u003c/p\u003e\n  \u003cp\u003e\n    \u003ca href=\"https://github.com/josh-hemphill/maxminddb-wasm/actions/workflows/ci.yml\"\u003e\u003cimg src=\".github/badges/test-deno.svg\" alt=\"Deno Status\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/josh-hemphill/maxminddb-wasm/actions/workflows/ci.yml\"\u003e\u003cimg src=\".github/badges/test-bun.svg\" alt=\"Bun Status\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/josh-hemphill/maxminddb-wasm/actions/workflows/ci.yml\"\u003e\u003cimg src=\".github/badges/test-browser.svg\" alt=\"Browser Status\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/josh-hemphill/maxminddb-wasm/actions/workflows/ci.yml\"\u003e\u003cimg src=\".github/badges/test-cloudflare.svg\" alt=\"Cloudflare Status\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/josh-hemphill/maxminddb-wasm/actions/workflows/ci.yml\"\u003e\u003cimg src=\".github/badges/test-node.svg\" alt=\"Node CJS Status\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/josh-hemphill/maxminddb-wasm/actions/workflows/ci.yml\"\u003e\u003cimg src=\".github/badges/test-node-module.svg\" alt=\"Node Module Status\" /\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n## About\n\nUses the [Rust MaxmindDB library](https://crates.io/crates/maxminddb) to create a WASM binary that lets you query MaxMind databases directly in JavaScript/TypeScript.\n\n### Status\n\n  - [x] Node.js\n  - [x] Deno\n  - [x] Bun\n  - [/] Browser (tests are flaky, so not certain)\n  - [?] 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))\n\n## Installation\n\n### Node.js / Browser (npm)\n\n```bash\nnpm install maxminddb-wasm\n# or\npnpm add maxminddb-wasm\n```\n\n### Deno ([jsr](https://jsr.io/docs/introduction))\n\n```ts\nimport { Maxmind } from \"jsr:@josh-hemphill/maxminddb-wasm/bundler\";\n```\n\n## Usage Examples\n\n### Node.js\n\n```ts\nimport { readFile } from 'node:fs/promises';\nimport { Maxmind } from 'maxminddb-wasm/node-module';\n\nconst dbFile = await readFile('./GeoLite2-City.mmdb');\nconst maxmind = new Maxmind(dbFile);\nconst result = maxmind.lookup_city('8.8.8.8');\nconsole.log(result);\n```\n\n### Deno\n\n```ts\nimport { Maxmind } from \"jsr:@josh-hemphill/maxminddb-wasm/bundler\";\n\nconst dbFile = await Deno.readFile('./GeoLite2-City.mmdb');\nconst maxmind = new Maxmind(dbFile);\nconst result = maxmind.lookup_city('8.8.8.8');\nconsole.log(result);\n```\n\n### Browser\n\n```ts\nimport { Maxmind } from 'maxminddb-wasm/browser';\n\n// Fetch the database file\nconst response = await fetch('/GeoLite2-City.mmdb');\nconst dbFile = new Uint8Array(await response.arrayBuffer());\nconst maxmind = new Maxmind(dbFile);\nconst result = maxmind.lookup_city('8.8.8.8');\n```\n\n### Cloudflare Workers\n\n```ts\nimport { Maxmind } from 'maxminddb-wasm/browser';\n\nexport default {\n  async fetch(request, env) {\n    const maxmind = new Maxmind(new Uint8Array(env.MAXMIND_DB));\n    const ip = request.headers.get('cf-connecting-ip');\n    const result = maxmind.lookup_city(ip);\n    return new Response(JSON.stringify(result));\n  }\n};\n```\n\n### Bun\n\n```ts\nimport { Maxmind } from 'maxminddb-wasm/node-module';\n\nconst dbFile = await Bun.file('./GeoLite2-City.mmdb').arrayBuffer();\nconst maxmind = new Maxmind(new Uint8Array(dbFile));\nconst result = maxmind.lookup_city('8.8.8.8');\n```\n\n## API Reference\n\n### `Maxmind` Class\n\n#### Constructor\n\n```ts\nnew Maxmind(dbFile: Uint8Array)\n```\n\nCreates a new Maxmind instance with the provided database file.\n\n#### Methods\n\n##### `lookup_city(ip: string): CityResponse`\n\nLooks up city information for the given IP address.\n\n##### `lookup_prefix(ip: string): PrefixResponse`\n\nLooks up network prefix information for the given IP address.\n\n##### `metadata: Metadata`\n\nRead-only property that returns database metadata.\n\n### Response Types\n\n#### `CityResponse`\n\n```ts\ninterface CityResponse {\n    city?: CityRecord;\n    continent?: ContinentRecord;\n    country?: CountryRecord;\n    subdivisions?: SubdivisionRecord[];\n    location?: LocationRecord;\n}\n```\n\n#### `CityRecord`\n\n```ts\ninterface CityRecord {\n    geoname_id?: number;\n    names?: Record\u003cstring, string\u003e;\n}\n```\n\n#### `ContinentRecord`\n\n```ts\ninterface ContinentRecord {\n    code?: string;\n    geoname_id?: number;\n    names?: Record\u003cstring, string\u003e;\n}\n```\n\n#### `CountryRecord`\n\n```ts\ninterface CountryRecord {\n    geoname_id?: number;\n    iso_code?: string;\n    names?: Record\u003cstring, string\u003e;\n}\n```\n\n#### `SubdivisionRecord`\n\n```ts\ninterface SubdivisionRecord {\n    geoname_id?: number;\n    iso_code?: string;\n    names?: Record\u003cstring, string\u003e;\n}\n```\n\n#### `LocationRecord`\n\n```ts\ninterface LocationRecord {\n    latitude?: number;\n    longitude?: number;\n    time_zone?: string;\n}\n```\n\n#### `PrefixResponse`\n\n```ts\ninterface PrefixResponse {\n    city: CityResponse;\n    prefix_length: number;\n}\n```\n\n#### `Metadata`\n\n```ts\ninterface Metadata {\n    binary_format_major_version: number;\n    binary_format_minor_version: number;\n    build_epoch: number;\n    database_type: string;\n    description: Record\u003cstring, string\u003e;\n    ip_version: number;\n    languages: string[];\n    node_count: number;\n    record_size: number;\n}\n```\n\n## Contributing\n\n### Build Setup\n\nFor running the automated build (which includes compiling the rust wasm) you'll need the following tools installed:\n\n  - [node](https://nodejs.org/en/download/)\n  - [pnpm](https://pnpm.io/installation)\n  - [Rust](https://doc.rust-lang.org/cargo/getting-started/installation.html)\n\nOnce you have all the necessary tools installed, you can just run `pnpm build`\n\n### Testing\n\nUnder `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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosh-hemphill%2Fmaxminddb-wasm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjosh-hemphill%2Fmaxminddb-wasm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosh-hemphill%2Fmaxminddb-wasm/lists"}