Add refreshTiles() to map public API (#5806)

* add refreshTile API

* add refreshTiles() to refresh many tiles at once.

* add source cache unit tests

* add map unit test and docs.

* update Changelog

* remove unneeded refreshTile()

* Split test

* it tileIds is not specified, perform global reload on the source.

* add top-level describe to test file

* reduce indentation, add break if matching tile is found

* replace for loop with Array::some()

Author: NathanMOlson

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ### ✨ Features and improvements
 - Add additional hillshade methods ([#5768](https://github.com/maplibre/maplibre-gl-js/pull/5768))
+- Add `refreshTiles()` to the map public API ([#5806](https://github.com/maplibre/maplibre-gl-js/pull/5806))
 - _...Add new stuff here..._
 
 ### 🐞 Bug fixes

src/source/source_cache.test.ts

@@ -3,7 +3,7 @@ import {SourceCache} from './source_cache';
 import {type Map} from '../ui/map';
 import {type Source, addSourceType} from './source';
 import {Tile} from './tile';
-import {OverscaledTileID} from './tile_id';
+import {CanonicalTileID, OverscaledTileID} from './tile_id';
 import {LngLat} from '../geo/lng_lat';
 import Point from '@mapbox/point-geometry';
 import {Event, ErrorEvent, Evented} from '../util/evented';
@@ -2142,4 +2142,92 @@ describe('SourceCache#usedForTerrain', () => {
             ['3s44', '3r44', '3c44', '3b44']
         );
     });
+
+});
+    
+describe('SourceCache::refreshTiles', () => {
+    test('calls reloadTile when tile exists', async () => {
+        const coord = new OverscaledTileID(1, 0, 1, 0, 1);
+        const sourceCache = createSourceCache();
+
+        const spy = vi.fn();
+        sourceCache._reloadTile = spy;
+        sourceCache._source.loadTile = async (tile) => {
+            tile.state = 'loaded';
+        };
+
+        sourceCache._addTile(coord);
+        sourceCache.refreshTiles([new CanonicalTileID(1, 0, 1)]);
+        expect(spy).toHaveBeenCalledOnce();
+        expect(spy.mock.calls[0][1]).toBe('expired');
+    });
+    
+    test('does not call reloadTile when tile does not exist', async () => {
+        const coord = new OverscaledTileID(1, 0, 1, 1, 1);
+        const sourceCache = createSourceCache();
+
+        const spy = vi.fn();
+        sourceCache._reloadTile = spy;
+        sourceCache._source.loadTile = async (tile) => {
+            tile.state = 'loaded';
+        };
+
+        sourceCache._addTile(coord);
+        sourceCache.refreshTiles([new CanonicalTileID(1, 0, 1)]);
+        expect(spy).toHaveBeenCalledTimes(0);
+    });
+
+    test('calls reloadTile when wrapped tile exists', async () => {
+        const coord = new OverscaledTileID(1, 1, 1, 0, 1);
+        const sourceCache = createSourceCache();
+
+        const spy = vi.fn();
+        sourceCache._reloadTile = spy;
+        sourceCache._source.loadTile = async (tile) => {
+            tile.state = 'loaded';
+        };
+
+        sourceCache._addTile(coord);
+        sourceCache.refreshTiles([new CanonicalTileID(1, 0, 1)]);
+        expect(spy).toHaveBeenCalledOnce();
+        expect(spy.mock.calls[0][1]).toBe('expired');
+    });
+
+    test('calls reloadTile when overscaled tile exists', async () => {
+        const coord = new OverscaledTileID(2, 0, 1, 0, 1);
+        const sourceCache = createSourceCache();
+
+        const spy = vi.fn();
+        sourceCache._reloadTile = spy;
+        sourceCache._source.loadTile = async (tile) => {
+            tile.state = 'loaded';
+        };
+
+        sourceCache._addTile(coord);
+        sourceCache.refreshTiles([new CanonicalTileID(1, 0, 1)]);
+        expect(spy).toHaveBeenCalledOnce();
+        expect(spy.mock.calls[0][1]).toBe('expired');
+    });
+
+    test('calls reloadTile for standard, wrapped, and overscaled tiles', async () => {
+        const sourceCache = createSourceCache();
+
+        const spy = vi.fn();
+        sourceCache._reloadTile = spy;
+        sourceCache._source.loadTile = async (tile) => {
+            tile.state = 'loaded';
+        };
+
+        sourceCache._addTile(new OverscaledTileID(1, 0, 1, 0, 1));
+        sourceCache._addTile(new OverscaledTileID(1, 1, 1, 0, 1));
+        sourceCache._addTile(new OverscaledTileID(2, 0, 1, 0, 1));
+        sourceCache._addTile(new OverscaledTileID(2, 1, 1, 0, 1));
+        sourceCache.refreshTiles([new CanonicalTileID(1, 0, 1)]);
+        expect(spy).toHaveBeenCalledTimes(4);
+        expect(spy.mock.calls[0][1]).toBe('expired');
+        expect(spy.mock.calls[1][1]).toBe('expired');
+        expect(spy.mock.calls[2][1]).toBe('expired');
+        expect(spy.mock.calls[3][1]).toBe('expired');
+    });
+
 });

src/source/source_cache.ts

@@ -19,7 +19,7 @@ import type {Style} from '../style/style';
 import type {Dispatcher} from '../util/dispatcher';
 import type {IReadonlyTransform, ITransform} from '../geo/transform_interface';
 import type {TileState} from './tile';
-import type {SourceSpecification} from '@maplibre/maplibre-gl-style-spec';
+import type {ICanonicalTileID, SourceSpecification} from '@maplibre/maplibre-gl-style-spec';
 import type {MapSourceDataEvent} from '../ui/events';
 import type {Terrain} from '../render/terrain';
 import type {CanvasSourceSpecification} from './canvas_source';
@@ -894,6 +894,20 @@ export class SourceCache extends Evented {
         }
     }
 
+    /**
+     * Reload any currently renderable tiles that are match one of the incoming `tileId` x/y/z
+     */
+    refreshTiles(tileIds: Array<ICanonicalTileID>) {
+        for (const id in this._tiles) {
+            if (!this._isIdRenderable(id)) {
+                continue;
+            }
+            if (tileIds.some(tid => tid.equals(this._tiles[id].tileID.canonical))) {
+                this._reloadTile(id, 'expired');
+            }
+        }
+    }
+
     /**
      * Remove a tile, given its id, from the pyramid
      */

src/ui/map.ts

@@ -67,6 +67,7 @@ import {MercatorCameraHelper} from '../geo/projection/mercator_camera_helper';
 import {isAbortError} from '../util/abort_error';
 import {isFramebufferNotCompleteError} from '../util/framebuffer_error';
 import {createCalculateTileZoomFunction} from '../geo/projection/covering_tiles';
+import {CanonicalTileID} from '../source/tile_id';
 
 const version = packageJSON.version;
 
@@ -2213,6 +2214,28 @@ export class Map extends Camera {
         return this;
     }
 
+    /**
+     * Triggers a reload of the selected tiles
+     *
+     * @param sourceId - The ID of the source
+     * @param tileIds - An array of tile IDs to be reloaded. If not defined, all tiles will be reloaded.
+     * @example
+     * ```ts
+     * map.refreshTiles('satellite', [{x:1024, y: 1023, z: 11}, {x:1023, y: 1023, z: 11}]);
+     * ```
+     */
+    refreshTiles(sourceId: string, tileIds?: Array<{x: number; y: number; z: number}>) {
+        const sourceCache = this.style.sourceCaches[sourceId];
+        if(!sourceCache) {
+            throw new Error(`There is no source cache with ID "${sourceId}", cannot refresh tile`);
+        }
+        if (tileIds === undefined) {
+            sourceCache.reload();
+        } else {
+            sourceCache.refreshTiles(tileIds.map((tileId) => {return new CanonicalTileID(tileId.z, tileId.x, tileId.y);}));
+        }
+    }
+
     /**
      * Add an image to the style. This image can be displayed on the map like any other icon in the style's
      * sprite using the image's ID with

src/ui/map_tests/map_refresh_tiles.test.ts

@@ -0,0 +1,48 @@
+import {beforeEach, test, expect, vi, describe} from 'vitest';
+import {createMap, beforeMapTest} from '../../util/test/util';
+import {CanonicalTileID} from '../../source/tile_id';
+
+beforeEach(() => {
+    beforeMapTest();
+    global.fetch = null;
+});
+
+describe('Map::refreshTiles', () => {
+    test('refreshTiles, non-existent source', async () => {
+        const map = createMap({interactive: false});
+        await map.once('style.load');
+
+        map.addSource('source-id1', {type: 'raster', url: ''});
+        const spy = vi.fn();
+        map.style.sourceCaches['source-id1'].refreshTiles = spy;
+
+        expect(() => {map.refreshTiles('source-id2', [{x: 1024, y: 1023, z: 11}]);})
+            .toThrow('There is no source cache with ID "source-id2", cannot refresh tile');
+        expect(spy).toHaveBeenCalledTimes(0);
+    });
+
+    test('refreshTiles, existing source', async () => {
+        const map = createMap({interactive: false});
+        await map.once('style.load');
+
+        map.addSource('source-id1', {type: 'raster', url: ''});
+        const spy = vi.fn();
+        map.style.sourceCaches['source-id1'].refreshTiles = spy;
+
+        map.refreshTiles('source-id1', [{x: 1024, y: 1023, z: 11}]);
+        expect(spy).toHaveBeenCalledOnce();
+        expect(spy.mock.calls[0][0]).toEqual([new CanonicalTileID(11, 1024, 1023)]);
+    });
+
+    test('refreshTiles, existing source, undefined tileIds', async () => {
+        const map = createMap({interactive: false});
+        await map.once('style.load');
+
+        map.addSource('source-id1', {type: 'raster', url: ''});
+        const spy = vi.fn();
+        map.style.sourceCaches['source-id1'].reload = spy;
+
+        map.refreshTiles('source-id1');
+        expect(spy).toHaveBeenCalledOnce();
+    });
+});