@mailwoman/spatial 4.9.0

package/h3/index.ts

@@ -0,0 +1,90 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import { cellToLatLng } from "h3-js"
+import type { Tagged } from "type-fest"
+import { GeoPoint, type PointLiteral } from "../geometries/point.js"
+
+/**
+ * A H3 cell index, full 64 bits.
+ *
+ * @type {string}
+ * @title H3 Cell Index
+ * @pattern ^[0-9a-f]{15}$
+ */
+export type H3Cell = Tagged<string, "H3Cell">
+
+export function isH3Cell(value: string): value is H3Cell {
+	return /^[0-9a-f]{15}$/.test(value)
+}
+
+/**
+ * A H3 cell index, shortened to 48 bits.
+ *
+ * @type {string}
+ * @title H3 Cell Index (Short)
+ * @pattern ^[0-9a-f]{12}$
+ */
+export type H3CellShort = Tagged<string, "H3CellShort">
+
+/**
+ * Given a full H3 cell index, shorten it to 48 bits.
+ */
+export function shortenH3Cell(cell: H3Cell): H3CellShort {
+	// ...and convert it to a 48-bit cell address.
+	const cellBigInt = BigInt(`0x${cell}`)
+	// 8 f 2 aa 84 5a 18 ac 6b
+	//     aa 84 5a 18 ac 6b
+
+	// Extract the cell address without the resolution
+	const h3CellShortBigInt = cellBigInt & 0xfffffffffffffn
+
+	const h3CellShortHex = h3CellShortBigInt.toString(16)
+
+	return h3CellShortHex as H3CellShort
+}
+
+//2 aa 84 5a 18 ac 6b
+
+// 8 f2 aa 84 5a 18 ac 6b
+/**
+ * Given a short cell address, expand it to a full H3 cell index.
+ */
+export function expandH3Cell(h3CellShort: H3CellShort, resolution = 15): H3Cell {
+	// Convert the short cell address back to BigInt
+	const h3CellShortBigInt = BigInt(`0x${h3CellShort}`)
+
+	const resolutionHex = resolution.toString(16)
+	// Reassemble the H3 cell index portion...
+	const cellBigInt = h3CellShortBigInt << BigInt(8 * (15 - resolution))
+	// Back to a string...
+	const partialCell = cellBigInt.toString(16)
+	// Finally, we add the resolution back to the cell index.
+	const cell = `8${resolutionHex}${partialCell}`
+
+	return cell as H3Cell
+}
+
+/**
+ * Given a geographic point, return a short cell address.
+ */
+export function shortCellToPoint(shortCell: H3CellShort, resolution = 15): GeoPoint {
+	const cell = expandH3Cell(shortCell, resolution)
+
+	// Convert the H3 cell index back to latitude and longitude
+	const [latitude, longitude] = cellToLatLng(cell)
+
+	return new GeoPoint([longitude, latitude])
+}
+
+export function cellToPointLiteral(cell: H3Cell): PointLiteral {
+	const [latitude, longitude] = cellToLatLng(cell)
+
+	return {
+		type: "Point",
+		coordinates: [longitude, latitude],
+	}
+}

package/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+export * from "./bbox.js"
+export * from "./countries/index.js"
+export * from "./feature.js"
+export * from "./geometries/index.js"
+export * from "./google/index.js"
+export * from "./h3/index.js"
+export * from "./objects.js"
+export * from "./position.js"
+export * from "./projection.js"
+export * from "./regions/index.js"

package/objects.ts

@@ -0,0 +1,116 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import { type BBox2DLiteral, type BBox3DLiteral, is2DBBox } from "./bbox.js"
+
+/**
+ * GeoJSON object types.
+ */
+export type GeometryType =
+	| "Point"
+	| "MultiPoint"
+	| "LineString"
+	| "MultiLineString"
+	| "Polygon"
+	| "MultiPolygon"
+	| "GeometryCollection"
+	| "FeatureCollection"
+
+/**
+ * Shadow enum-like record of valid GeoJSON object types.
+ */
+export const GeometryType = {
+	Point: "Point",
+	MultiPoint: "MultiPoint",
+	LineString: "LineString",
+	MultiLineString: "MultiLineString",
+	Polygon: "Polygon",
+	MultiPolygon: "MultiPolygon",
+	GeometryCollection: "GeometryCollection",
+	FeatureCollection: "FeatureCollection",
+} as const satisfies { [K in GeometryType]: K }
+
+/**
+ * The base GeoJSON object.
+ *
+ * The GeoJSON specification also allows foreign members
+ * (https://tools.ietf.org/html/rfc7946#section-6.1) to be included in the object.
+ *
+ * @see {@link https://tools.ietf.org/html/rfc7946#section-3 GeoJSON Object}
+ * @title Geo Object
+ * @public
+ */
+export interface GeoObjectLiteral {
+	/**
+	 * Specifies the type of GeoJSON object.
+	 */
+	type: GeometryType
+
+	/**
+	 * A unique identifier for the feature, such as a UUID, a serial number, or a name.
+	 */
+	id?: string | number | undefined | null
+
+	/**
+	 * A bounding box of the coordinate range of the object's Geometries, Features, or Feature
+	 * Collections.
+	 *
+	 * This is useful when defining the extent of a GeoJSON object, i.e. the minimum and maximum
+	 * coordinates of the object's Geometries, Features, or Feature Collections.
+	 *
+	 * @see {@link https://tools.ietf.org/html/rfc7946#section-5 GeoJSON Bounding Boxes}
+	 */
+	bbox?: BBox2DLiteral | BBox3DLiteral
+
+	/**
+	 * Coordinate reference system for GeoJSON objects.
+	 *
+	 * @see {@link https://tools.ietf.org/html/rfc7946#section-4 Coordinate Reference Systems}
+	 * @title Coordinate Reference System
+	 */
+	crs?: {
+		type: "name"
+
+		properties: {
+			/**
+			 * The name of the coordinate reference system.
+			 *
+			 * @default "EPSG:4326"
+			 */
+			name: string
+		}
+	}
+}
+
+/**
+ * Abstract base-class for all GeoJSON class constructors.
+ */
+export abstract class GeoObject implements GeoObjectLiteral {
+	/**
+	 * The JSON literal type of the GeoJSON object.
+	 */
+	abstract type: GeometryType
+
+	/**
+	 * A bounding box of the coordinate range of the object's Geometries, Features, or Feature.
+	 *
+	 * @see {@linkcode BBox2DLiteral} for 2-dimensional bounding boxes.
+	 * @see {@linkcode BBox3DLiteral} for 3-dimensional bounding boxes.
+	 * @see
+	 */
+	bbox?: BBox2DLiteral | BBox3DLiteral
+
+	protected constructor(bbox?: BBox2DLiteral | BBox3DLiteral) {
+		this.bbox = bbox
+	}
+
+	/**
+	 * Predicate to determine if the GeoJSON object is 2-dimensional.
+	 */
+	public is2D() {
+		return is2DBBox(this.bbox)
+	}
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+	"name": "@mailwoman/spatial",
+	"version": "4.9.0",
+	"description": "Spatial analysis, geocoding, and other geo-related utilities.",
+	"license": "AGPL-3.0",
+	"contributors": [
+		{
+			"name": "Teffen Ellis",
+			"email": "teffen@sister.software"
+		}
+	],
+	"type": "module",
+	"exports": {
+		"./package.json": "./package.json",
+		"./schema/*.json": "./dist/schema/*.json",
+		"./sdk": "./out/sdk/index.js",
+		".": "./out/index.js"
+	},
+	"dependencies": {
+		"@mailwoman/core": "workspace:*",
+		"geo-coordinates-parser": "^1.7.4",
+		"h3-js": "^4.4.0",
+		"wkx": "^0.5.0"
+	},
+	"devDependencies": {
+		"@googlemaps/google-maps-services-js": "^3.4.2",
+		"@types/google.maps": "^3.65.1",
+		"type-fest": "^5.7.0"
+	},
+	"optionalDependencies": {
+		"@googlemaps/google-maps-services-js": "^3.4.2",
+		"@types/google.maps": "^3.65.1"
+	},
+	"engines": {
+		"node": ">=22.5.1"
+	},
+	"keywords": [
+		"geo",
+		"spatial"
+	],
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/position.ts

@@ -0,0 +1,269 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   This file contains types and utilities for working with geographic positions.
+ */
+
+import { type LatLngLiteral } from "@googlemaps/google-maps-services-js"
+import { GeoPoint, type GeoPointInput } from "@mailwoman/spatial"
+
+/**
+ * An ordered pair of coordinates in the form of [longitude, latitude].
+ *
+ * Note that unlike the typical order, GeoJSON coordinates are in the order of [longitude, latitude]
+ * to match the order of [x, y] in Cartesian coordinates.
+ *
+ * @category Position
+ * @category GeoJSON
+ * @see {@linkcode Coordinates3D} for 3D coordinates.
+ */
+export type Coordinates2D = [
+	/**
+	 * The longitude of the point, i.e. the x-coordinate.
+	 *
+	 * @minimum -180
+	 * @maximum 180
+	 */
+	longitude: number,
+	/**
+	 * The latitude of the point, i.e. the y-coordinate.
+	 *
+	 * @minimum -90
+	 * @maximum 90
+	 */
+	latitude: number,
+]
+
+/**
+ * Orders the given coordinates as [longitude, latitude].
+ *
+ * This is useful when converting into GeoJSON format.
+ *
+ * @category GeoJSON
+ * @category Position
+ */
+export function orderCoordPairToGeoJSON([latitude, longitude]: [number, number]): Coordinates2D {
+	return [longitude, latitude]
+}
+
+/**
+ * Orders the given coordinates as [latitude, longitude].
+ *
+ * This is useful when converting into Google Maps format.
+ *
+ * @category GeoJSON
+ * @category Position
+ */
+export function orderGeoJSONToCoordPair([longitude, latitude]: Coordinates2D): [number, number] {
+	return [latitude, longitude]
+}
+
+/**
+ * Given an input which appears to be reversed GeoJSON coordinates (i.e. [latitude, longitude]),
+ * returns the coordinates in the correct order of [longitude, latitude].
+ *
+ * Note that this is a heuristic and is only accurate for North American coordinates.
+ *
+ * @category GeoJSON
+ * @category Position
+ */
+export function inferGeoJSONCoordOrder([coordA, coordB]: [number, number]): Coordinates2D {
+	// Latitude values typically range from -90 to 90
+	const isCoordALat = coordA >= -90 && coordA <= 90
+	const isCoordBLat = coordB >= -90 && coordB <= 90
+
+	if (isCoordALat && !isCoordBLat) {
+		// coordA is latitude, coordB is longitude
+		return [coordB, coordA]
+	}
+
+	if (!isCoordALat && isCoordBLat) {
+		// coordB is latitude, coordA is longitude
+		return [coordA, coordB]
+	}
+
+	// In case both appear to be latitudes (unlikely) or longitudes (out of range for US),
+	// assume coordA is longitude and coordB is latitude as default.
+	return [coordA, coordB]
+}
+
+/**
+ * An ordered triple of coordinates in the form of [longitude, latitude, altitude].
+ *
+ * @category Position
+ * @category GeoJSON
+ * @see {@linkcode Coordinates2D} for 2D coordinates.
+ */
+export type Coordinates3D = [
+	/**
+	 * The longitude of the point, i.e. the x-coordinate.
+	 *
+	 * @minimum -180
+	 * @maximum 180
+	 */
+	longitude: number,
+	/**
+	 * The latitude of the point, i.e. the y-coordinate.
+	 *
+	 * @minimum -90
+	 * @maximum 90
+	 */
+	latitude: number,
+	/**
+	 * The altitude of the point, i.e. the z-coordinate.
+	 */
+	altitude: number,
+]
+
+/**
+ * A record of internal coordinates, typically used by the US Census.
+ */
+export type InternalPointCoordinates = {
+	/**
+	 * Internal Longitude (X) Coordinates
+	 *
+	 * @minimum -180
+	 * @maximum 180
+	 */
+	x: number
+	/**
+	 * Internal Latitude (Y) Coordinates
+	 *
+	 * @minimum -90
+	 * @maximum 90
+	 */
+	y: number
+}
+
+/**
+ * Type-predicate to determine if the given input is a GeoJSON Point geometry.
+ *
+ * @category Type Predicates
+ * @category GeoJSON
+ */
+export function isCoordPairLiteral(input: unknown): input is [number, number] | [number, number, number] {
+	if (!Array.isArray(input)) return false
+
+	if (input.length !== 2 && input.length !== 3) return false
+
+	return input.every((coord) => typeof coord === "number")
+}
+
+/**
+ * Type-predicate to determine if the given input is a {@linkcode LatLngLiteral} object.
+ *
+ * @category Position
+ * @category Type Predicates
+ * @see {@link https://developers.google.com/maps/documentation/javascript/reference/coordinates#LatLngLiteral Google Maps API Documentation}
+ */
+export function isGoogleMapsLatLngLiteral(input: unknown): input is LatLngLiteral {
+	if (!input || typeof input !== "object") return false
+
+	if (!Object.hasOwn(input, "lat") || !Object.hasOwn(input, "lng")) return false
+
+	return true
+}
+
+/**
+ * Type-predicate to determine if the given input is a {@linkcode InternalPointCoordinates} object.
+ *
+ * @category Position
+ * @category Type Predicates
+ */
+export function isInterpolatedCoordinates(input: unknown): input is InternalPointCoordinates {
+	if (!input || typeof input !== "object") return false
+
+	if (!("x" in input)) return false
+	if (!("y" in input)) return false
+
+	return typeof input.x === "number" && typeof input.y === "number"
+}
+
+/**
+ * Given a longitude value, wraps it to the range of [-180, 180].
+ *
+ * This is useful when normalizing longitude values.
+ *
+ * @category Position
+ * @param longitude The longitude value to wrap.
+ */
+export function wrapLongitude(longitude: number): number {
+	return ((((longitude + 180) % 360) + 360) % 360) - 180
+}
+
+/**
+ * Given a latitude value, clamps it to the range of [-90, 90].
+ *
+ * This is useful when normalizing latitude values.
+ *
+ * @category Position
+ * @param value The latitude value to clamp.
+ */
+export function clampLatitude(value: number): number {
+	return Math.min(90, Math.max(-90, value))
+}
+
+/**
+ * Conversion factors for converting between degrees and radians.
+ *
+ * @category Position
+ * @see {@link https://en.wikipedia.org/wiki/Radian Wikipedia: Radian}
+ * @see {@link https://en.wikipedia.org/wiki/Degree_(angle) Wikipedia: Degree (angle)}
+ */
+export const ConversionFactor = {
+	DegreesToRadians: (Math.PI / 180) as unknown as 0.01745329251,
+	RadiansToDegrees: (180 / Math.PI) as unknown as 57.2957795131,
+} as const
+
+/**
+ * Available conversion units for the radius of the Earth.
+ */
+export type EarthRadiusUnit = "km" | "miles" | "meters"
+
+/**
+ * Radius of the Earth in various units
+ */
+const RADII = {
+	km: 6371,
+	miles: 3958.8,
+	meters: 6371000,
+} as const satisfies Record<EarthRadiusUnit, number>
+
+/**
+ * Calculate the distance between two points on the Earth's surface.
+ *
+ * @category Position
+ * @param point1 The first point to calculate the distance from.
+ * @param point2 The second point to calculate the distance to.
+ * @param unit The unit of measurement to return the distance in.
+ *
+ * @returns The distance between the two points in the specified unit.
+ */
+export function haversine(point1: GeoPointInput, point2: GeoPointInput, unit: EarthRadiusUnit = "km"): number {
+	const p1 = GeoPoint.from(point1)
+	const p2 = GeoPoint.from(point2)
+
+	if (!p1 || !p2) return NaN
+
+	const lat1 = p1.latitude
+	const lon1 = p1.longitude
+	const lat2 = p2.latitude
+	const lon2 = p2.longitude
+
+	const dLat = (lat2 - lat1) * ConversionFactor.DegreesToRadians
+
+	const dLon = (lon2 - lon1) * ConversionFactor.DegreesToRadians
+
+	const a =
+		Math.pow(Math.sin(dLat / 2), 2) +
+		Math.cos(lat1 * ConversionFactor.DegreesToRadians) *
+			Math.cos(lat2 * ConversionFactor.DegreesToRadians) *
+			Math.pow(Math.sin(dLon / 2), 2)
+
+	const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a))
+	const radius = RADII[unit]
+
+	return radius * c
+}

package/projection.ts

@@ -0,0 +1,23 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+/**
+ * A coordinate system used to represent the Earth's surface.
+ *
+ * @category Geo
+ */
+export enum CoordinateProjection {
+	/**
+	 * Coordinate system used in Google Earth and GSP systems.
+	 *
+	 * It represents Earth as a three-dimensional ellipsoid.
+	 */
+	WGS84 = "4326",
+	/**
+	 * North American Datum 1983, a geodetic reference system used in the TIGER/Line data.
+	 */
+	NAD83 = "4269",
+}

package/regions/codes.ts

@@ -0,0 +1,43 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import type { RegionName } from "./names.js"
+
+/**
+ * M.49 region codes for continents.
+ */
+export const RegionCodes = [
+	// ---
+	"AF",
+	"AN",
+	"AS",
+	"EU",
+	"NA",
+	"OC",
+	"SA",
+] as const satisfies readonly string[]
+
+/**
+ * M.49 region code for a specific continent.
+ *
+ * @public
+ */
+export type RegionCode = (typeof RegionCodes)[number]
+
+/**
+ * Continent codes to their full names.
+ *
+ * @internal
+ */
+export const RegionCodeToNameRecord = {
+	AF: "Africa",
+	AN: "Antarctica",
+	AS: "Asia",
+	EU: "Europe",
+	NA: "North America",
+	OC: "Oceania",
+	SA: "South America",
+} as const satisfies Record<RegionCode, RegionName>

package/regions/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+export * from "./codes.js"
+export * from "./names.js"

package/regions/names.ts

@@ -0,0 +1,29 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+/**
+ * A list of geographic regions, i.e. continents.
+ *
+ * @category Geographic
+ */
+export const RegionNames = [
+	"Africa",
+	"Antarctica",
+	"Asia",
+	"Europe",
+	"North America",
+	"Oceania",
+	"South America",
+] as const satisfies readonly string[]
+
+/**
+ * A region of the world, i.e. a continent.
+ *
+ * @category Geographic
+ * @title Geographic Region
+ * @public
+ */
+export type RegionName = (typeof RegionNames)[number]

package/sdk/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+export * from "./well-known-text.js"