@loaders.gl/tiles 5.0.0-alpha.11 → 5.0.0-alpha.13

package/src/pmtiles/lib/encode-pmtiles.ts

@@ -0,0 +1,322 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {GZipCompressor} from '@loaders.gl/compression';
+import {zxyToTileId} from 'pmtiles';
+import type {PMTilesEncodeOptions, PMTilesTileInput} from '../pmtiles-writer-types';
+
+/** PMTiles v3 has a fixed header and a root constrained to the first 16 KiB. */
+const HEADER_BYTES = 127;
+const MAX_ROOT_BYTES = 16384 - HEADER_BYTES;
+/** Payload type values defined by the PMTiles v3 specification. */
+const TILE_TYPES = {mvt: 1, png: 2, jpeg: 3, webp: 4, avif: 5, mlt: 6} as const;
+/** Compression values describe existing payload bytes or encoded internal sections. */
+const COMPRESSIONS = {none: 1, gzip: 2, brotli: 3, zstd: 4} as const;
+
+/** One directory entry with offsets relative to its associated data section. */
+interface DirectoryEntry {
+  /** Hilbert tile ID, exact within the supported zoom range. */
+  readonly tileId: number;
+  /** Relative byte offset. */
+  readonly offset: number;
+  /** Nonzero byte length. */
+  readonly length: number;
+  /** One for a tile, zero for a leaf directory. */
+  readonly runLength: number;
+}
+
+/** A snapshot of a caller's tile payload, sorted independently of input ordering. */
+interface EncodedTile {
+  /** Hilbert tile address. */
+  readonly tileId: number;
+  /** Owned payload bytes. */
+  readonly bytes: Uint8Array<ArrayBuffer>;
+}
+
+/**
+ * Packages explicit encoded XYZ tiles into a deterministic PMTiles v3 ArrayBuffer.
+ * Input payloads are opaque and must all match the declared format and compression.
+ * The input snapshots and complete output coexist in memory; this is not an out-of-core writer.
+ */
+export async function encodePMTiles(
+  input: PMTilesTileInput,
+  options?: PMTilesEncodeOptions
+): Promise<ArrayBuffer> {
+  options?.signal?.throwIfAborted();
+  if (!options || !Object.hasOwn(TILE_TYPES, options.tileType))
+    throw new TypeError('PMTiles requires a supported tileType');
+  options = {
+    ...options,
+    bounds: options.bounds?.slice() as PMTilesEncodeOptions['bounds'],
+    center: options.center?.slice() as PMTilesEncodeOptions['center']
+  };
+  const tileCompression = options.tileCompression ?? 'none';
+  const internalCompression = options.internalCompression ?? 'none';
+  if (
+    !Object.hasOwn(COMPRESSIONS, tileCompression) ||
+    !['none', 'gzip'].includes(internalCompression)
+  )
+    throw new TypeError('Unsupported PMTiles compression');
+  const maxTiles = validateLimit(options.maxTiles ?? 100000, 'tile');
+  const maxOutputBytes = validateLimit(options.maxOutputBytes ?? 256 * 1024 * 1024, 'output');
+  const maxMetadataBytes = validateLimit(options.maxMetadataBytes ?? 1024 * 1024, 'metadata');
+  const metadata = encodeMetadata(
+    options.metadata ?? {},
+    options.tileType === 'mvt',
+    maxMetadataBytes
+  );
+  const tiles: EncodedTile[] = [];
+  const tileIds = new Set<number>();
+  const bounds: [number, number, number, number] = [180, 90, -180, -90];
+  let minZoom = 26;
+  let maxZoom = 0;
+  let payloadBytes = 0;
+  for await (const tile of input) {
+    options.signal?.throwIfAborted();
+    if (tiles.length >= maxTiles) throw new RangeError('PMTiles tile limit exceeded');
+    if (
+      !Number.isInteger(tile.z) ||
+      tile.z < 0 ||
+      tile.z > 26 ||
+      !Number.isInteger(tile.x) ||
+      !Number.isInteger(tile.y) ||
+      tile.x < 0 ||
+      tile.y < 0 ||
+      tile.x >= 2 ** tile.z ||
+      tile.y >= 2 ** tile.z
+    )
+      throw new RangeError('Invalid PMTiles XYZ tile coordinate');
+    const tileId = zxyToTileId(tile.z, tile.x, tile.y);
+    if (tileIds.has(tileId)) throw new Error('Duplicate PMTiles tile coordinate');
+    const data = tile.data;
+    if (!(data instanceof Blob) && !(data instanceof ArrayBuffer) && !ArrayBuffer.isView(data))
+      throw new TypeError('PMTiles tile data must be a Blob, ArrayBuffer or typed-array view');
+    const size = data instanceof Blob ? data.size : data.byteLength;
+    if (!size) throw new RangeError('PMTiles tile payload must be nonempty');
+    payloadBytes += size;
+    if (HEADER_BYTES + payloadBytes > maxOutputBytes)
+      throw new RangeError('PMTiles output limit exceeded');
+    const bytes =
+      data instanceof Blob
+        ? new Uint8Array(await data.arrayBuffer())
+        : data instanceof ArrayBuffer
+          ? new Uint8Array(data).slice()
+          : new Uint8Array(data.buffer, data.byteOffset, data.byteLength).slice();
+    options.signal?.throwIfAborted();
+    tileIds.add(tileId);
+    tiles.push({tileId, bytes});
+    minZoom = Math.min(minZoom, tile.z);
+    maxZoom = Math.max(maxZoom, tile.z);
+    const width = 2 ** tile.z;
+    bounds[0] = Math.min(bounds[0], (tile.x / width) * 360 - 180);
+    bounds[1] = Math.min(bounds[1], getLatitude((tile.y + 1) / width));
+    bounds[2] = Math.max(bounds[2], ((tile.x + 1) / width) * 360 - 180);
+    bounds[3] = Math.max(bounds[3], getLatitude(tile.y / width));
+  }
+  if (!tiles.length) throw new RangeError('PMTiles requires at least one tile');
+  const outputBounds = options.bounds ?? bounds;
+  validateBounds(outputBounds);
+  const center = options.center ?? [
+    (outputBounds[0] + outputBounds[2]) / 2,
+    (outputBounds[1] + outputBounds[3]) / 2,
+    minZoom
+  ];
+  if (
+    center.length !== 3 ||
+    !Number.isFinite(center[0]) ||
+    Math.abs(center[0]) > 180 ||
+    !Number.isFinite(center[1]) ||
+    Math.abs(center[1]) > 90 ||
+    !Number.isInteger(center[2]) ||
+    center[2] < minZoom ||
+    center[2] > maxZoom
+  )
+    throw new RangeError('Invalid PMTiles center');
+  tiles.sort((first, second) => first.tileId - second.tileId);
+  let offset = 0;
+  const entries = tiles.map(tile => {
+    const entry = {tileId: tile.tileId, offset, length: tile.bytes.byteLength, runLength: 1};
+    offset += entry.length;
+    return entry;
+  });
+  /** Compresses internal sections with the shared first-party codec, when requested. */
+  const compress = async (bytes: Uint8Array<ArrayBuffer>): Promise<Uint8Array<ArrayBuffer>> => {
+    options.signal?.throwIfAborted();
+    const result =
+      internalCompression === 'gzip'
+        ? new Uint8Array(await new GZipCompressor().compress(bytes.buffer))
+        : bytes;
+    options.signal?.throwIfAborted();
+    return result;
+  };
+  let root = await compress(encodeDirectory(entries));
+  const leaves: Uint8Array<ArrayBuffer>[] = [];
+  let leafBytes = 0;
+  if (root.byteLength > MAX_ROOT_BYTES) {
+    const pointers: DirectoryEntry[] = [];
+    // Bound root entries even at zoom 26 with large offset varints.
+    const entriesPerLeaf = Math.max(1024, Math.ceil(entries.length / 512));
+    for (let index = 0; index < entries.length; index += entriesPerLeaf) {
+      const leaf = await compress(encodeDirectory(entries.slice(index, index + entriesPerLeaf)));
+      pointers.push({
+        tileId: entries[index].tileId,
+        offset: leafBytes,
+        length: leaf.byteLength,
+        runLength: 0
+      });
+      leaves.push(leaf);
+      leafBytes += leaf.byteLength;
+      if (HEADER_BYTES + leafBytes + payloadBytes > maxOutputBytes)
+        throw new RangeError('PMTiles output limit exceeded');
+    }
+    root = await compress(encodeDirectory(pointers));
+  }
+  if (root.byteLength > MAX_ROOT_BYTES)
+    throw new RangeError('PMTiles root directory limit exceeded');
+  const encodedMetadata = await compress(metadata);
+  const metadataOffset = HEADER_BYTES + root.byteLength;
+  const leafOffset = metadataOffset + encodedMetadata.byteLength;
+  const tileOffset = leafOffset + leafBytes;
+  const outputLength = tileOffset + payloadBytes;
+  if (outputLength > maxOutputBytes) throw new RangeError('PMTiles output limit exceeded');
+  const output = new Uint8Array(outputLength);
+  output.set(new TextEncoder().encode('PMTiles'));
+  output[7] = 3;
+  const header = new DataView(output.buffer);
+  const fields = [
+    HEADER_BYTES,
+    root.byteLength,
+    metadataOffset,
+    encodedMetadata.byteLength,
+    leafOffset,
+    leafBytes,
+    tileOffset,
+    payloadBytes,
+    tiles.length,
+    tiles.length,
+    tiles.length
+  ];
+  fields.forEach((value, index) => header.setBigUint64(8 + index * 8, BigInt(value), true));
+  output.set(
+    [
+      1,
+      COMPRESSIONS[internalCompression],
+      COMPRESSIONS[tileCompression],
+      TILE_TYPES[options.tileType],
+      minZoom,
+      maxZoom
+    ],
+    96
+  );
+  outputBounds.forEach((value, index) =>
+    header.setInt32(102 + index * 4, Math.round(value * 1e7), true)
+  );
+  output[118] = center[2];
+  header.setInt32(119, Math.round(center[0] * 1e7), true);
+  header.setInt32(123, Math.round(center[1] * 1e7), true);
+  offset = HEADER_BYTES;
+  for (const section of [root, encodedMetadata, ...leaves, ...tiles.map(tile => tile.bytes)]) {
+    output.set(section, offset);
+    offset += section.byteLength;
+  }
+  options.signal?.throwIfAborted();
+  return output.buffer;
+}
+
+/** Serializes directory columns with delta tile IDs and contiguous offset markers. */
+function encodeDirectory(entries: readonly DirectoryEntry[]): Uint8Array<ArrayBuffer> {
+  const bytes: number[] = [];
+  writeVarint(bytes, entries.length);
+  let previousTileId = 0;
+  for (const entry of entries) {
+    writeVarint(bytes, entry.tileId - previousTileId);
+    previousTileId = entry.tileId;
+  }
+  for (const entry of entries) writeVarint(bytes, entry.runLength);
+  for (const entry of entries) writeVarint(bytes, entry.length);
+  for (let index = 0; index < entries.length; index++) {
+    const entry = entries[index];
+    const previous = entries[index - 1];
+    writeVarint(
+      bytes,
+      previous && entry.offset === previous.offset + previous.length ? 0 : entry.offset + 1
+    );
+  }
+  return Uint8Array.from(bytes);
+}
+
+/** Writes unsigned base-128 varints without 32-bit truncation of zoom-26 IDs. */
+function writeVarint(output: number[], value: number): void {
+  while (value >= 128) {
+    output.push((value % 128) + 128);
+    value = Math.floor(value / 128);
+  }
+  output.push(value);
+}
+
+/** Checks configurable budgets before consuming the caller's tile iterator. */
+function validateLimit(value: number, name: string): number {
+  if (!Number.isSafeInteger(value) || value < 1)
+    throw new RangeError(`Invalid PMTiles ${name} limit`);
+  return value;
+}
+
+/** Validates geographic bounds independently of tile-local payload coordinates. */
+function validateBounds(bounds: readonly number[]): void {
+  if (
+    bounds.length !== 4 ||
+    bounds.some(value => !Number.isFinite(value)) ||
+    Math.abs(bounds[0]) > 180 ||
+    Math.abs(bounds[2]) > 180 ||
+    Math.abs(bounds[1]) > 90 ||
+    Math.abs(bounds[3]) > 90 ||
+    bounds[0] > bounds[2] ||
+    bounds[1] > bounds[3]
+  )
+    throw new RangeError('Invalid PMTiles bounds');
+}
+
+/** Converts a normalized Web Mercator tile edge to latitude. */
+function getLatitude(value: number): number {
+  return (Math.atan(Math.sinh(Math.PI * (1 - 2 * value))) * 180) / Math.PI;
+}
+
+/** Encodes a JSON object and enforces MVT's required TileJSON layer declarations. */
+function encodeMetadata(
+  metadata: Readonly<Record<string, unknown>>,
+  mvt: boolean,
+  limit: number
+): Uint8Array<ArrayBuffer> {
+  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata))
+    throw new TypeError('PMTiles metadata must be a JSON object');
+  const json = JSON.stringify(metadata);
+  const normalized = JSON.parse(json);
+  if (!normalized || typeof normalized !== 'object' || Array.isArray(normalized))
+    throw new TypeError('PMTiles metadata must serialize to a JSON object');
+  if (mvt || normalized.vector_layers !== undefined) {
+    const layers = normalized.vector_layers;
+    const ids = new Set<string>();
+    if (!Array.isArray(layers) || !layers.length)
+      throw new TypeError('PMTiles vector_layers must declare at least one layer');
+    for (const layer of layers) {
+      if (
+        !layer ||
+        typeof layer.id !== 'string' ||
+        !layer.id ||
+        ids.has(layer.id) ||
+        !layer.fields ||
+        typeof layer.fields !== 'object' ||
+        Array.isArray(layer.fields) ||
+        Object.values(layer.fields).some(
+          value => !['String', 'Number', 'Boolean'].includes(value as string)
+        )
+      )
+        throw new TypeError('Invalid PMTiles vector_layers declaration');
+      ids.add(layer.id);
+    }
+  }
+  const bytes = new TextEncoder().encode(json);
+  if (bytes.byteLength > limit) throw new RangeError('PMTiles metadata limit exceeded');
+  return bytes;
+}

package/src/pmtiles/lib/parse-pmtiles.ts

@@ -0,0 +1,180 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {
+  createTileGrid,
+  createWebMercatorTileGrid,
+  type TileGrid,
+  LoaderOptions
+} from '@loaders.gl/core/loader-utils';
+import type {TileJSON} from '@loaders.gl/tiles/mvt';
+import {parseTileJSON} from '@loaders.gl/tiles/mvt';
+// import {Source, PMTiles, Header, TileType} from 'pmtiles';
+import * as pmtiles from 'pmtiles';
+const {TileType} = pmtiles;
+
+/** Metadata describing a PMTiles file */
+export type PMTilesMetadata = {
+  format: 'pmtiles';
+  /** Native XYZ levels; complete geometry requires an explicit source CRS contract. */
+  tileGrid?: TileGrid;
+  /** Version of pm tiles format used by this tileset */
+  formatVersion: number;
+
+  /** MIME type for tile contents. Unknown tile types will return 'application/octet-stream */
+  tileMIMEType:
+    | 'application/vnd.mapbox-vector-tile'
+    | 'application/vnd.maplibre-tile'
+    | 'image/png'
+    | 'image/jpeg'
+    | 'image/webp'
+    | 'image/avif'
+    | 'application/octet-stream';
+
+  /** Name of the tileset (extracted from JSON metadata if available) */
+  name?: string;
+  /** Attribution string (extracted from JSON metadata if available) */
+  attributions?: string[];
+
+  /** Minimal zoom level of tiles in this tileset */
+  minZoom: number;
+  /** Maximal zoom level of tiles in this tileset */
+  maxZoom: number;
+  /** Bounding box of tiles in this tileset `[[w, s], [e, n]]`  */
+  boundingBox: [min: [x: number, y: number], max: [x: number, y: number]];
+  /** Center long, lat of this tileset */
+  center: [number, number];
+  /** Center zoom level of this tileset */
+  centerZoom: number;
+  /** Cache tag */
+  etag?: string;
+
+  /** Parsed TileJSON/tilestats metadata, if present */
+  tilejson?: TileJSON;
+
+  /** @deprecated PMTiles format specific header */
+  formatHeader?: pmtiles.Header;
+  /** @deprecated Unparsed metadata (Assumption metadata generated by e.g. tippecanoe, typically TileJSON) */
+  formatMetadata?: Record<string, unknown>;
+};
+
+/**
+ * Parse PMTiles metdata from a PMTiles file
+ * @param header
+ * @param tilejsonMetadata
+ * @param options
+ * @param loadOptions
+ * @returns
+ */
+export function parsePMTilesHeader(
+  header: pmtiles.Header,
+  pmtilesMetadata: Record<string, unknown> | null,
+  options?: {
+    /** Include the deprecated raw format header. */
+    includeFormatHeader?: boolean;
+    /** Explicit source contract for geographic XYZ geometry. */
+    coordinateReferenceSystem?: 'EPSG:3857';
+    /** Logical tile size; independent of encoded tile dimensions. */
+    tileSize?: number;
+  },
+  loadOptions?: LoaderOptions
+): PMTilesMetadata {
+  // Ironically, to use the TileJSON loader we need to stringify the metadata again.
+  // This is the price of integrating with the existing pmtiles library.
+  // TODO - provide a non-standard TileJSONLoader parsers that accepts a JSON object?
+  let tilejson: TileJSON | null = null;
+  if (pmtilesMetadata) {
+    try {
+      tilejson = parseTileJSON(pmtilesMetadata, (loadOptions as any)?.tilejson) || null;
+    } catch (error) {
+      // eslint-disable-next-line no-console
+      console.warn('PMTiles metadata could not be interpreted as TileJSON', error);
+    }
+  }
+
+  const partialMetadata: Partial<PMTilesMetadata> = {};
+
+  if (typeof tilejson?.name === 'string') {
+    partialMetadata.name = tilejson.name;
+  }
+
+  if (typeof tilejson?.htmlAttribution === 'string') {
+    partialMetadata.attributions = [tilejson.htmlAttribution];
+  }
+
+  // Preserve native header metadata even when its range cannot form a supported numeric grid.
+  const canonicalGrid =
+    Number.isInteger(header.minZoom) &&
+    Number.isInteger(header.maxZoom) &&
+    header.minZoom >= 0 &&
+    header.maxZoom >= header.minZoom &&
+    header.maxZoom <= 31
+      ? createWebMercatorTileGrid(header.minZoom, header.maxZoom, options?.tileSize ?? 256)
+      : undefined;
+  const tileGrid =
+    !canonicalGrid || options?.coordinateReferenceSystem === 'EPSG:3857'
+      ? canonicalGrid
+      : createTileGrid(
+          undefined,
+          canonicalGrid.matrices!.map(({id, tileSize, matrixSize}) => ({id, tileSize, matrixSize}))
+        );
+  const metadata: PMTilesMetadata = {
+    ...partialMetadata,
+    format: 'pmtiles',
+    tileGrid,
+    formatVersion: header.specVersion,
+    attributions: [],
+    tileMIMEType: decodeTileType(header.tileType),
+    minZoom: header.minZoom,
+    maxZoom: header.maxZoom,
+    boundingBox: [
+      [header.minLon, header.minLat],
+      [header.maxLon, header.maxLat]
+    ],
+    center: [header.centerLon, header.centerLat],
+    centerZoom: header.centerZoom,
+    etag: header.etag
+  };
+
+  if (tilejson) {
+    metadata.tilejson = tilejson;
+  }
+
+  // Application can optionally include the raw header and metadata.
+  if (options?.includeFormatHeader) {
+    metadata.formatHeader = header;
+    metadata.formatMetadata = metadata;
+  }
+
+  return metadata;
+}
+
+/** Extract a MIME type for tiles from vector tile header  */
+function decodeTileType(
+  tileType: pmtiles.TileType
+):
+  | 'application/vnd.mapbox-vector-tile'
+  | 'application/vnd.maplibre-tile'
+  | 'image/png'
+  | 'image/jpeg'
+  | 'image/webp'
+  | 'image/avif'
+  | 'application/octet-stream' {
+  switch (tileType) {
+    case TileType.Mvt:
+      return 'application/vnd.mapbox-vector-tile';
+    case TileType.Mlt:
+      return 'application/vnd.maplibre-tile';
+    case TileType.Png:
+      return 'image/png';
+    case TileType.Jpeg:
+      return 'image/jpeg';
+    case TileType.Webp:
+      return 'image/webp';
+    case TileType.Avif:
+      return 'image/avif';
+    default:
+      return 'application/octet-stream';
+  }
+}

package/src/pmtiles/lib/range-request-source.ts

@@ -0,0 +1,60 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {
+  RangeRequestScheduler,
+  type RangeRequestSchedulerProps
+} from '@loaders.gl/core/loader-utils';
+import type {Source, RangeResponse} from 'pmtiles';
+
+/** Options for the PMTiles range-request source adapter. */
+export type RangeRequestSourceOptions = RangeRequestSchedulerProps & {
+  /** Fetch function used for PMTiles HTTP requests. */
+  fetch?: (url: string, options?: RequestInit) => Promise<Response>;
+};
+
+/**
+ * PMTiles compatible source that reads HTTP byte ranges through a coalescing scheduler.
+ */
+export class RangeRequestSource implements Source {
+  /** URL of the PMTiles archive. */
+  readonly url: string;
+  private readonly fetch: (url: string, options?: RequestInit) => Promise<Response>;
+  private readonly scheduler: RangeRequestScheduler;
+  private readonly requestContext = {};
+
+  /** Creates a PMTiles package Source backed by scheduled HTTP range requests. */
+  constructor(url: string, options: RangeRequestSourceOptions = {}) {
+    this.url = url;
+    this.fetch = options.fetch || fetch;
+    this.scheduler = new RangeRequestScheduler({
+      batchDelayMs: options.batchDelayMs ?? 0,
+      maxGapBytes: options.maxGapBytes,
+      rangeExpansionBytes: options.rangeExpansionBytes,
+      maxMergedBytes: options.maxMergedBytes,
+      stats: options.stats,
+      onEvent: options.onEvent
+    });
+  }
+
+  /** Returns the PMTiles source cache key. */
+  getKey(): string {
+    return this.url;
+  }
+
+  /** Reads an exact byte range from the PMTiles archive. */
+  async getBytes(offset: number, length: number, signal?: AbortSignal): Promise<RangeResponse> {
+    const data = await this.scheduler.fetch({
+      sourceId: this.url,
+      url: this.url,
+      offset,
+      length,
+      signal,
+      isolationKey: this.requestContext,
+      fetch: this.fetch
+    });
+
+    return {data};
+  }
+}

package/src/pmtiles/lib/version.ts

@@ -0,0 +1,8 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// Version constant cannot be imported, it needs to correspond to the build version of **this** module.
+// __VERSION__ is injected by babel-plugin-version-inline
+// @ts-ignore TS2304: Cannot find name '__VERSION__'.
+export const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';

package/src/pmtiles/pmtiles-format.ts

@@ -0,0 +1,19 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Format} from '@loaders.gl/core/loader-utils';
+
+/**
+ * PMTiles
+ */
+export const PMTilesFormat = {
+  name: 'PMTiles',
+  id: 'pmtiles',
+  module: 'tiles',
+  encoding: 'binary',
+  format: 'pmtiles',
+  extensions: ['pmtiles'],
+  mimeTypes: ['application/vnd.pmtiles', 'application/octet-stream'],
+  tests: ['PMTiles']
+} as const satisfies Format;

package/src/pmtiles/pmtiles-loader-with-parser.ts

@@ -0,0 +1,60 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {LoaderWithParser, LoaderOptions, ReadableFile} from '@loaders.gl/core/loader-utils';
+import {BlobFile} from '@loaders.gl/core/loader-utils';
+
+import {VectorSourceInfo, ImageSourceInfo} from './source-info';
+import {PMTilesTileSource, PMTilesSourceLoaderOptions} from './pmtiles-source-loader';
+import {PMTilesLoader as PMTilesLoaderMetadata} from './pmtiles-loader';
+
+const {preload: _PMTilesLoaderPreload, ...PMTilesLoaderMetadataWithoutPreload} =
+  PMTilesLoaderMetadata;
+
+export type PMTilesLoaderOptions = LoaderOptions & {
+  pmtiles?: PMTilesSourceLoaderOptions['pmtiles'];
+};
+
+/**
+ * Loader for PMTiles metadata
+ * @note This loader is intended to allow PMTiles to be treated like other file types in top-level loading logic.
+ * @note For actual access to the tile data, use the PMTilesSourceLoader class.
+ */
+export const PMTilesLoaderWithParser = {
+  ...PMTilesLoaderMetadataWithoutPreload,
+  parse: async (arrayBuffer: ArrayBuffer, options?: PMTilesLoaderOptions) =>
+    parseFileAsPMTiles(new BlobFile(new Blob([arrayBuffer])), options),
+  parseFile: parseFileAsPMTiles
+} as const satisfies LoaderWithParser<
+  VectorSourceInfo | ImageSourceInfo,
+  never,
+  PMTilesLoaderOptions
+>;
+
+async function parseFileAsPMTiles(
+  file: ReadableFile,
+  options?: PMTilesLoaderOptions
+): Promise<VectorSourceInfo | ImageSourceInfo> {
+  const source = new PMTilesTileSource(file.handle as string | Blob, {
+    pmtiles: options?.pmtiles || {}
+  });
+  const formatSpecificMetadata = await source.getMetadata();
+  const {tileMIMEType, tilejson = {}} = formatSpecificMetadata;
+  const {layers = []} = tilejson;
+  switch (tileMIMEType) {
+    case 'application/vnd.mapbox-vector-tile':
+    case 'application/vnd.maplibre-tile':
+      return {
+        shape: 'vector-source',
+        layers: layers.map(layer => ({name: layer.name, schema: layer.schema})),
+        tables: [],
+        formatSpecificMetadata
+      } as VectorSourceInfo;
+    case 'image/png':
+    case 'image/jpeg':
+      return {shape: 'image-source', formatSpecificMetadata} as ImageSourceInfo;
+    default:
+      throw new Error(`PMTilesLoaderWithParser: Unsupported tile MIME type ${tileMIMEType}`);
+  }
+}

package/src/pmtiles/pmtiles-loader.ts

@@ -0,0 +1,30 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Loader, LoaderOptions} from '@loaders.gl/core/loader-utils';
+import {VERSION} from './lib/version';
+
+import {VectorSourceInfo, ImageSourceInfo} from './source-info';
+import type {PMTilesSourceLoaderOptions} from './pmtiles-source-loader';
+import {PMTilesFormat} from './pmtiles-format';
+
+export type PMTilesLoaderOptions = LoaderOptions & {
+  pmtiles?: PMTilesSourceLoaderOptions['pmtiles'];
+};
+
+/** Preloads the parser-bearing PMTiles loader implementation. */
+async function preload() {
+  const {PMTilesLoaderWithParser} = await import('./pmtiles-loader-with-parser');
+  return PMTilesLoaderWithParser;
+}
+
+/** Metadata-only loader for PMTiles metadata. */
+export const PMTilesLoader = {
+  ...PMTilesFormat,
+  version: VERSION,
+  options: {
+    pmtiles: {}
+  },
+  preload
+} as const satisfies Loader<VectorSourceInfo | ImageSourceInfo, never, PMTilesLoaderOptions>;