Merge pull request #153 from nrabinowitz/typescript-libdef

Add Typescript typechecking, generate types with tsc
uber · Aug 22, 2022 · ece84ef · ece84ef
2 parents 7eeeb99 + 2593335
commit ece84ef
Show file tree

Hide file tree

Showing 11 changed files with 213 additions and 109 deletions.
diff --git a/README.md b/README.md
@@ -98,8 +98,8 @@ const coordinates = h3.cellsToMultiPolygon(hexagons, true);
 ## h3
 
 * [h3](#module_h3)
-    * [.UNITS](#module_h3.UNITS) : <code>Object</code>
-    * [.h3IndexToSplitLong(h3Index)](#module_h3.h3IndexToSplitLong) ⇒ <code>Array.&lt;number&gt;</code>
+    * [.UNITS](#module_h3.UNITS)
+    * [.h3IndexToSplitLong(h3Index)](#module_h3.h3IndexToSplitLong) ⇒ <code>SplitLong</code>
     * [.splitLongToH3Index(lower, upper)](#module_h3.splitLongToH3Index) ⇒ <code>H3Index</code>
     * [.isValidCell(h3Index)](#module_h3.isValidCell) ⇒ <code>boolean</code>
     * [.isPentagon(h3Index)](#module_h3.isPentagon) ⇒ <code>boolean</code>
@@ -108,16 +108,16 @@ const coordinates = h3.cellsToMultiPolygon(hexagons, true);
     * [.getIcosahedronFaces(h3Index)](#module_h3.getIcosahedronFaces) ⇒ <code>Array.&lt;number&gt;</code>
     * [.getResolution(h3Index)](#module_h3.getResolution) ⇒ <code>number</code>
     * [.latLngToCell(lat, lng, res)](#module_h3.latLngToCell) ⇒ <code>H3Index</code>
-    * [.cellToLatLng(h3Index)](#module_h3.cellToLatLng) ⇒ <code>Array.&lt;number&gt;</code>
-    * [.cellToBoundary(h3Index, [formatAsGeoJson])](#module_h3.cellToBoundary) ⇒ <code>Array.&lt;Array.&lt;number&gt;&gt;</code>
+    * [.cellToLatLng(h3Index)](#module_h3.cellToLatLng) ⇒ <code>CoordPair</code>
+    * [.cellToBoundary(h3Index, [formatAsGeoJson])](#module_h3.cellToBoundary) ⇒ <code>Array.&lt;CoordPair&gt;</code>
     * [.cellToParent(h3Index, res)](#module_h3.cellToParent) ⇒ <code>H3Index</code>
     * [.cellToChildren(h3Index, res)](#module_h3.cellToChildren) ⇒ <code>Array.&lt;H3Index&gt;</code>
     * [.cellToCenterChild(h3Index, res)](#module_h3.cellToCenterChild) ⇒ <code>H3Index</code>
     * [.gridDisk(h3Index, ringSize)](#module_h3.gridDisk) ⇒ <code>Array.&lt;H3Index&gt;</code>
     * [.gridDiskDistances(h3Index, ringSize)](#module_h3.gridDiskDistances) ⇒ <code>Array.&lt;Array.&lt;H3Index&gt;&gt;</code>
     * [.gridRingUnsafe(h3Index, ringSize)](#module_h3.gridRingUnsafe) ⇒ <code>Array.&lt;H3Index&gt;</code>
     * [.polygonToCells(coordinates, res, [isGeoJson])](#module_h3.polygonToCells) ⇒ <code>Array.&lt;H3Index&gt;</code>
-    * [.cellsToMultiPolygon(h3Indexes, [formatAsGeoJson])](#module_h3.cellsToMultiPolygon) ⇒ <code>Array.&lt;Array.&lt;Array.&lt;Array.&lt;number&gt;&gt;&gt;&gt;</code>
+    * [.cellsToMultiPolygon(h3Indexes, [formatAsGeoJson])](#module_h3.cellsToMultiPolygon) ⇒ <code>Array.&lt;Array.&lt;Array.&lt;CoordPair&gt;&gt;&gt;</code>
     * [.compactCells(h3Set)](#module_h3.compactCells) ⇒ <code>Array.&lt;H3Index&gt;</code>
     * [.uncompactCells(compactedSet, res)](#module_h3.uncompactCells) ⇒ <code>Array.&lt;H3Index&gt;</code>
     * [.areNeighborCells(origin, destination)](#module_h3.areNeighborCells) ⇒ <code>boolean</code>
@@ -127,7 +127,7 @@ const coordinates = h3.cellsToMultiPolygon(hexagons, true);
     * [.isValidDirectedEdge(edgeIndex)](#module_h3.isValidDirectedEdge) ⇒ <code>boolean</code>
     * [.directedEdgeToCells(edgeIndex)](#module_h3.directedEdgeToCells) ⇒ <code>Array.&lt;H3Index&gt;</code>
     * [.originToDirectedEdges(h3Index)](#module_h3.originToDirectedEdges) ⇒ <code>Array.&lt;H3Index&gt;</code>
-    * [.directedEdgeToBoundary(edgeIndex, [formatAsGeoJson])](#module_h3.directedEdgeToBoundary) ⇒ <code>Array.&lt;Array.&lt;number&gt;&gt;</code>
+    * [.directedEdgeToBoundary(edgeIndex, [formatAsGeoJson])](#module_h3.directedEdgeToBoundary) ⇒ <code>Array.&lt;CoordPair&gt;</code>
     * [.gridDistance(origin, destination)](#module_h3.gridDistance) ⇒ <code>number</code>
     * [.gridPathCells(origin, destination)](#module_h3.gridPathCells) ⇒ <code>Array.&lt;H3Index&gt;</code>
     * [.cellToLocalIj(origin, destination)](#module_h3.cellToLocalIj) ⇒ <code>CoordIJ</code>
@@ -139,7 +139,7 @@ const coordinates = h3.cellsToMultiPolygon(hexagons, true);
     * [.getHexagonEdgeLengthAvg(res, unit)](#module_h3.getHexagonEdgeLengthAvg) ⇒ <code>number</code>
     * [.cellToVertex(h3Index, vertexNum)](#module_h3.cellToVertex) ⇒ <code>H3Index</code>
     * [.cellToVertexes(h3Index)](#module_h3.cellToVertexes) ⇒ <code>Array.&lt;H3Index&gt;</code>
-    * [.vertexToLatLng(h3Index)](#module_h3.vertexToLatLng) ⇒ <code>Array.&lt;number&gt;</code>
+    * [.vertexToLatLng(h3Index)](#module_h3.vertexToLatLng) ⇒ <code>CoordPair</code>
     * [.isValidVertex(h3Index)](#module_h3.isValidVertex) ⇒ <code>boolean</code>
     * [.getNumCells(res)](#module_h3.getNumCells) ⇒ <code>number</code>
     * [.getRes0Cells()](#module_h3.getRes0Cells) ⇒ <code>Array.&lt;H3Index&gt;</code>
@@ -148,15 +148,17 @@ const coordinates = h3.cellsToMultiPolygon(hexagons, true);
     * [.radsToDegs(rad)](#module_h3.radsToDegs) ⇒ <code>number</code>
     * [.H3Index](#module_h3.H3Index) : <code>string</code>
     * [.H3IndexInput](#module_h3.H3IndexInput) : <code>string</code> \| <code>Array.&lt;number&gt;</code>
-    * [.CoordIJ](#module_h3.CoordIJ) : <code>Object</code>
-    * [.H3Error](#module_h3.H3Error) ⇐ <code>Error</code>
+    * [.CoordIJ](#module_h3.CoordIJ)
+    * [.H3Error](#module_h3.H3Error)
+    * [.CoordPair](#module_h3.CoordPair) : <code>Array.&lt;number&gt;</code>
+    * [.SplitLong](#module_h3.SplitLong) : <code>Array.&lt;number&gt;</code>
 
 
 * * *
 
 <a name="module_h3.UNITS"></a>
 
-### h3.UNITS : <code>Object</code>
+### h3.UNITS
 Length/Area units
 
 **Properties**
@@ -175,10 +177,10 @@ Length/Area units
 
 <a name="module_h3.h3IndexToSplitLong"></a>
 
-### h3.h3IndexToSplitLong(h3Index) ⇒ <code>Array.&lt;number&gt;</code>
+### h3.h3IndexToSplitLong(h3Index) ⇒ <code>SplitLong</code>
 Convert an H3 index (64-bit hexidecimal string) into a "split long" - a pair of 32-bit ints
 
-**Returns**: <code>Array.&lt;number&gt;</code> - A two-element array with 32 lower bits and 32 upper bits  
+**Returns**: <code>SplitLong</code> - A two-element array with 32 lower bits and 32 upper bits  
 
 | Param | Type | Description |
 | --- | --- | --- |
@@ -314,10 +316,10 @@ Get the hexagon containing a lat,lon point
 
 <a name="module_h3.cellToLatLng"></a>
 
-### h3.cellToLatLng(h3Index) ⇒ <code>Array.&lt;number&gt;</code>
+### h3.cellToLatLng(h3Index) ⇒ <code>CoordPair</code>
 Get the lat,lon center of a given hexagon
 
-**Returns**: <code>Array.&lt;number&gt;</code> - Point as a [lat, lng] pair  
+**Returns**: <code>CoordPair</code> - Point as a [lat, lng] pair  
 **Throws**:
 
 - <code>H3Error</code> If input is invalid
@@ -332,12 +334,12 @@ Get the lat,lon center of a given hexagon
 
 <a name="module_h3.cellToBoundary"></a>
 
-### h3.cellToBoundary(h3Index, [formatAsGeoJson]) ⇒ <code>Array.&lt;Array.&lt;number&gt;&gt;</code>
+### h3.cellToBoundary(h3Index, [formatAsGeoJson]) ⇒ <code>Array.&lt;CoordPair&gt;</code>
 Get the vertices of a given hexagon (or pentagon), as an array of [lat, lng]
 points. For pentagons and hexagons on the edge of an icosahedron face, this
 function may return up to 10 vertices.
 
-**Returns**: <code>Array.&lt;Array.&lt;number&gt;&gt;</code> - Array of [lat, lng] pairs  
+**Returns**: <code>Array.&lt;CoordPair&gt;</code> - Array of [lat, lng] pairs  
 **Throws**:
 
 - <code>H3Error</code> If input is invalid
@@ -494,7 +496,7 @@ expected to be holes.
 
 <a name="module_h3.cellsToMultiPolygon"></a>
 
-### h3.cellsToMultiPolygon(h3Indexes, [formatAsGeoJson]) ⇒ <code>Array.&lt;Array.&lt;Array.&lt;Array.&lt;number&gt;&gt;&gt;&gt;</code>
+### h3.cellsToMultiPolygon(h3Indexes, [formatAsGeoJson]) ⇒ <code>Array.&lt;Array.&lt;Array.&lt;CoordPair&gt;&gt;&gt;</code>
 Get the outlines of a set of H3 hexagons, returned in GeoJSON MultiPolygon
 format (an array of polygons, each with an array of loops, each an array of
 coordinates). Coordinates are returned as [lat, lng] pairs unless GeoJSON
@@ -505,7 +507,7 @@ set have the same resolution and that the set contains no duplicates. Behavior
 is undefined if duplicates or multiple resolutions are present, and the
 algorithm may produce unexpected or invalid polygons.
 
-**Returns**: <code>Array.&lt;Array.&lt;Array.&lt;Array.&lt;number&gt;&gt;&gt;&gt;</code> - MultiPolygon-style output.  
+**Returns**: <code>Array.&lt;Array.&lt;Array.&lt;CoordPair&gt;&gt;&gt;</code> - MultiPolygon-style output.  
 **Throws**:
 
 - <code>H3Error</code> If input is invalid
@@ -514,7 +516,7 @@ algorithm may produce unexpected or invalid polygons.
 | Param | Type | Description |
 | --- | --- | --- |
 | h3Indexes | <code>Array.&lt;H3IndexInput&gt;</code> | H3 indexes to get outlines for |
-| [formatAsGeoJson] | <code>boolean</code> | Whether to provide GeoJSON output:                                    [lng, lat], closed loops |
+| [formatAsGeoJson] | <code>boolean</code> | Whether to provide GeoJSON output: [lng, lat], closed loops |
 
 
 * * *
@@ -684,11 +686,11 @@ every neighbor)
 
 <a name="module_h3.directedEdgeToBoundary"></a>
 
-### h3.directedEdgeToBoundary(edgeIndex, [formatAsGeoJson]) ⇒ <code>Array.&lt;Array.&lt;number&gt;&gt;</code>
+### h3.directedEdgeToBoundary(edgeIndex, [formatAsGeoJson]) ⇒ <code>Array.&lt;CoordPair&gt;</code>
 Get the vertices of a given edge as an array of [lat, lng] points. Note that for edges that
 cross the edge of an icosahedron face, this may return 3 coordinates.
 
-**Returns**: <code>Array.&lt;Array.&lt;number&gt;&gt;</code> - Array of geo coordinate pairs  
+**Returns**: <code>Array.&lt;CoordPair&gt;</code> - Array of geo coordinate pairs  
 **Throws**:
 
 - <code>H3Error</code> If the input is invalid
@@ -947,10 +949,10 @@ Find the indexes for all vertexes of a cell.
 
 <a name="module_h3.vertexToLatLng"></a>
 
-### h3.vertexToLatLng(h3Index) ⇒ <code>Array.&lt;number&gt;</code>
+### h3.vertexToLatLng(h3Index) ⇒ <code>CoordPair</code>
 Get the lat, lng of a given vertex
 
-**Returns**: <code>Array.&lt;number&gt;</code> - Latitude, longitude coordinates of the vertex  
+**Returns**: <code>CoordPair</code> - Latitude, longitude coordinates of the vertex  
 **Throws**:
 
 - <code>H3Error</code> If the input is invalid
@@ -1073,7 +1075,7 @@ or two 32-bit integers in little endian order in an array.
 
 <a name="module_h3.CoordIJ"></a>
 
-### h3.CoordIJ : <code>Object</code>
+### h3.CoordIJ
 Coordinates as an `{i, j}` pair
 
 **Properties**
@@ -1088,11 +1090,10 @@ Coordinates as an `{i, j}` pair
 
 <a name="module_h3.H3Error"></a>
 
-### h3.H3Error ⇐ <code>Error</code>
-Custom JS Error with an attached error code. Error codes come from the
+### h3.H3Error
+Custom JS Error instance with an attached error code. Error codes come from the
 core H3 library and can be found [in the H3 docs](https://h3geo.org/docs/next/library/errors#table-of-error-codes).
 
-**Extends**: <code>Error</code>  
 **Properties**
 
 | Name | Type |
@@ -1101,6 +1102,22 @@ core H3 library and can be found [in the H3 docs](https://h3geo.org/docs/next/li
 | code | <code>number</code> | 
 
 
+* * *
+
+<a name="module_h3.CoordPair"></a>
+
+### h3.CoordPair : <code>Array.&lt;number&gt;</code>
+Pair of lat,lng coordinates (or lng,lat if GeoJSON output is specified)
+
+
+* * *
+
+<a name="module_h3.SplitLong"></a>
+
+### h3.SplitLong : <code>Array.&lt;number&gt;</code>
+Pair of lower,upper 32-bit ints representing a 64-bit value
+
+
 * * *
 
 

diff --git a/build/pre.js b/build/pre.js
@@ -0,0 +1 @@
+// @ts-nocheck
diff --git a/lib/bindings.js b/lib/bindings.js
@@ -28,6 +28,7 @@ const POINTER = NUMBER;
 // Define the bindings to functions in the C lib. Functions are defined as
 // [name, return type, [arg types]]. You must run `npm run build-emscripten`
 // before new functions added here will be available.
+/** @type {([string, string] | [string, string | null, string[]])[]} */
 export default [
     // The size functions are inserted via build/sizes.h
     ['sizeOfH3Index', NUMBER],

diff --git a/lib/errors.js b/lib/errors.js
@@ -59,6 +59,7 @@ const H3_ERROR_MSGS = {
 // Error codes for JS errors thrown in the bindings
 export const E_UNKNOWN_UNIT = 1000;
 export const E_ARRAY_LENGTH = 1001;
+export const E_NULL_INDEX = 1002;
 
 /**
  * Error messages for errors thrown in the binding code. These don't strictly
@@ -67,7 +68,8 @@ export const E_ARRAY_LENGTH = 1001;
  */
 const JS_ERROR_MESSAGES = {
     [E_UNKNOWN_UNIT]: 'Unknown unit',
-    [E_ARRAY_LENGTH]: 'Array length out of bounds'
+    [E_ARRAY_LENGTH]: 'Array length out of bounds',
+    [E_NULL_INDEX]: 'Got unexpected null value for H3 index'
 };
 
 const UNKNOWN_ERROR_MSG = 'Unknown error';
@@ -77,17 +79,18 @@ const UNKNOWN_ERROR_MSG = 'Unknown error';
  * @private
  * @param {Record<number, string>} messages  Map of code-to-messages to use
  * @param {number} errCode                   Numeric error code
- * @param {{value: unknown}} meta            Metadata with value to associate with the error
+ * @param {{value: unknown} | {}} [meta]     Metadata with value to associate with the error
  */
 function createError(messages, errCode, meta) {
     // The error value may be "undefined", so check if the argument was provided
-    const hasValue = 'value' in meta;
+    const hasValue = meta && 'value' in meta;
     // Throw a custom error type with the code attached
     const err = new Error(
         `${messages[errCode] || UNKNOWN_ERROR_MSG} (code: ${errCode}${
             hasValue ? `, value: ${meta.value}` : ''
         })`
     );
+    // @ts-expect-error - TS doesn't like extending Error
     err.code = errCode;
     return err;
 }
@@ -96,7 +99,7 @@ function createError(messages, errCode, meta) {
  * Custom error for H3Error codes
  * @private
  * @param {number} errCode     Error code from the H3 library
- * @param {unknown} value      Value to associate with the error, if any
+ * @param {unknown} [value]    Value to associate with the error, if any
  * @returns {Error}
  */
 export function H3LibraryError(errCode, value) {
@@ -109,7 +112,7 @@ export function H3LibraryError(errCode, value) {
  * Custom errors thrown from the JS bindings.
  * @private
  * @param {number} errCode     Error code from the H3 library
- * @param {unknown} value      Value to associate with the error, if any
+ * @param {unknown} [value]    Value to associate with the error, if any
  * @returns {Error}
  */
 export function JSBindingError(errCode, value) {
@@ -121,7 +124,7 @@ export function JSBindingError(errCode, value) {
 /**
  * Throw a JavaScript error if the C library return code is an error
  * @private
- * @param {number} err Error code from the H3 library
+ * @param {number} errCode     Error code from the H3 library
  * @throws {Error} Error if err is not E_SUCCESS (0)
  */
 export function throwIfError(errCode) {