@loaders.gl/wms 3.4.0-alpha.2 → 3.4.0-alpha.4

package/src/lib/services/ogc/wms-service.ts

@@ -1,7 +1,6 @@
 // loaders.gl, MIT license
 
 /* eslint-disable camelcase */
-
 import type {ImageType} from '@loaders.gl/images';
 import {ImageLoader} from '@loaders.gl/images';
 import {mergeLoaderOptions} from '@loaders.gl/loader-utils';
@@ -21,53 +20,87 @@ import {WMSLayerDescriptionLoader} from '../../../wip/wms-layer-description-load
 import type {WMSLoaderOptions} from '../../../wms-error-loader';
 import {WMSErrorLoader} from '../../../wms-error-loader';
 
-type WMSCommonParameters = {
-  /** In case the endpoint supports multiple services */
-  service?: 'WMS';
-  /** In case the endpoint supports multiple WMS versions */
-  version?: '1.1.1' | '1.3.0';
+/**
+ * "Static" WMS parameters (not viewport or selected pixel dependent)
+ * These can be provided as defaults in the WMSService constructor
+ */
+export type WMSParameters = {
+  /** WMS version (all requests) */
+  version?: '1.3.0' | '1.1.1';
+  /** Layers to render (GetMap, GetFeatureInfo) */
+  layers?: string[];
+  /** list of layers to query.. (GetFeatureInfo) */
+  query_layers?: string[];
+
+  /** Coordinate Reference System (CRS) for the image (not the bounding box) */
+  crs?: string;
+  /** Requested format for the return image (GetMap, GetLegendGraphic) */
+  format?: 'image/png';
+  /** Requested MIME type of returned feature info (GetFeatureInfo) */
+  info_format?: 'text/plain' | 'application/geojson' | 'application/vnd.ogc.gml';
+  /** Styling - Not yet supported */
+  styles?: unknown;
+  /** Any additional parameters specific to this WMSService (GetMap) */
+  transparent?: boolean;
 };
 
-export type WMSGetCapabilitiesParameters = WMSCommonParameters & {
-  /** Request type */
-  request?: 'GetCapabilities';
+/** Parameters for GetCapabilities */
+export type WMSGetCapabilitiesParameters = {
+  /** In case the endpoint supports multiple WMS versions */
+  version?: '1.3.0' | '1.1.1';
 };
 
-export type WMSGetMapParameters = WMSCommonParameters & {
-  /** Request type */
-  request?: 'GetMap';
-  /** Layers to render */
-  layers: string | string[];
-  /** Styling */
-  styles?: unknown;
+/** Parameters for GetMap */
+export type WMSGetMapParameters = {
+  /** In case the endpoint supports multiple WMS versions */
+  version?: '1.3.0' | '1.1.1';
   /** bounding box of the requested map image */
   bbox: [number, number, number, number];
   /** pixel width of returned image */
   width: number;
   /** pixels */
   height: number;
-  /** srs for the image (not the bounding box) */
-  srs?: string;
-  /** requested format for the return image */
+  /** Layers to render - can be provided in service constructor */
+  layers?: string | string[];
+  /** Coordinate Reference System for the image (not bounding box). can be provided in service constructor. */
+  crs?: string;
+  /** Styling. can be provided in service constructor */
+  styles?: unknown;
+  /** Don't render background when no data. can be provided in service constructor */
+  transparent?: boolean;
+  /** requested format for the return image. can be provided in service constructor */
   format?: 'image/png';
 };
 
-// https://imagery.pasda.psu.edu/arcgis/services/pasda/UrbanTreeCanopy_Landcover/MapServer/WmsServer?SERVICE=WMS&
-export type WMSGetFeatureInfoParameters = WMSCommonParameters & {
-  /** Request type */
-  request?: 'GetFeatureInfo';
+/** GetMap parameters that are specific to the current view */
+export type WMSGetMapViewParameters = {
+  /** pixel width of returned image */
+  width: number;
+  /** pixels */
+  height: number;
+  /** bounding box of the requested map image */
+  bbox: [number, number, number, number];
+  /** Coordinate Reference System for the image (not bounding box). can be provided in service constructor. */
+  crs?: string;
+};
 
+/**
+ * Parameters for GetFeatureInfo
+ * @see https://imagery.pasda.psu.edu/arcgis/services/pasda/UrbanTreeCanopy_Landcover/MapServer/WmsServer?SERVICE=WMS&
+ */
+export type WMSGetFeatureInfoParameters = {
+  /** In case the endpoint supports multiple WMS versions */
+  version?: '1.3.0' | '1.1.1';
   /** x coordinate for the feature info request */
   x: number;
   /** y coordinate for the feature info request */
   y: number;
-  /** list of layers to query (could be different from rendered layers) */
-  query_layers: string[];
-  /** Requested MIME type of returned feature info */
-  info_format?: 'text/plain' | 'application/vnd.ogc.gml';
-
-  /** Layers to render */
-  layers: string[];
+  /** MIME type of returned feature info. Can be specified in service constructor */
+  info_format?: 'text/plain' | 'application/geojson' | 'application/vnd.ogc.gml';
+  /** list of layers to query. Required but can be specified in service constructor. */
+  query_layers?: string[];
+  /** Layers to render. Required, but can be specified in service constructor */
+  layers?: string[];
   /** Styling */
   styles?: unknown;
   /** bounding box of the requested map image */
@@ -77,37 +110,50 @@ export type WMSGetFeatureInfoParameters = WMSCommonParameters & {
   /** pixels */
   height: number;
   /** srs for the image (not the bounding box) */
-  srs?: string;
-  /** requested format for the return image */
-  format?: 'image/png';
+  crs?: string;
 };
 
-export type WMSDescribeLayerParameters = WMSCommonParameters & {
-  /** Request type */
-  request?: 'DescribeLayer';
+/** GetMap parameters that are specific to the current view */
+export type WMSGetFeatureInfoViewParameters = {
+  /** x coordinate for the feature info request */
+  x: number;
+  /** y coordinate for the feature info request */
+  y: number;
+  /** pixel width of returned image */
+  width: number;
+  /** pixels */
+  height: number;
+  /** bounding box of the requested map image */
+  bbox: [number, number, number, number];
+  /** srs for the image (not the bounding box) */
+  crs?: string;
 };
 
-export type WMSGetLegendGraphicParameters = WMSCommonParameters & {
-  /** Request type */
-  request?: 'GetLegendGraphic';
+/** Parameters for DescribeLayer */
+export type WMSDescribeLayerParameters = {
+  /** In case the endpoint supports multiple WMS versions */
+  version?: '1.3.0' | '1.1.1';
 };
 
-/** Properties for initializing a WMS service */
+/** Parameters for GetLegendGraphic */
+export type WMSGetLegendGraphicParameters = {
+  /** In case the endpoint supports multiple WMS versions */
+  version?: '1.3.0' | '1.1.1';
+};
+
+//
+
+/** Properties for creating a enw WMS service */
 export type WMSServiceProps = ImageSourceProps & {
   /** Base URL to the service */
   url: string;
-  /** WMS version */
-  version?: '1.1.1' | '1.3.0';
-  /** Layers to render */
-  layers?: string[];
-  /** SRS for the image (not the bounding box) */
-  srs?: string;
-  /** Requested format for the return image */
-  format?: 'image/png';
-  /** Requested MIME type of returned feature info */
-  info_format?: 'text/plain' | 'application/vnd.ogc.gml';
-  /** Styling */
-  styles?: unknown;
+  /** In 1.3.0, replaces references to EPSG:4326 with CRS:84 */
+  substituteCRS84?: boolean;
+
+  /** Default WMS parameters. If not provided here, must be provided in the various request */
+  wmsParameters?: WMSParameters;
+  /** Any additional service specific parameters */
+  vendorParameters?: Record<string, unknown>;
 };
 
 /**
@@ -117,11 +163,23 @@ export type WMSServiceProps = ImageSourceProps & {
  * - implements the ImageService interface
  * @note Only the URL parameter conversion is supported. XML posts are not supported.
  */
-export class WMSService extends ImageSource {
+export class WMSService extends ImageSource<WMSServiceProps> {
   static type: 'wms' = 'wms';
   static testURL = (url: string): boolean => url.toLowerCase().includes('wms');
 
-  props: Required<WMSServiceProps>;
+  /** Base URL to the service */
+  readonly url: string;
+
+  /** In WMS 1.3.0, replaces references to EPSG:4326 with CRS:84. But not always supported. Default: false */
+  substituteCRS84: boolean;
+  /** In WMS 1.3.0, flips x,y (lng, lat) coordinates for the supplied coordinate systems. Default: ['ESPG:4326'] */
+  flipCRS: string[];
+
+  /** Default static WMS parameters */
+  wmsParameters: Required<WMSParameters>;
+  /** Default static vendor parameters */
+  vendorParameters?: Record<string, unknown>;
+
   capabilities: WMSCapabilities | null = null;
 
   /** A list of loaders used by the WMSService methods */
@@ -139,17 +197,26 @@ export class WMSService extends ImageSource {
 
     // TODO - defaults such as version, layers etc could be extracted from a base URL with parameters
     // This would make pasting in any WMS URL more likely to make this class just work.
+    // const {baseUrl, parameters} = this._parseWMSUrl(props.url);
+
+    this.url = props.url;
+
+    this.substituteCRS84 = props.substituteCRS84 ?? false;
+    this.flipCRS = ['EPSG:4326'];
 
-    this.props = {
-      loadOptions: undefined!,
+    this.wmsParameters = {
       layers: undefined!,
+      query_layers: undefined!,
       styles: undefined,
-      version: '1.1.1',
-      srs: 'EPSG:4326',
+      version: '1.3.0',
+      crs: 'EPSG:4326',
       format: 'image/png',
       info_format: 'text/plain',
-      ...props
+      transparent: undefined!,
+      ...props.wmsParameters
     };
+
+    this.vendorParameters = props.vendorParameters || {};
   }
 
   // ImageSource implementation
@@ -177,22 +244,22 @@ export class WMSService extends ImageSource {
     const response = await this.fetch(url);
     const arrayBuffer = await response.arrayBuffer();
     this._checkResponse(response, arrayBuffer);
-    const capabilities = await WMSCapabilitiesLoader.parse(arrayBuffer, this.props.loadOptions);
+    const capabilities = await WMSCapabilitiesLoader.parse(arrayBuffer, this.loadOptions);
     this.capabilities = capabilities;
     return capabilities;
   }
 
   /** Get a map image */
   async getMap(
-    options: WMSGetMapParameters,
+    wmsParameters: WMSGetMapParameters,
     vendorParameters?: Record<string, unknown>
   ): Promise<ImageType> {
-    const url = this.getMapURL(options, vendorParameters);
+    const url = this.getMapURL(wmsParameters, vendorParameters);
     const response = await this.fetch(url);
     const arrayBuffer = await response.arrayBuffer();
     this._checkResponse(response, arrayBuffer);
     try {
-      return await ImageLoader.parse(arrayBuffer, this.props.loadOptions);
+      return await ImageLoader.parse(arrayBuffer, this.loadOptions);
     } catch {
       throw this._parseError(arrayBuffer);
     }
@@ -200,22 +267,22 @@ export class WMSService extends ImageSource {
 
   /** Get Feature Info for a coordinate */
   async getFeatureInfo(
-    options: WMSGetFeatureInfoParameters,
+    wmsParameters: WMSGetFeatureInfoParameters,
     vendorParameters?: Record<string, unknown>
   ): Promise<WMSFeatureInfo> {
-    const url = this.getFeatureInfoURL(options, vendorParameters);
+    const url = this.getFeatureInfoURL(wmsParameters, vendorParameters);
     const response = await this.fetch(url);
     const arrayBuffer = await response.arrayBuffer();
     this._checkResponse(response, arrayBuffer);
-    return await WMSFeatureInfoLoader.parse(arrayBuffer, this.props.loadOptions);
+    return await WMSFeatureInfoLoader.parse(arrayBuffer, this.loadOptions);
   }
 
   /** Get Feature Info for a coordinate */
   async getFeatureInfoText(
-    options: WMSGetFeatureInfoParameters,
+    wmsParameters: WMSGetFeatureInfoParameters,
     vendorParameters?: Record<string, unknown>
   ): Promise<string> {
-    const url = this.getFeatureInfoURL(options, vendorParameters);
+    const url = this.getFeatureInfoURL(wmsParameters, vendorParameters);
     const response = await this.fetch(url);
     const arrayBuffer = await response.arrayBuffer();
     this._checkResponse(response, arrayBuffer);
@@ -224,27 +291,27 @@ export class WMSService extends ImageSource {
 
   /** Get more information about a layer */
   async describeLayer(
-    options: WMSDescribeLayerParameters,
+    wmsParameters: WMSDescribeLayerParameters,
     vendorParameters?: Record<string, unknown>
   ): Promise<WMSLayerDescription> {
-    const url = this.describeLayerURL(options, vendorParameters);
+    const url = this.describeLayerURL(wmsParameters, vendorParameters);
     const response = await this.fetch(url);
     const arrayBuffer = await response.arrayBuffer();
     this._checkResponse(response, arrayBuffer);
-    return await WMSLayerDescriptionLoader.parse(arrayBuffer, this.props.loadOptions);
+    return await WMSLayerDescriptionLoader.parse(arrayBuffer, this.loadOptions);
   }
 
   /** Get an image with a semantic legend */
   async getLegendGraphic(
-    options: WMSGetLegendGraphicParameters,
+    wmsParameters: WMSGetLegendGraphicParameters,
     vendorParameters?: Record<string, unknown>
   ): Promise<ImageType> {
-    const url = this.getLegendGraphicURL(options, vendorParameters);
+    const url = this.getLegendGraphicURL(wmsParameters, vendorParameters);
     const response = await this.fetch(url);
     const arrayBuffer = await response.arrayBuffer();
     this._checkResponse(response, arrayBuffer);
     try {
-      return await ImageLoader.parse(arrayBuffer, this.props.loadOptions);
+      return await ImageLoader.parse(arrayBuffer, this.loadOptions);
     } catch {
       throw this._parseError(arrayBuffer);
     }
@@ -259,13 +326,10 @@ export class WMSService extends ImageSource {
     vendorParameters?: Record<string, unknown>
   ): string {
     const options: Required<WMSGetCapabilitiesParameters> = {
-      service: 'WMS',
-      version: this.props.version,
-      request: 'GetCapabilities',
-      ...wmsParameters,
-      ...vendorParameters
+      version: this.wmsParameters.version,
+      ...wmsParameters
     };
-    return this._getWMSUrl(options, vendorParameters);
+    return this._getWMSUrl('GetCapabilities', options, vendorParameters);
   }
 
   /** Generate a URL for the GetMap request */
@@ -273,21 +337,20 @@ export class WMSService extends ImageSource {
     wmsParameters: WMSGetMapParameters,
     vendorParameters?: Record<string, unknown>
   ): string {
+    wmsParameters = this._getWMS130Parameters(wmsParameters);
     const options: Required<WMSGetMapParameters> = {
-      service: 'WMS',
-      version: this.props.version,
-      request: 'GetMap',
-      // layers: [],
+      version: this.wmsParameters.version,
+      format: this.wmsParameters.format,
+      transparent: this.wmsParameters.transparent,
+      layers: this.wmsParameters.layers,
+      styles: this.wmsParameters.styles,
+      crs: this.wmsParameters.crs,
       // bbox: [-77.87304, 40.78975, -77.85828, 40.80228],
       // width: 1200,
       // height: 900,
-      styles: this.props.styles,
-      srs: this.props.srs,
-      format: this.props.format,
-      ...wmsParameters,
-      ...vendorParameters
+      ...wmsParameters
     };
-    return this._getWMSUrl(options, vendorParameters);
+    return this._getWMSUrl('GetMap', options, vendorParameters);
   }
 
   /** Generate a URL for the GetFeatureInfo request */
@@ -296,24 +359,22 @@ export class WMSService extends ImageSource {
     vendorParameters?: Record<string, unknown>
   ): string {
     const options: Required<WMSGetFeatureInfoParameters> = {
-      service: 'WMS',
-      version: this.props.version,
-      request: 'GetFeatureInfo',
-      // layers: this.props.layers,
+      version: this.wmsParameters.version,
+      // query_layers: [],
+      // format: this.wmsParameters.format,
+      info_format: this.wmsParameters.info_format,
+      layers: this.wmsParameters.layers,
+      query_layers: this.wmsParameters.query_layers,
+      styles: this.wmsParameters.styles,
+      crs: this.wmsParameters.crs,
       // bbox: [-77.87304, 40.78975, -77.85828, 40.80228],
       // width: 1200,
       // height: 900,
       // x: undefined!,
       // y: undefined!,
-      // query_layers: [],
-      srs: this.props.srs,
-      format: this.props.format,
-      info_format: this.props.info_format,
-      styles: this.props.styles,
-      ...wmsParameters,
-      ...vendorParameters
+      ...wmsParameters
     };
-    return this._getWMSUrl(options, vendorParameters);
+    return this._getWMSUrl('GetFeatureInfo', options, vendorParameters);
   }
 
   /** Generate a URL for the GetFeatureInfo request */
@@ -322,13 +383,10 @@ export class WMSService extends ImageSource {
     vendorParameters?: Record<string, unknown>
   ): string {
     const options: Required<WMSDescribeLayerParameters> = {
-      service: 'WMS',
-      version: this.props.version,
-      request: 'DescribeLayer',
-      ...wmsParameters,
-      ...vendorParameters
+      version: this.wmsParameters.version,
+      ...wmsParameters
     };
-    return this._getWMSUrl(options, vendorParameters);
+    return this._getWMSUrl('DescribeLayer', options, vendorParameters);
   }
 
   getLegendGraphicURL(
@@ -336,45 +394,152 @@ export class WMSService extends ImageSource {
     vendorParameters?: Record<string, unknown>
   ): string {
     const options: Required<WMSGetLegendGraphicParameters> = {
-      service: 'WMS',
-      version: this.props.version,
-      request: 'GetLegendGraphic',
+      version: this.wmsParameters.version,
       // format?
-      ...wmsParameters,
-      ...vendorParameters
+      ...wmsParameters
     };
-    return this._getWMSUrl(options, vendorParameters);
+    return this._getWMSUrl('GetLegendGraphic', options, vendorParameters);
   }
 
   // INTERNAL METHODS
 
+  _parseWMSUrl(url: string): {url: string; parameters: Record<string, unknown>} {
+    const [baseUrl, search] = url.split('?');
+    const searchParams = search.split('&');
+
+    const parameters: Record<string, unknown> = {};
+    for (const parameter of searchParams) {
+      const [key, value] = parameter.split('=');
+      parameters[key] = value;
+    }
+
+    return {url: baseUrl, parameters};
+  }
+
   /**
+   * Generate a URL with parameters
    * @note case _getWMSUrl may need to be overridden to handle certain backends?
+   * @note at the moment, only URLs with parameters are supported (no XML payloads)
    * */
   protected _getWMSUrl(
-    options: Record<string, unknown>,
+    request: string,
+    wmsParameters: {version?: '1.3.0' | '1.1.1'; [key: string]: unknown},
     vendorParameters?: Record<string, unknown>
   ): string {
-    let url = this.props.url;
+    let url = this.url;
     let first = true;
-    for (const [key, value] of Object.entries(options)) {
-      url += first ? '?' : '&';
-      first = false;
-      if (Array.isArray(value)) {
-        url += `${key.toUpperCase()}=${value.join(',')}`;
-      } else {
-        url += `${key.toUpperCase()}=${value ? String(value) : ''}`;
+
+    // Add any vendor searchParams
+    const allParameters = {
+      service: 'WMS',
+      version: wmsParameters.version,
+      request,
+      ...wmsParameters,
+      ...this.vendorParameters,
+      ...vendorParameters
+    };
+
+    // Encode the keys
+    for (const [key, value] of Object.entries(allParameters)) {
+      // hack to preserve test cases. Not super clear if keys should be included when values are undefined
+      if (key !== 'transparent' || value) {
+        url += first ? '?' : '&';
+        first = false;
+        url += this._getURLParameter(key, value, wmsParameters);
       }
     }
+
     return encodeURI(url);
   }
 
+  _getWMS130Parameters<ParametersT extends {crs?: string; srs?: string}>(
+    wmsParameters: ParametersT
+  ): ParametersT {
+    const newParameters = {...wmsParameters};
+    if (newParameters.srs) {
+      newParameters.crs = newParameters.crs || newParameters.srs;
+      delete newParameters.srs;
+    }
+    return newParameters;
+  }
+
+  // eslint-disable-complexity
+  _getURLParameter(key: string, value: unknown, wmsParameters: WMSParameters): string {
+    // Substitute by key
+    switch (key) {
+      case 'crs':
+        // CRS was called SRS before WMS 1.3.0
+        if (wmsParameters.version !== '1.3.0') {
+          key = 'srs';
+        } else if (this.substituteCRS84 && value === 'EPSG:4326') {
+          /** In 1.3.0, replaces references to 'EPSG:4326' with the new backwards compatible CRS:84 */
+          // Substitute by value
+          value = 'CRS:84';
+        }
+        break;
+
+      case 'srs':
+        // CRS was called SRS before WMS 1.3.0
+        if (wmsParameters.version === '1.3.0') {
+          key = 'crs';
+        }
+        break;
+
+      case 'bbox':
+        // Coordinate order is flipped for certain CRS in WMS 1.3.0
+        const bbox = this._flipBoundingBox(value, wmsParameters);
+        if (bbox) {
+          value = bbox;
+        }
+        break;
+
+      default:
+      // do nothing
+    }
+
+    key = key.toUpperCase();
+
+    return Array.isArray(value)
+      ? `${key}=${value.join(',')}`
+      : `${key}=${value ? String(value) : ''}`;
+  }
+
+  /** Coordinate order is flipped for certain CRS in WMS 1.3.0 */
+  _flipBoundingBox(
+    bboxValue: unknown,
+    wmsParameters: WMSParameters
+  ): [number, number, number, number] | null {
+    // Sanity checks
+    if (!Array.isArray(bboxValue) || bboxValue.length !== 4) {
+      return null;
+    }
+
+    const flipCoordinates =
+      // Only affects WMS 1.3.0
+      wmsParameters.version === '1.3.0' &&
+      // Flip if we are dealing with a CRS that was flipped in 1.3.0
+      this.flipCRS.includes(wmsParameters.crs || '') &&
+      // Don't flip if we are subsituting EPSG:4326 with CRS:84
+      !(this.substituteCRS84 && wmsParameters.crs === 'EPSG:4326');
+
+    const bbox = bboxValue as [number, number, number, number];
+    return flipCoordinates ? [bbox[1], bbox[0], bbox[3], bbox[2]] : bbox;
+  }
+
+  /** Fetches an array buffer and checks the response (boilerplate reduction) */
+  protected async _fetchArrayBuffer(url: string): Promise<ArrayBuffer> {
+    const response = await this.fetch(url);
+    const arrayBuffer = await response.arrayBuffer();
+    this._checkResponse(response, arrayBuffer);
+    return arrayBuffer;
+  }
+
   /** Checks for and parses a WMS XML formatted ServiceError and throws an exception */
   protected _checkResponse(response: Response, arrayBuffer: ArrayBuffer): void {
     const contentType = response.headers['content-type'];
     if (!response.ok || WMSErrorLoader.mimeTypes.includes(contentType)) {
       // We want error responses to throw exceptions, the WMSErrorLoader can do this
-      const loadOptions = mergeLoaderOptions<WMSLoaderOptions>(this.props.loadOptions, {
+      const loadOptions = mergeLoaderOptions<WMSLoaderOptions>(this.loadOptions, {
         wms: {throwOnError: true}
       });
       const error = WMSErrorLoader.parseSync(arrayBuffer, loadOptions);
@@ -384,7 +549,7 @@ export class WMSService extends ImageSource {
 
   /** Error situation detected */
   protected _parseError(arrayBuffer: ArrayBuffer): Error {
-    const error = WMSErrorLoader.parseSync(arrayBuffer, this.props.loadOptions);
+    const error = WMSErrorLoader.parseSync(arrayBuffer, this.loadOptions);
     return new Error(error);
   }
 }

package/src/lib/sources/data-source.ts

@@ -8,16 +8,43 @@ export type DataSourceProps = {
 };
 
 /** base class of all data sources */
-export abstract class DataSource {
+export abstract class DataSource<PropsT extends DataSourceProps> {
   /** A resolved fetch function extracted from loadOptions prop */
   fetch: (url: string, options?: RequestInit) => Promise<Response>;
   /** The actual load options, if calling a loaders.gl loader */
   loadOptions: LoaderOptions;
+  _needsRefresh: boolean = true;
 
-  constructor(props: DataSourceProps) {
+  props: PropsT;
+
+  constructor(props: PropsT) {
+    this.props = {...props};
     this.loadOptions = {...props.loadOptions};
     this.fetch = getFetchFunction(this.loadOptions);
   }
+
+  setProps(props: PropsT) {
+    this.props = Object.assign(this.props, props);
+    // TODO - add a shallow compare to avoid setting refresh if no change?
+    this.setNeedsRefresh();
+  }
+
+  /** Mark this data source as needing a refresh (redraw) */
+  setNeedsRefresh(): void {
+    this._needsRefresh = true;
+  }
+
+  /**
+   * Does this data source need refreshing?
+   * @note The specifics of the refresh mechanism depends on type of data source
+   */
+  getNeedsRefresh(clear: boolean = true) {
+    const needsRefresh = this._needsRefresh;
+    if (clear) {
+      this._needsRefresh = false;
+    }
+    return needsRefresh;
+  }
 }
 
 /**