@mailwoman/spatial 4.15.0 → 4.16.0

package/bbox.test.ts

@@ -0,0 +1,39 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import { is2DBBox, is3DBBox, isBBox } from "@mailwoman/spatial"
+import { expect, test } from "vitest"
+
+// 2D GeoJSON bbox: [west, south, east, north]. 3D adds min/max altitude: [w, s, minA, e, n, maxA].
+const BBOX_2D = [-74.1, 40.6, -73.9, 40.9]
+const BBOX_3D = [-74.1, 40.6, 0, -73.9, 40.9, 100]
+
+test("is2DBBox: a length-4 tuple is 2D; a length-6 tuple is not", () => {
+	// Regression: this guard used to check length === 6 (a copy of is3DBBox), so it never
+	// recognized a real 2D bbox.
+	expect(is2DBBox(BBOX_2D)).toBe(true)
+	expect(is2DBBox(BBOX_3D)).toBe(false)
+})
+
+test("is3DBBox: a length-6 tuple is 3D; a length-4 tuple is not", () => {
+	expect(is3DBBox(BBOX_3D)).toBe(true)
+	expect(is3DBBox(BBOX_2D)).toBe(false)
+})
+
+test("isBBox: accepts length 4 or 6, rejects other shapes", () => {
+	expect(isBBox(BBOX_2D)).toBe(true)
+	expect(isBBox(BBOX_3D)).toBe(true)
+	expect(isBBox([1, 2, 3, 4, 5])).toBe(false) // length 5
+	expect(isBBox([1, 2, 3])).toBe(false) // length 3
+})
+
+test("the bbox guards reject non-array input", () => {
+	for (const input of [null, undefined, {}, "bbox", 4, { length: 4 }]) {
+		expect(is2DBBox(input)).toBe(false)
+		expect(is3DBBox(input)).toBe(false)
+		expect(isBBox(input)).toBe(false)
+	}
+})

package/bbox.ts

@@ -109,15 +109,15 @@ export type BBox3DLiteral = [
 //#region Type Predicates
 
 /**
- * Type-predicate for 3-dimensional bounding boxes.
+ * Type-predicate for 2-dimensional bounding boxes (`[west, south, east, north]`).
  *
  * This is useful when determining the type of bounding box in a GeoJSON object.
  *
  * @category GeoJSON
  * @category Bounding Box
  */
-export function is2DBBox(input: unknown): input is BBox3DLiteral {
-	return Array.isArray(input) && input.length === 6
+export function is2DBBox(input: unknown): input is BBox2DLiteral {
+	return Array.isArray(input) && input.length === 4
 }
 
 /**

package/coordinate-formats.test.ts

@@ -0,0 +1,84 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import { expect, test } from "vitest"
+import {
+	coordinateFormatAnnotator,
+	qiblaBearing,
+	sunTimes,
+	toDMS,
+	toGeohash,
+	toMaidenhead,
+	toMercator,
+	toMGRS,
+} from "./coordinate-formats.js"
+
+// The White House (38.8977, -77.0365) — reference values cross-checked against published converters.
+const LAT = 38.8977
+const LON = -77.0365
+
+test("toDMS: signed decimals → D° M′ S″ with hemisphere", () => {
+	const dms = toDMS(LAT, LON)
+	expect(dms.lat).toBe("38° 53′ 51.72″ N")
+	expect(dms.lon).toBe("77° 2′ 11.40″ W")
+})
+
+test("toMaidenhead: 6-char locator with lowercase subsquare", () => {
+	expect(toMaidenhead(LAT, LON)).toBe("FM18lv")
+})
+
+test("toGeohash: precision-9, deterministic, DC prefix", () => {
+	const gh = toGeohash(LAT, LON)
+	expect(gh).toHaveLength(9)
+	expect(gh.startsWith("dqc")).toBe(true)
+	expect(toGeohash(LAT, LON)).toBe(gh)
+})
+
+test("toMercator: EPSG:3857 projection in range", () => {
+	const { x, y } = toMercator(LAT, LON)
+	expect(x).toBeGreaterThan(-8576000)
+	expect(x).toBeLessThan(-8575000)
+	expect(y).toBeGreaterThan(4690000)
+	expect(y).toBeLessThan(4730000)
+})
+
+test("qiblaBearing: from DC the Kaaba is ~58° (ENE)", () => {
+	const b = qiblaBearing(LAT, LON)
+	expect(b).toBeGreaterThan(54)
+	expect(b).toBeLessThan(62)
+})
+
+test("sunTimes: NYC summer solstice — sunrise ~09:26 UTC, ordered, ~15h day", () => {
+	const s = sunTimes(40.7128, -74.006, new Date("2026-06-21T12:00:00Z"))
+	const expectedRise = new Date("2026-06-21T09:26:00Z").getTime() / 1000
+	expect(Math.abs(s.rise! - expectedRise)).toBeLessThan(600) // within 10 min
+	expect(s.rise!).toBeLessThan(s.noon)
+	expect(s.noon).toBeLessThan(s.set!)
+	expect((s.set! - s.rise!) / 3600).toBeGreaterThan(14.5)
+})
+
+test("sunTimes: polar day has no sunrise/sunset, only solar noon", () => {
+	const s = sunTimes(80, 0, new Date("2026-06-21T12:00:00Z"))
+	expect(s.rise).toBeUndefined()
+	expect(s.set).toBeUndefined()
+	expect(typeof s.noon).toBe("number")
+})
+
+test("toMGRS: Washington Monument matches Wikipedia's vector (~4m); zone+band elsewhere; empty in polar bands", () => {
+	// Wikipedia MGRS article cites 18S UJ 23487 06483 for the monument; we match to ~4m.
+	expect(toMGRS(38.88949, -77.03524)).toBe("18SUJ2348306482")
+	expect(toMGRS(-33.8688, 151.2093).startsWith("56H")).toBe(true) // Sydney, zone 56 band H
+	expect(toMGRS(85, 0)).toBe("") // above 84°N — MGRS bands stop
+})
+
+test("coordinateFormatAnnotator: fills the coordinate-format slice of an AnnotationSet", () => {
+	const set = coordinateFormatAnnotator({ lat: LAT, lon: LON })
+	expect(set.maidenhead).toBe("FM18lv")
+	expect(set.geohash).toHaveLength(9)
+	expect(set.dms?.lat).toContain("N")
+	expect(typeof set.qiblaBearing).toBe("number")
+	expect(set.mercator?.x).toBeLessThan(0)
+})

package/coordinate-formats.ts

@@ -0,0 +1,215 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Coordinate-format conversions — the pure-math annotators OpenCage exposes (DMS, geohash,
+ *   Maidenhead, MGRS, Web Mercator, qibla bearing, sun times). No data, no I/O; each is a
+ *   deterministic function of a `{lat, lon}`. {@link coordinateFormatAnnotator} packages them as an
+ *   `@mailwoman/annotations` `Annotator`.
+ */
+
+import type { AnnotationSet, Annotator } from "@mailwoman/annotations"
+
+const toRad = (d: number): number => (d * Math.PI) / 180
+const toDeg = (r: number): number => (r * 180) / Math.PI
+
+/**
+ * Render a single signed degree as `D° M′ S″ H` with the given hemisphere letters `[positive,
+ * negative]`.
+ */
+function dmsComponent(value: number, hemispheres: [string, string], secondsDp = 2): string {
+	const hemisphere = value >= 0 ? hemispheres[0] : hemispheres[1]
+	const abs = Math.abs(value)
+	const degrees = Math.floor(abs)
+	const minutesFull = (abs - degrees) * 60
+	const minutes = Math.floor(minutesFull)
+	const seconds = (minutesFull - minutes) * 60
+	return `${degrees}° ${minutes}′ ${seconds.toFixed(secondsDp)}″ ${hemisphere}`
+}
+
+/** Degrees-minutes-seconds for a coordinate. */
+export function toDMS(lat: number, lon: number): { lat: string; lon: string } {
+	return { lat: dmsComponent(lat, ["N", "S"]), lon: dmsComponent(lon, ["E", "W"]) }
+}
+
+const WEB_MERCATOR_R = 6378137
+
+/** Web Mercator (EPSG:3857) projection of a coordinate. */
+export function toMercator(lat: number, lon: number): { x: number; y: number } {
+	const clampedLat = Math.max(-85.05112878, Math.min(85.05112878, lat))
+	return {
+		x: WEB_MERCATOR_R * toRad(lon),
+		y: WEB_MERCATOR_R * Math.log(Math.tan(Math.PI / 4 + toRad(clampedLat) / 2)),
+	}
+}
+
+const KAABA = { lat: 21.4225, lon: 39.8262 }
+
+/** Initial great-circle bearing (degrees from true north) from a coordinate toward the Kaaba. */
+export function qiblaBearing(lat: number, lon: number): number {
+	const phi1 = toRad(lat)
+	const phi2 = toRad(KAABA.lat)
+	const dLon = toRad(KAABA.lon - lon)
+	const y = Math.sin(dLon)
+	const x = Math.cos(phi1) * Math.tan(phi2) - Math.sin(phi1) * Math.cos(dLon)
+	return (toDeg(Math.atan2(y, x)) + 360) % 360
+}
+
+const GEOHASH_BASE32 = "0123456789bcdefghjkmnpqrstuvwxyz"
+
+/** Encode a coordinate as a geohash of the given precision (default 9 ≈ 4.8 m). */
+export function toGeohash(lat: number, lon: number, precision = 9): string {
+	let latMin = -90
+	let latMax = 90
+	let lonMin = -180
+	let lonMax = 180
+	let hash = ""
+	let bits = 0
+	let bit = 0
+	let evenBit = true
+
+	while (hash.length < precision) {
+		if (evenBit) {
+			const mid = (lonMin + lonMax) / 2
+			if (lon >= mid) {
+				bits = bits * 2 + 1
+				lonMin = mid
+			} else {
+				bits *= 2
+				lonMax = mid
+			}
+		} else {
+			const mid = (latMin + latMax) / 2
+			if (lat >= mid) {
+				bits = bits * 2 + 1
+				latMin = mid
+			} else {
+				bits *= 2
+				latMax = mid
+			}
+		}
+		evenBit = !evenBit
+		if (++bit === 5) {
+			hash += GEOHASH_BASE32[bits]
+			bit = 0
+			bits = 0
+		}
+	}
+	return hash
+}
+
+const A_CODE = "A".charCodeAt(0)
+
+/** Maidenhead grid locator (default 6-char: field uppercase, square digits, subsquare lowercase). */
+export function toMaidenhead(lat: number, lon: number, pairs = 3): string {
+	const lonAdj = lon + 180
+	const latAdj = lat + 90
+	const out = [
+		String.fromCharCode(A_CODE + Math.floor(lonAdj / 20)),
+		String.fromCharCode(A_CODE + Math.floor(latAdj / 10)),
+		String(Math.floor((lonAdj % 20) / 2)),
+		String(Math.floor(latAdj % 10)),
+		String.fromCharCode(A_CODE + Math.floor((lonAdj % 2) * 12)).toLowerCase(),
+		String.fromCharCode(A_CODE + Math.floor((latAdj % 1) * 24)).toLowerCase(),
+	]
+	return out.slice(0, pairs * 2).join("")
+}
+
+const J2000 = 2451545.0
+const unixEpochJulian = 2440587.5
+
+/**
+ * Sunrise / solar-noon / sunset for a coordinate on a date, as UTC epoch seconds, via the standard
+ * sunrise equation. `rise` and `set` are absent during polar day or polar night (the sun never
+ * crosses the horizon); `noon` (solar transit) is always present.
+ */
+export function sunTimes(
+	lat: number,
+	lon: number,
+	date: Date = new Date()
+): { rise?: number; set?: number; noon: number } {
+	const julian = date.getTime() / 86400000 + unixEpochJulian
+	const n = Math.round(julian - J2000 - 0.0009 + lon / 360)
+	const meanSolarTime = n + 0.0009 - lon / 360
+	const M = (357.5291 + 0.98560028 * meanSolarTime) % 360
+	const Mr = toRad(M)
+	const center = 1.9148 * Math.sin(Mr) + 0.02 * Math.sin(2 * Mr) + 0.0003 * Math.sin(3 * Mr)
+	const lambda = toRad((M + center + 180 + 102.9372) % 360)
+	const transit = J2000 + meanSolarTime + 0.0053 * Math.sin(Mr) - 0.0069 * Math.sin(2 * lambda)
+	const declination = Math.asin(Math.sin(lambda) * Math.sin(toRad(23.4397)))
+	const latR = toRad(lat)
+	const cosH =
+		(Math.sin(toRad(-0.833)) - Math.sin(latR) * Math.sin(declination)) / (Math.cos(latR) * Math.cos(declination))
+	const toEpoch = (j: number): number => Math.round((j - unixEpochJulian) * 86400)
+	const noon = toEpoch(transit)
+	if (cosH >= 1 || cosH <= -1) return { noon }
+	const hourAngle = toDeg(Math.acos(cosH))
+	return { rise: toEpoch(transit - hourAngle / 360), set: toEpoch(transit + hourAngle / 360), noon }
+}
+
+// MGRS / UTM (WGS84). The forward Transverse Mercator series + the military grid lettering.
+const UTM_A = 6378137.0
+const UTM_F = 1 / 298.257223563
+const UTM_K0 = 0.9996
+const UTM_E2 = UTM_F * (2 - UTM_F)
+const UTM_EP2 = UTM_E2 / (1 - UTM_E2)
+
+function latLonToUtm(lat: number, lon: number): { zone: number; easting: number; northing: number } {
+	const zone = Math.floor((lon + 180) / 6) + 1
+	const lon0 = toRad((zone - 1) * 6 - 180 + 3)
+	const phi = toRad(lat)
+	const N = UTM_A / Math.sqrt(1 - UTM_E2 * Math.sin(phi) ** 2)
+	const T = Math.tan(phi) ** 2
+	const C = UTM_EP2 * Math.cos(phi) ** 2
+	const A = Math.cos(phi) * (toRad(lon) - lon0)
+	const M =
+		UTM_A *
+		((1 - UTM_E2 / 4 - (3 * UTM_E2 ** 2) / 64 - (5 * UTM_E2 ** 3) / 256) * phi -
+			((3 * UTM_E2) / 8 + (3 * UTM_E2 ** 2) / 32 + (45 * UTM_E2 ** 3) / 1024) * Math.sin(2 * phi) +
+			((15 * UTM_E2 ** 2) / 256 + (45 * UTM_E2 ** 3) / 1024) * Math.sin(4 * phi) -
+			((35 * UTM_E2 ** 3) / 3072) * Math.sin(6 * phi))
+	const easting =
+		UTM_K0 * N * (A + ((1 - T + C) * A ** 3) / 6 + ((5 - 18 * T + T ** 2 + 72 * C - 58 * UTM_EP2) * A ** 5) / 120) +
+		500000
+	let northing =
+		UTM_K0 *
+		(M +
+			N *
+				Math.tan(phi) *
+				(A ** 2 / 2 +
+					((5 - T + 9 * C + 4 * C ** 2) * A ** 4) / 24 +
+					((61 - 58 * T + T ** 2 + 600 * C - 330 * UTM_EP2) * A ** 6) / 720))
+	if (lat < 0) northing += 10000000
+	return { zone, easting, northing }
+}
+
+const MGRS_LAT_BANDS = "CDEFGHJKLMNPQRSTUVWX"
+const MGRS_COL_SETS = ["ABCDEFGH", "JKLMNPQR", "STUVWXYZ"]
+const MGRS_ROW_LETTERS = "ABCDEFGHJKLMNPQRSTUV"
+
+/** Military Grid Reference System for a coordinate (`"18SUJ2340806479"`); `""` outside MGRS bands
+(±80°/84°). */
+export function toMGRS(lat: number, lon: number): string {
+	if (lat < -80 || lat > 84) return ""
+	const band = MGRS_LAT_BANDS[Math.floor((lat + 80) / 8)]!
+	const { zone, easting, northing } = latLonToUtm(lat, lon)
+	const colLetter = MGRS_COL_SETS[(zone - 1) % 3]![Math.floor(easting / 100000) - 1]!
+	let row = Math.floor(northing / 100000) % 20
+	if (zone % 2 === 0) row = (row + 5) % 20
+	const rowLetter = MGRS_ROW_LETTERS[row]!
+	const e = String(Math.floor(easting % 100000)).padStart(5, "0")
+	const n = String(Math.floor(northing % 100000)).padStart(5, "0")
+	return `${zone}${band}${colLetter}${rowLetter}${e}${n}`
+}
+
+/** Fill the coordinate-format slice of an {@link AnnotationSet} from a `{lat, lon}`. */
+export const coordinateFormatAnnotator: Annotator = ({ lat, lon, date }): Partial<AnnotationSet> => ({
+	dms: toDMS(lat, lon),
+	geohash: toGeohash(lat, lon),
+	maidenhead: toMaidenhead(lat, lon),
+	mgrs: toMGRS(lat, lon) || undefined,
+	mercator: toMercator(lat, lon),
+	qiblaBearing: qiblaBearing(lat, lon),
+	sun: sunTimes(lat, lon, date),
+})

package/feature.ts

@@ -8,7 +8,7 @@
 import { type GeometryLiteral } from "./geometries/index.js"
 
 export interface IdentifiableGeoFeature {
-	GEOID: any
+	GEOID: string | number
 }
 
 /**
@@ -16,7 +16,7 @@ export interface IdentifiableGeoFeature {
  *
  * @see https://tools.ietf.org/html/rfc7946#section-3.2
  */
-export interface GeoFeature<G = GeometryLiteral, P extends object | null = null> {
+export interface GeoFeature<G = GeometryLiteral, P extends object | null = never> {
 	/**
 	 * Declares the type of GeoJSON object as a `Feature`.
 	 */
@@ -31,7 +31,7 @@ export interface GeoFeature<G = GeometryLiteral, P extends object | null = null>
 	/**
 	 * A unique identifier for the feature, such as a UUID, a serial number, or a name.
 	 */
-	id: P extends IdentifiableGeoFeature ? P["GEOID"] : string | number | undefined | null
+	id?: P extends IdentifiableGeoFeature ? P["GEOID"] : never
 
 	/**
 	 * Additional properties associated with a GeoJSON object.

package/geometries/point.test.ts

@@ -0,0 +1,144 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import { GeoPoint } from "@mailwoman/spatial"
+import { expect, test } from "vitest"
+
+// GeoPoint stores GeoJSON [longitude, latitude(, altitude)] order. `from` recognizes several input
+// shapes and treats a 0/0 coordinate (Null Island) as a "missing coordinate" sentinel → null.
+
+test("GeoPoint.from: a 2-tuple is read as GeoJSON [longitude, latitude]", () => {
+	// coordA = -74 is in [-90, 90] so inferGeoJSONCoordOrder can't disambiguate; it falls through to
+	// the default, leaving the pair as-is: longitude = -74, latitude = 40.7.
+	const point = GeoPoint.from([-74.006, 40.7128])!
+
+	expect(point).not.toBeNull()
+	expect(point.longitude).toBe(-74.006)
+	expect(point.latitude).toBe(40.7128)
+	expect(point.altitude).toBe(0)
+	expect(point.is2D()).toBe(true)
+})
+
+test("GeoPoint.from: an out-of-lat-range longitude is recognized as longitude", () => {
+	// coordA = -118.24 is outside [-90, 90] → unambiguously the longitude; coordB = 34.05 is latitude.
+	const point = GeoPoint.from([-118.2437, 34.0522])!
+
+	expect(point.longitude).toBe(-118.2437)
+	expect(point.latitude).toBe(34.0522)
+})
+
+test("GeoPoint.from: a 3-tuple is used directly as [longitude, latitude, altitude]", () => {
+	const point = GeoPoint.from([-74.006, 40.7128, 125])!
+
+	expect(point.longitude).toBe(-74.006)
+	expect(point.latitude).toBe(40.7128)
+	expect(point.altitude).toBe(125)
+	expect(point.is3D()).toBe(true)
+	expect(point.coordinates).toEqual([-74.006, 40.7128, 125])
+})
+
+test("GeoPoint.from: a PointLiteral copies coordinates verbatim (no axis inference)", () => {
+	const point = GeoPoint.from({ type: "Point", coordinates: [-74.006, 40.7128] })!
+
+	expect(point.type).toBe("Point")
+	expect(point.longitude).toBe(-74.006)
+	expect(point.latitude).toBe(40.7128)
+})
+
+test("GeoPoint.from: a Google Maps LatLngLiteral maps lng→longitude, lat→latitude", () => {
+	const point = GeoPoint.from({ lat: 40.7128, lng: -74.006 })!
+
+	expect(point.longitude).toBe(-74.006)
+	expect(point.latitude).toBe(40.7128)
+})
+
+test("GeoPoint.from: a GeolocationCoordinates-like object carries altitude through", () => {
+	const point = GeoPoint.from({ latitude: 48.8566, longitude: 2.3522, altitude: 35 })!
+
+	expect(point.longitude).toBe(2.3522)
+	expect(point.latitude).toBe(48.8566)
+	expect(point.altitude).toBe(35)
+	expect(point.is3D()).toBe(true)
+})
+
+test("GeoPoint.from: internal {x, y} coordinates map x→longitude, y→latitude", () => {
+	const point = GeoPoint.from({ x: -74.006, y: 40.7128 })!
+
+	expect(point.longitude).toBe(-74.006)
+	expect(point.latitude).toBe(40.7128)
+	expect(point.altitude).toBe(0)
+})
+
+test("GeoPoint.from: a bracketless coordinate string is parsed into a pair", () => {
+	// "-74.006,40.7128" isn't valid JSON, so `from` retries as "[-74.006,40.7128]".
+	const point = GeoPoint.from("-74.006,40.7128")!
+
+	expect(point).not.toBeNull()
+	expect(point.longitude).toBe(-74.006)
+	expect(point.latitude).toBe(40.7128)
+})
+
+test("GeoPoint.from: a JSON array string is parsed", () => {
+	const point = GeoPoint.from("[2.3522, 48.8566]")!
+
+	expect(point.longitude).toBe(2.3522)
+	expect(point.latitude).toBe(48.8566)
+})
+
+test("GeoPoint.from: an existing GeoPoint is returned unchanged", () => {
+	const original = GeoPoint.from([12.4924, 41.8902])!
+	const passed = GeoPoint.from(original)
+
+	expect(passed).toBe(original)
+})
+
+test("GeoPoint.from: the 0/0 (Null Island) sentinel resolves to null", () => {
+	expect(GeoPoint.from([0, 0])).toBeNull()
+	expect(GeoPoint.from({ type: "Point", coordinates: [0, 0] })).toBeNull()
+	expect(GeoPoint.from({ lat: 0, lng: 0 })).toBeNull()
+	expect(GeoPoint.from({ x: 0, y: 0 })).toBeNull()
+	expect(GeoPoint.from("0,0")).toBeNull()
+})
+
+test("GeoPoint.from: falsy and unparseable input resolves to null", () => {
+	expect(GeoPoint.from(null)).toBeNull()
+	expect(GeoPoint.from(undefined)).toBeNull()
+	expect(GeoPoint.from("")).toBeNull()
+	expect(GeoPoint.from(0)).toBeNull()
+	// A garbage string that is neither valid JSON nor a wrappable pair falls back to the default 0/0
+	// coordinate, which the Null-Island sentinel then rejects.
+	expect(GeoPoint.from("not-a-coordinate")).toBeNull()
+})
+
+test("GeoPoint.from: a non-zero point that is NOT Null Island survives", () => {
+	// Guards against an over-eager sentinel: a real coordinate near, but not at, the origin.
+	const point = GeoPoint.from([0.0001, 0.0001])!
+
+	expect(point).not.toBeNull()
+	expect(point.isNullIsland()).toBe(false)
+})
+
+test("GeoPoint: longitude wraps and latitude clamps on assignment", () => {
+	const point = new GeoPoint([0, 0])
+
+	point.longitude = 190 // 190 wraps to -170
+	point.latitude = 100 // clamped to the north pole
+
+	expect(point.longitude).toBe(-170)
+	expect(point.latitude).toBe(90)
+})
+
+test("GeoPoint is iterable, yielding its coordinate tuple", () => {
+	const point = GeoPoint.from([-74.006, 40.7128, 5])!
+
+	expect([...point]).toEqual([-74.006, 40.7128, 5])
+})
+
+test("GeoPoint.toJSON emits a GeoJSON Point literal", () => {
+	const point = GeoPoint.from([-74.006, 40.7128])!
+
+	expect(point.toJSON()).toEqual({ type: "Point", coordinates: [-74.006, 40.7128] })
+})

package/geometries/polygon.test.ts

@@ -0,0 +1,62 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import { expect, test } from "vitest"
+import {
+	isPolygonLiteral,
+	isResidentialElement,
+	isSolidPolygonPath,
+	polygonToOSMFilter,
+	type OSMOverpassElement,
+	type PolygonLiteral,
+} from "./polygon.js"
+
+const SOLID: PolygonLiteral = {
+	type: "Polygon",
+	coordinates: [
+		[
+			[100, 0],
+			[101, 0],
+			[101, 1],
+			[100, 1],
+			[100, 0],
+		],
+	],
+}
+
+test("isPolygonLiteral: only a {type:'Polygon', coordinates: []} object qualifies", () => {
+	expect(isPolygonLiteral(SOLID)).toBe(true)
+	expect(isPolygonLiteral({ type: "Point", coordinates: [0, 0] })).toBe(false)
+	expect(isPolygonLiteral({ type: "Polygon" })).toBe(false) // no coordinates
+	expect(isPolygonLiteral(null)).toBe(false)
+	expect(isPolygonLiteral("Polygon")).toBe(false)
+})
+
+test("isSolidPolygonPath: one ring = solid, more rings = has holes", () => {
+	expect(isSolidPolygonPath(SOLID)).toBe(true)
+	const withHole = {
+		type: "Polygon",
+		coordinates: [SOLID.coordinates[0], SOLID.coordinates[0]],
+	} as unknown as PolygonLiteral
+	expect(isSolidPolygonPath(withHole)).toBe(false)
+})
+
+test("polygonToOSMFilter: emits the exterior ring as Overpass 'lat lon' pairs (NOT GeoJSON lon,lat)", () => {
+	// GeoJSON positions are [lon, lat]; Overpass wants "lat lon" — this swap is the foot-gun.
+	expect(polygonToOSMFilter(SOLID)).toBe("poly:'0 100 0 101 1 101 1 100 0 100'")
+	expect(polygonToOSMFilter({ type: "Point" } as unknown as PolygonLiteral)).toBe("") // non-polygon → empty
+})
+
+test("isResidentialElement: rejects commercial tags + restaurants, accepts a plain address node", () => {
+	const el = (tags: Record<string, string>): OSMOverpassElement =>
+		({ type: "node", id: 1, lat: 0, lon: 0, tags }) as unknown as OSMOverpassElement
+
+	expect(isResidentialElement(el({ "addr:housenumber": "5", "addr:street": "Main" }))).toBe(true)
+	expect(isResidentialElement(el({ shop: "bakery" }))).toBe(false) // forbidden commercial tag
+	expect(isResidentialElement(el({ office: "company" }))).toBe(false)
+	expect(isResidentialElement(el({ amenity: "restaurant" }))).toBe(false) // restaurant special-case
+	expect(isResidentialElement(el({ amenity: "bench" }))).toBe(true) // a non-forbidden amenity is fine
+})

package/google/place-id.test.ts

@@ -0,0 +1,54 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import { GOOGLE_PLACE_ID_PATTERN, isGooglePlaceID } from "@mailwoman/spatial"
+import { expect, test } from "vitest"
+
+// A Google Place ID is a non-empty string of base64url-style characters: letters, digits, "_", "-".
+// The pattern is anchored end-to-end, so any other character (or an empty string) is rejected.
+
+test("isGooglePlaceID: a real 27-char Place ID is accepted", () => {
+	// Google's documented example ID for the Sydney Opera House.
+	expect(isGooglePlaceID("ChIJN1t_tDeuEmsRUsoyG83frY4")).toBe(true)
+})
+
+test("isGooglePlaceID: underscores and dashes are valid characters", () => {
+	expect(isGooglePlaceID("a_b-c_D-9")).toBe(true)
+	expect(isGooglePlaceID("____")).toBe(true)
+	expect(isGooglePlaceID("----")).toBe(true)
+})
+
+test("isGooglePlaceID: alphanumerics of any length are accepted", () => {
+	expect(isGooglePlaceID("a")).toBe(true)
+	expect(isGooglePlaceID("ABC123xyz")).toBe(true)
+})
+
+test("isGooglePlaceID: an empty string is rejected (minLength 1)", () => {
+	expect(isGooglePlaceID("")).toBe(false)
+})
+
+test("isGooglePlaceID: characters outside [A-Za-z0-9_-] are rejected", () => {
+	expect(isGooglePlaceID("has space")).toBe(false)
+	expect(isGooglePlaceID("has.dot")).toBe(false)
+	expect(isGooglePlaceID("plus+sign")).toBe(false)
+	expect(isGooglePlaceID("slash/here")).toBe(false)
+	expect(isGooglePlaceID("equals=pad")).toBe(false)
+	expect(isGooglePlaceID("emoji😀")).toBe(false)
+})
+
+test("isGooglePlaceID: the pattern is fully anchored (a bad char anywhere fails)", () => {
+	// A leading or trailing invalid character must fail even when the rest is valid — proving the
+	// regex is anchored at both ends rather than merely "contains a valid run".
+	expect(isGooglePlaceID(" ChIJN1t_tDeuEmsRUsoyG83frY4")).toBe(false)
+	expect(isGooglePlaceID("ChIJN1t_tDeuEmsRUsoyG83frY4 ")).toBe(false)
+	expect(isGooglePlaceID("valid\ninvalid")).toBe(false)
+})
+
+test("GOOGLE_PLACE_ID_PATTERN is the anchored character-class pattern", () => {
+	expect(GOOGLE_PLACE_ID_PATTERN.source).toBe("^[A-Za-z0-9_-]+$")
+	expect(GOOGLE_PLACE_ID_PATTERN.test("ChIJN1t_tDeuEmsRUsoyG83frY4")).toBe(true)
+	expect(GOOGLE_PLACE_ID_PATTERN.test("bad char")).toBe(false)
+})

package/index.ts

@@ -5,6 +5,7 @@
  */
 
 export * from "./bbox.js"
+export * from "./coordinate-formats.js"
 export * from "./countries/index.js"
 export * from "./feature.js"
 export * from "./geometries/index.js"

package/out/bbox.d.ts

@@ -96,14 +96,14 @@ export type BBox3DLiteral = [
     maxAltitude: number
 ];
 /**
- * Type-predicate for 3-dimensional bounding boxes.
+ * Type-predicate for 2-dimensional bounding boxes (`[west, south, east, north]`).
  *
  * This is useful when determining the type of bounding box in a GeoJSON object.
  *
  * @category GeoJSON
  * @category Bounding Box
  */
-export declare function is2DBBox(input: unknown): input is BBox3DLiteral;
+export declare function is2DBBox(input: unknown): input is BBox2DLiteral;
 /**
  * Type-predicate for 3-dimensional bounding boxes.
  *