@mailwoman/spatial 4.9.0

package/geometries/point.ts

@@ -0,0 +1,419 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import type google from "@googlemaps/google-maps-services-js"
+import type { LatLng, LatLngLiteral } from "@googlemaps/google-maps-services-js"
+import { tryParsingJSON } from "@mailwoman/core/objects"
+import { convert as convertCoords } from "geo-coordinates-parser"
+import { latLngToCell } from "h3-js"
+import { type BBox2DLiteral, type BBox3DLiteral, GeoBoundingBox, isBBox } from "../bbox.js"
+import { type H3Cell, shortenH3Cell } from "../h3/index.js"
+import { type GeoObjectLiteral, GeometryType } from "../objects.js"
+import {
+	type InternalPointCoordinates,
+	type Coordinates2D as Point2DCoordinates,
+	type Coordinates3D as Point3DCoordinates,
+	clampLatitude,
+	inferGeoJSONCoordOrder,
+	isCoordPairLiteral,
+	isGoogleMapsLatLngLiteral,
+	isInterpolatedCoordinates,
+	wrapLongitude,
+} from "../position.js"
+
+/**
+ * A JSON-serializeable single point geometry, such as a specific location, address, or longitude,
+ * latitude pair.
+ *
+ * ```js
+ * {
+ * 	"type": "Point",
+ * 	"coordinates": [100, 0]
+ * }
+ * ```
+ *
+ * @title Point Geometry
+ * @public
+ */
+export interface PointLiteral extends GeoObjectLiteral {
+	/**
+	 * Declares the type of GeoJSON object as a `Point` geometry.
+	 */
+	type: "Point"
+	/**
+	 * A pair of coordinates in the form of [longitude, latitude].
+	 *
+	 * @see {@linkcode Point2DCoordinates} for more information.
+	 */
+	coordinates: Point2DCoordinates | Point3DCoordinates
+}
+
+/**
+ * Type-predicate to determine if the given input is a GeoJSON Point geometry.
+ */
+export function isPointLiteral(input: PointLiteral | null | undefined | unknown): input is PointLiteral {
+	if (!input || typeof input !== "object") return false
+
+	if (!("type" in input)) return false
+	if (!("coordinates" in input)) return false
+	if (input.type !== GeometryType.Point) return false
+
+	return isCoordPairLiteral(input.coordinates)
+}
+
+/**
+ * Common interface for Browser Geolocation API coordinates.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GeolocationCoordinates MDN Web Docs}
+ */
+export interface GeolocationCoordinatesLike {
+	latitude: number
+	longitude: number
+	altitude: number
+}
+
+/**
+ * Type-predicate to determine if the given input appears to be a {@linkcode GeolocationCoordinates}
+ * object.
+ */
+export function isGeolocationCoordinatesLike(input: unknown): input is GeolocationCoordinatesLike {
+	if (!input || typeof input !== "object") return false
+
+	if (!("latitude" in input)) return false
+	if (!("longitude" in input)) return false
+	if (!("altitude" in input)) return false
+
+	return true
+}
+
+export type GeoPointInput =
+	| PointLiteral
+	| Point2DCoordinates
+	| Point3DCoordinates
+	| GeolocationCoordinatesLike
+	| InternalPointCoordinates
+	| LatLngLiteral
+	| LatLng
+
+//#region GeoPoint
+
+/**
+ * A single point geometry, such as a specific location, address, or longitude, latitude pair.
+ */
+export class GeoPoint implements PointLiteral {
+	//#region Properties
+
+	/**
+	 * Declares the type of GeoJSON object as a `Point` geometry.
+	 */
+	readonly type = GeometryType.Point
+
+	/**
+	 * The bounding box literal of the GeoPoint.
+	 *
+	 * @see {@linkcode GeoPoint.bbox} for the actual bounding box object.
+	 * @see {@linkcode GeoBoundingBox} for creating a bounding box.
+	 */
+	public boundingBox: GeoBoundingBox | null = null
+
+	/**
+	 * The bounding box literal of the GeoPoint.
+	 *
+	 * @see {@linkcode BBox2DLiteral} for 2D bounding boxes.
+	 * @see {@linkcode BBox3DLiteral} for 3D bounding boxes.
+	 * @see {@linkcode GeoBoundingBox} for creating a bounding box.
+	 */
+	public get bbox(): BBox2DLiteral | BBox3DLiteral | undefined {
+		return this.boundingBox?.toJSON()
+	}
+
+	public set bbox(bbox: BBox2DLiteral | BBox3DLiteral | undefined) {
+		this.boundingBox = bbox ? new GeoBoundingBox(bbox) : null
+	}
+
+	public get coordinates(): Point2DCoordinates | Point3DCoordinates {
+		if (this.is3D()) {
+			return [this.#longitude, this.#latitude, this.#altitude]
+		}
+
+		return [this.#longitude, this.#latitude]
+	}
+
+	public set coordinates(coords: Point2DCoordinates | Point3DCoordinates) {
+		const [longitude, latitude, altitude] = coords
+
+		this.#longitude = longitude
+		this.#latitude = latitude
+		this.#altitude = typeof altitude === "number" ? altitude : 0
+	}
+
+	#latitude: number = 0
+	#longitude: number = 0
+	#altitude: number = 0
+
+	/**
+	 * The longitude of the point in degrees, i.e. the x-coordinate.
+	 *
+	 * Values outside the range will be wrapped around to the opposite side of the globe.
+	 *
+	 * @minimum -180
+	 * @maximum 180
+	 */
+	public get longitude(): number {
+		return this.#longitude
+	}
+
+	public set longitude(value: number) {
+		this.#longitude = wrapLongitude(value)
+	}
+
+	/**
+	 * The latitude of the point in degrees, i.e. the y-coordinate.
+	 *
+	 * Values outside the range will be clamped to the poles.
+	 *
+	 * @minimum -90
+	 * @maximum 90
+	 */
+	public get latitude(): number {
+		return this.#latitude
+	}
+
+	public set latitude(value: number) {
+		this.#latitude = clampLatitude(value)
+	}
+
+	/**
+	 * The altitude of the point, i.e. the z-coordinate.
+	 *
+	 * This is optional and is typically measured in meters.
+	 */
+	public get altitude(): number {
+		return this.#altitude
+	}
+
+	public set altitude(value: number) {
+		this.#altitude = value
+	}
+
+	//#endregion
+
+	//#region Constructors
+
+	/**
+	 * Create a new GeoPoint object with default coordinates.
+	 */
+	constructor()
+	/**
+	 * Create a new GeoPoint instance from another {@linkcode GeoJSONPosition} coordinates.
+	 */
+	constructor(
+		geoJSONPosition: Point2DCoordinates | Point3DCoordinates,
+		bbox?: BBox2DLiteral | BBox3DLiteral | GeoBoundingBox
+	)
+
+	/**
+	 * Create a new GeoPoint instance from the browser's Geolocation API coordinates.
+	 *
+	 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GeolocationCoordinates MDN Web Docs}
+	 */
+	constructor(geoLocationCoordinates: GeolocationCoordinatesLike, bbox?: BBox2DLiteral | BBox3DLiteral | GeoBoundingBox)
+
+	/**
+	 * Creates a new GeoPoint instance from a Google Maps API
+	 * {@linkcode google.LatLngLiteral | LatLngLiteral} object.
+	 */
+	constructor(latLngLiteral: google.LatLngLiteral, bbox?: BBox2DLiteral | BBox3DLiteral | GeoBoundingBox)
+
+	/**
+	 * Creates a new GeoPoint instance from internal coordinates.
+	 */
+	constructor(interpolatedCoords: InternalPointCoordinates, bbox?: BBox2DLiteral | BBox3DLiteral | GeoBoundingBox)
+	/**
+	 * Creates a new GeoPoint instance from a Google Maps API {@linkcode google.LatLng | LatLng}
+	 * object.
+	 */
+	constructor(latLng: LatLngLiteral, bbox?: BBox2DLiteral | BBox3DLiteral | GeoBoundingBox)
+	/**
+	 * Create a new GeoPoint instance from another {@linkcode PointLiteral}.
+	 */
+	constructor(geoPointJSON: PointLiteral, bbox?: BBox2DLiteral | BBox3DLiteral | GeoBoundingBox)
+
+	/**
+	 * Create a new GeoPoint instance.
+	 */
+	constructor(input: GeoPointInput, bbox?: BBox2DLiteral | BBox3DLiteral | GeoBoundingBox)
+	constructor(input?: GeoPointInput, bbox?: BBox2DLiteral | BBox3DLiteral | GeoBoundingBox) {
+		if (isCoordPairLiteral(input)) {
+			if (input.length === 2) {
+				this.coordinates = inferGeoJSONCoordOrder(input)
+			} else {
+				this.coordinates = input
+			}
+		} else if (isPointLiteral(input)) {
+			this.coordinates = [...input.coordinates]
+
+			if (isBBox(input.bbox)) {
+				this.bbox = [...input.bbox]
+			}
+		} else if (isGoogleMapsLatLngLiteral(input)) {
+			this.coordinates = [input.lng, input.lat]
+		} else if (isGeolocationCoordinatesLike(input)) {
+			this.#longitude = input.longitude
+			this.#latitude = input.latitude
+			this.#altitude = input.altitude || 0
+		} else if (isInterpolatedCoordinates(input)) {
+			this.#longitude = input.x
+			this.#latitude = input.y
+			this.#altitude = 0
+		} else {
+			this.coordinates = [0, 0]
+		}
+
+		if (isBBox(bbox)) {
+			this.bbox = bbox
+		}
+	}
+
+	/**
+	 * Attempts to create a new GeoPoint instance from the given input.
+	 */
+	static from(input: unknown): GeoPoint | null {
+		if (!input) return null
+		if (input instanceof GeoPoint) return input
+
+		if (typeof input === "string") {
+			const coordinates = tryParsingJSON<GeoPointInput>(input) || tryParsingJSON<GeoPointInput>(`[${input}]`)
+
+			if (coordinates) {
+				input = coordinates
+			}
+		}
+
+		try {
+			const point = new GeoPoint(input as GeoPointInput)
+			if (point.isNullIsland()) return null
+
+			return point
+		} catch (_error) {
+			return null
+		}
+	}
+
+	//#endregion
+
+	//#region Predicates
+
+	/**
+	 * Whether the GeoPoint is 2-dimensional.
+	 */
+	public is2D() {
+		return !this.is3D()
+	}
+
+	/**
+	 * Whether the GeoPoint is 3-dimensional.
+	 */
+	public is3D() {
+		return this.#altitude !== 0
+	}
+
+	/**
+	 * Whether the GeoPoint is the null island at 0, 0.
+	 */
+	public isNullIsland(): boolean {
+		return this.#latitude === 0 && this.#longitude === 0
+	}
+
+	//#endregion
+
+	//#region Conversion
+
+	public toJSON(): PointLiteral {
+		return {
+			type: this.type,
+			coordinates: this.coordinates,
+		}
+	}
+
+	public to2DCoordinates(): Point2DCoordinates {
+		return [this.#longitude, this.#latitude]
+	}
+
+	public to3DCoordinates(): Point3DCoordinates {
+		return [this.#longitude, this.#latitude, this.#altitude]
+	}
+
+	/**
+	 * Converts the GeoPoint to a Google Maps API {@linkcode google.LatLngLiteral | LatLngLiteral}
+	 * object.
+	 */
+	public toGoogleLatLngLiteral(): google.LatLngLiteral {
+		return {
+			lat: this.#latitude,
+			lng: this.#longitude,
+		}
+	}
+
+	/**
+	 * Converts the GeoPoint to DMS (Degrees, Minutes, Seconds) format.
+	 */
+	public toDMS(): string {
+		const converter = convertCoords(`${this.#latitude},${this.#longitude}`)
+
+		return converter.toCoordinateFormat("DMS")
+	}
+
+	/**
+	 * Converts the GeoPoint to a H3 short cell address.
+	 */
+	public toH3Cell(resolution = 15) {
+		const cell = latLngToCell(this.#latitude, this.#longitude, resolution) as H3Cell
+
+		return cell
+	}
+
+	/**
+	 * Converts the GeoPoint to a H3 short cell address.
+	 */
+	public toH3ShortCell(resolution = 15) {
+		const cell = this.toH3Cell(resolution)
+
+		return shortenH3Cell(cell)
+	}
+
+	public toString(): string {
+		return JSON.stringify(this.toJSON())
+	}
+	//#endregion
+
+	public [Symbol.iterator](): Iterator<number> {
+		return this.coordinates[Symbol.iterator]()
+	}
+}
+
+/**
+ * An array of positions for each point in the geometry.
+ *
+ * @see {@linkcode GeoJSONPosition} for more information.
+ */
+export type MultiPointPath = [...points: Array<Point2DCoordinates | Point3DCoordinates>]
+
+/**
+ * A collection of points, such as a constellation or a set of locations.
+ */
+export interface MultiPointLiteral extends GeoObjectLiteral {
+	/**
+	 * Declares the type of GeoJSON object as a `MultiPoint` geometry.
+	 */
+	type: "MultiPoint"
+	/**
+	 * An array of positions for each point in the geometry.
+	 *
+	 * @see {@linkcode GeoJSONPosition} for more information.
+	 */
+	coordinates: MultiPointPath
+}

package/geometries/polygon.ts

@@ -0,0 +1,237 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import { ResourceError } from "@mailwoman/core/errors"
+import type { GeoObjectLiteral } from "../objects.js"
+import type { LineStringPath } from "./line-string.js"
+
+/**
+ * An array of positions forming a closed shape, such as a country or a lake.
+ *
+ * @example
+ *
+ * A polygon without holes:
+ *
+ * ```json
+ * {
+ * 	"type": "Polygon",
+ * 	"coordinates": [
+ * 		[
+ * 			[100, 0],
+ * 			[101, 0],
+ * 			[101, 1],
+ * 			[100, 1],
+ * 			[100, 0]
+ * 		]
+ * 	]
+ * }
+ * ```
+ */
+export type SolidPolygonPath = [
+	/**
+	 * - A linear ring is a closed LineString with four or more positions.
+	 * - The first and last positions are equivalent (they represent equivalent points).
+	 */
+	exteriorRing: LineStringPath,
+]
+
+/**
+ * An array of positions forming a closed shape with holes, such as a country with islands or a lake
+ * with islands.
+ *
+ * @example
+ *
+ * A polygon with holes:
+ *
+ * ```json
+ * {
+ * 	"type": "Polygon",
+ * 	"coordinates": [
+ * 		[
+ * 			[100.0, 0.0],
+ * 			[101.0, 0.0],
+ * 			[101.0, 1.0],
+ * 			[100.0, 1.0],
+ * 			[100.0, 0.0]
+ * 		],
+ * 		[
+ * 			[100.8, 0.8],
+ * 			[100.8, 0.2],
+ * 			[100.2, 0.2],
+ * 			[100.2, 0.8],
+ * 			[100.8, 0.8]
+ * 		]
+ * 	]
+ * }
+ * ```
+ */
+export type NestedPolygonPath = [
+	/**
+	 * - A linear ring is a closed LineString with four or more positions.
+	 * - The first and last positions are equivalent (they represent equivalent points).
+	 */
+	exteriorRing: LineStringPath,
+	/**
+	 * - The interior rings are arrays of positions forming holes in the polygon.
+	 */
+	...interiorRings: LineStringPath[],
+]
+
+/**
+ * A polygon geometry.
+ *
+ * @see {@linkcode PolygonLiteral} for applicable JSON schema.
+ * @see {@linkcode SolidPolygonPath} for more information.
+ * @see {@linkcode NestedPolygonPath} for more information.
+ */
+export type PolygonPath = SolidPolygonPath | NestedPolygonPath
+
+/**
+ * An array of positions forming a closed shape, such as a country or a lake.
+ */
+export interface PolygonLiteral<P extends PolygonPath = SolidPolygonPath> extends GeoObjectLiteral {
+	/**
+	 * Declares the type of GeoJSON object as a `Polygon` geometry.
+	 */
+	type: "Polygon"
+	/**
+	 * An array of positions for each point in the geometry.
+	 *
+	 * @see {@link https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6 | RFC 7946 Section 3.1.6}
+	 * @see {@linkcode SolidPolygonPath}
+	 * @see {@linkcode NestedPolygonPath}
+	 */
+	coordinates: P
+}
+
+/**
+ * Predicate for checking if a GeoJSON object is a `Polygon` geometry.
+ */
+export function isPolygonLiteral<P extends PolygonPath = PolygonPath>(input: unknown): input is PolygonLiteral<P> {
+	if (typeof input !== "object" || input === null) return false
+
+	return "type" in input && input.type === "Polygon" && "coordinates" in input && Array.isArray(input.coordinates)
+}
+
+/**
+ * Predicate for checking if a polygon geometry is a solid, i.e. it has no holes.
+ */
+export function isSolidPolygonPath(input: PolygonLiteral): boolean {
+	return input.coordinates.length === 1
+}
+
+/**
+ * A collection of polygons, such as a country with islands or a lake with islands.
+ */
+export interface MultiPolygonLiteral<P extends PolygonPath = SolidPolygonPath> extends GeoObjectLiteral {
+	type: "MultiPolygon"
+
+	/**
+	 * An array of polygons.
+	 */
+	coordinates: P[][]
+}
+/**
+ * Predicate for checking if a GeoJSON object is a `MultiPolygon` geometry.
+ */
+
+/**
+ * Given a polygon geometry, return an OSM filter string.
+ *
+ * This is useful when working with the Overpass API.
+ */
+export function polygonToOSMFilter(input: PolygonLiteral): string {
+	if (!isPolygonLiteral(input)) return ""
+
+	const [exteriorRing] = input.coordinates
+
+	const filter = exteriorRing.map(([lon, lat]) => `${lat} ${lon}`).join(" ")
+
+	return `poly:'${filter}'`
+}
+
+/**
+ * Tags returned by the Overpass API for a node.
+ *
+ * @category OSM
+ */
+export enum OSMNodeTag {
+	HouseNumber = "addr:housenumber",
+	PostCode = "addr:postcode",
+	Street = "addr:street",
+	State = "addr:state",
+	City = "addr:city",
+	Website = "website",
+	Email = "email",
+	Phone = "phone",
+	Shop = "shop",
+	Brand = "brand",
+	Cuisine = "cuisine",
+	Name = "name",
+	Healthcare = "healthcare",
+	Office = "office",
+	Amenity = "amenity",
+}
+
+export const ForbiddenResidentialOSMNodeTags: ReadonlySet<OSMNodeTag> = new Set<OSMNodeTag>([
+	OSMNodeTag.Shop,
+	OSMNodeTag.Brand,
+	OSMNodeTag.Cuisine,
+	OSMNodeTag.Office,
+	OSMNodeTag.Healthcare,
+])
+
+export type OSMNodeTagRecord = Record<OSMNodeTag, string | undefined>
+
+export interface OSMOverpassElement {
+	type: "node"
+	id: number
+	lat: number
+	lon: number
+	tags: OSMNodeTagRecord
+}
+
+export interface OSMOverpassResponseBody {
+	version: string
+	generator: string
+	osm3s: {
+		timestamp_osm_base: string
+		copyright: string
+	}
+	elements: OSMOverpassElement[]
+}
+
+/**
+ * Given an OSM element, attempts to infer if the result is a residential address.
+ */
+export function isResidentialElement(element: OSMOverpassElement): boolean {
+	for (const key in element.tags) {
+		if (ForbiddenResidentialOSMNodeTags.has(key as OSMNodeTag)) return false
+	}
+
+	if (element.tags[OSMNodeTag.Amenity] === "restaurant") return false
+
+	return true
+}
+
+export function fetchOSMElementViaOverpassAPI(input: PolygonLiteral): Promise<OSMOverpassElement[]> {
+	const filter = polygonToOSMFilter(input)
+
+	const url = new URL("http://overpass-api.de/api/interpreter")
+	url.searchParams.set("data", `[out:json];(node['addr:housenumber'](${filter}););out body;>;out skel qt;`)
+
+	return fetch(url)
+		.then((response) => {
+			if (!response.ok) throw ResourceError.from(response.status, response.statusText, "osm", "overpass-api", "fetch")
+
+			return response
+		})
+		.then((response) => response.json() as Promise<OSMOverpassResponseBody>)
+		.then((body) => body.elements)
+		.catch((error) => {
+			throw ResourceError.wrap(error, "osm", "overpass-api", "fetch")
+		})
+}

package/google/index.ts

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

package/google/place-id.ts

@@ -0,0 +1,44 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Google Place ID utilities.
+ */
+
+import type { Tagged } from "type-fest"
+
+/**
+ * A Place ID uniquely identifies a place in the Google Places database and on Google Maps.
+ *
+ * The length of the identifier may vary. Generally, the identifier is a 27-character string,
+ * however, more specific places may have longer identifiers.
+ *
+ * Place IDs appear to be base64-encoded strings, delimited by underscores and dashes.
+ *
+ * Note that Place IDs do change. Consider a them stale after a few days.
+ *
+ * @category Google
+ * @category Geocoding
+ * @type {string}
+ * @minLength 1
+ * @pattern ^[A-Za-z0-9_-]+$
+ * @title Google Place ID
+ */
+export type GooglePlaceID = Tagged<string, "GooglePlaceID">
+
+/**
+ * Pattern for validating a Google Place ID.
+ */
+export const GOOGLE_PLACE_ID_PATTERN = /^[A-Za-z0-9_-]+$/
+
+/**
+ * Type-predicate for checking if a value appears to be a valid Google Place ID.
+ *
+ * @category Google
+ * @category Geocoding
+ * @internal
+ */
+export function isGooglePlaceID(input: string): input is GooglePlaceID {
+	return GOOGLE_PLACE_ID_PATTERN.test(input.toString())
+}