h3-js - npm Package Compare versions

Comparing version 4.0.1 to 4.1.0

benchmark/benchmarks.js

@@ -65,2 +65,18 @@ /*
 
+    suite.add('cellToChildren', () => {
+        h3core.cellToChildren(h3Index, 14);
+    });
+
+    suite.add('cellToParent', () => {
+        h3core.cellToParent(h3Index, 0);
+    });
+
+    suite.add('cellToChildPos', () => {
+        h3core.cellToChildPos(h3Index, 0);
+    });
+
+    suite.add('childPosToCell', () => {
+        h3core.childPosToCell(16800, h3Index, 14);
+    });
+
     suite.add('gridDisk', () => {
@@ -67,0 +83,0 @@ h3core.gridDisk(h3Index, 1);

CHANGELOG.md

@@ -6,3 +6,15 @@ # Change Log
 ## [Unreleased]
+- *None*
 
+## [4.1.0] - 2023-01-19
+### Added
+- Add `cellToChildPos`, `childPosToCell`, and `cellToChildrenSize` functions. (#170)
+
+### Changed
+- Updated the core library to `v4.1.0` (#170)
+
+### Fixed
+- Patch libh3 bundles to check for `typeof document != "undefined"` before accessing `document`. This allows h3-js to be used in a Web Worker and React Native (#169)
+- Fix H3Index type hints for `cellToBoundary`, `cellArea`, `edgeLength` (#171)
+
 ## [4.0.1] - 2022-09-19
@@ -9,0 +21,0 @@ ### Changed

dist/legacy-types.d.ts

@@ -83,3 +83,3 @@ declare module "h3-js" {
      * @static
-     * @param  {H3Index} h3Index          H3 index
+     * @param  {H3IndexInput} h3Index          H3 index
      * @param {boolean} [formatAsGeoJson] Whether to provide GeoJSON output: [lng, lat], closed loops
@@ -89,3 +89,3 @@ * @return {CoordPair[]}              Array of [lat, lng] pairs
      */
-    export function h3ToGeoBoundary(h3Index: H3Index, formatAsGeoJson?: boolean): CoordPair[];
+    export function h3ToGeoBoundary(h3Index: H3IndexInput, formatAsGeoJson?: boolean): CoordPair[];
     /**
@@ -110,6 +110,15 @@ * Get the parent of the given hexagon at a particular resolution
     /**
+     * Get the number of children for a cell at a given resolution
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index to get child count for
+     * @param  {number} res            Child resolution
+     * @return {number}                Number of children at res for the given cell
+     * @throws {H3Error}               If cell or parentRes are invalid
+     */
+    export function cellToChildrenSize(h3Index: H3IndexInput, res: number): number;
+    /**
      * Get the center child of the given hexagon at a particular resolution
      * @static
      * @param  {H3IndexInput} h3Index  H3 index to get center child for
-     * @param  {number} res       Resolution of hexagon to return
+     * @param  {number} res       Resolution of cell to return
      * @return {H3Index}          H3 index of child, or null for invalid input
@@ -120,2 +129,23 @@ * @throws {H3Error}          If resolution is invalid
     /**
+     * Get the position of the cell within an ordered list of all children of the
+     * cell's parent at the specified resolution.
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index to get child pos for
+     * @param  {number} parentRes      Resolution of reference parent
+     * @return {number}                Position of child within parent at parentRes
+     * @throws {H3Error}               If cell or parentRes are invalid
+     */
+    export function cellToChildPos(h3Index: H3IndexInput, parentRes: number): number;
+    /**
+     * Get the child cell at a given position within an ordered list of all children
+     * at the specified resolution
+     * @static
+     * @param  {number} childPos       Position of the child cell to get
+     * @param  {H3IndexInput} h3Index  H3 index of the parent cell
+     * @param  {number} childRes       Resolution of child cell to return
+     * @return {H3Index}          H3 index of child
+     * @throws {H3Error}          If input is invalid
+     */
+    export function childPosToCell(childPos: number, h3Index: H3IndexInput, childRes: number): H3Index;
+    /**
      * Get all hexagons in a k-ring around a given center. The order of the hexagons is undefined.
@@ -354,3 +384,3 @@ * @static
      * @static
-     * @param  {H3Index} h3Index  H3 index of the hexagon to measure
+     * @param  {H3IndexInput} h3Index  H3 index of the hexagon to measure
      * @param  {string}  unit     Distance unit (either UNITS.m2, UNITS.km2, or UNITS.rads2)
@@ -360,7 +390,7 @@ * @return {number}           Cell area
      */
-    export function cellArea(h3Index: H3Index, unit: string): number;
+    export function cellArea(h3Index: H3IndexInput, unit: string): number;
     /**
      * Calculate length of a given unidirectional edge
      * @static
-     * @param  {H3Index} edge     H3 index of the edge to measure
+     * @param  {H3IndexInput} edge     H3 index of the edge to measure
      * @param  {string}  unit     Distance unit (either UNITS.m, UNITS.km, or UNITS.rads)
@@ -370,3 +400,3 @@ * @return {number}           Cell area
      */
-    export function exactEdgeLength(edge: H3Index, unit: string): number;
+    export function exactEdgeLength(edge: H3IndexInput, unit: string): number;
     /**
@@ -373,0 +403,0 @@ * Average hexagon area at a given resolution

dist/print-bindings.js

@@ -70,2 +70,4 @@ 'use strict';
     ['cellToChildrenSize', H3_ERROR, [H3_LOWER, H3_UPPER, RESOLUTION, POINTER]],
+    ['cellToChildPos', H3_ERROR, [H3_LOWER, H3_UPPER, RESOLUTION, POINTER]],
+    ['childPosToCell', H3_ERROR, [NUMBER, NUMBER, H3_LOWER, H3_UPPER, RESOLUTION, POINTER]],
     ['areNeighborCells', H3_ERROR, [H3_LOWER, H3_UPPER, H3_LOWER, H3_UPPER, POINTER]],
@@ -72,0 +74,0 @@ ['cellsToDirectedEdge', H3_ERROR, [H3_LOWER, H3_UPPER, H3_LOWER, H3_UPPER, POINTER]],

dist/types.d.ts

@@ -83,3 +83,3 @@ declare module "h3-js" {
      * @static
-     * @param  {H3Index} h3Index          H3 index
+     * @param  {H3IndexInput} h3Index          H3 index
      * @param {boolean} [formatAsGeoJson] Whether to provide GeoJSON output: [lng, lat], closed loops
@@ -89,3 +89,3 @@ * @return {CoordPair[]}              Array of [lat, lng] pairs
      */
-    export function cellToBoundary(h3Index: H3Index, formatAsGeoJson?: boolean): CoordPair[];
+    export function cellToBoundary(h3Index: H3IndexInput, formatAsGeoJson?: boolean): CoordPair[];
     /**
@@ -110,6 +110,15 @@ * Get the parent of the given hexagon at a particular resolution
     /**
+     * Get the number of children for a cell at a given resolution
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index to get child count for
+     * @param  {number} res            Child resolution
+     * @return {number}                Number of children at res for the given cell
+     * @throws {H3Error}               If cell or parentRes are invalid
+     */
+    export function cellToChildrenSize(h3Index: H3IndexInput, res: number): number;
+    /**
      * Get the center child of the given hexagon at a particular resolution
      * @static
      * @param  {H3IndexInput} h3Index  H3 index to get center child for
-     * @param  {number} res       Resolution of hexagon to return
+     * @param  {number} res       Resolution of cell to return
      * @return {H3Index}          H3 index of child, or null for invalid input
@@ -120,2 +129,23 @@ * @throws {H3Error}          If resolution is invalid
     /**
+     * Get the position of the cell within an ordered list of all children of the
+     * cell's parent at the specified resolution.
+     * @static
+     * @param  {H3IndexInput} h3Index  H3 index to get child pos for
+     * @param  {number} parentRes      Resolution of reference parent
+     * @return {number}                Position of child within parent at parentRes
+     * @throws {H3Error}               If cell or parentRes are invalid
+     */
+    export function cellToChildPos(h3Index: H3IndexInput, parentRes: number): number;
+    /**
+     * Get the child cell at a given position within an ordered list of all children
+     * at the specified resolution
+     * @static
+     * @param  {number} childPos       Position of the child cell to get
+     * @param  {H3IndexInput} h3Index  H3 index of the parent cell
+     * @param  {number} childRes       Resolution of child cell to return
+     * @return {H3Index}          H3 index of child
+     * @throws {H3Error}          If input is invalid
+     */
+    export function childPosToCell(childPos: number, h3Index: H3IndexInput, childRes: number): H3Index;
+    /**
      * Get all hexagons in a k-ring around a given center. The order of the hexagons is undefined.
@@ -354,3 +384,3 @@ * @static
      * @static
-     * @param  {H3Index} h3Index  H3 index of the hexagon to measure
+     * @param  {H3IndexInput} h3Index  H3 index of the hexagon to measure
      * @param  {string}  unit     Distance unit (either UNITS.m2, UNITS.km2, or UNITS.rads2)
@@ -360,7 +390,7 @@ * @return {number}           Cell area
      */
-    export function cellArea(h3Index: H3Index, unit: string): number;
+    export function cellArea(h3Index: H3IndexInput, unit: string): number;
     /**
      * Calculate length of a given unidirectional edge
      * @static
-     * @param  {H3Index} edge     H3 index of the edge to measure
+     * @param  {H3IndexInput} edge     H3 index of the edge to measure
      * @param  {string}  unit     Distance unit (either UNITS.m, UNITS.km, or UNITS.rads)
@@ -370,3 +400,3 @@ * @return {number}           Cell area
      */
-    export function edgeLength(edge: H3Index, unit: string): number;
+    export function edgeLength(edge: H3IndexInput, unit: string): number;
     /**
@@ -373,0 +403,0 @@ * Average hexagon area at a given resolution

lib/bindings.js

@@ -68,2 +68,4 @@ /*
     ['cellToChildrenSize', H3_ERROR, [H3_LOWER, H3_UPPER, RESOLUTION, POINTER]],
+    ['cellToChildPos', H3_ERROR, [H3_LOWER, H3_UPPER, RESOLUTION, POINTER]],
+    ['childPosToCell', H3_ERROR, [NUMBER, NUMBER, H3_LOWER, H3_UPPER, RESOLUTION, POINTER]],
     ['areNeighborCells', H3_ERROR, [H3_LOWER, H3_UPPER, H3_LOWER, H3_UPPER, POINTER]],
@@ -70,0 +72,0 @@ ['cellsToDirectedEdge', H3_ERROR, [H3_LOWER, H3_UPPER, H3_LOWER, H3_UPPER, POINTER]],

lib/h3core.js

@@ -30,3 +30,4 @@ /*
     E_ARRAY_LENGTH,
-    E_NULL_INDEX
+    E_NULL_INDEX,
+    E_CELL_INVALID
 } from './errors';
@@ -252,3 +253,20 @@
 
+// One more than the max size of an unsigned 32-bit int.
+// Dividing by this number is equivalent to num >>> 32
+const UPPER_BIT_DIVISOR = Math.pow(2, 32);
+
 /**
+ * Convert a JS double-precision floating point number to a split long
+ * @private
+ * @param  {number} num  Number to convert
+ * @return {SplitLong}     A two-element array with 32 lower bits and 32 upper bits
+ */
+function numberToSplitLong(num) {
+    if (typeof num !== 'number') {
+        return [0, 0];
+    }
+    return [num | 0, (num / UPPER_BIT_DIVISOR) | 0];
+}
+
+/**
  * Populate a C-appropriate GeoLoop struct from a polygon array
@@ -730,3 +748,3 @@ * @private
  * @static
- * @param  {H3Index} h3Index          H3 index
+ * @param  {H3IndexInput} h3Index          H3 index
  * @param {boolean} [formatAsGeoJson] Whether to provide GeoJSON output: [lng, lat], closed loops
@@ -784,13 +802,29 @@ * @return {CoordPair[]}              Array of [lat, lng] pairs
     const [lower, upper] = h3IndexToSplitLong(h3Index);
+    const count = validateArrayLength(cellToChildrenSize(h3Index, res));
+    const hexagons = C._calloc(count, SZ_H3INDEX);
+    try {
+        throwIfError(H3.cellToChildren(lower, upper, res, hexagons));
+        return readArrayOfH3Indexes(hexagons, count);
+    } finally {
+        C._free(hexagons);
+    }
+}
+
+/**
+ * Get the number of children for a cell at a given resolution
+ * @static
+ * @param  {H3IndexInput} h3Index  H3 index to get child count for
+ * @param  {number} res            Child resolution
+ * @return {number}                Number of children at res for the given cell
+ * @throws {H3Error}               If cell or parentRes are invalid
+ */
+export function cellToChildrenSize(h3Index, res) {
+    if (!isValidCell(h3Index)) {
+        throw H3LibraryError(E_CELL_INVALID);
+    }
+    const [lower, upper] = h3IndexToSplitLong(h3Index);
     const countPtr = C._malloc(SZ_INT64);
     try {
         throwIfError(H3.cellToChildrenSize(lower, upper, res, countPtr));
-        const count = validateArrayLength(readInt64AsDoubleFromPointer(countPtr));
-        const hexagons = C._calloc(count, SZ_H3INDEX);
-        try {
-            throwIfError(H3.cellToChildren(lower, upper, res, hexagons));
-            return readArrayOfH3Indexes(hexagons, count);
-        } finally {
-            C._free(hexagons);
-        }
+        return readInt64AsDoubleFromPointer(countPtr);
     } finally {
@@ -805,3 +839,3 @@ C._free(countPtr);
  * @param  {H3IndexInput} h3Index  H3 index to get center child for
- * @param  {number} res       Resolution of hexagon to return
+ * @param  {number} res       Resolution of cell to return
  * @return {H3Index}          H3 index of child, or null for invalid input
@@ -822,2 +856,44 @@ * @throws {H3Error}          If resolution is invalid
 /**
+ * Get the position of the cell within an ordered list of all children of the
+ * cell's parent at the specified resolution.
+ * @static
+ * @param  {H3IndexInput} h3Index  H3 index to get child pos for
+ * @param  {number} parentRes      Resolution of reference parent
+ * @return {number}                Position of child within parent at parentRes
+ * @throws {H3Error}               If cell or parentRes are invalid
+ */
+export function cellToChildPos(h3Index, parentRes) {
+    const [lower, upper] = h3IndexToSplitLong(h3Index);
+    const childPos = C._malloc(SZ_INT64);
+    try {
+        throwIfError(H3.cellToChildPos(lower, upper, parentRes, childPos));
+        return readInt64AsDoubleFromPointer(childPos);
+    } finally {
+        C._free(childPos);
+    }
+}
+
+/**
+ * Get the child cell at a given position within an ordered list of all children
+ * at the specified resolution
+ * @static
+ * @param  {number} childPos       Position of the child cell to get
+ * @param  {H3IndexInput} h3Index  H3 index of the parent cell
+ * @param  {number} childRes       Resolution of child cell to return
+ * @return {H3Index}          H3 index of child
+ * @throws {H3Error}          If input is invalid
+ */
+export function childPosToCell(childPos, h3Index, childRes) {
+    const [cpLower, cpUpper] = numberToSplitLong(childPos);
+    const [lower, upper] = h3IndexToSplitLong(h3Index);
+    const child = C._malloc(SZ_H3INDEX);
+    try {
+        throwIfError(H3.childPosToCell(cpLower, cpUpper, lower, upper, childRes, child));
+        return validateH3Index(readH3IndexFromPointer(child));
+    } finally {
+        C._free(child);
+    }
+}
+
+/**
  * Get all hexagons in a k-ring around a given center. The order of the hexagons is undefined.
@@ -1404,3 +1480,3 @@ * @static
  * @static
- * @param  {H3Index} h3Index  H3 index of the hexagon to measure
+ * @param  {H3IndexInput} h3Index  H3 index of the hexagon to measure
  * @param  {string}  unit     Distance unit (either UNITS.m2, UNITS.km2, or UNITS.rads2)
@@ -1436,3 +1512,3 @@ * @return {number}           Cell area
  * @static
- * @param  {H3Index} edge     H3 index of the edge to measure
+ * @param  {H3IndexInput} edge     H3 index of the edge to measure
  * @param  {string}  unit     Distance unit (either UNITS.m, UNITS.km, or UNITS.rads)
@@ -1439,0 +1515,0 @@ * @return {number}           Cell area

package.json

 {
   "name": "h3-js",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "description": "Pure-Javascript version of the H3 library, a hexagon-based geographic grid system",
@@ -5,0 +5,0 @@ "author": "Nick Rabinowitz <[e-mail]>",

README.md

@@ -11,3 +11,3 @@ <!-- the README is generated from a template, please edit doc-files/README.md.tmpl -->
 [![npm version](https://badge.fury.io/js/h3-js.svg)](https://badge.fury.io/js/h3-js)
-[![H3 Version](https://img.shields.io/static/v1?label=h3%20api&message=v4.0.0&color=blue)](https://github.com/uber/h3/releases/tag/v4.0.1)
+[![H3 Version](https://img.shields.io/static/v1?label=h3%20api&message=v4.1.0&color=blue)](https://github.com/uber/h3/releases/tag/v4.1.0)
 
@@ -116,3 +116,6 @@ The `h3-js` library provides a pure-JavaScript version of the [H3 Core Library](https://github.com/uber/h3), a hexagon-based geographic grid system. It can be used either in Node >= 6 or in the browser. The core library is transpiled from C using [emscripten](http://kripken.github.io/emscripten-site), offering full parity with the C API and highly efficient operations.
     * [.cellToChildren(h3Index, res)](#module_h3.cellToChildren) ⇒ <code>Array.&lt;H3Index&gt;</code>
+    * [.cellToChildrenSize(h3Index, res)](#module_h3.cellToChildrenSize) ⇒ <code>number</code>
     * [.cellToCenterChild(h3Index, res)](#module_h3.cellToCenterChild) ⇒ <code>H3Index</code>
+    * [.cellToChildPos(h3Index, parentRes)](#module_h3.cellToChildPos) ⇒ <code>number</code>
+    * [.childPosToCell(childPos, h3Index, childRes)](#module_h3.childPosToCell) ⇒ <code>H3Index</code>
     * [.gridDisk(h3Index, ringSize)](#module_h3.gridDisk) ⇒ <code>Array.&lt;H3Index&gt;</code>
@@ -352,3 +355,3 @@ * [.gridDiskDistances(h3Index, ringSize)](#module_h3.gridDiskDistances) ⇒ <code>Array.&lt;Array.&lt;H3Index&gt;&gt;</code>
 | --- | --- | --- |
-| h3Index | <code>H3Index</code> | H3 index |
+| h3Index | <code>H3IndexInput</code> | H3 index |
 | [formatAsGeoJson] | <code>boolean</code> | Whether to provide GeoJSON output: [lng, lat], closed loops |
@@ -397,2 +400,21 @@
 
+<a name="module_h3.cellToChildrenSize"></a>
+
+### h3.cellToChildrenSize(h3Index, res) ⇒ <code>number</code>
+Get the number of children for a cell at a given resolution
+
+**Returns**: <code>number</code> - Number of children at res for the given cell  
+**Throws**:
+
+- <code>H3Error</code> If cell or parentRes are invalid
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| h3Index | <code>H3IndexInput</code> | H3 index to get child count for |
+| res | <code>number</code> | Child resolution |
+
+
+* * *
+
 <a name="module_h3.cellToCenterChild"></a>
@@ -412,3 +434,3 @@
 | h3Index | <code>H3IndexInput</code> | H3 index to get center child for |
-| res | <code>number</code> | Resolution of hexagon to return |
+| res | <code>number</code> | Resolution of cell to return |
 
@@ -418,2 +440,43 @@
 
+<a name="module_h3.cellToChildPos"></a>
+
+### h3.cellToChildPos(h3Index, parentRes) ⇒ <code>number</code>
+Get the position of the cell within an ordered list of all children of the
+cell's parent at the specified resolution.
+
+**Returns**: <code>number</code> - Position of child within parent at parentRes  
+**Throws**:
+
+- <code>H3Error</code> If cell or parentRes are invalid
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| h3Index | <code>H3IndexInput</code> | H3 index to get child pos for |
+| parentRes | <code>number</code> | Resolution of reference parent |
+
+
+* * *
+
+<a name="module_h3.childPosToCell"></a>
+
+### h3.childPosToCell(childPos, h3Index, childRes) ⇒ <code>H3Index</code>
+Get the child cell at a given position within an ordered list of all children
+at the specified resolution
+
+**Returns**: <code>H3Index</code> - H3 index of child  
+**Throws**:
+
+- <code>H3Error</code> If input is invalid
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| childPos | <code>number</code> | Position of the child cell to get |
+| h3Index | <code>H3IndexInput</code> | H3 index of the parent cell |
+| childRes | <code>number</code> | Resolution of child cell to return |
+
+
+* * *
+
 <a name="module_h3.gridDisk"></a>
@@ -856,3 +919,3 @@
 | --- | --- | --- |
-| h3Index | <code>H3Index</code> | H3 index of the hexagon to measure |
+| h3Index | <code>H3IndexInput</code> | H3 index of the hexagon to measure |
 | unit | <code>string</code> | Distance unit (either UNITS.m2, UNITS.km2, or UNITS.rads2) |
@@ -876,3 +939,3 @@
 | --- | --- | --- |
-| edge | <code>H3Index</code> | H3 index of the edge to measure |
+| edge | <code>H3IndexInput</code> | H3 index of the edge to measure |
 | unit | <code>string</code> | Distance unit (either UNITS.m, UNITS.km, or UNITS.rads) |
@@ -879,0 +942,0 @@

New alerts

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

Fixed alerts

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

5910140

increased by5.56%

Lines of code

61096

increased by5.37%

Number of lines in readme file

1287

increased by5.15%

No dependency changes