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

package/src/loader-utils/lib/scan-utils/point-cloud-query.ts

@@ -0,0 +1,176 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ColumnarPredicate, ColumnarPredicateProperty} from './columnar-predicate';
+import type {
+  TableQueryCapabilities,
+  TableQueryOperatorSupport,
+  TableQueryOptions
+} from './table-query';
+import {validateTableQueryOptions} from './table-query';
+
+/** Three-dimensional axis-aligned bounds in the point cloud's source coordinate system. */
+export type PointCloudQueryBounds = Readonly<{
+  /** Inclusive minimum X, Y, and Z coordinates. */
+  minimum: readonly [x: number, y: number, z: number];
+  /** Inclusive maximum X, Y, and Z coordinates. */
+  maximum: readonly [x: number, y: number, z: number];
+}>;
+
+/** Portable attribute, bounds, and hierarchy request for a point-cloud scan. */
+export type PointCloudQueryOptions<
+  PredicateT extends ColumnarPredicate<unknown, ColumnarPredicateProperty> = ColumnarPredicate
+> = TableQueryOptions<PredicateT> &
+  Readonly<{
+    /** Optional three-dimensional source-coordinate bounds. */
+    bounds?: PointCloudQueryBounds;
+    /** Shallowest hierarchy level that may contribute points. */
+    minimumLevel?: number;
+    /** Deepest hierarchy level that may contribute points. */
+    maximumLevel?: number;
+    /** Desired maximum point spacing in source coordinate units. */
+    targetSpacing?: number;
+  }>;
+
+/** Capabilities advertised by a point-cloud query adapter. */
+export type PointCloudQueryCapabilities = TableQueryCapabilities &
+  Readonly<{
+    /** Whether spatial bounds prune hierarchy nodes or are evaluated residually. */
+    bounds: TableQueryOperatorSupport;
+    /** Whether hierarchy level constraints avoid physical node reads. */
+    levelOfDetail: TableQueryOperatorSupport;
+    /** Whether target spacing participates in physical node selection. */
+    spacing: TableQueryOperatorSupport;
+  }>;
+
+/** One hierarchy node considered by a portable point-cloud scan planner. */
+export type PointCloudScanTile = Readonly<{
+  /** Stable source-defined node identifier. */
+  id: string;
+  /** Zero-based hierarchy level. */
+  level: number;
+  /** Number of points stored by this node. */
+  pointCount: number;
+  /** Source spacing or geometric error represented by this node. */
+  geometricError: number;
+  /** Three-dimensional node bounds in the source coordinate system. */
+  bounds: PointCloudQueryBounds;
+}>;
+
+/** Loads the direct children of one portable point-cloud scan tile. */
+export type PointCloudScanChildrenLoader<TileT extends PointCloudScanTile = PointCloudScanTile> = (
+  tile: TileT
+) => Promise<readonly TileT[]>;
+
+/** Validates a point-cloud query against the attributes exposed by one source. */
+export function validatePointCloudQueryOptions<
+  ValueT,
+  PropertyT extends ColumnarPredicateProperty,
+  PredicateT extends ColumnarPredicate<ValueT, PropertyT>
+>(sourceColumnNames: readonly string[], options: PointCloudQueryOptions<PredicateT>): void {
+  validateTableQueryOptions(sourceColumnNames, options);
+  validatePointCloudBounds(options.bounds);
+  validateHierarchyLevel(options.minimumLevel, 'minimumLevel');
+  validateHierarchyLevel(options.maximumLevel, 'maximumLevel');
+  if (
+    options.minimumLevel !== undefined &&
+    options.maximumLevel !== undefined &&
+    options.minimumLevel > options.maximumLevel
+  ) {
+    throw new Error('Point cloud query minimumLevel cannot exceed maximumLevel.');
+  }
+  if (
+    options.targetSpacing !== undefined &&
+    (!Number.isFinite(options.targetSpacing) || options.targetSpacing <= 0)
+  ) {
+    throw new Error('Point cloud query targetSpacing must be a positive finite number.');
+  }
+}
+
+/**
+ * Selects point-cloud hierarchy nodes in deterministic breadth-first order.
+ *
+ * Bounds reject whole subtrees. Maximum level and target spacing stop descent after the selected
+ * node, while minimum level suppresses coarser node payloads without suppressing their children.
+ */
+export async function* selectPointCloudScanTiles<TileT extends PointCloudScanTile>(
+  rootTile: TileT,
+  loadChildren: PointCloudScanChildrenLoader<TileT>,
+  options: PointCloudQueryOptions = {}
+): AsyncIterableIterator<TileT> {
+  const pendingTiles: TileT[] = [rootTile];
+  const minimumLevel = options.minimumLevel ?? 0;
+
+  while (pendingTiles.length > 0) {
+    throwIfPointCloudScanAborted(options.signal);
+    const tile = pendingTiles.shift()!;
+    if (options.bounds && !intersectPointCloudBounds(tile.bounds, options.bounds)) {
+      continue;
+    }
+
+    const satisfiesMinimumLevel = tile.level >= minimumLevel;
+    if (satisfiesMinimumLevel) {
+      yield tile;
+    }
+
+    const reachedMaximumLevel =
+      options.maximumLevel !== undefined && tile.level >= options.maximumLevel;
+    const reachedTargetSpacing =
+      satisfiesMinimumLevel &&
+      options.targetSpacing !== undefined &&
+      tile.geometricError <= options.targetSpacing;
+    if (reachedMaximumLevel || reachedTargetSpacing) {
+      continue;
+    }
+
+    const children = [...(await loadChildren(tile))].sort((left, right) =>
+      left.id.localeCompare(right.id)
+    );
+    pendingTiles.push(...children);
+  }
+}
+
+/** Returns whether two inclusive point-cloud bounds intersect. */
+export function intersectPointCloudBounds(
+  left: PointCloudQueryBounds,
+  right: PointCloudQueryBounds
+): boolean {
+  for (let dimension = 0; dimension < 3; dimension++) {
+    if (
+      left.maximum[dimension] < right.minimum[dimension] ||
+      left.minimum[dimension] > right.maximum[dimension]
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function validatePointCloudBounds(bounds: PointCloudQueryBounds | undefined): void {
+  if (!bounds) {
+    return;
+  }
+  for (let dimension = 0; dimension < 3; dimension++) {
+    const minimum = bounds.minimum[dimension];
+    const maximum = bounds.maximum[dimension];
+    if (!Number.isFinite(minimum) || !Number.isFinite(maximum)) {
+      throw new Error('Point cloud query bounds must contain finite coordinates.');
+    }
+    if (minimum > maximum) {
+      throw new Error('Point cloud query bounds minimum cannot exceed maximum.');
+    }
+  }
+}
+
+function validateHierarchyLevel(level: number | undefined, name: string): void {
+  if (level !== undefined && (!Number.isSafeInteger(level) || level < 0)) {
+    throw new Error(`Point cloud query ${name} must be a non-negative safe integer.`);
+  }
+}
+
+function throwIfPointCloudScanAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) {
+    throw new DOMException('The operation was aborted', 'AbortError');
+  }
+}

package/src/loader-utils/lib/scan-utils/raster-query.ts

@@ -0,0 +1,82 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {RasterBoundingBox} from '../sources/raster-source';
+
+/** A bounded raster request shared by GeoTIFF, Zarr, and multidimensional sources. */
+export type RasterQueryOptions = Readonly<{
+  /** Source-coordinate bounds to read, in `[min, max]` form. */
+  bounds?: RasterBoundingBox;
+  /** Requested output width in pixels. */
+  width?: number;
+  /** Requested output height in pixels. */
+  height?: number;
+  /** Overview or multiscale level to read. */
+  level?: number;
+  /** Named variables or bands to include in the result. */
+  variables?: readonly string[];
+  /** Numeric channel indices to include in the result. */
+  channels?: readonly number[];
+  /** Non-spatial dimension indices or half-open `[start, stop)` ranges. */
+  slices?: Readonly<Record<string, number | readonly [number, number]>>;
+}>;
+
+/** Operator support advertised by a raster source. */
+export type RasterQueryCapabilities = Readonly<{
+  /** Whether bounds avoid reading unrelated tiles or chunks. */
+  bounds: 'unsupported' | 'residual' | 'pushdown';
+  /** Whether levels or overviews avoid reading full resolution data. */
+  level: 'unsupported' | 'residual' | 'pushdown';
+  /** Whether variables or channels avoid decoding unrelated values. */
+  variables: 'unsupported' | 'residual' | 'pushdown';
+  /** Whether named dimensions are selected before decoding. */
+  slices: 'unsupported' | 'residual' | 'pushdown';
+  /** Whether requests stream bounded tile or chunk tasks. */
+  streaming: boolean;
+  /** Whether range, chunk, and decode work observes cancellation. */
+  cancellation: boolean;
+}>;
+
+/** Validates a raster query without opening or decoding source data. */
+export function validateRasterQueryOptions(options: RasterQueryOptions): void {
+  if (options.width !== undefined) validatePositiveInteger(options.width, 'width');
+  if (options.height !== undefined) validatePositiveInteger(options.height, 'height');
+  if (options.level !== undefined) validateNonNegativeInteger(options.level, 'level');
+  if (options.bounds) {
+    for (let axis = 0; axis < 2; axis++) {
+      const minimum = options.bounds[0][axis];
+      const maximum = options.bounds[1][axis];
+      if (!Number.isFinite(minimum) || !Number.isFinite(maximum) || minimum > maximum) {
+        throw new Error('Raster query bounds must contain finite, ordered coordinates.');
+      }
+    }
+  }
+  for (const channel of options.channels || []) {
+    validateNonNegativeInteger(channel, 'channel');
+  }
+  for (const [name, slice] of Object.entries(options.slices || {})) {
+    if (!name) throw new Error('Raster query slice names must be non-empty.');
+    if (Array.isArray(slice)) {
+      if (slice.length !== 2 || !slice.every(Number.isFinite) || slice[0] > slice[1]) {
+        throw new Error(`Raster query slice ${name} must be an ordered finite range.`);
+      }
+    } else if (!Number.isFinite(slice)) {
+      throw new Error(`Raster query slice ${name} must be finite.`);
+    }
+  }
+}
+
+/** Validates a positive raster dimension. */
+function validatePositiveInteger(value: number, name: string): void {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new Error(`Raster query ${name} must be a positive safe integer.`);
+  }
+}
+
+/** Validates a non-negative raster index. */
+function validateNonNegativeInteger(value: number, name: string): void {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new Error(`Raster query ${name} must be a non-negative safe integer.`);
+  }
+}

package/src/loader-utils/lib/scan-utils/relational-query.ts

@@ -0,0 +1,188 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ColumnarPredicate, ColumnarPredicateProperty} from './columnar-predicate';
+import type {TableQueryOptions} from './table-query';
+import {planTableQuery} from './table-query';
+
+/** A scalar expression in the portable relational planner. */
+export type RelationalExpression = Readonly<{
+  /** Output alias for the expression. */
+  name: string;
+  /** Expression operator and operands. */
+  expression:
+    | {readonly op: 'column'; readonly column: string}
+    | {readonly op: 'literal'; readonly value: boolean | number | string | null}
+    | {
+        readonly op: 'add' | 'subtract' | 'multiply' | 'divide';
+        readonly left: string;
+        readonly right: string;
+      };
+}>;
+
+/** A portable ordering key. */
+export type RelationalOrderKey = Readonly<{
+  /** Column or expression name to order by. */
+  column: string;
+  /** Sort direction. */
+  direction?: 'asc' | 'desc';
+  /** Null placement. */
+  nulls?: 'first' | 'last';
+}>;
+
+/** A portable aggregate specification. */
+export type RelationalAggregate = Readonly<{
+  /** Aggregate function. */
+  function: 'count' | 'sum' | 'min' | 'max' | 'avg';
+  /** Input column, omitted for `count(*)`. */
+  column?: string;
+  /** Output alias. */
+  name: string;
+}>;
+
+/** A relational child query used by unions and joins. */
+export type RelationalChildQuery<
+  PredicateT extends ColumnarPredicate<unknown, ColumnarPredicateProperty> = ColumnarPredicate<
+    unknown,
+    ColumnarPredicateProperty
+  >
+> = Readonly<{
+  /** Logical source name. */
+  source: string;
+  /** Portable table query applied to the child. */
+  query?: TableQueryOptions<PredicateT>;
+}>;
+
+/** Portable relational extensions layered on top of a table scan. */
+export type RelationalQueryOptions<
+  PredicateT extends ColumnarPredicate<unknown, ColumnarPredicateProperty> = ColumnarPredicate<
+    unknown,
+    ColumnarPredicateProperty
+  >
+> = TableQueryOptions<PredicateT> &
+  Readonly<{
+    /** Computed columns evaluated before projection. */
+    expressions?: readonly RelationalExpression[];
+    /** Stable ordering applied before the global limit. */
+    orderBy?: readonly RelationalOrderKey[];
+    /** Grouping keys for aggregate output. */
+    groupBy?: readonly string[];
+    /** Aggregate output definitions. */
+    aggregates?: readonly RelationalAggregate[];
+    /** Additional child queries to concatenate. */
+    union?: readonly RelationalChildQuery<PredicateT>[];
+    /** Optional equi-join child and key mapping. */
+    join?: Readonly<{child: RelationalChildQuery<PredicateT>; left: string; right: string}>;
+  }>;
+
+/** Logical operator in a relational query plan. */
+export type RelationalPlanStep = Readonly<{
+  kind: 'table-query' | 'expression' | 'order' | 'aggregate' | 'union' | 'join';
+  detail: unknown;
+}>;
+
+/** Validates and normalizes the relational extensions without executing them. */
+export function planRelationalQuery<
+  PredicateT extends ColumnarPredicate<unknown, ColumnarPredicateProperty> = ColumnarPredicate<
+    unknown,
+    ColumnarPredicateProperty
+  >
+>(
+  sourceColumnNames: readonly string[],
+  options: RelationalQueryOptions<PredicateT> = {}
+): {
+  readonly tablePlan: ReturnType<typeof planTableQuery>;
+  readonly relationalSteps: readonly RelationalPlanStep[];
+} {
+  const available = new Set(sourceColumnNames);
+  const expressionNames = new Set<string>();
+  for (const expression of options.expressions || []) {
+    if (!expression.name) throw new Error('Relational expression names must be non-empty.');
+    if (available.has(expression.name) || expressionNames.has(expression.name)) {
+      throw new Error(`Relational expression duplicates column: ${expression.name}`);
+    }
+    expressionNames.add(expression.name);
+  }
+  const aggregateNames = new Set((options.aggregates || []).map(aggregate => aggregate.name));
+  const requiredColumns = new Set<string>();
+  const availableColumns = new Set(sourceColumnNames);
+  for (const expression of options.expressions || []) {
+    const definition = expression.expression;
+    if (definition.op === 'column') {
+      validateRelationalColumnReference(definition.column, availableColumns);
+      if (available.has(definition.column)) requiredColumns.add(definition.column);
+    }
+    if ('left' in definition) {
+      validateRelationalColumnReference(definition.left, availableColumns);
+      validateRelationalColumnReference(definition.right, availableColumns);
+      if (available.has(definition.left)) requiredColumns.add(definition.left);
+      if (available.has(definition.right)) requiredColumns.add(definition.right);
+    }
+    availableColumns.add(expression.name);
+  }
+  for (const key of options.orderBy || []) requiredColumns.add(key.column);
+  for (const key of options.groupBy || []) requiredColumns.add(key);
+  for (const aggregate of options.aggregates || []) {
+    if (aggregate.column) requiredColumns.add(aggregate.column);
+  }
+  const outputColumns = options.columns?.filter(
+    column => !expressionNames.has(column) && !aggregateNames.has(column)
+  );
+  const tablePlan = [
+    ...planTableQuery(sourceColumnNames, {
+      ...options,
+      columns: outputColumns,
+      predicate: options.predicate
+    })
+  ];
+  const scanStep = tablePlan[0];
+  if (scanStep?.kind === 'scan') {
+    const scanColumns = new Set(scanStep.columns);
+    for (const column of requiredColumns) {
+      if (available.has(column)) scanColumns.add(column);
+    }
+    tablePlan[0] = Object.freeze({kind: 'scan', columns: Object.freeze([...scanColumns])});
+  }
+  for (const expression of expressionNames) available.add(expression);
+  for (const aggregate of aggregateNames) available.add(aggregate);
+  for (const key of options.orderBy || []) {
+    if (!available.has(key.column))
+      throw new Error(`Relational order column not found: ${key.column}`);
+  }
+  for (const key of options.groupBy || []) {
+    if (!available.has(key)) throw new Error(`Relational group column not found: ${key}`);
+  }
+  for (const aggregate of options.aggregates || []) {
+    if (!aggregate.name) throw new Error('Relational aggregate names must be non-empty.');
+    if (aggregate.function !== 'count' && !aggregate.column) {
+      throw new Error(`Relational aggregate ${aggregate.function} requires a column.`);
+    }
+    if (aggregate.column && !available.has(aggregate.column)) {
+      throw new Error(`Relational aggregate column not found: ${aggregate.column}`);
+    }
+  }
+  const relationalSteps: RelationalPlanStep[] = [];
+  if (options.expressions?.length)
+    relationalSteps.push({kind: 'expression', detail: options.expressions});
+  if (options.orderBy?.length) relationalSteps.push({kind: 'order', detail: options.orderBy});
+  if (options.aggregates?.length || options.groupBy?.length) {
+    relationalSteps.push({
+      kind: 'aggregate',
+      detail: {groupBy: options.groupBy, aggregates: options.aggregates}
+    });
+  }
+  if (options.union?.length) relationalSteps.push({kind: 'union', detail: options.union});
+  if (options.join) relationalSteps.push({kind: 'join', detail: options.join});
+  return {tablePlan, relationalSteps: Object.freeze(relationalSteps)};
+}
+
+/** Validates that an expression operand refers to a source or earlier computed column. */
+function validateRelationalColumnReference(
+  columnName: string,
+  availableColumns: ReadonlySet<string>
+): void {
+  if (!availableColumns.has(columnName)) {
+    throw new Error(`Relational expression column not found: ${columnName}`);
+  }
+}

package/src/loader-utils/lib/scan-utils/scan-executor.ts

@@ -0,0 +1,208 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** A lazily executed ordered unit of scan work. */
+export type ScanTask<Value> = {
+  /** Executes the task and returns its values as an asynchronous iterable. */
+  readonly run: (signal: AbortSignal) => AsyncIterable<Value> | Promise<AsyncIterable<Value>>;
+};
+
+/** Options for bounded, ordered scan-task execution. */
+export type ScanExecutorOptions = {
+  /** Maximum number of tasks executing concurrently. Defaults to four. */
+  readonly concurrency?: number;
+  /** Signal used to cancel discovery, queued tasks, and active tasks. */
+  readonly signal?: AbortSignal;
+};
+
+const DEFAULT_SCAN_CONCURRENCY = 4;
+
+/**
+ * Executes scan tasks concurrently while yielding values in task order.
+ *
+ * Each task has a one-value buffer. This preserves deterministic output without allowing a slow
+ * earlier task to cause every later task to materialize its complete result in memory.
+ */
+export async function* executeScanTasks<Value>(
+  tasks: AsyncIterable<ScanTask<Value>>,
+  options: ScanExecutorOptions = {}
+): AsyncIterable<Value> {
+  const concurrency = normalizeScanConcurrency(options.concurrency);
+  const execution = createScanExecution(options.signal);
+  const signal = execution.signal;
+  throwIfScanAborted(signal);
+  const iterator = tasks[Symbol.asyncIterator]();
+  const scheduledTasks = new Map<number, ScanTaskState<Value>>();
+  let nextTaskIndex = 0;
+  let nextOutputIndex = 0;
+  let tasksComplete = false;
+  let discoveryError: unknown;
+
+  const scheduleNext = async (): Promise<void> => {
+    if (tasksComplete) return;
+    const next = await iterator.next();
+    if (next.done) {
+      tasksComplete = true;
+      return;
+    }
+    const queue = new ScanValueQueue<Value>();
+    const task = next.value;
+    const execution = executeScanTask(task, queue, signal);
+    scheduledTasks.set(nextTaskIndex++, {queue, execution});
+  };
+
+  const fillSlots = async (): Promise<void> => {
+    try {
+      while (scheduledTasks.size < concurrency && !tasksComplete) await scheduleNext();
+    } catch (error) {
+      discoveryError = error;
+      tasksComplete = true;
+    }
+  };
+
+  try {
+    await scheduleNext();
+    let discoveryPromise = fillSlots();
+    while (scheduledTasks.size > 0) {
+      const scheduledTask = scheduledTasks.get(nextOutputIndex);
+      if (!scheduledTask) throw new Error('Scan executor internal task ordering error');
+      for await (const value of scheduledTask.queue) {
+        throwIfScanAborted(signal);
+        yield value;
+      }
+      await scheduledTask.execution;
+      scheduledTasks.delete(nextOutputIndex++);
+      await discoveryPromise;
+      if (discoveryError !== undefined) throw discoveryError;
+      discoveryPromise = fillSlots();
+    }
+    await discoveryPromise;
+    if (discoveryError !== undefined) throw discoveryError;
+  } finally {
+    execution.abortController.abort();
+    execution.removeSignalListener();
+    await iterator.return?.();
+    await Promise.allSettled([...scheduledTasks.values()].map(task => task.execution));
+  }
+}
+
+/** Creates an internal cancellation scope for one scan execution. */
+function createScanExecution(signal?: AbortSignal): {
+  abortController: AbortController;
+  signal: AbortSignal;
+  removeSignalListener: () => void;
+} {
+  const abortController = new AbortController();
+  const abort = (): void => abortController.abort(signal?.reason);
+  if (signal?.aborted) abort();
+  else signal?.addEventListener('abort', abort, {once: true});
+  return {
+    abortController,
+    signal: abortController.signal,
+    removeSignalListener: () => signal?.removeEventListener('abort', abort)
+  };
+}
+
+type ScanTaskState<Value> = {
+  readonly queue: ScanValueQueue<Value>;
+  readonly execution: Promise<void>;
+};
+
+/** Runs one task and forwards its values into a bounded queue. */
+async function executeScanTask<Value>(
+  task: ScanTask<Value>,
+  queue: ScanValueQueue<Value>,
+  signal?: AbortSignal
+): Promise<void> {
+  try {
+    for await (const value of await task.run(signal || new AbortController().signal)) {
+      await queue.push(value, signal);
+    }
+    queue.finish();
+  } catch (error) {
+    queue.fail(error);
+  }
+}
+
+/** One-slot asynchronous queue used to apply backpressure between scan tasks and output. */
+class ScanValueQueue<Value> implements AsyncIterable<Value> {
+  private value!: Value;
+  private hasValue = false;
+  private finished = false;
+  private error: unknown;
+  private wakeConsumer: (() => void) | null = null;
+  private wakeProducer: (() => void) | null = null;
+
+  /** Buffers one value and waits until it has been consumed. */
+  async push(value: Value, signal?: AbortSignal): Promise<void> {
+    throwIfScanAborted(signal);
+    while (this.hasValue) await this.waitForWakeup('producer', signal);
+    this.value = value;
+    this.hasValue = true;
+    this.wakeConsumer?.();
+    this.wakeConsumer = null;
+    while (this.hasValue) await this.waitForWakeup('producer', signal);
+  }
+
+  /** Marks the queue complete and wakes its consumer. */
+  finish(): void {
+    this.finished = true;
+    this.wakeConsumer?.();
+    this.wakeConsumer = null;
+  }
+
+  /** Stores a producer error and wakes its consumer. */
+  fail(error: unknown): void {
+    this.error = error;
+    this.finished = true;
+    this.wakeConsumer?.();
+    this.wakeConsumer = null;
+  }
+
+  /** Iterates values in task order. */
+  async *[Symbol.asyncIterator](): AsyncIterator<Value> {
+    while (true) {
+      if (this.hasValue) {
+        const value = this.value;
+        this.hasValue = false;
+        this.wakeProducer?.();
+        this.wakeProducer = null;
+        yield value;
+        continue;
+      }
+      if (this.error !== undefined) throw this.error;
+      if (this.finished) return;
+      await this.waitForWakeup('consumer');
+    }
+  }
+
+  /** Waits for a queue transition while respecting cancellation. */
+  private waitForWakeup(type: 'producer' | 'consumer', signal?: AbortSignal): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const abort = (): void => reject(signal?.reason || new DOMException('Aborted', 'AbortError'));
+      const wakeup = (): void => {
+        signal?.removeEventListener('abort', abort);
+        resolve();
+      };
+      if (type === 'producer') this.wakeProducer = wakeup;
+      else this.wakeConsumer = wakeup;
+      if (signal?.aborted) abort();
+      else signal?.addEventListener('abort', abort, {once: true});
+    });
+  }
+}
+
+/** Validates and normalizes scan concurrency. */
+function normalizeScanConcurrency(value: number | undefined): number {
+  const concurrency = value ?? DEFAULT_SCAN_CONCURRENCY;
+  if (!Number.isInteger(concurrency) || concurrency < 1) {
+    throw new Error(`scan concurrency must be a positive integer, received ${String(value)}`);
+  }
+  return concurrency;
+}
+
+/** Throws the caller's cancellation reason when a scan has been aborted. */
+function throwIfScanAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) throw signal.reason || new DOMException('Aborted', 'AbortError');
+}

package/src/loader-utils/lib/scan-utils/scan-fragments.ts

@@ -0,0 +1,33 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {TableScanReadOptions} from './scan-query-metadata';
+import type {ColumnarPredicate, ColumnarPredicateProperty} from './columnar-predicate';
+
+/** A catalog-independent fragment selected before format-specific decoding. */
+export type ScanFragment = Readonly<{
+  /** Stable identifier for the fragment or data file. */
+  id: string;
+  /** URI or opaque source handle used by the physical executor. */
+  uri?: string;
+  /** Partition values available for early query pruning. */
+  partitionValues?: Readonly<Record<string, unknown>>;
+  /** Approximate physical size, when supplied by the catalog. */
+  byteLength?: number | bigint;
+  /** Approximate row count, when supplied by the catalog. */
+  rowCount?: number | bigint;
+  /** Format- or catalog-specific metadata retained for explain/provenance output. */
+  metadata?: Readonly<Record<string, unknown>>;
+}>;
+
+/** Provider contract for catalog or manifest layers that select physical scan fragments. */
+export type ScanFragmentProvider<
+  PredicateT extends ColumnarPredicate<unknown, ColumnarPredicateProperty> = ColumnarPredicate<
+    unknown,
+    ColumnarPredicateProperty
+  >
+> = {
+  /** Discovers fragments without opening their data pages. */
+  getScanFragments(options?: TableScanReadOptions<PredicateT>): Promise<readonly ScanFragment[]>;
+};