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

package/dist/parquetjs/parser/parquet-reader.js

@@ -4,11 +4,46 @@
 // Copyright (c) 2017 ironSource Ltd.
 // Forked from https://github.com/kbajalc/parquets under MIT license
 import { ParquetSchema } from "../schema/schema.js";
-import { decodeSchema, decodeDataPages, decodePage } from "./decoders.js";
+import { decodeSchema, decodeDataPages, decodePage, decodeUncompressedDataPages, decodeUncompressedDictionaryBuffer } from "./decoders.js";
+import { scanParquetEncodedPages } from "./encoded-pages.js";
 import { materializeRows } from "../schema/shred.js";
+import { createParquetPageDecompressor } from "../compression.js";
 import { PARQUET_MAGIC, PARQUET_MAGIC_ENCRYPTED } from "../../lib/constants.js";
-import { CompressionCodec, Type } from "../parquet-thrift/index.js";
-import { decodeFileMetadata, getThriftEnum, fieldIndexOf } from "../utils/read-utils.js";
+import { CompressionCodec, Encoding, PageType, Type } from "../parquet-thrift/index.js";
+import { decodeColumnMetadata, decodeFileCryptoMetadata, decodeFileMetadata, decodePageHeader, getThriftEnum, fieldIndexOf, serializeThrift } from "../utils/read-utils.js";
+import { decodeString, readUInt32LE, toUint8Array } from "../utils/binary-utils.js";
+import { CompactInt64 } from "../utils/uint8-array-compact-protocol.js";
+import { createParquetModuleAad, decryptParquetModule, readParquetEncryptedModule, verifyParquetFooterSignature } from "../../lib/parquet-encryption.js";
+/** Bounds concurrent range requests when a row group contains unusually many selected columns. */
+const MAXIMUM_CONCURRENT_COLUMN_READS = 16;
+/**
+ * Returns whether column metadata guarantees that every data page can decode directly into an
+ * Arrow-compatible byte buffer. Level encodings are included in the metadata encoding set and do
+ * not prevent the byte-array fast path.
+ */
+function hasOnlyArrowByteArrayDataPageEncodings(encodings, dictionaryPageOffset) {
+    if (dictionaryPageOffset !== undefined || encodings.length === 0) {
+        return false;
+    }
+    for (const encoding of encodings) {
+        if (encoding !== Encoding.PLAIN &&
+            encoding !== Encoding.DELTA_LENGTH_BYTE_ARRAY &&
+            encoding !== Encoding.DELTA_BYTE_ARRAY &&
+            encoding !== Encoding.RLE &&
+            encoding !== Encoding.BIT_PACKED) {
+            return false;
+        }
+    }
+    return true;
+}
+/** Returns the algorithm name represented by the Thrift encryption union. */
+function getEncryptionAlgorithm(value) {
+    if (value.AES_GCM_V1)
+        return 'AES_GCM_V1';
+    if (value.AES_GCM_CTR_V1)
+        return 'AES_GCM_CTR_V1';
+    throw new Error('Unsupported Parquet encryption algorithm');
+}
 /**
  * The parquet envelope reader allows direct, unbuffered access to the individual
  * sections of the parquet file, namely the header, footer and the row groups.
@@ -19,19 +54,118 @@ export class ParquetReader {
     static defaultProps = {
         // max ArrayBuffer size in js is 2Gb
         defaultDictionarySize: 2147483648,
-        preserveBinary: false
+        preserveBinary: false,
+        retainByteArrayViews: false,
+        useTypedValueBuffers: false,
+        useTypedLevelBuffers: false,
+        useArrowByteArrayBuffers: false,
+        verifyPageChecksums: false,
+        int96AsTimestamp: false,
+        verifyFooterSignature: true,
+        signal: undefined,
+        keyRetriever: undefined,
+        aadPrefix: undefined,
+        encryptionContext: undefined
     };
     props;
     file;
     metadata = null;
+    /** Parsed Parquet schema shared by metadata, iteration, and materialization paths. */
+    schema = null;
+    /** Encryption parameters decoded from plaintext or encrypted footer metadata. */
+    encryptionContext;
+    /** Resolved keys shared by encrypted modules in this reader instance. */
+    encryptionKeyCache = new Map();
+    /** Compression backends selected once and shared by every page in this reader. */
+    pageDecompressors = new Map();
     constructor(file, props) {
         this.file = file;
         this.props = { ...ParquetReader.defaultProps, ...props };
+        this.encryptionContext = this.props.encryptionContext;
+    }
+    /** Whether the decoded footer describes an encrypted Parquet file. */
+    get encrypted() {
+        return Boolean(this.encryptionContext);
+    }
+    /** Whether this reader decodes legacy INT96 values as epoch nanoseconds. */
+    get int96AsTimestamp() {
+        return this.props.int96AsTimestamp;
+    }
+    /** Returns a cloneable snapshot of the file encryption context for worker decoding. */
+    getEncryptionContextForWorker() {
+        const encryptionContext = this.encryptionContext;
+        if (!encryptionContext)
+            return undefined;
+        return {
+            algorithm: encryptionContext.algorithm,
+            aadPrefix: encryptionContext.aadPrefix && new Uint8Array(encryptionContext.aadPrefix),
+            fileUnique: new Uint8Array(encryptionContext.fileUnique),
+            footerKeyMetadata: encryptionContext.footerKeyMetadata && new Uint8Array(encryptionContext.footerKeyMetadata)
+        };
+    }
+    /** Resolves one column key on the caller thread before transferring encrypted ranges. */
+    async getColumnKeyForWorker(columnChunk, rowGroupOrdinal, columnOrdinal) {
+        if (!this.encryptionContext || !this.props.keyRetriever) {
+            throw new Error('Encrypted Parquet worker reads require parquet.keyRetriever');
+        }
+        const keyMetadata = this.getColumnKeyMetadata(columnChunk);
+        const keyMaterial = await this.props.keyRetriever(keyMetadata, {
+            algorithm: this.encryptionContext.algorithm,
+            aad: createParquetModuleAad(this.encryptionContext.aadPrefix, this.encryptionContext.fileUnique, 'data-page', rowGroupOrdinal, columnOrdinal, 0)
+        });
+        const keyBytes = keyMaterial instanceof ArrayBuffer
+            ? new Uint8Array(keyMaterial)
+            : new Uint8Array(keyMaterial.buffer, keyMaterial.byteOffset, keyMaterial.byteLength);
+        return { keyMetadata, keyMaterial: keyBytes };
     }
     close() {
+        this.encryptionKeyCache.clear();
+        this.pageDecompressors.clear();
         // eslint-disable-next-line @typescript-eslint/no-floating-promises
         this.file.close();
     }
+    /** Returns the reader-scoped decoder for one Parquet compression method. */
+    getPageDecompressor(compression) {
+        let decompressor = this.pageDecompressors.get(compression);
+        if (!decompressor) {
+            decompressor = createParquetPageDecompressor(compression);
+            this.pageDecompressors.set(compression, decompressor);
+        }
+        return decompressor;
+    }
+    /** Reads a byte range, retaining a zero-copy view when the complete file is already in memory. */
+    async readBytes(start, length, signal) {
+        const effectiveSignal = signal ?? this.props.signal;
+        if (effectiveSignal?.aborted) {
+            throw new Error('Request aborted');
+        }
+        if (this.file.handle instanceof ArrayBuffer) {
+            return new Uint8Array(this.file.handle, start, length);
+        }
+        return toUint8Array(await this.file.read(start, length, effectiveSignal));
+    }
+    /** Returns a reader-scoped key resolver that avoids repeating key-provider work per module. */
+    getCachedKeyRetriever() {
+        const keyRetriever = this.props.keyRetriever;
+        if (!keyRetriever) {
+            throw new Error('Encrypted Parquet requires parquet.keyRetriever');
+        }
+        return (keyMetadata, context) => {
+            const encryptionContext = this.encryptionContext;
+            const cacheKey = createEncryptionKeyCacheKey(context.algorithm, keyMetadata, context.aad, encryptionContext?.aadPrefix?.byteLength ?? this.props.aadPrefix?.byteLength, encryptionContext?.fileUnique.byteLength);
+            let keyPromise = this.encryptionKeyCache.get(cacheKey);
+            if (!keyPromise) {
+                keyPromise = Promise.resolve().then(() => keyRetriever(keyMetadata, context));
+                this.encryptionKeyCache.set(cacheKey, keyPromise);
+                void keyPromise.catch(() => {
+                    if (this.encryptionKeyCache.get(cacheKey) === keyPromise) {
+                        this.encryptionKeyCache.delete(cacheKey);
+                    }
+                });
+            }
+            return keyPromise;
+        };
+    }
     // HIGH LEVEL METHODS
     /** Yield one row at a time */
     async *rowIterator(props) {
@@ -52,25 +186,30 @@ export class ParquetReader {
     /** Iterate over the raw row groups */
     async *rowGroupIterator(props) {
         // Ensure strings are nested in arrays
-        const columnList = (props?.columnList || []).map((x) => Array.isArray(x) ? x : [x]);
-        const metadata = await this.getFileMetadata();
-        const schema = await this.getSchema();
+        const columnList = (props?.columnList || []).map(x => (Array.isArray(x) ? x : [x]));
+        const metadata = await this.getFileMetadata(props?.signal);
+        const schema = await this.getSchema(props?.signal);
         const rowGroupCount = metadata?.row_groups.length || 0;
-        for (let rowGroupIndex = 0; rowGroupIndex < rowGroupCount; rowGroupIndex++) {
-            const rowGroup = await this.readRowGroup(schema, metadata.row_groups[rowGroupIndex], columnList);
+        const rowGroupIndices = props?.rowGroups || Array.from({ length: rowGroupCount }, (_, index) => index);
+        for (const rowGroupIndex of rowGroupIndices) {
+            if (!Number.isInteger(rowGroupIndex) || rowGroupIndex < 0 || rowGroupIndex >= rowGroupCount) {
+                throw new Error(`Invalid Parquet row-group index ${rowGroupIndex}`);
+            }
+            const rowGroup = await this.readRowGroup(schema, metadata.row_groups[rowGroupIndex], columnList, props?.signal, rowGroupIndex);
             yield rowGroup;
         }
     }
-    async getRowCount() {
-        const metadata = await this.getFileMetadata();
+    async getRowCount(signal) {
+        const metadata = await this.getFileMetadata(signal);
         return Number(metadata.num_rows);
     }
-    async getSchema() {
-        const metadata = await this.getFileMetadata();
-        const root = metadata.schema[0];
-        const { schema: schemaDefinition } = decodeSchema(metadata.schema, 1, root.num_children);
-        const schema = new ParquetSchema(schemaDefinition);
-        return schema;
+    async getSchema(signal) {
+        this.schema ||= this.getFileMetadata(signal).then(metadata => {
+            const root = metadata.schema[0];
+            const { schema: schemaDefinition } = decodeSchema(metadata.schema, 1, root.num_children);
+            return new ParquetSchema(schemaDefinition);
+        });
+        return await this.schema;
     }
     /**
      * Returns the user (key/value) metadata for this file
@@ -84,106 +223,655 @@ export class ParquetReader {
         }
         return md;
     }
-    async getFileMetadata() {
+    async getFileMetadata(signal) {
         if (!this.metadata) {
-            await this.readHeader();
-            this.metadata = this.readFooter();
+            await this.readHeader(signal);
+            this.metadata = this.readFooter(signal);
         }
         return this.metadata;
     }
     // LOW LEVEL METHODS
     /** Metadata is stored in the footer */
-    async readHeader() {
-        const arrayBuffer = await this.file.read(0, PARQUET_MAGIC.length);
-        const buffer = Buffer.from(arrayBuffer);
-        const magic = buffer.toString();
+    async readHeader(signal) {
+        const magic = decodeString(await this.readBytes(0, PARQUET_MAGIC.length, signal));
         switch (magic) {
             case PARQUET_MAGIC:
                 break;
             case PARQUET_MAGIC_ENCRYPTED:
-                throw new Error('Encrypted parquet file not supported');
+                break;
             default:
                 throw new Error(`Invalid parquet file (magic=${magic})`);
         }
     }
     /** Metadata is stored in the footer */
-    async readFooter() {
+    async readFooter(signal) {
         const trailerLen = PARQUET_MAGIC.length + 4;
-        const arrayBuffer = await this.file.read(this.file.size - trailerLen, trailerLen);
-        const trailerBuf = Buffer.from(arrayBuffer);
-        const magic = trailerBuf.slice(4).toString();
+        const trailer = await this.readBytes(this.file.size - trailerLen, trailerLen, signal);
+        const magic = decodeString(trailer, 4);
+        const metadataSize = readUInt32LE(trailer, 0);
+        const metadataOffset = this.file.size - metadataSize - trailerLen;
+        if (magic === PARQUET_MAGIC_ENCRYPTED) {
+            return await this.readEncryptedFooter(metadataSize, metadataOffset, signal);
+        }
         if (magic !== PARQUET_MAGIC) {
             throw new Error(`Not a valid parquet file (magic="${magic})`);
         }
-        const metadataSize = trailerBuf.readUInt32LE(0);
-        const metadataOffset = this.file.size - metadataSize - trailerLen;
         if (metadataOffset < PARQUET_MAGIC.length) {
             throw new Error(`Invalid metadata size ${metadataOffset}`);
         }
-        const arrayBuffer2 = await this.file.read(metadataOffset, metadataSize);
-        const metadataBuf = Buffer.from(arrayBuffer2);
+        const metadataBuf = await this.readBytes(metadataOffset, metadataSize, signal);
         // let metadata = new parquet_thrift.FileMetaData();
         // parquet_util.decodeThrift(metadata, metadataBuf);
-        const { metadata } = decodeFileMetadata(metadataBuf);
+        const decoded = decodeFileMetadata(metadataBuf);
+        const { metadata } = decoded;
+        this.setEncryptionContext(metadata);
+        if (this.props.verifyFooterSignature && this.encryptionContext?.footerSigningKeyMetadata) {
+            // The compact-protocol decoder may consume bytes from the signature that
+            // happen to look like valid Thrift fields. The format defines the
+            // signature as the final fixed 28 bytes of the footer range, so use the
+            // physical boundary rather than the decoder's consumed length.
+            const signatureOffset = metadataBuf.byteLength - 28;
+            if (signatureOffset < decoded.length) {
+                throw new Error('Invalid Parquet plaintext-footer signature boundary');
+            }
+            const signature = metadataBuf.subarray(signatureOffset);
+            const encryptionContext = this.encryptionContext;
+            if (!this.props.keyRetriever) {
+                throw new Error('Signed Parquet footer requires parquet.keyRetriever');
+            }
+            await verifyParquetFooterSignature(metadataBuf.subarray(0, signatureOffset), signature, {
+                algorithm: encryptionContext.algorithm,
+                aad: createParquetModuleAad(encryptionContext.aadPrefix, encryptionContext.fileUnique, 'footer'),
+                keyMetadata: encryptionContext.footerSigningKeyMetadata,
+                keyRetriever: this.getCachedKeyRetriever()
+            });
+        }
+        return metadata;
+    }
+    /** Reads and decrypts an encrypted footer after the standard trailer. */
+    async readEncryptedFooter(metadataSize, metadataOffset, signal) {
+        if (!this.props.keyRetriever) {
+            throw new Error('Encrypted Parquet footer requires parquet.keyRetriever');
+        }
+        const encryptedFooter = await this.readBytes(metadataOffset, metadataSize, signal);
+        const cryptoMetadata = decodeFileCryptoMetadata(encryptedFooter);
+        const algorithm = getEncryptionAlgorithm(cryptoMetadata.metadata.encryption_algorithm);
+        const algorithmMetadata = cryptoMetadata.metadata.encryption_algorithm.AES_GCM_V1 ||
+            cryptoMetadata.metadata.encryption_algorithm.AES_GCM_CTR_V1;
+        const aadPrefix = algorithmMetadata?.aad_prefix || this.props.aadPrefix;
+        if (!algorithmMetadata?.aad_file_unique) {
+            throw new Error('Encrypted Parquet footer is missing aad_file_unique');
+        }
+        const aad = createParquetModuleAad(aadPrefix, algorithmMetadata.aad_file_unique, 'footer');
+        const plaintext = await decryptParquetModule(encryptedFooter.subarray(cryptoMetadata.length), {
+            algorithm,
+            aad,
+            keyMetadata: cryptoMetadata.metadata.key_metadata,
+            keyRetriever: this.getCachedKeyRetriever()
+        });
+        this.encryptionContext = {
+            algorithm,
+            aadPrefix,
+            fileUnique: algorithmMetadata.aad_file_unique,
+            footerKeyMetadata: cryptoMetadata.metadata.key_metadata
+        };
+        const metadata = decodeFileMetadata(plaintext).metadata;
+        return metadata;
+    }
+    /** Records the encryption parameters exposed by plaintext-footer files. */
+    setEncryptionContext(metadata) {
+        const encryptionAlgorithm = metadata.encryption_algorithm;
+        if (!encryptionAlgorithm)
+            return;
+        const algorithm = getEncryptionAlgorithm(encryptionAlgorithm);
+        const algorithmMetadata = encryptionAlgorithm.AES_GCM_V1 || encryptionAlgorithm.AES_GCM_CTR_V1;
+        if (!algorithmMetadata?.aad_file_unique) {
+            throw new Error('Encrypted Parquet footer is missing aad_file_unique');
+        }
+        this.encryptionContext = {
+            algorithm,
+            aadPrefix: algorithmMetadata.aad_prefix || this.props.aadPrefix,
+            fileUnique: algorithmMetadata.aad_file_unique,
+            footerSigningKeyMetadata: metadata.footer_signing_key_metadata
+        };
+    }
+    /** Resolves only the selected encrypted columns, using crypto metadata paths before decryption. */
+    async resolveColumnMetadata(rowGroup, rowGroupOrdinal, selectedColumnPaths) {
+        for (let columnOrdinal = 0; columnOrdinal < rowGroup.columns.length; columnOrdinal++) {
+            const columnChunk = rowGroup.columns[columnOrdinal];
+            const path = getColumnChunkPath(columnChunk);
+            if (selectedColumnPaths &&
+                path &&
+                !selectedColumnPaths.some(selectedPath => fieldIndexOf([Array.from(selectedPath)], path) >= 0)) {
+                continue;
+            }
+            if (columnChunk.encrypted_column_metadata && !columnChunk.meta_data) {
+                columnChunk.meta_data = await this.getColumnMetadata(columnChunk, rowGroupOrdinal, getPhysicalColumnOrdinal(columnChunk, columnOrdinal));
+            }
+        }
+    }
+    /** Decrypts one encrypted column index or offset index module for selective planning. */
+    async decryptIndexModule(bytes, module, rowGroupOrdinal, columnOrdinal, columnChunk) {
+        if (!columnChunk.crypto_metadata)
+            return bytes;
+        const encryptionContext = this.encryptionContext;
+        if (!encryptionContext || !this.props.keyRetriever) {
+            throw new Error('Encrypted Parquet indexes require parquet.keyRetriever');
+        }
+        const aad = createParquetModuleAad(encryptionContext.aadPrefix, encryptionContext.fileUnique, module, rowGroupOrdinal, columnOrdinal);
+        return await decryptParquetModule(bytes, {
+            algorithm: encryptionContext.algorithm,
+            aad,
+            keyMetadata: this.getColumnKeyMetadata(columnChunk),
+            keyRetriever: this.getCachedKeyRetriever()
+        });
+    }
+    /** Decrypts the encrypted Bloom-filter header and bitset modules for one column chunk. */
+    async decryptBloomFilter(bytes, rowGroupOrdinal, columnOrdinal, columnChunk) {
+        if (!columnChunk.crypto_metadata)
+            return bytes;
+        const encryptionContext = this.encryptionContext;
+        if (!encryptionContext || !this.props.keyRetriever) {
+            throw new Error('Encrypted Parquet Bloom filters require parquet.keyRetriever');
+        }
+        const header = readParquetEncryptedModule(bytes);
+        const bitset = readParquetEncryptedModule(bytes, header.nextOffset);
+        const keyMetadata = this.getColumnKeyMetadata(columnChunk);
+        const headerBytes = await decryptParquetModule(header.bytes, {
+            algorithm: encryptionContext.algorithm,
+            aad: createParquetModuleAad(encryptionContext.aadPrefix, encryptionContext.fileUnique, 'bloom-filter-header', rowGroupOrdinal, columnOrdinal),
+            keyMetadata,
+            keyRetriever: this.getCachedKeyRetriever()
+        });
+        const bitsetBytes = await decryptParquetModule(bitset.bytes, {
+            algorithm: encryptionContext.algorithm,
+            aad: createParquetModuleAad(encryptionContext.aadPrefix, encryptionContext.fileUnique, 'bloom-filter-bitset', rowGroupOrdinal, columnOrdinal),
+            keyMetadata,
+            keyRetriever: this.getCachedKeyRetriever()
+        });
+        const plaintext = new Uint8Array(headerBytes.byteLength + bitsetBytes.byteLength);
+        plaintext.set(headerBytes);
+        plaintext.set(bitsetBytes, headerBytes.byteLength);
+        return plaintext;
+    }
+    /** Resolves a column's plaintext metadata, decrypting column-specific metadata when present. */
+    async getColumnMetadata(columnChunk, rowGroupOrdinal, columnOrdinal) {
+        if (!columnChunk.encrypted_column_metadata) {
+            if (!columnChunk.meta_data) {
+                throw new Error('Parquet column metadata is missing');
+            }
+            return columnChunk.meta_data;
+        }
+        if (!this.props.keyRetriever) {
+            throw new Error('Encrypted Parquet column metadata requires parquet.keyRetriever');
+        }
+        const encryptionContext = this.encryptionContext;
+        if (!encryptionContext) {
+            throw new Error('Encrypted Parquet column metadata has no file encryption context');
+        }
+        const columnKey = columnChunk.crypto_metadata?.ENCRYPTION_WITH_COLUMN_KEY;
+        const usesFooterKey = Boolean(columnChunk.crypto_metadata?.ENCRYPTION_WITH_FOOTER_KEY);
+        if (!columnKey && !usesFooterKey) {
+            throw new Error('Encrypted Parquet column metadata has no key reference');
+        }
+        const aad = createParquetModuleAad(encryptionContext.aadPrefix, encryptionContext.fileUnique, 'column-metadata', rowGroupOrdinal, columnOrdinal);
+        const plaintext = await decryptParquetModule(columnChunk.encrypted_column_metadata, {
+            algorithm: encryptionContext.algorithm,
+            aad,
+            keyMetadata: columnKey?.key_metadata ??
+                encryptionContext.footerKeyMetadata ??
+                encryptionContext.footerSigningKeyMetadata,
+            keyRetriever: this.getCachedKeyRetriever()
+        });
+        const metadata = decodeColumnMetadata(plaintext).metadata;
+        if (columnKey &&
+            JSON.stringify(metadata.path_in_schema) !== JSON.stringify(columnKey.path_in_schema)) {
+            throw new Error('Encrypted Parquet column metadata path does not match crypto metadata');
+        }
         return metadata;
     }
     /** Data is stored in row groups (similar to Apache Arrow record batches) */
-    async readRowGroup(schema, rowGroup, columnList) {
-        const buffer = {
+    async readRowGroup(schema, rowGroup, columnList, signal, rowGroupOrdinal = 0) {
+        await this.resolveColumnMetadata(rowGroup, rowGroupOrdinal, columnList);
+        const selectedColumnChunks = [];
+        for (let columnOrdinal = 0; columnOrdinal < rowGroup.columns.length; columnOrdinal++) {
+            const columnChunk = rowGroup.columns[columnOrdinal];
+            const path = getColumnChunkPath(columnChunk);
+            if (columnList.length > 0 && (!path || fieldIndexOf(columnList, path) < 0)) {
+                continue;
+            }
+            const physicalColumnOrdinal = getPhysicalColumnOrdinal(columnChunk, columnOrdinal);
+            const metadata = columnChunk.meta_data ||
+                (await this.getColumnMetadata(columnChunk, rowGroupOrdinal, physicalColumnOrdinal));
+            if (columnList.length === 0 || fieldIndexOf(columnList, metadata.path_in_schema) >= 0) {
+                selectedColumnChunks.push({ columnChunk, metadata, columnOrdinal: physicalColumnOrdinal });
+            }
+        }
+        if (this.file.handle instanceof ArrayBuffer &&
+            selectedColumnChunks.every(({ columnChunk, metadata }) => (columnChunk.file_path === undefined || columnChunk.file_path === null) &&
+                !columnChunk.crypto_metadata &&
+                getThriftEnum(CompressionCodec, metadata.codec) === 'UNCOMPRESSED')) {
+            return {
+                rowCount: Number(rowGroup.num_rows),
+                columnData: Object.fromEntries(selectedColumnChunks.map(({ columnChunk, metadata }) => [
+                    metadata.path_in_schema.join(),
+                    this.readUncompressedColumnChunkFromMemory(schema, columnChunk, metadata)
+                ]))
+            };
+        }
+        const columnEntries = [];
+        for (let batchStart = 0; batchStart < selectedColumnChunks.length; batchStart += MAXIMUM_CONCURRENT_COLUMN_READS) {
+            const columnBatch = selectedColumnChunks.slice(batchStart, batchStart + MAXIMUM_CONCURRENT_COLUMN_READS);
+            columnEntries.push(...(await Promise.all(columnBatch.map(({ columnChunk, metadata, columnOrdinal }) => {
+                const columnKey = metadata.path_in_schema.join();
+                if (this.file.handle instanceof ArrayBuffer &&
+                    (columnChunk.file_path === undefined || columnChunk.file_path === null) &&
+                    !columnChunk.crypto_metadata &&
+                    getThriftEnum(CompressionCodec, metadata.codec) === 'UNCOMPRESSED') {
+                    return [
+                        columnKey,
+                        this.readUncompressedColumnChunkFromMemory(schema, columnChunk, metadata)
+                    ];
+                }
+                return this.readColumnChunk(schema, columnChunk, signal, rowGroupOrdinal, columnOrdinal, metadata).then(columnData => [columnKey, columnData]);
+            }))));
+        }
+        return {
             rowCount: Number(rowGroup.num_rows),
-            columnData: {}
+            columnData: Object.fromEntries(columnEntries)
         };
-        for (const colChunk of rowGroup.columns) {
-            const colMetadata = colChunk.meta_data;
-            const colKey = colMetadata?.path_in_schema;
-            if (columnList.length > 0 && fieldIndexOf(columnList, colKey) < 0) {
-                continue; // eslint-disable-line no-continue
+    }
+    /**
+     * Reads selected column chunks as encoded page descriptors without materializing values.
+     *
+     * Page headers, encryption, checksums, and optional decompression remain reader concerns. Value,
+     * dictionary, and level decoding is deliberately left to the downstream consumer.
+     */
+    async readRowGroupEncodedPages(schema, rowGroup, columnList, preserveCompression, signal, rowGroupOrdinal = 0) {
+        await this.resolveColumnMetadata(rowGroup, rowGroupOrdinal, columnList);
+        const selectedColumnChunks = [];
+        for (let columnOrdinal = 0; columnOrdinal < rowGroup.columns.length; columnOrdinal++) {
+            const columnChunk = rowGroup.columns[columnOrdinal];
+            const path = getColumnChunkPath(columnChunk);
+            if (columnList.length > 0 && (!path || fieldIndexOf(columnList, path) < 0))
+                continue;
+            const physicalColumnOrdinal = getPhysicalColumnOrdinal(columnChunk, columnOrdinal);
+            const metadata = columnChunk.meta_data ||
+                (await this.getColumnMetadata(columnChunk, rowGroupOrdinal, physicalColumnOrdinal));
+            if (columnList.length === 0 || fieldIndexOf(columnList, metadata.path_in_schema) >= 0) {
+                selectedColumnChunks.push({
+                    columnChunk,
+                    metadata,
+                    columnOrdinal: physicalColumnOrdinal
+                });
+            }
+        }
+        const columns = [];
+        for (let batchStart = 0; batchStart < selectedColumnChunks.length; batchStart += MAXIMUM_CONCURRENT_COLUMN_READS) {
+            columns.push(...(await Promise.all(selectedColumnChunks
+                .slice(batchStart, batchStart + MAXIMUM_CONCURRENT_COLUMN_READS)
+                .map(async ({ columnChunk, metadata, columnOrdinal }) => {
+                const encodedColumn = await this.readColumnChunkEncodedPages(schema, columnChunk, preserveCompression, signal, rowGroupOrdinal, columnOrdinal, metadata);
+                return encodedColumn;
+            }))));
+        }
+        return Object.freeze(columns);
+    }
+    /** Reads independently materializable non-repeated columns for one row range using page indexes. */
+    async readRowGroupRange(schema, rowGroup, columnList, rowRange, pageLocations, signal, rowGroupOrdinal = 0) {
+        await this.resolveColumnMetadata(rowGroup, rowGroupOrdinal, columnList);
+        const selectedColumnChunks = [];
+        for (let columnOrdinal = 0; columnOrdinal < rowGroup.columns.length; columnOrdinal++) {
+            const columnChunk = rowGroup.columns[columnOrdinal];
+            const path = getColumnChunkPath(columnChunk);
+            if (columnList.length > 0 && (!path || fieldIndexOf(columnList, path) < 0)) {
+                continue;
+            }
+            const physicalColumnOrdinal = getPhysicalColumnOrdinal(columnChunk, columnOrdinal);
+            const metadata = columnChunk.meta_data ||
+                (await this.getColumnMetadata(columnChunk, rowGroupOrdinal, physicalColumnOrdinal));
+            if (columnList.length === 0 || fieldIndexOf(columnList, metadata.path_in_schema) >= 0) {
+                selectedColumnChunks.push({ columnChunk, metadata, columnOrdinal: physicalColumnOrdinal });
+            }
+        }
+        const columnEntries = await Promise.all(selectedColumnChunks.map(async ({ columnChunk, metadata, columnOrdinal }) => {
+            const columnKey = metadata.path_in_schema.join();
+            const pages = pageLocations[JSON.stringify(metadata.path_in_schema)];
+            if (!pages) {
+                throw new Error(`Parquet offset index missing for ${columnKey}`);
             }
-            buffer.columnData[colKey.join()] = await this.readColumnChunk(schema, colChunk);
+            const columnData = await this.readColumnChunkRange(schema, columnChunk, rowRange, pages, signal, rowGroupOrdinal, columnOrdinal, metadata);
+            return [columnKey, columnData];
+        }));
+        return {
+            rowCount: rowRange.end - rowRange.start,
+            columnData: Object.fromEntries(columnEntries)
+        };
+    }
+    /**
+     * Each row group contains column chunks for all the columns.
+     */
+    readUncompressedColumnChunkFromMemory(schema, columnChunk, metadata) {
+        if (!(this.file.handle instanceof ArrayBuffer)) {
+            throw new Error('Synchronous Parquet column reads require an in-memory ArrayBuffer');
         }
-        return buffer;
+        const field = schema.findField(metadata.path_in_schema);
+        const type = getThriftEnum(Type, metadata.type);
+        if (type !== field.primitiveType) {
+            throw new Error(`chunk type not matching schema: ${type}`);
+        }
+        const pagesOffset = Number(metadata.data_page_offset);
+        const dictionaryPageOffset = metadata.dictionary_page_offset;
+        const validDictionaryPageOffset = dictionaryPageOffset !== undefined && Number(dictionaryPageOffset) > 0
+            ? Number(dictionaryPageOffset)
+            : undefined;
+        const chunkOffset = Math.min(pagesOffset, validDictionaryPageOffset ?? pagesOffset);
+        const chunkEnd = chunkOffset + Number(metadata.total_compressed_size);
+        const chunkSize = Math.min(this.file.size - chunkOffset, Math.max(0, chunkEnd - chunkOffset));
+        const chunkBuffer = new Uint8Array(this.file.handle, chunkOffset, chunkSize);
+        const pagesRelativeOffset = pagesOffset - chunkOffset;
+        const pagesSize = Math.min(chunkBuffer.length - pagesRelativeOffset, Math.max(0, chunkEnd - pagesOffset));
+        const context = {
+            type,
+            rLevelMax: field.rLevelMax,
+            dLevelMax: field.dLevelMax,
+            compression: 'UNCOMPRESSED',
+            column: field,
+            numValues: metadata.num_values,
+            dictionary: [],
+            decompressPage: this.getPageDecompressor('UNCOMPRESSED'),
+            preserveBinary: this.props.preserveBinary,
+            retainByteArrayViews: this.props.retainByteArrayViews,
+            useTypedValueBuffers: this.props.useTypedValueBuffers,
+            useTypedLevelBuffers: this.props.useTypedLevelBuffers,
+            useArrowByteArrayBuffers: this.props.useArrowByteArrayBuffers,
+            // Metadata proves whether the decoder may skip its otherwise duplicated page-header scan.
+            // Keep the scan for mixed/unknown encodings: it is both a correctness guard and fallback.
+            hasOnlyArrowByteArrayDataPages: hasOnlyArrowByteArrayDataPageEncodings(metadata.encodings, validDictionaryPageOffset),
+            verifyPageChecksums: this.props.verifyPageChecksums,
+            int96AsTimestamp: this.props.int96AsTimestamp
+        };
+        let dictionary;
+        if (validDictionaryPageOffset !== undefined) {
+            const dictionaryRelativeOffset = validDictionaryPageOffset - chunkOffset;
+            const dictionarySize = Math.min(Math.max(0, pagesOffset - validDictionaryPageOffset), chunkBuffer.length - dictionaryRelativeOffset, this.props.defaultDictionarySize);
+            dictionary = decodeUncompressedDictionaryBuffer(chunkBuffer.subarray(dictionaryRelativeOffset, dictionaryRelativeOffset + dictionarySize), context);
+        }
+        return decodeUncompressedDataPages(chunkBuffer.subarray(pagesRelativeOffset, pagesRelativeOffset + pagesSize), { ...context, dictionary });
     }
     /**
      * Each row group contains column chunks for all the columns.
      */
-    async readColumnChunk(schema, colChunk) {
+    async readColumnChunk(schema, colChunk, signal, rowGroupOrdinal = 0, columnOrdinal = 0, resolvedMetadata) {
         if (colChunk.file_path !== undefined && colChunk.file_path !== null) {
             throw new Error('external references are not supported');
         }
-        const field = schema.findField(colChunk.meta_data?.path_in_schema);
-        const type = getThriftEnum(Type, colChunk.meta_data?.type);
+        const metadata = resolvedMetadata || colChunk.meta_data;
+        if (!metadata) {
+            throw new Error('Parquet column metadata is missing');
+        }
+        const field = schema.findField(metadata.path_in_schema);
+        const type = getThriftEnum(Type, metadata.type);
         if (type !== field.primitiveType) {
             throw new Error(`chunk type not matching schema: ${type}`);
         }
-        const compression = getThriftEnum(CompressionCodec, colChunk.meta_data?.codec);
-        const pagesOffset = Number(colChunk.meta_data?.data_page_offset);
-        let pagesSize = Number(colChunk.meta_data?.total_compressed_size);
-        if (!colChunk.file_path) {
-            pagesSize = Math.min(this.file.size - pagesOffset, Number(colChunk.meta_data?.total_compressed_size));
-        }
+        const compression = getThriftEnum(CompressionCodec, metadata.codec);
+        const pagesOffset = Number(metadata.data_page_offset);
+        const dictionaryPageOffset = metadata.dictionary_page_offset;
+        const validDictionaryPageOffset = dictionaryPageOffset !== undefined && Number(dictionaryPageOffset) > 0
+            ? Number(dictionaryPageOffset)
+            : undefined;
+        const chunkOffset = Math.min(pagesOffset, validDictionaryPageOffset ?? pagesOffset);
+        const chunkEnd = chunkOffset + Number(metadata.total_compressed_size);
+        const chunkSize = Math.min(this.file.size - chunkOffset, Math.max(0, chunkEnd - chunkOffset));
+        const chunkBuffer = await this.readBytes(chunkOffset, chunkSize, signal);
+        const pagesRelativeOffset = pagesOffset - chunkOffset;
+        const pagesSize = Math.min(chunkBuffer.length - pagesRelativeOffset, Math.max(0, chunkEnd - pagesOffset));
         const context = {
             type,
             rLevelMax: field.rLevelMax,
             dLevelMax: field.dLevelMax,
             compression,
             column: field,
-            numValues: colChunk.meta_data?.num_values,
+            numValues: metadata.num_values,
             dictionary: [],
+            decompressPage: this.getPageDecompressor(compression),
             // Options - TBD is this the right place for these?
-            preserveBinary: this.props.preserveBinary
+            preserveBinary: this.props.preserveBinary,
+            retainByteArrayViews: this.props.retainByteArrayViews,
+            useTypedValueBuffers: this.props.useTypedValueBuffers,
+            useTypedLevelBuffers: this.props.useTypedLevelBuffers,
+            useArrowByteArrayBuffers: this.props.useArrowByteArrayBuffers,
+            // Avoid parsing every page header twice when trusted column metadata already establishes the
+            // direct Arrow byte-array invariant. Unknown/mixed encodings retain the defensive scan.
+            hasOnlyArrowByteArrayDataPages: hasOnlyArrowByteArrayDataPageEncodings(metadata.encodings, validDictionaryPageOffset),
+            verifyPageChecksums: this.props.verifyPageChecksums,
+            int96AsTimestamp: this.props.int96AsTimestamp
         };
         let dictionary;
-        const dictionaryPageOffset = colChunk?.meta_data?.dictionary_page_offset;
-        if (dictionaryPageOffset) {
-            const dictionaryOffset = Number(dictionaryPageOffset);
-            // Getting dictionary from column chunk to iterate all over indexes to get dataPage values.
-            dictionary = await this.getDictionary(dictionaryOffset, context, pagesOffset);
+        if (validDictionaryPageOffset !== undefined) {
+            const dictionaryRelativeOffset = validDictionaryPageOffset - chunkOffset;
+            const dictionarySize = Math.min(Math.max(0, pagesOffset - validDictionaryPageOffset), chunkBuffer.length - dictionaryRelativeOffset, this.props.defaultDictionarySize);
+            const dictionaryBuffer = chunkBuffer.subarray(dictionaryRelativeOffset, dictionaryRelativeOffset + dictionarySize);
+            const decodedDictionaryBuffer = colChunk.crypto_metadata
+                ? await this.decryptColumnPages(dictionaryBuffer, context, rowGroupOrdinal, columnOrdinal, this.getColumnKeyMetadata(colChunk), true)
+                : dictionaryBuffer;
+            dictionary = await decodeDictionaryBuffer(decodedDictionaryBuffer, context);
         }
         dictionary = context.dictionary?.length ? context.dictionary : dictionary;
-        const arrayBuffer = await this.file.read(pagesOffset, pagesSize);
-        const pagesBuf = Buffer.from(arrayBuffer);
+        const pagesBuf = colChunk.crypto_metadata
+            ? await this.decryptColumnPages(chunkBuffer.subarray(pagesRelativeOffset, pagesRelativeOffset + pagesSize), context, rowGroupOrdinal, columnOrdinal, this.getColumnKeyMetadata(colChunk))
+            : chunkBuffer.subarray(pagesRelativeOffset, pagesRelativeOffset + pagesSize);
         return await decodeDataPages(pagesBuf, { ...context, dictionary });
     }
+    /** Reads one column chunk as encoded dictionaries, levels, and values for deferred decoding. */
+    async readColumnChunkEncodedPages(schema, columnChunk, preserveCompression, signal, rowGroupOrdinal = 0, columnOrdinal = 0, resolvedMetadata) {
+        if (columnChunk.file_path !== undefined && columnChunk.file_path !== null) {
+            throw new Error('external references are not supported');
+        }
+        const metadata = resolvedMetadata || columnChunk.meta_data;
+        if (!metadata)
+            throw new Error('Parquet column metadata is missing');
+        const field = schema.findField(metadata.path_in_schema);
+        const physicalType = getThriftEnum(Type, metadata.type);
+        if (physicalType !== field.primitiveType) {
+            throw new Error(`chunk type not matching schema: ${physicalType}`);
+        }
+        const compression = getThriftEnum(CompressionCodec, metadata.codec);
+        const dataPageOffset = Number(metadata.data_page_offset);
+        const dictionaryPageOffset = metadata.dictionary_page_offset;
+        const validDictionaryPageOffset = dictionaryPageOffset !== undefined && Number(dictionaryPageOffset) > 0
+            ? Number(dictionaryPageOffset)
+            : undefined;
+        const chunkOffset = Math.min(dataPageOffset, validDictionaryPageOffset ?? dataPageOffset);
+        const chunkEnd = chunkOffset + Number(metadata.total_compressed_size);
+        const chunkByteLength = Math.min(this.file.size - chunkOffset, Math.max(0, chunkEnd - chunkOffset));
+        const chunkBuffer = await this.readBytes(chunkOffset, chunkByteLength, signal);
+        const dataPageRelativeOffset = dataPageOffset - chunkOffset;
+        const dataPageByteLength = Math.min(chunkBuffer.byteLength - dataPageRelativeOffset, Math.max(0, chunkEnd - dataPageOffset));
+        const context = {
+            column: field,
+            compression,
+            decompressPage: this.getPageDecompressor(compression),
+            preserveCompression,
+            verifyPageChecksums: this.props.verifyPageChecksums
+        };
+        let dictionary;
+        if (validDictionaryPageOffset !== undefined) {
+            const dictionaryRelativeOffset = validDictionaryPageOffset - chunkOffset;
+            const dictionaryByteLength = Math.min(Math.max(0, dataPageOffset - validDictionaryPageOffset), chunkBuffer.byteLength - dictionaryRelativeOffset, this.props.defaultDictionarySize);
+            const dictionaryBuffer = chunkBuffer.subarray(dictionaryRelativeOffset, dictionaryRelativeOffset + dictionaryByteLength);
+            const plaintextDictionaryBuffer = columnChunk.crypto_metadata
+                ? await this.decryptColumnPages(dictionaryBuffer, {
+                    type: physicalType,
+                    rLevelMax: field.rLevelMax,
+                    dLevelMax: field.dLevelMax,
+                    compression,
+                    column: field
+                }, rowGroupOrdinal, columnOrdinal, this.getColumnKeyMetadata(columnChunk), true)
+                : dictionaryBuffer;
+            dictionary = (await scanParquetEncodedPages(plaintextDictionaryBuffer, context))[0];
+        }
+        const dataPageBuffer = chunkBuffer.subarray(dataPageRelativeOffset, dataPageRelativeOffset + dataPageByteLength);
+        const plaintextDataPageBuffer = columnChunk.crypto_metadata
+            ? await this.decryptColumnPages(dataPageBuffer, {
+                type: physicalType,
+                rLevelMax: field.rLevelMax,
+                dLevelMax: field.dLevelMax,
+                compression,
+                column: field
+            }, rowGroupOrdinal, columnOrdinal, this.getColumnKeyMetadata(columnChunk))
+            : dataPageBuffer;
+        const pages = await scanParquetEncodedPages(plaintextDataPageBuffer, context);
+        return Object.freeze({
+            path: Object.freeze([...metadata.path_in_schema]),
+            physicalType,
+            typeLength: field.typeLength,
+            maxRepetitionLevel: field.rLevelMax,
+            maxDefinitionLevel: field.dLevelMax,
+            compression,
+            valueCount: Number(metadata.num_values),
+            dictionary,
+            pages: Object.freeze(pages)
+        });
+    }
+    /** Decrypts the length-prefixed page header and data modules in one column chunk. */
+    async decryptColumnPages(encryptedPages, context, rowGroupOrdinal, columnOrdinal, keyMetadata, includesDictionary = false, dataPageOrdinalStart = 0) {
+        if (!this.encryptionContext || !this.props.keyRetriever) {
+            throw new Error('Encrypted Parquet pages require parquet.keyRetriever');
+        }
+        const plaintextPages = [];
+        let offset = 0;
+        let dataPageOrdinal = dataPageOrdinalStart;
+        let pageIndex = 0;
+        while (offset < encryptedPages.length) {
+            const headerModule = readParquetEncryptedModule(encryptedPages, offset);
+            offset = headerModule.nextOffset;
+            const dictionaryPage = includesDictionary && pageIndex === 0;
+            const headerModuleType = dictionaryPage
+                ? 'dictionary-page-header'
+                : 'data-page-header';
+            const headerAad = createParquetModuleAad(this.encryptionContext.aadPrefix, this.encryptionContext.fileUnique, headerModuleType, rowGroupOrdinal, columnOrdinal, dictionaryPage ? undefined : dataPageOrdinal);
+            const headerBytes = await decryptParquetModule(headerModule.bytes, {
+                algorithm: this.encryptionContext.algorithm,
+                aad: headerAad,
+                keyMetadata,
+                keyRetriever: this.getCachedKeyRetriever()
+            });
+            const { pageHeader } = decodePageHeader(headerBytes);
+            const pageType = getThriftEnum(PageType, pageHeader.type);
+            const dataModule = readParquetEncryptedModule(encryptedPages, offset);
+            offset = dataModule.nextOffset;
+            const dataAad = createParquetModuleAad(this.encryptionContext.aadPrefix, this.encryptionContext.fileUnique, dictionaryPage ? 'dictionary-page' : 'data-page', rowGroupOrdinal, columnOrdinal, dictionaryPage ? undefined : dataPageOrdinal);
+            const dataBytes = await decryptParquetModule(dataModule.bytes, {
+                algorithm: this.encryptionContext.algorithm,
+                aad: dataAad,
+                keyMetadata,
+                keyRetriever: this.getCachedKeyRetriever(),
+                page: true
+            });
+            plaintextPages.push(serializeThrift(pageHeader), dataBytes);
+            if (pageType !== 'DICTIONARY_PAGE')
+                dataPageOrdinal++;
+            pageIndex++;
+        }
+        const plaintextLength = plaintextPages.reduce((total, page) => total + page.length, 0);
+        const plaintext = new Uint8Array(plaintextLength);
+        let plaintextOffset = 0;
+        for (const page of plaintextPages) {
+            plaintext.set(page, plaintextOffset);
+            plaintextOffset += page.length;
+        }
+        return plaintext;
+    }
+    /** Resolves the key metadata reference for an encrypted column. */
+    getColumnKeyMetadata(columnChunk) {
+        return (columnChunk.crypto_metadata?.ENCRYPTION_WITH_COLUMN_KEY?.key_metadata ??
+            this.encryptionContext?.footerKeyMetadata ??
+            this.encryptionContext?.footerSigningKeyMetadata);
+    }
+    /** Reads and decodes contiguous data pages that begin and end on complete row boundaries. */
+    async readColumnChunkRange(schema, columnChunk, rowRange, pages, signal, rowGroupOrdinal = 0, columnOrdinal = 0, resolvedMetadata) {
+        if (columnChunk.file_path !== undefined && columnChunk.file_path !== null) {
+            throw new Error('external references are not supported');
+        }
+        const columnMetadata = resolvedMetadata || columnChunk.meta_data;
+        if (!columnMetadata) {
+            throw new Error('Parquet column metadata is missing');
+        }
+        const encrypted = Boolean(columnChunk.crypto_metadata);
+        const field = schema.findField(columnMetadata.path_in_schema);
+        const type = getThriftEnum(Type, columnMetadata.type);
+        if (type !== field.primitiveType) {
+            throw new Error(`chunk type not matching schema: ${type}`);
+        }
+        const compression = getThriftEnum(CompressionCodec, columnMetadata.codec);
+        const overlappingPages = pages.filter(page => page.endRowIndex > rowRange.start && page.firstRowIndex < rowRange.end);
+        if (!overlappingPages.length) {
+            throw new Error('Parquet page plan does not overlap the requested row range');
+        }
+        let firstPageIndex = pages.indexOf(overlappingPages[0]);
+        const lastPage = overlappingPages[overlappingPages.length - 1];
+        let firstPage = pages[firstPageIndex];
+        const context = {
+            type,
+            rLevelMax: field.rLevelMax,
+            dLevelMax: field.dLevelMax,
+            compression,
+            column: field,
+            // Repeated leaves have one level entry per physical value, not one per logical row. Let the
+            // page decoder consume the selected page range and preserve all repetition levels.
+            numValues: field.rLevelMax === 0
+                ? new CompactInt64(lastPage.endRowIndex - firstPage.firstRowIndex)
+                : undefined,
+            dictionary: [],
+            decompressPage: this.getPageDecompressor(compression),
+            preserveBinary: this.props.preserveBinary,
+            retainByteArrayViews: this.props.retainByteArrayViews,
+            useTypedValueBuffers: this.props.useTypedValueBuffers,
+            useArrowByteArrayBuffers: this.props.useArrowByteArrayBuffers,
+            verifyPageChecksums: this.props.verifyPageChecksums,
+            int96AsTimestamp: this.props.int96AsTimestamp
+        };
+        let dictionary;
+        const dictionaryPageOffset = Number(columnMetadata.dictionary_page_offset);
+        if (Number.isSafeInteger(dictionaryPageOffset) && dictionaryPageOffset > 0) {
+            const dictionaryLength = Math.max(0, pages[0].offset - dictionaryPageOffset);
+            const dictionaryBuffer = await this.readBytes(dictionaryPageOffset, dictionaryLength, signal);
+            const decodedDictionaryBuffer = encrypted
+                ? await this.decryptColumnPages(dictionaryBuffer, context, rowGroupOrdinal, columnOrdinal, this.getColumnKeyMetadata(columnChunk), true)
+                : dictionaryBuffer;
+            dictionary = await decodeDictionaryBuffer(decodedDictionaryBuffer, context);
+        }
+        if (field.rLevelMax !== 0) {
+            // Probe predecessor pages independently, then decode the final range once. This avoids
+            // quadratic re-decoding when a large repeated row spans many pages.
+            while (firstPageIndex > 0) {
+                const probeBuffer = await this.readBytes(firstPage.offset, firstPage.compressedByteLength, signal);
+                const decodedProbeBuffer = encrypted
+                    ? await this.decryptColumnPages(probeBuffer, context, rowGroupOrdinal, columnOrdinal, this.getColumnKeyMetadata(columnChunk), false, firstPageIndex)
+                    : probeBuffer;
+                const probe = await decodeDataPages(decodedProbeBuffer, { ...context, dictionary });
+                if (probe.rlevels[0] === 0) {
+                    break;
+                }
+                firstPage = pages[--firstPageIndex];
+            }
+        }
+        const dataLength = lastPage.offset + lastPage.compressedByteLength - firstPage.offset;
+        const dataBuffer = await this.readBytes(firstPage.offset, dataLength, signal);
+        const decodedDataBuffer = encrypted
+            ? await this.decryptColumnPages(dataBuffer, context, rowGroupOrdinal, columnOrdinal, this.getColumnKeyMetadata(columnChunk), false, firstPageIndex)
+            : dataBuffer;
+        const decoded = await decodeDataPages(decodedDataBuffer, { ...context, dictionary });
+        if (field.rLevelMax !== 0) {
+            const rowStart = rowRange.start - firstPage.firstRowIndex;
+            return sliceRepeatedColumnChunk(decoded, Math.max(0, rowStart), rowRange.end - rowRange.start, field.dLevelMax);
+        }
+        const relativeStart = rowRange.start - firstPage.firstRowIndex;
+        const relativeEnd = relativeStart + rowRange.end - rowRange.start;
+        return sliceNonRepeatedColumnChunk(decoded, field.dLevelMax, relativeStart, relativeEnd);
+    }
     /**
      * Getting dictionary for allows to flatten values by indices.
      * @param dictionaryPageOffset
@@ -191,7 +879,7 @@ export class ParquetReader {
      * @param pagesOffset
      * @returns
      */
-    async getDictionary(dictionaryPageOffset, context, pagesOffset) {
+    async getDictionary(dictionaryPageOffset, context, pagesOffset, signal) {
         if (dictionaryPageOffset === 0) {
             // dictionarySize = Math.min(this.fileSize - pagesOffset, this.defaultDictionarySize);
             // pagesBuf = await this.read(pagesOffset, dictionarySize);
@@ -201,12 +889,91 @@ export class ParquetReader {
             // Now if we use code commented above we don't get DICTIONARY_PAGE we get DATA_PAGE instead.
             return [];
         }
-        const dictionarySize = Math.min(this.file.size - dictionaryPageOffset, this.props.defaultDictionarySize);
-        const arrayBuffer = await this.file.read(dictionaryPageOffset, dictionarySize);
-        const pagesBuf = Buffer.from(arrayBuffer);
-        const cursor = { buffer: pagesBuf, offset: 0, size: pagesBuf.length };
-        const decodedPage = await decodePage(cursor, context);
-        return decodedPage.dictionary;
+        const dictionarySize = Math.min(Math.max(0, pagesOffset - dictionaryPageOffset), this.file.size - dictionaryPageOffset, this.props.defaultDictionarySize);
+        const pagesBuf = await this.readBytes(dictionaryPageOffset, dictionarySize, signal);
+        return await decodeDictionaryBuffer(pagesBuf, context);
+    }
+}
+/** Returns a column path available without decrypting column metadata when possible. */
+function getColumnChunkPath(columnChunk) {
+    return (columnChunk.meta_data?.path_in_schema ??
+        columnChunk.crypto_metadata?.ENCRYPTION_WITH_COLUMN_KEY?.path_in_schema);
+}
+/** Builds a stable cache key while preserving module scope for context-dependent key providers. */
+function createEncryptionKeyCacheKey(algorithm, keyMetadata, aad, aadPrefixByteLength, fileUniqueByteLength) {
+    const metadataKey = keyMetadata ? Array.from(keyMetadata).join(',') : 'footer';
+    if (fileUniqueByteLength === undefined) {
+        return `${algorithm}:${metadataKey}:aad:${Array.from(aad).join(',')}`;
+    }
+    const moduleOffset = (aadPrefixByteLength ?? 0) + fileUniqueByteLength;
+    if (moduleOffset + 5 > aad.byteLength) {
+        return `${algorithm}:${metadataKey}:aad:${Array.from(aad).join(',')}`;
+    }
+    const moduleType = aad[moduleOffset];
+    if (moduleType === 0) {
+        return `${algorithm}:${metadataKey}:footer`;
+    }
+    const view = new DataView(aad.buffer, aad.byteOffset + moduleOffset, aad.byteLength - moduleOffset);
+    const rowGroupOrdinal = view.getInt16(1, true);
+    const columnOrdinal = view.getInt16(3, true);
+    return `${algorithm}:${metadataKey}:module:${moduleType}:row-group:${rowGroupOrdinal}:column:${columnOrdinal}`;
+}
+/** Returns the original row-group ordinal for a worker-reduced column list. */
+function getPhysicalColumnOrdinal(columnChunk, fallbackOrdinal) {
+    return (columnChunk.parquetColumnOrdinal ??
+        fallbackOrdinal);
+}
+/** Decodes one dictionary page from an already-read column-chunk range. */
+async function decodeDictionaryBuffer(dictionaryBuffer, context) {
+    const cursor = { buffer: dictionaryBuffer, offset: 0, size: dictionaryBuffer.length };
+    const decodedPage = await decodePage(cursor, context);
+    return decodedPage.dictionary;
+}
+/** Slices one decoded non-repeated column chunk while preserving optional-value alignment. */
+function sliceNonRepeatedColumnChunk(columnChunk, definitionLevelMaximum, start, end) {
+    const valueStart = countDefinedValues(columnChunk.dlevels, definitionLevelMaximum, 0, start);
+    const valueEnd = valueStart + countDefinedValues(columnChunk.dlevels, definitionLevelMaximum, start, end);
+    return {
+        rlevels: columnChunk.rlevels.slice(start, end),
+        dlevels: columnChunk.dlevels.slice(start, end),
+        values: columnChunk.values.slice(valueStart, valueEnd),
+        count: end - start,
+        pageHeaders: columnChunk.pageHeaders
+    };
+}
+/** Slices a repeated column by logical rows while preserving its level/value alignment. */
+function sliceRepeatedColumnChunk(columnChunk, rowStart, rowCount, definitionLevelMaximum) {
+    const rowStarts = [];
+    for (let levelIndex = 0; levelIndex < columnChunk.rlevels.length; levelIndex++) {
+        if (columnChunk.rlevels[levelIndex] === 0) {
+            rowStarts.push(levelIndex);
+        }
+    }
+    const levelStart = rowStarts[rowStart];
+    const endRow = rowStart + rowCount;
+    const levelEnd = rowStarts[endRow] ?? columnChunk.rlevels.length;
+    if (levelStart === undefined || endRow > rowStarts.length || levelEnd < levelStart) {
+        throw new Error('Parquet repeated page range does not contain the requested rows');
+    }
+    const valueStart = countDefinedValues(columnChunk.dlevels, definitionLevelMaximum, 0, levelStart);
+    const valueEnd = valueStart +
+        countDefinedValues(columnChunk.dlevels, definitionLevelMaximum, levelStart, levelEnd);
+    return {
+        rlevels: columnChunk.rlevels.slice(levelStart, levelEnd),
+        dlevels: columnChunk.dlevels.slice(levelStart, levelEnd),
+        values: columnChunk.values.slice(valueStart, valueEnd),
+        count: levelEnd - levelStart,
+        pageHeaders: columnChunk.pageHeaders
+    };
+}
+/** Counts defined primitive values represented by one non-repeated level interval. */
+function countDefinedValues(definitionLevels, definitionLevelMaximum, start, end) {
+    let count = 0;
+    for (let index = start; index < Math.min(end, definitionLevels.length); index++) {
+        if (definitionLevels[index] === definitionLevelMaximum) {
+            count++;
+        }
     }
+    return count;
 }
 //# sourceMappingURL=parquet-reader.js.map