ol-load-geopackage 2.0.1 → 2.2.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):
 
@@ -29,8 +32,7 @@ initSqlJsWasm(sqlJsWasmDir);
 Begin asynchronous loading of a single OGC GeoPackage, then extract vector data tables into OpenLayers Vector Sources, transforming the data (if necessary) to match the specified display projection. If a "layer_styles" table is found (as generated by QGIS [Package Layers](https://docs.qgis.org/3.16/en/docs/user_manual/processing_algs/qgis/database.html#package-layers) Processing Toolbox command), it will extract the constituent SLD XML styling data associated with each vector data table.
 
 Parameters:
-
-- string `gpkgFile`: OGC GeoPackage file URL or path relative to root
+- string|File|Blob|URL `gpkgFile`: OGC GeoPackage URL string or File/URL object (URL can be path relative to document's base URI)
 - string `displayProjection`: Map display projection for output sources (e.g. 'EPSG:3857'). Note that projections not built in to OpenLayers must be defined before calling the function. This is most easily done using the Proj4JS library  - see Proj4 [Example](README.md#examples-in-github-repository).
 
 Returns a Promise which delivers an array of 2 objects:
@@ -55,10 +57,16 @@ Notes:
 3. In the output GeoPackage from QGIS [Package Layers](https://docs.qgis.org/3.16/en/docs/user_manual/processing_algs/qgis/database.html#package-layers) the "table name" used for each vector data table will be exactly the same as the "layer name" used to index the SLD style strings in the "layer_styles" table.
 
 Errors thrown on these events:
-- Unable to load WebAssembly binary (sql-wasm.wasm)
-- Unable to load requested OGC GeoPackage
-- Missing requested display projection
+- SQL WASM loading not previously started, i.e. mmissing a preceding call to initSqlJsWasm()
+- ol/proj is missing the requested display projection (can be added beforehand using ol/proj/proj4.js)
+ 
+Promise rejected on these events:
+- Unable to load SQLite JS WebAssembly binary (sql-wasm.wasm)
+- `gpkgFile` parameter not of type URL string or URL/File/Blob object
+- Unable to load requested GeoPackage
 - Missing a data projection (from any of Geopackage tables)
+- Failure trying to extract feature tables from GeoPackage
+- Invalid geometry envelope size flag in a GeoPackage table feature
 
 
 ## sql_js_version

package/README.md

@@ -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
 
@@ -47,7 +47,12 @@ This package must be imported as a module - it is not designed to be loaded dire
 import { initSqlJsWasm, loadGpkg } from 'ol-load-geopackage';
 
 initSqlJsWasm('.');
-var gpkgPromise = loadGpkg(<gpkgFile>, <displayProjection>);
+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,7 +64,7 @@ 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 current folder in this case), so is best placed early in the code.
@@ -116,7 +121,7 @@ npm run-script dev
 The JavaScript module has 3 exported functions/constants which are described in the separate [API Specification](API.md):
 
 - [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
+- [loadGpkg()](API.md#loadgpkggpkgfile-displayprojection) - start asynchronous 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

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<WebAssembly>} Promise which delivers:
+ *   sql.js SQLITE database access library WebAssembly
  */
 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;
@@ -41,44 +46,62 @@ function initSqlJsWasm(sqlJsWasmDir) {
     });
     promiseSqlWasmLoaded
         .catch(error => {
-            // Only need report error here - any later calls to loadGpkg() will throw error
-            console.error(`initSqlJsWasm() unable to load SQLite JS binary (sql-wasm.wasm) from folder:\n` +
-                `${sqlJsWasmDir}/\n` +
-                `[sql.js error message]: ${error}`);
+            // Only reporting error to console here to simplify error handling;
+            // Error will be dealt with on later call(s) to loadGpkg()
+            console.error('initSqlJsWasm() unable to load SQLite JS binary ' +
+                `(sql-wasm.wasm) from URL folder:\n` +
+                `  ${sqlJsWasmDir}/\n` +
+                error);
         });
+
+    return promiseSqlWasmLoaded;
 }
 
 /**
  * Wrapper to load a single OGC GeoPackage
- * @param {string} gpkgFile - OGC GeoPackage file path
+ * @param {(string|File|Blob|URL)} gpkgFile - OGC GeoPackage URL string or File/URL object
  * @param {string} displayProjection - map display projection (e.g. EPSG:3857)
- * @returns {Promise} Promise which delivers array of 2 objects:
+ * @returns {Promise<[Object, Object]>} Promise delivering array of 2 objects:
  *   data tables (OpenLayers vector sources, indexed by table name),
  *   styles (SLD layer_styles XML strings, indexed by layer name)
+ * @throws {Error} If SQL WASM loading not previously started
+ * @throws {Error} If ol/proj is missing the requested display projection
  */
 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') {
-                throw new Error('Unable to load SQLite JS binary (sql-wasm.wasm)');
+                // Throw (initSqlJs() failure) will convert to rejected promise
+                throw new Error(
+                    'Unable to load SQLite JS binary (sql-wasm.wasm).\n' +
+                    results[0].reason);
             }
             if (results[1].status === 'rejected') {
-                throw new Error(`Unable to read raw GeoPackage data from file: ${gpkgFile}`);
+                // Propagate exact Error object from readRawGpkg().
+                // Throw will convert to rejected promise
+                throw results[1].reason;
             }
             const sqlWasm = results[0].value;
-            const gpkgArrayBuffer = results[1].value;
-            return processGpkgData(gpkgFile, gpkgArrayBuffer, sqlWasm, displayProjection);
+            const gpkgByteArray = results[1].value;
+            const gpkgFileName = (gpkgFile instanceof File) ? gpkgFile.name : gpkgFile.toString();
+            return processGpkgData(gpkgFileName, gpkgByteArray, sqlWasm, displayProjection);
         }
     );
 }
@@ -87,44 +110,60 @@ function loadGpkg(gpkgFile, displayProjection) {
 
 /**
  * Read raw data from source for a single OGC GeoPackage
- * @param {string} gpkgFile - OGC GeoPackage file path
- * @returns {Promise} Promise with Gpkg contents in ArrayBuffer format
+ * @param {(string|File|Blob|URL)} input - OGC GeoPackage URL string or File/URL object
+ * @returns {Promise<Uint8Array>} Promise with Gpkg contents in byte array format
  */
-function readRawGpkg(gpkgFile) {
-    return new Promise(function(succeed, fail) {
-        var oReq = new XMLHttpRequest();
-        oReq.responseType = "arraybuffer";
-        oReq.onreadystatechange = function() {
+async function readRawGpkg(input) {
 
-            // When request finished and response is ready
-            if (this.readyState == 4) {
-                var gpkgArrayBuffer = this.response;
-                if (this.status === 200 && gpkgArrayBuffer) {
-                    succeed(gpkgArrayBuffer);
-                } else {
-                    fail(new Error(
-                        'Requested GPKG file could not be loaded: ' +
-                        gpkgFile));
-                }
-            }
-        };
-        oReq.open("GET", gpkgFile);
-        oReq.send();
-    });
+    // Fetch() or File/Blob object (both have the equivalent methods we need)
+    let gpkgSource;
+
+    // File object is a specific type of Blob
+    if (input instanceof Blob) {
+        gpkgSource = input;
+    } else if (typeof input === 'string' || input instanceof URL) {
+        const response = await fetch(input);
+        if (!response.ok) {
+            // Throw will convert to rejected promise (as an async function)
+            throw new Error('GPKG file could not be loaded from URL:\n' +
+                `  ${input}\n` +
+                `Response: (${response.status}) ${response.statusText}`);
+        }
+        gpkgSource = response;
+    } else {
+        // Throw will convert to rejected promise (as an async function)
+        throw new TypeError('Input must be URL string or URL/File/Blob object');
+    }
+
+    try {
+        // Use .bytes() method if available (most browsers since Jan 2025)
+        if (typeof gpkgSource.bytes === 'function') {
+            return await gpkgSource.bytes();
+        }
+
+        // Fallback approach: Convert ArrayBuffer to Uint8Array
+        //console.log('readRawGpkg(): using fallback .arrayBuffer() + Uint8Array() methods');
+        const buffer = await gpkgSource.arrayBuffer();
+        return new Uint8Array(buffer);
+    } catch (error) {
+        // Throw will convert to rejected promise (as an async function)
+        throw new Error('Requested GPKG file could not be loaded.\n' + error);
+    }
 }
 
 /**
- * Process OGC GeoPackage (SQLite database) once loaded
- * @param {*} loadedGpkgFile - name of GeoPackage file (for diagnostics only)
- * @param {ArrayBuffer} gpkgArrayBuffer - ArrayBuffer containing Gpkg data read
+ * Process OGC GeoPackage (based on SQLite database) once loaded
+ * @param {string} loadedGpkgFile - name of GeoPackage file (for diagnostics only)
+ * @param {Uint8Array} gpkgByteArray - Byte Array containing Gpkg data read
  * @param {WebAssembly} sqlWasm - sql.js SQLITE database access library
  * @param {string} displayProjection - map display projection (e.g. EPSG:3857)
- * @returns {object[]} array of 2 objects: [<data tables>, <slds>]
- *   <data tables>: OpenLayers vector sources, indexed by table name
- *   <slds>: SLD XML strings, indexed by layer name
+ * @returns {[Object, Object]} Array of 2 objects:
+ *   data tables (OpenLayers vector sources, indexed by table name),
+ *   styles (SLD layer_styles XML strings, indexed by layer name) 
+ * @throws {Error} If unable to extract feature tables from OGC GeoPackage file
+ * @throws {Error} If ol/proj is missing required projection for a data table
  */
-function processGpkgData(loadedGpkgFile, gpkgArrayBuffer, sqlWasm,
-    displayProjection) {
+function processGpkgData(loadedGpkgFile, gpkgByteArray, sqlWasm, displayProjection) {
     var db;
 
     // Data and associated SLD styles loaded both from GPKG
@@ -134,9 +173,6 @@ function processGpkgData(loadedGpkgFile, gpkgArrayBuffer, sqlWasm,
     // DEBUG: measure GPKG processing time
     //var startProcessing = Date.now();
 
-    // Convert Array Buffer to Byte Array for SQLite
-    var gpkgByteArray = new Uint8Array(gpkgArrayBuffer);
-
     try {
         db = new sqlWasm.Database(gpkgByteArray);
 
@@ -158,16 +194,16 @@ 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]
             });
         }
     }
     catch (err) {
         throw new Error(
-            'Unable to extract feature tables from OGC GeoPackage file "' +
-            loadedGpkgFile + '":\n' + err);
+            'Unable to extract feature tables from OGC GeoPackage file.\n' +
+            err);
     }
 
     // Extract SLD styles for each layer (if styles included in the gpkg)
@@ -177,7 +213,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,11 +230,12 @@ 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');
         }
 
+        //console.log(`Extracting table "${table_name}" (SRS: ${tableDataProjection})`);
         stmt = db.prepare("SELECT * FROM '" + table_name + "'");
         let vectorSource = new ol_source_Vector();
         let geometry_column_name = table.geometry_column_name;
@@ -226,7 +263,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;
     }
 /*
@@ -241,8 +278,9 @@ function processGpkgData(loadedGpkgFile, gpkgArrayBuffer, sqlWasm,
 /**
  * Extract (SRS ID &) WKB from an OGC GeoPackage feature
  * (i.e. strip off the variable length header)
- * @param {object} gpkgBinGeom feature geometry property (includes header)
- * @returns feature geometry in WKB (Well Known Binary) format
+ * @param {Uint8Array} gpkgBinGeom - feature geometry property (includes header)
+ * @returns {Uint8Array} feature geometry in WKB (Well Known Binary) format
+ * @throws {Error} If invalid geometry envelope size flag in GeoPackage
  */
 function parseGpkgGeom(gpkgBinGeom) {
     var flags = gpkgBinGeom[3];
@@ -263,7 +301,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 +319,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.1",
+  "version": "2.2.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",