geohash-kit 1.0.0

package/LICENCE

@@ -0,0 +1,21 @@
+MIT Licence
+
+Copyright (c) 2026 TheCryptoDonkey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,250 @@
+# geohash-kit
+
+**The modern TypeScript geohash toolkit — encode, decode, cover polygons, and discover location-based Nostr events.**
+
+[![npm](https://img.shields.io/npm/v/geohash-kit)](https://www.npmjs.com/package/geohash-kit)
+[![licence](https://img.shields.io/npm/l/geohash-kit)](./LICENCE)
+![zero deps](https://img.shields.io/badge/dependencies-0-brightgreen)
+![TypeScript](https://img.shields.io/badge/TypeScript-native-blue)
+
+## Why geohash-kit?
+
+- **Modern TypeScript** — native types, ESM-only, tree-shakeable subpath exports. Zero dependencies. A drop-in replacement for `ngeohash`.
+- **Smart polygon coverage** — adaptive multi-precision subdivision produces compact geohash sets (coarse interior, fine edges). Other polygon libraries use single-precision brute-force, producing 10-100x more cells for the same area.
+- **Production-hardened** — input validation on all public APIs, RangeError on invalid/infeasible parameters, 736 tests including fuzz and property-based suites.
+- **Nostr-native** — generates multi-precision `g`-tag ladders for publishing and location-based `#g` filter arrays for REQ subscriptions. Perfect for building location-based Nostr applications.
+
+## Install
+
+```bash
+npm install geohash-kit
+```
+
+## Quick Start
+
+```typescript
+import {
+  encode, decode, neighbours, distance,
+  polygonToGeohashes, geohashesToGeoJSON,
+  createGTagLadder, createGTagFilter,
+} from 'geohash-kit'
+
+// Encode a location
+const hash = encode(51.5074, -0.1278)  // 'gcpvj'
+
+// Decode back to coordinates
+const { lat, lon, error } = decode(hash)
+
+// Get adjacent cells
+const adj = neighbours(hash)  // { n, ne, e, se, s, sw, w, nw }
+
+// Distance between two geohashes
+const d = distance('gcpvj', 'u09tu')  // ~340km (London → Paris)
+
+// Cover a polygon with geohashes
+const coverage = polygonToGeohashes([
+  [-0.15, 51.50], [-0.10, 51.50],
+  [-0.10, 51.52], [-0.15, 51.52],
+])
+
+// Render coverage on a map
+const geojson = geohashesToGeoJSON(coverage)
+
+// Cover a donut polygon (outer ring with a hole)
+const donut = polygonToGeohashes({
+  type: 'Polygon',
+  coordinates: [
+    [[-0.15, 51.49], [-0.05, 51.49], [-0.05, 51.54], [-0.15, 51.54], [-0.15, 51.49]],
+    [[-0.12, 51.51], [-0.08, 51.51], [-0.08, 51.53], [-0.12, 51.53], [-0.12, 51.51]],
+  ],
+})
+
+// Generate Nostr event tags
+const tags = createGTagLadder(hash)
+// [['g','g'], ['g','gc'], ['g','gcp'], ['g','gcpv'], ['g','gcpvj']]
+
+// Generate Nostr subscription filter
+const filter = createGTagFilter(51.5074, -0.1278, 5000)
+// { '#g': ['gcpvj', 'gcpvm', ...] }
+```
+
+## For Nostr Developers
+
+Nostr relays match `#g` tags by exact equality — there's no prefix matching. An event tagged `["g", "gcpvjb"]` won't match filter `{"#g": ["gcpvj"]}`. The workaround is a **tag ladder**: publish every precision prefix, subscribe at the right precision with neighbour expansion.
+
+**Building location-based Nostr apps?** Use geohash-kit to:
+- Tag events with multi-precision `g`-tag ladders for geographic discoverability
+- Query nearby events using ring-based expansion (`expandRings`)
+- Filter subscriptions by location using geohash proximity matching
+
+### Publishing
+
+```typescript
+import { encode } from 'geohash-kit/core'
+import { createGTagLadder } from 'geohash-kit/nostr'
+
+const hash = encode(51.5074, -0.1278, 6)
+const tags = createGTagLadder(hash)
+// Add to your event: [['g','g'], ['g','gc'], ..., ['g','gcpvjb']]
+```
+
+### Subscribing
+
+```typescript
+import { createGTagFilter, nearbyFilter } from 'geohash-kit/nostr'
+
+// From coordinates + radius
+const filter = createGTagFilter(51.5074, -0.1278, 5000)
+// { '#g': ['gcpvj', ...neighbours] }
+
+// Or with explicit precision and ring count
+const filter2 = nearbyFilter(51.5074, -0.1278, { precision: 4, rings: 2 })
+```
+
+### Parsing events
+
+```typescript
+import { parseGTags, bestGeohash } from 'geohash-kit/nostr'
+
+const best = bestGeohash(event.tags)  // highest-precision g tag
+const all = parseGTags(event.tags)    // [{ geohash, precision }, ...]
+```
+
+## API Reference
+
+### `geohash-kit/core`
+
+| Function | Description |
+|----------|-------------|
+| `encode(lat, lon, precision?)` | Encode coordinates to geohash (default precision 5) |
+| `decode(hash)` | Decode to `{ lat, lon, error }` |
+| `bounds(hash)` | Bounding rectangle `{ minLat, maxLat, minLon, maxLon }` |
+| `children(hash)` | 32 child geohashes at next precision |
+| `neighbour(hash, direction)` | Single adjacent cell |
+| `neighbours(hash)` | All 8 adjacent cells |
+| `contains(a, b)` | Bidirectional prefix containment |
+| `matchesAny(hash, candidates)` | Match against multi-precision set |
+| `distance(hashA, hashB)` | Haversine distance in metres |
+| `distanceFromCoords(lat1, lon1, lat2, lon2)` | Haversine distance in metres |
+| `radiusToPrecision(metres)` | Optimal precision for search radius |
+| `precisionToRadius(precision)` | Approximate cell radius in metres |
+
+### `geohash-kit/coverage`
+
+| Function | Description |
+|----------|-------------|
+| `polygonToGeohashes(polygon, options?)` | Adaptive threshold polygon coverage; accepts `[lon, lat][]`, GeoJSON `Polygon` (with holes), or `MultiPolygon` |
+| `geohashesToGeoJSON(hashes)` | GeoJSON FeatureCollection for map rendering |
+| `geohashesToConvexHull(hashes)` | Convex hull reconstruction |
+| `deduplicateGeohashes(hashes, options?)` | Remove redundant ancestors; `{ lossy: true }` merges ≥30/32 siblings |
+| `pointInPolygon(point, polygon)` | Ray-casting point-in-polygon test |
+| `boundsOverlapsPolygon(bounds, polygon)` | Bounds–polygon overlap test |
+| `boundsFullyInsidePolygon(bounds, polygon)` | Bounds fully inside polygon test |
+
+**`CoverageOptions`:** `{ minPrecision?, maxPrecision?, maxCells?, mergeThreshold? }`
+
+**`PolygonInput`:** `[number, number][] | GeoJSONPolygon | GeoJSONMultiPolygon`
+
+### `geohash-kit/nostr`
+
+| Function | Description |
+|----------|-------------|
+| `createGTagLadder(geohash, minPrecision?)` | Multi-precision g-tag ladder |
+| `createGTagFilter(lat, lon, radiusMetres)` | REQ filter from coordinates |
+| `createGTagFilterFromGeohashes(hashes)` | REQ filter from hash set |
+| `expandRings(hash, rings?)` | Concentric neighbour rings |
+| `nearbyFilter(lat, lon, options?)` | Encode + expand + filter |
+| `parseGTags(tags)` | Extract g tags from event |
+| `bestGeohash(tags)` | Highest-precision g tag |
+
+## Polygon Coverage Algorithm
+
+`polygonToGeohashes` uses adaptive threshold recursive subdivision:
+
+1. BFS from precision-1 cells that overlap the polygon
+2. For each cell: fully inside → emit (if deep enough); at max precision → emit if overlaps; partial → subdivide children
+3. `mergeThreshold` controls interior cell granularity: 1.0 = uniform max precision, 0.0 = coarsest fully-inside cells
+4. If result exceeds `maxCells`, `maxPrecision` is stepped down until the result fits
+5. Post-processing merges sibling sets based on `mergeThreshold` — at threshold 1.0 only complete sets (32/32), at 0.0 as few as 24/32. Result is sorted and deduplicated
+6. If no precision level fits within `maxCells`, a `RangeError` is thrown — increase `maxCells` or reduce the polygon area
+7. **Holes:** GeoJSON Polygon inner rings (holes) are respected — cells fully inside a hole are excluded, cells overlapping a hole boundary subdivide to `maxPrecision` for accuracy. Degenerate holes (< 3 vertices) are silently ignored
+8. **MultiPolygon:** `maxCells` is enforced globally across all child polygons, not per-polygon. The algorithm steps down precision until the merged result fits the budget
+
+**Memory:** `polygonToGeohashes` builds the full result array in memory. At `maxCells: 100,000` with average hash length 6, this is roughly 1–2 MB — well within typical Node.js/browser limits. For extremely large polygons (millions of cells), consider splitting the polygon into smaller regions and processing each independently.
+
+## Comparison
+
+| Feature | geohash-kit | ngeohash | geohashing | latlon-geohash | geohash-poly | shape2geohash | nostr-geotags |
+|---------|:-----------:|:--------:|:----------:|:--------------:|:------------:|:-------------:|:-------------:|
+| TypeScript native | **Yes** | No | Yes | No | No | No | Yes |
+| ESM-only | **Yes** | No | No | Yes | No | No | Yes |
+| Zero dependencies | **Yes** | Yes | Yes | Yes | No (10) | No (11) | No (2) |
+| Polygon → geohashes | **Multi-precision** | — | — | — | Single-precision | Single-precision | — |
+| Multi-precision output | **Yes** | — | — | — | No | No | — |
+| maxCells budget | **Yes** | — | — | — | No | No | — |
+| GeoJSON output | **Yes** | No | Yes | No | No | No | No |
+| Convex hull | **Yes** | No | No | No | No | No | No |
+| Deduplication | **Yes** | No | No | No | No | No | No |
+| Distance / radius | **Yes** | No | No | No | No | No | No |
+| Neighbours / rings | **Yes** | Yes | Yes | Yes | No | No | No |
+| Nostr g-tag ladders | **Yes** | No | No | No | No | No | Partial |
+| Nostr REQ filters | **Yes** | No | No | No | No | No | No |
+| Input validation | **Yes** | No | No | No | No | No | No |
+| Last published | 2026 | 2018 | 2024 | 2019 | 2019 | 2022 | 2025 |
+| Weekly downloads | — | ~171k | ~7k | ~19k | ~1k | ~500 | <100 |
+
+## Migrating from ngeohash
+
+geohash-kit is a modern TypeScript replacement for [ngeohash](https://github.com/sunng87/node-geohash).
+
+**Import change:**
+
+```typescript
+// Before
+const ngeohash = require('ngeohash')
+
+// After (ESM)
+import { encode, decode, bounds, neighbours } from 'geohash-kit'
+```
+
+**Function mapping:**
+
+| ngeohash | geohash-kit | Notes |
+|----------|-------------|-------|
+| `encode(lat, lon, precision?)` | `encode(lat, lon, precision?)` | Same signature |
+| `decode(hash)` | `decode(hash)` | Returns `{ lat, lon, error }` instead of `{ latitude, longitude, error }` |
+| `decode_bbox(hash)` | `bounds(hash)` | Returns `{ minLat, maxLat, minLon, maxLon }` object instead of `[minlat, minlon, maxlat, maxlon]` array |
+| `neighbors(hash)` | `neighbours(hash)` | British spelling; returns `{ n, ne, e, ... }` object instead of array |
+| `neighbor(hash, [latDir, lonDir])` | `neighbour(hash, direction)` | Direction is a string (`'n'`, `'sw'`, etc.) instead of `[1, 0]` array |
+| `bboxes(minLat, minLon, maxLat, maxLon, precision)` | `polygonToGeohashes(polygon)` | More powerful: accepts polygons (not just rectangles), multi-precision output, maxCells budget |
+| `encode_int` / `decode_int` / `*_int` | — | Integer geohash encoding not supported |
+
+**Key differences:**
+
+- **ESM-only** — no `require()`, use `import` syntax
+- **Input validation** — throws `RangeError` on invalid coordinates, NaN, or Infinity (ngeohash returns garbage)
+- **British English** — `neighbours` not `neighbors`, `neighbour` not `neighbor`
+- **Structured returns** — named object properties instead of positional arrays
+
+## Benchmarking
+
+geohash-kit includes comprehensive performance benchmarks for all major functions. Run them with:
+
+```bash
+npm run bench
+```
+
+Performance summary:
+- **Core functions** (encode, decode, bounds, etc.): >5M ops/sec, all sub-100µs
+- **`polygonToGeohashes`** (the main workhorse): 282–7,230 ops/sec depending on polygon size and precision
+- **Nostr functions** (tag ladders, filters): 256k–10M ops/sec
+
+For detailed performance analysis, device comparisons, and optimization guidance, see [docs/BENCHMARKS.md](./docs/BENCHMARKS.md).
+
+## For AI Assistants
+
+See [llms.txt](./llms.txt) for a concise API summary, or [llms-full.txt](./llms-full.txt) for the complete reference with examples.
+
+## Licence
+
+[MIT](./LICENCE)

package/dist/core.d.ts

@@ -0,0 +1,39 @@
+export interface GeohashBounds {
+    minLat: number;
+    maxLat: number;
+    minLon: number;
+    maxLon: number;
+}
+export type Direction = 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'nw';
+/** Encode latitude/longitude to a geohash string. Default precision 5 (~4.9km). */
+export declare function encode(lat: number, lon: number, precision?: number): string;
+/** Decode a geohash to its centre point with error margins. */
+export declare function decode(hash: string): {
+    lat: number;
+    lon: number;
+    error: {
+        lat: number;
+        lon: number;
+    };
+};
+/** Get the bounding rectangle of a geohash cell. */
+export declare function bounds(hash: string): GeohashBounds;
+/** Get the 32 children of a geohash at the next precision level. */
+export declare function children(hash: string): string[];
+/** Check if two geohashes overlap (bidirectional prefix containment). */
+export declare function contains(a: string, b: string): boolean;
+/** Check if a geohash matches any candidate in a multi-precision set. */
+export declare function matchesAny(hash: string, candidates: string[]): boolean;
+/** Get a single adjacent geohash cell in the given direction. */
+export declare function neighbour(hash: string, direction: Direction): string;
+/** Get all 8 adjacent geohash cells. */
+export declare function neighbours(hash: string): Record<Direction, string>;
+/** Haversine distance in metres between two coordinate pairs. */
+export declare function distanceFromCoords(lat1: number, lon1: number, lat2: number, lon2: number): number;
+/** Haversine distance in metres between centres of two geohash cells. */
+export declare function distance(hashA: string, hashB: string): number;
+/** Optimal geohash precision for a given search radius in metres. */
+export declare function radiusToPrecision(metres: number): number;
+/** Approximate cell radius in metres for a given precision level. */
+export declare function precisionToRadius(precision: number): number;
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,CAAA;AAczE,mFAAmF;AACnF,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,SAAI,GAAG,MAAM,CA2BtE;AAED,+DAA+D;AAC/D,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAWtG;AAED,oDAAoD;AACpD,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAoBlD;AAED,oEAAoE;AACpE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAG/C;AAID,yEAAyE;AACzE,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,yEAAyE;AACzE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAEtE;AAID,iEAAiE;AACjE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,MAAM,CA0BpE;AAED,wCAAwC;AACxC,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAWlE;AAMD,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAWjG;AAED,yEAAyE;AACzE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAI7D;AAkBD,qEAAqE;AACrE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAMxD;AAED,qEAAqE;AACrE,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAI3D"}

package/dist/core.js

@@ -0,0 +1,213 @@
+// geohash-kit/core — encode, decode, bounds, children, contains, matchesAny
+const BASE32 = '0123456789bcdefghjkmnpqrstuvwxyz';
+const BASE32_DECODE = {};
+for (let i = 0; i < BASE32.length; i++)
+    BASE32_DECODE[BASE32[i]] = i;
+// --- Validation ---
+function validateGeohash(hash) {
+    for (const ch of hash) {
+        if (!(ch in BASE32_DECODE)) {
+            throw new TypeError(`Invalid geohash character: '${ch}' in "${hash}"`);
+        }
+    }
+}
+// --- Encoding ---
+/** Encode latitude/longitude to a geohash string. Default precision 5 (~4.9km). */
+export function encode(lat, lon, precision = 5) {
+    if (!Number.isFinite(lat) || lat < -90 || lat > 90)
+        throw new RangeError(`Invalid latitude: ${lat}`);
+    if (!Number.isFinite(lon) || lon < -180 || lon > 180)
+        throw new RangeError(`Invalid longitude: ${lon}`);
+    if (!Number.isFinite(precision))
+        throw new RangeError(`Invalid precision: ${precision}`);
+    precision = Math.round(precision);
+    if (precision < 1)
+        throw new RangeError(`Invalid precision: ${precision}`);
+    precision = Math.min(12, precision);
+    let latMin = -90, latMax = 90;
+    let lonMin = -180, lonMax = 180;
+    let hash = '';
+    let bit = 0;
+    let ch = 0;
+    let isLon = true;
+    while (hash.length < precision) {
+        if (isLon) {
+            const mid = (lonMin + lonMax) / 2;
+            if (lon >= mid) {
+                ch |= 1 << (4 - bit);
+                lonMin = mid;
+            }
+            else {
+                lonMax = mid;
+            }
+        }
+        else {
+            const mid = (latMin + latMax) / 2;
+            if (lat >= mid) {
+                ch |= 1 << (4 - bit);
+                latMin = mid;
+            }
+            else {
+                latMax = mid;
+            }
+        }
+        isLon = !isLon;
+        bit++;
+        if (bit === 5) {
+            hash += BASE32[ch];
+            bit = 0;
+            ch = 0;
+        }
+    }
+    return hash;
+}
+/** Decode a geohash to its centre point with error margins. */
+export function decode(hash) {
+    if (hash.length === 0)
+        throw new TypeError('Cannot decode an empty geohash');
+    const b = bounds(hash);
+    return {
+        lat: (b.minLat + b.maxLat) / 2,
+        lon: (b.minLon + b.maxLon) / 2,
+        error: {
+            lat: (b.maxLat - b.minLat) / 2,
+            lon: (b.maxLon - b.minLon) / 2,
+        },
+    };
+}
+/** Get the bounding rectangle of a geohash cell. */
+export function bounds(hash) {
+    validateGeohash(hash);
+    let minLat = -90, maxLat = 90;
+    let minLon = -180, maxLon = 180;
+    let isLon = true;
+    for (const ch of hash) {
+        const bits = BASE32_DECODE[ch];
+        for (let bit = 4; bit >= 0; bit--) {
+            if (isLon) {
+                const mid = (minLon + maxLon) / 2;
+                if ((bits >> bit) & 1)
+                    minLon = mid;
+                else
+                    maxLon = mid;
+            }
+            else {
+                const mid = (minLat + maxLat) / 2;
+                if ((bits >> bit) & 1)
+                    minLat = mid;
+                else
+                    maxLat = mid;
+            }
+            isLon = !isLon;
+        }
+    }
+    return { minLat, maxLat, minLon, maxLon };
+}
+/** Get the 32 children of a geohash at the next precision level. */
+export function children(hash) {
+    validateGeohash(hash);
+    return Array.from(BASE32, (ch) => hash + ch);
+}
+// --- Matching ---
+/** Check if two geohashes overlap (bidirectional prefix containment). */
+export function contains(a, b) {
+    return a.startsWith(b) || b.startsWith(a);
+}
+/** Check if a geohash matches any candidate in a multi-precision set. */
+export function matchesAny(hash, candidates) {
+    return candidates.some(c => contains(hash, c));
+}
+// --- Neighbours ---
+/** Get a single adjacent geohash cell in the given direction. */
+export function neighbour(hash, direction) {
+    const b = bounds(hash);
+    const latHeight = b.maxLat - b.minLat;
+    const lonWidth = b.maxLon - b.minLon;
+    const centreLat = (b.minLat + b.maxLat) / 2;
+    const centreLon = (b.minLon + b.maxLon) / 2;
+    let dLat = 0;
+    let dLon = 0;
+    if (direction.includes('n'))
+        dLat = latHeight;
+    if (direction.includes('s'))
+        dLat = -latHeight;
+    if (direction.includes('e'))
+        dLon = lonWidth;
+    if (direction.includes('w'))
+        dLon = -lonWidth;
+    let newLat = centreLat + dLat;
+    let newLon = centreLon + dLon;
+    // Wrap longitude around the antimeridian
+    if (newLon > 180)
+        newLon -= 360;
+    if (newLon < -180)
+        newLon += 360;
+    // Clamp latitude at poles (no wrapping)
+    newLat = Math.max(-89.99999, Math.min(89.99999, newLat));
+    return encode(newLat, newLon, hash.length);
+}
+/** Get all 8 adjacent geohash cells. */
+export function neighbours(hash) {
+    return {
+        n: neighbour(hash, 'n'),
+        ne: neighbour(hash, 'ne'),
+        e: neighbour(hash, 'e'),
+        se: neighbour(hash, 'se'),
+        s: neighbour(hash, 's'),
+        sw: neighbour(hash, 'sw'),
+        w: neighbour(hash, 'w'),
+        nw: neighbour(hash, 'nw'),
+    };
+}
+// --- Distance ---
+const EARTH_RADIUS_M = 6_371_000; // Earth mean radius in metres
+/** Haversine distance in metres between two coordinate pairs. */
+export function distanceFromCoords(lat1, lon1, lat2, lon2) {
+    if (!Number.isFinite(lat1) || !Number.isFinite(lon1) || !Number.isFinite(lat2) || !Number.isFinite(lon2)) {
+        throw new RangeError('All coordinate arguments must be finite numbers');
+    }
+    const toRad = (deg) => (deg * Math.PI) / 180;
+    const dLat = toRad(lat2 - lat1);
+    const dLon = toRad(lon2 - lon1);
+    const a = Math.sin(dLat / 2) ** 2 +
+        Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLon / 2) ** 2;
+    return EARTH_RADIUS_M * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+}
+/** Haversine distance in metres between centres of two geohash cells. */
+export function distance(hashA, hashB) {
+    const a = decode(hashA);
+    const b = decode(hashB);
+    return distanceFromCoords(a.lat, a.lon, b.lat, b.lon);
+}
+// --- Precision ↔ Radius ---
+// Approximate cell half-diagonal in metres at each precision level (equator).
+const PRECISION_RADIUS_M = [
+    /* 0 (unused) */ 0,
+    /* 1 */ 2_500_000,
+    /* 2 */ 630_000,
+    /* 3 */ 78_000,
+    /* 4 */ 20_000,
+    /* 5 */ 2_400,
+    /* 6 */ 610,
+    /* 7 */ 76,
+    /* 8 */ 19,
+    /* 9 */ 2.4,
+];
+/** Optimal geohash precision for a given search radius in metres. */
+export function radiusToPrecision(metres) {
+    if (!Number.isFinite(metres) || metres < 0)
+        throw new RangeError(`Invalid radius: ${metres}`);
+    for (let p = 1; p <= 9; p++) {
+        if (PRECISION_RADIUS_M[p] <= metres)
+            return p;
+    }
+    return 9;
+}
+/** Approximate cell radius in metres for a given precision level. */
+export function precisionToRadius(precision) {
+    if (!Number.isFinite(precision))
+        throw new RangeError(`Invalid precision: ${precision}`);
+    const p = Math.max(1, Math.min(9, Math.round(precision)));
+    return PRECISION_RADIUS_M[p];
+}
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"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"}

package/dist/coverage.d.ts

@@ -0,0 +1,86 @@
+import type { GeohashBounds } from './core.js';
+import type { PolygonInput } from './geojson.js';
+export type { GeohashBounds } from './core.js';
+export type { PolygonInput, GeoJSONPolygon, GeoJSONMultiPolygon } from './geojson.js';
+/**
+ * Ray-casting algorithm: test whether a point [x, y] lies inside a polygon.
+ * Polygon is an array of [x, y] vertices (closed automatically).
+ */
+export declare function pointInPolygon(point: [number, number], polygon: [number, number][]): boolean;
+/**
+ * Test whether all four corners of bounds lie inside the polygon.
+ */
+export declare function boundsFullyInsidePolygon(bounds: GeohashBounds, polygon: [number, number][]): boolean;
+/**
+ * Test whether a bounds rectangle overlaps a polygon at all.
+ * Checks: (1) any bounds corner inside polygon, (2) any polygon vertex inside bounds,
+ * (3) any edge intersection.
+ */
+export declare function boundsOverlapsPolygon(bounds: GeohashBounds, polygon: [number, number][]): boolean;
+export interface CoverageOptions {
+    minPrecision?: number;
+    maxPrecision?: number;
+    maxCells?: number;
+    mergeThreshold?: number;
+}
+/**
+ * Convert a polygon (array of [lon, lat] vertices) to an efficient set of
+ * multi-precision geohash strings using recursive subdivision.
+ *
+ * Edges always subdivide to maxPrecision for a tight boundary. Interior
+ * cells use the coarsest precision allowed by mergeThreshold. If the result
+ * exceeds maxCells, maxPrecision is stepped down until it fits.
+ *
+ * Throws RangeError if the polygon cannot be covered within maxCells at
+ * the given minPrecision.
+ *
+ * **Antimeridian:** polygons crossing ±180° longitude are not supported.
+ * Split at the antimeridian and cover each half separately.
+ */
+export declare function polygonToGeohashes(input: PolygonInput, options?: CoverageOptions): string[];
+/**
+ * Compute a convex hull polygon from an array of geohash strings.
+ * Collects all unique cell corners, then builds the hull using
+ * Andrew's monotone chain algorithm.
+ * Returns `[lon, lat][]`.
+ *
+ * **Antimeridian:** throws if the input hashes straddle ±180° longitude.
+ * Dateline-crossing hulls cannot be consumed by planar geometry functions
+ * (`pointInPolygon`, `polygonToGeohashes`). Split hash sets at the
+ * antimeridian and compute separate hulls for each side.
+ */
+export declare function geohashesToConvexHull(hashes: string[]): [number, number][];
+export interface DeduplicateOptions {
+    /**
+     * Allow near-complete sibling merges (30/32) for a smaller result array.
+     * Trades a tiny boundary overshoot for fewer cells. Default: `false` (exact).
+     */
+    lossy?: boolean;
+}
+/**
+ * Remove redundant geohashes and merge sibling groups.
+ * 1. Remove any geohash whose ancestor (shorter prefix) is already in the set.
+ * 2. Merge sibling sets bottom-up — exact (all 32) by default, or
+ *    near-complete (≥30/32) when `lossy: true`.
+ */
+export declare function deduplicateGeohashes(hashes: string[], options?: DeduplicateOptions): string[];
+export interface GeohashGeoJSON {
+    type: 'FeatureCollection';
+    features: {
+        type: 'Feature';
+        geometry: {
+            type: 'Polygon';
+            coordinates: [number, number][][];
+        };
+        properties: {
+            geohash: string;
+            precision: number;
+        };
+    }[];
+}
+/**
+ * Convert an array of geohash strings to a GeoJSON FeatureCollection
+ * of polygon rectangles, suitable for rendering on a MapLibre map.
+ */
+export declare function geohashesToGeoJSON(hashes: string[]): GeohashGeoJSON;
+//# sourceMappingURL=coverage.d.ts.map

package/dist/coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../src/coverage.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAuC,MAAM,cAAc,CAAA;AAGrF,YAAY,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAC9C,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAgBrF;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EACvB,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAC1B,OAAO,CAcT;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAC1B,OAAO,CAwBT;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAC1B,OAAO,CAoCT;AAoCD,MAAM,WAAW,eAAe;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AA+CD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE,eAAoB,GAC5B,MAAM,EAAE,CAmHV;AAyKD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CA8D1E;AAID,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,kBAAuB,GAAG,MAAM,EAAE,CAgBjG;AAID,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,mBAAmB,CAAA;IACzB,QAAQ,EAAE;QACR,IAAI,EAAE,SAAS,CAAA;QACf,QAAQ,EAAE;YAAE,IAAI,EAAE,SAAS,CAAC;YAAC,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,CAAA;SAAE,CAAA;QAChE,UAAU,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAA;KACnD,EAAE,CAAA;CACJ;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,cAAc,CAqBnE"}