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

package/src/mvt/map-style.ts

@@ -0,0 +1,218 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {LoaderContext, LoaderOptions} from '@loaders.gl/core/loader-utils';
+import {MapStyleSchema, MapStyleSourceSchema, ResolvedMapStyleSchema} from './map-style-schema';
+
+/**
+ * A style source entry from a MapLibre or Mapbox style document.
+ */
+export type MapStyleSource = {
+  /** Source kind such as `vector` or `raster`. */
+  type?: string;
+  /** Optional TileJSON URL used to resolve the source metadata. */
+  url?: string;
+  /** Inline tile templates for the source. */
+  tiles?: string[];
+  /** Minimum source zoom. */
+  minzoom?: number;
+  /** Maximum source zoom. */
+  maxzoom?: number;
+  /** Tile size in pixels. */
+  tileSize?: number;
+  /** Additional source properties are preserved verbatim. */
+  [key: string]: unknown;
+};
+
+/**
+ * A style layer entry.
+ */
+export type MapStyleLayer = {
+  /** Unique layer identifier. */
+  id: string;
+  /** Style layer type such as `background`, `fill`, `line`, `symbol`, or `raster`. */
+  type: string;
+  /** Referenced source identifier. */
+  source?: string;
+  /** Referenced vector source-layer identifier. */
+  'source-layer'?: string;
+  /** Optional minimum zoom. */
+  minzoom?: number;
+  /** Optional maximum zoom. */
+  maxzoom?: number;
+  /** Optional style-spec filter expression. */
+  filter?: unknown[];
+  /** Paint properties from the source style layer. */
+  paint?: Record<string, unknown>;
+  /** Layout properties from the source style layer. */
+  layout?: Record<string, unknown>;
+  /** Additional layer properties are preserved verbatim. */
+  [key: string]: unknown;
+};
+
+/**
+ * A MapLibre or Mapbox style document.
+ */
+export type MapStyle = {
+  /** Style-spec version number. */
+  version?: number;
+  /** Optional style metadata bag. */
+  metadata?: Record<string, unknown>;
+  /** Named source definitions used by the style. */
+  sources?: Record<string, MapStyleSource>;
+  /** Ordered list of style layers. */
+  layers?: MapStyleLayer[];
+  /** Additional style properties are preserved verbatim. */
+  [key: string]: unknown;
+};
+
+/**
+ * A style document after all sources have been normalized and TileJSON-backed sources resolved.
+ */
+export type ResolvedMapStyle = MapStyle & {
+  /** Fully resolved source definitions. */
+  sources: Record<string, MapStyleSource>;
+  /** Style layers copied into a mutable array. */
+  layers: MapStyleLayer[];
+};
+
+/**
+ * Load options accepted by {@link resolveMapStyle}.
+ */
+export type MapStyleLoadOptions = LoaderOptions & {
+  mapStyle?: {
+    /** Base URL used to resolve relative style source or tile URLs. */
+    baseUrl?: string;
+    /** Optional custom fetch implementation. */
+    fetch?: typeof fetch;
+    /** Optional init object passed to the selected fetch implementation. */
+    fetchOptions?: RequestInit;
+    /** Additional loader options are accepted for forward compatibility. */
+    [key: string]: unknown;
+  };
+};
+
+/**
+ * Extracts map style options from loader options and loader context.
+ */
+export function getMapStyleLoadOptions(
+  options?: MapStyleLoadOptions,
+  context?: LoaderContext
+): NonNullable<MapStyleLoadOptions['mapStyle']> {
+  return {
+    ...options?.mapStyle,
+    baseUrl: options?.mapStyle?.baseUrl || context?.url || context?.baseUrl,
+    fetch: options?.mapStyle?.fetch || (context?.fetch as typeof fetch | undefined)
+  };
+}
+
+/**
+ * Resolves a URL against the provided base URL.
+ */
+export function normalizeMapStyleUrl(
+  url: string | undefined,
+  baseUrl?: string
+): string | undefined {
+  if (!url) {
+    return url;
+  }
+
+  try {
+    return decodeURI(new URL(url, baseUrl).toString());
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * Resolves all tile templates in a source against the provided base URL.
+ */
+export function normalizeMapStyleTiles(
+  tiles: string[] | undefined,
+  baseUrl?: string
+): string[] | undefined {
+  return Array.isArray(tiles)
+    ? tiles.map(tile => normalizeMapStyleUrl(tile, baseUrl) || tile)
+    : tiles;
+}
+
+/**
+ * Fetches and parses a JSON resource.
+ */
+export async function fetchMapStyleJson(
+  url: string,
+  loadOptions?: NonNullable<MapStyleLoadOptions['mapStyle']>
+): Promise<unknown> {
+  const fetchFunction = loadOptions?.fetch || fetch;
+  const response = await fetchFunction(url, loadOptions?.fetchOptions);
+
+  if (!response.ok) {
+    throw new Error(`Failed to load map style resource: ${url} (${response.status})`);
+  }
+
+  return await response.json();
+}
+
+/**
+ * Resolves a single source, including optional TileJSON indirection.
+ */
+export async function resolveMapStyleSource(
+  source: MapStyleSource | undefined,
+  baseUrl: string | undefined,
+  loadOptions?: NonNullable<MapStyleLoadOptions['mapStyle']>
+): Promise<MapStyleSource | undefined> {
+  if (!source) {
+    return source;
+  }
+
+  const resolvedSource: MapStyleSource = {...source};
+  let sourceBaseUrl = baseUrl;
+
+  if (resolvedSource.url) {
+    const tileJsonUrl = normalizeMapStyleUrl(resolvedSource.url, baseUrl);
+    const tileJson = MapStyleSourceSchema.parse(
+      await fetchMapStyleJson(tileJsonUrl || resolvedSource.url, loadOptions)
+    );
+    Object.assign(resolvedSource, tileJson);
+    resolvedSource.url = tileJsonUrl;
+    sourceBaseUrl = tileJsonUrl;
+  }
+
+  if (resolvedSource.tiles) {
+    resolvedSource.tiles = normalizeMapStyleTiles(resolvedSource.tiles, sourceBaseUrl);
+  }
+
+  return resolvedSource;
+}
+
+/**
+ * Resolves a style input into a style object whose sources contain directly consumable tile
+ * templates and source metadata.
+ */
+export async function resolveMapStyle(
+  style: string | MapStyle,
+  options?: MapStyleLoadOptions
+): Promise<ResolvedMapStyle> {
+  const mapStyleOptions = getMapStyleLoadOptions(options);
+  const styleDefinition = MapStyleSchema.parse(
+    typeof style === 'string'
+      ? await fetchMapStyleJson(style, mapStyleOptions)
+      : structuredClone(style)
+  );
+  const baseUrl = typeof style === 'string' ? style : mapStyleOptions.baseUrl;
+  const resolvedSources: Record<string, MapStyleSource> = {};
+
+  await Promise.all(
+    Object.entries(styleDefinition.sources || {}).map(async ([sourceId, source]) => {
+      resolvedSources[sourceId] =
+        (await resolveMapStyleSource(source, baseUrl, mapStyleOptions)) || {};
+    })
+  );
+
+  return ResolvedMapStyleSchema.parse({
+    ...styleDefinition,
+    sources: resolvedSources,
+    layers: [...(styleDefinition.layers || [])]
+  });
+}

package/src/mvt/mvt-format.ts

@@ -0,0 +1,25 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
+import type {Format} from '@loaders.gl/core/loader-utils';
+
+/**
+ * Worker loader for the Mapbox Vector Tile format
+ */
+export const MVTFormat = {
+  name: 'Mapbox Vector Tile',
+  id: 'mvt',
+  module: 'tiles',
+  encoding: 'protobuf',
+  format: 'mvt',
+  // Note: ArcGIS uses '.pbf' extension and 'application/octet-stream'
+  extensions: ['mvt', 'pbf'],
+  mimeTypes: [
+    // https://www.iana.org/assignments/media-types/application/vnd.mapbox-vector-tile
+    'application/vnd.mapbox-vector-tile',
+    'application/x-protobuf'
+    // 'application/octet-stream'
+  ],
+  category: 'geometry'
+} as const satisfies Format;

package/src/mvt/mvt-geojson-loader-types.ts

@@ -0,0 +1,60 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Loader, LoaderOptions} from '@loaders.gl/core/loader-utils';
+import {MVTFormat} from './mvt-format';
+import type {MVTGeoJSONOptions, MVTGeoJSONTable} from './lib/types';
+
+// __VERSION__ is injected by babel-plugin-version-inline.
+// @ts-ignore TS2304: Cannot find name '__VERSION__'.
+const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
+
+/** Options for parsing a Mapbox Vector Tile as a GeoJSON feature collection. */
+export type MVTGeoJSONLoaderOptions = LoaderOptions &
+  MVTGeoJSONOptions & {
+    /** Fixed output shape of this loader. */
+    shape?: 'geojson-table';
+    mvt?: {
+      /** Output shape is fixed to `geojson-table`. */
+      shape?: 'geojson-table';
+      /** Coordinate system for returned feature coordinates. */
+      coordinates?: 'wgs84' | 'local';
+      /** Tile index required when coordinates are requested in WGS84. */
+      tileIndex?: {x: number; y: number; z: number};
+      /** Add each feature's source layer name to this property. */
+      layerProperty?: string | number | null;
+      /** Include source-layer provenance outside feature properties. */
+      sourceLayer?: boolean;
+      /** Return features from only the named vector-tile layers. */
+      layers?: string[];
+    };
+  };
+
+/** Preload the parser-bearing GeoJSON-only MVT loader. */
+async function preload() {
+  const {MVTGeoJSONLoaderWithParser} = await import('@loaders.gl/tiles/mvt/mvt-geojson-loader');
+  return MVTGeoJSONLoaderWithParser;
+}
+
+/** Lightweight metadata loader for GeoJSON output from Mapbox Vector Tiles. */
+export const MVTGeoJSONLoader = {
+  ...MVTFormat,
+  name: 'Mapbox Vector Tile (GeoJSON)',
+  dataType: null as unknown as MVTGeoJSONTable,
+  batchType: null as never,
+  version: VERSION,
+  worker: false,
+  options: {
+    mvt: {
+      shape: 'geojson-table',
+      coordinates: 'local',
+      layerProperty: 'layerName',
+      sourceLayer: false,
+      layers: undefined!,
+      tileIndex: undefined!
+    }
+  },
+  preload,
+  binary: true
+} as const satisfies Loader<MVTGeoJSONTable, never, MVTGeoJSONLoaderOptions>;

package/src/mvt/mvt-geojson-loader.ts

@@ -0,0 +1,20 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {LoaderWithParser} from '@loaders.gl/core/loader-utils';
+import type {MVTGeoJSONTable} from './lib/types';
+import {parseMVTGeoJSON} from './lib/parse-mvt-geojson';
+import {MVTGeoJSONLoader as MVTGeoJSONLoaderMetadata} from './mvt-geojson-loader-types';
+import type {MVTGeoJSONLoaderOptions} from './mvt-geojson-loader-types';
+
+const {preload: _MVTGeoJSONLoaderPreload, ...MVTGeoJSONLoaderMetadataWithoutPreload} =
+  MVTGeoJSONLoaderMetadata;
+
+/** Parser-bearing GeoJSON-only loader for Mapbox Vector Tiles. */
+export const MVTGeoJSONLoaderWithParser = {
+  ...MVTGeoJSONLoaderMetadataWithoutPreload,
+  parse: async (arrayBuffer, options?: MVTGeoJSONLoaderOptions) =>
+    parseMVTGeoJSON(arrayBuffer, options),
+  parseSync: parseMVTGeoJSON
+} as const satisfies LoaderWithParser<MVTGeoJSONTable, never, MVTGeoJSONLoaderOptions>;

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

@@ -0,0 +1,53 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
+import type {LoaderWithParser, LoaderOptions} from '@loaders.gl/core/loader-utils';
+import type {GeoArrowEncodingPreference} from '@loaders.gl/core/schema';
+// import type {MVTOptions} from './lib/types';
+import {parseMVT} from './lib/parse-mvt';
+import {deserializeMVTWorkerResult, serializeMVTWorkerResult} from './lib/mvt-worker-transport';
+import {MVTLoader as MVTLoaderMetadata} from './mvt-loader';
+
+const {preload: _MVTLoaderPreload, ...MVTLoaderMetadataWithoutPreload} = MVTLoaderMetadata;
+
+export type MVTLoaderOptions = LoaderOptions & {
+  /** Preferred encoding for Arrow geometry output. */
+  geoarrow?: {encodingPreference?: GeoArrowEncodingPreference};
+  mvt?: {
+    /** Shape of returned data */
+    shape?: 'geojson-table' | 'columnar-table' | 'binary-geometry' | 'arrow-table';
+    /** `wgs84`: coordinates in long, lat (`tileIndex` must be provided. `local` coordinates are `0-1` from tile origin */
+    coordinates?: 'wgs84' | 'local';
+    /** An object containing tile index values (`x`, `y`, `z`) to reproject features' coordinates into WGS84. Mandatory with `wgs84` coordinates option. */
+    tileIndex?: {x: number; y: number; z: number};
+    /** If provided, stored the layer name of each feature is added to `feature.properties[layerProperty]`. */
+    layerProperty?: string | number | null;
+    /** Include source-layer provenance outside feature properties for GeoJSON output. */
+    sourceLayer?: boolean;
+    /** layer filter. If provided, only features belonging to the named layers will be included, otherwise features from all layers are returned. */
+    layers?: string[];
+    /** Override the URL to the worker bundle (by default loads from unpkg.com) */
+    workerUrl?: string;
+    /** Preferred encoding for Arrow geometry output. */
+    geoarrow?: {encodingPreference?: GeoArrowEncodingPreference};
+  };
+};
+
+/**
+ * Loader for the Mapbox Vector Tile format
+ */
+export const MVTLoaderWithParser = {
+  ...MVTLoaderMetadataWithoutPreload,
+  parse: async (arrayBuffer, options?: MVTLoaderOptions) => parseMVT(arrayBuffer, options),
+  parseSync: parseMVT,
+  serializeWorkerResult: serializeMVTWorkerResult,
+  deserializeWorkerResult: deserializeMVTWorkerResult
+} as const satisfies LoaderWithParser<
+  any, // BinaryFeatureCollection | GeoJSONTable | Feature<Geometry, GeoJsonProperties>,
+  never,
+  MVTLoaderOptions
+>;
+
+/** @deprecated Use MVTLoaderWithParser. */
+export const MVTWorkerLoaderWithParser = MVTLoaderWithParser;

package/src/mvt/mvt-loader.ts

@@ -0,0 +1,73 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
+import type {Loader, LoaderOptions} from '@loaders.gl/core/loader-utils';
+import type {GeoArrowEncodingPreference} from '@loaders.gl/core/schema';
+// import type {MVTOptions} from './lib/types';
+import {MVTFormat} from './mvt-format';
+import {deserializeMVTWorkerResult, serializeMVTWorkerResult} from './lib/mvt-worker-transport';
+
+// __VERSION__ is injected by babel-plugin-version-inline
+// @ts-ignore TS2304: Cannot find name '__VERSION__'.
+const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
+
+export type MVTLoaderOptions = LoaderOptions & {
+  /** Preferred encoding for Arrow geometry output. */
+  geoarrow?: {encodingPreference?: GeoArrowEncodingPreference};
+  mvt?: {
+    /** Shape of returned data */
+    shape?: 'geojson-table' | 'columnar-table' | 'binary-geometry' | 'arrow-table';
+    /** `wgs84`: coordinates in long, lat (`tileIndex` must be provided. `local` coordinates are `0-1` from tile origin */
+    coordinates?: 'wgs84' | 'local';
+    /** An object containing tile index values (`x`, `y`, `z`) to reproject features' coordinates into WGS84. Mandatory with `wgs84` coordinates option. */
+    tileIndex?: {x: number; y: number; z: number};
+    /** If provided, stored the layer name of each feature is added to `feature.properties[layerProperty]`. */
+    layerProperty?: string | number | null;
+    /** Include source-layer provenance outside feature properties for GeoJSON output. */
+    sourceLayer?: boolean;
+    /** layer filter. If provided, only features belonging to the named layers will be included, otherwise features from all layers are returned. */
+    layers?: string[];
+    /** Override the URL to the worker bundle (by default loads from unpkg.com) */
+    workerUrl?: string;
+    /** Preferred encoding for Arrow geometry output. */
+    geoarrow?: {encodingPreference?: GeoArrowEncodingPreference};
+  };
+};
+
+/** Preloads the parser-bearing MVT loader implementation. */
+async function preload() {
+  const {MVTLoaderWithParser} = await import('./mvt-loader-with-parser');
+  return MVTLoaderWithParser;
+}
+
+/** Metadata-only loader for the Mapbox Vector Tile format. */
+export const MVTLoader = {
+  ...MVTFormat,
+  dataType: null as any,
+  batchType: null as never,
+  version: VERSION,
+  worker: true,
+  workerSourceNode: 'mvt/workers/mvt-worker-node.ts',
+  options: {
+    mvt: {
+      shape: 'arrow-table',
+      coordinates: 'local',
+      layerProperty: 'layerName',
+      sourceLayer: false,
+      layers: undefined!,
+      tileIndex: undefined!
+    }
+  },
+  serializeWorkerResult: serializeMVTWorkerResult,
+  deserializeWorkerResult: deserializeMVTWorkerResult,
+  preload,
+  binary: true
+} as const satisfies Loader<
+  any, // BinaryFeatureCollection | GeoJSONTable | Feature<Geometry, GeoJsonProperties>,
+  never,
+  MVTLoaderOptions
+>;
+
+/** @deprecated Use MVTLoader. */
+export const MVTWorkerLoader = MVTLoader;