@aws-amplify/geo 1.2.4 → 1.2.5-geo.18

package/src/types/Geo.ts

@@ -22,6 +22,10 @@ export interface GeoConfig {
 			items: string[];
 			default: string;
 		};
+		geofenceCollections?: {
+			items: string[];
+			default: string;
+		};
 	};
 }
 
@@ -31,10 +35,10 @@ export interface MapStyle {
 	style: string;
 }
 
-export type Latitude = number;
 export type Longitude = number;
+export type Latitude = number;
 
-// Coordinate point
+// Coordinates are a tuple of longitude and latitude
 export type Coordinates = [Longitude, Latitude];
 
 // SW Longitude point for bounding box
@@ -73,6 +77,7 @@ export type SearchByTextOptions =
 	| SearchByTextOptionsWithBiasPosition
 	| SearchByTextOptionsWithSearchAreaConstraints;
 
+// Options object for searchByCoordinates
 export type SearchByCoordinatesOptions = {
 	maxResults?: number;
 	searchIndexName?: string;
@@ -97,6 +102,70 @@ export interface Place {
 	street?: string;
 	subRegion?: string;
 }
+// Array of 4 or more coordinates, where the first and last coordinate are the same to form a closed boundary
+export type LinearRing = Coordinates[];
+
+// An array of one linear ring
+export type GeofencePolygon = LinearRing[];
+
+// Geometry object for Polygon
+export type PolygonGeometry = {
+	polygon: GeofencePolygon;
+};
+
+export type GeofenceId = string;
+
+// Geofence object used as input for saveGeofences
+export type GeofenceInput = {
+	geofenceId: GeofenceId;
+	geometry: PolygonGeometry;
+};
+
+// Options object for saveGeofences
+export type GeofenceOptions = {
+	providerName?: string;
+};
 
-// Return type for searchForSuggestions
-export type SearchForSuggestionsResults = string[];
+// Error type for errors related to Geofence API calls
+export type GeofenceError = {
+	error: {
+		code: string;
+		message: string;
+	};
+	geofenceId: GeofenceId;
+};
+
+// Base geofence object
+type GeofenceBase = {
+	geofenceId: GeofenceId;
+	createTime?: Date;
+	updateTime?: Date;
+};
+
+// Results object for getGeofence
+export type Geofence = GeofenceBase & {
+	geometry: PolygonGeometry;
+};
+
+// Results object for saveGeofences
+export type SaveGeofencesResults = {
+	successes: GeofenceBase[];
+	errors: GeofenceError[];
+};
+
+// Options object for listGeofence
+export type ListGeofenceOptions = GeofenceOptions & {
+	nextToken?: string;
+};
+
+// Results options for listGeofence
+export type ListGeofenceResults = {
+	entries: Geofence[];
+	nextToken: string | undefined;
+};
+
+// Results object for deleteGeofence
+export type DeleteGeofencesResults = {
+	successes: GeofenceId[];
+	errors: GeofenceError[];
+};

package/src/types/Provider.ts

@@ -10,14 +10,20 @@
  * CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions
  * and limitations under the License.
  */
-
 import {
 	SearchByTextOptions,
 	SearchByCoordinatesOptions,
-	SearchForSuggestionsResults,
 	Coordinates,
 	Place,
 	MapStyle,
+	Geofence,
+	GeofenceId,
+	GeofenceInput,
+	GeofenceOptions,
+	ListGeofenceOptions,
+	ListGeofenceResults,
+	SaveGeofencesResults,
+	DeleteGeofencesResults,
 } from './Geo';
 
 export interface GeoProvider {
@@ -36,15 +42,33 @@ export interface GeoProvider {
 	// get the map resource listed as default
 	getDefaultMap(): MapStyle;
 
+	// search by a text string and return a list of places
 	searchByText(text: string, options?: SearchByTextOptions): Promise<Place[]>;
 
+	// search by coordinates and return a matching place
 	searchByCoordinates(
 		coordinates: Coordinates,
 		options?: SearchByCoordinatesOptions
 	): Promise<Place>;
 
-	searchForSuggestions(
-		text: string,
-		options?: SearchByTextOptions
-	): Promise<SearchForSuggestionsResults>;
+	// create geofences
+	saveGeofences(
+		geofences: GeofenceInput[],
+		options?: GeofenceOptions
+	): Promise<SaveGeofencesResults>;
+
+	// get a single geofence
+	getGeofence(
+		geofenceId: GeofenceId,
+		options?: ListGeofenceOptions
+	): Promise<Geofence>;
+
+	// list all geofences
+	listGeofences(options?: ListGeofenceOptions): Promise<ListGeofenceResults>;
+
+	// Delete geofences
+	deleteGeofences(
+		geofenceIds: string[],
+		options?: GeofenceOptions
+	): Promise<DeleteGeofencesResults>;
 }

package/src/util.ts

@@ -0,0 +1,180 @@
+/*
+ * Copyright 2017-2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with
+ * the License. A copy of the License is located at
+ *
+ *     http://aws.amazon.com/apache2.0/
+ *
+ * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+ * CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions
+ * and limitations under the License.
+ */
+import booleanClockwise from '@turf/boolean-clockwise';
+
+import {
+	Longitude,
+	Latitude,
+	GeofenceId,
+	GeofenceInput,
+	GeofencePolygon,
+	LinearRing,
+} from './types';
+
+export function validateCoordinates(lng: Longitude, lat: Latitude): void {
+	if (!Number.isFinite(lng) || !Number.isFinite(lat)) {
+		throw new Error(`Invalid coordinates: [${lng},${lat}]`);
+	}
+	if (lat < -90 || 90 < lat) {
+		throw new Error('Latitude must be between -90 and 90 degrees inclusive.');
+	} else if (lng < -180 || 180 < lng) {
+		throw new Error(
+			'Longitude must be between -180 and 180 degrees inclusive.'
+		);
+	}
+}
+
+export function validateGeofenceId(geofenceId: GeofenceId): void {
+	const geofenceIdRegex = /^[-._\p{L}\p{N}]+$/iu;
+
+	// Check if geofenceId is valid
+	if (!geofenceIdRegex.test(geofenceId)) {
+		throw new Error(
+			`Invalid geofenceId: '${geofenceId}' - IDs can only contain alphanumeric characters, hyphens, underscores and periods.`
+		);
+	}
+}
+
+export function validateLinearRing(
+	linearRing: LinearRing,
+	geofenceId?: GeofenceId
+): void {
+	const errorPrefix = geofenceId ? `${geofenceId}: ` : '';
+	// Validate LinearRing size, must be at least 4 points
+	if (linearRing.length < 4) {
+		throw new Error(
+			`${errorPrefix}LinearRing must contain 4 or more coordinates.`
+		);
+	}
+
+	// Validate all coordinates are valid, error with which ones are bad
+	const badCoordinates = [];
+	linearRing.forEach(coordinates => {
+		try {
+			validateCoordinates(coordinates[0], coordinates[1]);
+		} catch (error) {
+			badCoordinates.push({ coordinates, error: error.message });
+		}
+	});
+	if (badCoordinates.length > 0) {
+		throw new Error(
+			`${errorPrefix}One or more of the coordinates in the Polygon LinearRing are not valid: ${JSON.stringify(
+				badCoordinates
+			)}`
+		);
+	}
+
+	// Validate first and last coordinates are the same
+	const [lngA, latA] = linearRing[0];
+	const [lngB, latB] = linearRing[linearRing.length - 1];
+
+	if (lngA !== lngB || latA !== latB) {
+		throw new Error(
+			`${errorPrefix}LinearRing's first and last coordinates are not the same`
+		);
+	}
+
+	if (booleanClockwise(linearRing)) {
+		throw new Error(
+			`${errorPrefix}LinearRing coordinates must be wound counterclockwise`
+		);
+	}
+}
+
+export function validatePolygon(
+	polygon: GeofencePolygon,
+	geofenceId?: GeofenceId
+): void {
+	const errorPrefix = geofenceId ? `${geofenceId}: ` : '';
+	if (!Array.isArray(polygon)) {
+		throw new Error(
+			`${errorPrefix}Polygon is of incorrect structure. It should be an array of LinearRings`
+		);
+	}
+	if (polygon.length < 1) {
+		throw new Error(
+			`${errorPrefix}Polygon must have a single LinearRing array.`
+		);
+	}
+
+	if (polygon.length > 1) {
+		throw new Error(
+			`${errorPrefix}Polygon must have a single LinearRing array. Note: We do not currently support polygons with holes, multipolygons, polygons that are wound clockwise, or that cross the antimeridian.`
+		);
+	}
+	const verticesCount = polygon.reduce(
+		(prev, linearRing) => prev + linearRing.length,
+		0
+	);
+	if (verticesCount > 1000) {
+		throw new Error(
+			`${errorPrefix}Polygon has more than the maximum 1000 vertices.`
+		);
+	}
+	polygon.forEach(linearRing => {
+		validateLinearRing(linearRing, geofenceId);
+	});
+}
+
+export function validateGeofencesInput(geofences: GeofenceInput[]) {
+	const geofenceIds = {};
+
+	geofences.forEach((geofence: GeofenceInput) => {
+		// verify all required properties are present
+
+		// Validate geofenceId exists
+		if (!geofence.geofenceId) {
+			throw new Error(`Geofence '${geofence}' is missing geofenceId`);
+		}
+		const { geofenceId } = geofence;
+		validateGeofenceId(geofenceId);
+
+		// Validate geofenceId is unique
+		if (geofenceIds[geofenceId]) {
+			throw new Error(`Duplicate geofenceId: ${geofenceId}`);
+		} else {
+			geofenceIds[geofenceId] = true;
+		}
+
+		// Validate geometry exists
+		if (!geofence.geometry) {
+			throw new Error(`Geofence '${geofenceId}' is missing geometry`);
+		}
+		const { geometry } = geofence;
+
+		// Validate polygon exists
+		if (!geometry.polygon) {
+			throw new Error(`Geofence '${geofenceId}' is missing geometry.polygon`);
+		}
+		const { polygon } = geometry;
+
+		// Validate polygon length and structure
+		try {
+			validatePolygon(polygon, geofenceId);
+		} catch (error) {
+			if (
+				error.message.includes(
+					'Polygon has more than the maximum 1000 vertices.'
+				)
+			) {
+				throw new Error(
+					`Geofence '${geofenceId}' has more than the maximum of 1000 vertices`
+				);
+			}
+		}
+
+		// Validate LinearRing length, structure, and coordinates
+		const [linearRing] = polygon;
+		validateLinearRing(linearRing, geofenceId);
+	});
+}