feat: add getClusterOptions getter to GeoJSONSource (#7948)

* feat: add getClusterOptions getter to GeoJSONSource

* test: reuse a single options object for setClusterOptions and its expectation

---------

Co-authored-by: Frank Elsinga <frank@elsinga.de>
Co-authored-by: Harel M <harel.mazor@gmail.com>

Author: 3 people

CHANGELOG.md

@@ -1,12 +1,13 @@
 ## main
 ### ✨ Features and improvements
+- Add `GeoJSONSource.getClusterOptions` to get a source's current cluster options (`cluster`, `clusterMaxZoom`, `clusterRadius`) ([#7948](https://github.com/maplibre/maplibre-gl-js/pull/7948)) (by [@lazerg](https://github.com/lazerg))
 - Support `global-state` expressions in `light.*` properties ([#7966](https://github.com/maplibre/maplibre-gl-js/pull/7966)) (by [@CommanderStorm](https://github.com/CommanderStorm))
 - Add `MapOptions.rotateSpeed` and `MapOptions.pitchSpeed`, the degrees the bearing/pitch change per pixel dragged ([#7949](https://github.com/maplibre/maplibre-gl-js/pull/7949)) (by [@clement-igonet](https://github.com/clement-igonet))
 - _...Add new stuff here..._
 
 ### 🐞 Bug fixes
 - Fix an error thrown when a paint property transitions between arrays of different length ([#6606](https://github.com/maplibre/maplibre-gl-js/issues/6606)) (by [@HarelM](https://github.com/HarelM))
-- Fix renderer crash when `RasterTileSource#setTiles`/`setUrl` is called while the source contains errored tiles ([#7911](https://github.com/maplibre/maplibre-gl-js/pull/7911)) (by [@lazerg](https://github.com/lazerg))
+- Fix renderer crash when `RasterTileSource.setTiles`/`setUrl` is called while the source contains errored tiles ([#7911](https://github.com/maplibre/maplibre-gl-js/pull/7911)) (by [@lazerg](https://github.com/lazerg))
 - Fix globe latitude precision on some GPUs (e.g. Mali) by reformulating the mercator-to-sphere Y coordinate algebraically (`exp` + rational arithmetic instead of `atan`/`sin`/`cos`), avoiding float32 cancellation and imprecise hardware transcendentals near the equator; the runtime GPU `atan`-error measurement/correction this superseded has also been removed ([#7419](https://github.com/maplibre/maplibre-gl-js/issues/7419)) (by [@clement-igonet](https://github.com/clement-igonet))
 - _...Add new stuff here..._
 

src/index.ts

@@ -22,7 +22,7 @@ import {now, setNow, restoreNow, isTimeFrozen} from './util/time_control.ts';
 import {WorkerPool} from './util/worker_pool.ts';
 import {prewarm, clearPrewarmedResources} from './util/global_worker_pool.ts';
 import {AJAXError, type ExpiryData, type GetResourceResponse, type RequestParameters} from './util/ajax.ts';
-import {GeoJSONSource, type SetClusterOptions} from './source/geojson_source.ts';
+import {GeoJSONSource, type GetClusterOptions, type SetClusterOptions} from './source/geojson_source.ts';
 import {CanvasSource, type CanvasSourceSpecification} from './source/canvas_source.ts';
 import {type CanonicalTileRange, type Coordinates, ImageSource, type UpdateImageOptions} from './source/image_source.ts';
 import {RasterDEMTileSource} from './source/raster_dem_tile_source.ts';
@@ -301,6 +301,7 @@ export {
     type UpdateImageOptions,
     type DragPanOptions,
     type FullscreenControlOptions,
+    type GetClusterOptions,
     type SetClusterOptions,
     type GeoJSONSourceDiff,
     type GeolocateControlOptions,

src/source/geojson_source.test.ts

@@ -1312,3 +1312,30 @@ describe('GeoJSONSource.getClusterLeaves', () => {
         vi.resetAllMocks();
     });
 });
+
+describe('GeoJSONSource.getClusterOptions', () => {
+    test('returns the cluster options configured on the source', () => {
+        const source = new GeoJSONSource('id', {
+            type: 'geojson',
+            data: {} as GeoJSON.GeoJSON,
+            cluster: true,
+            clusterMaxZoom: 12,
+            clusterRadius: 80
+        }, mockDispatcher, undefined);
+
+        expect(source.getClusterOptions()).toEqual({cluster: true, clusterMaxZoom: 12, clusterRadius: 80});
+    });
+
+    test('reflects options updated via setClusterOptions', async () => {
+        const source = new GeoJSONSource('id', {
+            type: 'geojson',
+            data: {} as GeoJSON.GeoJSON,
+            cluster: false
+        }, mockDispatcher, undefined);
+
+        const options = {cluster: true, clusterMaxZoom: 9, clusterRadius: 40};
+        await source.setClusterOptions(options);
+
+        expect(source.getClusterOptions()).toEqual(options);
+    });
+});

src/source/geojson_source.ts

@@ -69,6 +69,24 @@ export type SetClusterOptions = {
     clusterRadius?: number;
 };
 
+/**
+ * The cluster options currently configured on a source, as returned by `getClusterOptions`
+ */
+export type GetClusterOptions = {
+    /**
+     * Whether or not the source is clustered
+     */
+    cluster: boolean;
+    /**
+     * The cluster's max zoom
+     */
+    clusterMaxZoom: number;
+    /**
+     * The cluster's radius, in pixels
+     */
+    clusterRadius: number;
+};
+
 /**
  * A source containing GeoJSON.
  * (See the [Style Specification](https://maplibre.org/maplibre-style-spec/#sources-geojson) for detailed documentation of options.)
@@ -226,6 +244,10 @@ export class GeoJSONSource extends Evented<SourceEventType> implements Source {
         return pixelValue * (EXTENT / this.tileSize);
     }
 
+    private _tileUnitsToPixels(tileUnitValue: number): number {
+        return tileUnitValue / (EXTENT / this.tileSize);
+    }
+
     private _getClusterMaxZoom(clusterMaxZoom: number): number {
         const effectiveClusterMaxZoom = clusterMaxZoom ? Math.round(clusterMaxZoom) : this.maxzoom - 1;
         if (!(Number.isInteger(clusterMaxZoom) || clusterMaxZoom === undefined)) {
@@ -321,6 +343,25 @@ export class GeoJSONSource extends Evented<SourceEventType> implements Source {
         return this._updateWorkerData();
     }
 
+    /**
+     * Gets the cluster options currently configured on the source.
+     * The returned values mirror the options accepted by `setClusterOptions`.
+     *
+     * @returns the source's current cluster options
+     * @example
+     * ```ts
+     * const {cluster, clusterMaxZoom, clusterRadius} = map.getSource('some id').getClusterOptions();
+     * ```
+     */
+    getClusterOptions(): GetClusterOptions {
+        const {cluster, clusterOptions} = this.workerOptions.geojsonVtOptions;
+        return {
+            cluster,
+            clusterMaxZoom: clusterOptions.maxZoom,
+            clusterRadius: this._tileUnitsToPixels(clusterOptions.radius)
+        };
+    }
+
     /**
      * For clustered sources, fetches the zoom at which the given cluster expands.
      *