@here/olp-sdk-dataservice-read 3.0.0 → 3.1.0

package/lib/client/VersionedLayerClient.d.ts

@@ -1,5 +1,6 @@
 import { HRN, OlpClientSettings } from "@here/olp-sdk-core";
 import { MetadataApi, QueryApi } from "@here/olp-sdk-dataservice-api";
+import { TileResponse } from "../utils/getTile";
 import { DataRequest } from "./DataRequest";
 import { PartitionsRequest } from "./PartitionsRequest";
 import { QuadKeyPartitionsRequest } from "./QuadKeyPartitionsRequest";
@@ -55,6 +56,46 @@ export declare class VersionedLayerClient {
      * @return Tile data (if it exists) or the nearest parent tile data
      */
     getAggregatedData(request: TileRequest, abortSignal?: AbortSignal): Promise<Response>;
+    /**
+     * @brief Fetches data of a tile or its closest ancestor.
+     * Use this API for tile-tree structures where children tile data is aggregated and stored in parent tiles.
+     *
+     * @param request The `TileRequest` instance that contains a complete set
+     * of request parameters.
+     * @param abortSignal A signal object that allows you to communicate with a request (such as the `fetch` request)
+     * and, if required, abort it using the `AbortController` object.
+     * @param options An optional object that can include the `includeTileKey` flag to indicate whether the parent tile key should be included in the response.
+     *
+     * For more information, see the [`AbortController` documentation](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+     *
+     * @return Tile data (if it exists) or the nearest parent tile data including the parent tile key
+     */
+    getAggregatedData(request: TileRequest, abortSignal: AbortSignal | undefined, options: {
+        includeTileKey: true;
+    }): Promise<TileResponse>;
+    /**
+     * @brief Fetches data of a tile or its closest ancestor.
+     *
+     * Same as the two-argument `getAggregatedData`, for callers that pass an
+     * options object with `includeTileKey` disabled or omitted.
+     *
+     * @return Tile data (if it exists) or the nearest parent tile data
+     */
+    getAggregatedData(request: TileRequest, abortSignal: AbortSignal | undefined, options: {
+        includeTileKey?: false;
+    }): Promise<Response>;
+    /**
+     * @brief Fetches data of a tile or its closest ancestor.
+     *
+     * Same as the two-argument `getAggregatedData`, for an `includeTileKey`
+     * flag whose value is only known at run time. Narrow the result before
+     * using it.
+     *
+     * @return A `TileResponse` if the flag was `true`, otherwise the tile data
+     */
+    getAggregatedData(request: TileRequest, abortSignal: AbortSignal | undefined, options: {
+        includeTileKey?: boolean;
+    }): Promise<Response | TileResponse>;
     /**
      * Fetches partition data using one of the following methods: ID, quadkey, or data handle.
      *

package/lib/client/VersionedLayerClient.js

@@ -59,20 +59,7 @@ class VersionedLayerClient {
             this.version = params.version;
         }
     }
-    /**
-     * @brief Fetches data of a tile or its closest ancestor.
-     * Use this API for tile-tree structures where children tile data is aggregated and stored in parent tiles.
-     *
-     * @param request The `TileRequest` instance that contains a complete set
-     * of request parameters.
-     * @param abortSignal A signal object that allows you to communicate with a request (such as the `fetch` request)
-     * and, if required, abort it using the `AbortController` object.
-     *
-     * For more information, see the [`AbortController` documentation](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
-     *
-     * @return Tile data (if it exists) or the nearest parent tile data
-     */
-    async getAggregatedData(request, abortSignal) {
+    async getAggregatedData(request, abortSignal, options) {
         let catalogVersion = this.version;
         if (catalogVersion === undefined) {
             catalogVersion = await this.getLatestVersion(request.getBillingTag());
@@ -84,7 +71,10 @@ class VersionedLayerClient {
             settings: this.settings,
             catalogVersion
         };
-        return (0, getTile_1.getTile)(request, params, abortSignal);
+        const tileResponse = await (0, getTile_1.getTile)(request, params, abortSignal, {
+            includeTileKey: true
+        });
+        return options?.includeTileKey ? tileResponse : tileResponse.response;
     }
     /**
      * Fetches partition data using one of the following methods: ID, quadkey, or data handle.

package/lib/utils/getTile.d.ts

@@ -11,6 +11,10 @@ export interface GetTileParams {
     layerId: string;
     layerType: "versioned" | "volatile";
 }
+export interface TileResponse {
+    response: Response;
+    parentTileKey: TileKey | undefined;
+}
 /**
  * Fetches asynchronously data from a tile or from its nearest ancestor if not found.
  *
@@ -46,6 +50,37 @@ export interface GetTileParams {
  * @returns The blob of the requested tile or the blob of the closest parent Tile.
  */
 export declare function getTile(request: TileRequest, params: TileRequestParams, abortSignal?: AbortSignal): Promise<Response>;
+/**
+ * Same as the three-argument [[getTile]], but also resolves the tile key of
+ * the parent whose data was actually returned.
+ *
+ * @param options Pass `{ includeTileKey: true }` to receive a [[TileResponse]]
+ * instead of a plain `Response`.
+ *
+ * @returns The blob of the requested tile or the blob of the closest parent
+ * tile, together with that tile's key.
+ */
+export declare function getTile(request: TileRequest, params: TileRequestParams, abortSignal: AbortSignal | undefined, options: {
+    includeTileKey: true;
+}): Promise<TileResponse>;
+/**
+ * Same as the three-argument [[getTile]], for callers that pass an options
+ * object with `includeTileKey` disabled or omitted.
+ *
+ * @returns The blob of the requested tile or the blob of the closest parent Tile.
+ */
+export declare function getTile(request: TileRequest, params: TileRequestParams, abortSignal: AbortSignal | undefined, options: {
+    includeTileKey?: false;
+}): Promise<Response>;
+/**
+ * Same as the three-argument [[getTile]], for an `includeTileKey` flag whose
+ * value is only known at run time. Narrow the result before using it.
+ *
+ * @returns A [[TileResponse]] if the flag was `true`, otherwise the plain blob.
+ */
+export declare function getTile(request: TileRequest, params: TileRequestParams, abortSignal: AbortSignal | undefined, options: {
+    includeTileKey?: boolean;
+}): Promise<Response | TileResponse>;
 /**
  * The function should request quad tree index for the parent tile with delta 4
  * and cache the responses in cache for later calls.

package/lib/utils/getTile.js

@@ -25,41 +25,14 @@ const olp_sdk_dataservice_api_1 = require("@here/olp-sdk-dataservice-api");
 const QuadTreeIndexCacheRepository_1 = require("../cache/QuadTreeIndexCacheRepository");
 const QuadTreeIndexRequest_1 = require("../client/QuadTreeIndexRequest");
 const QueryClient_1 = require("../client/QueryClient");
+async function getTile(request, params, abortSignal, options) {
+    const tileResponse = await fetchTile(request, params, abortSignal);
+    return options?.includeTileKey ? tileResponse : tileResponse.response;
+}
 /**
- * Fetches asynchronously data from a tile or from its nearest ancestor if not found.
- *
- * The tile is a geometric area represented as a HERE tile.
- * The quad tree metadata fetches the blob of needed tile from the HERE Query Service,
- * then caches it, and returns to the user.
- * To disable caching of metadata use `request.withFetchOption(FetchOptions.OnlineOnly)`.
- *
- * @param request Requests the [[TileRequest]] instance with the configured parameters.
- * @see [[TileRequest]]
- *
- * @param abortSignal The signal object that allows you to communicate with a request (such as the `fetch` request)
- * and, if required, abort it using the `AbortController` object.
- * @see the [`AbortController` documentation](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
- *
- * @example
- *
- * ```
- *  const params: GetTileParams = {
- *       settings: "% your `OlpClientSettings` instance % ",
- *       catalogHrn: "% the HRN instance of your catalog %",
- *       layerId: "% your layer ID %",
- *       layerType: "% versioned or volatile %",
- *   }
- *
- *  const request = new TileRequest();
- *
- *  const tile1 = await getTile(request.withTileKey(yourTileKey1), params);
- *  const tile2 = await getTile(request.withTileKey(yourTileKey2), params);
- *
- * ```
- *
- * @returns The blob of the requested tile or the blob of the closest parent Tile.
+ * @hidden
  */
-async function getTile(request, params, abortSignal) {
+async function fetchTile(request, params, abortSignal) {
     let catalogVersion;
     const quadKey = request.getTileKey();
     if (!quadKey) {
@@ -70,65 +43,86 @@ async function getTile(request, params, abortSignal) {
     }
     const blobType = params.layerType === "versioned" ? "blob" : "volatile-blob";
     const blobRequestBuilder = await olp_sdk_core_1.RequestFactory.create(blobType, "v1", params.settings, params.catalogHrn, abortSignal);
-    const delta = 4;
+    const depth = 4;
     const requestedTileKey = olp_sdk_core_1.TileKey.fromRowColumnLevel(quadKey.row, quadKey.column, quadKey.level);
-    let quadTreeIndex = null;
+    const quadTreeIndexRoot = requestedTileKey.changedLevelBy(-depth);
+    let quadTreeIndex;
     if (request.getFetchOption() !== olp_sdk_core_1.FetchOptions.OnlineOnly) {
         const cache = new QuadTreeIndexCacheRepository_1.QuadTreeIndexCacheRepository(params.settings.cache);
-        for (let i = 1; i <= delta; i++) {
-            const parentInCache = requestedTileKey.changedLevelBy(-i);
-            const cachedTree = cache.get({
-                hrn: params.catalogHrn.toString(),
-                layerId: params.layerId,
-                depth: delta,
-                root: parentInCache,
-                version: catalogVersion
-            });
-            if (cachedTree) {
-                quadTreeIndex = cachedTree;
-            }
-        }
+        quadTreeIndex = cache.get({
+            hrn: params.catalogHrn.toString(),
+            layerId: params.layerId,
+            depth,
+            root: quadTreeIndexRoot,
+            version: catalogVersion
+        });
     }
-    const parentTileKey = requestedTileKey.changedLevelBy(-delta);
     if (!quadTreeIndex) {
         quadTreeIndex = await fetchQuadTreeIndex({
             ...params,
             catalogVersion,
-            depth: delta,
+            depth,
             fetchOptions: request.getFetchOption(),
-            tileKey: parentTileKey,
+            tileKey: quadTreeIndexRoot,
             abortSignal,
             billingTag: request.getBillingTag()
         });
     }
-    if (!quadTreeIndex.subQuads || !quadTreeIndex.subQuads.length) {
-        return Promise.resolve(new Response(null, {
-            status: 204,
-            statusText: "No Content"
-        }));
+    const subQuads = quadTreeIndex.subQuads ?? [];
+    const parentQuads = quadTreeIndex.parentQuads ?? [];
+    if (!subQuads.length && !parentQuads.length) {
+        return Promise.resolve({
+            response: new Response(null, {
+                status: 204,
+                statusText: "No Content"
+            }),
+            parentTileKey: undefined
+        });
     }
-    // Return the data for the requested QuadKey or for the closest parent
-    const subQuads = quadTreeIndex.subQuads;
-    let currentTileKey = requestedTileKey;
-    let currentDelta = delta;
-    for (let level = currentTileKey.level; level >= parentTileKey.level; --level) {
-        const metadata = subQuads.find((item) => item.subQuadKey === currentTileKey.getSubHereTile(currentDelta));
-        if (metadata) {
-            return olp_sdk_dataservice_api_1.BlobApi.getBlob(blobRequestBuilder, {
-                dataHandle: metadata.dataHandle,
-                layerId: params.layerId,
-                billingTag: request.getBillingTag()
-            });
-        }
-        try {
-            currentTileKey = currentTileKey.parent();
-            currentDelta = parentTileKey.level - currentTileKey.level;
+    const closestParent = findClosestParent(requestedTileKey, quadTreeIndex, quadTreeIndexRoot);
+    if (!closestParent) {
+        return Promise.reject(new Error(`Error getting blob for Tile: ${requestedTileKey.toHereTile()}`));
+    }
+    return {
+        response: await olp_sdk_dataservice_api_1.BlobApi.getBlob(blobRequestBuilder, {
+            dataHandle: closestParent.parentQuad.dataHandle,
+            layerId: params.layerId,
+            billingTag: request.getBillingTag()
+        }),
+        parentTileKey: closestParent.tileKey
+    };
+}
+/**
+ * Helper function to get the closest parent quad for a given tile key.
+ * @hidden
+ */
+function findClosestParent(tileKey, quadTreeIndex, quadTreeIndexRoot) {
+    const subQuads = quadTreeIndex.subQuads ?? [];
+    const parentQuads = quadTreeIndex.parentQuads ?? [];
+    // First, iterate through the sub quad trees, starting from lowest level up to the quad tree index root
+    let currentTileKey = tileKey;
+    while (currentTileKey.level >= quadTreeIndexRoot.level) {
+        const currentDelta = currentTileKey.level - quadTreeIndexRoot.level;
+        const subHereTile = currentTileKey.getSubHereTile(currentDelta);
+        const subQuad = subQuads.find((item) => item.subQuadKey === subHereTile);
+        if (subQuad) {
+            return { parentQuad: subQuad, tileKey: currentTileKey };
         }
-        catch (error) {
-            continue;
+        // Stop before requesting the parent of the quad tree index root -
+        // that root can be the global root tile (level 0), whose parent()
+        // throws rather than returning another tile.
+        if (currentTileKey.level === quadTreeIndexRoot.level) {
+            break;
         }
+        currentTileKey = currentTileKey.parent();
     }
-    return Promise.reject(new Error(`Error getting blob for Tile: ${JSON.stringify(quadKey)}`));
+    // not found? Find the closest parent quad
+    return parentQuads.reduce((closest, parentQuad) => {
+        const tileKey = olp_sdk_core_1.TileKey.fromHereTile(parentQuad.partition);
+        return !closest || tileKey.level > closest.tileKey.level
+            ? { parentQuad, tileKey }
+            : closest;
+    }, undefined);
 }
 /**
  * The function should request quad tree index for the parent tile with delta 4
@@ -146,7 +140,8 @@ async function fetchQuadTreeIndex(params) {
     }
     const quadTreeIndex = await queryClient.fetchQuadTreeIndex(quadTreeIndexRequest, params.abortSignal);
     if (params.fetchOptions !== olp_sdk_core_1.FetchOptions.OnlineOnly &&
-        quadTreeIndex.subQuads) {
+        (quadTreeIndex.subQuads !== undefined ||
+            quadTreeIndex.parentQuads !== undefined)) {
         cache.put({
             hrn: params.catalogHrn.toString(),
             layerId: params.layerId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@here/olp-sdk-dataservice-read",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Wrapper around a subset of the HERE Open Location Platform Data REST API related to reading data from OLP catalogs",
   "main": "index.js",
   "browser": "index.web.js",