@loaders.gl/parquet 4.5.3 → 5.0.0-alpha.10

package/dist/workers/parquet-worker.js

@@ -0,0 +1,27 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+import { createLoaderWorker } from '@loaders.gl/loader-utils';
+import { ParquetLoaderWithParser } from "../parquet-loader.js";
+/** Worker-local Parquet loader with a package-relative default WASM URL. */
+const ParquetWorkerLoader = {
+    ...ParquetLoaderWithParser,
+    parse(arrayBuffer, options) {
+        return ParquetLoaderWithParser.parse(arrayBuffer, addWorkerWasmUrl(options));
+    }
+};
+/** Adds the package-local WASM asset URL when the caller did not provide one. */
+function addWorkerWasmUrl(options) {
+    if (options?.parquet?.wasmUrl || typeof globalThis.location?.href !== 'string') {
+        return options;
+    }
+    return {
+        ...options,
+        parquet: {
+            ...options?.parquet,
+            wasmUrl: new URL('parquet_wasm_bg.wasm', globalThis.location.href).toString()
+        }
+    };
+}
+createLoaderWorker(ParquetWorkerLoader);
+//# sourceMappingURL=parquet-worker.js.map

package/dist/workers/parquet-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parquet-worker.js","sourceRoot":"","sources":["../../src/workers/parquet-worker.ts"],"names":[],"mappings":"AAAA,aAAa;AACb,+BAA+B;AAC/B,oCAAoC;AAEpC,OAAO,EAAC,kBAAkB,EAAC,MAAM,0BAA0B,CAAC;AAE5D,OAAO,EAAC,uBAAuB,EAAC,6BAA0B;AAE1D,4EAA4E;AAC5E,MAAM,mBAAmB,GAAG;IAC1B,GAAG,uBAAuB;IAC1B,KAAK,CAAC,WAAwB,EAAE,OAA8B;QAC5D,OAAO,uBAAuB,CAAC,KAAK,CAAC,WAAW,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/E,CAAC;CACF,CAAC;AAEF,iFAAiF;AACjF,SAAS,gBAAgB,CAAC,OAA8B;IACtD,IAAI,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,OAAO,UAAU,CAAC,QAAQ,EAAE,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC/E,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,OAAO;QACL,GAAG,OAAO;QACV,OAAO,EAAE;YACP,GAAG,OAAO,EAAE,OAAO;YACnB,OAAO,EAAE,IAAI,GAAG,CAAC,sBAAsB,EAAE,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;SAC9E;KACF,CAAC;AACJ,CAAC;AAED,kBAAkB,CAAC,mBAAmB,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loaders.gl/parquet",
-  "version": "4.5.3",
+  "version": "5.0.0-alpha.10",
   "description": "Framework-independent loader for Apache Parquet files",
   "license": "MIT",
   "type": "module",
@@ -31,13 +31,71 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
-    "./parquet-worker.js": {
-      "import": "./dist/parquet-worker.js"
+    "./unbundled": {
+      "types": "./dist/unbundled.d.ts",
+      "import": "./dist/unbundled.js"
+    },
+    "./bundled": {
+      "types": "./dist/bundled.d.ts",
+      "import": "./dist/bundled.js"
+    },
+    "./parquet-loader": {
+      "types": "./dist/parquet-loader.d.ts",
+      "import": "./dist/parquet-loader.js"
+    },
+    "./iceberg-table-source": {
+      "types": "./dist/iceberg-table-source.d.ts",
+      "import": "./dist/iceberg-table-source.js"
+    },
+    "./iceberg-types": {
+      "types": "./dist/iceberg-types.d.ts",
+      "import": "./dist/iceberg-types.js"
+    },
+    "./iceberg-rest-catalog": {
+      "types": "./dist/iceberg-rest-catalog.d.ts",
+      "import": "./dist/iceberg-rest-catalog.js"
+    },
+    "./delta-source": {
+      "types": "./dist/delta-source.d.ts",
+      "import": "./dist/delta-source.js"
+    },
+    "./delta-source-loader-types": {
+      "types": "./dist/delta-source-loader-types.d.ts",
+      "import": "./dist/delta-source-loader-types.js"
+    },
+    "./delta-types": {
+      "types": "./dist/delta-types.d.ts",
+      "import": "./dist/delta-types.js"
     },
     "./parquet-js-loader": {
       "types": "./dist/parquet-js-loader.d.ts",
       "import": "./dist/parquet-js-loader.js"
-    }
+    },
+    "./parquet-source-loader": {
+      "types": "./dist/parquet-source-loader.d.ts",
+      "import": "./dist/parquet-source-loader.js",
+      "require": "./dist/parquet-source-loader.cjs"
+    },
+    "./parquet-dataset-source": {
+      "types": "./dist/parquet-dataset-source.d.ts",
+      "import": "./dist/parquet-dataset-source.js",
+      "require": "./dist/parquet-dataset-source.cjs"
+    },
+    "./parquet-worker.js": {
+      "import": "./dist/parquet-worker.js"
+    },
+    "./parquet-worker-node.cjs": {
+      "import": "./dist/parquet-worker-node.cjs",
+      "require": "./dist/parquet-worker-node.cjs"
+    },
+    "./parquet-source-worker.js": {
+      "import": "./dist/parquet-source-worker.js"
+    },
+    "./wasm": {
+      "types": "./dist/wasm.d.ts",
+      "import": "./dist/wasm.js"
+    },
+    "./parquet_wasm_bg.wasm": "./dist/parquet_wasm_bg.wasm"
   },
   "sideEffects": false,
   "files": [
@@ -46,15 +104,15 @@
     "README.md"
   ],
   "scripts": {
-    "pre-build": "echo npm run build-worker && yarn run copy-wasm",
+    "pre-build": "npm run copy-wasm && npm run build-worker && npm run build-worker-node && npm run build-source-worker",
     "build-bundle": "ocular-bundle ./bundle.ts --output=dist/dist.min.js",
     "build-bundle-dev": "ocular-bundle ./bundle.ts --env=dev --output=dist/dist.dev.js",
-    "build-worker": "esbuild src/workers/parquet-worker.ts --outfile=dist/parquet-worker.js --bundle --minify --sourcemap --external:{util,fs,path,crypto,events} --define:__VERSION__=\\\"$npm_package_version\\\"",
-    "copy-wasm": "cp ../../node_modules/parquet-wasm/esm/parquet_wasm_bg.wasm dist/parquet_wasm_bg.wasm"
+    "copy-wasm": "cp ../../node_modules/parquet-wasm/esm/parquet_wasm_bg.wasm dist/parquet_wasm_bg.wasm",
+    "build-worker": "esbuild src/workers/parquet-worker.ts --outfile=dist/parquet-worker.js --target=esnext --platform=browser --bundle --sourcemap --inject:src/polyfills/process.ts --banner:js=var\\ global=globalThis\\; --define:__VERSION__=\\\"$npm_package_version\\\"",
+    "build-worker-node": "esbuild src/workers/parquet-worker.ts --outfile=dist/parquet-worker-node.cjs --platform=node --target=node16 --bundle --sourcemap --tree-shaking=false --define:__VERSION__=\\\"$npm_package_version\\\"",
+    "build-source-worker": "esbuild src/workers/parquet-source-worker.ts --outfile=dist/parquet-source-worker.js --target=esnext --platform=browser --bundle --sourcemap --inject:src/polyfills/process.ts --banner:js=var\\ global=globalThis\\; --define:__VERSION__=\\\"$npm_package_version\\\""
   },
   "browser": {
-    "./dist/polyfills/buffer/buffer-polyfill.node.js": "./dist/polyfills/buffer/buffer-polyfill.browser.js",
-    "./src/polyfills/buffer/buffer-polyfill.node.ts": "./src/polyfills/buffer/buffer-polyfill.browser.ts",
     "child_process": false,
     "events": false,
     "fs": false,
@@ -63,43 +121,29 @@
     "tls": false,
     "util": false
   },
-  "comments": [
-    "base64-js and ieee754 are used by buffer polyfill"
-  ],
   "dependencies": {
-    "@loaders.gl/arrow": "4.5.3",
-    "@loaders.gl/bson": "4.5.3",
-    "@loaders.gl/compression": "4.5.3",
-    "@loaders.gl/geoarrow": "4.5.3",
-    "@loaders.gl/gis": "4.5.3",
-    "@loaders.gl/loader-utils": "4.5.3",
-    "@loaders.gl/schema": "4.5.3",
-    "@loaders.gl/wkt": "4.5.3",
+    "@loaders.gl/arrow": "5.0.0-alpha.10",
+    "@loaders.gl/avro": "5.0.0-alpha.10",
+    "@loaders.gl/bson": "5.0.0-alpha.10",
+    "@loaders.gl/compression": "5.0.0-alpha.10",
+    "@loaders.gl/geoarrow": "5.0.0-alpha.10",
+    "@loaders.gl/gis": "5.0.0-alpha.10",
+    "@loaders.gl/loader-utils": "5.0.0-alpha.10",
+    "@loaders.gl/schema": "5.0.0-alpha.10",
+    "@loaders.gl/schema-utils": "5.0.0-alpha.10",
+    "@loaders.gl/wkt": "5.0.0-alpha.10",
     "@probe.gl/log": "^4.1.1",
-    "async-mutex": "^0.2.2",
-    "base64-js": "^1.3.1",
-    "brotli": "^1.3.2",
-    "ieee754": "^1.2.1",
-    "int53": "^0.2.4",
-    "isomorphic-ws": "^5.0.0",
-    "lz4js": "^0.2.0",
-    "node-int64": "^0.4.0",
-    "object-stream": "0.0.1",
-    "parquet-wasm": "^0.6.1",
-    "snappyjs": "^0.6.0",
-    "thrift": "^0.19.0",
-    "util": "^0.12.5",
-    "varint": "^6.0.0",
-    "zstd-codec": "^0.1"
+    "parquet-wasm": "0.7.2"
   },
   "devDependencies": {
-    "@types/node-int64": "^0.4.29",
-    "@types/thrift": "^0.10.8",
-    "@types/varint": "^5.0.0"
+    "brotli": "^1.3.2",
+    "hyparquet": "1.29.0",
+    "hyparquet-compressors": "1.1.1",
+    "zstd-codec": "^0.1"
   },
   "peerDependencies": {
-    "@loaders.gl/core": "~4.5.0",
+    "@loaders.gl/core": "~5.0.0-alpha.0",
     "apache-arrow": ">= 17.0.0"
   },
-  "gitHead": "3ad4ab002b4a53ac5d88feb856117a8a1e8c5bb0"
+  "gitHead": "7cbfaef633e86356c946541dab4977b522745b6c"
 }

package/src/bundled.ts

@@ -0,0 +1,43 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export type {ParquetLoaderOptions} from './parquet-loader-types';
+export type {GeoParquetLoaderOptions} from './geoparquet-loader';
+export {ParquetLoaderWithParser as ParquetLoader} from './parquet-loader';
+export {GeoParquetLoaderWithParser as GeoParquetLoader} from './geoparquet-loader-with-parser';
+export {ParquetJSLoaderWithParser as ParquetJSLoader} from './parquet-js-loader';
+export {
+  ParquetSourceLoader,
+  ParquetSource,
+  type ParquetDeferredPageFilter,
+  type ParquetEncodedColumnChunk,
+  type ParquetEncodedPage,
+  type ParquetEncodedPageBatch,
+  type ParquetEncodedPageReadOptions,
+  type ParquetEncodedPageSection,
+  type ParquetPageCompressionState,
+  type ParquetSourceLoaderOptions,
+  type ParquetSourceReadOptions,
+  type ParquetSourceMetadata,
+  type ParquetRowGroupMetadata,
+  type ParquetSortingColumn,
+  type ParquetColumnChunkMetadata,
+  type ParquetGeospatialBoundingBox,
+  type ParquetGeospatialStatistics,
+  type ParquetBatchMetadata,
+  type ParquetSourceBatch
+} from './parquet-source-loader';
+export {
+  ParquetDatasetSource,
+  type ParquetDatasetBatch,
+  type ParquetDatasetFile,
+  type ParquetDatasetFileProvider,
+  type ParquetDatasetReadOptions,
+  type ParquetDatasetSourceOptions,
+  type ParquetDatasetTelemetry
+} from './parquet-dataset-source';
+export {
+  PARQUET_SOURCE_CAPABILITIES,
+  type ParquetSourceCapabilities
+} from './parquet-source-capabilities';

package/src/delta-format.ts

@@ -0,0 +1,12 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Metadata describing the Delta Lake transaction-log format. */
+export const DeltaFormat = {
+  name: 'Delta Lake',
+  id: 'delta',
+  module: 'parquet',
+  extensions: ['json', 'checkpoint.parquet'],
+  mimeTypes: ['application/json']
+};

package/src/delta-source-loader-types.ts

@@ -0,0 +1,40 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {SourceLoader} from '@loaders.gl/loader-utils';
+import {DeltaFormat} from './delta-format';
+import type {DeltaSourceOptions} from './delta-types';
+import type {DeltaTableSource} from './delta-source';
+
+// __VERSION__ is injected by babel-plugin-version-inline
+// @ts-ignore TS2304: Cannot find name '__VERSION__'.
+const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
+
+/** Metadata-only Delta source loader options. */
+export type DeltaSourceLoaderOptions = DeltaSourceOptions;
+
+/** Loads the parser-bearing Delta source implementation on demand. */
+async function preloadDeltaSourceLoader(): Promise<SourceLoader<DeltaTableSource>> {
+  const {DeltaSourceLoaderWithParser} = await import('@loaders.gl/parquet/delta-source');
+  return DeltaSourceLoaderWithParser;
+}
+
+/** Metadata-only Delta source loader; runtime code is available through `preload()`. */
+export const DeltaSourceLoader = {
+  ...DeltaFormat,
+  dataType: null as unknown as DeltaTableSource,
+  batchType: null as never,
+  name: 'DeltaSourceLoader',
+  version: VERSION,
+  type: 'delta',
+  fromUrl: true,
+  fromBlob: true,
+  options: {},
+  defaultOptions: {},
+  testURL: (url: string): boolean =>
+    /\/_delta_log\/(?:\d{20}\.json|_last_checkpoint)(?:$|[?#])/i.test(url),
+  preload: preloadDeltaSourceLoader
+} as const satisfies Omit<SourceLoader<DeltaTableSource>, 'createDataSource'> & {
+  preload: () => Promise<SourceLoader<DeltaTableSource>>;
+};

package/src/delta-source.ts

@@ -0,0 +1,305 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {
+  ScanFragment,
+  ScanFragmentProvider,
+  ScanQueryMetadata,
+  ScanQueryMetadataOptions,
+  TableScanSource,
+  SourceLoader
+} from '@loaders.gl/loader-utils';
+import {createScanQueryMetadata, DataSource} from '@loaders.gl/loader-utils';
+import {ParquetDatasetSource} from './parquet-dataset-source';
+import {PARQUET_TABLE_QUERY_CAPABILITIES} from './parquet-source-capabilities';
+import type {DeltaAction, DeltaScanOptions, DeltaSourceOptions} from './delta-types';
+import type {
+  ParquetDatasetBatch,
+  ParquetDatasetExplain,
+  ParquetPredicate
+} from './parquet-source-types';
+import {DeltaFormat} from './delta-format';
+
+// __VERSION__ is injected by babel-plugin-version-inline
+// @ts-ignore TS2304: Cannot find name '__VERSION__'.
+const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
+
+/** Lightweight Delta Lake snapshot source backed by a newline-delimited commit log. */
+export class DeltaTableSource
+  extends DataSource<string | Blob, DeltaSourceOptions>
+  implements
+    TableScanSource<ParquetDatasetBatch, ParquetPredicate>,
+    ScanFragmentProvider<ParquetPredicate>
+{
+  private readonly actionsPromises = new Map<string, Promise<readonly DeltaAction[]>>();
+
+  /** Creates a source from a Delta commit JSON URL or Blob. */
+  constructor(data: string | Blob, options: DeltaSourceOptions = {}) {
+    super(data, options);
+  }
+
+  /** Discovers the active Parquet files represented by the commit log. */
+  async getScanFragments(options: DeltaScanOptions = {}): Promise<readonly ScanFragment[]> {
+    const actions = await this.getActions(options.version, options.signal);
+    const activeFiles = selectActiveDeltaFiles(actions);
+    return Object.freeze(
+      activeFiles.map(file =>
+        Object.freeze({
+          id: file.path,
+          uri: this.resolveDataFile(file.path),
+          partitionValues: file.partitionValues,
+          byteLength: file.size,
+          rowCount: getDeltaRecordCount(file.stats),
+          metadata: {stats: file.stats}
+        })
+      )
+    );
+  }
+
+  /** Discovers schema and snapshot statistics without decoding all rows. */
+  async getQueryMetadata(options: ScanQueryMetadataOptions = {}): Promise<ScanQueryMetadata> {
+    const fragments = await this.getScanFragments(options);
+    if (!fragments.length) {
+      throw new Error('Delta snapshot contains no active Parquet files');
+    }
+    const dataset = this.createDataset(fragments);
+    const schema = await dataset.getSchema({signal: options.signal});
+    return createScanQueryMetadata({
+      sourceType: 'delta',
+      queryType: 'table',
+      execution: {status: 'supported', method: 'read'},
+      name: this.data instanceof Blob ? undefined : this.data,
+      schema,
+      capabilities: {table: PARQUET_TABLE_QUERY_CAPABILITIES},
+      statistics: {
+        rowCount: fragments.reduce((total, fragment) => total + Number(fragment.rowCount || 0), 0),
+        byteLength: fragments.reduce(
+          (total, fragment) => total + Number(fragment.byteLength || 0),
+          0
+        )
+      }
+    });
+  }
+
+  /** Explains the Delta snapshot and delegated Parquet physical plans. */
+  async getScanPlan(options: DeltaScanOptions = {}): Promise<ParquetDatasetExplain> {
+    return this.createDataset(await this.getScanFragments(options)).getScanPlan(options);
+  }
+
+  /** Reads the active snapshot through the shared Parquet dataset executor. */
+  read(options: DeltaScanOptions = {}): AsyncIterable<ParquetDatasetBatch> {
+    return this.createDatasetFromOptions(options).read(options);
+  }
+
+  /** Alias for `read()` used by scan-aware consumers. */
+  scan(options: DeltaScanOptions = {}): AsyncIterable<ParquetDatasetBatch> {
+    return this.read(options);
+  }
+
+  private async getActions(
+    requestedVersion?: number,
+    signal?: AbortSignal
+  ): Promise<readonly DeltaAction[]> {
+    const version = this.getSnapshotVersion(requestedVersion);
+    const cacheKey = version === undefined ? 'single-commit' : String(version);
+    let actionsPromise = this.actionsPromises.get(cacheKey);
+    if (!actionsPromise) {
+      actionsPromise = this.loadActions(version, signal);
+      this.actionsPromises.set(cacheKey, actionsPromise);
+    }
+    return actionsPromise;
+  }
+
+  /** Returns the configured or URL-derived snapshot version, when available. */
+  private getSnapshotVersion(version?: number): number | undefined {
+    const selectedVersion = version ?? this.options.delta?.version;
+    if (selectedVersion !== undefined) {
+      if (!Number.isSafeInteger(selectedVersion) || selectedVersion < 0) {
+        throw new Error('Delta snapshot version must be a non-negative safe integer');
+      }
+      return selectedVersion;
+    }
+    if (typeof this.data !== 'string') return undefined;
+    const match = /\/_delta_log\/(\d{20})\.json(?:$|[?#])/i.exec(this.data);
+    return match ? Number(match[1]) : undefined;
+  }
+
+  /** Reads one commit log or replays all commits through the requested version. */
+  private async loadActions(
+    version: number | undefined,
+    signal?: AbortSignal
+  ): Promise<readonly DeltaAction[]> {
+    if (typeof this.data !== 'string' || version === undefined) {
+      const text =
+        typeof this.data === 'string'
+          ? await this.readResponse(
+              await this.fetch(this.url, {
+                headers: this.options.delta?.headers,
+                signal
+              })
+            )
+          : await this.data.text();
+      const actions = parseDeltaActions(text);
+      validateDeltaActions(actions);
+      return actions;
+    }
+
+    const tableRoot = this.data.replace(/\/_delta_log\/[^/?#]+(?:[?#].*)?$/i, '');
+    const actions: DeltaAction[] = [];
+    for (let currentVersion = 0; currentVersion <= version; currentVersion++) {
+      const commitURL = `${tableRoot}/_delta_log/${String(currentVersion).padStart(20, '0')}.json`;
+      const text = await this.readResponse(
+        await this.fetch(commitURL, {
+          headers: this.options.delta?.headers,
+          signal
+        })
+      );
+      actions.push(...parseDeltaActions(text));
+    }
+    const replayedActions = Object.freeze(actions);
+    validateDeltaActions(replayedActions);
+    return replayedActions;
+  }
+
+  private async readResponse(response: Response): Promise<string> {
+    if (!response.ok)
+      throw new Error(`Delta commit log request failed with status ${response.status}`);
+    return response.text();
+  }
+
+  private createDataset(fragments: readonly ScanFragment[]): ParquetDatasetSource {
+    return new ParquetDatasetSource(
+      fragments.map(fragment => ({
+        data: fragment.uri!,
+        id: fragment.id,
+        partitions: fragment.partitionValues as never,
+        metadata: fragment.metadata
+      })),
+      this.options
+    );
+  }
+
+  private createDatasetFromOptions(options: DeltaScanOptions): ParquetDatasetSource {
+    return new ParquetDatasetSource(
+      () =>
+        this.getScanFragments(options).then(fragments =>
+          fragments.map(fragment => ({
+            data: fragment.uri!,
+            id: fragment.id,
+            partitions: fragment.partitionValues as never
+          }))
+        ),
+      this.options
+    );
+  }
+
+  private resolveDataFile(path: string): string {
+    if (this.options.delta?.baseUrl) return new URL(path, this.options.delta.baseUrl).toString();
+    if (typeof this.data === 'string') {
+      const tableRoot = this.data.replace(/\/_delta_log\/[^/]*$/i, '/');
+      return new URL(path, tableRoot).toString();
+    }
+    return path;
+  }
+}
+
+/** Parser-bearing Delta source loader exposed through the explicit source subpath. */
+export const DeltaSourceLoaderWithParser = {
+  ...DeltaFormat,
+  dataType: null as unknown as DeltaTableSource,
+  batchType: null as never,
+  name: 'DeltaSourceLoader',
+  version: VERSION,
+  type: 'delta',
+  fromUrl: true,
+  fromBlob: true,
+  options: {},
+  defaultOptions: {},
+  testURL: (url: string): boolean =>
+    /\/_delta_log\/(?:\d{20}\.json|_last_checkpoint)(?:$|[?#])/i.test(url),
+  createDataSource: (data: string | Blob, options: DeltaSourceOptions = {}): DeltaTableSource =>
+    new DeltaTableSource(data, options)
+} as const satisfies SourceLoader<DeltaTableSource>;
+
+/** Extracts Delta's optional `numRecords` statistic from an add action. */
+function getDeltaRecordCount(
+  stats: string | Readonly<Record<string, unknown>> | undefined
+): number | undefined {
+  const parsed = typeof stats === 'string' ? parseDeltaStats(stats) : stats;
+  const value = parsed?.numRecords;
+  return typeof value === 'number' && Number.isSafeInteger(value) ? value : undefined;
+}
+
+function parseDeltaStats(stats: string): Readonly<Record<string, unknown>> | undefined {
+  try {
+    const value: unknown = JSON.parse(stats);
+    return value && typeof value === 'object'
+      ? (value as Readonly<Record<string, unknown>>)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function selectActiveDeltaFiles(
+  actions: readonly DeltaAction[]
+): Array<NonNullable<DeltaAction['add']>> {
+  const files = new Map<string, NonNullable<DeltaAction['add']>>();
+  for (const action of actions) {
+    if (action.add) {
+      files.set(action.add.path, action.add);
+    }
+    if (action.remove) files.delete(action.remove.path);
+  }
+  const activeFiles = [...files.values()];
+  const deletionVectorFile = activeFiles.find(file => file.deletionVector !== undefined);
+  if (deletionVectorFile) {
+    throw new Error(
+      `Delta deletion vectors are not supported for active file ${deletionVectorFile.path}`
+    );
+  }
+  return activeFiles;
+}
+
+/** Parses a newline-delimited Delta commit into typed actions. */
+function parseDeltaActions(text: string): readonly DeltaAction[] {
+  return Object.freeze(
+    text
+      .split(/\r?\n/)
+      .filter(line => line.trim().length > 0)
+      .map(line => JSON.parse(line) as DeltaAction)
+  );
+}
+
+/** Rejects Delta protocol features that this Parquet snapshot adapter cannot interpret safely. */
+function validateDeltaActions(actions: readonly DeltaAction[]): void {
+  for (const action of actions) {
+    const protocol = action.protocol;
+    if (protocol) {
+      if (
+        protocol.minReaderVersion !== undefined &&
+        (!Number.isSafeInteger(protocol.minReaderVersion) || protocol.minReaderVersion < 1)
+      ) {
+        throw new Error('Delta protocol has an invalid minReaderVersion');
+      }
+      if ((protocol.minReaderVersion ?? 1) > 1) {
+        throw new Error(
+          `Delta reader protocol ${protocol.minReaderVersion} is not supported by this source`
+        );
+      }
+      if (protocol.readerFeatures?.length) {
+        throw new Error(
+          `Delta reader features are not supported: ${protocol.readerFeatures.join(', ')}`
+        );
+      }
+    }
+
+    const columnMappingMode = action.metaData?.configuration?.['delta.columnMapping.mode'];
+    if (columnMappingMode && columnMappingMode !== 'none') {
+      throw new Error(
+        `Delta column mapping mode "${columnMappingMode}" is not supported by this source`
+      );
+    }
+  }
+}

package/src/delta-types.ts

@@ -0,0 +1,40 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ParquetDatasetSourceOptions, ParquetDatasetReadOptions} from './parquet-source-types';
+
+/** One Delta Lake transaction action from a commit log or checkpoint projection. */
+export type DeltaAction = Readonly<{
+  protocol?: Readonly<{
+    minReaderVersion?: number;
+    readerFeatures?: readonly string[];
+  }>;
+  metaData?: Readonly<{
+    configuration?: Readonly<Record<string, string | null>>;
+  }>;
+  add?: Readonly<{
+    path: string;
+    size?: number;
+    partitionValues?: Readonly<Record<string, string | null>>;
+    stats?: string | Readonly<Record<string, unknown>>;
+    /** Delta deletion-vector descriptor, which is not decoded by this source. */
+    deletionVector?: unknown;
+  }>;
+  remove?: Readonly<{path: string}>;
+}>;
+
+/** Options for reading a Delta snapshot from its newline-delimited commit log. */
+export type DeltaSourceOptions = ParquetDatasetSourceOptions & {
+  delta?: {
+    /** Snapshot version to replay when the source is a commit-log URL. */
+    version?: number;
+    /** Table root used to resolve relative Parquet add-file paths. */
+    baseUrl?: string;
+    /** Headers sent while reading commit-log files. */
+    headers?: HeadersInit;
+  };
+};
+
+/** Query options accepted by a Delta snapshot scan. */
+export type DeltaScanOptions = ParquetDatasetReadOptions & {version?: number};