feat: Add options.<loader>.workerUrl (#2950)

docs/whats-new.mdx

@@ -6,7 +6,8 @@ Target Release Date: April, 2024
 
 - deck.gl v9: Website and `examples/website/*` updated to deck.gl v9.
 - Internal tooling upgrades: ~10x faster builds via esbuild. ~2x faster installs via yarn 4.
-- Improved developer experience: More loader object information is visible in applications when hovering over a loader object, e.g. in vscode (loader objects are now typed using `as const satisfies Loader<...>`).
+- Types: More loader object information is preserved (e.g. when hovering over a loader object in vscod). loaders are now typed using `as const satisfies Loader<...>`. 
+- Types: Loaders that support workers now declare the `workerUrl` field in their LoaderOptions type removing type errors when overriding.
 
 **@loaders.gl/tile-converter**
 

modules/arrow/src/arrow-loader.ts

@@ -17,10 +17,16 @@ import {parseArrowInBatches} from './parsers/parse-arrow-in-batches';
 // @ts-ignore TS2304: Cannot find name '__VERSION__'.
 const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
 
+/** ArrowLoader options */
 export type ArrowLoaderOptions = LoaderOptions & {
+  /** ArrowLoader options */
   arrow?: {
+    /** Shape of returned data */
     shape: 'arrow-table' | 'columnar-table' | 'array-row-table' | 'object-row-table';
+    /** Debounce time between batches (prevent excessive numbers of small batches) */
     batchDebounceMs?: number;
+    /** Override the URL to the worker bundle (by default loads from unpkg.com) */
+    workerUrl?: string;
   };
 };
 

modules/draco/src/draco-loader.ts

@@ -9,10 +9,11 @@ import {VERSION} from './lib/utils/version';
 
 export type DracoLoaderOptions = LoaderOptions & {
   draco?: DracoParseOptions & {
+    /** @deprecated WASM decoding is faster but JS is more backwards compatible */
     decoderType?: 'wasm' | 'js';
+    /** @deprecated Specify where to load the Draco decoder library */
     libraryPath?: string;
-    extraAttributes?;
-    attributeNameEntry?: string;
+    /** Override the URL to the worker bundle (by default loads from unpkg.com) */
     workerUrl?: string;
   };
 };

modules/draco/src/lib/draco-parser.ts

@@ -28,18 +28,17 @@ import type {
 import {getMeshBoundingBox} from '@loaders.gl/schema';
 import {getDracoSchema} from './utils/get-draco-schema';
 
-/**
- * @param topology - How triangle indices should be generated (mesh only)
- * @param attributeNameEntry
- * @param extraAttributes
- * @param quantizedAttributes
- * @param octahedronAttributes
- */
+/** Options to control draco parsing */
 export type DracoParseOptions = {
+  /** How triangle indices should be generated (mesh only) */
   topology?: 'triangle-list' | 'triangle-strip';
+  /** Specify which attribute metadata entry stores the attribute name */
   attributeNameEntry?: string;
+  /** Names and ids of extra attributes to include in the output */
   extraAttributes?: {[uniqueId: string]: number};
+  /** Skip transforms specific quantized attributes */
   quantizedAttributes?: ('POSITION' | 'NORMAL' | 'COLOR' | 'TEX_COORD' | 'GENERIC')[];
+  /** Skip transforms specific octahedron encoded  attributes */
   octahedronAttributes?: ('POSITION' | 'NORMAL' | 'COLOR' | 'TEX_COORD' | 'GENERIC')[];
 };
 

modules/draco/test/data/README.md

@@ -3,3 +3,5 @@
 ## DRC
 
 Samples from Google Draco `testdata`:
+
+- `64-bit-attribute/1.pts` From https://storage.googleapis.com/external-geo-projects/GTE464_Crocodile_Lower_LAS/2/1.pnts 

modules/excel/src/excel-loader.ts

@@ -10,9 +10,14 @@ import type {ObjectRowTable} from '@loaders.gl/schema';
 const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
 
 export type ExcelLoaderOptions = LoaderOptions & {
+  /** Options for ExcelLoader */
   excel?: {
+    /** Format of returned data */
     shape?: /* 'array-row-table' | */ 'object-row-table';
-    sheet?: string; // Load default Sheet
+    /** Specify which sheet to load, if omitted loads default sheet */
+    sheet?: string;
+    /** Override the URL to the worker bundle (by default loads from unpkg.com) */
+    workerUrl?: string;
   };
 };
 

modules/flatgeobuf/src/flatgeobuf-loader.ts

@@ -15,6 +15,8 @@ const FGB_MAGIC_NUMBER = [0x66, 0x67, 0x62, 0x03, 0x66, 0x67, 0x62, 0x01];
 export type FlatGeobufLoaderOptions = LoaderOptions & {
   flatgeobuf?: {
     shape?: 'geojson-table' | 'columnar-table' | 'binary';
+    /** Override the URL to the worker bundle (by default loads from unpkg.com) */
+    workerUrl?: string;
   };
   gis?: {
     reproject?: boolean;

modules/geopackage/src/geopackage-loader.ts

@@ -20,6 +20,8 @@ export type GeoPackageLoaderOptions = LoaderOptions & {
     table?: string;
     /** Use null in Node */
     sqlJsCDN?: string | null;
+    /** Override the URL to the worker bundle (by default loads from unpkg.com) */
+    workerUrl?: string;
   };
   gis?: {
     reproject?: boolean;

modules/geopackage/src/index.ts

@@ -2,4 +2,5 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+export type {GeoPackageLoaderOptions} from './geopackage-loader';
 export {GeoPackageLoader} from './geopackage-loader';

modules/las/src/las-loader.ts

@@ -12,6 +12,8 @@ export type LASLoaderOptions = LoaderOptions & {
     fp64?: boolean;
     skip?: number;
     colorDepth?: number | string;
+    /** Override the URL to the worker bundle (by default loads from unpkg.com) */
+    workerUrl?: string;
   };
   onProgress?: Function;
 };

modules/mvt/src/helpers/binary-util-functions.ts

@@ -1,7 +1,11 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
 import Protobuf from 'pbf';
 import {getPolygonSignedArea} from '@math.gl/polygon';
 import {FlatIndexedGeometry, FlatPolygon} from '@loaders.gl/schema';
-import VectorTileFeature from '../lib/binary-vector-tile/vector-tile-feature';
+import {BinaryVectorTileFeature} from '../lib/binary-vector-tile/vector-tile-feature';
 
 /**
  * Classifies an array of rings into polygons with outer rings and holes
@@ -97,7 +101,7 @@ export function project(data: number[], x0: number, y0: number, size: number): v
  * @param feature
  * @param pbf
  */
-export function readFeature(tag: number, feature?: VectorTileFeature, pbf?: Protobuf): void {
+export function readFeature(tag: number, feature?: BinaryVectorTileFeature, pbf?: Protobuf): void {
   if (feature && pbf) {
     if (tag === 1) feature.id = pbf.readVarint();
     else if (tag === 2) readTag(pbf, feature);
@@ -110,7 +114,7 @@ export function readFeature(tag: number, feature?: VectorTileFeature, pbf?: Prot
  * @param pbf
  * @param feature
  */
-export function readTag(pbf: Protobuf, feature: VectorTileFeature): void {
+export function readTag(pbf: Protobuf, feature: BinaryVectorTileFeature): void {
   const end = pbf.readVarint() + pbf.pos;
 
   while (pbf.pos < end) {

modules/mvt/src/helpers/mapbox-util-functions.ts

@@ -1,6 +1,10 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
 import Protobuf from 'pbf';
 import {MVTMapboxGeometry} from '../lib/types';
-import VectorTileFeature from '../lib/mapbox-vector-tile/vector-tile-feature';
+import {VectorTileFeature} from '../lib/mapbox-vector-tile/vector-tile-feature';
 
 /**
  * Classifies an array of rings into polygons with outer rings and holes

modules/mvt/src/index.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-export type {MVTLoaderOptions} from './lib/types';
+export type {MVTLoaderOptions} from './mvt-loader';
 export {MVTLoader, MVTWorkerLoader} from './mvt-loader';
 
 export type {TileJSON} from './lib/parse-tilejson';

modules/mvt/src/lib/binary-vector-tile/vector-tile-feature.ts

@@ -1,3 +1,7 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
 // This code is forked from https://github.com/mapbox/vector-tile-js under BSD 3-clause license.
 
 import Protobuf from 'pbf';
@@ -17,7 +21,7 @@ export const TEST_EXPORTS = {
   classifyRings
 };
 
-export default class VectorTileFeature {
+export class BinaryVectorTileFeature {
   properties: {[x: string]: string | number | boolean | null};
   extent: any;
   type: number;

modules/mvt/src/lib/binary-vector-tile/vector-tile-layer.ts

@@ -1,11 +1,15 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
 /* eslint-disable indent */
 // This code is forked from https://github.com/mapbox/vector-tile-js under BSD 3-clause license.
 
-import VectorTileFeature from './vector-tile-feature';
+import {BinaryVectorTileFeature} from './vector-tile-feature';
 import Protobuf from 'pbf';
 import {GeojsonGeometryInfo} from '@loaders.gl/schema';
 
-export default class VectorTileLayer {
+export class BinaryVectorTileLayer {
   version: number;
   name: string;
   extent: number;
@@ -33,21 +37,21 @@ export default class VectorTileLayer {
   }
 
   /**
-   * return feature `i` from this layer as a `VectorTileFeature`
+   * return feature `i` from this layer as a `BinaryVectorTileFeature`
    *
    * @param index
    * @param geometryInfo
-   * @returns {VectorTileFeature}
+   * @returns {BinaryVectorTileFeature}
    */
-  feature(i: number, geometryInfo: GeojsonGeometryInfo): VectorTileFeature {
+  feature(i: number, geometryInfo: GeojsonGeometryInfo): BinaryVectorTileFeature {
     if (i < 0 || i >= this._features.length) {
       throw new Error('feature index out of bounds');
     }
 
     this._pbf.pos = this._features[i];
 
     const end = this._pbf.readVarint() + this._pbf.pos;
-    return new VectorTileFeature(
+    return new BinaryVectorTileFeature(
       this._pbf,
       end,
       this.extent,
@@ -64,7 +68,7 @@ export default class VectorTileLayer {
  * @param layer
  * @param pbf
  */
-function readLayer(tag: number, layer?: VectorTileLayer, pbf?: Protobuf): void {
+function readLayer(tag: number, layer?: BinaryVectorTileLayer, pbf?: Protobuf): void {
   if (layer && pbf) {
     if (tag === 15) layer.version = pbf.readVarint();
     else if (tag === 1) layer.name = pbf.readString();

modules/mvt/src/lib/binary-vector-tile/vector-tile.ts

@@ -1,10 +1,14 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
 // This code is forked from https://github.com/mapbox/vector-tile-js under BSD 3-clause license.
 
-import VectorTileLayer from './vector-tile-layer';
+import {BinaryVectorTileLayer} from './vector-tile-layer';
 import Protobuf from 'pbf';
 
-export default class VectorTile {
-  layers: {[x: string]: VectorTileLayer};
+export class BinaryVectorTile {
+  layers: {[x: string]: BinaryVectorTileLayer};
   constructor(pbf: Protobuf, end?: number) {
     this.layers = pbf.readFields(readTile, {}, end);
   }
@@ -16,10 +20,14 @@ export default class VectorTile {
  * @param layers
  * @param pbf
  */
-function readTile(tag: number, layers?: {[x: string]: VectorTileLayer}, pbf?: Protobuf): void {
+function readTile(
+  tag: number,
+  layers?: {[x: string]: BinaryVectorTileLayer},
+  pbf?: Protobuf
+): void {
   if (tag === 3) {
     if (pbf) {
-      const layer = new VectorTileLayer(pbf, pbf.readVarint() + pbf.pos);
+      const layer = new BinaryVectorTileLayer(pbf, pbf.readVarint() + pbf.pos);
       if (layer.length && layers) {
         layers[layer.name] = layer;
       }

modules/mvt/src/lib/mapbox-vector-tile/vector-tile-feature.ts

@@ -1,9 +1,13 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
 // This code is forked from https://github.com/mapbox/vector-tile-js under BSD 3-clause license.
 import Protobuf from 'pbf';
 import {MVTMapboxCoordinates, MVTMapboxGeometry} from '../types';
 import {readFeature, classifyRings} from '../../helpers/mapbox-util-functions';
 
-export default class VectorTileFeature {
+export class VectorTileFeature {
   properties: {[x: string]: string | number | boolean | null};
   extent: any;
   type: number;

modules/mvt/src/lib/mapbox-vector-tile/vector-tile-layer.ts

@@ -1,10 +1,14 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
 /* eslint-disable indent */
 // This code is forked from https://github.com/mapbox/vector-tile-js under BSD 3-clause license.
 
 import Protobuf from 'pbf';
-import VectorTileFeature from './vector-tile-feature';
+import {VectorTileFeature} from './vector-tile-feature';
 
-export default class VectorTileLayer {
+export class VectorTileLayer {
   version: number;
   name: string;
   extent: number;

modules/mvt/src/lib/mapbox-vector-tile/vector-tile.ts

@@ -1,9 +1,13 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
 // This code is forked from https://github.com/mapbox/vector-tile-js under BSD 3-clause license.
 
-import VectorTileLayer from './vector-tile-layer';
+import {VectorTileLayer} from './vector-tile-layer';
 import Protobuf from 'pbf';
 
-export default class VectorTile {
+export class VectorTile {
   layers: {[x: string]: VectorTileLayer};
   constructor(pbf: Protobuf, end?: number) {
     this.layers = pbf.readFields(readTile, {}, end);

modules/mvt/src/lib/parse-mvt.ts

@@ -1,3 +1,7 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
 import {flatGeojsonToBinary} from '@loaders.gl/gis';
 import type {
   FlatFeature,
@@ -8,12 +12,13 @@ import type {
 } from '@loaders.gl/schema';
 import Protobuf from 'pbf';
 
-import type {MVTMapboxCoordinates, MVTOptions, MVTLoaderOptions} from '../lib/types';
+import type {MVTMapboxCoordinates, MVTOptions} from '../lib/types';
+import type {MVTLoaderOptions} from '../mvt-loader';
 
-import VectorTile from './mapbox-vector-tile/vector-tile';
-import BinaryVectorTile from './binary-vector-tile/vector-tile';
-import VectorTileFeatureBinary from './binary-vector-tile/vector-tile-feature';
-import VectorTileFeatureMapBox from './mapbox-vector-tile/vector-tile-feature';
+import {VectorTile} from './mapbox-vector-tile/vector-tile';
+import {BinaryVectorTile} from './binary-vector-tile/vector-tile';
+import {BinaryVectorTileFeature} from './binary-vector-tile/vector-tile-feature';
+import {VectorTileFeature as VectorTileFeatureMapBox} from './mapbox-vector-tile/vector-tile-feature';
 
 /**
  * Parse MVT arrayBuffer and return GeoJSON.
@@ -22,7 +27,7 @@ import VectorTileFeatureMapBox from './mapbox-vector-tile/vector-tile-feature';
  * @param options
  * @returns A GeoJSON geometry object or a binary representation
  */
-export default function parseMVT(arrayBuffer: ArrayBuffer, options?: MVTLoaderOptions) {
+export function parseMVT(arrayBuffer: ArrayBuffer, options?: MVTLoaderOptions) {
   const mvtOptions = normalizeOptions(options);
 
   const shape: string | undefined =
@@ -179,12 +184,12 @@ function getDecodedFeature(
  * @returns decoded binary feature
  */
 function getDecodedFeatureBinary(
-  feature: VectorTileFeatureBinary,
+  feature: BinaryVectorTileFeature,
   options: MVTOptions,
   layerName: string
 ): FlatFeature {
   const decodedFeature = feature.toBinaryCoordinates(
-    // @ts-expect-error What is going on here?
+    // @ts-expect-error
     options.coordinates === 'wgs84' ? options.tileIndex : transformToLocalCoordinatesBinary
   );
 

modules/mvt/src/lib/types.ts

@@ -1,4 +1,6 @@
-import type {LoaderOptions} from '@loaders.gl/loader-utils';
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
 
 /** For local coordinates, the tileIndex is not required */
 type MVTLocalCoordinatesOptions = {
@@ -55,13 +57,3 @@ export type MVTMapboxCoordinates = {
   properties: {[x: string]: string | number | boolean | null};
   id?: number;
 };
-
-export type MVTLoaderOptions = LoaderOptions & {
-  mvt?: MVTOptions;
-  gis?: {
-    /** `true`: parser will output the data in binary format. Equivalent to loading the data as GeoJSON and then applying geojsonToBinary */
-    binary?: boolean;
-    /** @deprecated. Use options.mvt.shape */
-    format?: 'geojson-table' | 'columnar-table' | 'geojson' | 'binary' | 'binary-geometry';
-  };
-};