@loaders.gl/tiles 5.0.0-alpha.1 → 5.0.0-alpha.10

package/src/raster-set.ts

@@ -1,66 +1,89 @@
 // loaders.gl
 // SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
 import type {
   GetRasterParameters,
+  NumericRasterData,
   RasterData,
   RasterSource,
   RasterSourceMetadata
 } from '@loaders.gl/loader-utils';
+import {waitForPromiseWithSignals} from '@loaders.gl/loader-utils';
 
 /** Accepted raster request currently retained by {@link RasterSet}. */
-export type RasterSetRequest<DataT = RasterData> = {
+export type RasterSetRequest<
+  DataT extends NumericRasterData = RasterData,
+  ParametersT extends object = GetRasterParameters
+> = {
   /** Unique request id assigned by the manager. */
   requestId: number;
   /** Raster request parameters that produced the accepted raster payload. */
-  parameters: GetRasterParameters;
+  parameters: ParametersT;
   /** Raster retained as the current output. */
   raster: DataT;
 };
 
 /** Arguments supplied to {@link RasterSetBaseProps.shouldRefetch}. */
-export type RasterSetShouldRefetchArgs<DataT = RasterData> = {
+export type RasterSetShouldRefetchArgs<
+  DataT extends NumericRasterData = RasterData,
+  ParametersT extends object = GetRasterParameters,
+  MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+> = {
   /** Current accepted request retained by the raster manager, if any. */
-  currentRequest: RasterSetRequest<DataT> | null;
+  currentRequest: RasterSetRequest<DataT, ParametersT> | null;
   /** Source metadata resolved by {@link RasterSet.loadMetadata}, if available. */
-  metadata: RasterSourceMetadata | null;
+  metadata: MetadataT | null;
   /** Candidate raster request parameters under evaluation. */
-  nextParameters: GetRasterParameters;
+  nextParameters: ParametersT;
 };
 
 /** Configuration shared by all {@link RasterSet} instances. */
-export type RasterSetBaseProps<DataT = RasterData> = {
+export type RasterSetBaseProps<
+  DataT extends NumericRasterData = RasterData,
+  ParametersT extends object = GetRasterParameters,
+  MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+> = {
   /** Callback used to load source metadata. */
-  getMetadata: () => Promise<RasterSourceMetadata>;
+  getMetadata: (options?: {
+    /** Metadata request cancellation. */ signal?: AbortSignal;
+  }) => Promise<MetadataT>;
   /** Callback used to load raster data for a viewport-derived request. */
-  getRaster: (parameters: GetRasterParameters) => Promise<DataT>;
+  getRaster: (parameters: ParametersT) => Promise<DataT>;
   /** Debounce interval applied before issuing raster requests. */
   debounceTime?: number;
   /** Optional policy callback that can skip redundant raster requests. */
-  shouldRefetch?: (args: RasterSetShouldRefetchArgs<DataT>) => boolean;
+  shouldRefetch?: (args: RasterSetShouldRefetchArgs<DataT, ParametersT, MetadataT>) => boolean;
 };
 
 /** Options for creating a {@link RasterSet}. */
-export type RasterSetProps<DataT = RasterData> = Partial<RasterSetBaseProps<DataT>> & {
+export type RasterSetProps<
+  DataT extends NumericRasterData = RasterData,
+  ParametersT extends object = GetRasterParameters,
+  MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+> = Partial<RasterSetBaseProps<DataT, ParametersT, MetadataT>> & {
   /** Optional loaders.gl raster source backing this manager. */
-  rasterSource?: RasterSource | null;
+  rasterSource?: RasterSource<DataT, ParametersT & GetRasterParameters, MetadataT> | null;
 };
 
 /** Subscription callbacks emitted by {@link RasterSet}. */
-export type RasterSetListener<DataT = RasterData> = {
+export type RasterSetListener<
+  DataT extends NumericRasterData = RasterData,
+  ParametersT extends object = GetRasterParameters,
+  MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+> = {
   /** Fired when metadata/raster loading starts or stops. */
   onLoadingStateChange?: (isLoading: boolean) => void;
   /** Fired when source metadata resolves successfully. */
-  onMetadataLoad?: (metadata: RasterSourceMetadata) => void;
+  onMetadataLoad?: (metadata: MetadataT) => void;
   /** Fired when metadata loading fails. */
   onMetadataLoadError?: (error: Error) => void;
   /** Fired when a new raster request is issued. */
-  onRasterLoadStart?: (requestId: number, parameters: GetRasterParameters) => void;
+  onRasterLoadStart?: (requestId: number, parameters: ParametersT) => void;
   /** Fired when a raster request resolves and becomes current. */
-  onRasterLoad?: (request: RasterSetRequest<DataT>) => void;
+  onRasterLoad?: (request: RasterSetRequest<DataT, ParametersT>) => void;
   /** Fired when a raster request fails. */
-  onRasterLoadError?: (requestId: number, error: Error, parameters: GetRasterParameters) => void;
+  onRasterLoadError?: (requestId: number, error: Error, parameters: ParametersT) => void;
   /** Fired when metadata or the current raster changes. */
   onUpdate?: () => void;
 };
@@ -84,23 +107,38 @@ const DEFAULT_RASTERSET_PROPS: Required<Omit<RasterSetProps, 'rasterSource'>> =
   shouldRefetch: () => true
 };
 
-/** Shared raster request manager used by viewport-driven raster examples and layers. */
-export class RasterSet<DataT = RasterData> {
+/**
+ * Shared raster request manager used by viewport-driven raster examples and layers.
+ *
+ * @typeParam DataT Raster payload retained by the manager.
+ * @typeParam ParametersT Request parameters accepted by the source.
+ * @typeParam MetadataT Metadata returned by the source.
+ */
+export class RasterSet<
+  DataT extends NumericRasterData = RasterData,
+  ParametersT extends object = GetRasterParameters,
+  MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+> {
   /** Cached metadata returned by the backing source, if any. */
-  metadata: RasterSourceMetadata | null = null;
+  metadata: MetadataT | null = null;
 
-  private _opts: Required<RasterSetProps<DataT>>;
-  private _listeners = new Set<RasterSetListener<DataT>>();
-  private _currentRequest: RasterSetRequest<DataT> | null = null;
-  private _lastAcceptedRequestId = -1;
+  private _opts: Required<RasterSetProps<DataT, ParametersT, MetadataT>>;
+  private _listeners = new Set<RasterSetListener<DataT, ParametersT, MetadataT>>();
+  private _currentRequest: RasterSetRequest<DataT, ParametersT> | null = null;
   private _nextRequestId = 0;
   private _loadCounter = 0;
   private _timeoutId: ReturnType<typeof setTimeout> | null = null;
   private _abortController: AbortController | null = null;
+  /** Controller owned by the newest metadata request. */
+  private _metadataAbortController: AbortController | null = null;
   private _finalized = false;
+  /** Generation invalidates metadata from replaced sources. */
+  private _sourceGeneration = 0;
+  /** Monotonic metadata request identity. */
+  private _metadataRequestId = 0;
 
   /** Creates a raster manager from a source or direct callbacks. */
-  constructor(opts: RasterSetProps<DataT>) {
+  constructor(opts: RasterSetProps<DataT, ParametersT, MetadataT>) {
     this._opts = this._normalizeOptions(opts);
     if (!this._opts.rasterSource && (!opts.getRaster || !opts.getMetadata)) {
       throw new Error(
@@ -110,11 +148,29 @@ export class RasterSet<DataT = RasterData> {
   }
 
   /** Convenience factory for wrapping a loaders.gl {@link RasterSource}. */
-  static fromRasterSource<DataT = RasterData>(
-    rasterSource: RasterSource,
-    opts: Omit<RasterSetProps<DataT>, 'rasterSource' | 'getRaster' | 'getMetadata'> = {}
-  ): RasterSet<DataT> {
-    return new RasterSet<DataT>({...opts, rasterSource});
+  static fromRasterSource<
+    DataT extends NumericRasterData = RasterData,
+    ParametersT extends GetRasterParameters = GetRasterParameters,
+    MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+  >(
+    rasterSource: RasterSource<DataT, ParametersT, MetadataT>,
+    opts: Omit<
+      RasterSetProps<DataT, ParametersT, MetadataT>,
+      'rasterSource' | 'getRaster' | 'getMetadata'
+    > = {}
+  ): RasterSet<DataT, ParametersT, MetadataT> {
+    return new RasterSet<DataT, ParametersT, MetadataT>({...opts, rasterSource});
+  }
+
+  /** Convenience factory for sources whose requests are not viewport-shaped. */
+  static fromCallbacks<
+    DataT extends NumericRasterData = RasterData,
+    ParametersT extends object = GetRasterParameters,
+    MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+  >(
+    opts: RasterSetBaseProps<DataT, ParametersT, MetadataT>
+  ): RasterSet<DataT, ParametersT, MetadataT> {
+    return new RasterSet<DataT, ParametersT, MetadataT>(opts);
   }
 
   /** Whether the manager has no requests in flight and a current raster. */
@@ -128,25 +184,30 @@ export class RasterSet<DataT = RasterData> {
   }
 
   /** Current accepted request and raster payload, if any. */
-  get currentRequest(): RasterSetRequest<DataT> | null {
+  get currentRequest(): RasterSetRequest<DataT, ParametersT> | null {
     return this._currentRequest;
   }
 
   /** Backing raster source when constructed from one. */
-  get rasterSource(): RasterSource | null {
+  get rasterSource(): RasterSource<DataT, ParametersT & GetRasterParameters, MetadataT> | null {
     return this._opts.rasterSource;
   }
 
   /** Subscribes to metadata and raster lifecycle events. */
-  subscribe(listener: RasterSetListener<DataT>): () => void {
+  subscribe(listener: RasterSetListener<DataT, ParametersT, MetadataT>): () => void {
     this._listeners.add(listener);
     return () => this._listeners.delete(listener);
   }
 
   /** Updates source callbacks or debounce settings, resetting state when the source changes. */
-  setOptions(opts: RasterSetProps<DataT>): void {
+  setOptions(opts: RasterSetProps<DataT, ParametersT, MetadataT>): void {
     const previousRasterSource = this._opts.rasterSource;
-    const nextOptions = this._normalizeOptions({...this._opts, ...opts});
+    const mergedOptions: RasterSetProps<DataT, ParametersT, MetadataT> = {...this._opts, ...opts};
+    if (opts.rasterSource && opts.rasterSource !== previousRasterSource) {
+      mergedOptions.getRaster = opts.getRaster;
+      mergedOptions.getMetadata = opts.getMetadata;
+    }
+    const nextOptions = this._normalizeOptions(mergedOptions);
     const sourceChanged =
       previousRasterSource !== nextOptions.rasterSource ||
       this._opts.getRaster !== nextOptions.getRaster ||
@@ -156,20 +217,42 @@ export class RasterSet<DataT = RasterData> {
 
     if (sourceChanged) {
       this._cancelScheduledRaster();
+      this._abortActiveRequest();
+      this._metadataAbortController?.abort();
+      this._sourceGeneration++;
       this.metadata = null;
       this._currentRequest = null;
-      this._lastAcceptedRequestId = -1;
-      this._nextRequestId = 0;
+
       this._emitUpdate();
     }
   }
 
   /** Loads metadata from the current raster source or callbacks. */
-  async loadMetadata(): Promise<RasterSourceMetadata> {
-    this._startLoading();
+  async loadMetadata(
+    options: {/** Caller cancellation for metadata. */ signal?: AbortSignal} = {}
+  ): Promise<MetadataT> {
+    if (this._finalized) throw new Error('RasterSet is finalized');
+    options.signal?.throwIfAborted();
+    this._metadataAbortController?.abort();
+    const abortController = new AbortController();
+    this._metadataAbortController = abortController;
+    const abortFromCaller = () => abortController.abort(options.signal?.reason);
+    options.signal?.addEventListener('abort', abortFromCaller, {once: true});
+    const metadataRequestId = ++this._metadataRequestId;
+    const generation = this._sourceGeneration;
     try {
-      const metadata = await this._opts.getMetadata();
-      if (this._finalized) {
+      this._startLoading();
+      abortController.signal.throwIfAborted();
+      const metadata = await waitForPromiseWithSignals(
+        signal => this._opts.getMetadata({signal}),
+        [abortController.signal]
+      );
+      abortController.signal.throwIfAborted();
+      if (
+        this._finalized ||
+        generation !== this._sourceGeneration ||
+        metadataRequestId !== this._metadataRequestId
+      ) {
         return metadata;
       }
       this.metadata = metadata;
@@ -179,26 +262,39 @@ export class RasterSet<DataT = RasterData> {
       this._emitUpdate();
       return metadata;
     } catch (error) {
+      if (abortController.signal.aborted) throw abortController.signal.reason;
+      if (isAbortError(error)) throw error;
       const normalizedError = normalizeRasterSetError(error, 'Raster metadata request failed');
-      if (!this._finalized) {
+      if (
+        !this._finalized &&
+        generation === this._sourceGeneration &&
+        metadataRequestId === this._metadataRequestId
+      ) {
         for (const listener of this._listeners) {
           listener.onMetadataLoadError?.(normalizedError);
         }
       }
       throw normalizedError;
     } finally {
+      options.signal?.removeEventListener('abort', abortFromCaller);
+      if (this._metadataAbortController === abortController) this._metadataAbortController = null;
       this._finishLoading();
     }
   }
 
   /** Debounces and issues a new raster request for the supplied parameters. */
-  requestRaster(parameters: GetRasterParameters, debounceTime = this._opts.debounceTime): number {
+  requestRaster(parameters: ParametersT, debounceTime = this._opts.debounceTime): number {
+    if (this._finalized) return -1;
     if (!this.shouldRefetchRaster(parameters)) {
+      this._cancelScheduledRaster();
+      this._abortActiveRequest();
+      this._nextRequestId++;
       return this._currentRequest?.requestId ?? -1;
     }
 
     const requestId = this._nextRequestId++;
     this._cancelScheduledRaster();
+    this._abortActiveRequest();
 
     if (debounceTime > 0) {
       this._timeoutId = setTimeout(() => {
@@ -213,7 +309,7 @@ export class RasterSet<DataT = RasterData> {
   }
 
   /** Returns `true` when the supplied parameters warrant a new raster fetch. */
-  shouldRefetchRaster(parameters: GetRasterParameters): boolean {
+  shouldRefetchRaster(parameters: ParametersT): boolean {
     return this._opts.shouldRefetch({
       currentRequest: this._currentRequest,
       metadata: this.metadata,
@@ -226,33 +322,41 @@ export class RasterSet<DataT = RasterData> {
     this._finalized = true;
     this._cancelScheduledRaster();
     this._abortActiveRequest();
+    this._metadataAbortController?.abort();
+    this._metadataAbortController = null;
+    this._loadCounter = 0;
     this._listeners.clear();
   }
 
   /** Loads a raster immediately and accepts it only if it is the newest completed request. */
-  private async _loadRaster(requestId: number, parameters: GetRasterParameters): Promise<void> {
+  private async _loadRaster(requestId: number, parameters: ParametersT): Promise<void> {
     if (this._finalized) {
       return;
     }
 
+    const callerSignal = (parameters as {signal?: AbortSignal}).signal;
+    if (callerSignal?.aborted) return;
+    const abortController = new AbortController();
+    this._abortController = abortController;
+    const abortFromCaller = () => abortController.abort(callerSignal?.reason);
+    callerSignal?.addEventListener('abort', abortFromCaller, {once: true});
     this._startLoading();
-    for (const listener of this._listeners) {
-      listener.onRasterLoadStart?.(requestId, parameters);
-    }
-
     try {
-      const abortController = new AbortController();
-      this._abortController = abortController;
-      const raster = await this._opts.getRaster({...parameters, signal: abortController.signal});
+      abortController.signal.throwIfAborted();
+      for (const listener of this._listeners) listener.onRasterLoadStart?.(requestId, parameters);
+      abortController.signal.throwIfAborted();
+      const raster = await waitForPromiseWithSignals(
+        signal => this._opts.getRaster(withAbortSignal(parameters, signal)),
+        [abortController.signal]
+      );
       if (
         this._finalized ||
         abortController.signal.aborted ||
-        requestId <= this._lastAcceptedRequestId
+        requestId !== this._nextRequestId - 1
       ) {
         return;
       }
 
-      this._lastAcceptedRequestId = requestId;
       this._currentRequest = {requestId, parameters, raster};
 
       for (const listener of this._listeners) {
@@ -260,23 +364,26 @@ export class RasterSet<DataT = RasterData> {
       }
       this._emitUpdate();
     } catch (error) {
-      if (isAbortError(error)) {
+      if (abortController.signal.aborted || isAbortError(error)) {
         return;
       }
       const normalizedError = normalizeRasterSetError(error, 'Raster request failed');
-      if (!this._finalized) {
+      if (!this._finalized && requestId === this._nextRequestId - 1) {
         for (const listener of this._listeners) {
           listener.onRasterLoadError?.(requestId, normalizedError, parameters);
         }
       }
     } finally {
-      this._abortController = null;
+      callerSignal?.removeEventListener('abort', abortFromCaller);
+      if (this._abortController === abortController) this._abortController = null;
       this._finishLoading();
     }
   }
 
   /** Resolves current options from either a source or direct callbacks. */
-  private _normalizeOptions(opts: RasterSetProps<DataT>): Required<RasterSetProps<DataT>> {
+  private _normalizeOptions(
+    opts: RasterSetProps<DataT, ParametersT, MetadataT>
+  ): Required<RasterSetProps<DataT, ParametersT, MetadataT>> {
     const rasterSource = opts.rasterSource || null;
     return {
       ...DEFAULT_RASTERSET_PROPS,
@@ -284,32 +391,35 @@ export class RasterSet<DataT = RasterData> {
       rasterSource,
       getMetadata:
         opts.getMetadata ||
-        (() => {
+        (options => {
           if (rasterSource) {
-            return rasterSource.getMetadata();
+            return rasterSource.getMetadata(options);
           }
-          return DEFAULT_RASTERSET_PROPS.getMetadata();
+          return DEFAULT_RASTERSET_PROPS.getMetadata() as Promise<MetadataT>;
         }),
       getRaster:
         opts.getRaster ||
-        ((parameters: GetRasterParameters) => {
+        ((parameters: ParametersT) => {
           if (rasterSource) {
-            return rasterSource.getRaster(parameters) as Promise<DataT>;
+            return rasterSource.getRaster(parameters as ParametersT & GetRasterParameters);
           }
-          return DEFAULT_RASTERSET_PROPS.getRaster(parameters) as Promise<DataT>;
+          return DEFAULT_RASTERSET_PROPS.getRaster(
+            parameters as GetRasterParameters
+          ) as Promise<DataT>;
         }),
       debounceTime: opts.debounceTime ?? DEFAULT_RASTERSET_PROPS.debounceTime,
       shouldRefetch:
         (opts.shouldRefetch as
-          | ((args: RasterSetShouldRefetchArgs<DataT>) => boolean)
+          | ((args: RasterSetShouldRefetchArgs<DataT, ParametersT, MetadataT>) => boolean)
           | undefined) ||
-        ((args: RasterSetShouldRefetchArgs<DataT>) =>
+        ((args: RasterSetShouldRefetchArgs<DataT, ParametersT, MetadataT>) =>
           DEFAULT_RASTERSET_PROPS.shouldRefetch(args as RasterSetShouldRefetchArgs))
     };
   }
 
   /** Emits one generic update notification to all subscribers. */
   private _emitUpdate(): void {
+    if (this._finalized) return;
     for (const listener of this._listeners) {
       listener.onUpdate?.();
     }
@@ -317,6 +427,7 @@ export class RasterSet<DataT = RasterData> {
 
   /** Emits one loading-state transition to all subscribers. */
   private _emitLoadingStateChange(isLoading: boolean): void {
+    if (this._finalized) return;
     for (const listener of this._listeners) {
       listener.onLoadingStateChange?.(isLoading);
     }
@@ -357,6 +468,25 @@ export class RasterSet<DataT = RasterData> {
   }
 }
 
+/** Adds cancellation to a request while preserving its array/prototype shape. */
+function withAbortSignal<ParametersT extends object>(
+  parameters: ParametersT,
+  signal: AbortSignal
+): ParametersT {
+  const descriptors = Object.getOwnPropertyDescriptors(parameters);
+  delete descriptors.signal;
+  const request = Array.isArray(parameters)
+    ? Object.defineProperties(parameters.slice(), descriptors)
+    : Object.create(Object.getPrototypeOf(parameters), descriptors);
+  Object.defineProperty(request, 'signal', {
+    configurable: true,
+    enumerable: true,
+    value: signal,
+    writable: true
+  });
+  return request as ParametersT;
+}
+
 /** Normalizes arbitrary thrown values to `Error` instances for raster-set callbacks. */
 function normalizeRasterSetError(error: unknown, message: string): Error {
   if (error instanceof Error) {