add getTileJson method to PMTiles class [#239, #247] (#453)

* add getTileJson method to PMTiles class [#239, #247]
* update docs related to FetchSource and headers [#397]

js/adapters.ts

@@ -164,20 +164,31 @@ const v3compat =
  * MapLibre GL JS protocol. Must be added once globally.
  */
 export class Protocol {
+  /** @hidden */
   tiles: Map<string, PMTiles>;
 
   constructor() {
     this.tiles = new Map<string, PMTiles>();
   }
 
+  /**
+   * Add a {@link PMTiles} instance to the global protocol instance.
+   *
+   * For remote fetch sources, references in MapLibre styles like pmtiles://http://...
+   * will resolve to the same instance if the URLs match.
+   */
   add(p: PMTiles) {
     this.tiles.set(p.source.getKey(), p);
   }
 
+  /**
+   * Fetch a {@link PMTiles} instance by URL, for remote PMTiles instances.
+   */
   get(url: string) {
     return this.tiles.get(url);
   }
 
+  /** @hidden */
   tilev4 = async (
     params: RequestParameters,
     abortController: AbortController

js/index.ts

@@ -150,6 +150,15 @@ export interface Entry {
   runLength: number;
 }
 
+interface MetadataLike {
+  attribution?: string;
+  name?: string;
+  version?: string;
+  // biome-ignore lint: TileJSON spec
+  vector_layers?: string;
+  description?: string;
+}
+
 /**
  * Enum representing a compression algorithm used.
  * 0 = unknown compression, for if you must use a different or unspecified algorithm.
@@ -212,6 +221,15 @@ export enum TileType {
   Avif = 5,
 }
 
+export function tileTypeExt(t: TileType): string {
+  if (t === TileType.Mvt) return ".mvt";
+  if (t === TileType.Png) return ".png";
+  if (t === TileType.Jpeg) return ".jpg";
+  if (t === TileType.Webp) return ".webp";
+  if (t === TileType.Avif) return ".avif";
+  return "";
+}
+
 const HEADER_SIZE_BYTES = 127;
 
 /**
@@ -327,10 +345,19 @@ export class FileSource implements Source {
  *
  * 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 implements Source {
   url: string;
+
+  /**
+   * A [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers) object, specfying custom [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers) set for all requests to the remote archive.
+   *
+   * This should be used instead of maplibre's [transformRequest](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#example) for PMTiles archives.
+   */
   customHeaders: Headers;
+  /** @hidden */
   mustReload: boolean;
 
   constructor(url: string, customHeaders: Headers = new Headers()) {
@@ -343,6 +370,9 @@ export class FetchSource implements Source {
     return this.url;
   }
 
+  /**
+   * Mutate the custom [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers) set for all requests to the remote archive.
+   */
   setHeaders(customHeaders: Headers) {
     this.customHeaders = customHeaders;
   }
@@ -1003,7 +1033,7 @@ export class PMTiles {
   }
 
   /**
-   * Primary method to get a single tile bytes from an archive.
+   * Primary method to get a single tile's bytes from an archive.
    *
    * Returns undefined if the tile does not exist in the archive.
    */
@@ -1056,4 +1086,33 @@ export class PMTiles {
       throw e;
     }
   }
+
+  /**
+   * Construct a [TileJSON](https://github.com/mapbox/tilejson-spec) object.
+   *
+   * baseTilesUrl is the desired tiles URL, excluding the suffix `/{z}/{x}/{y}.{ext}`.
+   * For example, if the desired URL is `http://example.com/tileset/{z}/{x}/{y}.mvt`,
+   * the baseTilesUrl should be `https://example.com/tileset`.
+   */
+  async getTileJson(baseTilesUrl: string): Promise<unknown> {
+    const header = await this.getHeader();
+    const metadata = (await this.getMetadata()) as MetadataLike;
+    const ext = tileTypeExt(header.tileType);
+
+    return {
+      tilejson: "3.0.0",
+      scheme: "xyz",
+      tiles: [`${baseTilesUrl}/{z}/{x}/{y}${ext}`],
+      // biome-ignore lint: TileJSON spec
+      vector_layers: metadata.vector_layers,
+      attribution: metadata.attribution,
+      description: metadata.description,
+      name: metadata.name,
+      version: metadata.version,
+      bounds: [header.minLon, header.minLat, header.maxLon, header.maxLat],
+      center: [header.centerLon, header.centerLat, header.centerZoom],
+      minzoom: header.minZoom,
+      maxzoom: header.maxZoom,
+    };
+  }
 }

js/test/v3.test.ts

@@ -11,10 +11,12 @@ import {
   RangeResponse,
   SharedPromiseCache,
   Source,
+  TileType,
   findTile,
   getUint64,
   readVarint,
   tileIdToZxy,
+  tileTypeExt,
   zxyToTileId,
 } from "../index";
 
@@ -376,3 +378,40 @@ test("pmtiles get metadata", async () => {
 });
 
 // echo '{"type":"Polygon","coordinates":[[[0,0],[0,1],[1,0],[0,0]]]}' | ./tippecanoe -zg -o test_fixture_2.pmtiles
+
+test("get file extension", async () => {
+  assert.equal("", tileTypeExt(TileType.Unknown));
+  assert.equal(".mvt", tileTypeExt(TileType.Mvt));
+  assert.equal(".png", tileTypeExt(TileType.Png));
+  assert.equal(".jpg", tileTypeExt(TileType.Jpeg));
+  assert.equal(".webp", tileTypeExt(TileType.Webp));
+  assert.equal(".avif", tileTypeExt(TileType.Avif));
+});
+
+interface TileJsonLike {
+  tilejson: string;
+  scheme: string;
+  tiles: string[];
+  description?: string;
+  name?: string;
+  attribution?: string;
+  version?: string;
+}
+
+test("pmtiles get TileJSON", async () => {
+  const source = new TestNodeFileSource(
+    "test/data/test_fixture_1.pmtiles",
+    "1"
+  );
+  const p = new PMTiles(source);
+  const tilejson = (await p.getTileJson(
+    "https://example.com/foo"
+  )) as TileJsonLike;
+  assert.equal("3.0.0", tilejson.tilejson);
+  assert.equal("xyz", tilejson.scheme);
+  assert.equal("https://example.com/foo/{z}/{x}/{y}.mvt", tilejson.tiles[0]);
+  assert.equal(undefined, tilejson.attribution);
+  assert.equal("test_fixture_1.pmtiles", tilejson.description);
+  assert.equal("test_fixture_1.pmtiles", tilejson.name);
+  assert.equal("2", tilejson.version);
+});