ol-load-geopackage 2.0.0 → 2.1.0

package/API.md

@@ -14,7 +14,10 @@ Parameters:
 
 - string `sqlJsWasmDir` (optional): URL or path relative to root of folder containing sql-wasm.wasm file. Default value is root folder.
 
-(No return value)
+Returns a Promise which delivers:
+- WebAssembly: sql.js SQLITE database access library
+
+Note that unless you require access to sql.js outside ol-load-geopackage, then the returned promise can be ignored; [loadGpkg()](#loadgpkggpkgfile-displayprojection) will wait if necessary and handle any errors loading the WASM file. The only other reason to monitor the returned promise is if you are unlikely to invoke loadGpkg() for a long time and want to ensure the WASM has been successfully loaded.
 
 If you want to load the associated WebAssembly binary (sql-wasm.wasm) from an external Content Delivery Network (CDN) then it is important that you load the WASM file that matches the version of the sql.js module being imported by ol-load-geopackage. Thus you will need to incorporate the _sql_js_version_ constant in the calling parameter, for example (from the proj4_example):
 

package/README.md

@@ -10,11 +10,11 @@ The current version was tested with OpenLayers 10.7, but should work with OpenLa
 
 Each example (in the [GitHub repository](https://github.com/richard-thomas/ol-load-geopackage)) is presented as HTML/JavaScript source code and as directly viewable web pages (built using both [Vite](https://vite.dev/) and the [Webpack](https://webpack.js.org/) module bundler).
 
-- Basic Example: web page: [Vite](https://richard-thomas.github.io/ol-load-geopackage/examples-vite/basic_example.html), [Webpack](https://richard-thomas.github.io/ol-load-geopackage/examples/dist/basic_example.html) (sources: [Vite HTML](https://github.com/richard-thomas/ol-load-geopackage/tree/master/examples-vite/basic_example.html), [Webpack HTML](https://github.com/richard-thomas/ol-load-geopackage/tree/master/examples/dist/basic_example.html),
+- Basic Example: web page: [Vite](https://richard-thomas.github.io/ol-load-geopackage/examples-vite/dist/basic_example.html), [Webpack](https://richard-thomas.github.io/ol-load-geopackage/examples/dist/basic_example.html) (sources: [Vite HTML](https://github.com/richard-thomas/ol-load-geopackage/tree/master/examples-vite/basic_example.html), [Webpack HTML](https://github.com/richard-thomas/ol-load-geopackage/tree/master/examples/dist/basic_example.html),
 [JavaScript (common)](https://github.com/richard-thomas/ol-load-geopackage/tree/master/examples/src/basic_example.js))
   - Loads vector tables and associated QGIS "layer_styles" SLD XML strings from an OGC GeoPackage and render all tables as layers on an OpenLayers map. Displays details of package contents.
 
-- Proj4 Example: web page: [Vite](https://richard-thomas.github.io/ol-load-geopackage/examples-vite/proj4_example.html), [Webpack](https://richard-thomas.github.io/ol-load-geopackage/examples/dist/proj4_example.html) (sources: [Vite HTML](https://github.com/richard-thomas/ol-load-geopackage/tree/master/examples-vite/proj4_example.html), [Webpack HTML](https://github.com/richard-thomas/ol-load-geopackage/tree/master/examples/dist/proj4_example.html),
+- Proj4 Example: web page: [Vite](https://richard-thomas.github.io/ol-load-geopackage/examples-vite/dist/proj4_example.html), [Webpack](https://richard-thomas.github.io/ol-load-geopackage/examples/dist/proj4_example.html) (sources: [Vite HTML](https://github.com/richard-thomas/ol-load-geopackage/tree/master/examples-vite/proj4_example.html), [Webpack HTML](https://github.com/richard-thomas/ol-load-geopackage/tree/master/examples/dist/proj4_example.html),
 [JavaScript (common)](https://github.com/richard-thomas/ol-load-geopackage/tree/master/examples/src/proj4_example.js))
   - Used in conjunction with Proj4js module to enable additional projections to those built in to OpenLayers. These other projections can be for the input source data and/or the output display projection. Also demonstrates loading required sql.js WebAssembly binary (WASM) from an external Content Delivery Network (CDN) site.
 
@@ -37,7 +37,7 @@ Use Node.js to install the NPM package: [ol-load-geopackage](https://www.npmjs.c
 npm install --save ol-load-geopackage
 ```
 
-After running npm install, the sql.js WebAssembly file (sql-wasm.wasm) will need to be copied from folder _node_modules/sql.js/dist/_ to a folder where the web page can load it from.
+After running npm install, the sql.js WebAssembly file (sql-wasm.wasm) will need to be copied from folder _node_modules/sql.js/dist/_ to a folder where the web page can load it from (unless you plan to load it from a CDN).
 
 ## Basic usage
 
@@ -46,8 +46,13 @@ This package must be imported as a module - it is not designed to be loaded dire
 ```javascript
 import { initSqlJsWasm, loadGpkg } from 'ol-load-geopackage';
 
-initSqlJsWasm();
-var gpkgPromise = loadGpkg(<gpkgFile>, <displayProjection>);
+initSqlJsWasm('.');
+var gpkgPromise;
+try {
+    gpkgPromise = loadGpkg(<gpkgFile>, <displayProjection>);
+} catch (error) {
+    alert('loadGpkg() failed before Promise set-up:\n' + error);
+}
 gpkgPromise
     .then(([dataFromGpkg, sldsFromGpkg]) => {
         for (var table in dataFromGpkg) {
@@ -59,10 +64,10 @@ gpkgPromise
             //   sldsFromGpkg[layerName]
         }
     })
-    .catch(error => alert('ol-load-geopackage error: ' + error));
+    .catch(error => alert('ol-load-geopackage error:\n' + error));
 ```
 
-Note that the _initSqlJsWasm()_ statement will start the asynchronous loading of the required sql.js WebAssembly binary file sql-wasm.wasm (from the root folder if no path specified), so is best placed early in the code.
+Note that the _initSqlJsWasm()_ statement will start the asynchronous loading of the required sql.js WebAssembly binary file sql-wasm.wasm (from the current folder in this case), so is best placed early in the code.
 
 ### Building with Webpack
 
@@ -99,13 +104,13 @@ npm install
 npm run-script sql-install
 npm run-script build
 ```
-You can then test the output code placed in the dist folder in a web browser at URL [http://localhost:8000/](http://localhost:8000/) using Vite's built in HTTP server with:
+Although you can then test the output code placed in the dist folder using the python HTTP server method (as in the Webpack example), it is easier to use Vite's built in HTTP server with:
 
 ```bash
 npm run-script preview
 ```
 
-The Vite dev-server can be used to automatically re-build, act as a webhost and trigger the browser to reload every time the code changes. The following script commands (defined in [package.json](https://github.com/richard-thomas/ol-load-geopackage/tree/master/examples-vite/package.json)) will start the dev-server at a top level _index.html_ file which has links to the 2 examples:
+The Vite dev server can be used to automatically re-build, act as a webhost and trigger the browser to reload every time the code changes. The following script commands (defined in [package.json](https://github.com/richard-thomas/ol-load-geopackage/tree/master/examples-vite/package.json)) will start the dev server at a top level _index.html_ file which has links to the 2 examples:
 
 ```bash
 npm run-script dev
@@ -115,9 +120,9 @@ npm run-script dev
 
 The JavaScript module has 3 exported functions/constants which are described in the separate [API Specification](API.md):
 
-- [initSqlJsWasm()](#initsqljswasmsqljswasmdir) - Initialisation: start loading of required sql.js WASM file
-- [loadGpkg()](#loadgpkggpkgfile-displayprojection) - start loading and data extraction of GeoPackage
-- [sql_js_version](#sql_js_version) - NPM version number of  underlying sql.js module
+- [initSqlJsWasm()](API.md#initsqljswasmsqljswasmdir) - Initialisation: start loading of required sql.js WASM file
+- [loadGpkg()](API.md#loadgpkggpkgfile-displayprojection) - start loading and data extraction of GeoPackage
+- [sql_js_version](API.md#sql_js_version) - NPM version number of  underlying sql.js module
 
 ## Migrating from ol-load-geopackage v1.x.x
 
@@ -126,11 +131,11 @@ In v1.x.x the sql.js WASM file (sql-wasm.wasm) was implicitly loaded from the cu
 ```javascript
 import loadGpkg from 'ol-load-geopackage';
 ```
-From v2.0.0 the WASM must be explicitly loaded by invoking the new [initSqlJsWasm()](#initsqljswasmsqljswasmdir) function, with the sql-wasm.wasm file placed in the root folder if not specified as a parameter:
+From v2.0.0 the WASM must be explicitly loaded by invoking the new [initSqlJsWasm()](API.md#initsqljswasmsqljswasmdir) function, with the sql-wasm.wasm file placed in the root folder if not specified as a parameter. In this example, it is placed in the current folder to mimic v1.x.x behaviour:
 
 ```javascript
 import { initSqlJsWasm, loadGpkg } from 'ol-load-geopackage';
-initSqlJsWasm();
+initSqlJsWasm('.');
 ```
 
 ## Contributions

package/dist/ol-load-geopackage.js

@@ -7,7 +7,7 @@
  *  Both Sources and SLDs are returned in objects with table names used as keys.
  */
 
-import initSqlJs from "sql.js";
+import initSqlJs from 'sql.js';
 import {get as ol_proj_get} from 'ol/proj.js';
 import ol_source_Vector from 'ol/source/Vector.js';
 import ol_format_WKB from 'ol/format/WKB.js';
@@ -25,13 +25,18 @@ var promiseSqlWasmLoaded;
 export { initSqlJsWasm, loadGpkg, sql_js_version };
 
 /**
- * Initialisation: start asynchronous loading of WASM file required by sql.js
+ * Initialisation: start asynchronous loading of WASM file required by sql.js.
+ * Note that unless you require access to sql.js outside ol-load-geopackage,
+ * then the returned promise can be ignored; loadGpkg() will wait if necessary
+ * and handle any errors loading the WASM file.
  * @param {string} sqlJsWasmDir - URL of folder containing sql-wasm.wasm file to load for sql.js
+ * @returns {Promise} Promise which delivers:
+ *   {WebAssembly} sql.js SQLITE database access library
  */
 function initSqlJsWasm(sqlJsWasmDir) {
     // If the WASM file location isn't specified look for it in the root folder
     if (sqlJsWasmDir === undefined) {
-        sqlJsWasmDir = "";
+        sqlJsWasmDir = '';
     }
 
     // For reading OGC GeoPackage files, use the sql.js SQLite reader;
@@ -46,6 +51,8 @@ function initSqlJsWasm(sqlJsWasmDir) {
                 `${sqlJsWasmDir}/\n` +
                 `[sql.js error message]: ${error}`);
         });
+
+    return promiseSqlWasmLoaded;
 }
 
 /**
@@ -58,16 +65,22 @@ function initSqlJsWasm(sqlJsWasmDir) {
  */
 function loadGpkg(gpkgFile, displayProjection) {
 
-    // Start OGC GeoPackage load and processing to extract data/SLDs
-    var gpkgReadPromise = readRawGpkg(gpkgFile);
+    // Check SQL WASM loading was initiated
+    if (promiseSqlWasmLoaded === undefined) {
+        throw new Error('SQL WASM loading has not started; ' +
+            'did you forget to run initSqlJsWasm() first?');
+    }
 
     // Check if we have a definition for the display projection (SRS)
     if (!ol_proj_get(displayProjection)) {
-        throw new Error("Missing requested display projection [" +
+        throw new Error('Missing requested display projection [' +
             displayProjection +
             '] - can be added beforehand with ol/proj/proj4');
     }
 
+    // Start OGC GeoPackage load and processing to extract data/SLDs
+    var gpkgReadPromise = readRawGpkg(gpkgFile);
+
     return Promise.allSettled([promiseSqlWasmLoaded, gpkgReadPromise])
         .then((results) => {
             if (results[0].status === 'rejected') {
@@ -93,7 +106,7 @@ function loadGpkg(gpkgFile, displayProjection) {
 function readRawGpkg(gpkgFile) {
     return new Promise(function(succeed, fail) {
         var oReq = new XMLHttpRequest();
-        oReq.responseType = "arraybuffer";
+        oReq.responseType = 'arraybuffer';
         oReq.onreadystatechange = function() {
 
             // When request finished and response is ready
@@ -108,7 +121,7 @@ function readRawGpkg(gpkgFile) {
                 }
             }
         };
-        oReq.open("GET", gpkgFile);
+        oReq.open('GET', gpkgFile);
         oReq.send();
     });
 }
@@ -158,9 +171,9 @@ function processGpkgData(loadedGpkgFile, gpkgArrayBuffer, sqlWasm,
         while (stmt.step()) {
             let row = stmt.get();
             featureTableNames.push({
-                "table_name": row[0],
-                "srs_id": row[1].toString(),
-                "geometry_column_name": row[2]
+                'table_name': row[0],
+                'srs_id': row[1].toString(),
+                'geometry_column_name': row[2]
             });
         }
     }
@@ -177,7 +190,7 @@ function processGpkgData(loadedGpkgFile, gpkgArrayBuffer, sqlWasm,
         WHERE gpkg_contents.table_name='layer_styles'
     `);
     if (stmt.step()) {
-        stmt = db.prepare("SELECT f_table_name,styleSLD FROM layer_styles");
+        stmt = db.prepare('SELECT f_table_name,styleSLD FROM layer_styles');
         while (stmt.step()) {
             let row = stmt.get();
             sldsFromGpkg[row[0]] = row[1];
@@ -194,7 +207,7 @@ function processGpkgData(loadedGpkgFile, gpkgArrayBuffer, sqlWasm,
 
         // Check if we have a definition for the data projection (SRS)
         if (!ol_proj_get(tableDataProjection)) {
-            throw new Error("Missing data projection [" +
+            throw new Error('Missing data projection [' +
                 tableDataProjection + '] for table "' + table_name +
                 '" - can be added beforehand with ol/proj/proj4');
         }
@@ -226,7 +239,7 @@ function processGpkgData(loadedGpkgFile, gpkgArrayBuffer, sqlWasm,
         }
 
         // For information only, save details of original projection (SRS)
-        vectorSource.setProperties({"origProjection": tableDataProjection});
+        vectorSource.setProperties({'origProjection': tableDataProjection});
         dataFromGpkg[table_name] = vectorSource;
     }
 /*
@@ -263,7 +276,7 @@ function parseGpkgGeom(gpkgBinGeom) {
             envelopeSize = 64;
             break;
         default:
-            throw new Error("Invalid geometry envelope size flag in GeoPackage");
+            throw new Error('Invalid geometry envelope size flag in GeoPackage');
     }
 /*
     // Extract SRS (EPSG code)
@@ -281,11 +294,11 @@ function parseGpkgGeom(gpkgBinGeom) {
     // DEBUG: display other properties of the feature
     console.log('gpkgBinGeom Header: ' + (littleEndian ? 'Little' : 'Big')
         + ' Endian');
-    console.log("gpkgBinGeom Magic: 0x${gpkgBinGeom[0].toString(16)}${gpkgBinGeom[1].toString(16)}");
-    console.log("gpkgBinGeom Version:", gpkgBinGeom[2]);
-    console.log("gpkgBinGeom Flags:", flags);
-    console.log("gpkgBinGeom srs_id:", srsId);
-    console.log("gpkgBinGeom envelope size (bytes):", envelopeSize);
+    console.log('gpkgBinGeom Magic: 0x${gpkgBinGeom[0].toString(16)}${gpkgBinGeom[1].toString(16)}');
+    console.log('gpkgBinGeom Version:', gpkgBinGeom[2]);
+    console.log('gpkgBinGeom Flags:', flags);
+    console.log('gpkgBinGeom srs_id:', srsId);
+    console.log('gpkgBinGeom envelope size (bytes):', envelopeSize);
 */
     // Extract WKB which starts after variable-size "envelope" field
     var wkbOffset = envelopeSize + 8;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ol-load-geopackage",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Loads OGC GeoPackage vector data tables into OpenLayers Vector Sources",
   "files": [
     "dist/",
@@ -24,8 +24,7 @@
   "license": "ISC",
   "dependencies": {
     "ol": ">=6.7.0",
-    "sql.js": "^1.6.1",
-    "util": "^0.12.4"
+    "sql.js": "^1.6.1"
   },
   "repository": {
     "type": "git",