@mailwoman/spatial

Spatial analysis, geocoding, and geo-related utilities for the Mailwoman ecosystem. Provides coordinate math, H3 hexagonal grid indexing, WKB geometry parsing, and coordinate-string parsing.

import { haversineKm, latLngToCell, parseCoordinateString } from "@mailwoman/spatial"

// Great-circle distance
const km = haversineKm(37.7749, -122.4194, 34.0522, -118.2437) // SF → LA

// H3 grid cell
const cell = latLngToCell(37.7749, -122.4194, 9) // resolution-9 H3 index

// Parse coordinate strings
const loc = parseCoordinateString("37.7749° N, 122.4194° W")

What's inside

| Capability | Implementation | | ---------------------- | --------------------------------------------------------------------------- | | Coordinate math | Haversine distance, bearing, bounding-box containment | | H3 indexing | Hexagonal grid indexing via h3-js — spatial blocking for the matcher | | WKB/WKT geometry | Parse/format Well-Known Binary geometry via wkx | | Coordinate parsing | Parse decimal, DMS, and UTM coordinate strings via geo-coordinates-parser | | GeoJSON | GeoJSON Feature/FeatureCollection types and utilities |

Dependencies

• h3-js — Uber's hexagonal hierarchical geospatial indexing system
• wkx — Well-Known Binary geometry parser
• geo-coordinates-parser — coordinate string parsing

Optional: @googlemaps/google-maps-services-js for Google Maps API integration.

Related

• @mailwoman/match — uses H3 cells for geo-first record blocking
• @mailwoman/address-id — uses H3 for stable address primary keys
• @mailwoman/core — consumes spatial types
• @mailwoman/codex/country — ISO 3166-1 country codes and names. This package once carried a byte-identical second copy of that table under countries/ (salvaged from isp-nexus alongside the geometry code, never imported by anything). It was deleted 2026-08-04; country reference data belongs to codex, not to the math home.

License

AGPL-3.0-only