js: maplibre protocol has option to throw on missing tile [#321] (#505)

* js: maplibre protocol has option to throw on missing tile [#321]

* js: update docs copy for errorOnMissingTile

* js: 4.1.0

js/CHANGELOG.md

@@ -1,3 +1,7 @@
+4.1.0
+* MapLibre `Protocol` constructor takes `errorOnMissingTile` option. [#505]
+  - Use this only for parity with the overzooming behavior of ZXY tile APIs.
+
 4.0.1
 * fix iife build via esbuild configuration for fflate browser dependency
 

js/examples/leaflet.html

@@ -4,7 +4,7 @@
         <meta charset="utf-8"/>
         <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.0/dist/leaflet.css" />
         <script src="https://unpkg.com/leaflet@1.9.0/dist/leaflet.js"></script>
-        <script src="https://unpkg.com/pmtiles@4.0.1/dist/pmtiles.js"></script>
+        <script src="https://unpkg.com/pmtiles@4.1.0/dist/pmtiles.js"></script>
         <style>
             body, #map {
                 height:100vh;

js/examples/maplibre.html

@@ -4,7 +4,7 @@
         <meta charset="utf-8"/>
         <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@4.7.0/dist/maplibre-gl.css" crossorigin="anonymous">
         <script src="https://unpkg.com/maplibre-gl@4.7.0/dist/maplibre-gl.js" crossorigin="anonymous"></script>
-        <script src="https://unpkg.com/pmtiles@4.0.1/dist/pmtiles.js"></script>
+        <script src="https://unpkg.com/pmtiles@4.1.0/dist/pmtiles.js"></script>
         <style>
             body {
                 margin: 0;

js/examples/maplibre_headers.html

@@ -4,7 +4,7 @@
         <meta charset="utf-8"/>
         <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@4.7.0/dist/maplibre-gl.css" crossorigin="anonymous">
         <script src="https://unpkg.com/maplibre-gl@4.7.0/dist/maplibre-gl.js" crossorigin="anonymous"></script>
-        <script src="https://unpkg.com/pmtiles@4.0.1/dist/pmtiles.js"></script>
+        <script src="https://unpkg.com/pmtiles@4.1.0/dist/pmtiles.js"></script>
         <style>
             body {
                 margin: 0;

js/examples/maplibre_raster_dem.html

@@ -4,7 +4,7 @@
         <meta charset="utf-8"/>
         <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@4.7.0/dist/maplibre-gl.css" crossorigin="anonymous">
         <script src="https://unpkg.com/maplibre-gl@4.7.0/dist/maplibre-gl.js" crossorigin="anonymous"></script>
-        <script src="https://unpkg.com/pmtiles@4.0.1/dist/pmtiles.js"></script>
+        <script src="https://unpkg.com/pmtiles@4.1.0/dist/pmtiles.js"></script>
         <style>
             body {
                 margin: 0;

js/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pmtiles",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "pmtiles",
-      "version": "4.0.1",
+      "version": "4.1.0",
       "license": "BSD-3-Clause",
       "dependencies": {
         "fflate": "^0.8.2"

js/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmtiles",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "description": "PMTiles archive decoder for browsers",
   "type": "module",
   "main": "dist/cjs/index.cjs",

js/src/adapters.ts

@@ -167,16 +167,21 @@ export class Protocol {
   /** @hidden */
   tiles: Map<string, PMTiles>;
   metadata: boolean;
+  errorOnMissingTile: boolean;
 
   /**
    * Initialize the MapLibre PMTiles protocol.
    *
    * * metadata: also load the metadata section of the PMTiles. required for some "inspect" functionality
    * and to automatically populate the map attribution. Requires an extra HTTP request.
+   * * errorOnMissingTile: When a vector MVT tile is missing from the archive, raise an error instead of
+   * returning the empty array. Not recommended. This is only to reproduce the behavior of ZXY tile APIs
+   * which some applications depend on when overzooming.
    */
-  constructor(options?: { metadata: boolean }) {
+  constructor(options?: { metadata?: boolean; errorOnMissingTile?: boolean }) {
     this.tiles = new Map<string, PMTiles>();
     this.metadata = options?.metadata || false;
+    this.errorOnMissingTile = options?.errorOnMissingTile || false;
   }
 
   /**
@@ -251,6 +256,9 @@ export class Protocol {
       };
     }
     if (header.tileType === TileType.Mvt) {
+      if (this.errorOnMissingTile) {
+        throw new Error("Tile not found.");
+      }
       return { data: new Uint8Array() };
     }
     return { data: null };