🤖 Merge PR #47621 [@types/unl-core] Update types for unl-core to v2.1.x by @jake-unl

* [@types/unl-core] Update types for unl-core to v2.1.x

* fix: repair some interfaces

types/unl-core/index.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for unl-core 2.0
+// Type definitions for unl-core 2.1
 // Project: https://github.com/u-n-l/core-js
 // Definitions by: UNL Network B.V. <https://github.com/u-n-l>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
@@ -51,6 +51,18 @@ export interface LocationIdWithElevation {
     elevationType: ElevationType;
 }
 
+export interface Address {
+    geohash: string;
+    words: string;
+    coordinates: PointWithElevation;
+    bounds: BoundsWithElevation;
+}
+
+export interface Polyhash {
+    precision: number;
+    data: string[];
+}
+
 /**
  * Encodes latitude/longitude coordinates to locationId, either to specified precision or
  * to default precision. Elevation information can be optionally specified in options parameter.
@@ -143,8 +155,86 @@ export function appendElevation(
  * SW/NE latitude/longitude bounds and precision. Each line is represented by an array of two
  * coordinates in the format: [[startLon, startLat], [endLon, endLat]].
  *
- * @param   bounds - The bound whithin to return the grid lines.
+ * @param   bounds - The bound within to return the grid lines.
  * @param   [precision] - Number of characters to consider for the locationId of a grid cell. Default value is 9.
  * @returns grid lines
  */
 export function gridLines(bounds: Bounds, precision?: number): Array<[[number, number], [number, number]]>;
+
+/**
+ * Returns the human-readable address of a given location (either coordinates or UNL cell id)
+ *
+ * @param location - the location (Id or lat-lon coordinates) of the point for which you would like the address
+ * @param apiKey - Your UNL API key used to access the location APIs
+ * @param langCode - 2 letter language code of response (default: en)
+ * @param count - the number of words in the returned address (only valid for coordinate calls)
+ */
+export function toWords(location: string, apiKey: string, langCode: string, count: number): Address;
+
+/**
+ * Returns the coordinates of a given address
+ *
+ * @param words - the words representing the point for which you would like the coordinates
+ * @param apiKey - Your UNL API key used to access the location APIs
+ * @param langCode - 2 letter language code of response (default: en)
+ */
+export function fromWords(words: string, apiKey: string, langCode: string): Address;
+
+// Polyhash
+
+/**
+ * Converts an array of points into a Polyhash, locationId-polygon
+ *
+ * @param points - An array of latitude longitude coordinates, making up a polygon
+ * @param locationIdPrecision - The precision of the output locationId polygon (Polyhash)
+ * @param shouldDeflate - if false, returned Polyhash will have full-length, inflated locationIds (default: false)
+ */
+export function toPolyhash(points: number[][], locationIdPrecision: number): Polyhash[];
+
+/**
+ * Returns an array of coordinates, the polygon represented by the given Polyhash
+ *
+ * @param polyhash - The Polyhash object to be turned back into coordinates
+ */
+export function toCoordinates(polyhash: string[]): number[][];
+
+/**
+ * Compress the given Polyhash object
+ *
+ * @param polyhash - The Polyhash object to be compressed
+ */
+export function compressPolyhash(polyhash: Polyhash[]): string;
+
+/**
+ * Return the Polyhash object represented by the compressed signature
+ *
+ * @param compressedPolyhash
+ */
+export function decompressPolyhash(compressedPolyhash: string): string[];
+
+/**
+ * Convert the given polygon into a cluster of locationIds
+ *
+ * @param points
+ * @param locationIdPrecision
+ */
+export function toCluster(points: number[][], locationIdPrecision: number): Polyhash[];
+
+/**
+ * Convert a list of deflated locationIds into its full-length equivalent
+ * @param deflatedList
+ */
+export function inflate(deflatedList: Polyhash[]): string[];
+
+/**
+ * Return a deflated list of locationIds
+ *
+ * @param locationIds
+ */
+export function deflate(locationIds: string[]): Polyhash[];
+
+/**
+ * Convert locationId array into Polyhash, removes the common prefix and group them by precision
+ * @param locationIds
+ */
+export function groupByPrefix(locationIds: string[]): string[][];

types/unl-core/unl-core-tests.ts

@@ -1,21 +1,100 @@
-import * as LocationId from 'unl-core';
+import * as UnlCore from 'unl-core';
 
 // Encoding
-const atx_locationId: string = LocationId.encode(30.2672, -97.7431);
-const atx_locationId_p3: string = LocationId.encode(30.2672, -97.7431, 3);
+const atx_locationId: string = UnlCore.encode(30.2672, -97.7431);
+const atx_locationId_p3: string = UnlCore.encode(30.2672, -97.7431, 3);
 
 // Decoding
-const atx_latlong: LocationId.PointWithElevation = LocationId.decode(atx_locationId);
+const atx_latlong: UnlCore.PointWithElevation = UnlCore.decode(atx_locationId);
 
 // Bounds
-const atx_bounds: LocationId.BoundsWithElevation = LocationId.bounds(atx_locationId);
+const atx_bounds: UnlCore.BoundsWithElevation = UnlCore.bounds(atx_locationId);
 
 // Adjacent
-const atx_adj_cell1: string = LocationId.adjacent(atx_locationId, 'N');
+const atx_adj_cell1: string = UnlCore.adjacent(atx_locationId, 'N');
 
 // Neighbors
-const atx_neighbors: LocationId.Neighbours = LocationId.neighbours(atx_locationId);
+const atx_neighbors: UnlCore.Neighbours = UnlCore.neighbours(atx_locationId);
 const atx_adj_cell3: string = atx_neighbors.n;
 
 // Grid Lines
-const atx_gridLines: Array<[[number, number], [number, number]]> = LocationId.gridLines(atx_bounds);
+const atx_gridLines: Array<[[number, number], [number, number]]> = UnlCore.gridLines(atx_bounds);
+
+// Polyhash
+
+// Sample polygon
+const grachtenGordel = [
+    [52.3860252, 4.882822],
+    [52.3721408, 4.8751831],
+    [52.3628122, 4.8804188],
+    [52.3578851, 4.8902035],
+    [52.3596149, 4.9085712],
+    [52.3625501, 4.9202442],
+    [52.3665334, 4.9275398],
+    [52.3716691, 4.9126911],
+    [52.3758612, 4.9129486],
+    [52.3776427, 4.9120903],
+    [52.3860252, 4.882822],
+];
+
+/**
+ * [{
+ *     precision: 7,
+ *     data: [
+ *        'u176p0e', '3yyj',
+ *        'zh3',    '72',
+ *        'ey',    'uq',
+ *        '9bjh',    '3zvc',
+ *        'y9',    'z0',
+ *        '6p0e'
+ *     ]
+ * }]
+ */
+const polyGordel: UnlCore.Polyhash[] = UnlCore.toPolyhash(grachtenGordel, 7);
+
+// u0COMqBaDeexPoRh4hvxrYSUjgDfbrPUn4AyoFo=
+let compressed: string = UnlCore.compressPolyhash(polyGordel);
+
+/**
+ * [
+ *    'u176p0e', 'u173yyj',
+ *    'u173zh3', 'u173z72',
+ *    'u173zey', 'u173zuq',
+ *    'u179bjh', 'u173zvc',
+ *    'u173zy9', 'u173zz0',
+ *    'u176p0e'
+ * ]
+ */
+const decompressed: string[] = UnlCore.decompressPolyhash(compressed);
+
+// == grachtenGordel
+const coords: number[][] = UnlCore.toCoordinates(decompressed);
+
+/**
+ * [
+ *     { precision: 6, data: [ 'u173zk', 'm', 'q', 's', 't', 'w' ] },
+ *     { precision: 7, data: [ 'yvp', 'w', 'x', 'y', 'z', 'yj','n', 'p', 'q', 'r', ... ] }
+ * ]
+ */
+const clusterGordel: UnlCore.Polyhash[] = UnlCore.toCluster(grachtenGordel, 7);
+
+/**
+ * s0COG/kzbOHLy7zerx6+fnsWjVs3ePX58Xx6+fh4 ...
+ */
+compressed = UnlCore.compressPolyhash(clusterGordel);
+
+/**
+ * [ 'u173zk',  'u173zm',  'u173zq',  ... ]
+ */
+const inflated: string[] = UnlCore.inflate(clusterGordel);
+
+/**
+ * [
+ *    [ 'u173zk', 'm', 'q', 's', 't', 'w' ],
+ *    [ 'u173yvp', 'w',  'x',  'y', 'z', 'yj', ... ]
+ * ]
+ */
+const grouped: string[][] = UnlCore.groupByPrefix(inflated);
+
+// == clusterGordel
+const deflated: UnlCore.Polyhash[] = UnlCore.deflate(inflated);