Merge pull request #16 from uber/upgrade-deps-types

* Adds TS type definitions
* Cleans up tests for h3-js@3.7.1
* Upgrades dev dependencies in yarn.lock

Author: nrabinowitz

.travis.yml

@@ -1,14 +1,12 @@
 language: node_js
 node_js:
-  - '6'
+  - '10'
+  - '12'
+  - '14'
 before_script:
   - yarn run dist-test
 script:
-  - yarn lint
-  - yarn run test-es6
-  - yarn run test-dist
-  - yarn run check-prettier
-  - yarn run check-docs
+  - yarn test-ci
   - yarn cover
 after_success:
   - npm install -g coveralls

README.md

@@ -142,7 +142,7 @@ in a separate `Polygon` feature with optional properties.
 | Param | Type | Description |
 | --- | --- | --- |
 | hexagons | <code>Array.&lt;String&gt;</code> | Hexagon addresses |
-| [getProperties] | <code>function</code> | Optional function returning properties                                    for a hexagon: f(hexAddress) => Object |
+| [getProperties] | <code>function</code> | Optional function returning properties                                    for a hexagon: f(h3Index) => Object |
 
 
 * * *

package.json

@@ -15,21 +15,25 @@
   },
   "main": "index.js",
   "es2015": "lib/geojson2h3.js",
+  "types": "dist/types.d.ts",
   "dependencies": {
     "h3-js": "^3.6.1"
   },
   "devDependencies": {
+    "@types/geojson": "^7946.0.7",
     "benchmark": "^2.1.4",
     "buble": "^0.19.3",
     "eslint": "^4.19.1",
     "eslint-config-prettier": "^2.9.0",
     "eslint-config-uber-es2015": "^3.1.2",
     "eslint-plugin-prettier": "^2.6.0",
-    "faucet": "0.0.1",
+    "faucet": "^0.0.1",
     "istanbul": "^0.4.3",
-    "jsdoc-to-markdown": "^4.0.1",
+    "jsdoc": "^3.6.6",
+    "jsdoc-to-markdown": "^6.0.1",
     "prettier": "^1.12.1",
-    "tape": "^4.8.0"
+    "tape": "^4.8.0",
+    "typescript": "^4.1.5"
   },
   "scripts": {
     "lint": "eslint src test",
@@ -38,19 +42,25 @@
     "test-raw": "node test/index.js",
     "test-es6": "yarn test-raw | faucet",
     "test-dist": "node dist/test/index.js | faucet",
+    "test-ci": "yarn lint && yarn run test-es6 && yarn run test-dist && yarn run check-prettier && yarn run check-docs && yarn run check-types",
     "check-prettier": "yarn prettier && git diff --exit-code",
+    "check-types": "tsc --strict --noEmit types.d.ts",
     "check-docs": "yarn build-docs && git diff --exit-code",
-    "build-docs": "jsdoc2md --global-index-format grouped --separators --template doc-files/README.md.tmpl src/geojson2h3.js > README.md",
-    "dist": "yarn dist-clean && buble -i src -o dist/src",
+    "build-docs": "jsdoc2md --no-cache --global-index-format grouped --separators --template doc-files/README.md.tmpl src/geojson2h3.js > README.md",
+    "dist": "yarn dist-clean && buble -i src -o dist/src && cp types.d.ts dist",
     "dist-clean": "rm -rf dist && mkdir dist",
     "dist-test": "yarn dist && buble -i test -o dist/test",
     "benchmarks": "yarn dist-test && node dist/test/benchmarks.js",
     "prepublish": "yarn dist",
-    "prettier": "prettier --write --single-quote --no-bracket-spacing --print-width=100 'src/**/*.js' 'test/**/*.js'"
+    "prettier": "prettier --write --single-quote --no-bracket-spacing --print-width=100 'src/**/*.js' 'test/**/*.js' '*.d.ts'"
   },
   "engines": {
     "node": ">=4",
     "npm": ">=3",
     "yarn": ">=1.3.0"
+  },
+  "volta": {
+    "node": "12.19.0",
+    "yarn": "1.22.10"
   }
 }

src/geojson2h3.js

@@ -109,12 +109,12 @@ function featureToH3Set(feature, resolution) {
  * @param  {Object} [properties] Optional feature properties
  * @return {Feature}             GeoJSON Feature object
  */
-function h3ToFeature(hexAddress, properties = {}) {
+function h3ToFeature(h3Index, properties = {}) {
     // Wrap in an array for a single-loop polygon
-    const coordinates = [h3.h3ToGeoBoundary(hexAddress, true)];
+    const coordinates = [h3.h3ToGeoBoundary(h3Index, true)];
     return {
         type: FEATURE,
-        id: hexAddress,
+        id: h3Index,
         properties,
         geometry: {
             type: POLYGON,
@@ -162,9 +162,9 @@ function h3SetToFeature(hexagons, properties = {}) {
  * @return {Feature}             GeoJSON Feature object
  */
 function h3SetToMultiPolygonFeature(hexagons, properties = {}) {
-    const coordinates = hexagons.map(hexAddress =>
+    const coordinates = hexagons.map(h3Index =>
         // Wrap in an array for a single-loop polygon
-        [h3.h3ToGeoBoundary(hexAddress, {geoJson: true})]
+        [h3.h3ToGeoBoundary(h3Index, {geoJson: true})]
     );
     return {
         type: FEATURE,
@@ -184,15 +184,15 @@ function h3SetToMultiPolygonFeature(hexagons, properties = {}) {
  * @static
  * @param  {String[]} hexagons  Hexagon addresses
  * @param  {Function} [getProperties] Optional function returning properties
- *                                    for a hexagon: f(hexAddress) => Object
+ *                                    for a hexagon: f(h3Index) => Object
  * @return {FeatureCollection}        GeoJSON FeatureCollection object
  */
 function h3SetToFeatureCollection(hexagons, getProperties) {
     const features = [];
     for (let i = 0; i < hexagons.length; i++) {
-        const hexAddress = hexagons[i];
-        const properties = getProperties ? getProperties(hexAddress) : {};
-        features.push(h3ToFeature(hexAddress, properties));
+        const h3Index = hexagons[i];
+        const properties = getProperties ? getProperties(h3Index) : {};
+        features.push(h3ToFeature(h3Index, properties));
     }
     return {
         type: FEATURE_COLLECTION,

test/geojson2h3.spec.js

@@ -134,7 +134,7 @@ function assertSymmetrical(assert, feature, hexagons) {
     );
     assertEqualFeatures(
         assert,
-        h3SetToFeature(featureToH3Set(feature, DEFAULT_RES)),
+        h3SetToFeature(featureToH3Set(feature, DEFAULT_RES).sort()),
         feature,
         'h3SetToFeature round-trip matches expected'
     );
@@ -274,8 +274,8 @@ test('featureToH3Set - MultiPolygon, contiguous', assert => {
     ];
 
     assert.deepEqual(
-        featureToH3Set(feature, DEFAULT_RES),
-        hexagons,
+        featureToH3Set(feature, DEFAULT_RES).sort(),
+        hexagons.sort(),
         'featureToH3Set matches expected'
     );
 
@@ -301,8 +301,8 @@ test('featureToH3Set - MultiPolygon, non-contiguous', assert => {
     ];
 
     assert.deepEqual(
-        featureToH3Set(feature, DEFAULT_RES),
-        hexagons,
+        featureToH3Set(feature, DEFAULT_RES).sort(),
+        hexagons.sort(),
         'featureToH3Set matches expected'
     );
 
@@ -341,8 +341,8 @@ test('featureToH3Set - FeatureCollection', assert => {
     ];
 
     assert.deepEqual(
-        featureToH3Set(feature, DEFAULT_RES),
-        hexagons,
+        featureToH3Set(feature, DEFAULT_RES).sort(),
+        hexagons.sort(),
         'featureToH3Set matches expected'
     );
 

types.d.ts

@@ -0,0 +1,41 @@
+declare module 'geojson2h3' {
+    import {Feature, FeatureCollection, GeoJsonProperties} from 'geojson';
+
+    /**
+     * Convert a GeoJSON feature to a set of hexagons. Only hexagons whose centers
+     * fall within the feature will be included. Note that conversion from GeoJSON
+     * is lossy; the resulting hexagon set only approximately describes the original
+     * shape, at a level of precision determined by the hexagon resolution.
+     */
+    export function featureToH3Set(feature: Feature, resolution: number): string[];
+
+    /**
+     * Convert a single H3 hexagon to a GeoJSON `Polygon` feature
+     */
+    export function h3ToFeature(h3Index: string, properties: GeoJsonProperties): Feature;
+
+    /**
+     * Convert a set of hexagons to a GeoJSON `Feature` with the set outline(s). The
+     * feature's geometry type will be either `Polygon` or `MultiPolygon` depending on
+     * the number of outlines required for the set.
+     */
+    export function h3SetToFeature(hexagons: string[], properties: GeoJsonProperties): Feature;
+
+    /**
+     * Convert a set of hexagons to a GeoJSON `MultiPolygon` feature with the
+     * outlines of each individual hexagon.
+     */
+    export function h3SetToMultiPolygonFeature(
+        hexagons: string[],
+        properties: GeoJsonProperties
+    ): Feature;
+
+    /**
+     * Convert a set of hexagons to a GeoJSON `FeatureCollection` with each hexagon
+     * in a separate `Polygon` feature with optional properties.
+     */
+    export function h3SetToFeatureCollection(
+        hexagons: string[],
+        getProperties: (h3Index: string) => GeoJsonProperties
+    ): FeatureCollection;
+}