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

package/src/parquet-encoded-page-types.ts

@@ -0,0 +1,122 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {
+  ParquetBoundingBox,
+  ParquetPredicate,
+  ParquetRowGroupMetadata
+} from './parquet-source-types';
+
+/** Byte range within an encoded Parquet page body. */
+export type ParquetEncodedPageSection = Readonly<{
+  /** Byte offset relative to {@link ParquetEncodedPage.data}. */
+  byteOffset: number;
+  /** Number of bytes in this section. */
+  byteLength: number;
+}>;
+
+/** Whether the page value payload still uses the column chunk's compression codec. */
+export type ParquetPageCompressionState = 'compressed' | 'decompressed';
+
+/** Encoded Parquet page body suitable for deferred CPU or GPU decoding. */
+export type ParquetEncodedPage = Readonly<{
+  /** Page role and data-page version. */
+  type: 'dictionary' | 'data-v1' | 'data-v2';
+  /** Zero-based data-page ordinal within the column chunk; dictionaries use `-1`. */
+  pageOrdinal: number;
+  /** Value encoding declared by the page header. */
+  encoding: string;
+  /** Repetition-level encoding for V1 pages. V2 levels always use RLE. */
+  repetitionLevelEncoding?: string;
+  /** Definition-level encoding for V1 pages. V2 levels always use RLE. */
+  definitionLevelEncoding?: string;
+  /** Compression codec declared by the containing column chunk. */
+  compression: string;
+  /** Whether the page value payload remains compressed. */
+  compressionState: ParquetPageCompressionState;
+  /** Number of encoded values declared by the page header. */
+  valueCount: number;
+  /** Number of non-null values when the page header reports it directly. */
+  nonNullValueCount?: number;
+  /** Encoded page body without its Thrift page header. */
+  data: Uint8Array;
+  /** Repetition-level bytes, when their range can be known without decoding values. */
+  repetitionLevels?: ParquetEncodedPageSection;
+  /** Definition-level bytes, when their range can be known without decoding values. */
+  definitionLevels?: ParquetEncodedPageSection;
+  /** Value or dictionary bytes, when their range can be known before deferred decoding. */
+  values?: ParquetEncodedPageSection;
+  /** Compressed body byte length reported by the page header. */
+  compressedByteLength: number;
+  /** Uncompressed body byte length reported by the page header. */
+  uncompressedByteLength: number;
+}>;
+
+/** One projected Parquet leaf column whose encoded pages have not been value-decoded. */
+export type ParquetEncodedColumnChunk = Readonly<{
+  /** Nested Parquet schema path. */
+  path: readonly string[];
+  /** Physical Parquet scalar type. */
+  physicalType: string;
+  /** Fixed byte width for FIXED_LEN_BYTE_ARRAY columns. */
+  typeLength?: number;
+  /** Maximum repetition level for this leaf column. */
+  maxRepetitionLevel: number;
+  /** Maximum definition level for this leaf column. */
+  maxDefinitionLevel: number;
+  /** Compression codec declared by the column chunk. */
+  compression: string;
+  /** Number of encoded values declared by the column chunk. */
+  valueCount: number;
+  /** Optional dictionary page associated only with this column chunk. */
+  dictionary?: ParquetEncodedPage;
+  /** Ordered data pages in this column chunk. */
+  pages: readonly ParquetEncodedPage[];
+}>;
+
+/** Exact filters a deferred decoder must apply after conservative metadata pruning. */
+export type ParquetDeferredPageFilter = Readonly<{
+  /** Exact scalar predicate requested by the caller. */
+  predicate?: ParquetPredicate;
+  /** Exact spatial extent requested by the caller. */
+  bbox?: ParquetBoundingBox;
+  /** Geometry column associated with `bbox`. */
+  geometryColumn?: string;
+}>;
+
+/** Candidate encoded pages returned for one Parquet row group. */
+export type ParquetEncodedPageBatch = Readonly<{
+  /** Stable discriminator for transport-neutral deferred Parquet pages. */
+  shape: 'parquet-encoded-pages';
+  /** Normalized row-group metadata. */
+  rowGroup: ParquetRowGroupMetadata;
+  /** Columns explicitly requested for final output. Empty means all columns. */
+  projectedColumns: readonly string[];
+  /** Hidden columns included so a deferred decoder can evaluate residual filters. */
+  filterColumns: readonly string[];
+  /** Ordered selected column chunks. Each chunk retains its complete nested schema path. */
+  columns: readonly ParquetEncodedColumnChunk[];
+  /** Exact work left after loaders.gl's conservative statistics and Bloom-filter pruning. */
+  residualFilter?: ParquetDeferredPageFilter;
+}>;
+
+/** Options for reading encoded Parquet pages without materializing values or Arrow arrays. */
+export type ParquetEncodedPageReadOptions = Readonly<{
+  /** Zero-based row-group indexes to inspect, in output order. Defaults to all row groups. */
+  rowGroups?: readonly number[];
+  /** Top-level output columns. Defaults to all columns. */
+  columns?: readonly string[];
+  /** Retains candidate row groups for which the callback returns true. */
+  rowGroupFilter?: (rowGroup: ParquetRowGroupMetadata) => boolean;
+  /** Exact predicate used for conservative pruning and returned as residual work. */
+  predicate?: ParquetPredicate;
+  /** Spatial extent used for conservative pruning and returned as residual work. */
+  bbox?: ParquetBoundingBox;
+  /** Geometry column associated with `bbox`; defaults to the GeoParquet primary column. */
+  geometryColumn?: string;
+  /** Compression codecs to preserve for a downstream decoder instead of inflating on the CPU. */
+  preserveCompression?: readonly string[];
+  /** Abort this page read and its outstanding range requests. */
+  signal?: AbortSignal;
+}>;

package/src/parquet-format.ts

@@ -7,6 +7,8 @@ import type {Format} from '@loaders.gl/loader-utils';
 export const ParquetFormat = {
   name: 'Apache Parquet',
   category: 'table',
+  encoding: 'parquet',
+  format: 'parquet',
   extensions: ['parquet'],
   mimeTypes: ['application/octet-stream'],
   binary: true,

package/src/parquet-js-loader-types.ts

@@ -0,0 +1,53 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Loader} from '@loaders.gl/loader-utils';
+import type {
+  ArrowTable,
+  ArrowTableBatch,
+  ObjectRowTable,
+  ObjectRowTableBatch
+} from '@loaders.gl/schema';
+
+import {ParquetFormat} from './parquet-format';
+import type {ParquetJSLoaderOptions} from './parquet-loader-options';
+
+// __VERSION__ is injected by babel-plugin-version-inline
+// @ts-ignore TS2304: Cannot find name '__VERSION__'.
+const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
+
+/** Default option bag for the experimental TypeScript-backed Parquet loader. */
+const DEFAULT_PARQUET_JS_OPTIONS = {
+  columns: undefined,
+  preserveBinary: false,
+  verifyFooterSignature: true,
+  shape: 'arrow-table' as const
+};
+
+/** Preloads the parser-bearing TypeScript Parquet loader implementation. */
+async function preloadParquetJSLoader() {
+  const {ParquetJSLoaderWithParser} = await import('@loaders.gl/parquet/parquet-js-loader');
+  return ParquetJSLoaderWithParser;
+}
+
+/** Metadata-only Parquet loader backed by the experimental TypeScript implementation. */
+export const ParquetJSLoader = {
+  ...ParquetFormat,
+
+  dataType: null as unknown as ObjectRowTable | ArrowTable,
+  batchType: null as unknown as ObjectRowTableBatch | ArrowTableBatch,
+
+  id: 'parquet-js',
+  module: 'parquet',
+  version: VERSION,
+  worker: false,
+  options: {
+    parquet: DEFAULT_PARQUET_JS_OPTIONS
+  },
+  preload: preloadParquetJSLoader
+} as const satisfies Loader<
+  ObjectRowTable | ArrowTable,
+  ObjectRowTableBatch | ArrowTableBatch,
+  ParquetJSLoaderOptions
+>;

package/src/parquet-js-loader.ts

@@ -2,27 +2,84 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {LoaderWithParser} from '@loaders.gl/loader-utils';
-import {BlobFile} from '@loaders.gl/loader-utils';
-import type {ObjectRowTable, ObjectRowTableBatch} from '@loaders.gl/schema';
+import type {LoaderWithParser, ReadableFile} from '@loaders.gl/loader-utils';
+import {ArrayBufferFile, concatenateArrayBuffersAsync} from '@loaders.gl/loader-utils';
+import type {
+  ArrowTable,
+  ArrowTableBatch,
+  ObjectRowTable,
+  ObjectRowTableBatch
+} from '@loaders.gl/schema';
 import {parseParquetFile, parseParquetFileInBatches} from './lib/parsers/parse-parquet-to-json';
-import {ParquetJSONWorkerLoader, type ParquetJSONLoaderOptions} from './parquet-json-loader';
+import {
+  parseParquetFileToArrowInBatchesWithJs,
+  parseParquetFileToArrowWithJs
+} from './lib/parsers/parse-parquet-to-arrow-js';
+import {normalizeParquetOptions} from './lib/utils/normalize-parquet-options';
+import {ParquetJSLoader as ParquetJSLoaderMetadata} from './parquet-js-loader-types';
+import type {ParquetJSLoaderOptions} from './parquet-loader-options';
 
-/** Options for the TypeScript-backed `ParquetJSLoader`. */
-export type ParquetJSLoaderOptions = ParquetJSONLoaderOptions;
+const {preload: _ParquetJSLoaderPreload, ...ParquetJSLoaderMetadataWithoutPreload} =
+  ParquetJSLoaderMetadata;
+
+/** Default option bag for the experimental TypeScript-backed Parquet loader. */
+const DEFAULT_PARQUET_JS_OPTIONS = {
+  columns: undefined,
+  preserveBinary: false,
+  verifyFooterSignature: true,
+  shape: 'arrow-table' as const
+};
+
+/** Parser-bearing TypeScript-only Parquet loader implementation. */
+export const ParquetJSLoaderWithParser = {
+  ...ParquetJSLoaderMetadataWithoutPreload,
+  worker: false,
+  parse(arrayBuffer: ArrayBuffer, options?: ParquetJSLoaderOptions) {
+    const parquetOptions = getParquetOptions(options);
+    const file = new ArrayBufferFile(arrayBuffer);
+    return parquetOptions.parquet?.shape === 'arrow-table'
+      ? parseParquetFileToArrowWithJs(file, parquetOptions)
+      : parseParquetFile(file, parquetOptions);
+  },
+  parseFile(file: ReadableFile, options?: ParquetJSLoaderOptions) {
+    const parquetOptions = getParquetOptions(options);
+    return parquetOptions.parquet?.shape === 'arrow-table'
+      ? parseParquetFileToArrowWithJs(file, parquetOptions)
+      : parseParquetFile(file, parquetOptions);
+  },
+  parseFileInBatches(file: ReadableFile, options?: ParquetJSLoaderOptions) {
+    const parquetOptions = getParquetOptions(options);
+    return parquetOptions.parquet?.shape === 'arrow-table'
+      ? parseParquetFileToArrowInBatchesWithJs(file, parquetOptions)
+      : parseParquetFileInBatches(file, parquetOptions);
+  },
+  async *parseInBatches(
+    asyncIterator:
+      | AsyncIterable<ArrayBufferLike | ArrayBufferView>
+      | Iterable<ArrayBufferLike | ArrayBufferView>,
+    options?: ParquetJSLoaderOptions,
+    _context?: unknown
+  ) {
+    const arrayBuffer = await concatenateArrayBuffersAsync(asyncIterator);
+    const parquetOptions = getParquetOptions(options);
+    const file = new ArrayBufferFile(arrayBuffer);
+    if (parquetOptions.parquet?.shape === 'arrow-table') {
+      yield* parseParquetFileToArrowInBatchesWithJs(file, parquetOptions);
+    } else {
+      yield* parseParquetFileInBatches(file, parquetOptions);
+    }
+  }
+} as const satisfies LoaderWithParser<
+  ObjectRowTable | ArrowTable,
+  ObjectRowTableBatch | ArrowTableBatch,
+  ParquetJSLoaderOptions
+>;
 
 /**
- * Parser-bearing Parquet loader that uses the built-in TypeScript decoder.
- *
- * This opt-in loader preserves the existing Parquet JSON-loader output while making the
- * TypeScript backend explicit. The legacy `ParquetLoader` alias remains unchanged.
+ * Normalizes caller options for the TypeScript-backed Parquet loader.
+ * @param options caller-supplied loader options
+ * @returns normalized options with TypeScript defaults applied
  */
-export const ParquetJSLoader = {
-  ...ParquetJSONWorkerLoader,
-  id: 'parquet-js',
-  worker: false,
-  parse: (arrayBuffer: ArrayBuffer, options?: ParquetJSLoaderOptions) =>
-    parseParquetFile(new BlobFile(arrayBuffer), options),
-  parseFile: parseParquetFile,
-  parseFileInBatches: parseParquetFileInBatches
-} as const satisfies LoaderWithParser<ObjectRowTable, ObjectRowTableBatch, ParquetJSLoaderOptions>;
+function getParquetOptions(options?: ParquetJSLoaderOptions): ParquetJSLoaderOptions {
+  return normalizeParquetOptions(options, DEFAULT_PARQUET_JS_OPTIONS);
+}

package/src/parquet-js-writer.ts

@@ -0,0 +1,98 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {WriterOptions, WriterWithEncoder} from '@loaders.gl/loader-utils';
+import type {ObjectRowTable, Table, TableBatch} from '@loaders.gl/schema';
+import {convertTable, deduceTableSchema} from '@loaders.gl/schema-utils';
+
+import {normalizeParquetOptions} from './lib/utils/normalize-parquet-options';
+import {encodeTableToParquetJs} from './lib/encoders/encode-table-to-parquet-js';
+import {ParquetFormat} from './parquet-format';
+import type {ParquetSortingColumnOption} from './parquetjs/encoder/parquet-encoder';
+import type {
+  ParquetWriterEncryptionOptions,
+  ParquetWriterFooterSignatureOptions
+} from './lib/parquet-encryption';
+
+export type {ParquetSortingColumnOption} from './parquetjs/encoder/parquet-encoder';
+export type {
+  ParquetWriterEncryptionOptions,
+  ParquetWriterFooterSignatureOptions
+} from './lib/parquet-encryption';
+
+// __VERSION__ is injected by babel-plugin-version-inline
+// @ts-ignore TS2304: Cannot find name '__VERSION__'.
+const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
+
+/** Stable value encodings selectable by the TypeScript Parquet writer. */
+export type ParquetJSWriterEncoding =
+  | 'PLAIN'
+  | 'PLAIN_DICTIONARY'
+  | 'BYTE_STREAM_SPLIT'
+  | 'DELTA_BINARY_PACKED'
+  | 'DELTA_LENGTH_BYTE_ARRAY'
+  | 'DELTA_BYTE_ARRAY';
+
+/** Encoder-specific options for the experimental parquetjs writer. */
+type ParquetJSWriterEncoderOptions = {
+  /** Value encoding overrides keyed by top-level column name. */
+  columnEncodings?: Record<string, ParquetJSWriterEncoding>;
+  /** Enables dictionary pages globally when forced or size-beneficial. */
+  dictionary?: boolean | 'auto';
+  /** Dictionary policy overrides keyed by top-level column name. */
+  columnDictionaries?: Record<string, boolean | 'auto'>;
+  /** Maximum uncompressed PLAIN dictionary payload per column chunk. */
+  dictionaryPageSizeLimit?: number;
+  /** Emits Parquet split-block Bloom filters for selected columns. */
+  bloomFilter?: boolean | Record<string, boolean>;
+  /** Emits Parquet column and offset indexes for selected non-repeated columns. */
+  pageIndex?: boolean | Record<string, boolean>;
+  /** Emits CRC-32 checksums for every data and dictionary page. */
+  writePageChecksums?: boolean;
+  /** Emits optional SizeStatistics metadata for every column chunk. */
+  writeSizeStatistics?: boolean;
+  /** Emits min/max/null-count statistics for every column chunk. */
+  writeStatistics?: boolean | Record<string, boolean>;
+  /** Declares row-group sort keys using top-level or dotted nested leaf names. */
+  sortingColumns?: readonly ParquetSortingColumnOption[];
+  /** Encodes INT96 input values as epoch nanoseconds using the canonical Julian-day layout. */
+  int96AsTimestamp?: boolean;
+  /** Encrypt the footer using Parquet modular encryption. */
+  encryption?: ParquetWriterEncryptionOptions;
+  /** Authenticate a plaintext footer with a Parquet modular-encryption signature. */
+  footerSignature?: ParquetWriterFooterSignatureOptions;
+  rowGroupSize?: number;
+  pageSize?: number;
+  useDataPageV2?: boolean;
+};
+
+/** Public options for the parquetjs-backed plain-table writer. */
+export type ParquetJSWriterOptions = WriterOptions & {
+  parquet?: {
+    [Key in keyof ParquetJSWriterEncoderOptions]?: ParquetJSWriterEncoderOptions[Key];
+  };
+};
+
+/** Default option bag for the experimental parquetjs writer. */
+const DEFAULT_PARQUET_JS_OPTIONS = {};
+
+/** Plain-row Parquet writer backed by the experimental parquetjs implementation. */
+export const ParquetJSWriter = {
+  ...ParquetFormat,
+  id: 'parquet-js',
+  module: 'parquet',
+  version: VERSION,
+  options: {
+    parquet: DEFAULT_PARQUET_JS_OPTIONS
+  },
+  async encode(table: Table, options?: ParquetJSWriterOptions) {
+    const schema = table.schema || deduceTableSchema(table);
+    const objectRowTable = convertTable({...table, schema}, 'object-row-table') as ObjectRowTable;
+    return await encodeTableToParquetJs(
+      {...table, schema},
+      objectRowTable,
+      normalizeParquetOptions(options, DEFAULT_PARQUET_JS_OPTIONS)
+    );
+  }
+} as const satisfies WriterWithEncoder<Table, TableBatch, ParquetJSWriterOptions>;

package/src/parquet-loader-base.ts

@@ -0,0 +1,34 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {
+  ArrowTable,
+  ArrowTableBatch,
+  ObjectRowTable,
+  ObjectRowTableBatch
+} from '@loaders.gl/schema';
+
+import {ParquetFormat} from './parquet-format';
+import {PARQUET_LOADER_DEFAULT_OPTIONS} from './parquet-loader-options';
+
+// __VERSION__ is injected by babel-plugin-version-inline
+// @ts-ignore TS2304: Cannot find name '__VERSION__'.
+const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
+
+/** Shared Parquet loader metadata without parser preloading or worker delivery policy. */
+export const PARQUET_LOADER_BASE = {
+  ...ParquetFormat,
+
+  dataType: null as unknown as ObjectRowTable | ArrowTable,
+  batchType: null as unknown as ObjectRowTableBatch | ArrowTableBatch,
+
+  id: 'parquet',
+  module: 'parquet',
+  version: VERSION,
+  options: {
+    parquet: {
+      ...PARQUET_LOADER_DEFAULT_OPTIONS
+    }
+  }
+} as const;

package/src/parquet-loader-options.ts

@@ -0,0 +1,62 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {LoaderOptions} from '@loaders.gl/loader-utils';
+import type {ParquetKeyRetriever} from './lib/parquet-encryption';
+
+/** Shared row-level options supported by both Parquet backends. */
+type ParquetCommonLoaderOptions = {
+  /** @deprecated Use `_scan.limit` instead. */
+  limit?: number;
+  offset?: number;
+  batchSize?: number;
+  /** @deprecated Use `_scan.columns` instead for logical projection. */
+  columns?: string[];
+  preserveBinary?: boolean;
+  /** Decode legacy INT96 values as Arrow timestamp-nanosecond values. */
+  int96AsTimestamp?: boolean;
+};
+
+/** Additional options supported by the wasm-backed Parquet reader. */
+type ParquetWasmLoaderOptions = ParquetCommonLoaderOptions & {
+  rowGroups?: number[];
+  concurrency?: number;
+  /** Cancels an active worker parse by terminating its worker. */
+  signal?: AbortSignal;
+  /** Overrides the packaged Parquet worker asset URL. */
+  workerUrl?: string;
+  /** Overrides the package-local parquet-wasm binary URL. */
+  wasmUrl?: string;
+};
+
+/** Public options for the wasm-backed `ParquetLoader` and `GeoParquetLoader`. */
+export type ParquetLoaderOptions = LoaderOptions & {
+  parquet?: {
+    shape?: 'object-row-table' | 'arrow-table';
+  } & {
+    [Key in keyof ParquetWasmLoaderOptions]?: ParquetWasmLoaderOptions[Key];
+  };
+};
+
+/** Public options for the experimental parquetjs-backed `ParquetJSLoader`. */
+export type ParquetJSLoaderOptions = LoaderOptions & {
+  parquet?: {
+    shape?: 'object-row-table' | 'arrow-table';
+    /** Resolves modular-encryption keys from file and column key metadata. */
+    keyRetriever?: ParquetKeyRetriever;
+    /** AAD prefix for encrypted files that intentionally omit it from metadata. */
+    aadPrefix?: Uint8Array;
+    /** Verify plaintext-footer signatures when present. Enabled by default. */
+    verifyFooterSignature?: boolean;
+  } & {
+    [Key in keyof ParquetCommonLoaderOptions]?: ParquetCommonLoaderOptions[Key];
+  };
+};
+
+/** Shared default option bag for the wasm-backed Parquet loaders. */
+export const PARQUET_LOADER_DEFAULT_OPTIONS = {
+  columns: undefined,
+  preserveBinary: false,
+  shape: 'arrow-table'
+} as const;

package/src/parquet-loader-types.ts

@@ -0,0 +1,35 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Loader} from '@loaders.gl/loader-utils';
+import type {
+  ObjectRowTable,
+  ObjectRowTableBatch,
+  ArrowTable,
+  ArrowTableBatch
+} from '@loaders.gl/schema';
+
+import {PARQUET_LOADER_BASE} from './parquet-loader-base';
+import type {ParquetLoaderOptions as SharedParquetLoaderOptions} from './parquet-loader-options';
+import {PARQUET_WORKER_URL} from './parquet-worker-url';
+
+/** Options for the Parquet loader. */
+export type ParquetLoaderOptions = SharedParquetLoaderOptions;
+
+/** Preloads the parser-bearing WASM Parquet loader implementation. */
+async function preloadParquetLoader() {
+  const {ParquetLoaderWithParser} = await import('@loaders.gl/parquet/parquet-loader');
+  return ParquetLoaderWithParser;
+}
+
+/** Metadata-only Parquet table loader supporting object-row and Arrow table output. */
+export const ParquetLoader = {
+  ...PARQUET_LOADER_BASE,
+  worker: PARQUET_WORKER_URL,
+  preload: preloadParquetLoader
+} as const satisfies Loader<
+  ObjectRowTable | ArrowTable,
+  ObjectRowTableBatch | ArrowTableBatch,
+  ParquetLoaderOptions
+>;

package/src/parquet-loader.ts

@@ -0,0 +1,115 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {LoaderWithParser} from '@loaders.gl/loader-utils';
+import {BlobFile, concatenateArrayBuffersAsync} from '@loaders.gl/loader-utils';
+import type {
+  ObjectRowTable,
+  ObjectRowTableBatch,
+  ArrowTable,
+  ArrowTableBatch
+} from '@loaders.gl/schema';
+import type {ReadableFile} from '@loaders.gl/loader-utils';
+
+import {
+  convertArrowBatchToObjectRows,
+  convertArrowTableToObjectRows
+} from './lib/parsers/convert-parquet-tables';
+import {
+  parseParquetFileToArrow,
+  parseParquetFileToArrowInBatches
+} from './lib/parsers/parse-parquet-to-arrow';
+import {normalizeParquetOptions} from './lib/utils/normalize-parquet-options';
+import {
+  deserializeParquetWorkerResult,
+  serializeParquetWorkerResult
+} from './lib/parquet-worker-transport';
+import {ParquetLoader as ParquetLoaderMetadata} from './parquet-loader-types';
+import type {ParquetLoaderOptions} from './parquet-loader-options';
+
+export type {ParquetLoaderOptions} from './parquet-loader-options';
+
+const {preload: _ParquetLoaderPreload, ...ParquetLoaderMetadataWithoutPreload} =
+  ParquetLoaderMetadata;
+
+/** WASM-backed Parquet table loader supporting object-row and Arrow table output. */
+export const ParquetLoaderWithParser = {
+  ...ParquetLoaderMetadataWithoutPreload,
+  parse(arrayBuffer: ArrayBuffer, options?: ParquetLoaderOptions) {
+    return parseParquetTable(new BlobFile(arrayBuffer), options);
+  },
+  parseFile(file, options?: ParquetLoaderOptions) {
+    return parseParquetTable(file, options);
+  },
+  parseFileInBatches(file, options?: ParquetLoaderOptions) {
+    return parseParquetTableInBatches(file, options);
+  },
+  async *parseInBatches(
+    asyncIterator:
+      | AsyncIterable<ArrayBufferLike | ArrayBufferView>
+      | Iterable<ArrayBufferLike | ArrayBufferView>,
+    options?: ParquetLoaderOptions,
+    _context?: unknown
+  ) {
+    const arrayBuffer = await concatenateArrayBuffersAsync(asyncIterator);
+    yield* parseParquetTableInBatches(new BlobFile(arrayBuffer), options);
+  },
+  serializeWorkerResult: serializeParquetWorkerResult,
+  deserializeWorkerResult: deserializeParquetWorkerResult
+} as const satisfies LoaderWithParser<
+  ObjectRowTable | ArrowTable,
+  ObjectRowTableBatch | ArrowTableBatch,
+  ParquetLoaderOptions
+>;
+
+/**
+ * Parses a Parquet file using the canonical WASM-backed table loader.
+ * @param file readable file abstraction
+ * @param options optional loader options
+ * @returns object-row or Arrow table output depending on `parquet.shape`
+ */
+async function parseParquetTable(
+  file: BlobFile | ReadableFile,
+  options?: ParquetLoaderOptions
+): Promise<ObjectRowTable | ArrowTable> {
+  const parquetOptions = getParquetOptions(options);
+
+  if (parquetOptions.parquet?.shape === 'arrow-table') {
+    return await parseParquetFileToArrow(file, parquetOptions.parquet);
+  }
+
+  const arrowTable = await parseParquetFileToArrow(file, parquetOptions.parquet);
+  return convertArrowTableToObjectRows(arrowTable);
+}
+
+/**
+ * Parses a Parquet file into streamed table batches using the canonical WASM-backed loader.
+ * @param file readable file abstraction
+ * @param options optional loader options
+ * @returns async iterable of object-row or Arrow batches
+ */
+async function* parseParquetTableInBatches(
+  file: BlobFile | ReadableFile,
+  options?: ParquetLoaderOptions
+): AsyncIterable<ObjectRowTableBatch | ArrowTableBatch> {
+  const parquetOptions = getParquetOptions(options);
+
+  if (parquetOptions.parquet?.shape === 'arrow-table') {
+    yield* parseParquetFileToArrowInBatches(file, parquetOptions.parquet);
+    return;
+  }
+
+  for await (const batch of parseParquetFileToArrowInBatches(file, parquetOptions.parquet)) {
+    yield convertArrowBatchToObjectRows(batch);
+  }
+}
+
+/**
+ * Normalizes caller options for the canonical WASM-backed Parquet loaders.
+ * @param options caller-supplied loader options
+ * @returns normalized loader options
+ */
+export function getParquetOptions(options?: ParquetLoaderOptions): ParquetLoaderOptions {
+  return normalizeParquetOptions(options, ParquetLoaderWithParser.options.parquet);
+}