@mailwoman/spatial 4.15.0 → 4.16.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailwoman/spatial",
-  "version": "4.15.0",
+  "version": "4.16.1",
   "description": "Spatial analysis, geocoding, and other geo-related utilities.",
   "license": "AGPL-3.0-only",
   "contributors": [
@@ -22,13 +22,14 @@
     ".": "./out/index.js"
   },
   "dependencies": {
-    "@mailwoman/core": "4.15.0",
+    "@mailwoman/core": "4.16.1",
     "geo-coordinates-parser": "^1.7.4",
     "h3-js": "^4.4.0",
     "wkx": "^0.5.0"
   },
   "devDependencies": {
     "@googlemaps/google-maps-services-js": "^3.4.2",
+    "@mailwoman/annotations": "4.16.1",
     "@types/google.maps": "^3.65.1",
     "type-fest": "^5.7.0"
   },
@@ -37,7 +38,7 @@
     "@types/google.maps": "^3.65.1"
   },
   "engines": {
-    "node": ">=22.5.1"
+    "node": ">=24.18.0"
   },
   "keywords": [
     "geo",

package/position.test.ts

@@ -0,0 +1,48 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import { haversineKm } from "@mailwoman/spatial"
+import { expect, test } from "vitest"
+
+// Earth mean radius the formula uses (RADII.km). Reference distances below are derived from it, not
+// looked up — so they pin the exact constant + formula, not an approximation.
+const R = 6371
+
+test("haversineKm: a point to itself is zero", () => {
+	expect(haversineKm(40.7128, -74.006, 40.7128, -74.006)).toBe(0)
+})
+
+test("haversineKm: one degree along the equator / a meridian is R·(π/180)", () => {
+	const oneDegree = (R * Math.PI) / 180 // ≈ 111.195 km
+	expect(haversineKm(0, 0, 0, 1)).toBeCloseTo(oneDegree, 3) // 1° longitude at the equator
+	expect(haversineKm(0, 0, 1, 0)).toBeCloseTo(oneDegree, 3) // 1° latitude along a meridian
+})
+
+test("haversineKm: antipodal points are half the great circle (R·π)", () => {
+	expect(haversineKm(0, 0, 0, 180)).toBeCloseTo(R * Math.PI, 2) // ≈ 20015.09 km
+})
+
+test("haversineKm: a real-world pair lands in the right ballpark (NYC ↔ LA)", () => {
+	const d = haversineKm(40.7128, -74.006, 34.0522, -118.2437)
+	expect(d).toBeGreaterThan(3900)
+	expect(d).toBeLessThan(3970) // ~3936 km
+})
+
+test("haversineKm: symmetric in its arguments", () => {
+	const ab = haversineKm(51.5074, -0.1278, 48.8566, 2.3522) // London → Paris
+	const ba = haversineKm(48.8566, 2.3522, 51.5074, -0.1278)
+	expect(ab).toBeCloseTo(ba, 10)
+	expect(ab).toBeGreaterThan(330)
+	expect(ab).toBeLessThan(355) // ~343 km
+})
+
+test("haversineKm: (0,0) is a real point (Gulf of Guinea), not a missing-coordinate sentinel", () => {
+	// Unlike the object-form `haversine`, the raw-scalar form has no Null-Island sentinel — 0/0 is a
+	// real coordinate, so this returns a finite distance rather than NaN.
+	const d = haversineKm(0, 0, 0.5, 0.5)
+	expect(Number.isNaN(d)).toBe(false)
+	expect(d).toBeGreaterThan(0)
+})

package/sdk/well-known-text.test.ts

@@ -0,0 +1,133 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import type { GeometryLiteral } from "@mailwoman/spatial"
+import { expect, test } from "vitest"
+import wkx from "wkx"
+import {
+	geometryToEWKB,
+	geometryToEWKH,
+	geometryToSQL,
+	geometryToWKB,
+	geometryToWKT,
+	wellKnownGeometryToGeoJSON,
+} from "./well-known-text.js"
+
+const POINT: GeometryLiteral = { type: "Point", coordinates: [30, 10] }
+
+// A closed exterior ring (last vertex repeats the first), as GeoJSON requires.
+const POLYGON: GeometryLiteral = {
+	type: "Polygon",
+	coordinates: [
+		[
+			[30, 10],
+			[40, 40],
+			[20, 40],
+			[10, 20],
+			[30, 10],
+		],
+	],
+}
+
+// The 4-level MultiPolygon literal doesn't narrow against the GeometryLiteral union; cast it.
+const MULTIPOLYGON = {
+	type: "MultiPolygon",
+	coordinates: [
+		[
+			[
+				[30, 20],
+				[45, 40],
+				[10, 40],
+				[30, 20],
+			],
+		],
+		[
+			[
+				[15, 5],
+				[40, 10],
+				[10, 20],
+				[5, 10],
+				[15, 5],
+			],
+		],
+	],
+} as unknown as GeometryLiteral
+
+test("wellKnownGeometryToGeoJSON: parses a WKT POINT into exact GeoJSON coordinates", () => {
+	const geo = wellKnownGeometryToGeoJSON<GeometryLiteral>("POINT(30 10)")
+	expect(geo).toEqual(POINT)
+})
+
+test("wellKnownGeometryToGeoJSON: parses a WKT POLYGON, preserving ring order and closure", () => {
+	const geo = wellKnownGeometryToGeoJSON<GeometryLiteral>("POLYGON((30 10,40 40,20 40,10 20,30 10))")
+	expect(geo).toEqual(POLYGON)
+})
+
+test("wellKnownGeometryToGeoJSON: parses a WKT MULTIPOLYGON into two distinct polygons", () => {
+	const geo = wellKnownGeometryToGeoJSON<GeometryLiteral>(
+		"MULTIPOLYGON(((30 20,45 40,10 40,30 20)),((15 5,40 10,10 20,5 10,15 5)))"
+	)
+	expect(geo).toEqual(MULTIPOLYGON)
+})
+
+test("wellKnownGeometryToGeoJSON: parses an EWKB buffer back into the source geometry", () => {
+	// Produce a known EWKB buffer, then round-trip it through the parser.
+	const ewkb = wkx.Geometry.parseGeoJSON(POINT).toEwkb()
+	const geo = wellKnownGeometryToGeoJSON<GeometryLiteral>(ewkb)
+	expect(geo).toEqual(POINT)
+})
+
+test("wellKnownGeometryToGeoJSON: throws on malformed WKT", () => {
+	expect(() => wellKnownGeometryToGeoJSON("NOT A GEOMETRY")).toThrow()
+})
+
+test("geometryToWKT: serializes GeoJSON back to its canonical WKT string", () => {
+	expect(geometryToWKT(POINT)).toBe("POINT(30 10)")
+	expect(geometryToWKT(POLYGON)).toBe("POLYGON((30 10,40 40,20 40,10 20,30 10))")
+	expect(geometryToWKT(MULTIPOLYGON)).toBe("MULTIPOLYGON(((30 20,45 40,10 40,30 20)),((15 5,40 10,10 20,5 10,15 5)))")
+})
+
+test("geometryToWKT ↔ wellKnownGeometryToGeoJSON: lossless round-trip for a polygon", () => {
+	const wkt = geometryToWKT(POLYGON)
+	const back = wellKnownGeometryToGeoJSON<GeometryLiteral>(wkt)
+	expect(back).toEqual(POLYGON)
+})
+
+test("geometryToWKB: produces the exact little-endian WKB byte string for a POINT", () => {
+	// 01 (LE) | 01000000 (type=Point) | 30 as float64 LE | 10 as float64 LE
+	const wkb = geometryToWKB(POINT)
+	expect(wkb.toString("hex")).toBe("01010000000000000000003e400000000000002440")
+})
+
+test("geometryToWKB: round-trips through the parser back to source GeoJSON", () => {
+	const wkb = geometryToWKB(MULTIPOLYGON)
+	const back = wkx.Geometry.parse(wkb).toGeoJSON()
+	expect(back).toEqual(MULTIPOLYGON)
+})
+
+test("geometryToEWKB: tags the geometry with the SRID-flag the plain WKB lacks", () => {
+	// EWKB sets the 0x20000000 SRID flag on the type word, so the hex differs from plain WKB.
+	const ewkb = geometryToEWKB(POINT)
+	expect(ewkb.toString("hex")).toBe("0101000020e61000000000000000003e400000000000002440")
+	// Distinct from plain WKB.
+	expect(ewkb.toString("hex")).not.toBe(geometryToWKB(POINT).toString("hex"))
+})
+
+test("geometryToEWKH: is the hex-encoded form of the EWKB buffer", () => {
+	expect(geometryToEWKH(POINT)).toBe(geometryToEWKB(POINT).toString("hex"))
+	expect(geometryToEWKH(POINT)).toBe("0101000020e61000000000000000003e400000000000002440")
+})
+
+test("geometryToSQL: returns a thunk emitting a GeomFromEWKB literal for a real geometry", () => {
+	const thunk = geometryToSQL(POINT)
+	expect(typeof thunk).toBe("function")
+	expect(thunk()).toBe(`GeomFromEWKB('${geometryToEWKH(POINT)}')`)
+})
+
+test("geometryToSQL: null/undefined geometry yields a thunk that emits the SQL literal NULL", () => {
+	expect(geometryToSQL(null)()).toBe("NULL")
+	expect(geometryToSQL(undefined)()).toBe("NULL")
+})

package/tsconfig.json

@@ -7,9 +7,10 @@
 		"emitDeclarationOnly": false,
 		"allowImportingTsExtensions": false
 	},
-	"exclude": ["./out/**/*"],
+	"exclude": ["./out/**/*", "./**/*.test.ts", "./**/*.test.tsx"],
 	"references": [
 		// ---
+		{ "path": "../annotations" },
 		{ "path": "../core" }
 	]
 }