@loaders.gl/core 5.0.0-alpha.11 → 5.0.0-alpha.13

package/src/loader-utils/lib/request-utils/request-scheduler.ts

@@ -0,0 +1,230 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Stats} from 'probe.gl/stats';
+
+type Handle = any;
+type DoneFunction = () => any;
+type GetPriorityFunction = () => number;
+type RequestResult = {
+  done: DoneFunction;
+} | null;
+
+/** RequestScheduler Options */
+export type RequestSchedulerProps = {
+  id?: string;
+  throttleRequests?: boolean;
+  maxRequests?: number;
+  /** Quiet period after the most recent new request; completions never restart this timer. */
+  debounceTime?: number;
+};
+
+const STAT_QUEUED_REQUESTS = 'Queued Requests';
+const STAT_ACTIVE_REQUESTS = 'Active Requests';
+const STAT_CANCELLED_REQUESTS = 'Cancelled Requests';
+const STAT_QUEUED_REQUESTS_EVER = 'Queued Requests Ever';
+const STAT_ACTIVE_REQUESTS_EVER = 'Active Requests Ever';
+
+const DEFAULT_PROPS: Required<RequestSchedulerProps> = {
+  id: 'request-scheduler',
+  /** Specifies if the request scheduler should throttle incoming requests, mainly for comparative testing. */
+  throttleRequests: true,
+  /** The maximum number of simultaneous active requests. Un-throttled requests do not observe this limit. */
+  maxRequests: 6,
+  /**
+   * Specifies a debounce time, in milliseconds. All requests are queued, until no new requests have
+   * been added to the queue for this amount of time.
+   */
+  debounceTime: 0
+};
+
+/** Tracks one request */
+type Request = {
+  handle: Handle;
+  priority: number;
+  getPriority: GetPriorityFunction;
+  resolve?: (value: any) => any;
+};
+
+/**
+ * Used to issue a request, without having them "deeply queued" by the browser.
+ * @todo - Track requests globally, across multiple servers
+ */
+export default class RequestScheduler {
+  readonly props: Required<RequestSchedulerProps>;
+  readonly stats: Stats;
+  activeRequestCount: number = 0;
+
+  /** Tracks the number of active requests and prioritizes/cancels queued requests. */
+  private requestQueue: Request[] = [];
+  private requestMap: Map<Handle, Promise<RequestResult>> = new Map();
+  /** Pending arrival debounce or next-tick refill; only new arrivals replace this timer. */
+  private updateTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(props: RequestSchedulerProps = {}) {
+    this.props = {...DEFAULT_PROPS, ...props};
+
+    // Returns the statistics used by the request scheduler.
+    this.stats = new Stats({id: this.props.id});
+    this.stats.get(STAT_QUEUED_REQUESTS);
+    this.stats.get(STAT_ACTIVE_REQUESTS);
+    this.stats.get(STAT_CANCELLED_REQUESTS);
+    this.stats.get(STAT_QUEUED_REQUESTS_EVER);
+    this.stats.get(STAT_ACTIVE_REQUESTS_EVER);
+  }
+
+  /**
+   * Update scheduler props. Preserves active and queued requests.
+   */
+  setProps(props: Omit<RequestSchedulerProps, 'id'>): void {
+    if (props.throttleRequests !== undefined) {
+      this.props.throttleRequests = props.throttleRequests;
+    }
+    if (props.maxRequests !== undefined) {
+      this.props.maxRequests = props.maxRequests;
+    }
+    if (props.debounceTime !== undefined) {
+      this.props.debounceTime = props.debounceTime;
+    }
+  }
+
+  /**
+   * Called by an application that wants to issue a request, without having it deeply queued by the browser
+   *
+   * When the returned promise resolved, it is OK for the application to issue a request.
+   * The promise resolves to an object that contains a `done` method.
+   * When the application's request has completed (or failed), the application must call the `done` function
+   *
+   * @param handle
+   * @param getPriority will be called when request "slots" open up,
+   *    allowing the caller to update priority or cancel the request
+   *    Highest priority executes first, priority < 0 cancels the request
+   * @returns a promise
+   *   - resolves to a object (with a `done` field) when the request can be issued without queueing,
+   *   - resolves to `null` if the request has been cancelled (by the callback return < 0).
+   *     In this case the application should not issue the request
+   */
+  scheduleRequest(
+    handle: Handle,
+    getPriority: GetPriorityFunction = () => 0
+  ): Promise<RequestResult> {
+    // Allows throttling to be disabled
+    if (!this.props.throttleRequests) {
+      return Promise.resolve({done: () => {}});
+    }
+
+    // dedupe
+    if (this.requestMap.has(handle)) {
+      return this.requestMap.get(handle) as Promise<any>;
+    }
+
+    const request: Request = {handle, priority: 0, getPriority};
+    const promise = new Promise<RequestResult>(resolve => {
+      // @ts-ignore
+      request.resolve = resolve;
+      return request;
+    });
+
+    this.requestQueue.push(request);
+    this.requestMap.set(handle, promise);
+    this._issueNewRequests();
+    return promise;
+  }
+
+  // PRIVATE
+
+  _issueRequest(request: Request): Promise<any> {
+    const {handle, resolve} = request;
+    let isDone = false;
+
+    const done = () => {
+      // can only be called once
+      if (!isDone) {
+        isDone = true;
+
+        // Stop tracking a request - it has completed, failed, cancelled etc
+        this.requestMap.delete(handle);
+        this.activeRequestCount--;
+        this.scheduleRefill();
+      }
+    };
+
+    // Track this request
+    this.activeRequestCount++;
+
+    return resolve ? resolve({done}) : Promise.resolve({done});
+  }
+
+  /** Refills freed slots on the next tick while preserving any pending arrival debounce. */
+  private scheduleRefill(): void {
+    if (this.updateTimer !== null) {
+      return;
+    }
+    this.updateTimer = setTimeout(() => this._issueNewRequestsAsync(), 0);
+  }
+
+  /** Restarts the quiet period when a new request enters the queue. */
+  _issueNewRequests(): void {
+    if (this.updateTimer !== null) {
+      clearTimeout(this.updateTimer);
+    }
+    this.updateTimer = setTimeout(() => this._issueNewRequestsAsync(), this.props.debounceTime);
+  }
+
+  /** Clears timer ownership before updating priorities and dispatching queued requests. */
+  _issueNewRequestsAsync() {
+    if (this.updateTimer !== null) {
+      clearTimeout(this.updateTimer);
+    }
+    this.updateTimer = null;
+
+    const freeSlots = Math.max(this.props.maxRequests - this.activeRequestCount, 0);
+
+    if (freeSlots === 0) {
+      return;
+    }
+
+    this._updateAllRequests();
+
+    // Resolve pending promises for the top-priority requests
+    for (let i = 0; i < freeSlots; ++i) {
+      const request = this.requestQueue.shift();
+      if (request) {
+        this._issueRequest(request); // eslint-disable-line @typescript-eslint/no-floating-promises
+      }
+    }
+
+    // Uncomment to debug
+    // console.log(`${freeSlots} free slots, ${this.requestQueue.length} queued requests`);
+  }
+
+  /** Ensure all requests have updated priorities, and that no longer valid requests are cancelled */
+  _updateAllRequests() {
+    const requestQueue = this.requestQueue;
+    for (let i = 0; i < requestQueue.length; ++i) {
+      const request = requestQueue[i];
+      if (!this._updateRequest(request)) {
+        // Remove the element and make sure to adjust the counter to account for shortened array
+        requestQueue.splice(i, 1);
+        this.requestMap.delete(request.handle);
+        i--;
+      }
+    }
+
+    // Sort the remaining requests based on priority
+    requestQueue.sort((a, b) => a.priority - b.priority);
+  }
+
+  /** Update a single request by calling the callback */
+  _updateRequest(request) {
+    request.priority = request.getPriority(request.handle); // eslint-disable-line callback-return
+
+    // by returning a negative priority, the callback cancels the request
+    if (request.priority < 0) {
+      request.resolve(null);
+      return false;
+    }
+    return true;
+  }
+}

package/src/loader-utils/lib/scan-utils/columnar-predicate.ts

@@ -0,0 +1,397 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ArrayType} from '@loaders.gl/core/schema';
+
+/** Scalar values supported by format-neutral columnar predicates. */
+export type ColumnarPredicateValue = boolean | number | bigint | string | Date | Uint8Array;
+
+/** Named value retained in a portable predicate until an executor binds it. */
+export type ColumnarPredicateParameter = Readonly<{
+  /** Parameter name without a query-language prefix. */
+  parameter: string;
+}>;
+
+/** Concrete scalar or unresolved named value accepted while constructing a predicate. */
+export type ColumnarPredicateInputValue = ColumnarPredicateValue | ColumnarPredicateParameter;
+
+/** Runtime values used to bind named predicate parameters. */
+export type ColumnarPredicateParameterValues = Readonly<Record<string, ColumnarPredicateValue>>;
+
+/** Reference to a top-level or nested column. */
+export type ColumnarPredicateProperty = {
+  property: string | readonly string[];
+};
+
+export type ColumnarComparisonPredicate<
+  ValueT = ColumnarPredicateValue,
+  PropertyT extends ColumnarPredicateProperty = ColumnarPredicateProperty
+> = {
+  op: '=' | '<>' | '<' | '<=' | '>' | '>=';
+  args: readonly [PropertyT, ValueT];
+};
+
+export type ColumnarInPredicate<
+  ValueT = ColumnarPredicateValue,
+  PropertyT extends ColumnarPredicateProperty = ColumnarPredicateProperty
+> = {
+  op: 'in';
+  args: readonly [PropertyT, readonly ValueT[]];
+};
+
+export type ColumnarNullPredicate<
+  PropertyT extends ColumnarPredicateProperty = ColumnarPredicateProperty
+> = {
+  op: 'isNull';
+  args: readonly [PropertyT];
+};
+
+export type ColumnarLogicalPredicate<
+  ValueT = ColumnarPredicateValue,
+  PropertyT extends ColumnarPredicateProperty = ColumnarPredicateProperty
+> = {
+  op: 'and' | 'or';
+  args: readonly ColumnarPredicate<ValueT, PropertyT>[];
+};
+
+export type ColumnarNotPredicate<
+  ValueT = ColumnarPredicateValue,
+  PropertyT extends ColumnarPredicateProperty = ColumnarPredicateProperty
+> = {
+  op: 'not';
+  args: readonly [ColumnarPredicate<ValueT, PropertyT>];
+};
+
+/** Small serializable expression tree suitable for scan planning and exact filtering. */
+export type ColumnarPredicate<
+  ValueT = ColumnarPredicateValue,
+  PropertyT extends ColumnarPredicateProperty = ColumnarPredicateProperty
+> =
+  | ColumnarComparisonPredicate<ValueT, PropertyT>
+  | ColumnarInPredicate<ValueT, PropertyT>
+  | ColumnarNullPredicate<PropertyT>
+  | ColumnarLogicalPredicate<ValueT, PropertyT>
+  | ColumnarNotPredicate<ValueT, PropertyT>;
+
+/** Predicate form that may retain named parameters before physical execution. */
+export type ParameterizedColumnarPredicate<
+  PropertyT extends ColumnarPredicateProperty = ColumnarPredicateProperty
+> = ColumnarPredicate<ColumnarPredicateInputValue, PropertyT>;
+
+export function getColumnarPredicateColumns<ValueT, PropertyT extends ColumnarPredicateProperty>(
+  predicate: ColumnarPredicate<ValueT, PropertyT>
+): string[] {
+  return [...new Set(getColumnarPredicatePaths(predicate).map(path => path[0]))];
+}
+
+export function getColumnarPredicatePath(property: ColumnarPredicateProperty): string[] {
+  return typeof property.property === 'string' ? [property.property] : [...property.property];
+}
+
+export function getColumnarPredicatePaths<ValueT, PropertyT extends ColumnarPredicateProperty>(
+  predicate: ColumnarPredicate<ValueT, PropertyT>
+): string[][] {
+  const paths = new Map<string, string[]>();
+  visitColumnarPredicate(predicate, child => {
+    if ('property' in child.args[0]) {
+      const path = getColumnarPredicatePath(child.args[0]);
+      paths.set(path.join('\0'), path);
+    }
+  });
+  return [...paths.values()];
+}
+
+/** Returns unresolved named parameter names in their first-occurrence order. */
+export function getColumnarPredicateParameterNames<PropertyT extends ColumnarPredicateProperty>(
+  predicate: ParameterizedColumnarPredicate<PropertyT>
+): string[] {
+  const parameterNames = new Set<string>();
+  visitColumnarPredicate(predicate, child => {
+    if (child.op === 'and' || child.op === 'or' || child.op === 'not' || child.op === 'isNull') {
+      return;
+    }
+    const values = child.op === 'in' ? child.args[1] : [child.args[1]];
+    for (const value of values) {
+      if (isColumnarPredicateParameter(value)) {
+        parameterNames.add(value.parameter);
+      }
+    }
+  });
+  return [...parameterNames];
+}
+
+export function copyColumnarPredicate(predicate: ColumnarPredicate): ColumnarPredicate {
+  if (predicate.op === 'and' || predicate.op === 'or') {
+    return {op: predicate.op, args: predicate.args.map(copyColumnarPredicate)};
+  }
+  if (predicate.op === 'not') {
+    return {op: 'not', args: [copyColumnarPredicate(predicate.args[0])]};
+  }
+  const leaf = predicate as
+    | ColumnarComparisonPredicate
+    | ColumnarInPredicate
+    | ColumnarNullPredicate;
+  const property = {property: [...getColumnarPredicatePath(leaf.args[0])]};
+  if (leaf.op === 'isNull') return {op: 'isNull', args: [property]};
+  if (leaf.op === 'in') {
+    return {op: 'in', args: [property, leaf.args[1].map(copyColumnarPredicateValue)]};
+  }
+  return {op: leaf.op, args: [property, copyColumnarPredicateValue(leaf.args[1])]};
+}
+
+export function validateColumnarPredicate(
+  predicate: ColumnarPredicate<unknown>,
+  availableColumns: ReadonlySet<string>
+): void {
+  visitColumnarPredicate(predicate, child => {
+    if (child.op === 'and' || child.op === 'or') {
+      if (child.args.length < 2)
+        throw new Error(`Columnar predicate ${child.op} requires at least two child predicates`);
+      return;
+    }
+    if (child.op === 'not') return;
+    const leaf = child as ColumnarComparisonPredicate | ColumnarInPredicate | ColumnarNullPredicate;
+    const path = getColumnarPredicatePath(leaf.args[0]);
+    if (!path.length || path.some(component => !component)) {
+      throw new Error('Columnar predicate property path must contain non-empty strings');
+    }
+    if (!availableColumns.has(path[0]))
+      throw new Error(`Columnar predicate column not found: ${path.join('.')}`);
+    if (leaf.op === 'in' && leaf.args[1].length === 0) {
+      throw new Error('Columnar predicate in requires at least one value');
+    }
+  });
+}
+
+/** Returns whether a predicate value is an unresolved named parameter. */
+export function isColumnarPredicateParameter(value: unknown): value is ColumnarPredicateParameter {
+  const parameterValue = value as {parameter?: unknown};
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.keys(value).length === 1 &&
+    Object.hasOwn(value, 'parameter') &&
+    typeof parameterValue.parameter === 'string' &&
+    parameterValue.parameter.length > 0
+  );
+}
+
+/** Returns whether a runtime value belongs to the portable predicate scalar set. */
+export function isColumnarPredicateValue(value: unknown): value is ColumnarPredicateValue {
+  return (
+    typeof value === 'boolean' ||
+    typeof value === 'bigint' ||
+    typeof value === 'string' ||
+    (typeof value === 'number' && Number.isFinite(value)) ||
+    (value instanceof Date && Number.isFinite(value.getTime())) ||
+    value instanceof Uint8Array
+  );
+}
+
+/** Binds every named parameter without mutating the portable predicate. */
+export function bindColumnarPredicateParameters<
+  PropertyT extends ColumnarPredicateProperty = ColumnarPredicateProperty
+>(
+  predicate: ParameterizedColumnarPredicate<PropertyT>,
+  parameters: ColumnarPredicateParameterValues
+): ColumnarPredicate<ColumnarPredicateValue, PropertyT> {
+  switch (predicate.op) {
+    case 'and':
+    case 'or':
+      return {
+        op: predicate.op,
+        args: predicate.args.map(child => bindColumnarPredicateParameters(child, parameters))
+      };
+    case 'not':
+      return {
+        op: 'not',
+        args: [bindColumnarPredicateParameters(predicate.args[0], parameters)]
+      };
+    case 'isNull':
+      return {op: 'isNull', args: [copyColumnarPredicateProperty(predicate.args[0])]};
+    case 'in':
+      return {
+        op: 'in',
+        args: [
+          copyColumnarPredicateProperty(predicate.args[0]),
+          predicate.args[1].map(value => bindColumnarPredicateValue(value, parameters))
+        ]
+      };
+    default:
+      return {
+        op: predicate.op,
+        args: [
+          copyColumnarPredicateProperty(predicate.args[0]),
+          bindColumnarPredicateValue(predicate.args[1], parameters)
+        ]
+      };
+  }
+}
+
+export function filterColumnarRowIndices(
+  predicate: ColumnarPredicate | undefined,
+  columns: Record<string, ArrayType>,
+  rowCount: number
+): number[] {
+  if (!predicate) return Array.from({length: rowCount}, (_, index) => index);
+  const result: number[] = [];
+  for (let rowIndex = 0; rowIndex < rowCount; rowIndex++) {
+    if (evaluateColumnarPredicate(predicate, columns, rowIndex) === true) result.push(rowIndex);
+  }
+  return result;
+}
+
+export function gatherColumnarColumns(
+  columns: Record<string, ArrayType>,
+  rowIndices: readonly number[],
+  selectedColumns?: ReadonlySet<string>
+): Record<string, ArrayType> {
+  const result: Record<string, ArrayType> = {};
+  for (const [name, column] of Object.entries(columns)) {
+    if (!selectedColumns || selectedColumns.has(name)) {
+      result[name] = rowIndices.map(rowIndex => (column as ArrayLike<unknown>)[rowIndex]);
+    }
+  }
+  return result;
+}
+
+function evaluateColumnarPredicate(
+  predicate: ColumnarPredicate,
+  columns: Record<string, ArrayType>,
+  rowIndex: number
+): boolean | null {
+  if (predicate.op === 'and' || predicate.op === 'or') {
+    const results = predicate.args.map(child =>
+      evaluateColumnarPredicate(child, columns, rowIndex)
+    );
+    return predicate.op === 'and'
+      ? results.includes(false)
+        ? false
+        : results.includes(null)
+          ? null
+          : true
+      : results.includes(true)
+        ? true
+        : results.includes(null)
+          ? null
+          : false;
+  }
+  if (predicate.op === 'not') {
+    const value = evaluateColumnarPredicate(predicate.args[0], columns, rowIndex);
+    return value === null ? null : !value;
+  }
+  const leaf = predicate as
+    | ColumnarComparisonPredicate
+    | ColumnarInPredicate
+    | ColumnarNullPredicate;
+  const value = getColumnarValue(columns, getColumnarPredicatePath(leaf.args[0]), rowIndex);
+  if (leaf.op === 'isNull') return value === null || value === undefined;
+  if (value === null || value === undefined) return null;
+  if (leaf.op === 'in')
+    return leaf.args[1].some(candidate => compareColumnarValues(value, candidate) === 0);
+  const comparison = compareColumnarValues(value, leaf.args[1]);
+  return leaf.op === '='
+    ? comparison === 0
+    : leaf.op === '<>'
+      ? comparison !== 0
+      : leaf.op === '<'
+        ? comparison < 0
+        : leaf.op === '<='
+          ? comparison <= 0
+          : leaf.op === '>'
+            ? comparison > 0
+            : comparison >= 0;
+}
+
+function visitColumnarPredicate<ValueT, PropertyT extends ColumnarPredicateProperty>(
+  predicate: ColumnarPredicate<ValueT, PropertyT>,
+  visitor: (predicate: ColumnarPredicate<ValueT, PropertyT>) => void
+): void {
+  visitor(predicate);
+  if (predicate.op === 'and' || predicate.op === 'or')
+    predicate.args.forEach(child => visitColumnarPredicate(child, visitor));
+  else if (predicate.op === 'not') visitColumnarPredicate(predicate.args[0], visitor);
+}
+
+/** Resolves one parameter reference or returns an already concrete scalar. */
+function bindColumnarPredicateValue(
+  value: ColumnarPredicateInputValue,
+  parameters: ColumnarPredicateParameterValues
+): ColumnarPredicateValue {
+  if (!isColumnarPredicateParameter(value)) return value;
+  if (!Object.hasOwn(parameters, value.parameter)) {
+    throw new Error(`Columnar predicate parameter ":${value.parameter}" requires a value`);
+  }
+  const parameterValue = parameters[value.parameter];
+  if (isColumnarPredicateParameter(parameterValue)) {
+    throw new Error(
+      `Columnar predicate parameter ":${value.parameter}" cannot reference another parameter`
+    );
+  }
+  if (!isColumnarPredicateValue(parameterValue)) {
+    throw new Error(`Columnar predicate parameter ":${value.parameter}" has an unsupported value`);
+  }
+  return copyColumnarPredicateValue(parameterValue);
+}
+
+/** Copies a property while preserving its backend-specific property subtype. */
+function copyColumnarPredicateProperty<PropertyT extends ColumnarPredicateProperty>(
+  property: PropertyT
+): PropertyT {
+  return {
+    ...property,
+    property: typeof property.property === 'string' ? property.property : [...property.property]
+  } as PropertyT;
+}
+
+function getColumnarValue(
+  columns: Record<string, ArrayType>,
+  path: string[],
+  rowIndex: number
+): unknown {
+  let value: any = columns[path[0]]?.[rowIndex];
+  for (let index = 1; index < path.length && value != null; index++) value = value[path[index]];
+  return value;
+}
+
+function copyColumnarPredicateValue(value: ColumnarPredicateValue): ColumnarPredicateValue {
+  if (value instanceof Uint8Array) return value.slice();
+  if (value instanceof Date) return new Date(value.getTime());
+  return value;
+}
+
+function compareColumnarValues(left: unknown, right: ColumnarPredicateValue): number {
+  if (left instanceof Uint8Array && right instanceof Uint8Array) return compareBytes(left, right);
+  if (left instanceof Uint8Array || right instanceof Uint8Array)
+    throw new Error('Columnar binary predicates require binary values on both sides');
+  if (left instanceof Date || right instanceof Date) {
+    if (!(left instanceof Date) || !(right instanceof Date))
+      throw new Error('Columnar date predicates require date values on both sides');
+    return compareNumbers(left.getTime(), right.getTime());
+  }
+  const leftType = typeof left;
+  const rightType = typeof right;
+  const numeric =
+    (leftType === 'number' || leftType === 'bigint') &&
+    (rightType === 'number' || rightType === 'bigint');
+  if (!numeric && leftType !== rightType)
+    throw new Error(`Columnar predicate cannot compare ${leftType} with ${rightType}`);
+  if (!numeric && leftType !== 'string' && leftType !== 'boolean')
+    throw new Error(`Columnar predicate does not support ${leftType} values`);
+  return (left as any) < (right as any) ? -1 : (left as any) > (right as any) ? 1 : 0;
+}
+
+function compareNumbers(left: number, right: number): number {
+  if (!Number.isFinite(left) || !Number.isFinite(right))
+    throw new Error('Non-finite values cannot be ordered by a columnar predicate');
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function compareBytes(left: Uint8Array, right: Uint8Array): number {
+  const length = Math.min(left.length, right.length);
+  for (let index = 0; index < length; index++)
+    if (left[index] !== right[index]) return left[index] < right[index] ? -1 : 1;
+  return left.length - right.length;
+}

package/src/loader-utils/lib/scan-utils/experimental-scan-options.ts

@@ -0,0 +1,46 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ColumnarPredicate} from './columnar-predicate';
+import type {ScanBounds, ScanExecutionTelemetryCallback} from './scan-query-metadata';
+
+/**
+ * Experimental common scan request accepted by loaders that implement the scan protocol.
+ *
+ * Format loaders apply the fields relevant to their query family and must reject unsupported
+ * fields rather than silently ignoring them. This intentionally remains a common superset in 5.0
+ * so applications and Deck.gl adapters can forward one stable option object.
+ */
+export type ExperimentalScanOptions = Readonly<{
+  /** Portable predicate for table-like sources. */
+  predicate?: ColumnarPredicate;
+  /** Output columns or bands selected by the caller. */
+  columns?: readonly string[];
+  /** Maximum number of rows or points retained after filtering. */
+  limit?: number;
+  /** Cooperative cancellation signal. */
+  signal?: AbortSignal;
+  /** Receives one terminal execution snapshot without changing query semantics. */
+  onTelemetry?: ScanExecutionTelemetryCallback;
+  /** Source-coordinate bounds for spatial, raster, and point-cloud scans. */
+  bounds?: ScanBounds;
+  /** Raster overview or point-cloud hierarchy level. */
+  level?: number;
+  /** Shallowest point-cloud hierarchy level to read. */
+  minimumLevel?: number;
+  /** Deepest point-cloud hierarchy level to read. */
+  maximumLevel?: number;
+  /** Desired maximum point spacing for point-cloud scans. */
+  targetSpacing?: number;
+  /** Requested raster output width in pixels. */
+  width?: number;
+  /** Requested raster output height in pixels. */
+  height?: number;
+  /** Named raster variables or bands. */
+  variables?: readonly string[];
+  /** Numeric raster channel indices. */
+  channels?: readonly number[];
+  /** Raster dimension indices or half-open ranges. */
+  slices?: Readonly<Record<string, number | readonly [number, number]>>;
+}>;