# `@protovoters/osmx`

[![Open on npmx.dev](https://npmx.dev/api/registry/badge/name/@protovoters/osmx)](https://npmx.dev/package/@protovoters/osmx)
[![Open on npmx.dev](https://npmx.dev/api/registry/badge/version/@protovoters/osmx)](https://npmx.dev/package/@protovoters/osmx)
[![Open on npmx.dev](https://npmx.dev/api/registry/badge/license/@protovoters/osmx)](https://npmx.dev/package/@protovoters/osmx)
[![Open on npmx.dev](https://npmx.dev/api/registry/badge/downloads-month/@protovoters/osmx)](https://npmx.dev/package/@protovoters/osmx)
[![Open on npmx.dev](https://npmx.dev/api/registry/badge/engines/@protovoters/osmx)](https://npmx.dev/package/@protovoters/osmx)
[![Open on npmx.dev](https://npmx.dev/api/registry/badge/types/@protovoters/osmx)](https://npmx.dev/package/@protovoters/osmx)

A portable WebAssembly-backed [OSM Express](https://github.com/bdon/OSMExpress) database toolkit for Node.js.

The TypeScript API reads LMDB pages on demand and decodes records with the `capnp-ts` runtime and generated schema bindings; tsdown emits the native-ESM package and declarations. The complete OSMExpress engine is compiled with `wasixcc`; typed library operations invoke that bundled module through Wasmer. The package contains no native addon, native executable, lifecycle compilation, or architecture-specific prebuild.

The package exposes one focused library surface: `open()` for structured database access plus typed `expand()`, `extract()`, `update()`, and `query()` operations. Raw command arguments, CLI compatibility objects, executable paths, and runtime internals are intentionally private.

```js
import { open, expand, query } from "@protovoters/osmx";

const created = await expand("input.osm.pbf", "data.osmx");
const info = await query(created.path);

const database = open(created.path);
const way = database.ways.get("123");
database.close();
```

All command operations run `wasm/osmx-engine.wasm` with the Wasmer runtime. Host directories containing command inputs and outputs are explicitly mounted into the WASIX sandbox. Install Wasmer separately (`curl -sSfL https://get.wasmer.io | sh`) or pass `options.wasmer`/set `WASMER_BIN` to select its executable.

The generated TypeScript schema source is checked in; maintainers can regenerate it after schema changes by installing the Cap’n Proto compiler and running `yarn build:capnp`. The C++ schema output used by the cross-build is also checked in under `generated/` and pinned to Cap’n Proto 1.3.0.

To rebuild the complete module, install WASIXCC 0.4.7, Ninja, CMake, Node, and Git, then run `yarn build-osmx`. The build validates `wasix-sources.lock.json`, exports OSMExpress and S2 into a clean `.wasix-work` tree, fetches dependency sources at immutable commits, and applies repository-specific WASIX patches. OpenSSL, zlib, and bzip2 are downloaded from the checksum-pinned official `wasix-org/build-scripts` v0.1.0 release into `.wasix-cache`; Expat and the WASIX-compatible LMDB sources are pinned under `vendor/`. Every source, release archive, and linked static library is verified before use. Run `yarn verify:wasix-sources` to verify clean patch application, or `yarn verify:wasix-repro` to perform two independent clean builds and compare them byte for byte against the locked engine digest.

The build uses `MDB_VL32`, so the wasm32 writer retains a 2 TiB logical LMDB limit while mapping only metadata and bounded page windows; it does not reserve 2 TiB of WebAssembly memory or preallocate the output file. The resulting database uses the same 64-bit format consumed by native OSMExpress and this package's TypeScript reader.

OSMX databases must remain immutable while a `Transaction` is active. The read-only WebAssembly implementation does not participate in LMDB's native lock table.

## License

Protovoters: free, accessible voter files for democracy
Copyright (C) 2026 Software Freedom Conservancy

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.