qvdjs 0.10.1 → 0.11.0

package/dist/index.cjs

@@ -262,6 +262,128 @@ var init_QvdSymbol = __esm({
     };
   }
 });
+
+// src/util/readOptions.js
+function requireRowCount(value, name, filePath) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    throw new exports.QvdValidationError(`${name} must be a non-negative integer`, {
+      option: name,
+      provided: value,
+      type: typeof value,
+      file: filePath
+    });
+  }
+  return value;
+}
+function normaliseWindow(window, filePath) {
+  if (window === null || window === void 0) {
+    return { offset: 0, limit: null };
+  }
+  if (typeof window === "number") {
+    return { offset: 0, limit: requireRowCount(window, "maxRows", filePath) };
+  }
+  if (typeof window !== "object" || Array.isArray(window)) {
+    throw new exports.QvdValidationError("The row window must be a number, null, or an {offset, limit} object", {
+      provided: window,
+      type: typeof window,
+      file: filePath
+    });
+  }
+  const { offset, limit, maxRows } = window;
+  const limitGiven = limit !== void 0 && limit !== null;
+  const maxRowsGiven = maxRows !== void 0 && maxRows !== null;
+  if (limitGiven && maxRowsGiven) {
+    throw new exports.QvdValidationError("maxRows and limit are two names for the same option; pass one of them, not both", {
+      maxRows,
+      limit,
+      file: filePath
+    });
+  }
+  return {
+    offset: offset === void 0 || offset === null ? 0 : requireRowCount(offset, "offset", filePath),
+    limit: limitGiven ? requireRowCount(limit, "limit", filePath) : maxRowsGiven ? requireRowCount(maxRows, "maxRows", filePath) : null
+  };
+}
+function resolveWindow(window, totalRows) {
+  const rows = Number.isSafeInteger(totalRows) && totalRows > 0 ? totalRows : 0;
+  const offset = Math.min(window.offset, rows);
+  return {
+    offset,
+    limit: Math.max(0, Math.min(window.limit === null ? Infinity : window.limit, rows - offset))
+  };
+}
+function selectFields(fields, requested, filePath) {
+  if (requested === null || requested === void 0) {
+    return fields;
+  }
+  if (!Array.isArray(requested)) {
+    throw new exports.QvdValidationError("fields must be an array of field names", {
+      provided: requested,
+      type: typeof requested,
+      file: filePath
+    });
+  }
+  const available = fields.map((field) => field["FieldName"]);
+  if (requested.length === 0) {
+    throw new exports.QvdValidationError("fields must name at least one field", {
+      availableColumns: available,
+      file: filePath
+    });
+  }
+  const seen = /* @__PURE__ */ new Set();
+  return requested.map((name) => {
+    if (typeof name !== "string") {
+      throw new exports.QvdValidationError("Field names must be strings", {
+        provided: name,
+        type: typeof name,
+        availableColumns: available,
+        file: filePath
+      });
+    }
+    if (seen.has(name)) {
+      throw new exports.QvdValidationError(`Field '${name}' is listed twice`, {
+        column: name,
+        fields: requested,
+        file: filePath
+      });
+    }
+    seen.add(name);
+    const index = available.indexOf(name);
+    if (index === -1) {
+      throw new exports.QvdValidationError(`Column '${name}' does not exist`, {
+        column: name,
+        availableColumns: available,
+        file: filePath
+      });
+    }
+    return fields[index];
+  });
+}
+function readerOptionsFrom(options) {
+  return {
+    allowedDir: options.allowedDir,
+    memorySafetyFactor: options.memorySafetyFactor,
+    symbolFilteringThreshold: options.symbolFilteringThreshold,
+    fields: options.fields === void 0 ? null : options.fields,
+    onProgress: options.onProgress,
+    signal: options.signal
+  };
+}
+function metadataOptionsFrom(options) {
+  return {
+    allowedDir: options.allowedDir,
+    onProgress: options.onProgress,
+    signal: options.signal
+  };
+}
+function windowFrom(options) {
+  return { offset: options.offset, limit: options.limit, maxRows: options.maxRows };
+}
+var init_readOptions = __esm({
+  "src/util/readOptions.js"() {
+    init_QvdErrors();
+  }
+});
 function isWithinDirectoryLexically(resolvedBaseDir, resolvedPath) {
   const isCaseInsensitiveFS = process.platform === "win32";
   const base = isCaseInsensitiveFS ? resolvedBaseDir.toLowerCase() : resolvedBaseDir;
@@ -819,11 +941,12 @@ function estimateRowMemory(rows, columnCount) {
   }
   return BASE_BYTES + rows * (ROW_BASE_BYTES + PER_CELL_BYTES * columnCount);
 }
-function estimateMemoryUsage(symbolTableSize, maxRows, totalRows, columnCount = 0, materialisesRows = true) {
+function estimateMemoryUsage(symbolTableSize, maxRows, totalRows, columnCount = 0, materialisesRows = true, rowsLive = null) {
   const FULL_PARSE_OVERHEAD = 6;
   const MINIMAL_OVERHEAD = 0.01;
   const rowsToLoad = maxRows === null || maxRows >= totalRows ? totalRows : maxRows;
-  const rowMemory = materialisesRows ? estimateRowMemory(rowsToLoad, columnCount) : BASE_BYTES;
+  const liveRows = rowsLive === null ? rowsToLoad : Math.min(rowsLive, rowsToLoad);
+  const rowMemory = materialisesRows ? estimateRowMemory(liveRows, columnCount) : BASE_BYTES;
   if (maxRows === null || maxRows >= totalRows) {
     return symbolTableSize * FULL_PARSE_OVERHEAD + rowMemory;
   }
@@ -833,18 +956,44 @@ function estimateMemoryUsage(symbolTableSize, maxRows, totalRows, columnCount =
   const skippedSymbolsMemory = symbolTableSize * (1 - symbolPercentage) * MINIMAL_OVERHEAD;
   return keptSymbolsMemory + skippedSymbolsMemory + rowMemory;
 }
-function recommendedRowsFor(budget, symbolTableSize, totalRows, columnCount, materialisesRows = true) {
-  if (estimateMemoryUsage(symbolTableSize, totalRows, totalRows, columnCount, materialisesRows) <= budget) {
+function recommendedRowsFor(budget, symbolTableSize, totalRows, columnCount, materialisesRows = true, includeExternal = false) {
+  const costOf = (rows) => estimateMemoryUsage(symbolTableSize, rows, totalRows, columnCount, materialisesRows) + (includeExternal ? estimateExternalMemory(Math.min(rows, totalRows), columnCount) : 0);
+  if (costOf(totalRows) <= budget) {
     return totalRows;
   }
-  if (estimateMemoryUsage(symbolTableSize, 0, totalRows, columnCount, materialisesRows) > budget) {
+  if (costOf(0) > budget) {
     return 0;
   }
   let low = 0;
   let high = totalRows;
   while (high - low > 1) {
     const mid = Math.floor((low + high) / 2);
-    if (estimateMemoryUsage(symbolTableSize, mid, totalRows, columnCount, materialisesRows) <= budget) {
+    if (costOf(mid) <= budget) {
+      low = mid;
+    } else {
+      high = mid;
+    }
+  }
+  return low;
+}
+function recommendedChunkFor(budget, symbolTableSize, windowRows, totalRows, columnCount, liveRowsPerChunk = 1, includeExternal = false) {
+  const covered = windowRows === null || windowRows >= totalRows ? totalRows : windowRows;
+  const fits = (chunk) => {
+    const live = Math.min(chunk * liveRowsPerChunk, covered);
+    const cost = estimateMemoryUsage(symbolTableSize, windowRows, totalRows, columnCount, true, chunk * liveRowsPerChunk) + (includeExternal ? estimateExternalMemory(live, columnCount) : 0);
+    return cost <= budget;
+  };
+  if (fits(covered)) {
+    return covered;
+  }
+  if (!fits(1)) {
+    return 0;
+  }
+  let low = 1;
+  let high = covered;
+  while (high - low > 1) {
+    const mid = Math.floor((low + high) / 2);
+    if (fits(mid)) {
       low = mid;
     } else {
       high = mid;
@@ -852,7 +1001,7 @@ function recommendedRowsFor(budget, symbolTableSize, totalRows, columnCount, mat
   }
   return low;
 }
-function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePath, safetyFactor = 0.8, columnCount = 0, materialisesRows = true) {
+function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePath, safetyFactor = 0.8, columnCount = 0, materialisesRows = true, live = null) {
   if (typeof safetyFactor !== "number" || safetyFactor < 0 || safetyFactor > 1) {
     throw new exports.QvdValidationError("safetyFactor must be a number between 0.0 and 1.0", { safetyFactor });
   }
@@ -861,12 +1010,16 @@ function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePat
   }
   const budget = getMemoryBudget();
   const rowsToLoad = maxRows === null || maxRows >= totalRows ? totalRows : maxRows;
-  const heapMemory = estimateMemoryUsage(symbolTableSize, maxRows, totalRows, columnCount, materialisesRows);
-  const externalMemory = estimateExternalMemory(rowsToLoad, columnCount);
+  const rowsLive = live === null ? null : live.rows;
+  const liveRowsPerChunk = live === null ? 1 : live.perChunk;
+  const liveRows = rowsLive === null ? rowsToLoad : Math.min(rowsLive, rowsToLoad);
+  const heapMemory = estimateMemoryUsage(symbolTableSize, maxRows, totalRows, columnCount, materialisesRows, rowsLive);
+  const externalMemory = estimateExternalMemory(liveRows, columnCount);
   const bounded = budget.candidates.map((candidate) => {
     const heapOnly = candidate.source === "V8 heap limit";
     return {
       ...candidate,
+      heapOnly,
       needs: heapOnly ? heapMemory : heapMemory + externalMemory,
       allowed: candidate.bytes * safetyFactor,
       bounds: heapOnly ? "the V8 heap" : "the whole process"
@@ -882,12 +1035,14 @@ function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePat
   const estimatedMemory = binding ? binding.needs : heapMemory;
   const maxAllowedMemory = binding ? binding.allowed : budget.bytes * safetyFactor;
   if (binding) {
+    const includeExternal = !binding.heapOnly;
     const recommendedMaxRows = recommendedRowsFor(
       maxAllowedMemory,
       symbolTableSize,
       totalRows,
       columnCount,
-      materialisesRows
+      materialisesRows,
+      includeExternal
     );
     const sizeMB = Math.round(symbolTableSize / 1024 / 1024);
     const estimatedMB = Math.round(estimatedMemory / 1024 / 1024);
@@ -899,15 +1054,27 @@ function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePat
     const limitingScope = binding.bounds;
     const budgetBreakdown = budget.candidates.map((candidate) => `${candidate.source} ${Math.round(candidate.bytes / 1024 / 1024)}MB`).join(", ");
     const observedBreakdown = budget.observed.map((entry) => `${entry.source} ${Math.round(entry.bytes / 1024 / 1024)}MB`).join(", ");
-    const nothingFits = recommendedMaxRows === 0;
     const containerBound = binding.source === "container memory limit";
+    const chunked = rowsLive !== null;
+    const recommendedChunk = chunked ? recommendedChunkFor(
+      maxAllowedMemory,
+      symbolTableSize,
+      maxRows,
+      totalRows,
+      columnCount,
+      liveRowsPerChunk,
+      includeExternal
+    ) : 0;
+    const knob = chunked ? "chunkSize" : "limit";
+    const recommendedValue = chunked ? recommendedChunk : recommendedMaxRows;
+    const nothingFits = recommendedValue === 0;
     let advice;
     if (nothingFits) {
-      advice = `No row count fits this budget - the symbol table alone exceeds it, so maxRows cannot help. ` + (containerBound ? `Raise the container's memory limit.` : `Raise the heap with --max-old-space-size, or raise memorySafetyFactor.`);
+      advice = `No row count fits this budget - the symbol table alone exceeds it, so ${knob} cannot help. ` + (containerBound ? `Raise the container's memory limit.` : `Raise the heap with --max-old-space-size, or raise memorySafetyFactor.`);
     } else if (containerBound) {
-      advice = `The binding limit is the container's, so raising --max-old-space-size would let V8 grow past it and be killed by the OOM killer instead. Set it below the container limit, raise the limit, or load fewer rows with maxRows (recommended: ${recommendedMaxRows.toLocaleString()} rows or less).`;
+      advice = `The binding limit is the container's, so raising --max-old-space-size would let V8 grow past it and be killed by the OOM killer instead. Set it below the container limit, raise the limit, or hold fewer rows with ${knob} (recommended: ${recommendedValue.toLocaleString()} rows or less).`;
     } else {
-      advice = `Try loading fewer rows using the maxRows parameter (recommended: ${recommendedMaxRows.toLocaleString()} rows or less), or raise the heap with --max-old-space-size.`;
+      advice = `Try holding fewer rows using the ${knob} parameter (recommended: ${recommendedValue.toLocaleString()} rows or less), or raise the heap with --max-old-space-size.`;
     }
     throw new exports.QvdValidationError(
       `Insufficient memory to load file safely. Symbol table: ${sizeMB}MB, Estimated memory needed: ${estimatedMB}MB, Available: ${availableMB}MB (limited by ${limitingFactor}, which bounds ${limitingScope}; considered: ${budgetBreakdown}; observed but not used: ${observedBreakdown}). ` + advice,
@@ -927,22 +1094,30 @@ function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePat
         columnCount,
         totalRows,
         maxRows,
-        recommendedMaxRows
+        recommendedMaxRows,
+        // Only present when a chunk size is what overflowed, so a caller cannot mistake one
+        // recommendation for the other.
+        ...chunked ? { rowsLive, recommendedChunkSize: recommendedChunk } : {}
       }
     );
   }
 }
 function warnLargeSymbolTable(symbolTableSize, maxRows, totalRows, columnCount = 0, materialisesRows = true) {
   const LARGE_SYMBOL_TABLE_WARNING = usableOldSpaceLimit() * 0.125;
-  if (symbolTableSize > LARGE_SYMBOL_TABLE_WARNING && (maxRows === null || maxRows >= totalRows)) {
-    const sizeMB = Math.round(symbolTableSize / 1024 / 1024);
-    const estimatedMemory = estimateMemoryUsage(symbolTableSize, maxRows, totalRows, columnCount, materialisesRows);
-    const estimatedMB = Math.round(estimatedMemory / 1024 / 1024);
-    const warnMB = Math.round(LARGE_SYMBOL_TABLE_WARNING / 1024 / 1024);
-    console.warn(
-      `\u26A0\uFE0F  Large symbol table detected (${sizeMB}MB > ${warnMB}MB threshold). Loading all ${totalRows.toLocaleString()} rows will use ~${estimatedMB}MB RAM. Consider using the maxRows parameter for better performance and lower memory usage.`
-    );
+  if (symbolTableSize <= LARGE_SYMBOL_TABLE_WARNING) {
+    return;
   }
+  const rowsToLoad = maxRows === null || maxRows >= totalRows ? totalRows : maxRows;
+  const estimatedMemory = estimateMemoryUsage(symbolTableSize, maxRows, totalRows, columnCount, materialisesRows);
+  if (estimatedMemory <= LARGE_SYMBOL_TABLE_WARNING) {
+    return;
+  }
+  const sizeMB = Math.round(symbolTableSize / 1024 / 1024);
+  const estimatedMB = Math.round(estimatedMemory / 1024 / 1024);
+  const warnMB = Math.round(LARGE_SYMBOL_TABLE_WARNING / 1024 / 1024);
+  console.warn(
+    `\u26A0\uFE0F  Large symbol table detected (${sizeMB}MB > ${warnMB}MB threshold). This read materialises ${rowsToLoad.toLocaleString()} of ${totalRows.toLocaleString()} rows and will use ~${estimatedMB}MB RAM. Reading fewer rows - with limit, maxRows, or a narrower offset window - lowers the row cost, though the symbol table is read in full either way.`
+  );
 }
 var HEAP_LIMIT_OVERSTATEMENT_BYTES, MINIMUM_BUDGET_BYTES, BASE_BYTES, ROW_BASE_BYTES, PER_CELL_BYTES;
 var init_memoryUtils = __esm({
@@ -983,7 +1158,7 @@ function validateSymbolTableSizeEarly(symbolTableLength, filePath) {
     const maxMB = Math.round(MAX_SYMBOL_TABLE_SIZE / 1024 / 1024);
     const heapMB = Math.round(heapLimit / 1024 / 1024);
     throw new exports.QvdValidationError(
-      `Symbol table too large (${sizeMB}MB exceeds ${maxMB}MB limit for lazy loading). This QVD file contains extremely high-cardinality fields. Limit scales with heap size (current: ${heapMB}MB, limit: 12.5% = ${maxMB}MB). Consider: (1) loading the full file without maxRows, (2) increasing heap size with --max-old-space-size, or (3) aggregating high-cardinality fields.`,
+      `Symbol table too large (${sizeMB}MB exceeds ${maxMB}MB limit for lazy loading). This QVD file contains extremely high-cardinality fields. Limit scales with heap size (current: ${heapMB}MB, limit: 12.5% = ${maxMB}MB). Consider: (1) loading the full file without a row window - maxRows, limit or offset - since the symbol table is read in full either way, (2) increasing heap size with --max-old-space-size, or (3) aggregating high-cardinality fields.`,
       {
         file: filePath,
         symbolTableSize: symbolTableLength,
@@ -1057,7 +1232,7 @@ function validateRecordCount(totalRows, filePath, stage = "parseIndexTable") {
     });
   }
 }
-function validateIndexTableMetadata(recordSize, totalRows, indexTableLength, indexTableOffset, bufferLength, rowsToLoad, filePath, fileSize = null) {
+function validateIndexTableMetadata(recordSize, totalRows, indexTableLength, indexTableOffset, bufferLength, rowsToLoad, filePath, fileSize = null, windowFirstRow = 0, bufferFirstRow = 0) {
   if (isNaN(recordSize) || !Number.isSafeInteger(recordSize) || recordSize < 0) {
     throw new exports.QvdCorruptedError("Invalid record byte size", {
       recordSize,
@@ -1119,23 +1294,28 @@ function validateIndexTableMetadata(recordSize, totalRows, indexTableLength, ind
     }
   }
   const requiredIndexBytes = rowsToLoad * recordSize;
-  if (indexTableOffset + requiredIndexBytes > bufferLength) {
+  const bufferRecordStart = (windowFirstRow - bufferFirstRow) * recordSize;
+  if (indexTableOffset + bufferRecordStart + requiredIndexBytes > bufferLength) {
     throw new exports.QvdCorruptedError("Index table truncated", {
       indexTableOffset,
       requiredBytes: requiredIndexBytes,
-      availableBytes: Math.max(0, bufferLength - indexTableOffset),
+      availableBytes: Math.max(0, bufferLength - indexTableOffset - bufferRecordStart),
       rowsToLoad,
+      windowFirstRow,
+      bufferFirstRow,
       recordSize,
       bufferSize: bufferLength,
       file: filePath,
       stage: "parseIndexTable"
     });
   }
-  if (indexTableLength < requiredIndexBytes) {
+  const requiredTableBytes = (windowFirstRow + rowsToLoad) * recordSize;
+  if (indexTableLength < requiredTableBytes) {
     throw new exports.QvdCorruptedError("Index table length smaller than required", {
       indexTableLength,
-      requiredBytes: requiredIndexBytes,
+      requiredBytes: requiredTableBytes,
       rowsToLoad,
+      windowFirstRow,
       recordSize,
       file: filePath,
       stage: "parseIndexTable"
@@ -1465,6 +1645,7 @@ exports.QvdColumn = void 0; exports.QvdColumnTable = void 0;
 var init_QvdColumnTable = __esm({
   "src/QvdColumnTable.js"() {
     init_QvdErrors();
+    init_readOptions();
     exports.QvdColumn = class {
       /**
        * @param {string} name The field name.
@@ -1659,9 +1840,21 @@ var init_QvdColumnTable = __esm({
       /**
        * Reads a QVD file as columns.
        *
+       * Takes the same options as `QvdDataFrame.fromQvd`, with the same meanings - one option
+       * vocabulary for both read paths, because they are two answers about the same file rather than
+       * two features. `{offset, limit}` is how a caller pages through a file columnwise; there is no
+       * columnar `iterate()` because there is nothing for it to bound - a columnar read materialises
+       * no rows, which is the memory chunking exists to cap.
+       *
        * @param {string} path The path to the QVD file.
        * @param {Object} [options] Loading options, with the same meanings they have on `fromQvd`.
-       * @param {number|null} [options.maxRows] Maximum rows to decode.
+       * @param {number|null} [options.maxRows] Rows to decode. The older name for `limit`.
+       * @param {number|null} [options.limit] Rows to decode, counting from `offset`.
+       * @param {number} [options.offset] File row to start at.
+       * @param {Array<string>|null} [options.fields] Field names to read, in the order they should
+       *   appear. Unselected fields have their symbols skipped entirely.
+       * @param {Function} [options.onProgress] Progress callback, `{stage, current, total, percent}`.
+       * @param {AbortSignal} [options.signal] Cancels the read.
        * @param {string} [options.allowedDir] Directory the path must resolve inside.
        * @param {number} [options.memorySafetyFactor] Fraction of the memory budget a load may use.
        * @param {number} [options.symbolFilteringThreshold] Symbol table size above which a limited
@@ -1671,15 +1864,13 @@ var init_QvdColumnTable = __esm({
       static async fromQvd(path3, options = {}) {
         const { QvdFileReader: QvdFileReader2 } = await Promise.resolve().then(() => (init_QvdFileReader(), QvdFileReader_exports));
         const reader = new QvdFileReader2(path3, {
-          allowedDir: options.allowedDir,
-          memorySafetyFactor: options.memorySafetyFactor,
-          symbolFilteringThreshold: options.symbolFilteringThreshold,
+          ...readerOptionsFrom(options),
           // This read builds no rows, so the memory guard must not charge it for them. A columnar
           // read of the 38MB taxi fixture completes in a 15MB heap; charged the row cost it was
           // refused below a 2GB one.
           materialisesRows: false
         });
-        return await reader.loadColumnar(options.maxRows !== void 0 ? options.maxRows : null);
+        return await reader.loadColumnar(windowFrom(options));
       }
       /** @return {Array<string>} Field names, in file order. */
       get columns() {
@@ -1727,7 +1918,7 @@ var QvdFileReader_exports = {};
 __export(QvdFileReader_exports, {
   QvdFileReader: () => exports.QvdFileReader
 });
-var MAX_HEADER_SIZE, READ_CHUNK_SIZE; exports.QvdFileReader = void 0;
+var MAX_HEADER_SIZE, READ_CHUNK_SIZE, ANALYSIS_SLICE_ROWS; exports.QvdFileReader = void 0;
 var init_QvdFileReader = __esm({
   "src/QvdFileReader.js"() {
     init_QvdDataFrame();
@@ -1737,8 +1928,10 @@ var init_QvdFileReader = __esm({
     init_memoryUtils();
     init_validationUtils();
     init_symbolParser();
+    init_readOptions();
     MAX_HEADER_SIZE = 16 * 1024 * 1024;
     READ_CHUNK_SIZE = 512 * 1024 * 1024;
+    ANALYSIS_SLICE_ROWS = 65536;
     exports.QvdFileReader = class {
       /**
        * Constructs a new QVD file parser.
@@ -1750,9 +1943,10 @@ var init_QvdFileReader = __esm({
        *   points outside it is rejected. Defaults to the current working directory. To permit
        *   an entire volume, pass its root explicitly ('/' on POSIX, 'C:\\' on Windows); a null or
        *   empty value falls back to the working directory rather than removing the restriction.
-       * @param {number} [options.memorySafetyFactor=0.3] Fraction (0.0-1.0) of the memory budget a
-       *   load may use. The budget is the smallest of the V8 heap limit, any container memory limit,
-       *   and the memory the OS reports as available. Default is 0.3. **Zero disables the memory
+       * @param {number} [options.memorySafetyFactor=0.8] Fraction (0.0-1.0) of the memory budget a
+       *   load may use. The budget is the smaller of the V8 heap limit and any container memory limit;
+       *   what the OS reports as available is recorded for diagnostics and deliberately not allowed to
+       *   bind - see `getMemoryBudget`. Default is 0.8. **Zero disables the memory
        *   check entirely**, which is the escape hatch for runtimes whose limits cannot be measured -
        *   Bun reports its current heap as its heap limit - and for callers who would rather manage
        *   memory themselves than trust the estimate.
@@ -1763,29 +1957,93 @@ var init_QvdFileReader = __esm({
        *   above which a lazy load switches to the two-pass filtering path. The default of 50MB is
        *   the point where the extra analysis pass pays for itself; lower it to use filtering on
        *   smaller files, raise it to keep the simpler single-pass read for longer.
+       * @param {Array<string>|null} [options.fields] Field names to read, in the order they should
+       *   appear. Null reads every field, in file order. An unknown or repeated name is refused.
+       * @param {Function} [options.onProgress] Called with `{stage, current, total, percent}` as the
+       *   read proceeds - the same shape `QvdFileWriter` emits.
+       * @param {AbortSignal} [options.signal] Cancels the read. When it is aborted the read throws
+       *   `signal.reason`, exactly as `signal.throwIfAborted()` does.
        */
       constructor(filePath, options = {}) {
         const {
           allowedDir,
           memorySafetyFactor = 0.8,
           symbolFilteringThreshold = 50 * 1024 * 1024,
-          materialisesRows = true
+          materialisesRows = true,
+          fields = null,
+          onProgress,
+          signal
         } = options;
         this._materialisesRows = materialisesRows;
         this._path = validatePath(filePath, allowedDir);
         this._memorySafetyFactor = memorySafetyFactor;
         this._symbolFilteringThreshold = symbolFilteringThreshold;
+        if (onProgress !== void 0 && typeof onProgress !== "function") {
+          throw new exports.QvdValidationError("onProgress must be a function", {
+            provided: onProgress,
+            type: typeof onProgress,
+            file: this._path
+          });
+        }
+        if (signal !== void 0 && (typeof signal !== "object" || signal === null || typeof signal.aborted !== "boolean")) {
+          throw new exports.QvdValidationError("signal must be an AbortSignal", {
+            provided: signal,
+            type: typeof signal,
+            file: this._path
+          });
+        }
+        this._requestedFields = fields === void 0 ? null : fields;
+        this._onProgress = onProgress;
+        this._signal = signal;
         this._buffer = null;
         this._headerOffset = null;
         this._symbolTableOffset = null;
         this._indexTableOffset = null;
         this._header = null;
+        this._allFields = null;
+        this._selectedFields = null;
+        this._fieldBitMetadataValidated = false;
         this._symbolTable = null;
         this._indexColumns = null;
         this._rowsDecoded = 0;
+        this._bufferFirstRow = 0;
         this._fileSize = null;
         this._headerMatchesFile = false;
       }
+      /**
+       * Emits a progress event if a callback is registered.
+       *
+       * The same shape `QvdFileWriter._emitProgress` emits, deliberately: a caller who has written a
+       * progress bar for a write should not have to write a second one for a read. The stage names
+       * differ because the stages differ, but `symbol-table` and `index-table` mean the same thing on
+       * both sides.
+       *
+       * @param {string} stage The current stage of the read.
+       * @param {number} current The current progress value.
+       * @param {number} total The total progress value.
+       * @private
+       */
+      _emitProgress(stage, current, total) {
+        if (this._onProgress) {
+          const percent = total > 0 ? Math.round(current / total * 100) : 100;
+          this._onProgress({ stage, current, total, percent });
+        }
+      }
+      /**
+       * Throws if the caller has cancelled the read.
+       *
+       * Throws `signal.reason` - a `DOMException` named `AbortError` unless the caller aborted with a
+       * reason of their own. That is what `AbortSignal` means everywhere else in Node, and inventing
+       * a `QvdAbortError` here would make this library's cancellation the one a caller has to special
+       * case.
+       *
+       * @private
+       */
+      _throwIfAborted() {
+        if (this._signal) {
+          this._signal.throwIfAborted();
+        }
+      }
       /**
        * Reads the binary data of the QVD file.
        *
@@ -1810,14 +2068,23 @@ var init_QvdFileReader = __esm({
        * - Streaming for header finding is efficient for unknown header sizes
        * - Direct byte-range reading for remaining data is fastest
        *
-       * @param {number|null} maxRows The maximum number of rows to load. If null, all data is loaded.
+       * A window with a non-zero `offset` reads two ranges rather than one: the header and symbol
+       * table from the front of the file, and the window's records from wherever they sit. The bytes
+       * between are never read, which is what makes `{offset: 1_700_000, limit: 100}` on the taxi
+       * fixture a 0.4MB read rather than a 38MB one.
+       *
+       * @param {QvdRowWindow} window The rows to read.
        * @param {boolean} [headerOnly=false] Stop once the XML header has been read, leaving the
        *   symbol and index tables on disk. This is the metadata-only path: the header is a few
        *   kilobytes whatever the file's size, so reading a schema costs the same for a 40MB file as
        *   for a 40GB one.
+       * @param {{rows: number, perChunk: number}|null} [liveRows=null] Rows held at one instant when
+       *   that is fewer than the window covers - see `_prepare`.
        * @private
        */
-      async _readData(maxRows = null, headerOnly = false) {
+      async _readData(window = { offset: 0, limit: null }, headerOnly = false, liveRows = null) {
+        this._throwIfAborted();
+        this._emitProgress("read", 0, 1);
         const HEADER_DELIMITER = "\r\n\0";
         const CHUNK_SIZE = 64 * 1024;
         const stream = fs__default.default.createReadStream(this._path, {
@@ -1887,13 +2154,14 @@ var init_QvdFileReader = __esm({
         const totalRows = parseInt(headerObj["QvdTableHeader"]["NoOfRecords"], 10);
         if (headerOnly) {
           this._buffer = headerBuffer.subarray(0, headerEndIndex);
+          this._emitProgress("read", 1, 1);
           return;
         }
         let headerFields = headerObj["QvdTableHeader"]?.["Fields"]?.["QvdFieldHeader"];
         if (headerFields && !Array.isArray(headerFields)) {
           headerFields = [headerFields];
         }
-        const columnCount = Array.isArray(headerFields) ? headerFields.length : 0;
+        const columnCount = Array.isArray(headerFields) ? selectFields(headerFields, this._requestedFields, this._path).length : 0;
         const headerNumbersUsable = [symbolTableLength, recordSize, totalRows].every(
           (value) => Number.isSafeInteger(value) && value >= 0
         );
@@ -1902,23 +2170,28 @@ var init_QvdFileReader = __esm({
           this._fileSize = fileSize;
           this._headerMatchesFile = headerEndIndex + symbolTableLength + totalRows * recordSize <= fileSize;
         }
+        const resolved = headerNumbersUsable ? resolveWindow(window, totalRows) : { offset: 0, limit: 0 };
+        const windowRows = resolved.limit;
         if (headerNumbersUsable && this._headerMatchesFile) {
           validateMemoryAvailability(
             symbolTableLength,
-            maxRows,
+            windowRows,
             totalRows,
             this._path,
             this._memorySafetyFactor,
             columnCount,
-            this._materialisesRows
+            this._materialisesRows,
+            liveRows
           );
         }
-        if (maxRows === null) {
+        if (window.offset === 0 && window.limit === null) {
           this._buffer = await fs__default.default.promises.readFile(this._path);
           this._fileSize = this._buffer.length;
+          this._bufferFirstRow = 0;
+          this._emitProgress("read", 1, 1);
           return;
         }
-        const rowsToLoad = Math.min(maxRows, totalRows);
+        const rowsToLoad = windowRows;
         validateSymbolTableSizeEarly(symbolTableLength, this._path);
         for (const [name, value] of [
           ["Offset", symbolTableLength],
@@ -1934,39 +2207,78 @@ var init_QvdFileReader = __esm({
             });
           }
         }
+        const skippedIndexBytes = resolved.offset * recordSize;
         const indexTableBytesToRead = rowsToLoad * recordSize;
         const totalBytesToRead = indexTableOffset + indexTableBytesToRead;
+        const fileBytesRequired = indexTableOffset + skippedIndexBytes + indexTableBytesToRead;
         const fd = await fs__default.default.promises.open(this._path, "r");
         try {
           const { size: fileSize } = await fd.stat();
           this._fileSize = fileSize;
-          if (totalBytesToRead > fileSize) {
+          if (fileBytesRequired > fileSize) {
             throw new exports.QvdCorruptedError("The file is shorter than its header claims.", {
               file: this._path,
               fileSize,
-              requiredBytes: totalBytesToRead,
+              requiredBytes: fileBytesRequired,
               stage: "readData"
             });
           }
           this._buffer = Buffer.alloc(totalBytesToRead);
-          let position = 0;
-          while (position < totalBytesToRead) {
-            const length = Math.min(READ_CHUNK_SIZE, totalBytesToRead - position);
-            const { bytesRead } = await fd.read(this._buffer, position, length, position);
-            if (bytesRead === 0) {
-              throw new exports.QvdCorruptedError("Unexpected end of file while reading QVD data.", {
-                file: this._path,
-                fileSize,
-                bytesRead: position,
-                requiredBytes: totalBytesToRead,
-                stage: "readData"
-              });
-            }
-            position += bytesRead;
+          await this._readRange(fd, 0, indexTableOffset, 0, fileSize, totalBytesToRead);
+          if (indexTableBytesToRead > 0) {
+            await this._readRange(
+              fd,
+              indexTableOffset,
+              indexTableBytesToRead,
+              indexTableOffset + skippedIndexBytes,
+              fileSize,
+              fileBytesRequired
+            );
           }
+          this._bufferFirstRow = resolved.offset;
         } finally {
           await fd.close();
         }
+        this._emitProgress("read", 1, 1);
+      }
+      /**
+       * Reads one byte range of the file into the buffer.
+       *
+       * Read in bounded chunks, checking bytesRead each time. A single fs.read call with a length of
+       * 2^31 or more does not throw - it trips a C++ assertion and aborts the whole process, which no
+       * try/catch can intercept.
+       *
+       * @param {import('fs/promises').FileHandle} fd The open file.
+       * @param {number} bufferOffset Where in the buffer to write.
+       * @param {number} byteCount How many bytes to read.
+       * @param {number} filePosition Where in the file to read from.
+       * @param {number} fileSize The file's size, for the error.
+       * @param {number} requiredBytes Bytes the whole read needs, for the error.
+       * @private
+       */
+      async _readRange(fd, bufferOffset, byteCount, filePosition, fileSize, requiredBytes) {
+        assert2__default.default(this._buffer, "The read buffer has not been allocated.");
+        let done = 0;
+        while (done < byteCount) {
+          const length = Math.min(READ_CHUNK_SIZE, byteCount - done);
+          const { bytesRead } = await fd.read(this._buffer, bufferOffset + done, length, filePosition + done);
+          if (bytesRead === 0) {
+            throw new exports.QvdCorruptedError("Unexpected end of file while reading QVD data.", {
+              file: this._path,
+              fileSize,
+              // Two numbers, because they stopped being the same one when a window began reading two
+              // ranges: `bytesRead` is how much of this range arrived, `filePosition` is where in the
+              // file it gave up. Reporting the position under the name of the count made a windowed
+              // read of a truncated file claim tens of megabytes had been read when a few hundred
+              // bytes had.
+              bytesRead: done,
+              filePosition: filePosition + done,
+              requiredBytes,
+              stage: "readData"
+            });
+          }
+          done += bytesRead;
+        }
       }
       /**
        * Parses the XML header of the QVD file. This method is part of the parsing process
@@ -2026,6 +2338,8 @@ var init_QvdFileReader = __esm({
         this._headerOffset = headerBeginIndex;
         this._symbolTableOffset = headerEndIndex;
         this._indexTableOffset = this._symbolTableOffset + parseInt(this._header["QvdTableHeader"]["Offset"], 10);
+        this._allFields = fieldList;
+        this._selectedFields = selectFields(this._allFields, this._requestedFields, this._path);
       }
       /**
        * Establishes the geometry of the index table, and validates it.
@@ -2036,14 +2350,15 @@ var init_QvdFileReader = __esm({
        * about keeping the sign in step with the other one: the two could drift, and #113 is what
        * that looks like when they do. There is one copy now.
        *
-       * @param {number|null} rowLimit Maximum rows of interest, or null for all of them.
+       * @param {QvdRowWindow} window The rows of interest, as file row indices.
        * @param {string} stage Stage name for any error raised here.
        * @return {{fields: Array<any>, recordSize: number, totalRows: number, rowsToLoad: number,
-       *   indexBuffer: Buffer}} The record geometry.
+       *   indexBuffer: Buffer}} The record geometry. `indexBuffer` starts at the window's first
+       *   record, so the decoder always counts from zero.
        * @private
        */
-      _planIndexTable(rowLimit, stage) {
-        if (!this._buffer || !this._header || !this._indexTableOffset) {
+      _planIndexTable(window, stage) {
+        if (!this._buffer || !this._header || !this._indexTableOffset || !this._selectedFields || !this._allFields) {
           throw new exports.QvdCorruptedError(
             "The QVD file has not been loaded in the proper order or has not been loaded at all.",
             {
@@ -2052,14 +2367,12 @@ var init_QvdFileReader = __esm({
             }
           );
         }
-        let fields = this._header["QvdTableHeader"]["Fields"]["QvdFieldHeader"];
-        if (!Array.isArray(fields)) {
-          fields = [fields];
-        }
+        const allFields = this._allFields;
+        const fields = this._selectedFields;
         const recordSize = parseInt(this._header["QvdTableHeader"]["RecordByteSize"], 10);
         const totalRows = parseInt(this._header["QvdTableHeader"]["NoOfRecords"], 10);
-        const rowsToLoad = rowLimit !== null ? Math.min(rowLimit, totalRows) : totalRows;
         const indexTableLength = parseInt(this._header["QvdTableHeader"]["Length"], 10);
+        const { offset: firstRow, limit: rowsToLoad } = resolveWindow(window, totalRows);
         validateIndexTableMetadata(
           recordSize,
           totalRows,
@@ -2068,11 +2381,20 @@ var init_QvdFileReader = __esm({
           this._buffer.length,
           rowsToLoad,
           this._path,
-          this._fileSize
+          this._fileSize,
+          firstRow,
+          this._bufferFirstRow
+        );
+        const bufferRecordStart = (firstRow - this._bufferFirstRow) * recordSize;
+        const indexBuffer = this._buffer.subarray(
+          this._indexTableOffset + bufferRecordStart,
+          this._indexTableOffset + bufferRecordStart + rowsToLoad * recordSize
         );
-        const indexBuffer = this._buffer.subarray(this._indexTableOffset, this._indexTableOffset + indexTableLength + 1);
-        for (const field of fields) {
-          validateFieldBitMetadata(field, recordSize, this._path);
+        if (!this._fieldBitMetadataValidated) {
+          for (const field of allFields) {
+            validateFieldBitMetadata(field, recordSize, this._path);
+          }
+          this._fieldBitMetadataValidated = true;
         }
         assert2__default.default(
           rowsToLoad === 0 || recordSize === 0 || Math.floor(indexBuffer.length / recordSize) >= rowsToLoad,
@@ -2084,31 +2406,45 @@ var init_QvdFileReader = __esm({
        * Analyzes the index table to determine which symbols are actually needed.
        * This is used for two-pass symbol filtering optimization.
        *
-       * @param {number} maxRows The maximum number of rows to analyze.
-       * @return {Promise<Map<string, Set<number>>>} Map of field names to Set of needed symbol indices.
+       * Only the selected fields are analysed. An unselected field's symbols are never parsed, so
+       * there is nothing for a usage set to filter and decoding its column would be a pass over the
+       * whole window for an answer nobody reads.
+       *
+       * @param {QvdRowWindow} window The rows to analyse.
+       * @return {Promise<Array<Set<number>>>} One set of needed symbol indices per selected field, in
+       *   the same order `_parseSymbolTable` walks them.
        * @private
        */
-      async _analyzeIndexTableSymbolUsage(maxRows) {
-        const { fields, recordSize, rowsToLoad, indexBuffer } = this._planIndexTable(maxRows, "analyzeIndexTableSymbolUsage");
-        const symbolUsage = /* @__PURE__ */ new Map();
-        const column = new Int32Array(rowsToLoad);
-        fields.forEach((field) => {
+      async _analyzeIndexTableSymbolUsage(window) {
+        const { fields, recordSize, rowsToLoad, indexBuffer } = this._planIndexTable(window, "analyzeIndexTableSymbolUsage");
+        const symbolUsage = [];
+        const sliceRows = Math.min(rowsToLoad, ANALYSIS_SLICE_ROWS);
+        const column = new Int32Array(sliceRows);
+        fields.forEach((field, position) => {
+          this._throwIfAborted();
           const needed = /* @__PURE__ */ new Set();
-          symbolUsage.set(field["FieldName"], needed);
-          decodeIndexColumn(
-            indexBuffer,
-            recordSize,
-            rowsToLoad,
-            parseInt(field["BitOffset"], 10),
-            parseInt(field["BitWidth"], 10),
-            parseInt(field["Bias"], 10),
-            column
-          );
-          for (let row = 0; row < rowsToLoad; row++) {
-            if (column[row] >= 0) {
-              needed.add(column[row]);
+          symbolUsage[position] = needed;
+          const bitOffset = parseInt(field["BitOffset"], 10);
+          const bitWidth = parseInt(field["BitWidth"], 10);
+          const bias = parseInt(field["Bias"], 10);
+          for (let first = 0; first < rowsToLoad; first += sliceRows) {
+            const count = Math.min(sliceRows, rowsToLoad - first);
+            decodeIndexColumn(
+              first === 0 ? indexBuffer : indexBuffer.subarray(first * recordSize),
+              recordSize,
+              count,
+              bitOffset,
+              bitWidth,
+              bias,
+              column
+            );
+            for (let row = 0; row < count; row++) {
+              if (column[row] >= 0) {
+                needed.add(column[row]);
+              }
             }
           }
+          this._emitProgress("symbol-analysis", position + 1, fields.length);
         });
         return symbolUsage;
       }
@@ -2116,12 +2452,20 @@ var init_QvdFileReader = __esm({
        * Parses the symbol table of the QVD file. This method is part of the parsing process
        * and should not be called directly.
        *
-       * @param {Map<string, Set<number>>|null} symbolsToKeep Optional map of field names to symbol indices to keep.
-       *   If provided, only these symbols will be parsed (two-pass filtering optimization).
-       * @param {number|null} maxRows Optional maximum number of rows being loaded (for memory estimation).
+       * A field the caller did not select is skipped whole. Its symbol area is neither scanned nor
+       * parsed - the per-field `Offset` and `Length` say exactly where it is, so there is nothing to
+       * walk past - and that is where field selection earns its keep. The index decode is cheap by
+       * comparison; parsing symbols is not.
+       *
+       * @param {Array<Set<number>>|null} symbolsToKeep Optional set of symbol indices to keep per
+       *   selected field, indexed by position. If provided, only these symbols will be parsed
+       *   (two-pass filtering optimization).
+       * @param {number} rowsToLoad Rows the read covers, for memory estimation.
+       * @param {{rows: number, perChunk: number}|null} [liveRows=null] Rows held at one instant when
+       *   that is fewer than the window covers - see `_prepare`.
        */
-      async _parseSymbolTable(symbolsToKeep = null, maxRows = null) {
-        if (!this._buffer || !this._header || !this._symbolTableOffset || !this._indexTableOffset) {
+      async _parseSymbolTable(symbolsToKeep = null, rowsToLoad = 0, liveRows = null) {
+        if (!this._buffer || !this._header || !this._symbolTableOffset || !this._indexTableOffset || !this._selectedFields || !this._allFields) {
           throw new exports.QvdCorruptedError(
             "The QVD file has not been loaded in the proper order or has not been loaded at all.",
             {
@@ -2130,7 +2474,8 @@ var init_QvdFileReader = __esm({
             }
           );
         }
-        let fields = this._header["QvdTableHeader"]["Fields"]["QvdFieldHeader"];
+        const allFields = this._allFields;
+        const fields = this._selectedFields;
         const symbolBuffer = this._buffer.subarray(this._symbolTableOffset, this._indexTableOffset);
         const symbolTableSize = symbolBuffer.length;
         const totalRows = parseInt(this._header["QvdTableHeader"]["NoOfRecords"], 10);
@@ -2138,32 +2483,25 @@ var init_QvdFileReader = __esm({
         if (this._headerMatchesFile) {
           validateMemoryAvailability(
             symbolTableSize,
-            maxRows,
+            rowsToLoad,
             totalRows,
             this._path,
             this._memorySafetyFactor,
-            Array.isArray(fields) ? fields.length : 1,
-            this._materialisesRows
+            fields.length,
+            this._materialisesRows,
+            liveRows
           );
         }
-        warnLargeSymbolTable(
-          symbolTableSize,
-          maxRows,
-          totalRows,
-          Array.isArray(fields) ? fields.length : 1,
-          this._materialisesRows
-        );
-        if (!Array.isArray(fields)) {
-          fields = [fields];
-        }
-        for (const field of fields) {
+        warnLargeSymbolTable(symbolTableSize, rowsToLoad, totalRows, fields.length, this._materialisesRows);
+        for (const field of allFields) {
           validateFieldMetadata(field, symbolBuffer.length, this._path);
         }
-        this._symbolTable = fields.map((field) => {
+        this._symbolTable = fields.map((field, position) => {
+          this._throwIfAborted();
           const symbolsOffset = parseInt(field["Offset"], 10);
           const symbolsLength = parseInt(field["Length"], 10);
           const fieldName = field["FieldName"];
-          const neededSymbols = symbolsToKeep ? symbolsToKeep.get(fieldName) : null;
+          const neededSymbols = symbolsToKeep ? symbolsToKeep[position] : null;
           const filteringEnabled = neededSymbols !== null;
           const symbols = [];
           let symbolIndex = 0;
@@ -2183,6 +2521,7 @@ var init_QvdFileReader = __esm({
             pointer += bytesRead - 1;
             symbolIndex++;
           }
+          this._emitProgress("symbol-table", position + 1, fields.length);
           return symbols;
         });
       }
@@ -2201,13 +2540,18 @@ var init_QvdFileReader = __esm({
        * same for every row, so they are hoisted out of the loop and the inner loop does arithmetic
        * into a typed array and nothing else. Rows are assembled later, once, in `load()`.
        *
-       * @param {number|null} maxRows The maximum number of rows to parse. If null, all rows are parsed.
+       * The window is what makes chunked iteration cheap: `decodeIndexColumn` walks records by
+       * `base += recordSize`, so decoding rows k to k+n is a question of where the buffer slice starts
+       * and how many iterations run. Nothing about the decoder changed to support it.
+       *
+       * @param {QvdRowWindow} window The rows to decode.
        */
-      async _parseIndexTable(maxRows = null) {
-        const { fields, recordSize, rowsToLoad, indexBuffer } = this._planIndexTable(maxRows, "parseIndexTable");
+      async _parseIndexTable(window) {
+        const { fields, recordSize, rowsToLoad, indexBuffer } = this._planIndexTable(window, "parseIndexTable");
         this._rowsDecoded = rowsToLoad;
-        this._indexColumns = fields.map(
-          (field) => decodeIndexColumn(
+        this._indexColumns = fields.map((field, position) => {
+          this._throwIfAborted();
+          const column = decodeIndexColumn(
             indexBuffer,
             recordSize,
             rowsToLoad,
@@ -2215,8 +2559,10 @@ var init_QvdFileReader = __esm({
             parseInt(field["BitWidth"], 10),
             parseInt(field["Bias"], 10),
             new Int32Array(rowsToLoad)
-          )
-        );
+          );
+          this._emitProgress("index-table", position + 1, fields.length);
+          return column;
+        });
       }
       /**
        * Reads the file's schema and header metadata, without touching the symbol or index tables.
@@ -2233,8 +2579,11 @@ var init_QvdFileReader = __esm({
        * @return {Promise<import('./QvdDataFrame.js').QvdFileMetadata>} The file's schema and header.
        */
       async loadMetadata() {
-        await this._readData(null, true);
+        await this._readData({ offset: 0, limit: null }, true);
+        this._emitProgress("header", 0, 1);
         await this._parseHeader();
+        this._emitProgress("header", 1, 1);
+        this._throwIfAborted();
         assert2__default.default(this._header, "The QVD file header has not been parsed.");
         const header = this._header["QvdTableHeader"];
         let fields = header["Fields"]?.["QvdFieldHeader"] ?? [];
@@ -2269,114 +2618,200 @@ var init_QvdFileReader = __esm({
       /**
        * Loads the QVD file into memory and parses it.
        *
-       * @param {number|null} maxRows The maximum number of rows to load. If null, all rows are loaded.
-       *   Must be a non-negative integer when given.
-       * @throws {QvdValidationError} If maxRows is neither null nor a non-negative integer.
+       * @param {number|null|{offset?: number, limit?: number|null, maxRows?: number|null}} [window]
+       *   The rows to load. A number or null means what it always meant - the first N rows, or all of
+       *   them - and `{offset, limit}` is the same thing said more precisely, so `5` and
+       *   `{offset: 0, limit: 5}` are one read. `maxRows` is accepted as a second name for `limit`.
+       * @throws {QvdValidationError} If the window is not a non-negative integer, null, or a valid
+       *   `{offset, limit}` object.
        * @return {Promise<QvdDataFrame>} The loaded QVD file.
        */
-      async load(maxRows = null) {
-        const { columns, metadata, loadStats, resolvedByField } = await this._decode(maxRows);
+      async load(window = null) {
+        const rows = normaliseWindow(window, this._path);
+        const prepared = await this._prepare(rows);
+        await this._parseIndexTable({ offset: prepared.offset, limit: prepared.rowsAvailable });
+        const data = this._buildRows(prepared.resolvedByField, 0, prepared.rowsAvailable);
+        return new exports.QvdDataFrame(data, prepared.columns, prepared.metadata, {
+          ...prepared.loadStats,
+          rowsLoaded: data.length
+        });
+      }
+      /**
+       * Reads the file as columns, without ever materialising rows.
+       *
+       * Shares every step with `load()` up to the point where rows would be built - see `_prepare`.
+       * What it keeps instead is what the decoder already produced: one `Int32Array` of stored
+       * indices per field, and one resolved value per distinct symbol. On the 1.7M x 20 taxi
+       * fixture that is 38.6 MiB against the 352.8 MiB `data` retains, because a column costs four
+       * bytes per row rather than a boxed value per cell, and the symbols are a few thousand
+       * entries shared across every row that uses them.
+       *
+       * @param {number|null|{offset?: number, limit?: number|null, maxRows?: number|null}} [window]
+       *   The rows to decode, in the same spellings `load()` accepts.
+       * @return {Promise<import('./QvdColumnTable.js').QvdColumnTable>} The decoded columns.
+       */
+      async loadColumnar(window = null) {
+        const rows = normaliseWindow(window, this._path);
+        const prepared = await this._prepare(rows);
+        await this._parseIndexTable({ offset: prepared.offset, limit: prepared.rowsAvailable });
+        const { QvdColumnTable: QvdColumnTable2 } = await Promise.resolve().then(() => (init_QvdColumnTable(), QvdColumnTable_exports));
         assert2__default.default(this._indexColumns, "The QVD file index table has not been parsed.");
-        const indexColumns = this._indexColumns;
-        const fieldCount = indexColumns.length;
-        const data = new Array(this._rowsDecoded);
-        for (let row = 0; row < this._rowsDecoded; row++) {
-          const values = new Array(fieldCount);
-          for (let field = 0; field < fieldCount; field++) {
-            const symbolIndex = indexColumns[field][row];
-            values[field] = symbolIndex < 0 ? null : resolvedByField[field][symbolIndex];
-          }
-          data[row] = values;
-        }
-        loadStats.rowsLoaded = data.length;
-        return new exports.QvdDataFrame(data, columns, metadata, loadStats);
+        return new QvdColumnTable2({
+          columns: prepared.columns,
+          codesByField: this._indexColumns,
+          symbolsByField: prepared.resolvedByField,
+          rowCount: this._rowsDecoded,
+          metadata: prepared.metadata,
+          loadStats: { ...prepared.loadStats, rowsLoaded: this._rowsDecoded }
+        });
       }
       /**
-       * Reads and decodes the file, stopping short of building rows.
+       * Yields the window as data frames of at most `chunkSize` rows.
        *
-       * Everything `load()` and `loadColumnar()` have in common, which is everything except the
-       * shape of the answer. Two read paths for one binary format is the drift risk #113 is the
-       * standing example of - a stored index resolved one way here and another way there returns
-       * plausible wrong values and throws nothing - so there is one path, and the two entry points
-       * differ only in what they do with what it returns.
+       * The file is opened, read and parsed **once**; only the index decode and the row building
+       * happen per chunk. That is the whole reason this exists as a method rather than as a loop of
+       * `load({offset, limit})` calls at the call site: the symbol table has to be parsed in full
+       * whatever the chunk size - a stored index in the last chunk can address the first symbol -
+       * and re-parsing it per chunk is what makes the obvious implementation cost more than a plain
+       * load rather than less. PyQvd's chunked read does re-read it, and the comment on #140 records
+       * that as a limitation rather than a design.
        *
-       * @param {number|null} maxRows Maximum rows to decode, or null for all of them.
-       * @return {Promise<{columns: Array<string>, metadata: any, loadStats: any,
-       *   resolvedByField: Array<Array<any>>}>} The decoded file.
-       * @private
+       * What it bounds is row materialisation, which is what actually dominates a large read's heap.
+       * Two chunks of rows are alive at a time, not one - `for await` keeps the yielded frame
+       * reachable while this generator builds the next - which is why `liveRows` below is
+       * `chunkSize * 2`, and why the heap it needs is twice what one chunk suggests.
+       *
+       * A window covering no rows yields nothing at all, rather than one empty frame - so
+       * `for await` over an exhausted offset does nothing, which is what a paging loop wants.
+       *
+       * @param {number|null|{offset?: number, limit?: number|null, maxRows?: number|null}} window
+       *   The rows to cover, in the same spellings `load()` accepts.
+       * @param {number} chunkSize Rows per frame. Must be a positive integer.
+       * @return {AsyncGenerator<QvdDataFrame>} The chunks, in order.
        */
-      async _decode(maxRows = null) {
-        if (maxRows !== null && (typeof maxRows !== "number" || !Number.isInteger(maxRows) || maxRows < 0)) {
-          throw new exports.QvdValidationError("maxRows must be a non-negative integer, or null to load all rows", {
-            provided: maxRows,
-            type: typeof maxRows,
+      async *iterateRows(window, chunkSize) {
+        if (typeof chunkSize !== "number" || !Number.isInteger(chunkSize) || chunkSize <= 0) {
+          throw new exports.QvdValidationError("chunkSize must be a positive integer", {
+            provided: chunkSize,
+            type: typeof chunkSize,
             file: this._path
           });
         }
-        await this._readData(maxRows);
+        const liveRows = { rows: chunkSize * 2, perChunk: 2 };
+        const rows = normaliseWindow(window, this._path);
+        const prepared = await this._prepare(rows, liveRows);
+        for (let done = 0; done < prepared.rowsAvailable; done += chunkSize) {
+          this._throwIfAborted();
+          const count = Math.min(chunkSize, prepared.rowsAvailable - done);
+          const offset = prepared.offset + done;
+          await this._parseIndexTable({ offset, limit: count });
+          const data = this._buildRows(prepared.resolvedByField, done, prepared.rowsAvailable);
+          yield new exports.QvdDataFrame(data, prepared.columns, prepared.metadata, {
+            ...prepared.loadStats,
+            offset,
+            rowsLoaded: data.length
+          });
+        }
+      }
+      /**
+       * Reads the file and resolves its symbols, stopping short of decoding any rows.
+       *
+       * Everything `load()`, `loadColumnar()` and `iterateRows()` have in common, which is everything
+       * that depends on the file rather than on the window. Two read paths for one binary format is
+       * the drift risk #113 is the standing example of - a stored index resolved one way here and
+       * another way there returns plausible wrong values and throws nothing - so there is one path,
+       * and the entry points differ only in what they do with what it returns and how many rows they
+       * ask for at a time.
+       *
+       * @param {QvdRowWindow} window The rows the read covers.
+       * @param {{rows: number, perChunk: number}|null} [liveRows] Rows held at one instant when that
+       *   is fewer than the window covers, and how many of them one row of the caller's chunk size
+       *   accounts for. Only `iterateRows` passes it; every other read holds what it covers.
+       * @return {Promise<{columns: Array<string>, metadata: any, loadStats: any,
+       *   resolvedByField: Array<Array<any>>, rowsAvailable: number, offset: number}>} The parsed
+       *   file, with the window as it resolved against it.
+       * @private
+       */
+      async _prepare(window, liveRows = null) {
+        this._throwIfAborted();
+        await this._readData(window, false, liveRows);
+        this._emitProgress("header", 0, 1);
         await this._parseHeader();
+        this._emitProgress("header", 1, 1);
+        this._throwIfAborted();
+        assert2__default.default(this._header, "The QVD file header has not been parsed.");
+        const totalRows = parseInt(this._header["QvdTableHeader"]["NoOfRecords"], 10);
+        const symbolTableLength = parseInt(this._header["QvdTableHeader"]["Offset"], 10);
+        const resolved = resolveWindow(window, totalRows);
+        const rowsAvailable = resolved.limit;
         let symbolsToKeep = null;
         let symbolsKept = null;
-        if (maxRows !== null && this._header) {
-          const symbolTableLength = parseInt(this._header["QvdTableHeader"]["Offset"], 10);
+        if (window.limit !== null || window.offset > 0) {
           if (symbolTableLength > this._symbolFilteringThreshold) {
-            symbolsToKeep = await this._analyzeIndexTableSymbolUsage(maxRows);
-            symbolsKept = Array.from(symbolsToKeep.values()).reduce((sum, set) => sum + set.size, 0);
+            symbolsToKeep = await this._analyzeIndexTableSymbolUsage({ offset: resolved.offset, limit: rowsAvailable });
+            symbolsKept = symbolsToKeep.reduce((sum, set) => sum + set.size, 0);
           }
         }
-        await this._parseSymbolTable(symbolsToKeep, maxRows);
-        await this._parseIndexTable(maxRows);
-        assert2__default.default(this._header, "The QVD file header has not been parsed.");
+        await this._parseSymbolTable(symbolsToKeep, rowsAvailable, liveRows);
         assert2__default.default(this._symbolTable, "The QVD file symbol table has not been parsed.");
-        assert2__default.default(this._indexColumns, "The QVD file index table has not been parsed.");
+        this._throwIfAborted();
         const resolvedByField = this._symbolTable.map((symbols) => {
-          const resolved = new Array(symbols.length);
+          const resolved2 = new Array(symbols.length);
           for (let index = 0; index < symbols.length; index++) {
             const value = symbols[index]?.toPrimaryValue();
-            resolved[index] = typeof value === "string" && value.trim() !== "" && !isNaN(Number(value)) ? Number(value) : value;
+            resolved2[index] = typeof value === "string" && value.trim() !== "" && !isNaN(Number(value)) ? Number(value) : value;
           }
-          return resolved;
+          return resolved2;
         });
-        let fields = this._header["QvdTableHeader"]["Fields"]["QvdFieldHeader"];
-        if (!Array.isArray(fields)) {
-          fields = [fields];
-        }
-        const columns = fields.map((field) => field["FieldName"]);
+        assert2__default.default(this._selectedFields, "The QVD file fields have not been resolved.");
+        const columns = this._selectedFields.map((field) => field["FieldName"]);
         const metadata = this._header["QvdTableHeader"];
         const loadStats = {
-          symbolTableBytes: parseInt(this._header["QvdTableHeader"]["Offset"], 10),
-          totalRows: parseInt(this._header["QvdTableHeader"]["NoOfRecords"], 10),
-          rowsLoaded: this._rowsDecoded,
+          symbolTableBytes: symbolTableLength,
+          totalRows,
+          rowsLoaded: 0,
+          offset: resolved.offset,
           symbolFiltering: symbolsToKeep !== null,
           symbolsKept
         };
-        return { columns, metadata, loadStats, resolvedByField };
+        return { columns, metadata, loadStats, resolvedByField, rowsAvailable, offset: resolved.offset };
       }
       /**
-       * Reads the file as columns, without ever materialising rows.
+       * Builds rows from the columns currently decoded.
        *
-       * Shares every step with `load()` up to the point where rows would be built - see `_decode`.
-       * What it keeps instead is what the decoder already produced: one `Int32Array` of stored
-       * indices per field, and one resolved value per distinct symbol. On the 1.7M x 20 taxi
-       * fixture that is 38.6 MiB against the 352.8 MiB `data` retains, because a column costs four
-       * bytes per row rather than a boxed value per cell, and the symbols are a few thousand
-       * entries shared across every row that uses them.
+       * `data` stays eager: of the four ways this library is used - a full read, a preview already
+       * bounded by a limit, writing an array out, and reading metadata - not one is helped by
+       * materialising a row only when it is touched, and a lazy accessor would cost a proxy, a cache
+       * and mutation semantics to serve none of them. A caller who wants columns without paying for
+       * rows uses `QvdColumnTable`, which stops before this loop.
        *
-       * @param {number|null} maxRows The maximum number of rows to decode.
-       * @return {Promise<import('./QvdColumnTable.js').QvdColumnTable>} The decoded columns.
+       * @param {Array<Array<any>>} resolvedByField One resolved value per distinct symbol, per field.
+       * @param {number} progressBase Rows already delivered before this call, so that progress over a
+       *   chunked iteration counts the whole window rather than restarting at every chunk.
+       * @param {number} progressTotal Rows the whole window covers.
+       * @return {Array<Array<any>>} The rows.
+       * @private
        */
-      async loadColumnar(maxRows = null) {
-        const { columns, metadata, loadStats, resolvedByField } = await this._decode(maxRows);
-        const { QvdColumnTable: QvdColumnTable2 } = await Promise.resolve().then(() => (init_QvdColumnTable(), QvdColumnTable_exports));
+      _buildRows(resolvedByField, progressBase, progressTotal) {
         assert2__default.default(this._indexColumns, "The QVD file index table has not been parsed.");
-        return new QvdColumnTable2({
-          columns,
-          codesByField: this._indexColumns,
-          symbolsByField: resolvedByField,
-          rowCount: this._rowsDecoded,
-          metadata,
-          loadStats
-        });
+        const indexColumns = this._indexColumns;
+        const fieldCount = indexColumns.length;
+        const rowCount = this._rowsDecoded;
+        const data = new Array(rowCount);
+        const reportInterval = Math.max(1, Math.floor(progressTotal / 100));
+        for (let row = 0; row < rowCount; row++) {
+          const values = new Array(fieldCount);
+          for (let field = 0; field < fieldCount; field++) {
+            const symbolIndex = indexColumns[field][row];
+            values[field] = symbolIndex < 0 ? null : resolvedByField[field][symbolIndex];
+          }
+          data[row] = values;
+          if ((progressBase + row + 1) % reportInterval === 0 || row + 1 === rowCount) {
+            this._throwIfAborted();
+            this._emitProgress("rows", progressBase + row + 1, progressTotal);
+          }
+        }
+        return data;
       }
     };
   }
@@ -2387,6 +2822,7 @@ exports.QvdDataFrame = void 0;
 var init_QvdDataFrame = __esm({
   "src/QvdDataFrame.js"() {
     init_QvdErrors();
+    init_readOptions();
     exports.QvdDataFrame = class _QvdDataFrame {
       /**
        * Represents the data frame stored inside a QVD file.
@@ -2429,12 +2865,15 @@ var init_QvdDataFrame = __esm({
       /**
        * Returns statistics about the read that produced this data frame.
        *
-       * Only a frame returned by fromQvd() carries these; fromDict(), head() and tail() produce
-       * frames that describe no particular read, and report null rather than a stale figure.
+       * Carried by every frame that came from a file - `fromQvd()`, and each chunk `iterate()` yields,
+       * which is how a chunk reports its `offset`. `fromDict()`, `head()`, `tail()`, `rows()` and
+       * `select()` describe no particular read and report null rather than a stale figure.
        *
        * The main use is confirming that a lazy load actually filtered the symbol table:
        * `symbolFiltering` says whether the two-pass path ran, and `symbolsKept` how many symbols
-       * survived it, which for a small maxRows should be a tiny fraction of the file's total.
+       * survived it. Note that a bounded read does not filter on its own - the two-pass path engages
+       * only above `symbolFilteringThreshold`, so on a file below it this reports false and every
+       * symbol was parsed however few rows were asked for.
        *
        * @return {QvdLoadStats|null} Load statistics, or null if this frame did not come from a file.
        */
@@ -2811,6 +3250,18 @@ var init_QvdDataFrame = __esm({
        * @param {Object} [options] Optional loading options.
        * @param {number|null} [options.maxRows] The maximum number of rows to load. Must be a non-negative
        *   integer; if not specified or null, all rows are loaded. Anything else throws a QvdValidationError.
+       *   This is the older name for `limit`; the two are the same option and passing both throws.
+       * @param {number|null} [options.limit] Rows to read, counting from `offset`. The same number as
+       *   `maxRows`, spelled so that it reads correctly beside an offset.
+       * @param {number} [options.offset=0] File row to start at. An offset past the end of the file
+       *   returns no rows rather than throwing, so a paging loop terminates on its own.
+       * @param {Array<string>|null} [options.fields] Field names to read, in the order they should
+       *   appear in the result. Unselected fields have their symbols skipped entirely rather than
+       *   parsed and discarded. An unknown or repeated name throws.
+       * @param {Function} [options.onProgress] Called with `{stage, current, total, percent}` as the
+       *   read proceeds - the same shape `toQvd`'s callback receives.
+       * @param {AbortSignal} [options.signal] Cancels the read. The rejection is `signal.reason`,
+       *   which is a `DOMException` named `AbortError` unless you aborted with a reason of your own.
        * @param {string} [options.allowedDir] Optional allowed directory path. If provided, the file path
        *   must be within this directory, with symlinks resolved first, so a link inside it that points
        *   outside it is rejected. Defaults to the current working directory. To permit an entire
@@ -2823,17 +3274,42 @@ var init_QvdDataFrame = __esm({
        *   **Zero disables the memory check entirely.**
        * @param {number} [options.symbolFilteringThreshold=52428800] Symbol table size, in bytes, above which
        *   a lazy load switches to the two-pass filtering path. Defaults to 50MB.
-       * @throws {QvdValidationError} If options.maxRows is neither null/undefined nor a non-negative integer.
+       * @throws {QvdValidationError} If a window option is not a non-negative integer, if both
+       *   `maxRows` and `limit` are given, or if `fields` names a column the file does not have.
        * @return {Promise<QvdDataFrame>} The data frame of the QVD file.
        */
       static async fromQvd(path3, options = {}) {
         const { QvdFileReader: QvdFileReader2 } = await Promise.resolve().then(() => (init_QvdFileReader(), QvdFileReader_exports));
-        const readerOptions = {
-          allowedDir: options.allowedDir,
-          memorySafetyFactor: options.memorySafetyFactor,
-          symbolFilteringThreshold: options.symbolFilteringThreshold
-        };
-        return await new QvdFileReader2(path3, readerOptions).load(options.maxRows !== void 0 ? options.maxRows : null);
+        return await new QvdFileReader2(path3, readerOptionsFrom(options)).load(windowFrom(options));
+      }
+      /**
+       * Reads a QVD file in chunks, as an async generator of data frames.
+       *
+       * The file is opened, read and parsed once; only the index decode and the row building happen
+       * per chunk, so what this bounds is row materialisation - the part that actually dominates a
+       * large read's heap. It is **not** constant-memory reading of an arbitrarily large file: the
+       * symbol table is parsed in full whatever the chunk size, because a stored index in the last
+       * chunk can address the first symbol. On a high-cardinality file that table is the bulk of the
+       * cost, and `readMetadata` is the only read that avoids it.
+       *
+       * ```js
+       * for await (const chunk of QvdDataFrame.iterate('big.qvd', {chunkSize: 50_000})) {
+       *   process(chunk.data);
+       * }
+       * ```
+       *
+       * A window covering no rows yields nothing, so a loop over an exhausted offset simply does not
+       * run its body.
+       *
+       * @param {string} path The path to the QVD file.
+       * @param {Object} [options] The same options `fromQvd` takes, plus:
+       * @param {number} [options.chunkSize=100000] Rows per frame. Must be a positive integer.
+       * @return {AsyncGenerator<QvdDataFrame>} The chunks, in file order.
+       */
+      static async *iterate(path3, options = {}) {
+        const { QvdFileReader: QvdFileReader2 } = await Promise.resolve().then(() => (init_QvdFileReader(), QvdFileReader_exports));
+        const reader = new QvdFileReader2(path3, readerOptionsFrom(options));
+        yield* reader.iterateRows(windowFrom(options), options.chunkSize === void 0 ? 1e5 : options.chunkSize);
       }
       /**
        * Reads a QVD file's schema and header metadata, without reading its data.
@@ -2857,11 +3333,15 @@ var init_QvdDataFrame = __esm({
        * @param {Object} [options] Optional reading options.
        * @param {string} [options.allowedDir] Optional allowed directory path, applied exactly as it
        *   is for `fromQvd`.
+       * @param {Function} [options.onProgress] Called with `{stage, current, total, percent}`, as on
+       *   the reads that return data. Only the `read` and `header` stages occur here; there are no
+       *   symbols to parse and no rows to build.
+       * @param {AbortSignal} [options.signal] Cancels the read, rejecting with `signal.reason`.
        * @return {Promise<QvdFileMetadata>} The file's schema and header metadata.
        */
       static async readMetadata(path3, options = {}) {
         const { QvdFileReader: QvdFileReader2 } = await Promise.resolve().then(() => (init_QvdFileReader(), QvdFileReader_exports));
-        return await new QvdFileReader2(path3, { allowedDir: options.allowedDir }).loadMetadata();
+        return await new QvdFileReader2(path3, metadataOptionsFrom(options)).loadMetadata();
       }
       /**
        * Constructs a data frame from a dictionary.