maplibre-tilepackage-protocol 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Måns Beckman
+Copyright (c) 2021 Protomaps LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# maplibre-tilepackage-protocol
+
+As an ES6 module: `npm add maplibre-tilepackage-protocol`
+
+```js
+import * as tilePackage from "maplibre-tilepackage-protocol";
+```
+
+## MapLibre GL JS
+
+Example of a TPKX/VTPK archive displayed in MapLibre GL JS:
+
+```js
+import * as tilePackage from "maplibre-tilepackage-protocol";
+let protocol = new tilePackage.Protocol();
+maplibregl.addProtocol("tilepackage",protocol.package);
+var style = {
+"version": 8,
+"sources": {
+    "example_source": {
+        "type": "raster",
+        "url": "tilepackage://https://example.com/example.tpkx",
+    ...
+```
+
+## TPKX
+
+A TPKX file containes a full tile pyramid and you just treat it as any other raster source.
+
+## VTPK
+
+Primarily flat VTPK files are supported, see below for indexed VTPK files.
+
+The file also contains everything you need for your map, such as a style with layers, glyphs, and spirits. You can get everything you need using the tilepackage.
+
+```js
+async initMap(package){
+    const header = await package.getHeader();
+    if (header.spatialReference == 3857) {
+        const style = await package.getStyle();
+        new maplibregl.Map({
+            container: "map-element",
+            localIdeographFontFamily: false,
+            style: style,
+        });
+    }
+}
+
+const source = String || tilePackage.FileSource;
+const package = new tilePackage.TilePackage(
+        source,
+      );
+initMap(package)
+```
+
+A VTPK file may contain an indexed tile pyramid where some tiles are missing, because of this you should always initialze a vtpk file with:
+
+```js
+let protocol = new tilePackage.Protocol({
+  errorOnMissingTile: true,
+});
+```
+
+This will make tiles from lower zoom levels remain in view when you zoom into the map. Unfortunatly it is not possible to get the tiles to over scale in the same way as in ArcGIS Pro without modifying the source cache code in Maplibre. https://github.com/maplibre/maplibre-gl-js/issues/5618
+
+# Acknowledgement
+
+The code for this protocol was based on the PMTiles protocol by Protomaps LLC.
+
+# Sample data
+
+A sample dataset covering Austria can be downloaded from the following link. Note that this file is an indexed VTPK and won't display all tiles correctly without modifying Maplibre.
+
+https://www.data.gv.at/katalog/de/dataset/basemap-at-verwaltungsgrundkarte-vektor-offline-osterreich#resources

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "maplibre-tilepackage-protocol",
+  "version": "1.0.0",
+  "description": "Maplibre-gl-js protocol for reading VTPK and TPKX files",
+  "homepage": "https://github.com/spatialillusions/maplibre-tilepackage-protocol#readme",
+  "bugs": {
+    "url": "https://github.com/spatialillusions/maplibre-tilepackage-protocol/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/spatialillusions/maplibre-tilepackage-protocol.git"
+  },
+  "license": "MIT",
+  "author": "Måns Beckman",
+  "type": "module",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}

package/src/default-decompress.js

@@ -0,0 +1,28 @@
+/* global globalThis */
+import * as fflate from "fflate";
+
+/**
+ * Provide a decompression implementation that acts on `buf` and returns decompressed data.
+ *
+ * Should use the native DecompressionStream on browsers, zlib on node.
+ * Should throw if the compression algorithm is not supported.
+ */
+export default async function defaultDecompress(buf, compression) {
+  if (compression === "none" || compression === undefined) {
+    return buf;
+  }
+  if (compression === "gzip") {
+    if (typeof globalThis.DecompressionStream === "undefined") {
+      return fflate.decompressSync(new Uint8Array(buf));
+    }
+    const stream = new Response(buf).body;
+    if (!stream) {
+      throw new Error("Failed to read response stream");
+    }
+    const result = stream.pipeThrough(
+      new globalThis.DecompressionStream("gzip"),
+    );
+    return new Response(result).arrayBuffer();
+  }
+  throw new Error("Compression method not supported");
+}

package/src/get-header-and-filelist.js

@@ -0,0 +1,249 @@
+import getJsonFromFile from "./get-json-from-file.js";
+
+function xmlToJson(xmlString) {
+  const parser = new DOMParser();
+  const xmlDoc = parser.parseFromString(xmlString, "application/xml");
+  const obj = {};
+
+  function traverse(node, obj) {
+    if (node.nodeType === 1) {
+      // element
+      const nodeName = node.nodeName;
+      if (!obj[nodeName] && node.childNodes.length > 0) {
+        obj[nodeName] = {};
+      }
+      if (node.childNodes.length == 1 && node.childNodes[0].nodeType == 3) {
+        obj[nodeName] = node.childNodes[0].nodeValue.trim();
+        return;
+      }
+      for (let i = 0; i < node.childNodes.length; i++) {
+        traverse(node.childNodes[i], obj[nodeName]);
+      }
+    }
+  }
+
+  traverse(xmlDoc.documentElement, obj);
+  return obj;
+}
+
+/**
+ * Parse json into a Header object.
+ */
+export function jsonToHeader(json, files, etag) {
+  let spatialReference;
+  try {
+    spatialReference = json.tileInfo.spatialReference.latestWkid;
+    // eslint-disable-next-line no-unused-vars
+  } catch (e) {
+    spatialReference = undefined;
+  }
+  return {
+    type: json.type,
+    name: json.name,
+    description: json.serviceDescription,
+    attribution: json.copyrightText,
+    version: json.version,
+    metadataOffset: json.metadataOffset || 0,
+    metadataLength: json.metadataLength || 0,
+    packageType: json.tileInfo.format ? "vtpk" : "tpkx",
+    spatialReference: spatialReference,
+    tileCompression: json.resourceInfo
+      ? json.resourceInfo.tileCompression || "none"
+      : "none",
+    tileType: json.tileInfo.format || json.tileImageInfo.format,
+    tileSize: json.tileInfo.rows,
+    minZoom: json.minZoom || json.minLOD,
+    maxZoom: json.maxZoom || json.maxLOD,
+    minLon: Number(json.extent.xmin),
+    minLat: Number(json.extent.ymin),
+    maxLon: Number(json.extent.xmax),
+    maxLat: Number(json.extent.ymax),
+    files: files,
+    etag: etag,
+  };
+}
+
+/**
+ * Retrieve the header and root directory of a TilePackage archive.
+ *
+ * @param {Source} source - The source of the TilePackage archive.
+ */
+export default async function getHeaderAndFileList(source) {
+  const key = source.getKey();
+  const fileSize = await source.getSize();
+  const resp = await source.getBytes(fileSize - 98, 98);
+  let v = new DataView(resp.data, 0, 98);
+  let entriesCentralDirectory, sizeCentralDirectory, offsetCentralDirectory;
+  //let bigZip64 = false;
+  if (v.getUint32(0, true) === 0x06064b50) {
+    // This is a ZIP64 tilepackage
+    //bigZip64 = true;
+    entriesCentralDirectory = Number(v.getBigUint64(32, true));
+    sizeCentralDirectory = Number(v.getBigUint64(40, true));
+    offsetCentralDirectory = Number(v.getBigUint64(48, true));
+  } else {
+    v = new DataView(resp.data, 98 - 22, 22);
+    if (v.getUint32(0, true) === 0x06054b50) {
+      // This is a ordinary zip archive
+      entriesCentralDirectory = Number(v.getUint16(10, true));
+      sizeCentralDirectory = Number(v.getUint32(12, true));
+      offsetCentralDirectory = Number(v.getUint32(16, true));
+    } else {
+      throw new Error("Wrong magic number for Zip archive");
+    }
+  }
+
+  const centralDirectory = await source.getBytes(
+    offsetCentralDirectory,
+    sizeCentralDirectory,
+  );
+
+  v = new DataView(centralDirectory.data, 0, sizeCentralDirectory);
+  if (v.getUint32(0, true) !== 0x02014b50) {
+    throw new Error("Wrong magic number for Central Directory archive");
+  }
+
+  let entryStart = 0;
+  const tilePackageFiles = {};
+  for (let i = 0; i < entriesCentralDirectory; i++) {
+    if (entryStart >= sizeCentralDirectory) break;
+    /*
+        central file header signature   4 bytes  (0x02014b50)
+        version made by                 2 bytes
+        version needed to extract       2 bytes
+        general purpose bit flag        2 bytes
+        compression method              2 bytes
+        last mod file time              2 bytes
+        last mod file date              2 bytes
+        crc-32                          4 bytes
+        compressed size                 4 bytes
+        uncompressed size               4 bytes
+        file name length                2 bytes
+        extra field length              2 bytes
+        file comment length             2 bytes
+        disk number start               2 bytes
+        internal file attributes        2 bytes
+        external file attributes        4 bytes
+        relative offset of local header 4 bytes
+
+        file name (variable size)
+        extra field (variable size)
+        file comment (variable size)
+    */
+    let sizeFile = v.getUint32(entryStart + 20, true);
+
+    const sizeFileName = v.getUint16(entryStart + 28, true);
+
+    const sizeExtraField = v.getUint16(entryStart + 30, true);
+
+    const sizeComment = v.getUint16(entryStart + 32, true);
+
+    let relativeOffset = v.getUint32(entryStart + 42, true);
+
+    const vFilename = new DataView(
+      centralDirectory.data,
+      entryStart + 46,
+      sizeFileName,
+    );
+    const decoder = new TextDecoder("utf-8");
+    const filename = decoder.decode(vFilename);
+
+    if (
+      (sizeFile == 0xffffffff || relativeOffset == 0xffffffff) &&
+      sizeExtraField > 0
+    ) {
+      const vExtended = new DataView(
+        centralDirectory.data,
+        entryStart + 46 + sizeFileName,
+        32,
+      );
+      if (vExtended.getUint16(0, true) == 0x0001) {
+        /*
+        Value      Size       Description
+        -----      ----       -----------
+(ZIP64) 0x0001     2 bytes    Tag for this "extra" block type
+        Size       2 bytes    Size of this "extra" block
+        Original 
+        Size       8 bytes    Original uncompressed file size
+        Compressed
+        Size       8 bytes    Size of compressed data
+        Relative Header
+        Offset     8 bytes    Offset of local header record
+        Disk Start
+        Number     4 bytes    Number of the disk on which
+                              this file starts
+      */
+
+        let j = 0;
+        if (sizeFile == 0xffffffff) {
+          sizeFile = Number(vExtended.getBigUint64(4, true));
+          j += 8;
+        }
+        if (relativeOffset == 0xffffffff) {
+          relativeOffset = Number(vExtended.getBigUint64(4 + j, true));
+        }
+      }
+    }
+
+    tilePackageFiles[filename] = {
+      filename: filename,
+      size: sizeFile,
+      relativeOffset: relativeOffset,
+      absoluteOffset: relativeOffset + 30 + filename.length,
+    };
+    entryStart += 46 + sizeFileName + sizeExtraField + sizeComment;
+  }
+
+  let root = {};
+
+  if (key.indexOf(".tpkx") !== -1) {
+    // TPKX
+    root = await getJsonFromFile("root.json", tilePackageFiles, source);
+    root.type = "tpkx";
+    const iteminfo = await getJsonFromFile(
+      "iteminfo.json",
+      tilePackageFiles,
+      source,
+    );
+    Object.keys(iteminfo).forEach((key) => {
+      if (key !== "type") {
+        root[key] = iteminfo[key];
+      }
+    });
+  } else {
+    // VTPK
+    root = await getJsonFromFile("p12/root.json", tilePackageFiles, source);
+    root.type = "vtpk";
+
+    const iteminfoFile = "esriinfo/iteminfo.xml";
+    if (tilePackageFiles[iteminfoFile]) {
+      const iteminfoOffset = tilePackageFiles[iteminfoFile].absoluteOffset;
+
+      const iteminfoData = await source.getBytes(
+        iteminfoOffset,
+        tilePackageFiles[iteminfoFile].size,
+      );
+      const decoder = new TextDecoder("utf-8");
+      const iteminfoString = decoder.decode(iteminfoData.data);
+      const iteminfo = xmlToJson(iteminfoString);
+      Object.keys(iteminfo.ESRI_ItemInformation).forEach((key) => {
+        if (key !== "type") {
+          root[key] = iteminfo.ESRI_ItemInformation[key];
+        }
+      });
+    }
+
+    if (tilePackageFiles["p12/metadata.json"]) {
+      const metadataOffset =
+        tilePackageFiles["p12/metadata.json"].absoluteOffset;
+      root.metadataOffset = metadataOffset;
+      root.metadataLength = tilePackageFiles["p12/metadata.json"].size;
+    }
+  }
+  //TODO read iteminfo.xml....
+
+  const header = jsonToHeader(root, tilePackageFiles, resp.etag);
+
+  //return [header, [dirKey, rootDir.length, rootDir]];
+  return [header, ""];
+}

package/src/get-json-from-file.js

@@ -0,0 +1,12 @@
+export default async function getJsonFromFile(file, tilePackageFiles, source) {
+  const decoder = new TextDecoder("utf-8");
+  if (tilePackageFiles[file]) {
+    const fileOffset = tilePackageFiles[file].absoluteOffset;
+    const fileJSON = await source.getBytes(
+      fileOffset,
+      tilePackageFiles[file].size,
+    );
+    return JSON.parse(decoder.decode(fileJSON.data));
+  }
+  return {};
+}

package/src/index.js

@@ -0,0 +1,258 @@
+export * from "./maplibre-gl-js-protocol.js";
+export * from "./source.js";
+import { FetchSource } from "./source.js";
+import defaultDecompress from "./default-decompress.js";
+import getJsonFromFile from "./get-json-from-file.js";
+import SharedPromiseCache from "./shared-promise-cache.js";
+
+function calculateFilename(z, x, y, header) {
+  const zoom = z.toString().padStart(2, "0");
+  const baseRow = Math.floor(y / 128) * 128;
+  const baseCol = Math.floor(x / 128) * 128;
+  const rowHex = baseRow.toString(16).padStart(4, "0");
+  const colHex = baseCol.toString(16).padStart(4, "0");
+  let basePath;
+  if (header.type === "tpkx") {
+    basePath = `tile`;
+  } else {
+    basePath = `p12/tile`;
+  }
+  return `${basePath}/L${zoom}/R${rowHex}C${colHex}.bundle`;
+}
+
+function getTileInfoFromTileIndex(tileIndex, z, x, y) {
+  const row = y % 128;
+  const col = x % 128;
+  return tileIndex[row][col];
+}
+
+/**
+ * Error thrown when a response for TilePackage over HTTP does not match previous, cached parts of the archive.
+ * The default TilePackage implementation will catch this error once internally and retry a request.
+ */
+class EtagMismatch extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EtagMismatch";
+  }
+}
+
+export class TilePackage {
+  constructor(source, cache, decompress) {
+    if (typeof source === "string") {
+      this.source = new FetchSource(source);
+    } else {
+      this.source = source;
+    }
+
+    if (decompress) {
+      this.decompress = decompress;
+    } else {
+      this.decompress = defaultDecompress;
+    }
+
+    if (cache) {
+      this.cache = cache;
+    } else {
+      this.cache = new SharedPromiseCache();
+    }
+  }
+
+  async getHeader() {
+    return await this.cache.getHeader(this.source);
+  }
+
+  async getZxyAttempt(z, x, y, signal) {
+    //y = (1 << z) - 1 - y; //TMS vs XYZ
+    const header = await this.cache.getHeader(this.source);
+    if (z < header.minZoom || z > header.maxZoom) {
+      return undefined;
+    }
+    const file = calculateFilename(z, x, y, header);
+    if (!header.files[file]) {
+      return undefined;
+    }
+    const tileIndex = await this.cache.getTileIndex(
+      this.source,
+      file,
+      header,
+      signal,
+    );
+    const tileInfo = getTileInfoFromTileIndex(tileIndex, z, x, y);
+    if (tileInfo && tileInfo.tileSize > 0) {
+      const tileOffset =
+        header.files[file].absoluteOffset + tileInfo.tileOffset;
+      const resp = await this.source.getBytes(
+        tileOffset,
+        tileInfo.tileSize,
+        signal,
+        header.etag,
+      );
+      const data = await this.decompress(resp.data, header.tileCompression);
+      return {
+        data: data,
+        cacheControl: resp.cacheControl,
+        expires: resp.expires,
+      };
+    } else {
+      //return await this.getZxyAttempt(z - 1, x / 2, y / 2, signal);
+      // Return undefined if the tile is not found
+      return undefined;
+    }
+  }
+
+  async getZxy(z, x, y, signal) {
+    try {
+      return await this.getZxyAttempt(z, x, y, signal);
+    } catch (e) {
+      if (e instanceof EtagMismatch) {
+        this.cache.invalidate(this.source);
+        return await this.getZxyAttempt(z, x, y, signal);
+      }
+      throw e;
+    }
+  }
+
+  async getMetadataAttempt() {
+    const header = await this.cache.getHeader(this.source);
+
+    let metadata = {};
+    if (header.packageType === "vtpk") {
+      const resp = await this.source.getBytes(
+        header.jsonMetadataOffset,
+        header.jsonMetadataLength,
+        undefined,
+        header.etag,
+      );
+
+      const decoder = new TextDecoder("utf-8");
+      metadata = JSON.parse(decoder.decode(resp.data));
+    }
+    metadata.name = header.name;
+
+    return metadata;
+  }
+
+  async getMetadata() {
+    try {
+      return await this.getMetadataAttempt();
+    } catch (e) {
+      if (e instanceof EtagMismatch) {
+        this.cache.invalidate(this.source);
+        return await this.getMetadataAttempt();
+      }
+      throw e;
+    }
+  }
+
+  async getResourceAttempt(file, signal) {
+    const header = await this.cache.getHeader(this.source);
+    if (!header.files[file]) {
+      return undefined;
+    }
+
+    const resource = await this.cache.getResource(
+      this.source,
+      file,
+      header,
+      signal,
+    );
+    return {
+      data: resource.data,
+      cacheControl: resource.cacheControl,
+      expires: resource.expires,
+    };
+  }
+
+  async getResource(file, signal) {
+    try {
+      return await this.getResourceAttempt(file, signal);
+    } catch (e) {
+      if (e instanceof EtagMismatch) {
+        this.cache.invalidate(this.source);
+        return await this.getResourceAttempt(file, signal);
+      }
+      throw e;
+    }
+  }
+
+  async getStyleAttempt() {
+    const header = await this.cache.getHeader(this.source);
+    const sourceKey = this.source.getKey();
+    if (header.packageType === "vtpk") {
+      const style = await getJsonFromFile(
+        "p12/resources/styles/root.json",
+        header.files,
+        this.source,
+      );
+      style.sources.esri.url = `"tilepackage://${sourceKey}`;
+      style.sources.esri.maxzoom = header.maxZoom || 22;
+      style.glyphs = `tilepackage://${sourceKey}/{fontstack}/{range}`;
+      style.sprite = `tilepackage://${sourceKey}/sprite`;
+
+      return style;
+    } else {
+      return {
+        version: 8,
+        sources: {
+          esri: {
+            type: "raster",
+            tileSize: header.tileSize || 256,
+            url: `"tilepackage://${sourceKey}`,
+            maxzoom: header.maxZoom || 22,
+          },
+        },
+        layers: [
+          {
+            id: "tilepackageraster",
+            type: "raster",
+            source: "esri",
+          },
+        ],
+      };
+    }
+  }
+
+  async getStyle() {
+    try {
+      return await this.getStyleAttempt();
+    } catch (e) {
+      if (e instanceof EtagMismatch) {
+        this.cache.invalidate(this.source);
+        return await this.getStyleAttempt();
+      }
+      throw e;
+    }
+  }
+
+  async getTileJson(baseTilesUrl) {
+    const header = await this.getHeader();
+    const metadata = await this.getMetadata();
+    const ext = header.tileType;
+
+    const tileJson = {
+      tilejson: "3.0.0",
+      scheme: "xyz",
+      tiles: [`${baseTilesUrl}/{z}/{x}/{y}${ext}`],
+      name: metadata.name,
+      version: header.version,
+      bounds: [header.minLon, header.minLat, header.maxLon, header.maxLat],
+    };
+    if (metadata.vector_layers) {
+      tileJson.vector_layers = metadata.vector_layers;
+    }
+    if (metadata.attribution) {
+      tileJson.attribution = metadata.attribution;
+    }
+    if (metadata.description) {
+      tileJson.description = metadata.description;
+    }
+    if (header.minZoom) {
+      tileJson.minzoom = header.minZoom;
+    }
+    if (header.maxZoom) {
+      tileJson.maxzoom = header.maxZoom;
+    }
+    return tileJson;
+  }
+}

package/src/maplibre-gl-js-protocol.js

@@ -0,0 +1,240 @@
+import { TilePackage } from "./index.js";
+import protocolGlyphs from "../protocol-glyphs.js";
+
+function stringEndsIn(string, endings) {
+  for (let i = 0; i < endings.length; i++) {
+    if (string.slice(-endings[i].length) == endings[i]) return endings[i];
+  }
+  return false;
+}
+
+const converter = (getData) => (requestParameters, arg2) => {
+  if (arg2 instanceof AbortController) {
+    return getData(requestParameters, arg2);
+  }
+  const abortController = new AbortController();
+  getData(requestParameters, abortController)
+    .then(
+      (result) => {
+        return arg2(
+          undefined,
+          result.data,
+          result.cacheControl || "",
+          result.expires || "",
+        );
+      },
+      (err) => {
+        return arg2(err);
+      },
+    )
+    .catch((e) => {
+      return arg2(e);
+    });
+  return { cancel: () => abortController.abort() };
+};
+
+/**
+ * MapLibre GL JS protocol. Must be added once globally.
+ */
+export class Protocol {
+  /**
+   * Initialize the MapLibre TilePackage protocol.
+   *
+   * * metadata: also load the metadata section of the TilePackage. 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) {
+    this.tiles = new Map();
+    this.metadata = options ? options.metadata || false : false;
+    this.errorOnMissingTile = options
+      ? options.errorOnMissingTile || false
+      : false;
+    this.getData = async (params, abortController) => {
+      if (params.type === "json") {
+        let tilePackageUrl = params.url.substr(14); // TODO fix this to be more robust
+        // at the moment we depend on that the tilePackage URL starts with tilepackage://
+
+        let spriteCheck = stringEndsIn(params.url, [
+          "/sprite",
+          "/sprite.json",
+          "/sprite@2x.json",
+        ]);
+        if (spriteCheck) {
+          // For some reason spirit and glyphs urls might loose the : in http://
+          tilePackageUrl = tilePackageUrl.replace(/(https?)\/\/?/g, "$1://");
+          tilePackageUrl = tilePackageUrl.slice(0, -spriteCheck.length);
+          if (spriteCheck == "/sprite") {
+            spriteCheck = "/sprite.json";
+          }
+        }
+
+        let instance = this.tiles.get(tilePackageUrl);
+        if (!instance) {
+          instance = new TilePackage(tilePackageUrl);
+          this.tiles.set(tilePackageUrl, instance);
+        }
+
+        if (spriteCheck) {
+          // This is a request for a sprite json
+          const file = `p12/resources/sprites${spriteCheck}`;
+          const resp = await instance.getResource(file, abortController.signal);
+          if (resp) {
+            const decoder = new TextDecoder("utf-8");
+            const json = JSON.parse(decoder.decode(resp.data));
+            return {
+              data: json,
+            };
+          }
+        }
+        // This is a request for a tile json
+        if (this.metadata) {
+          return {
+            data: await instance.getTileJson(params.url),
+          };
+        }
+        const h = await instance.getHeader();
+        if (h.minLon >= h.maxLon || h.minLat >= h.maxLat) {
+          console.error(
+            `Bounds of TilePackage archive ${h.minLon},${h.minLat},${h.maxLon},${h.maxLat} are not valid.`,
+          );
+        }
+
+        return {
+          data: {
+            tiles: [`${params.url}/{z}/{x}/{y}`],
+            minzoom: h.minZoom,
+            maxzoom: h.maxZoom,
+            bounds: [h.minLon, h.minLat, h.maxLon, h.maxLat],
+          },
+        };
+        //}
+      }
+      // TODO handle other paths ???
+      let re = new RegExp(/tilepackage:\/\/(.+)\/(\d+)\/(\d+)\/(\d+)/);
+      let result = params.url.match(re);
+      if (!result) {
+        // This might be a request for glyphs or spirit
+        let tilePackageUrl = params.url.substr(14);
+        // For some reason spirit and glyphs urls might loose the : in http://
+        tilePackageUrl = tilePackageUrl.replace(/(https?)\/\/?/g, "$1://");
+        let spriteCheck = stringEndsIn(params.url, [
+          "/sprite",
+          "/sprite.png",
+          "/sprite@2x.png",
+        ]);
+        if (spriteCheck) {
+          // It looks like we are looking for a spirit png
+          tilePackageUrl = tilePackageUrl.slice(0, -spriteCheck.length);
+          if (spriteCheck == "/sprite") {
+            spriteCheck = "/sprite.png";
+          }
+          let instance = this.tiles.get(tilePackageUrl);
+          if (!instance) {
+            instance = new TilePackage(tilePackageUrl);
+            this.tiles.set(tilePackageUrl, instance);
+          }
+          const file = `p12/resources/sprites${spriteCheck}`;
+          const resp = await instance.getResource(file, abortController.signal);
+          if (resp) {
+            return {
+              data: new Uint8Array(resp.data),
+              cacheControl: resp.cacheControl,
+              expires: resp.expires,
+            };
+          }
+        } else {
+          // This is more likely a glyph url
+          re = new RegExp(/^tilepackage:\/\/(.+?)\/([^/]+)\/([^/]+)$/);
+          result = params.url.match(re);
+          if (result && isNaN(result[2])) {
+            const tilePackageUrl = result[1];
+            let instance = this.tiles.get(tilePackageUrl);
+            if (!instance) {
+              instance = new TilePackage(tilePackageUrl);
+              this.tiles.set(tilePackageUrl, instance);
+            }
+            const file = `p12/resources/fonts/${result[2]}/${result[3]}.pbf`;
+            const resp = await instance.getResource(
+              file,
+              abortController.signal,
+            );
+            if (resp) {
+              return {
+                data: new Uint8Array(resp.data),
+                cacheControl: resp.cacheControl,
+                expires: resp.expires,
+              };
+            }
+
+            // Fallback to local glyphs since we couldn't load the coorect from the vtpk
+            const fallback = await protocolGlyphs({
+              url: `glyphs://${result[2]}/${result[3]}`,
+            });
+            if (fallback) {
+              return fallback;
+            }
+
+            return { data: null };
+          }
+        }
+      }
+
+      if (!result) {
+        throw new Error("Invalid TilePackage protocol URL");
+      }
+      const tilePackageUrl = result[1];
+
+      let instance = this.tiles.get(tilePackageUrl);
+      if (!instance) {
+        instance = new TilePackage(tilePackageUrl);
+        this.tiles.set(tilePackageUrl, instance);
+      }
+      const z = result[2];
+      const x = result[3];
+      const y = result[4];
+      const header = await instance.getHeader();
+      const resp = await instance.getZxy(+z, +x, +y, abortController.signal);
+      if (resp) {
+        return {
+          data: new Uint8Array(resp.data),
+          cacheControl: resp.cacheControl,
+          expires: resp.expires,
+        };
+      }
+      if (header.tileType === "pbf") {
+        if (this.errorOnMissingTile) {
+          const e = new Error(
+            "Tile not found in Tile Package, this is normal for VTPK files with variable tile depth.",
+          ); // e.name is 'Error'
+          e.name = "TileError";
+          throw e;
+        }
+        return { data: new Uint8Array() };
+      } else {
+        return { data: null };
+      }
+    };
+
+    this.package = converter(this.getData);
+  }
+
+  /**
+   * Add a {@link TilePackage} instance to the global protocol instance.
+   *
+   * For remote fetch sources, references in MapLibre styles like tilePackage://http://...
+   * will resolve to the same instance if the URLs match.
+   */
+  add(p) {
+    this.tiles.set(p.source.getKey(), p);
+  }
+
+  /**
+   * Fetch a {@link TilePackage} instance by URL, for remote TilePackage instances.
+   */
+  get(url) {
+    return this.tiles.get(url);
+  }
+}

package/src/shared-promise-cache.js

@@ -0,0 +1,195 @@
+import getHeaderAndFileList from "./get-header-and-filelist.js";
+
+function deserializeIndex(dataView) {
+  const index = [];
+
+  //const M = BigInt(Math.pow(2, 40));
+  for (let row = 0; row < 128; row++) {
+    index[row] = [];
+    for (let col = 0; col < 128; col++) {
+      const tileIndexOffset = 8 * (128 * (row % 128) + (col % 128));
+      // eslint-disable-next-line no-undef
+      let tileOffset = BigInt(0);
+      for (let i = 4; i >= 0; i--) {
+        // Start from the last byte for little-endian
+        tileOffset =
+          // eslint-disable-next-line no-undef
+          (tileOffset << BigInt(8)) |
+          // eslint-disable-next-line no-undef
+          BigInt(dataView.getUint8(tileIndexOffset + i));
+      }
+      // eslint-disable-next-line no-undef
+      let tileSize = BigInt(0);
+      for (let i = 2; i >= 0; i--) {
+        // Start from the last byte for little-endian
+        tileSize =
+          // eslint-disable-next-line no-undef
+          (tileSize << BigInt(8)) |
+          // eslint-disable-next-line no-undef
+          BigInt(dataView.getUint8(tileIndexOffset + 5 + i));
+      }
+      if (tileSize > 0) {
+        index[row][col] = {
+          row: row,
+          col: col,
+          tileOffset: Number(tileOffset),
+          tileSize: Number(tileSize),
+        };
+      }
+    }
+  }
+
+  return index;
+}
+
+async function getResource(source, file, header, signal) {
+  const resp = await source.getBytes(
+    header.files[file].absoluteOffset,
+    header.files[file].size,
+    signal,
+    header.etag,
+  );
+  return resp;
+}
+
+async function getTileIndex(source, file, header, signal) {
+  const offset = header.files[file].absoluteOffset + 64; // File header 64bytes
+  const resp = await source.getBytes(
+    offset,
+    128 * 128 * 8,
+    signal,
+    header.etag,
+  );
+  const dataView = new DataView(resp.data, 0, 128 * 128 * 8);
+  const directory = deserializeIndex(dataView);
+  if (directory.length === 0) {
+    throw new Error("Empty directory is invalid");
+  }
+  return directory;
+}
+
+/**
+ * A cache for parts of a TilePackage archive where promises can be shared between requests.
+ *
+ * Only caches headers, resource files, and directories, not individual tile contents.
+ */
+export default class SharedPromiseCache {
+  constructor(maxCacheEntries = 100) {
+    this.cache = new Map();
+    this.invalidations = new Map();
+    this.maxCacheEntries = maxCacheEntries;
+    this.counter = 1;
+    //this.decompress = decompress;
+  }
+
+  async getHeader(source) {
+    const cacheKey = source.getKey();
+    const cacheValue = this.cache.get(cacheKey);
+    if (cacheValue) {
+      cacheValue.lastUsed = this.counter++;
+      const data = await cacheValue.data;
+      return data;
+    }
+
+    const p = new Promise((resolve, reject) => {
+      getHeaderAndFileList(source)
+        .then((res) => {
+          /*
+          if (res[1]) {
+            this.cache.set(res[1][0], {
+              lastUsed: this.counter++,
+              data: Promise.resolve(res[1][2]),
+            });
+          }*/
+          resolve(res[0]);
+          this.prune();
+        })
+        .catch((e) => {
+          reject(e);
+        });
+    });
+    this.cache.set(cacheKey, { lastUsed: this.counter++, data: p });
+    return p;
+  }
+
+  async getResource(source, file, header, signal) {
+    const cacheKey = `${source.getKey()}|${header.etag || ""}|${file}|Resource`;
+    const cacheValue = this.cache.get(cacheKey);
+    if (cacheValue) {
+      cacheValue.lastUsed = this.counter++;
+      const data = await cacheValue.data;
+      return data;
+    }
+    const p = new Promise((resolve, reject) => {
+      getResource(source, file, header, signal)
+        .then((resource) => {
+          resolve(resource);
+          this.prune();
+        })
+        .catch((e) => {
+          reject(e);
+        });
+    });
+    this.cache.set(cacheKey, { lastUsed: this.counter++, data: p });
+    return p;
+  }
+
+  async getTileIndex(source, file, header, signal) {
+    const cacheKey = `${source.getKey()}|${
+      header.etag || ""
+    }|${file}|TileIndex`;
+    const cacheValue = this.cache.get(cacheKey);
+    if (cacheValue) {
+      cacheValue.lastUsed = this.counter++;
+      const data = await cacheValue.data;
+      return data;
+    }
+    const p = new Promise((resolve, reject) => {
+      getTileIndex(source, file, header, signal)
+        .then((directory) => {
+          resolve(directory);
+          this.prune();
+        })
+        .catch((e) => {
+          reject(e);
+        });
+    });
+    this.cache.set(cacheKey, { lastUsed: this.counter++, data: p });
+    return p;
+  }
+
+  prune() {
+    if (this.cache.size >= this.maxCacheEntries) {
+      let minUsed = Infinity;
+      let minKey = undefined;
+      this.cache.forEach((cacheValue, key) => {
+        if (cacheValue.lastUsed < minUsed) {
+          minUsed = cacheValue.lastUsed;
+          minKey = key;
+        }
+      });
+      if (minKey) {
+        this.cache.delete(minKey);
+      }
+    }
+  }
+
+  async invalidate(source) {
+    const key = source.getKey();
+    if (this.invalidations.get(key)) {
+      return await this.invalidations.get(key);
+    }
+    this.cache.delete(source.getKey());
+    const p = new Promise((resolve, reject) => {
+      this.getHeader(source)
+        .then(() => {
+          resolve();
+          this.invalidations.delete(key);
+        })
+        .catch((e) => {
+          reject(e);
+        });
+    });
+    this.invalidations.set(key, p);
+  }
+}

package/src/source.js

@@ -0,0 +1,237 @@
+/* global globalThis */
+
+/**
+ * Interface for retrieving an archive from remote or local storage.
+ */
+export class Source {
+  async getBytes() {
+    throw new Error("Not implemented");
+  }
+
+  getKey() {
+    throw new Error("Not implemented");
+  }
+}
+
+/**
+ * Use the Browser's File API, which is different from the NodeJS file API.
+ * see https://developer.mozilla.org/en-US/docs/Web/API/File_API
+ */
+export class FileSource extends Source {
+  constructor(file) {
+    super();
+    this.file = file;
+  }
+
+  getKey() {
+    return this.file.name;
+  }
+
+  async getSize() {
+    return this.file.size;
+  }
+
+  // eslint-disable-next-line no-unused-vars
+  async getBytes(offset, length, passedSignal, etag) {
+    const blob = this.file.slice(offset, offset + length);
+    const a = await blob.arrayBuffer();
+    return { data: a };
+  }
+}
+
+/**
+ * Uses the browser Fetch API to make tile requests via HTTP.
+ *
+ * This method does not send conditional request headers If-Match because of CORS.
+ * Instead, it detects ETag mismatches via the response ETag or the 416 response code.
+ *
+ * This also works around browser and storage-specific edge cases.
+ */
+export class FetchSource extends Source {
+  constructor(url, customHeaders = new Headers()) {
+    super();
+    this.url = url;
+    this.customHeaders = customHeaders;
+    this.mustReload = false;
+    let userAgent = "";
+    if ("navigator" in globalThis) {
+      userAgent = globalThis.navigator.userAgent || "";
+    }
+    const isWindows = userAgent.indexOf("Windows") > -1;
+    const isChromiumBased = /Chrome|Chromium|Edg|OPR|Brave/.test(userAgent);
+    this.chromeWindowsNoCache = false;
+    if (isWindows && isChromiumBased) {
+      this.chromeWindowsNoCache = true;
+    }
+  }
+
+  getKey() {
+    return this.url;
+  }
+
+  // eslint-disable-next-line no-unused-vars
+  async getSize(passedSignal, etag) {
+    if (this.size) return this.size;
+
+    let controller;
+    let signal;
+    if (passedSignal) {
+      signal = passedSignal;
+    } else {
+      controller = new AbortController();
+      signal = controller.signal;
+    }
+
+    const requestHeaders = new Headers(this.customHeaders);
+    requestHeaders.set("range", `bytes=${0}-${4}`);
+
+    let cache;
+    if (this.mustReload) {
+      cache = "reload";
+    } else if (this.chromeWindowsNoCache) {
+      cache = "no-store";
+    }
+
+    const resp = await fetch(this.url, {
+      signal: signal,
+      cache: cache,
+      headers: requestHeaders,
+    });
+
+    //Making sure that the server supports content-range and getting the file size
+    const contentRange = resp.headers.get("Content-Range");
+    if (resp.status === 206 && contentRange) {
+      const fileSize = contentRange.split("/")[1];
+      if (fileSize) {
+        this.size = fileSize;
+        return fileSize;
+      }
+    }
+    if (resp.status === 206 && !contentRange) {
+      // We didn't get a content-range response, getting head instead
+      // Getting head is much slower but works. We need to get the size
+      // of the file in some way since zip files has the catalog
+      // directory at the end.
+      const response = await fetch(this.url, {
+        method: "HEAD",
+      });
+      if (response.ok) {
+        const fileSize = response.headers.get("Content-Length");
+        this.size = fileSize;
+        return fileSize;
+      }
+    }
+
+    if (resp.status === 200 && !contentRange) {
+      if (controller) controller.abort();
+      throw new Error(
+        "Server returned no content-length header or content-length exceeding request. Check that your storage backend supports HTTP Byte Serving.",
+      );
+    }
+    //const requestHeaders = new Headers(this.customHeaders);
+    //requestHeaders.set("method", "HEAD");
+
+    /*
+    let controller;
+    let signal;
+    if (passedSignal) {
+      signal = passedSignal;
+    } else {
+      controller = new AbortController();
+      signal = controller.signal;
+    }
+    */
+    /*
+    try {
+      const response = await fetch(this.url, { method: "HEAD" });
+      if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`);
+      }
+      const contentLength = response.headers.get("content-length");
+      if (contentLength) {
+        console.log(contentLength);
+        this.size = contentLength;
+        return contentLength;
+      } else {
+        console.error("Content-Length header is not available.");
+      }
+    } catch (error) {
+      console.error("Error fetching headers:", error);
+    }*/
+  }
+
+  setHeaders(customHeaders) {
+    this.customHeaders = customHeaders;
+  }
+
+  async getBytes(offset, length, passedSignal, etag) {
+    let controller;
+    let signal;
+    if (passedSignal) {
+      signal = passedSignal;
+    } else {
+      controller = new AbortController();
+      signal = controller.signal;
+    }
+
+    const requestHeaders = new Headers(this.customHeaders);
+    requestHeaders.set("range", `bytes=${offset}-${offset + length - 1}`);
+
+    let cache;
+    if (this.mustReload) {
+      cache = "reload";
+    } else if (this.chromeWindowsNoCache) {
+      cache = "no-store";
+    }
+
+    let resp = await fetch(this.url, {
+      signal: signal,
+      cache: cache,
+      headers: requestHeaders,
+    });
+
+    if (offset === 0 && resp.status === 416) {
+      const contentRange = resp.headers.get("Content-Range");
+      if (!contentRange || !contentRange.startsWith("bytes */")) {
+        throw new Error("Missing content-length on 416 response");
+      }
+      const actualLength = +contentRange.substr(8);
+      resp = await fetch(this.url, {
+        signal: signal,
+        cache: "reload",
+        headers: { range: `bytes=0-${actualLength - 1}` },
+      });
+    }
+
+    let newEtag = resp.headers.get("Etag");
+    if (newEtag && newEtag.startsWith("W/")) {
+      newEtag = null;
+    }
+
+    if (resp.status === 416 || (etag && newEtag && newEtag !== etag)) {
+      this.mustReload = true;
+      throw new Error(
+        `Server returned non-matching ETag ${etag} after one retry. Check browser extensions and servers for issues that may affect correct ETag headers.`,
+      );
+    }
+
+    if (resp.status >= 300) {
+      throw new Error(`Bad response code: ${resp.status}`);
+    }
+
+    const contentLength = resp.headers.get("Content-Length");
+    if (resp.status === 200 && (!contentLength || +contentLength > length)) {
+      if (controller) controller.abort();
+      throw new Error(
+        "Server returned no content-length header or content-length exceeding request. Check that your storage backend supports HTTP Byte Serving.",
+      );
+    }
+    const a = await resp.arrayBuffer();
+    return {
+      data: a,
+      etag: newEtag || undefined,
+      cacheControl: resp.headers.get("Cache-Control") || undefined,
+      expires: resp.headers.get("Expires") || undefined,
+    };
+  }
+}