h3-js - npm Package Compare versions

Comparing version 4.0.0-rc3 to 4.0.0-rc4

CHANGELOG.md

@@ -7,5 +7,11 @@ # Change Log
 
+## [4.0.0-rc4] - 2022-08-22
+### Breaking changes
+- Updated the core library to `v4.0.0-rc5`. (#151)
+### Changed
+- Add Typescript typechecking, generate types with tsc (#153)
+
 ## [4.0.0-rc3] - 2022-08-11
 ### Fixed
-- Fail package publish if there are library changes
+- Fail package publish if there are library changes (#148)
 
@@ -12,0 +18,0 @@ ## [4.0.0-rc2] - 2022-08-11

dist/legacy-types.d.ts

 declare module "h3-js" {
     /**
-     * 64-bit hexidecimal string representation of an H3 index
-     */
-    type H3Index = string;
-    /**
-     * 64-bit hexidecimal string representation of an H3 index,
-     * or two 32-bit integers in little endian order in an array.
-     */
-    type H3IndexInput = string | number[];
-    /**
-     * Coordinates as an `{i, j}` pair
-     */
-    type CoordIJ = {
-        i: number;
-        j: number;
-    };
-    /**
-     * Custom JS Error 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).
-     */
-    type H3Error = {
-        message: string;
-        code: number;
-    };
-    /**
-     * Length/Area units
-     */
-    const UNITS: {
-        m: string;
-        m2: string;
-        km: string;
-        km2: string;
-        rads: string;
-        rads2: string;
-    };
-    /**
      * Convert an H3 index (64-bit hexidecimal string) into a "split long" - a pair of 32-bit ints
-     * @param h3Index - H3 index to check
-     * @returns A two-element array with 32 lower bits and 32 upper bits
+     * @param  {H3IndexInput} h3Index  H3 index to check
+     * @return {SplitLong}             A two-element array with 32 lower bits and 32 upper bits
      */
-    function h3IndexToSplitLong(h3Index: H3IndexInput): number[];
+    export function h3IndexToSplitLong(h3Index: H3IndexInput): SplitLong;
     /**
      * Get a H3 index string from a split long (pair of 32-bit ints)
-     * @param lower - Lower 32 bits
-     * @param upper - Upper 32 bits
-     * @returns H3 index
+     * @param  {number} lower Lower 32 bits
+     * @param  {number} upper Upper 32 bits
+     * @return {H3Index}       H3 index
      */
-    function splitLongToH3Index(lower: number, upper: number): H3Index;
+    export function splitLongToH3Index(lower: number, upper: number): H3Index;
     /**
      * Whether a given string represents a valid H3 index
-     * @param h3Index - H3 index to check
-     * @returns Whether the index is valid
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index to check
+     * @return {boolean}          Whether the index is valid
      */
-    function h3IsValid(h3Index: H3IndexInput): boolean;
+    export function h3IsValid(h3Index: H3IndexInput): boolean;
     /**
      * Whether the given H3 index is a pentagon
-     * @param h3Index - H3 index to check
-     * @returns h3IsPentagon
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index to check
+     * @return {boolean}          h3IsPentagon
      */
-    function h3IsPentagon(h3Index: H3IndexInput): boolean;
+    export function h3IsPentagon(h3Index: H3IndexInput): boolean;
     /**
@@ -66,38 +33,47 @@ * Whether the given H3 index is in a Class III resolution (rotated versus
      * icosahedron edges, making them not true hexagons).
-     * @param h3Index - H3 index to check
-     * @returns h3IsResClassIII
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index to check
+     * @return {boolean}          h3IsResClassIII
      */
-    function h3IsResClassIII(h3Index: H3IndexInput): boolean;
+    export function h3IsResClassIII(h3Index: H3IndexInput): boolean;
     /**
      * Get the number of the base cell for a given H3 index
-     * @param h3Index - H3 index to get the base cell for
-     * @returns Index of the base cell (0-121)
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index to get the base cell for
+     * @return {number}           Index of the base cell (0-121)
      */
-    function h3GetBaseCell(h3Index: H3IndexInput): number;
+    export function h3GetBaseCell(h3Index: H3IndexInput): number;
     /**
      * Get the indices of all icosahedron faces intersected by a given H3 index
-     * @param h3Index - H3 index to get faces for
-     * @returns Indices (0-19) of all intersected faces
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index to get faces for
+     * @return {number[]}              Indices (0-19) of all intersected faces
+     * @throws {H3Error}               If input is invalid
      */
-    function h3GetFaces(h3Index: H3IndexInput): number[];
+    export function h3GetFaces(h3Index: H3IndexInput): number[];
     /**
      * Returns the resolution of an H3 index
-     * @param h3Index - H3 index to get resolution
-     * @returns The number (0-15) resolution, or -1 if invalid
+     * @static
+     * @param  {H3IndexInput} h3Index H3 index to get resolution
+     * @return {number}          The number (0-15) resolution, or -1 if invalid
      */
-    function h3GetResolution(h3Index: H3IndexInput): number;
+    export function h3GetResolution(h3Index: H3IndexInput): number;
     /**
      * Get the hexagon containing a lat,lon point
-     * @param lat - Latitude of point
-     * @param lng - Longtitude of point
-     * @param res - Resolution of hexagons to return
-     * @returns H3 index
+     * @static
+     * @param  {number} lat Latitude of point
+     * @param  {number} lng Longtitude of point
+     * @param  {number} res Resolution of hexagons to return
+     * @return {H3Index}    H3 index
+     * @throws {H3Error}    If input is invalid
      */
-    function geoToH3(lat: number, lng: number, res: number): H3Index;
+    export function geoToH3(lat: number, lng: number, res: number): H3Index;
     /**
      * Get the lat,lon center of a given hexagon
-     * @param h3Index - H3 index
-     * @returns Point as a [lat, lng] pair
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index
+     * @return {CoordPair}             Point as a [lat, lng] pair
+     * @throws {H3Error}               If input is invalid
      */
-    function h3ToGeo(h3Index: H3IndexInput): number[];
+    export function h3ToGeo(h3Index: H3IndexInput): CoordPair;
     /**
@@ -107,51 +83,66 @@ * Get the vertices of a given hexagon (or pentagon), as an array of [lat, lng]
      * function may return up to 10 vertices.
-     * @param h3Index - H3 index
-     * @param [formatAsGeoJson] - Whether to provide GeoJSON output: [lng, lat], closed loops
-     * @returns Array of [lat, lng] pairs
+     * @static
+     * @param  {H3Index} h3Index          H3 index
+     * @param {boolean} [formatAsGeoJson] Whether to provide GeoJSON output: [lng, lat], closed loops
+     * @return {CoordPair[]}              Array of [lat, lng] pairs
+     * @throws {H3Error}                  If input is invalid
      */
-    function h3ToGeoBoundary(h3Index: H3Index, formatAsGeoJson?: boolean): number[][];
+    export function h3ToGeoBoundary(h3Index: H3Index, formatAsGeoJson?: boolean): CoordPair[];
     /**
      * Get the parent of the given hexagon at a particular resolution
-     * @param h3Index - H3 index to get parent for
-     * @param res - Resolution of hexagon to return
-     * @returns H3 index of parent, or null for invalid input
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index to get parent for
+     * @param  {number} res       Resolution of hexagon to return
+     * @return {H3Index}          H3 index of parent, or null for invalid input
+     * @throws {H3Error}          If input is invalid
      */
-    function h3ToParent(h3Index: H3IndexInput, res: number): H3Index;
+    export function h3ToParent(h3Index: H3IndexInput, res: number): H3Index;
     /**
      * Get the children/descendents of the given hexagon at a particular resolution
-     * @param h3Index - H3 index to get children for
-     * @param res - Resolution of hexagons to return
-     * @returns H3 indexes of children, or empty array for invalid input
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index to get children for
+     * @param  {number} res       Resolution of hexagons to return
+     * @return {H3Index[]}        H3 indexes of children, or empty array for invalid input
+     * @throws {H3Error}          If resolution is invalid or output is too large for JS
      */
-    function h3ToChildren(h3Index: H3IndexInput, res: number): H3Index[];
+    export function h3ToChildren(h3Index: H3IndexInput, res: number): H3Index[];
     /**
      * Get the center child of the given hexagon at a particular resolution
-     * @param h3Index - H3 index to get center child for
-     * @param res - Resolution of hexagon to return
-     * @returns H3 index of child, or null for invalid input
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index to get center child for
+     * @param  {number} res       Resolution of hexagon to return
+     * @return {H3Index}          H3 index of child, or null for invalid input
+     * @throws {H3Error}          If resolution is invalid
      */
-    function h3ToCenterChild(h3Index: H3IndexInput, res: number): H3Index;
+    export function h3ToCenterChild(h3Index: H3IndexInput, res: number): H3Index;
     /**
      * Get all hexagons in a k-ring around a given center. The order of the hexagons is undefined.
-     * @param h3Index - H3 index of center hexagon
-     * @param ringSize - Radius of k-ring
-     * @returns H3 indexes for all hexagons in ring
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index of center hexagon
+     * @param  {number} ringSize  Radius of k-ring
+     * @return {H3Index[]}        H3 indexes for all hexagons in ring
+     * @throws {H3Error}          If input is invalid or output is too large for JS
      */
-    function kRing(h3Index: H3IndexInput, ringSize: number): H3Index[];
+    export function kRing(h3Index: H3IndexInput, ringSize: number): H3Index[];
     /**
      * Get all hexagons in a k-ring around a given center, in an array of arrays
      * ordered by distance from the origin. The order of the hexagons within each ring is undefined.
-     * @param h3Index - H3 index of center hexagon
-     * @param ringSize - Radius of k-ring
-     * @returns Array of arrays with H3 indexes for all hexagons each ring
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index of center hexagon
+     * @param  {number} ringSize  Radius of k-ring
+     * @return {H3Index[][]}      Array of arrays with H3 indexes for all hexagons each ring
+     * @throws {H3Error}          If input is invalid or output is too large for JS
      */
-    function kRingDistances(h3Index: H3IndexInput, ringSize: number): H3Index[][];
+    export function kRingDistances(h3Index: H3IndexInput, ringSize: number): H3Index[][];
     /**
      * Get all hexagons in a hollow hexagonal ring centered at origin with sides of a given length.
      * Unlike kRing, this function will throw an error if there is a pentagon anywhere in the ring.
-     * @param h3Index - H3 index of center hexagon
-     * @param ringSize - Radius of ring
-     * @returns H3 indexes for all hexagons in ring
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index of center hexagon
+     * @param  {number} ringSize  Radius of ring
+     * @return {H3Index[]}        H3 indexes for all hexagons in ring
+     * @throws {Error}            If the algorithm could not calculate the ring
+     * @throws {H3Error}          If input is invalid
      */
-    function hexRing(h3Index: H3IndexInput, ringSize: number): H3Index[];
+    export function hexRing(h3Index: H3IndexInput, ringSize: number): H3Index[];
     /**
@@ -163,9 +154,12 @@ * Get all hexagons with centers contained in a given polygon. The polygon
      * expected to be holes.
-     * @param coordinates - Array of loops, or a single loop
-     * @param res - Resolution of hexagons to return
-     * @param [isGeoJson] - Whether to expect GeoJson-style [lng, lat]
+     * @static
+     * @param  {number[][] | number[][][]} coordinates
+     *                                  Array of loops, or a single loop
+     * @param  {number} res             Resolution of hexagons to return
+     * @param  {boolean} [isGeoJson]    Whether to expect GeoJson-style [lng, lat]
      *                                  pairs instead of [lat, lng]
-     * @returns H3 indexes for all hexagons in polygon
+     * @return {H3Index[]}              H3 indexes for all hexagons in polygon
+     * @throws {H3Error}                If input is invalid or output is too large for JS
      */
-    function polyfill(coordinates: number[][] | number[][][], res: number, isGeoJson?: boolean): H3Index[];
+    export function polyfill(coordinates: number[][] | number[][][], res: number, isGeoJson?: boolean): H3Index[];
     /**
@@ -181,75 +175,96 @@ * Get the outlines of a set of H3 hexagons, returned in GeoJSON MultiPolygon
      * algorithm may produce unexpected or invalid polygons.
-     * @param h3Indexes - H3 indexes to get outlines for
-     * @param [formatAsGeoJson] - Whether to provide GeoJSON output:
-     *                                    [lng, lat], closed loops
-     * @returns MultiPolygon-style output.
+     *
+     * @static
+     * @param {H3IndexInput[]} h3Indexes  H3 indexes to get outlines for
+     * @param {boolean} [formatAsGeoJson] Whether to provide GeoJSON output: [lng, lat], closed loops
+     * @return {CoordPair[][][]}          MultiPolygon-style output.
+     * @throws {H3Error}                  If input is invalid
      */
-    function h3SetToMultiPolygon(h3Indexes: H3IndexInput[], formatAsGeoJson?: boolean): number[][][][];
+    export function h3SetToMultiPolygon(h3Indexes: H3IndexInput[], formatAsGeoJson?: boolean): CoordPair[][][];
     /**
      * Compact a set of hexagons of the same resolution into a set of hexagons across
      * multiple levels that represents the same area.
-     * @param h3Set - H3 indexes to compact
-     * @returns Compacted H3 indexes
+     * @static
+     * @param  {H3IndexInput[]} h3Set H3 indexes to compact
+     * @return {H3Index[]}       Compacted H3 indexes
+     * @throws {H3Error}         If the input is invalid (e.g. duplicate hexagons)
      */
-    function compact(h3Set: H3IndexInput[]): H3Index[];
+    export function compact(h3Set: H3IndexInput[]): H3Index[];
     /**
      * Uncompact a compacted set of hexagons to hexagons of the same resolution
-     * @param compactedSet - H3 indexes to uncompact
-     * @param res - The resolution to uncompact to
-     * @returns The uncompacted H3 indexes
+     * @static
+     * @param  {H3IndexInput[]} compactedSet H3 indexes to uncompact
+     * @param  {number}    res          The resolution to uncompact to
+     * @return {H3Index[]}              The uncompacted H3 indexes
+     * @throws {H3Error}                If the input is invalid (e.g. invalid resolution)
      */
-    function uncompact(compactedSet: H3IndexInput[], res: number): H3Index[];
+    export function uncompact(compactedSet: H3IndexInput[], res: number): H3Index[];
     /**
      * Whether two H3 indexes are neighbors (share an edge)
-     * @param origin - Origin hexagon index
-     * @param destination - Destination hexagon index
-     * @returns Whether the hexagons share an edge
+     * @static
+     * @param  {H3IndexInput} origin      Origin hexagon index
+     * @param  {H3IndexInput} destination Destination hexagon index
+     * @return {boolean}             Whether the hexagons share an edge
+     * @throws {H3Error}             If the input is invalid
      */
-    function h3IndexesAreNeighbors(origin: H3IndexInput, destination: H3IndexInput): boolean;
+    export function h3IndexesAreNeighbors(origin: H3IndexInput, destination: H3IndexInput): boolean;
     /**
      * Get an H3 index representing a unidirectional edge for a given origin and destination
-     * @param origin - Origin hexagon index
-     * @param destination - Destination hexagon index
-     * @returns H3 index of the edge, or null if no edge is shared
+     * @static
+     * @param  {H3IndexInput} origin      Origin hexagon index
+     * @param  {H3IndexInput} destination Destination hexagon index
+     * @return {H3Index}             H3 index of the edge, or null if no edge is shared
+     * @throws {H3Error}             If the input is invalid
      */
-    function getH3UnidirectionalEdge(origin: H3IndexInput, destination: H3IndexInput): H3Index;
+    export function getH3UnidirectionalEdge(origin: H3IndexInput, destination: H3IndexInput): H3Index;
     /**
      * Get the origin hexagon from an H3 index representing a unidirectional edge
-     * @param edgeIndex - H3 index of the edge
-     * @returns H3 index of the edge origin
+     * @static
+     * @param  {H3IndexInput} edgeIndex H3 index of the edge
+     * @return {H3Index}           H3 index of the edge origin
+     * @throws {H3Error}           If the input is invalid
      */
-    function getOriginH3IndexFromUnidirectionalEdge(edgeIndex: H3IndexInput): H3Index;
+    export function getOriginH3IndexFromUnidirectionalEdge(edgeIndex: H3IndexInput): H3Index;
     /**
      * Get the destination hexagon from an H3 index representing a unidirectional edge
-     * @param edgeIndex - H3 index of the edge
-     * @returns H3 index of the edge destination
+     * @static
+     * @param  {H3IndexInput} edgeIndex H3 index of the edge
+     * @return {H3Index}           H3 index of the edge destination
+     * @throws {H3Error}           If the input is invalid
      */
-    function getDestinationH3IndexFromUnidirectionalEdge(edgeIndex: H3IndexInput): H3Index;
+    export function getDestinationH3IndexFromUnidirectionalEdge(edgeIndex: H3IndexInput): H3Index;
     /**
      * Whether the input is a valid unidirectional edge
-     * @param edgeIndex - H3 index of the edge
-     * @returns Whether the index is valid
+     * @static
+     * @param  {H3IndexInput} edgeIndex H3 index of the edge
+     * @return {boolean}           Whether the index is valid
      */
-    function h3UnidirectionalEdgeIsValid(edgeIndex: H3IndexInput): boolean;
+    export function h3UnidirectionalEdgeIsValid(edgeIndex: H3IndexInput): boolean;
     /**
      * Get the [origin, destination] pair represented by a unidirectional edge
-     * @param edgeIndex - H3 index of the edge
-     * @returns [origin, destination] pair as H3 indexes
+     * @static
+     * @param  {H3IndexInput} edgeIndex H3 index of the edge
+     * @return {H3Index[]}         [origin, destination] pair as H3 indexes
+     * @throws {H3Error}           If the input is invalid
      */
-    function getH3IndexesFromUnidirectionalEdge(edgeIndex: H3IndexInput): H3Index[];
+    export function getH3IndexesFromUnidirectionalEdge(edgeIndex: H3IndexInput): H3Index[];
     /**
      * Get all of the unidirectional edges with the given H3 index as the origin (i.e. an edge to
      * every neighbor)
-     * @param h3Index - H3 index of the origin hexagon
-     * @returns List of unidirectional edges
+     * @static
+     * @param  {H3IndexInput} h3Index   H3 index of the origin hexagon
+     * @return {H3Index[]}         List of unidirectional edges
+     * @throws {H3Error}           If the input is invalid
      */
-    function getH3UnidirectionalEdgesFromHexagon(h3Index: H3IndexInput): H3Index[];
+    export function getH3UnidirectionalEdgesFromHexagon(h3Index: H3IndexInput): H3Index[];
     /**
      * 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.
-     * @param edgeIndex - H3 index of the edge
-     * @param [formatAsGeoJson] - Whether to provide GeoJSON output: [lng, lat]
-     * @returns Array of geo coordinate pairs
+     * @static
+     * @param  {H3IndexInput} edgeIndex        H3 index of the edge
+     * @param {boolean} [formatAsGeoJson] Whether to provide GeoJSON output: [lng, lat]
+     * @return {CoordPair[]}              Array of geo coordinate pairs
+     * @throws {H3Error}                  If the input is invalid
      */
-    function getH3UnidirectionalEdgeBoundary(edgeIndex: H3IndexInput, formatAsGeoJson?: boolean): number[][];
+    export function getH3UnidirectionalEdgeBoundary(edgeIndex: H3IndexInput, formatAsGeoJson?: boolean): CoordPair[];
     /**
@@ -259,7 +274,9 @@ * Get the grid distance between two hex indexes. This function may fail
      * on opposite sides of a pentagon.
-     * @param origin - Origin hexagon index
-     * @param destination - Destination hexagon index
-     * @returns Distance between hexagons
+     * @static
+     * @param  {H3IndexInput} origin      Origin hexagon index
+     * @param  {H3IndexInput} destination Destination hexagon index
+     * @return {number}          Distance between hexagons
+     * @throws {H3Error}         If input is invalid or the distance could not be calculated
      */
-    function h3Distance(origin: H3IndexInput, destination: H3IndexInput): number;
+    export function h3Distance(origin: H3IndexInput, destination: H3IndexInput): number;
     /**
@@ -280,7 +297,10 @@ * Given two H3 indexes, return the line of indexes between them (inclusive).
      *    Cartesian lines or great arcs.
-     * @param origin - Origin hexagon index
-     * @param destination - Destination hexagon index
-     * @returns H3 indexes connecting origin and destination
+     *
+     * @static
+     * @param  {H3IndexInput} origin      Origin hexagon index
+     * @param  {H3IndexInput} destination Destination hexagon index
+     * @return {H3Index[]}           H3 indexes connecting origin and destination
+     * @throws {H3Error}             If input is invalid or the line cannot be calculated
      */
-    function h3Line(origin: H3IndexInput, destination: H3IndexInput): H3Index[];
+    export function h3Line(origin: H3IndexInput, destination: H3IndexInput): H3Index[];
     /**
@@ -297,7 +317,9 @@ * Produces IJ coordinates for an H3 index anchored by an origin.
      * to be compatible across different versions of H3.
-     * @param origin - Origin H3 index
-     * @param destination - H3 index for which to find relative coordinates
-     * @returns Coordinates as an `{i, j}` pair
+     * @static
+     * @param  {H3IndexInput} origin      Origin H3 index
+     * @param  {H3IndexInput} destination H3 index for which to find relative coordinates
+     * @return {CoordIJ}             Coordinates as an `{i, j}` pair
+     * @throws {H3Error}             If the IJ coordinates cannot be calculated
      */
-    function experimentalH3ToLocalIj(origin: H3IndexInput, destination: H3IndexInput): CoordIJ;
+    export function experimentalH3ToLocalIj(origin: H3IndexInput, destination: H3IndexInput): CoordIJ;
     /**
@@ -314,69 +336,88 @@ * Produces an H3 index for IJ coordinates anchored by an origin.
      * to be compatible across different versions of H3.
-     * @param origin - Origin H3 index
-     * @param coords - Coordinates as an `{i, j}` pair
-     * @returns H3 index at the relative coordinates
+     * @static
+     * @param  {H3IndexInput} origin     Origin H3 index
+     * @param  {CoordIJ} coords     Coordinates as an `{i, j}` pair
+     * @return {H3Index}            H3 index at the relative coordinates
+     * @throws {H3Error}            If the H3 index cannot be calculated
      */
-    function experimentalLocalIjToH3(origin: H3IndexInput, coords: CoordIJ): H3Index;
+    export function experimentalLocalIjToH3(origin: H3IndexInput, coords: CoordIJ): H3Index;
     /**
      * Great circle distance between two geo points. This is not specific to H3,
      * but is implemented in the library and provided here as a convenience.
-     * @param latLng1 - Origin coordinate as [lat, lng]
-     * @param latLng2 - Destination coordinate as [lat, lng]
-     * @param unit - Distance unit (either UNITS.m, UNITS.km, or UNITS.rads)
-     * @returns Great circle distance
+     * @static
+     * @param  {number[]} latLng1 Origin coordinate as [lat, lng]
+     * @param  {number[]} latLng2 Destination coordinate as [lat, lng]
+     * @param  {string}   unit    Distance unit (either UNITS.m, UNITS.km, or UNITS.rads)
+     * @return {number}           Great circle distance
+     * @throws {H3Error}          If the unit is invalid
      */
-    function pointDist(latLng1: number[], latLng2: number[], unit: string): number;
+    export function pointDist(latLng1: number[], latLng2: number[], unit: string): number;
     /**
      * Exact area of a given cell
-     * @param h3Index - H3 index of the hexagon to measure
-     * @param unit - Distance unit (either UNITS.m2, UNITS.km2, or UNITS.rads2)
-     * @returns Cell area
+     * @static
+     * @param  {H3Index} h3Index  H3 index of the hexagon to measure
+     * @param  {string}  unit     Distance unit (either UNITS.m2, UNITS.km2, or UNITS.rads2)
+     * @return {number}           Cell area
+     * @throws {H3Error}          If the input is invalid
      */
-    function cellArea(h3Index: H3Index, unit: string): number;
+    export function cellArea(h3Index: H3Index, unit: string): number;
     /**
-     * Exact length of a given unidirectional edge
-     * @param edge - H3 index of the edge to measure
-     * @param unit - Distance unit (either UNITS.m, UNITS.km, or UNITS.rads)
-     * @returns Cell area
+     * Calculate length of a given unidirectional edge
+     * @static
+     * @param  {H3Index} edge     H3 index of the edge to measure
+     * @param  {string}  unit     Distance unit (either UNITS.m, UNITS.km, or UNITS.rads)
+     * @return {number}           Cell area
+     * @throws {H3Error}          If the input is invalid
      */
-    function exactEdgeLength(edge: H3Index, unit: string): number;
+    export function exactEdgeLength(edge: H3Index, unit: string): number;
     /**
      * Average hexagon area at a given resolution
-     * @param res - Hexagon resolution
-     * @param unit - Area unit (either UNITS.m2, UNITS.km2, or UNITS.rads2)
-     * @returns Average area
+     * @static
+     * @param  {number} res  Hexagon resolution
+     * @param  {string} unit Area unit (either UNITS.m2, UNITS.km2, or UNITS.rads2)
+     * @return {number}      Average area
+     * @throws {H3Error}     If the input is invalid
      */
-    function hexArea(res: number, unit: string): number;
+    export function hexArea(res: number, unit: string): number;
     /**
      * Average hexagon edge length at a given resolution
-     * @param res - Hexagon resolution
-     * @param unit - Distance unit (either UNITS.m, UNITS.km, or UNITS.rads)
-     * @returns Average edge length
+     * @static
+     * @param  {number} res  Hexagon resolution
+     * @param  {string} unit Distance unit (either UNITS.m, UNITS.km, or UNITS.rads)
+     * @return {number}      Average edge length
+     * @throws {H3Error}     If the input is invalid
      */
-    function edgeLength(res: number, unit: string): number;
+    export function edgeLength(res: number, unit: string): number;
     /**
      * Find the index for a vertex of a cell.
-     * @param h3Index - Cell to find the vertex for
-     * @param vertexNum - Number (index) of the vertex to calculate
-     * @returns Vertex index
+     * @static
+     * @param {H3IndexInput} h3Index     Cell to find the vertex for
+     * @param {number} vertexNum         Number (index) of the vertex to calculate
+     * @return {H3Index}     Vertex index
+     * @throws {H3Error}     If the input is invalid
      */
-    function cellToVertex(h3Index: H3IndexInput, vertexNum: number): H3Index;
+    export function cellToVertex(h3Index: H3IndexInput, vertexNum: number): H3Index;
     /**
      * Find the indexes for all vertexes of a cell.
-     * @param h3Index - Cell to find all vertexes for
-     * @returns All vertex indexes of this cell
+     * @static
+     * @param {H3IndexInput} h3Index     Cell to find all vertexes for
+     * @return {H3Index[]}   All vertex indexes of this cell
+     * @throws {H3Error}     If the input is invalid
      */
-    function cellToVertexes(h3Index: H3IndexInput): H3Index[];
+    export function cellToVertexes(h3Index: H3IndexInput): H3Index[];
     /**
      * Get the lat, lng of a given vertex
-     * @param h3Index - A vertex index
-     * @returns Latitude, longitude coordinates of the vertex
+     * @static
+     * @param {H3IndexInput} h3Index A vertex index
+     * @returns {CoordPair}          Latitude, longitude coordinates of the vertex
+     * @throws {H3Error}             If the input is invalid
      */
-    function vertexToLatLng(h3Index: H3IndexInput): number[];
+    export function vertexToLatLng(h3Index: H3IndexInput): CoordPair;
     /**
      * Returns true if the input is a valid vertex index.
-     * @param h3Index - An index to test for being a vertex index
-     * @returns True if the index represents a vertex
+     * @static
+     * @param {H3IndexInput} h3Index An index to test for being a vertex index
+     * @returns {boolean} True if the index represents a vertex
      */
-    function isValidVertex(h3Index: H3IndexInput): boolean;
+    export function isValidVertex(h3Index: H3IndexInput): boolean;
     /**
@@ -386,6 +427,8 @@ * The total count of hexagons in the world at a given resolution. Note that above
      * so consumers should use caution when applying further operations to the output.
-     * @param res - Hexagon resolution
-     * @returns Count
+     * @static
+     * @param  {number} res  Hexagon resolution
+     * @return {number}      Count
+     * @throws {H3Error}     If the resolution is invalid
      */
-    function numHexagons(res: number): number;
+    export function numHexagons(res: number): number;
     /**
@@ -395,25 +438,68 @@ * Get all H3 indexes at resolution 0. As every index at every resolution > 0 is
      * over H3 indexes at any resolution.
-     * @returns All H3 indexes at res 0
+     * @static
+     * @return {H3Index[]}  All H3 indexes at res 0
      */
-    function getRes0Indexes(): H3Index[];
+    export function getRes0Indexes(): H3Index[];
     /**
      * Get the twelve pentagon indexes at a given resolution.
-     * @param res - Hexagon resolution
-     * @returns All H3 pentagon indexes at res
+     * @static
+     * @param  {number} res  Hexagon resolution
+     * @return {H3Index[]}   All H3 pentagon indexes at res
+     * @throws {H3Error}     If the resolution is invalid
      */
-    function getPentagonIndexes(res: number): H3Index[];
+    export function getPentagonIndexes(res: number): H3Index[];
     /**
      * Convert degrees to radians
-     * @param deg - Value in degrees
-     * @returns Value in radians
+     * @static
+     * @param  {number} deg Value in degrees
+     * @return {number}     Value in radians
      */
-    function degsToRads(deg: number): number;
+    export function degsToRads(deg: number): number;
     /**
      * Convert radians to degrees
-     * @param rad - Value in radians
-     * @returns Value in degrees
+     * @static
+     * @param  {number} rad Value in radians
+     * @return {number}     Value in degrees
      */
-    function radsToDegs(rad: number): number;
+    export function radsToDegs(rad: number): number;
+    export namespace UNITS {
+        const m: string;
+        const m2: string;
+        const km: string;
+        const km2: string;
+        const rads: string;
+        const rads2: string;
+    }
+    /**
+     * 64-bit hexidecimal string representation of an H3 index
+     */
+    export type H3Index = string;
+    /**
+     * 64-bit hexidecimal string representation of an H3 index,
+     * or two 32-bit integers in little endian order in an array.
+     */
+    export type H3IndexInput = string | number[];
+    /**
+     * Coordinates as an `{i, j}` pair
+     */
+    export type CoordIJ = {
+        i: number;
+        j: number;
+    };
+    /**
+     * 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).
+     */
+    export type H3Error = {
+        message: string;
+        code: number;
+    };
+    /**
+     * Pair of lat,lng coordinates (or lng,lat if GeoJSON output is specified)
+     */
+    export type CoordPair = [number,number];
+    /**
+     * Pair of lower,upper 32-bit ints representing a 64-bit value
+     */
+    export type SplitLong = [number,number];
 }
-
-

dist/legacy.js

@@ -41,3 +41,3 @@
 cellArea: h3v4.cellArea,
-exactEdgeLength: h3v4.exactEdgeLength,
+exactEdgeLength: h3v4.edgeLength,
 hexArea: h3v4.getHexagonAreaAvg,
@@ -44,0 +44,0 @@ edgeLength: h3v4.getHexagonEdgeLengthAvg,

dist/print-bindings.js

@@ -33,2 +33,3 @@ 'use strict';
 // before new functions added here will be available.
+/** @type {([string, string] | [string, string | null, string[]])[]} */
 var BINDINGS = [
@@ -93,5 +94,5 @@ // The size functions are inserted via build/sizes.h
     ['cellAreaRads2', H3_ERROR, [H3_LOWER, H3_UPPER, POINTER]],
-    ['exactEdgeLengthM', H3_ERROR, [H3_LOWER, H3_UPPER, POINTER]],
-    ['exactEdgeLengthKm', H3_ERROR, [H3_LOWER, H3_UPPER, POINTER]],
-    ['exactEdgeLengthRads', H3_ERROR, [H3_LOWER, H3_UPPER, POINTER]],
+    ['edgeLengthM', H3_ERROR, [H3_LOWER, H3_UPPER, POINTER]],
+    ['edgeLengthKm', H3_ERROR, [H3_LOWER, H3_UPPER, POINTER]],
+    ['edgeLengthRads', H3_ERROR, [H3_LOWER, H3_UPPER, POINTER]],
     ['getNumCells', H3_ERROR, [RESOLUTION, POINTER]],
@@ -98,0 +99,0 @@ ['getRes0Cells', H3_ERROR, [POINTER]],

dist/types.d.ts

 declare module "h3-js" {
     /**
-     * 64-bit hexidecimal string representation of an H3 index
-     */
-    type H3Index = string;
-    /**
-     * 64-bit hexidecimal string representation of an H3 index,
-     * or two 32-bit integers in little endian order in an array.
-     */
-    type H3IndexInput = string | number[];
-    /**
-     * Coordinates as an `{i, j}` pair
-     */
-    type CoordIJ = {
-        i: number;
-        j: number;
-    };
-    /**
-     * Custom JS Error 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).
-     */
-    type H3Error = {
-        message: string;
-        code: number;
-    };
-    /**
-     * Length/Area units
-     */
-    const UNITS: {
-        m: string;
-        m2: string;
-        km: string;
-        km2: string;
-        rads: string;
-        rads2: string;
-    };
-    /**
      * Convert an H3 index (64-bit hexidecimal string) into a "split long" - a pair of 32-bit ints
-     * @param h3Index - H3 index to check
-     * @returns A two-element array with 32 lower bits and 32 upper bits
+     * @param  {H3IndexInput} h3Index  H3 index to check
+     * @return {SplitLong}             A two-element array with 32 lower bits and 32 upper bits
      */
-    function h3IndexToSplitLong(h3Index: H3IndexInput): number[];
+    export function h3IndexToSplitLong(h3Index: H3IndexInput): SplitLong;
     /**
      * Get a H3 index string from a split long (pair of 32-bit ints)
-     * @param lower - Lower 32 bits
-     * @param upper - Upper 32 bits
-     * @returns H3 index
+     * @param  {number} lower Lower 32 bits
+     * @param  {number} upper Upper 32 bits
+     * @return {H3Index}       H3 index
      */
-    function splitLongToH3Index(lower: number, upper: number): H3Index;
+    export function splitLongToH3Index(lower: number, upper: number): H3Index;
     /**
      * Whether a given string represents a valid H3 index
-     * @param h3Index - H3 index to check
-     * @returns Whether the index is valid
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index to check
+     * @return {boolean}          Whether the index is valid
      */
-    function isValidCell(h3Index: H3IndexInput): boolean;
+    export function isValidCell(h3Index: H3IndexInput): boolean;
     /**
      * Whether the given H3 index is a pentagon
-     * @param h3Index - H3 index to check
-     * @returns isPentagon
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index to check
+     * @return {boolean}          isPentagon
      */
-    function isPentagon(h3Index: H3IndexInput): boolean;
+    export function isPentagon(h3Index: H3IndexInput): boolean;
     /**
@@ -66,38 +33,47 @@ * Whether the given H3 index is in a Class III resolution (rotated versus
      * icosahedron edges, making them not true hexagons).
-     * @param h3Index - H3 index to check
-     * @returns isResClassIII
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index to check
+     * @return {boolean}          isResClassIII
      */
-    function isResClassIII(h3Index: H3IndexInput): boolean;
+    export function isResClassIII(h3Index: H3IndexInput): boolean;
     /**
      * Get the number of the base cell for a given H3 index
-     * @param h3Index - H3 index to get the base cell for
-     * @returns Index of the base cell (0-121)
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index to get the base cell for
+     * @return {number}           Index of the base cell (0-121)
      */
-    function getBaseCellNumber(h3Index: H3IndexInput): number;
+    export function getBaseCellNumber(h3Index: H3IndexInput): number;
     /**
      * Get the indices of all icosahedron faces intersected by a given H3 index
-     * @param h3Index - H3 index to get faces for
-     * @returns Indices (0-19) of all intersected faces
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index to get faces for
+     * @return {number[]}              Indices (0-19) of all intersected faces
+     * @throws {H3Error}               If input is invalid
      */
-    function getIcosahedronFaces(h3Index: H3IndexInput): number[];
+    export function getIcosahedronFaces(h3Index: H3IndexInput): number[];
     /**
      * Returns the resolution of an H3 index
-     * @param h3Index - H3 index to get resolution
-     * @returns The number (0-15) resolution, or -1 if invalid
+     * @static
+     * @param  {H3IndexInput} h3Index H3 index to get resolution
+     * @return {number}          The number (0-15) resolution, or -1 if invalid
      */
-    function getResolution(h3Index: H3IndexInput): number;
+    export function getResolution(h3Index: H3IndexInput): number;
     /**
      * Get the hexagon containing a lat,lon point
-     * @param lat - Latitude of point
-     * @param lng - Longtitude of point
-     * @param res - Resolution of hexagons to return
-     * @returns H3 index
+     * @static
+     * @param  {number} lat Latitude of point
+     * @param  {number} lng Longtitude of point
+     * @param  {number} res Resolution of hexagons to return
+     * @return {H3Index}    H3 index
+     * @throws {H3Error}    If input is invalid
      */
-    function latLngToCell(lat: number, lng: number, res: number): H3Index;
+    export function latLngToCell(lat: number, lng: number, res: number): H3Index;
     /**
      * Get the lat,lon center of a given hexagon
-     * @param h3Index - H3 index
-     * @returns Point as a [lat, lng] pair
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index
+     * @return {CoordPair}             Point as a [lat, lng] pair
+     * @throws {H3Error}               If input is invalid
      */
-    function cellToLatLng(h3Index: H3IndexInput): number[];
+    export function cellToLatLng(h3Index: H3IndexInput): CoordPair;
     /**
@@ -107,51 +83,66 @@ * Get the vertices of a given hexagon (or pentagon), as an array of [lat, lng]
      * function may return up to 10 vertices.
-     * @param h3Index - H3 index
-     * @param [formatAsGeoJson] - Whether to provide GeoJSON output: [lng, lat], closed loops
-     * @returns Array of [lat, lng] pairs
+     * @static
+     * @param  {H3Index} h3Index          H3 index
+     * @param {boolean} [formatAsGeoJson] Whether to provide GeoJSON output: [lng, lat], closed loops
+     * @return {CoordPair[]}              Array of [lat, lng] pairs
+     * @throws {H3Error}                  If input is invalid
      */
-    function cellToBoundary(h3Index: H3Index, formatAsGeoJson?: boolean): number[][];
+    export function cellToBoundary(h3Index: H3Index, formatAsGeoJson?: boolean): CoordPair[];
     /**
      * Get the parent of the given hexagon at a particular resolution
-     * @param h3Index - H3 index to get parent for
-     * @param res - Resolution of hexagon to return
-     * @returns H3 index of parent, or null for invalid input
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index to get parent for
+     * @param  {number} res       Resolution of hexagon to return
+     * @return {H3Index}          H3 index of parent, or null for invalid input
+     * @throws {H3Error}          If input is invalid
      */
-    function cellToParent(h3Index: H3IndexInput, res: number): H3Index;
+    export function cellToParent(h3Index: H3IndexInput, res: number): H3Index;
     /**
      * Get the children/descendents of the given hexagon at a particular resolution
-     * @param h3Index - H3 index to get children for
-     * @param res - Resolution of hexagons to return
-     * @returns H3 indexes of children, or empty array for invalid input
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index to get children for
+     * @param  {number} res       Resolution of hexagons to return
+     * @return {H3Index[]}        H3 indexes of children, or empty array for invalid input
+     * @throws {H3Error}          If resolution is invalid or output is too large for JS
      */
-    function cellToChildren(h3Index: H3IndexInput, res: number): H3Index[];
+    export function cellToChildren(h3Index: H3IndexInput, res: number): H3Index[];
     /**
      * Get the center child of the given hexagon at a particular resolution
-     * @param h3Index - H3 index to get center child for
-     * @param res - Resolution of hexagon to return
-     * @returns H3 index of child, or null for invalid input
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index to get center child for
+     * @param  {number} res       Resolution of hexagon to return
+     * @return {H3Index}          H3 index of child, or null for invalid input
+     * @throws {H3Error}          If resolution is invalid
      */
-    function cellToCenterChild(h3Index: H3IndexInput, res: number): H3Index;
+    export function cellToCenterChild(h3Index: H3IndexInput, res: number): H3Index;
     /**
      * Get all hexagons in a k-ring around a given center. The order of the hexagons is undefined.
-     * @param h3Index - H3 index of center hexagon
-     * @param ringSize - Radius of k-ring
-     * @returns H3 indexes for all hexagons in ring
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index of center hexagon
+     * @param  {number} ringSize  Radius of k-ring
+     * @return {H3Index[]}        H3 indexes for all hexagons in ring
+     * @throws {H3Error}          If input is invalid or output is too large for JS
      */
-    function gridDisk(h3Index: H3IndexInput, ringSize: number): H3Index[];
+    export function gridDisk(h3Index: H3IndexInput, ringSize: number): H3Index[];
     /**
      * Get all hexagons in a k-ring around a given center, in an array of arrays
      * ordered by distance from the origin. The order of the hexagons within each ring is undefined.
-     * @param h3Index - H3 index of center hexagon
-     * @param ringSize - Radius of k-ring
-     * @returns Array of arrays with H3 indexes for all hexagons each ring
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index of center hexagon
+     * @param  {number} ringSize  Radius of k-ring
+     * @return {H3Index[][]}      Array of arrays with H3 indexes for all hexagons each ring
+     * @throws {H3Error}          If input is invalid or output is too large for JS
      */
-    function gridDiskDistances(h3Index: H3IndexInput, ringSize: number): H3Index[][];
+    export function gridDiskDistances(h3Index: H3IndexInput, ringSize: number): H3Index[][];
     /**
      * Get all hexagons in a hollow hexagonal ring centered at origin with sides of a given length.
      * Unlike kRing, this function will throw an error if there is a pentagon anywhere in the ring.
-     * @param h3Index - H3 index of center hexagon
-     * @param ringSize - Radius of ring
-     * @returns H3 indexes for all hexagons in ring
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index of center hexagon
+     * @param  {number} ringSize  Radius of ring
+     * @return {H3Index[]}        H3 indexes for all hexagons in ring
+     * @throws {Error}            If the algorithm could not calculate the ring
+     * @throws {H3Error}          If input is invalid
      */
-    function gridRingUnsafe(h3Index: H3IndexInput, ringSize: number): H3Index[];
+    export function gridRingUnsafe(h3Index: H3IndexInput, ringSize: number): H3Index[];
     /**
@@ -163,9 +154,12 @@ * Get all hexagons with centers contained in a given polygon. The polygon
      * expected to be holes.
-     * @param coordinates - Array of loops, or a single loop
-     * @param res - Resolution of hexagons to return
-     * @param [isGeoJson] - Whether to expect GeoJson-style [lng, lat]
+     * @static
+     * @param  {number[][] | number[][][]} coordinates
+     *                                  Array of loops, or a single loop
+     * @param  {number} res             Resolution of hexagons to return
+     * @param  {boolean} [isGeoJson]    Whether to expect GeoJson-style [lng, lat]
      *                                  pairs instead of [lat, lng]
-     * @returns H3 indexes for all hexagons in polygon
+     * @return {H3Index[]}              H3 indexes for all hexagons in polygon
+     * @throws {H3Error}                If input is invalid or output is too large for JS
      */
-    function polygonToCells(coordinates: number[][] | number[][][], res: number, isGeoJson?: boolean): H3Index[];
+    export function polygonToCells(coordinates: number[][] | number[][][], res: number, isGeoJson?: boolean): H3Index[];
     /**
@@ -181,75 +175,96 @@ * Get the outlines of a set of H3 hexagons, returned in GeoJSON MultiPolygon
      * algorithm may produce unexpected or invalid polygons.
-     * @param h3Indexes - H3 indexes to get outlines for
-     * @param [formatAsGeoJson] - Whether to provide GeoJSON output:
-     *                                    [lng, lat], closed loops
-     * @returns MultiPolygon-style output.
+     *
+     * @static
+     * @param {H3IndexInput[]} h3Indexes  H3 indexes to get outlines for
+     * @param {boolean} [formatAsGeoJson] Whether to provide GeoJSON output: [lng, lat], closed loops
+     * @return {CoordPair[][][]}          MultiPolygon-style output.
+     * @throws {H3Error}                  If input is invalid
      */
-    function cellsToMultiPolygon(h3Indexes: H3IndexInput[], formatAsGeoJson?: boolean): number[][][][];
+    export function cellsToMultiPolygon(h3Indexes: H3IndexInput[], formatAsGeoJson?: boolean): CoordPair[][][];
     /**
      * Compact a set of hexagons of the same resolution into a set of hexagons across
      * multiple levels that represents the same area.
-     * @param h3Set - H3 indexes to compact
-     * @returns Compacted H3 indexes
+     * @static
+     * @param  {H3IndexInput[]} h3Set H3 indexes to compact
+     * @return {H3Index[]}       Compacted H3 indexes
+     * @throws {H3Error}         If the input is invalid (e.g. duplicate hexagons)
      */
-    function compactCells(h3Set: H3IndexInput[]): H3Index[];
+    export function compactCells(h3Set: H3IndexInput[]): H3Index[];
     /**
      * Uncompact a compacted set of hexagons to hexagons of the same resolution
-     * @param compactedSet - H3 indexes to uncompact
-     * @param res - The resolution to uncompact to
-     * @returns The uncompacted H3 indexes
+     * @static
+     * @param  {H3IndexInput[]} compactedSet H3 indexes to uncompact
+     * @param  {number}    res          The resolution to uncompact to
+     * @return {H3Index[]}              The uncompacted H3 indexes
+     * @throws {H3Error}                If the input is invalid (e.g. invalid resolution)
      */
-    function uncompactCells(compactedSet: H3IndexInput[], res: number): H3Index[];
+    export function uncompactCells(compactedSet: H3IndexInput[], res: number): H3Index[];
     /**
      * Whether two H3 indexes are neighbors (share an edge)
-     * @param origin - Origin hexagon index
-     * @param destination - Destination hexagon index
-     * @returns Whether the hexagons share an edge
+     * @static
+     * @param  {H3IndexInput} origin      Origin hexagon index
+     * @param  {H3IndexInput} destination Destination hexagon index
+     * @return {boolean}             Whether the hexagons share an edge
+     * @throws {H3Error}             If the input is invalid
      */
-    function areNeighborCells(origin: H3IndexInput, destination: H3IndexInput): boolean;
+    export function areNeighborCells(origin: H3IndexInput, destination: H3IndexInput): boolean;
     /**
      * Get an H3 index representing a unidirectional edge for a given origin and destination
-     * @param origin - Origin hexagon index
-     * @param destination - Destination hexagon index
-     * @returns H3 index of the edge, or null if no edge is shared
+     * @static
+     * @param  {H3IndexInput} origin      Origin hexagon index
+     * @param  {H3IndexInput} destination Destination hexagon index
+     * @return {H3Index}             H3 index of the edge, or null if no edge is shared
+     * @throws {H3Error}             If the input is invalid
      */
-    function cellsToDirectedEdge(origin: H3IndexInput, destination: H3IndexInput): H3Index;
+    export function cellsToDirectedEdge(origin: H3IndexInput, destination: H3IndexInput): H3Index;
     /**
      * Get the origin hexagon from an H3 index representing a unidirectional edge
-     * @param edgeIndex - H3 index of the edge
-     * @returns H3 index of the edge origin
+     * @static
+     * @param  {H3IndexInput} edgeIndex H3 index of the edge
+     * @return {H3Index}           H3 index of the edge origin
+     * @throws {H3Error}           If the input is invalid
      */
-    function getDirectedEdgeOrigin(edgeIndex: H3IndexInput): H3Index;
+    export function getDirectedEdgeOrigin(edgeIndex: H3IndexInput): H3Index;
     /**
      * Get the destination hexagon from an H3 index representing a unidirectional edge
-     * @param edgeIndex - H3 index of the edge
-     * @returns H3 index of the edge destination
+     * @static
+     * @param  {H3IndexInput} edgeIndex H3 index of the edge
+     * @return {H3Index}           H3 index of the edge destination
+     * @throws {H3Error}           If the input is invalid
      */
-    function getDirectedEdgeDestination(edgeIndex: H3IndexInput): H3Index;
+    export function getDirectedEdgeDestination(edgeIndex: H3IndexInput): H3Index;
     /**
      * Whether the input is a valid unidirectional edge
-     * @param edgeIndex - H3 index of the edge
-     * @returns Whether the index is valid
+     * @static
+     * @param  {H3IndexInput} edgeIndex H3 index of the edge
+     * @return {boolean}           Whether the index is valid
      */
-    function isValidDirectedEdge(edgeIndex: H3IndexInput): boolean;
+    export function isValidDirectedEdge(edgeIndex: H3IndexInput): boolean;
     /**
      * Get the [origin, destination] pair represented by a unidirectional edge
-     * @param edgeIndex - H3 index of the edge
-     * @returns [origin, destination] pair as H3 indexes
+     * @static
+     * @param  {H3IndexInput} edgeIndex H3 index of the edge
+     * @return {H3Index[]}         [origin, destination] pair as H3 indexes
+     * @throws {H3Error}           If the input is invalid
      */
-    function directedEdgeToCells(edgeIndex: H3IndexInput): H3Index[];
+    export function directedEdgeToCells(edgeIndex: H3IndexInput): H3Index[];
     /**
      * Get all of the unidirectional edges with the given H3 index as the origin (i.e. an edge to
      * every neighbor)
-     * @param h3Index - H3 index of the origin hexagon
-     * @returns List of unidirectional edges
+     * @static
+     * @param  {H3IndexInput} h3Index   H3 index of the origin hexagon
+     * @return {H3Index[]}         List of unidirectional edges
+     * @throws {H3Error}           If the input is invalid
      */
-    function originToDirectedEdges(h3Index: H3IndexInput): H3Index[];
+    export function originToDirectedEdges(h3Index: H3IndexInput): H3Index[];
     /**
      * 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.
-     * @param edgeIndex - H3 index of the edge
-     * @param [formatAsGeoJson] - Whether to provide GeoJSON output: [lng, lat]
-     * @returns Array of geo coordinate pairs
+     * @static
+     * @param  {H3IndexInput} edgeIndex        H3 index of the edge
+     * @param {boolean} [formatAsGeoJson] Whether to provide GeoJSON output: [lng, lat]
+     * @return {CoordPair[]}              Array of geo coordinate pairs
+     * @throws {H3Error}                  If the input is invalid
      */
-    function directedEdgeToBoundary(edgeIndex: H3IndexInput, formatAsGeoJson?: boolean): number[][];
+    export function directedEdgeToBoundary(edgeIndex: H3IndexInput, formatAsGeoJson?: boolean): CoordPair[];
     /**
@@ -259,7 +274,9 @@ * Get the grid distance between two hex indexes. This function may fail
      * on opposite sides of a pentagon.
-     * @param origin - Origin hexagon index
-     * @param destination - Destination hexagon index
-     * @returns Distance between hexagons
+     * @static
+     * @param  {H3IndexInput} origin      Origin hexagon index
+     * @param  {H3IndexInput} destination Destination hexagon index
+     * @return {number}          Distance between hexagons
+     * @throws {H3Error}         If input is invalid or the distance could not be calculated
      */
-    function gridDistance(origin: H3IndexInput, destination: H3IndexInput): number;
+    export function gridDistance(origin: H3IndexInput, destination: H3IndexInput): number;
     /**
@@ -280,7 +297,10 @@ * Given two H3 indexes, return the line of indexes between them (inclusive).
      *    Cartesian lines or great arcs.
-     * @param origin - Origin hexagon index
-     * @param destination - Destination hexagon index
-     * @returns H3 indexes connecting origin and destination
+     *
+     * @static
+     * @param  {H3IndexInput} origin      Origin hexagon index
+     * @param  {H3IndexInput} destination Destination hexagon index
+     * @return {H3Index[]}           H3 indexes connecting origin and destination
+     * @throws {H3Error}             If input is invalid or the line cannot be calculated
      */
-    function gridPathCells(origin: H3IndexInput, destination: H3IndexInput): H3Index[];
+    export function gridPathCells(origin: H3IndexInput, destination: H3IndexInput): H3Index[];
     /**
@@ -297,7 +317,9 @@ * Produces IJ coordinates for an H3 index anchored by an origin.
      * to be compatible across different versions of H3.
-     * @param origin - Origin H3 index
-     * @param destination - H3 index for which to find relative coordinates
-     * @returns Coordinates as an `{i, j}` pair
+     * @static
+     * @param  {H3IndexInput} origin      Origin H3 index
+     * @param  {H3IndexInput} destination H3 index for which to find relative coordinates
+     * @return {CoordIJ}             Coordinates as an `{i, j}` pair
+     * @throws {H3Error}             If the IJ coordinates cannot be calculated
      */
-    function cellToLocalIj(origin: H3IndexInput, destination: H3IndexInput): CoordIJ;
+    export function cellToLocalIj(origin: H3IndexInput, destination: H3IndexInput): CoordIJ;
     /**
@@ -314,69 +336,88 @@ * Produces an H3 index for IJ coordinates anchored by an origin.
      * to be compatible across different versions of H3.
-     * @param origin - Origin H3 index
-     * @param coords - Coordinates as an `{i, j}` pair
-     * @returns H3 index at the relative coordinates
+     * @static
+     * @param  {H3IndexInput} origin     Origin H3 index
+     * @param  {CoordIJ} coords     Coordinates as an `{i, j}` pair
+     * @return {H3Index}            H3 index at the relative coordinates
+     * @throws {H3Error}            If the H3 index cannot be calculated
      */
-    function localIjToCell(origin: H3IndexInput, coords: CoordIJ): H3Index;
+    export function localIjToCell(origin: H3IndexInput, coords: CoordIJ): H3Index;
     /**
      * Great circle distance between two geo points. This is not specific to H3,
      * but is implemented in the library and provided here as a convenience.
-     * @param latLng1 - Origin coordinate as [lat, lng]
-     * @param latLng2 - Destination coordinate as [lat, lng]
-     * @param unit - Distance unit (either UNITS.m, UNITS.km, or UNITS.rads)
-     * @returns Great circle distance
+     * @static
+     * @param  {number[]} latLng1 Origin coordinate as [lat, lng]
+     * @param  {number[]} latLng2 Destination coordinate as [lat, lng]
+     * @param  {string}   unit    Distance unit (either UNITS.m, UNITS.km, or UNITS.rads)
+     * @return {number}           Great circle distance
+     * @throws {H3Error}          If the unit is invalid
      */
-    function greatCircleDistance(latLng1: number[], latLng2: number[], unit: string): number;
+    export function greatCircleDistance(latLng1: number[], latLng2: number[], unit: string): number;
     /**
      * Exact area of a given cell
-     * @param h3Index - H3 index of the hexagon to measure
-     * @param unit - Distance unit (either UNITS.m2, UNITS.km2, or UNITS.rads2)
-     * @returns Cell area
+     * @static
+     * @param  {H3Index} h3Index  H3 index of the hexagon to measure
+     * @param  {string}  unit     Distance unit (either UNITS.m2, UNITS.km2, or UNITS.rads2)
+     * @return {number}           Cell area
+     * @throws {H3Error}          If the input is invalid
      */
-    function cellArea(h3Index: H3Index, unit: string): number;
+    export function cellArea(h3Index: H3Index, unit: string): number;
     /**
-     * Exact length of a given unidirectional edge
-     * @param edge - H3 index of the edge to measure
-     * @param unit - Distance unit (either UNITS.m, UNITS.km, or UNITS.rads)
-     * @returns Cell area
+     * Calculate length of a given unidirectional edge
+     * @static
+     * @param  {H3Index} edge     H3 index of the edge to measure
+     * @param  {string}  unit     Distance unit (either UNITS.m, UNITS.km, or UNITS.rads)
+     * @return {number}           Cell area
+     * @throws {H3Error}          If the input is invalid
      */
-    function exactEdgeLength(edge: H3Index, unit: string): number;
+    export function edgeLength(edge: H3Index, unit: string): number;
     /**
      * Average hexagon area at a given resolution
-     * @param res - Hexagon resolution
-     * @param unit - Area unit (either UNITS.m2, UNITS.km2, or UNITS.rads2)
-     * @returns Average area
+     * @static
+     * @param  {number} res  Hexagon resolution
+     * @param  {string} unit Area unit (either UNITS.m2, UNITS.km2, or UNITS.rads2)
+     * @return {number}      Average area
+     * @throws {H3Error}     If the input is invalid
      */
-    function getHexagonAreaAvg(res: number, unit: string): number;
+    export function getHexagonAreaAvg(res: number, unit: string): number;
     /**
      * Average hexagon edge length at a given resolution
-     * @param res - Hexagon resolution
-     * @param unit - Distance unit (either UNITS.m, UNITS.km, or UNITS.rads)
-     * @returns Average edge length
+     * @static
+     * @param  {number} res  Hexagon resolution
+     * @param  {string} unit Distance unit (either UNITS.m, UNITS.km, or UNITS.rads)
+     * @return {number}      Average edge length
+     * @throws {H3Error}     If the input is invalid
      */
-    function getHexagonEdgeLengthAvg(res: number, unit: string): number;
+    export function getHexagonEdgeLengthAvg(res: number, unit: string): number;
     /**
      * Find the index for a vertex of a cell.
-     * @param h3Index - Cell to find the vertex for
-     * @param vertexNum - Number (index) of the vertex to calculate
-     * @returns Vertex index
+     * @static
+     * @param {H3IndexInput} h3Index     Cell to find the vertex for
+     * @param {number} vertexNum         Number (index) of the vertex to calculate
+     * @return {H3Index}     Vertex index
+     * @throws {H3Error}     If the input is invalid
      */
-    function cellToVertex(h3Index: H3IndexInput, vertexNum: number): H3Index;
+    export function cellToVertex(h3Index: H3IndexInput, vertexNum: number): H3Index;
     /**
      * Find the indexes for all vertexes of a cell.
-     * @param h3Index - Cell to find all vertexes for
-     * @returns All vertex indexes of this cell
+     * @static
+     * @param {H3IndexInput} h3Index     Cell to find all vertexes for
+     * @return {H3Index[]}   All vertex indexes of this cell
+     * @throws {H3Error}     If the input is invalid
      */
-    function cellToVertexes(h3Index: H3IndexInput): H3Index[];
+    export function cellToVertexes(h3Index: H3IndexInput): H3Index[];
     /**
      * Get the lat, lng of a given vertex
-     * @param h3Index - A vertex index
-     * @returns Latitude, longitude coordinates of the vertex
+     * @static
+     * @param {H3IndexInput} h3Index A vertex index
+     * @returns {CoordPair}          Latitude, longitude coordinates of the vertex
+     * @throws {H3Error}             If the input is invalid
      */
-    function vertexToLatLng(h3Index: H3IndexInput): number[];
+    export function vertexToLatLng(h3Index: H3IndexInput): CoordPair;
     /**
      * Returns true if the input is a valid vertex index.
-     * @param h3Index - An index to test for being a vertex index
-     * @returns True if the index represents a vertex
+     * @static
+     * @param {H3IndexInput} h3Index An index to test for being a vertex index
+     * @returns {boolean} True if the index represents a vertex
      */
-    function isValidVertex(h3Index: H3IndexInput): boolean;
+    export function isValidVertex(h3Index: H3IndexInput): boolean;
     /**
@@ -386,6 +427,8 @@ * The total count of hexagons in the world at a given resolution. Note that above
      * so consumers should use caution when applying further operations to the output.
-     * @param res - Hexagon resolution
-     * @returns Count
+     * @static
+     * @param  {number} res  Hexagon resolution
+     * @return {number}      Count
+     * @throws {H3Error}     If the resolution is invalid
      */
-    function getNumCells(res: number): number;
+    export function getNumCells(res: number): number;
     /**
@@ -395,25 +438,68 @@ * Get all H3 indexes at resolution 0. As every index at every resolution > 0 is
      * over H3 indexes at any resolution.
-     * @returns All H3 indexes at res 0
+     * @static
+     * @return {H3Index[]}  All H3 indexes at res 0
      */
-    function getRes0Cells(): H3Index[];
+    export function getRes0Cells(): H3Index[];
     /**
      * Get the twelve pentagon indexes at a given resolution.
-     * @param res - Hexagon resolution
-     * @returns All H3 pentagon indexes at res
+     * @static
+     * @param  {number} res  Hexagon resolution
+     * @return {H3Index[]}   All H3 pentagon indexes at res
+     * @throws {H3Error}     If the resolution is invalid
      */
-    function getPentagons(res: number): H3Index[];
+    export function getPentagons(res: number): H3Index[];
     /**
      * Convert degrees to radians
-     * @param deg - Value in degrees
-     * @returns Value in radians
+     * @static
+     * @param  {number} deg Value in degrees
+     * @return {number}     Value in radians
      */
-    function degsToRads(deg: number): number;
+    export function degsToRads(deg: number): number;
     /**
      * Convert radians to degrees
-     * @param rad - Value in radians
-     * @returns Value in degrees
+     * @static
+     * @param  {number} rad Value in radians
+     * @return {number}     Value in degrees
      */
-    function radsToDegs(rad: number): number;
+    export function radsToDegs(rad: number): number;
+    export namespace UNITS {
+        const m: string;
+        const m2: string;
+        const km: string;
+        const km2: string;
+        const rads: string;
+        const rads2: string;
+    }
+    /**
+     * 64-bit hexidecimal string representation of an H3 index
+     */
+    export type H3Index = string;
+    /**
+     * 64-bit hexidecimal string representation of an H3 index,
+     * or two 32-bit integers in little endian order in an array.
+     */
+    export type H3IndexInput = string | number[];
+    /**
+     * Coordinates as an `{i, j}` pair
+     */
+    export type CoordIJ = {
+        i: number;
+        j: number;
+    };
+    /**
+     * 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).
+     */
+    export type H3Error = {
+        message: string;
+        code: number;
+    };
+    /**
+     * Pair of lat,lng coordinates (or lng,lat if GeoJSON output is specified)
+     */
+    export type CoordPair = [number,number];
+    /**
+     * Pair of lower,upper 32-bit ints representing a 64-bit value
+     */
+    export type SplitLong = [number,number];
 }
-
-

lib/bindings.js

@@ -31,2 +31,3 @@ /*
 // before new functions added here will be available.
+/** @type {([string, string] | [string, string | null, string[]])[]} */
 export default [
@@ -91,5 +92,5 @@ // The size functions are inserted via build/sizes.h
     ['cellAreaRads2', H3_ERROR, [H3_LOWER, H3_UPPER, POINTER]],
-    ['exactEdgeLengthM', H3_ERROR, [H3_LOWER, H3_UPPER, POINTER]],
-    ['exactEdgeLengthKm', H3_ERROR, [H3_LOWER, H3_UPPER, POINTER]],
-    ['exactEdgeLengthRads', H3_ERROR, [H3_LOWER, H3_UPPER, POINTER]],
+    ['edgeLengthM', H3_ERROR, [H3_LOWER, H3_UPPER, POINTER]],
+    ['edgeLengthKm', H3_ERROR, [H3_LOWER, H3_UPPER, POINTER]],
+    ['edgeLengthRads', H3_ERROR, [H3_LOWER, H3_UPPER, POINTER]],
     ['getNumCells', H3_ERROR, [RESOLUTION, POINTER]],
@@ -96,0 +97,0 @@ ['getRes0Cells', H3_ERROR, [POINTER]],

lib/errors.js

@@ -62,2 +62,3 @@ /*
 export const E_ARRAY_LENGTH = 1001;
+export const E_NULL_INDEX = 1002;
 
@@ -71,3 +72,4 @@ /**
     [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'
 };
@@ -82,7 +84,7 @@
  * @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
@@ -94,2 +96,3 @@ const err = new Error(
     );
+    // @ts-expect-error - TS doesn't like extending Error
     err.code = errCode;
@@ -103,3 +106,3 @@ return err;
  * @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}
@@ -117,3 +120,3 @@ */
  * @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}
@@ -130,3 +133,3 @@ */
  * @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)
@@ -133,0 +136,0 @@ */

lib/h3core.js

@@ -29,5 +29,11 @@ /*
     E_UNKNOWN_UNIT,
-    E_ARRAY_LENGTH
+    E_ARRAY_LENGTH,
+    E_NULL_INDEX
 } from './errors';
 
+/**
+ * Map of C-defined functions
+ * @type {any}
+ * @private
+ */
 const H3 = {};
@@ -81,3 +87,2 @@
  * @typedef CoordIJ
- * @type {Object}
  * @property {number} i
@@ -88,7 +93,6 @@ * @property {number} j
 /**
- * Custom JS Error with an attached error code. Error codes come from the
+ * 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).
  * @static
  * @typedef H3Error
- * @extends Error
  * @property {string} message
@@ -98,2 +102,14 @@ * @property {number} code
 
+/**
+ * Pair of lat,lng coordinates (or lng,lat if GeoJSON output is specified)
+ * @static
+ * @typedef {number[]} CoordPair
+ */
+
+/**
+ * Pair of lower,upper 32-bit ints representing a 64-bit value
+ * @static
+ * @typedef {number[]} SplitLong
+ */
+
 // ----------------------------------------------------------------------------
@@ -105,3 +121,2 @@ // Unit constants
  * @static
- * @type {Object}
  * @property {string} m
@@ -130,2 +145,3 @@ * @property {string} m2
  * @param  {unknown} res Value to validate
+ * @return {number}      Valid res
  * @throws {H3Error}     If invalid
@@ -137,4 +153,17 @@ */
     }
+    return res;
 }
 
+/**
+ * Assert H3 index output, throwing an error if null
+ * @private
+ * @param {H3Index | null} h3Index    Index to validate
+ * @return {H3Index}
+ * @throws {H3Error}     If invalid
+ */
+function validateH3Index(h3Index) {
+    if (!h3Index) throw JSBindingError(E_NULL_INDEX);
+    return h3Index;
+}
+
 const MAX_JS_ARRAY_LENGTH = Math.pow(2, 32) - 1;
@@ -149,2 +178,3 @@
  * @param  {number} length  Length to validate
+ * @return {number}         Valid array length
  * @throws {H3Error}        If invalid
@@ -156,2 +186,3 @@ */
     }
+    return length;
 }
@@ -164,3 +195,3 @@
  * @param  {H3IndexInput} h3Index  H3 index to check
- * @return {number[]}         A two-element array with 32 lower bits and 32 upper bits
+ * @return {SplitLong}             A two-element array with 32 lower bits and 32 upper bits
  */
@@ -233,6 +264,6 @@ export function h3IndexToSplitLong(h3Index) {
  * @private
- * @param  {Array[]} polygonArray Polygon, as an array of coordinate pairs
- * @param  {number}  geoLoop      C pointer to a GeoLoop struct
- * @param  {boolean} isGeoJson    Whether coordinates are in [lng, lat] order per GeoJSON spec
- * @return {number}               C pointer to populated GeoLoop struct
+ * @param  {number[][]} polygonArray  Polygon, as an array of coordinate pairs
+ * @param  {number}  geoLoop          C pointer to a GeoLoop struct
+ * @param  {boolean} isGeoJson        Whether coordinates are in [lng, lat] order per GeoJSON spec
+ * @return {number}                   C pointer to populated GeoLoop struct
  */
@@ -258,5 +289,5 @@ function polygonArrayToGeoLoop(polygonArray, geoLoop, isGeoJson) {
  * @private
- * @param  {Array[]} coordinates  Array of polygons, each an array of coordinate pairs
- * @param  {boolean} isGeoJson    Whether coordinates are in [lng, lat] order per GeoJSON spec
- * @return {number}               C pointer to populated GeoPolygon struct
+ * @param  {number[][][]} coordinates Array of polygons, each an array of coordinate pairs
+ * @param  {boolean} isGeoJson        Whether coordinates are in [lng, lat] order per GeoJSON spec
+ * @return {number}                   C pointer to populated GeoPolygon struct
  */
@@ -289,3 +320,4 @@ function coordinatesToGeoPolygon(coordinates, isGeoJson) {
  * @private
- * @return {number} geoPolygon C pointer to populated GeoPolygon struct
+ * @param {number} geoPolygon     C pointer to GeoPolygon struct
+ * @return {void}
  */
@@ -319,3 +351,3 @@ function destroyGeoPolygon(geoPolygon) {
  *                            reading an array
- * @return {H3Index}          H3 index, or null if index was invalid
+ * @return {H3Index | null}   H3 index, or null if index was invalid
  */
@@ -433,2 +465,8 @@ function readH3IndexFromPointer(cAddress, offset = 0) {
 
+/**
+ * Read a single lat or lng value
+ * @private
+ * @param  {number} cAddress Pointer to C value
+ * @return {number}
+ */
 function readSingleCoord(cAddress) {
@@ -442,3 +480,3 @@ return radsToDegs(C.getValue(cAddress, 'double'));
  * @param  {number} cAddress    Pointer to C struct
- * @return {number[]}           [lat, lng] pair
+ * @return {CoordPair}          [lat, lng] pair
  */
@@ -453,3 +491,3 @@ function readLatLng(cAddress) {
  * @param  {number} cAddress    Pointer to C struct
- * @return {number[]}           [lng, lat] pair
+ * @return {CoordPair}          [lng, lat] pair
  */
@@ -463,6 +501,6 @@ function readLatLngGeoJson(cAddress) {
  * @private
- * @param {number}  cellBoundary     C pointer to CellBoundary struct
- * @param {boolean} geoJsonCoords   Whether to provide GeoJSON coordinate order: [lng, lat]
- * @param {boolean} closedLoop      Whether to close the loop
- * @return {Array[]}                Array of geo coordinate pairs
+ * @param {number}  cellBoundary       C pointer to CellBoundary struct
+ * @param {boolean} [geoJsonCoords]    Whether to provide GeoJSON coordinate order: [lng, lat]
+ * @param {boolean} [closedLoop]       Whether to close the loop
+ * @return {CoordPair[]}               Array of geo coordinate pairs
  */
@@ -490,5 +528,5 @@ function readCellBoundary(cellBoundary, geoJsonCoords, closedLoop) {
  * @private
- * @param {number}  polygon         C pointer to LinkedGeoPolygon struct
- * @param {boolean} formatAsGeoJson Whether to provide GeoJSON output: [lng, lat], closed loops
- * @return {number[][][][]}         MultiPolygon-style output.
+ * @param {number}  polygon           C pointer to LinkedGeoPolygon struct
+ * @param {boolean} [formatAsGeoJson] Whether to provide GeoJSON output: [lng, lat], closed loops
+ * @return {CoordPair[][][]}          MultiPolygon-style output.
  */
@@ -545,4 +583,5 @@ function readMultiPolygon(polygon, formatAsGeoJson) {
  * @private
- * @param  {number} cAddress    Pointer to C struct
- * @return {CoordIJ}            {i, j} pair
+ * @param  {number} cAddress    Pointer to C memory
+ * @param {CoordIJ} ij          {i,j} pair to store
+ * @return {void}
  */
@@ -679,3 +718,3 @@ function storeCoordIJ(cAddress, {i, j}) {
         throwIfError(H3.latLngToCell(latLng, res, h3Index));
-        return readH3IndexFromPointer(h3Index);
+        return validateH3Index(readH3IndexFromPointer(h3Index));
     } finally {
@@ -691,4 +730,4 @@ C._free(h3Index);
  * @param  {H3IndexInput} h3Index  H3 index
- * @return {number[]}       Point as a [lat, lng] pair
- * @throws {H3Error}        If input is invalid
+ * @return {CoordPair}             Point as a [lat, lng] pair
+ * @throws {H3Error}               If input is invalid
  */
@@ -713,3 +752,3 @@ export function cellToLatLng(h3Index) {
  * @param {boolean} [formatAsGeoJson] Whether to provide GeoJSON output: [lng, lat], closed loops
- * @return {number[][]}               Array of [lat, lng] pairs
+ * @return {CoordPair[]}              Array of [lat, lng] pairs
  * @throws {H3Error}                  If input is invalid
@@ -744,3 +783,3 @@ */
         throwIfError(H3.cellToParent(lower, upper, res, parent));
-        return readH3IndexFromPointer(parent);
+        return validateH3Index(readH3IndexFromPointer(parent));
     } finally {
@@ -769,4 +808,3 @@ C._free(parent);
         throwIfError(H3.cellToChildrenSize(lower, upper, res, countPtr));
-        const count = readInt64AsDoubleFromPointer(countPtr);
-        validateArrayLength(count);
+        const count = validateArrayLength(readInt64AsDoubleFromPointer(countPtr));
         const hexagons = C._calloc(count, SZ_H3INDEX);
@@ -797,3 +835,3 @@ try {
         throwIfError(H3.cellToCenterChild(lower, upper, res, centerChild));
-        return readH3IndexFromPointer(centerChild);
+        return validateH3Index(readH3IndexFromPointer(centerChild));
     } finally {
@@ -817,4 +855,3 @@ C._free(centerChild);
         throwIfError(H3.maxGridDiskSize(ringSize, countPtr));
-        const count = readInt64AsDoubleFromPointer(countPtr);
-        validateArrayLength(count);
+        const count = validateArrayLength(readInt64AsDoubleFromPointer(countPtr));
         const hexagons = C._calloc(count, SZ_H3INDEX);
@@ -846,4 +883,3 @@ try {
         throwIfError(H3.maxGridDiskSize(ringSize, countPtr));
-        const count = readInt64AsDoubleFromPointer(countPtr);
-        validateArrayLength(count);
+        const count = validateArrayLength(readInt64AsDoubleFromPointer(countPtr));
         const kRings = C._calloc(count, SZ_H3INDEX);
@@ -853,3 +889,7 @@ const distances = C._calloc(count, SZ_INT);
             throwIfError(H3.gridDiskDistances(lower, upper, ringSize, kRings, distances));
-            // Create an array of empty arrays to hold the output
+            /**
+             * An array of empty arrays to hold the output
+             * @type {string[][]}
+             * @private
+             */
             const out = [];
@@ -922,11 +962,12 @@ for (let i = 0; i < ringSize + 1; i++) {
     // Wrap to expected format if a single loop is provided
-    if (typeof coordinates[0][0] === 'number') {
-        coordinates = [coordinates];
-    }
-    const geoPolygon = coordinatesToGeoPolygon(coordinates, isGeoJson);
+    const polygon = typeof coordinates[0][0] === 'number' ? [coordinates] : coordinates;
+    const geoPolygon = coordinatesToGeoPolygon(
+        // @ts-expect-error - There's no way to convince TS that polygon is now number[][][]
+        polygon,
+        isGeoJson
+    );
     const countPtr = C._malloc(SZ_INT64);
     try {
         throwIfError(H3.maxPolygonToCellsSize(geoPolygon, res, 0, countPtr));
-        const count = readInt64AsDoubleFromPointer(countPtr);
-        validateArrayLength(count);
+        const count = validateArrayLength(readInt64AsDoubleFromPointer(countPtr));
         const hexagons = C._calloc(count, SZ_H3INDEX);
@@ -957,6 +998,5 @@ try {
  * @static
- * @param {H3IndexInput[]} h3Indexes       H3 indexes to get outlines for
- * @param {boolean} [formatAsGeoJson] Whether to provide GeoJSON output:
- *                                    [lng, lat], closed loops
- * @return {number[][][][]}           MultiPolygon-style output.
+ * @param {H3IndexInput[]} h3Indexes  H3 indexes to get outlines for
+ * @param {boolean} [formatAsGeoJson] Whether to provide GeoJSON output: [lng, lat], closed loops
+ * @return {CoordPair[][][]}          MultiPolygon-style output.
  * @throws {H3Error}                  If input is invalid
@@ -1036,4 +1076,5 @@ */
         );
-        const uncompactCellSize = readInt64AsDoubleFromPointer(uncompactCellSizePtr);
-        validateArrayLength(uncompactCellSize);
+        const uncompactCellSize = validateArrayLength(
+            readInt64AsDoubleFromPointer(uncompactCellSizePtr)
+        );
         // Allocate memory for uncompacted hexagons
@@ -1100,3 +1141,3 @@ const uncompactedSet = C._calloc(uncompactCellSize, SZ_H3INDEX);
         throwIfError(H3.cellsToDirectedEdge(oLower, oUpper, dLower, dUpper, h3Index));
-        return readH3IndexFromPointer(h3Index);
+        return validateH3Index(readH3IndexFromPointer(h3Index));
     } finally {
@@ -1119,3 +1160,3 @@ C._free(h3Index);
         throwIfError(H3.getDirectedEdgeOrigin(lower, upper, h3Index));
-        return readH3IndexFromPointer(h3Index);
+        return validateH3Index(readH3IndexFromPointer(h3Index));
     } finally {
@@ -1138,3 +1179,3 @@ C._free(h3Index);
         throwIfError(H3.getDirectedEdgeDestination(lower, upper, h3Index));
-        return readH3IndexFromPointer(h3Index);
+        return validateH3Index(readH3IndexFromPointer(h3Index));
     } finally {
@@ -1201,3 +1242,3 @@ C._free(h3Index);
  * @param {boolean} [formatAsGeoJson] Whether to provide GeoJSON output: [lng, lat]
- * @return {number[][]}               Array of geo coordinate pairs
+ * @return {CoordPair[]}              Array of geo coordinate pairs
  * @throws {H3Error}                  If the input is invalid
@@ -1266,4 +1307,3 @@ */
         throwIfError(H3.gridPathCellsSize(oLower, oUpper, dLower, dUpper, countPtr));
-        const count = readInt64AsDoubleFromPointer(countPtr);
-        validateArrayLength(count);
+        const count = validateArrayLength(readInt64AsDoubleFromPointer(countPtr));
         const hexagons = C._calloc(count, SZ_H3INDEX);
@@ -1347,3 +1387,3 @@ try {
         );
-        return readH3IndexFromPointer(out);
+        return validateH3Index(readH3IndexFromPointer(out));
     } finally {
@@ -1425,3 +1465,3 @@ C._free(ij);
 /**
- * Exact length of a given unidirectional edge
+ * Calculate length of a given unidirectional edge
  * @static
@@ -1433,3 +1473,3 @@ * @param  {H3Index} edge     H3 index of the edge to measure
  */
-export function exactEdgeLength(edge, unit) {
+export function edgeLength(edge, unit) {
     const [lower, upper] = h3IndexToSplitLong(edge);
@@ -1440,9 +1480,9 @@ const out = C._malloc(SZ_DBL);
             case UNITS.m:
-                throwIfError(H3.exactEdgeLengthM(lower, upper, out));
+                throwIfError(H3.edgeLengthM(lower, upper, out));
                 break;
             case UNITS.km:
-                throwIfError(H3.exactEdgeLengthKm(lower, upper, out));
+                throwIfError(H3.edgeLengthKm(lower, upper, out));
                 break;
             case UNITS.rads:
-                throwIfError(H3.exactEdgeLengthRads(lower, upper, out));
+                throwIfError(H3.edgeLengthRads(lower, upper, out));
                 break;
@@ -1530,3 +1570,3 @@ default:
         throwIfError(H3.cellToVertex(lower, upper, vertexNum, vertexIndex));
-        return readH3IndexFromPointer(vertexIndex);
+        return validateH3Index(readH3IndexFromPointer(vertexIndex));
     } finally {
@@ -1560,4 +1600,4 @@ C._free(vertexIndex);
  * @param {H3IndexInput} h3Index A vertex index
- * @returns {number[]} Latitude, longitude coordinates of the vertex
- * @throws {H3Error}     If the input is invalid
+ * @returns {CoordPair}          Latitude, longitude coordinates of the vertex
+ * @throws {H3Error}             If the input is invalid
  */
@@ -1564,0 +1604,0 @@ export function vertexToLatLng(h3Index) {

lib/legacy-mapping.js

@@ -54,3 +54,3 @@ /*
     cellArea: 'cellArea',
-    exactEdgeLength: 'exactEdgeLength',
+    exactEdgeLength: 'edgeLength',
     hexArea: 'getHexagonAreaAvg',
@@ -57,0 +57,0 @@ edgeLength: 'getHexagonEdgeLengthAvg',

package.json

 {
   "name": "h3-js",
-  "version": "4.0.0-rc3",
+  "version": "4.0.0-rc4",
   "description": "Pure-Javascript version of the H3 library, a hexagon-based geographic grid system",
@@ -33,3 +33,3 @@ "author": "Nick Rabinowitz <[e-mail]>",
     "build-docs": "jsdoc2md --no-cache --global-index-format grouped --partial doc-files/scope.hbs --helper ./doc-files/insert-version.js --separators --template doc-files/README.tmpl.md lib/h3core.js lib/errors.js > README.md",
-    "build-tsd-core": "jsdoc -t node_modules/tsd-jsdoc/dist -d console lib/h3core.js | sed 's/\"h3\"/\"h3-js\"/g' > dist/types.d.ts",
+    "build-tsd-core": "tsc lib/h3core.js --noResolve --skipLibCheck --allowJs --declaration --emitDeclarationOnly --outFile dist/types.d.ts && bash scripts/postprocess-types.sh",
     "build-tsd-legacy": "node scripts/build-legacy-types.js",
@@ -56,5 +56,5 @@ "build-tsd": "yarn build-tsd-core && yarn build-tsd-legacy",
     "check-docs": "yarn build-docs && git diff --exit-code",
-    "check-tsd": "yarn build-tsd && tsc --strict --noEmit dist/types.d.ts",
-    "lint": "eslint lib* test/*",
-    "test": "yarn lint && yarn test-fast && yarn test-legacy",
+    "check-tsd": "yarn build-tsd && tsc --strict --noEmit dist/types.d.ts && tsc --strict --noEmit dist/legacy-types.d.ts",
+    "lint": "tsc --noEmit && eslint lib* test/*",
+    "test": "yarn lint && yarn && yarn test-fast && yarn test-legacy",
     "test-fast": "yarn test-raw | faucet",
@@ -89,4 +89,3 @@ "test-raw": "yarn rollup-test && node dist/test.js",
     "tape": "^5.5.3",
-    "tsd-jsdoc": "^2.5.0",
-    "typescript": "^3.6.3"
+    "typescript": "^4.7.4"
   },
@@ -93,0 +92,0 @@ "resolutions": {

README.md

@@ -101,4 +101,4 @@ <!-- the README is generated from a template, please edit doc-files/README.md.tmpl -->
 * [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>
@@ -112,4 +112,4 @@ * [.isValidCell(h3Index)](#module_h3.isValidCell) ⇒ <code>boolean</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>
@@ -122,3 +122,3 @@ * [.cellToChildren(h3Index, res)](#module_h3.cellToChildren) ⇒ <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>
@@ -133,3 +133,3 @@ * [.uncompactCells(compactedSet, res)](#module_h3.uncompactCells) ⇒ <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>
@@ -141,3 +141,3 @@ * [.gridPathCells(origin, destination)](#module_h3.gridPathCells) ⇒ <code>Array.&lt;H3Index&gt;</code>
     * [.cellArea(h3Index, unit)](#module_h3.cellArea) ⇒ <code>number</code>
-    * [.exactEdgeLength(edge, unit)](#module_h3.exactEdgeLength) ⇒ <code>number</code>
+    * [.edgeLength(edge, unit)](#module_h3.edgeLength) ⇒ <code>number</code>
     * [.getHexagonAreaAvg(res, unit)](#module_h3.getHexagonAreaAvg) ⇒ <code>number</code>
@@ -147,3 +147,3 @@ * [.getHexagonEdgeLengthAvg(res, unit)](#module_h3.getHexagonEdgeLengthAvg) ⇒ <code>number</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>
@@ -157,4 +157,6 @@ * [.getNumCells(res)](#module_h3.getNumCells) ⇒ <code>number</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>
 
@@ -166,3 +168,3 @@
 
-### h3.UNITS : <code>Object</code>
+### h3.UNITS
 Length/Area units
@@ -186,6 +188,6 @@
 
-### 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  
 
@@ -326,6 +328,6 @@ | Param | Type | Description |
 
-### 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**:
@@ -345,3 +347,3 @@
 
-### 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]
@@ -351,3 +353,3 @@ points. For pentagons and hexagons on the edge of an icosahedron face, this
 
-**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**:
@@ -509,3 +511,3 @@
 
-### 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
@@ -521,3 +523,3 @@ format (an array of polygons, each with an array of loops, each an array of
 
-**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**:
@@ -531,3 +533,3 @@
 | 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 |
 
@@ -702,7 +704,7 @@
 
-### 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**:
@@ -870,6 +872,6 @@
 
-<a name="module_h3.exactEdgeLength"></a>
+<a name="module_h3.edgeLength"></a>
 
-### h3.exactEdgeLength(edge, unit) ⇒ <code>number</code>
-Exact length of a given unidirectional edge
+### h3.edgeLength(edge, unit) ⇒ <code>number</code>
+Calculate length of a given unidirectional edge
 
@@ -967,6 +969,6 @@ **Returns**: <code>number</code> - Cell area
 
-### 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**:
@@ -1094,3 +1096,3 @@
 
-### h3.CoordIJ : <code>Object</code>
+### h3.CoordIJ
 Coordinates as an `{i, j}` pair
@@ -1110,7 +1112,6 @@
 
-### 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**
@@ -1126,3 +1127,19 @@
 
+<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
+
+
+* * *
+
+
 ## Legacy API
@@ -1129,0 +1146,0 @@

No alert changes

Improved metrics

Total package byte prevSize

5593341

increased by0.87%

Dev dependency count

15

decreased by-6.25%

Number of package files

33

increased by3.13%

Lines of code

57885

increased by1.23%

Number of lines in readme file

1224

increased by1.41%

No dependency changes