@masterportal/masterportalapi 2.7.0 → 2.9.0

package/CHANGELOG.md

@@ -5,13 +5,38 @@
 
 ## Unreleased - in development
 ### Added
+
 ### Changed
 
 ### Deprecated
 
 ### Removed
+
 ### Fixed
 
+---
+
+## 2.9.0 - 2022-10-25
+### Added
+
+### Changed
+- Exports in src/rawLayerList and src/crs.js changed to module.exports to provide the possibility to stub the functions with sinon in masterportal.
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+---
+
+## 2.8.0 - 2022-10-04
+### Added
+- Issue #814: Adding optional error callbacks and availability detection to layers.
+- Added possibility to set initial features for layer vectorBase.
+
+---
+
 ## 2.7.0 - 2022-09-14
 ### Changed
 - The following packages have been updated:

package/README.md

@@ -10,6 +10,13 @@ If you want to create a 3d map, you have to provide the peer dependency cesium.
 
 By importing the project by module name like ``import ... from "masterportalAPI"``, most bundlers and bundler configurations will include the whole masterportalAPI. If you only need a subset of the provided functions and want to keep your build clean, directly import the needed functions like ``import {createMap} from "masterportalAPI/src/map.js``.
 
+## Error Handling
+
+1. Error event callback: The methods `createMap` and `addLayer` both optionally accept error event callbacks that are called with OpenLayers error events (tileloaderror, imageloaderror, featuresloaderror, error).
+2. Ping: A method that returns a Promise. This resolves to the status code of the layer's GetCapabilities request, which can be used to decide if the service is reachable and usable at all.
+
+Both methods may be required for useful user feedback. For example, a WMS may answer a tile request with 404 if no tile is available for a region, but may be fully available within its specification. This may throw an error while the service itself is available as specified. It is up to the using implementation how to react, how often to ping, and so on.
+
 ## Scripts
 
 |Script|Effect|

package/example/config/services.json

@@ -47,7 +47,7 @@
   {
     "id": "4001",
     "name": "Gelaende",
-    "url": "https://daten-hamburg.de/gdi3d/datasource-data/Gelaende ",
+    "url": "https://daten-hamburg.de/gdi3d/datasource-data/Gelaende",
     "typ": "Terrain3D",
     "cesiumTerrainProviderOptions": {
       "requestVertexNormals": true

package/example/index.js

@@ -11,6 +11,10 @@ import portalConfig from "./config/portal.json";
 import localGeoJSON from "./config/localGeoJSON.js";
 import {load3DScript} from "../src/lib/load3DScript";
 
+function errorCallback (errorEvent) {
+    console.error("This is an error event:", errorEvent);
+}
+
 //* Add elements to window to play with API in console
 window.mpapi = {
     ...mpapi,
@@ -94,7 +98,7 @@ document.getElementById("layer-visibility").addEventListener("click", function (
     });
 });
 
-map2D = mapsAPI.map.createMap(config, "2D");
+map2D = mapsAPI.map.createMap(config, "2D", {errorCallback});
 services.push(localService);
 // */
 
@@ -148,7 +152,18 @@ services.find(({id}) => id === "5001").style = styleOaf;
 //* SYNCHRONOUS EXAMPLE: layerConf is known
 window.mpapi.map = map2D;
 
-["2001", "2002", "1002", "3001", "5001"].forEach(id => window.mpapi.map.addLayer(id));
+["2001", "2002", "1002", "3001", "5001"].forEach(id => window.mpapi.map.addLayer(id, {errorCallback}));
+
+// ping all layers
+services
+    .map(service => ({
+        ping: mpapi.ping(service),
+        service
+    }))
+    .forEach(({ping, service}) => ping
+        // eslint-disable-next-line no-console
+        .then(statusCode => console.log(`Service ${service.id} pinged; returned ${statusCode}.`))
+        .catch(console.error));
 
 // */
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@masterportal/masterportalapi",
   "author": "Implementierungspartnerschaft Masterportal <info@masterportal.org> (https://www.masterportal.org)",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "license": "MIT",
   "description": "Basic functions of the Masterportal as api",
   "repository": {

package/src/crs.js

@@ -22,7 +22,7 @@ function addAliasForWFSFromGeoserver (epsgCode) {
  * @param {string} name - projection name as written in [0] position of namedProjections
  * @returns {(object|undefined)} proj4 projection object or undefined
  */
-export function getProjection (name) {
+function getProjection (name) {
     return proj4.defs(name);
 }
 
@@ -33,7 +33,7 @@ export function getProjection (name) {
     ]] - projection name, projection definition string
  * @returns {undefined}
  */
-export function registerProjections (namedProjections = defaults.namedProjections) {
+function registerProjections (namedProjections = defaults.namedProjections) {
     proj4.defs(namedProjections);
     register(proj4);
     namedProjections.forEach(projection => {
@@ -48,7 +48,7 @@ export function registerProjections (namedProjections = defaults.namedProjection
  * Returns all known projections.
  * @returns {object[]} array of projection objects with their name added
  */
-export function getProjections () {
+function getProjections () {
     const projections = Object
         .keys(proj4.defs)
         .map(name => Object.assign(proj4.defs(name), {name}));
@@ -64,7 +64,7 @@ export function getProjections () {
  * @param {ol.Map} map - map to get projection of
  * @returns {string} active projection name of map
  */
-export function getMapProjection (map) {
+function getMapProjection (map) {
     return map.getView().getProjection().getCode();
 }
 
@@ -87,7 +87,7 @@ function getProj4Projection (projection) {
  * @param {number[]} point - point to project
  * @returns {number[]|undefined} transformed point
  */
-export function transform (sourceProjection, targetProjection, point) {
+function transform (sourceProjection, targetProjection, point) {
     const source = getProj4Projection(sourceProjection),
         target = getProj4Projection(targetProjection);
 
@@ -106,7 +106,7 @@ export function transform (sourceProjection, targetProjection, point) {
  * @param {number[]} point - point to project
  * @returns {number[]|undefined} new point or undefined
  */
-export function transformToMapProjection (map, sourceProjection, point) {
+function transformToMapProjection (map, sourceProjection, point) {
     return transform(sourceProjection, getMapProjection(map), point);
 }
 
@@ -117,6 +117,16 @@ export function transformToMapProjection (map, sourceProjection, point) {
  * @param {number[]} point - point to project
  * @returns {(number[]|undefined)} new point or undefined
  */
-export function transformFromMapProjection (map, targetProjection, point) {
+function transformFromMapProjection (map, targetProjection, point) {
     return transform(getMapProjection(map), targetProjection, point);
 }
+
+module.exports = {
+    transformFromMapProjection,
+    transformToMapProjection,
+    transform,
+    getMapProjection,
+    getProjections,
+    registerProjections,
+    getProjection
+};

package/src/index.js

@@ -14,6 +14,7 @@ import Tileset from "./layer/tileset";
 import * as layerLib from "./layer/lib";
 import {search, setGazetteerUrl} from "./searchAddress";
 import setBackgroundImage from "./lib/setBackgroundImage";
+import ping from "./lib/ping";
 
 export {
     createMapView,
@@ -31,6 +32,7 @@ export {
     setBackgroundImage,
     setGazetteerUrl,
     rawLayerList,
+    ping,
     search,
     crs
 };

package/src/layer/wms.js

@@ -5,7 +5,7 @@ import TileGrid from "ol/tilegrid/TileGrid";
 import ImageWMS from "ol/source/ImageWMS.js";
 import {get as getProjection} from "ol/proj";
 
-import {getLayerWhere} from "../rawLayerList";
+import {rawLayerList} from "../index.js";
 
 const OLCS_DEFAULT_OLCS_PROJECTION_CRS = "EPSG:3857";
 
@@ -176,7 +176,7 @@ export function updateSource (layer) {
  * @returns {(string|undefined)} the gfiURL, or undefined if it could not be constructed
  */
 export function getGfiURL (layer, map, coordinate) {
-    const rawLayer = getLayerWhere({Id: layer.get("id")}),
+    const rawLayer = rawLayerList.getLayerWhere({Id: layer.get("id")}),
         resolution = map.getView().getResolution(),
         projection = map.getView().getProjection(),
         params = Object.assign({

package/src/lib/ping.js

@@ -0,0 +1,63 @@
+/**
+ * Helper function to detect layer availability/usability. Depending on layer
+ * type, the method to infer availability broadly varies.
+ * @param {Object} layerSpecification services.json layer specification
+ * @returns {Promise} resolves to status code of a layer-specific default
+ * request as Number, or null if no request could be made, which should
+ * indicate misconfiguration; defaults to 900 if the request itself failed for
+ * arbitrary reasons (usually CORS-related)
+ */
+export default function ({url, typ, capabilitiesUrl, ...rest}) {
+    const statusCheckUrls = [];
+
+    if (capabilitiesUrl) {
+        statusCheckUrls.push(capabilitiesUrl);
+    }
+    else if (typ === "OAF") {
+        statusCheckUrls.push(url);
+    }
+    else if (typ === "Entities3D") {
+        rest.entities
+            .forEach(entity => entity.url ? statusCheckUrls.push(entity.url) : null);
+    }
+    else if (typ === "TileSet3D" || typ === "Terrain3D") {
+        statusCheckUrls.push(url);
+    }
+    else if (typ === "GeoJSON") {
+        if (!url && rest.features) {
+            // may be a local layer without source url – that's equal to 200
+            return Promise.resolve(200);
+        }
+        if (url) {
+            statusCheckUrls.push(url);
+        }
+    }
+    else if (typ === "VectorTile") {
+        statusCheckUrls.push(url.replaceAll(/\{[xyz]\}/ig, "0"));
+    }
+    else if (typ === "WMTS") {
+        const arbitraryTileRequests = (url ? [url] : rest.urls)
+            .map(entry => entry
+                .replace(/\{Style\}/ig, rest.style)
+                .replace(/\{TileMatrixSet\}/ig, rest.tileMatrixSet)
+                .replaceAll(/\{(TileMatrix|TileRow|TileCol)\}/ig, "0"));
+
+        statusCheckUrls.push(...arbitraryTileRequests);
+    }
+    else if (url) {
+        statusCheckUrls.push(`${url}?service=${typ}&request=GetCapabilities`);
+    }
+
+    if (!statusCheckUrls.length) {
+        return Promise.resolve(null);
+    }
+
+    return Promise
+        .allSettled(statusCheckUrls
+            .map(statusCheckUrl => new Promise((resolve) => fetch(statusCheckUrl, {method: "HEAD"})
+                .then(({status}) => resolve(status))
+                // usually from CORS, treated as 900 here ("proprietary" status code)
+                .catch(() => resolve(900)))))
+        // return highest status code (will indicate erroneous behaviour)
+        .then(codes => Math.max(...codes.map(({value}) => value)));
+}

package/src/maps/map.js

@@ -20,6 +20,7 @@ export default {
     * @param {object}  [settings={}] - settings object
     * @param {object} [settings.mapParams] - additional parameter object that is spread into the ol.Map constructor object
     * @param {function} [settings.callback] - optional callback for layer list loading
+    * @param {function} [settings.errorCallback] - optional callback for layer error events
     * @returns {module:ol/Map~Map} The map.
     */
     createMap: function (config, mapMode = "2D", settings = {}) {

package/src/maps/ol/olMap.js

@@ -11,7 +11,7 @@ import * as vectorBase from "../../layer/vectorBase";
 import * as vectortile from "../../layer/vectorTile";
 import * as oaf from "../../layer/oaf";
 import {createMapView} from "../../maps/mapView";
-import {initializeLayerList, getLayerWhere} from "../../rawLayerList";
+import {rawLayerList} from "../../index.js";
 import {registerProjections} from "../../crs";
 import {setGazetteerUrl} from "../../searchAddress";
 
@@ -32,6 +32,48 @@ const layerBuilderMap = {
     },
     originalAddLayer = Map.prototype.addLayer;
 
+/**
+ * Flattens a Layer/LayerGroup to an array of non-group instances.
+ * @param {ol/layer/Base} layer any layer, possibly a LayerGroup
+ * @returns {ol/layer/Base[]} array of all given layers
+ */
+function flattenLayerGroups (layer) {
+    return layer.getLayers
+        ? layer
+            .getLayers()
+            .getArray()
+            .map(l => flattenLayerGroups(l))
+            .flat(1)
+        : [layer];
+}
+
+/**
+ * Adds an error handling function to an arbitrary layer. The event will be
+ * registered to the tileloaderror, imageloaderror, featuresloaderror, and
+ * generic error event. Depending on the type of layer and error, only one of
+ * these events will fire.
+ * @param {ol/layer/Base} layer Any type of layer implemented.
+ * @param {Function} errorCallback Error callback, called from OL event.
+ * @returns {void} side-effect to layer
+ */
+function injectErrorCallback (layer, errorCallback) {
+    const layers = flattenLayerGroups(layer);
+
+    layers.forEach(l => {
+        const source = l.getSource?.();
+
+        if (source) {
+            source.on?.("tileloaderror", errorCallback);
+            source.on?.("imageloaderror", errorCallback);
+            source.on?.("featuresloaderror", errorCallback);
+            source.on?.("error", errorCallback);
+        }
+        else {
+            console.error("Could not register error callback on layer:", l);
+        }
+    });
+}
+
 /**
  * Adds a layer to the map, or adds a layer to the map by id.
  * This id is looked up within the array of all known services.
@@ -40,18 +82,22 @@ const layerBuilderMap = {
  * if you request the services from the internet.
  *
  * This function is available on all ol/Map instances.
- * @param {(string|ol/Layer)} layerOrId - if of layer to add to map
+ * @param {(string|ol/layer/Base)} layerOrId - if of layer to add to map
  * @param {object} [params] - optional parameter object
  * @param {boolean} [params.visibility=true] - whether added layer is initially visible
  * @param {Number} [params.transparency=0] - how visible the layer is initially
+ * @param {Function} [params.errorCallback=console.error] - callback for layer source error events
  * @returns {?ol.Layer} added layer
  */
-function addLayer (layerOrId, params = {visibility: true, transparency: 0}) {
-    var layer, layerBuilder;
+function addLayer (layerOrId, params = {visibility: true, transparency: 0, errorCallback: console.error}) {
+    const errorCallback = typeof params.errorCallback === "function"
+        ? params.errorCallback
+        : console.error;
+    let layer, layerBuilder;
 
     // if parameter is id, create and add layer with masterportalAPI mechanisms
     if (typeof layerOrId === "string") {
-        const rawLayer = getLayerWhere({id: layerOrId});
+        const rawLayer = rawLayerList.getLayerWhere({id: layerOrId});
 
         if (!rawLayer) {
             console.error("Layer with id '" + layerOrId + "' not found. No layer added to map.");
@@ -65,11 +111,13 @@ function addLayer (layerOrId, params = {visibility: true, transparency: 0}) {
         layer = layerBuilder.createLayer(rawLayer, {}, {map: this});
         layer.setVisible(typeof params.visibility === "boolean" ? params.visibility : true);
         layer.setOpacity(typeof params.transparency === "number" ? (100 - params.transparency) / 100 : 1);
+        injectErrorCallback(layer, errorCallback);
         originalAddLayer.call(this, layer);
         return layer;
     }
 
     // else use original function
+    injectErrorCallback(layerOrId, errorCallback);
     return originalAddLayer.call(this, layerOrId);
 }
 
@@ -93,10 +141,11 @@ Map.prototype.addLayer = addLayer;
  * @param {object}  [settings={}] - setings object
  * @param {object} [settings.mapParams] - additional parameter object that is spread into the ol.Map constructor object
  * @param {function} [settings.callback] - optional callback for layer list loading
+ * @param {function} [settings.errorCallback] – method called on error events
  * @param {String} [mapMode = "2D"] The map mode. '2D' to craete a 2D-map and '3D' to create a 3D-map.
  * @returns {object} map object from ol
  */
-export function createMap (config = defaults, {mapParams, callback} = {}) {
+export function createMap (config = defaults, {mapParams, callback, errorCallback} = {}) {
     registerProjections(config.namedProjections);
     setBackgroundImage(config);
     setGazetteerUrl(config.gazetteerUrl);
@@ -111,10 +160,10 @@ export function createMap (config = defaults, {mapParams, callback} = {}) {
     map.set("id", `map2D_${mapIdCounter++}`);
 
     // extend callback to load configured initial layers
-    initializeLayerList(config.layerConf, (param, error) => {
+    rawLayerList.initializeLayerList(config.layerConf, (param, error) => {
         getInitialLayers(config)
             .forEach(layer => {
-                map.addLayer(layer.id, layer);
+                map.addLayer(layer.id, {errorCallback});
             });
 
         if (typeof callback === "function") {

package/src/rawLayerList.js

@@ -14,7 +14,7 @@ let layerList = [];
  * @param {function} [callback] - called with services after loaded; called with false and error on error
  * @returns {undefined} nothing, add callback to receive layerList
  */
-export function initializeLayerList (layerConf = defaults.layerConf, callback) {
+function initializeLayerList (layerConf = defaults.layerConf, callback) {
     if (Array.isArray(layerConf)) {
         // case: parameter was services.json contents
         layerList = layerConf;
@@ -55,14 +55,14 @@ export function initializeLayerList (layerConf = defaults.layerConf, callback) {
  * @param {object} searchAttributes - key/value-pairs to be searched for, e.g. { typ: "WMS" } to get the first WMS
  * @returns {?object} first layer matching the searchAttributes or null if none was found
  */
-export function getLayerWhere (searchAttributes) {
+function getLayerWhere (searchAttributes) {
     const keys = Object.keys(searchAttributes);
 
     return layerList.find(entry => keys.every(key => entry[key] === searchAttributes[key])) || null;
 }
 
 /** @returns {object[]} complete layerList as initialized */
-export function getLayerList () {
+function getLayerList () {
     return layerList;
 }
 
@@ -72,7 +72,7 @@ export function getLayerList () {
  * @param {string} [featureAttribute] - if given, only one entry of map is returned
  * @returns {?(object|string)} - map of originalName->displayName or name of featureAttribute if specified; if layer or featureAttribute not found, null
  */
-export function getDisplayNamesOfFeatureAttributes (layerId, featureAttribute) {
+function getDisplayNamesOfFeatureAttributes (layerId, featureAttribute) {
     const attributes = getLayerWhere({id: layerId});
 
     if (attributes && typeof featureAttribute === "string") {
@@ -86,3 +86,11 @@ export function getDisplayNamesOfFeatureAttributes (layerId, featureAttribute) {
 
     return null;
 }
+
+
+module.exports = {
+    getLayerWhere,
+    getDisplayNamesOfFeatureAttributes,
+    initializeLayerList,
+    getLayerList
+};

package/test/layer/wmts.test.js

@@ -3,7 +3,7 @@ import {getWidth} from "ol/extent";
 
 import * as wmts from "../../src/layer/wmts";
 
-describe.only("wmts.js", function () {
+describe("wmts.js", function () {
     describe("generateArrays", function () {
         it("should fill the arrays resolutions and matrixIds with numbers", function () {
             const size = getWidth(getProjection("EPSG:3857").getExtent()) / 256,

package/test/lib/ping.test.js

@@ -0,0 +1,69 @@
+import ping from "../../src/lib/ping";
+
+const originalFetch = global.fetch;
+
+describe("ping.js", function () {
+    let mockFetch;
+
+    beforeEach(() => {
+        mockFetch = jest.fn(() => Promise.resolve({
+            status: 200
+        }));
+        global.fetch = mockFetch;
+    });
+
+    afterAll(() => {
+        global.fetch = originalFetch;
+    });
+
+    describe("ping", function () {
+        it("calls an url from the service definition", async function () {
+            const status = await ping({url: "www.example.com", typ: "WMS"});
+
+            expect(status).toBe(200);
+            expect(mockFetch).toHaveBeenCalledWith("www.example.com?service=WMS&request=GetCapabilities", {method: "HEAD"});
+        });
+
+        it("calls 0/0/0 tile for VectorTile services", async function () {
+            const status = await ping({url: "www.example.com/{x}/{y}/{z}", typ: "VectorTile"});
+
+            expect(status).toBe(200);
+            expect(mockFetch).toHaveBeenCalledWith("www.example.com/0/0/0", {method: "HEAD"});
+        });
+
+        it("calls the URL directly for OAF services", async function () {
+            const status = await ping({url: "www.example.com", typ: "OAF"});
+
+            expect(status).toBe(200);
+            expect(mockFetch).toHaveBeenCalledWith("www.example.com", {method: "HEAD"});
+        });
+
+        it("returns 900 on network errors", async function () {
+            mockFetch = jest.fn(() => Promise.resolve({status: 900}));
+            global.fetch = mockFetch;
+
+            const status = await ping({url: "www.example.com", typ: "OAF"});
+
+            expect(status).toBe(900);
+            expect(mockFetch).toHaveBeenCalledWith("www.example.com", {method: "HEAD"});
+        });
+
+        it("returns highest status code on multiple urls", async function () {
+            let counter = 200;
+
+            mockFetch = jest.fn(() => Promise.resolve({status: counter++}));
+            global.fetch = mockFetch;
+
+            const status = await ping({urls: [
+                "www.example.com",
+                "www.example.com/but"
+            ], typ: "WMTS"});
+
+            expect(status).toBe(201);
+            expect(mockFetch)
+                .toHaveBeenCalledWith("www.example.com", {method: "HEAD"});
+            expect(mockFetch)
+                .toHaveBeenCalledWith("www.example.com/but", {method: "HEAD"});
+        });
+    });
+});