qvdjs 2.0.6 → 2.1.0

package/README.md

@@ -80,6 +80,7 @@ holds.
 | Rows from a file too large to hold       | `QvdDataFrame.iterate(path, {chunkSize})` | Everything, but holds two chunks — a 96 MB heap against 512 MB       |
 | A few columns of a large file            | `QvdColumnTable.fromQvd(path)`            | Everything, but stops before building rows — 141 MiB against 385 MiB |
 | Only the schema: names, row count, types | `QvdDataFrame.readMetadata(path)`         | The header alone. Constant cost, whatever the file's size            |
+| To know whether a read will fit first    | `QvdDataFrame.checkRead(path, options)`   | The header alone. Answers rather than reads; a read it approves is not refused for memory |
 
 ```javascript
 import {QvdDataFrame, QvdColumnTable} from 'qvdjs';
@@ -87,6 +88,9 @@ import {QvdDataFrame, QvdColumnTable} from 'qvdjs';
 // What is in this file? Costs the same whether it is 20 KB or 20 GB.
 const {columns, rowCount} = await QvdDataFrame.readMetadata('sales.qvd');
 
+// Will reading it fit? Also the header alone, and every suggestion it gives has been checked.
+const {fits, suggestions} = await QvdDataFrame.checkRead('sales.qvd');
+
 // Sum one column without ever building a row.
 const table = await QvdColumnTable.fromQvd('sales.qvd');
 let total = 0;

package/dist/index.cjs

@@ -453,7 +453,9 @@ var init_optionTypes = __esm({
 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`, {
+      reason: "option",
       option: name,
+      value,
       provided: value,
       type: typeof value,
       file: filePath
@@ -470,6 +472,9 @@ function normaliseWindow(window, 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", {
+      reason: "option",
+      option: "limit",
+      value: window,
       provided: window,
       type: typeof window,
       file: filePath
@@ -480,6 +485,9 @@ function normaliseWindow(window, filePath) {
   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", {
+      reason: "option",
+      option: "limit",
+      value: limit,
       maxRows,
       limit,
       file: filePath
@@ -490,6 +498,19 @@ function normaliseWindow(window, filePath) {
     limit: limitGiven ? requireRowCount(limit, "limit", filePath) : maxRowsGiven ? requireRowCount(maxRows, "maxRows", filePath) : null
   };
 }
+function requireChunkSize(chunkSize, filePath) {
+  if (typeof chunkSize !== "number" || !Number.isInteger(chunkSize) || chunkSize <= 0) {
+    throw new exports.QvdValidationError("chunkSize must be a positive integer", {
+      reason: "option",
+      option: "chunkSize",
+      value: chunkSize,
+      provided: chunkSize,
+      type: typeof chunkSize,
+      file: filePath
+    });
+  }
+  return chunkSize;
+}
 function resolveWindow(window, totalRows) {
   const rows = Number.isSafeInteger(totalRows) && totalRows > 0 ? totalRows : 0;
   const offset = Math.min(window.offset, rows);
@@ -504,6 +525,9 @@ function selectFields(fields, requested, filePath) {
   }
   if (!Array.isArray(requested)) {
     throw new exports.QvdValidationError("fields must be an array of field names", {
+      reason: "option",
+      option: "fields",
+      value: requested,
       provided: requested,
       type: typeof requested,
       file: filePath
@@ -512,6 +536,9 @@ function selectFields(fields, requested, filePath) {
   const available = fields.map((field) => field["FieldName"]);
   if (requested.length === 0) {
     throw new exports.QvdValidationError("fields must name at least one field", {
+      reason: "option",
+      option: "fields",
+      value: requested,
       availableColumns: available,
       file: filePath
     });
@@ -520,6 +547,9 @@ function selectFields(fields, requested, filePath) {
   return requested.map((name) => {
     if (typeof name !== "string") {
       throw new exports.QvdValidationError("Field names must be strings", {
+        reason: "option",
+        option: "fields",
+        value: name,
         provided: name,
         type: typeof name,
         availableColumns: available,
@@ -528,6 +558,9 @@ function selectFields(fields, requested, filePath) {
     }
     if (seen.has(name)) {
       throw new exports.QvdValidationError(`Field '${name}' is listed twice`, {
+        reason: "option",
+        option: "fields",
+        value: name,
         column: name,
         fields: requested,
         file: filePath
@@ -537,6 +570,9 @@ function selectFields(fields, requested, filePath) {
     const index = available.indexOf(name);
     if (index === -1) {
       throw new exports.QvdValidationError(`Column '${name}' does not exist`, {
+        reason: "option",
+        option: "fields",
+        value: name,
         column: name,
         availableColumns: available,
         file: filePath
@@ -551,7 +587,9 @@ function normaliseDuals(value, filePath) {
   }
   if (!DUAL_MODES.includes(value)) {
     throw new exports.QvdValidationError(`duals must be one of ${DUAL_MODES.map((mode) => `'${mode}'`).join(", ")}`, {
+      reason: "option",
       option: "duals",
+      value,
       provided: value,
       file: filePath
     });
@@ -590,6 +628,7 @@ var init_readOptions = __esm({
     init_optionTypes();
     __name(requireRowCount, "requireRowCount");
     __name(normaliseWindow, "normaliseWindow");
+    __name(requireChunkSize, "requireChunkSize");
     __name(resolveWindow, "resolveWindow");
     __name(selectFields, "selectFields");
     DUAL_MODES = Object.freeze(["number", "text", "both"]);
@@ -2218,22 +2257,56 @@ function recommendedChunkFor(budget, symbolTableSize, windowRows, totalRows, col
   }
   return low;
 }
-function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePath, safetyFactor = 0.8, columnCount = 0, materialisesRows = true, live = null, bytesHeld = 0) {
-  if (typeof safetyFactor !== "number" || safetyFactor < 0 || safetyFactor > 1) {
-    throw new exports.QvdValidationError("safetyFactor must be a number between 0.0 and 1.0", { safetyFactor });
-  }
-  if (safetyFactor === 0) {
+function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePath, safetyFactor = 0.8, columnCount = 0, materialisesRows = true, live = null, bytesHeld = null, readBytes = null) {
+  const answer = checkMemory({
+    symbolTableSize,
+    maxRows,
+    totalRows,
+    safetyFactor,
+    columnCount,
+    materialisesRows,
+    live,
+    bytesHeld,
+    readBytes
+  });
+  if (answer.fits) {
     return;
   }
-  const budget = getMemoryBudget();
+  const { message, context } = answer.refusal;
+  throw new exports.QvdValidationError(message, {
+    file: filePath,
+    ...context,
+    reason: "memory",
+    check: answerOf(answer)
+  });
+}
+function checkMemory({
+  symbolTableSize,
+  maxRows,
+  totalRows,
+  safetyFactor = 0.8,
+  columnCount = 0,
+  materialisesRows = true,
+  live = null,
+  bytesHeld = null,
+  readBytes = null,
+  measured = 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,
+      reason: "option",
+      option: "memorySafetyFactor",
+      value: safetyFactor
+    });
+  }
+  const budget = measured ?? getMemoryBudget();
   const rowsToLoad = maxRows === null || maxRows >= totalRows ? totalRows : maxRows;
   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 held = typeof bytesHeld === "number" ? bytesHeld : bytesHeld.held;
-  const heldForRows = typeof bytesHeld === "number" ? () => bytesHeld : bytesHeld.forRows;
-  const heldForChunk = typeof bytesHeld === "number" ? () => bytesHeld : bytesHeld.forChunk;
+  const { held, forRows: heldForRows, forChunk: heldForChunk } = bytesHeld ?? noBytesHeld;
   const externalMemory = estimateExternalMemory(liveRows, columnCount) + held;
   const bounded = budget.candidates.map((candidate) => {
     const heapOnly = candidate.source === "V8 heap limit";
@@ -2245,11 +2318,26 @@ function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePat
       bounds: heapOnly ? "the V8 heap" : "the whole process"
     };
   });
-  const exceeded = bounded.filter((candidate) => candidate.needs > candidate.allowed);
-  const binding = exceeded.reduce(
-    (worst, candidate) => candidate.needs / candidate.allowed > worst.needs / worst.allowed ? candidate : worst,
-    exceeded[0]
+  if (safetyFactor === 0) {
+    const lowest = budget.candidates.reduce((least, candidate) => candidate.bytes < least.bytes ? candidate : least);
+    return {
+      fits: true,
+      estimate: { heapBytes: heapMemory, externalBytes: externalMemory, readBytes },
+      // The ceilings are still there and still named - what is missing is any measurement against them.
+      // An earlier version reported `bound: 'none'` here, a third value in a two-value vocabulary that a
+      // caller switching on the documented two would fall straight through.
+      budget: {
+        ...budgetOf(budget, { ...lowest, heapOnly: lowest.source === "V8 heap limit" }, 0),
+        allowedBytes: Infinity
+      },
+      exact: symbolTableSize === 0,
+      suggestions: []
+    };
+  }
+  const tightest = bounded.reduce(
+    (worst, candidate) => candidate.needs / candidate.allowed > worst.needs / worst.allowed ? candidate : worst
   );
+  const binding = tightest.needs > tightest.allowed ? tightest : null;
   const heapLimit = getHeapLimit();
   const availableMemory = binding ? binding.bytes : budget.bytes;
   const estimatedMemory = binding ? binding.needs : heapMemory;
@@ -2306,31 +2394,75 @@ function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePat
     } else {
       advice = `Try holding fewer rows using the ${knob} parameter (recommended: ${formatCount(recommendedValue)} 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,
-      {
-        file: filePath,
-        symbolTableSize,
-        symbolTableSizeMB: sizeMB,
-        estimatedMemoryMB: estimatedMB,
-        availableMemoryMB: availableMB,
-        heapLimitMB,
-        reportedHeapLimitMB,
-        availableRamMB,
-        limitingFactor,
-        limitingScope,
-        memoryBudget: budget.candidates,
-        memoryObserved: budget.observed,
-        columnCount,
-        totalRows,
-        maxRows,
-        recommendedMaxRows,
-        // Only present when a chunk size is what overflowed, so a caller cannot mistake one
-        // recommendation for the other.
-        ...chunked ? { rowsLive, recommendedChunkSize: recommendedChunk } : {}
+    const suggestions = [];
+    if (!nothingFits) {
+      suggestions.push({ option: knob, value: recommendedValue });
+    }
+    if (!containerBound) {
+      let needed = Math.ceil(estimatedMemory / safetyFactor / (1024 * 1024));
+      while (Math.max(needed * 1024 * 1024, MINIMUM_BUDGET_BYTES) * safetyFactor < estimatedMemory) {
+        needed += 1;
       }
-    );
+      suggestions.push({ nodeOption: "--max-old-space-size", value: needed });
+    }
+    return {
+      fits: false,
+      reason: "memory",
+      estimate: { heapBytes: heapMemory, externalBytes: externalMemory, readBytes },
+      budget: budgetOf(budget, tightest, safetyFactor),
+      // The symbol term is six times the bytes on disk, an overhead measured across files rather than
+      // derived, so any read with symbols in it is an estimate and says so. Only a read that decodes
+      // nothing can be exact.
+      exact: symbolTableSize === 0,
+      suggestions,
+      refusal: {
+        message: `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,
+        context: {
+          symbolTableSize,
+          symbolTableSizeMB: sizeMB,
+          estimatedMemoryMB: estimatedMB,
+          availableMemoryMB: availableMB,
+          heapLimitMB,
+          reportedHeapLimitMB,
+          availableRamMB,
+          limitingFactor,
+          limitingScope,
+          memoryBudget: budget.candidates,
+          memoryObserved: budget.observed,
+          columnCount,
+          totalRows,
+          maxRows,
+          recommendedMaxRows,
+          // Only present when a chunk size is what overflowed, so a caller cannot mistake one
+          // recommendation for the other.
+          ...chunked ? { rowsLive, recommendedChunkSize: recommendedChunk } : {}
+        }
+      }
+    };
   }
+  return {
+    fits: true,
+    estimate: { heapBytes: heapMemory, externalBytes: externalMemory, readBytes },
+    budget: budgetOf(budget, tightest, safetyFactor),
+    exact: symbolTableSize === 0,
+    suggestions: []
+  };
+}
+function answerOf(answer) {
+  const { refusal, ...rest } = answer;
+  return rest;
+}
+function budgetOf(budget, tightest, safetyFactor) {
+  const processLimit = budget.candidates.find((candidate) => candidate.source !== "V8 heap limit");
+  return {
+    heapBytes: usableOldSpaceLimit(),
+    processBytes: processLimit ? processLimit.bytes : null,
+    bound: tightest.heapOnly ? "heap" : "process",
+    safetyFactor,
+    allowedBytes: tightest.allowed ?? tightest.bytes * safetyFactor,
+    candidates: budget.candidates,
+    observed: budget.observed
+  };
 }
 function formatCount(value) {
   return value.toLocaleString("en-US");
@@ -2352,7 +2484,7 @@ function warnLargeSymbolTable(symbolTableSize, maxRows, totalRows, columnCount =
     `\u26A0\uFE0F  Large symbol table detected (${sizeMB}MB > ${warnMB}MB threshold). This read materialises ${formatCount(rowsToLoad)} of ${formatCount(totalRows)} 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 HEAP_LIMIT_OVERSTATEMENT_BYTES, MINIMUM_BUDGET_BYTES, BASE_BYTES, ROW_BASE_BYTES, PER_CELL_BYTES, noBytesHeld;
 var init_memoryUtils = __esm({
   "src/util/memoryUtils.js"() {
     init_QvdErrors();
@@ -2370,7 +2502,11 @@ var init_memoryUtils = __esm({
     __name(estimateMemoryUsage, "estimateMemoryUsage");
     __name(recommendedRowsFor, "recommendedRowsFor");
     __name(recommendedChunkFor, "recommendedChunkFor");
+    noBytesHeld = Object.freeze({ held: 0, forRows: /* @__PURE__ */ __name(() => 0, "forRows"), forChunk: /* @__PURE__ */ __name(() => 0, "forChunk") });
     __name(validateMemoryAvailability, "validateMemoryAvailability");
+    __name(checkMemory, "checkMemory");
+    __name(answerOf, "answerOf");
+    __name(budgetOf, "budgetOf");
     __name(formatCount, "formatCount");
     __name(warnLargeSymbolTable, "warnLargeSymbolTable");
   }
@@ -3455,6 +3591,16 @@ async function parseHeaderXml(text, file, stage) {
   }
   return parsed;
 }
+function symbolBytesOf(selected, symbolTableLength) {
+  const areaBytes = selected.map((field) => headerInteger(field["Length"]));
+  return areaBytes.every((bytes) => Number.isSafeInteger(bytes) && bytes >= 0) ? Math.min(
+    symbolTableLength,
+    areaBytes.reduce((sum, bytes) => sum + bytes, 0)
+  ) : symbolTableLength;
+}
+function readPasses(analysisAhead) {
+  return analysisAhead ? 2 : 1;
+}
 var MAX_HEADER_SIZE, READ_CHUNK_SIZE, ANALYSIS_SLICE_ROWS, SLICE_BYTES, COUNT_SYMBOLS_PAST; exports.QvdFileReader = void 0;
 var init_QvdFileReader = __esm({
   "src/QvdFileReader.js"() {
@@ -3477,6 +3623,8 @@ var init_QvdFileReader = __esm({
     COUNT_SYMBOLS_PAST = 65536;
     __name(chunksFrom, "chunksFrom");
     __name(parseHeaderXml, "parseHeaderXml");
+    __name(symbolBytesOf, "symbolBytesOf");
+    __name(readPasses, "readPasses");
     exports.QvdFileReader = class {
       static {
         __name(this, "QvdFileReader");
@@ -3818,6 +3966,15 @@ var init_QvdFileReader = __esm({
         const indexTableOffset = symbolTableOffset + symbolTableLength;
         const recordSize = headerInteger(headerObj["QvdTableHeader"]["RecordByteSize"]);
         const totalRows = headerInteger(headerObj["QvdTableHeader"]["NoOfRecords"]);
+        const { size: fileSize } = await handle.stat().catch(failed);
+        this._fileSize = fileSize;
+        this._headerMatchesFile = false;
+        const headerNumbersUsable = [symbolTableLength, recordSize, totalRows].every(
+          (value) => Number.isSafeInteger(value) && value >= 0
+        );
+        if (headerNumbersUsable) {
+          this._headerMatchesFile = headerEndIndex + symbolTableLength + totalRows * recordSize <= fileSize;
+        }
         if (headerOnly) {
           this._headerBuffer = headerBuffer.subarray(0, headerEndIndex);
           this._emitProgress("read", 1, 1);
@@ -3826,20 +3983,7 @@ var init_QvdFileReader = __esm({
         this._headerBuffer = headerBuffer.subarray(0, headerEndIndex);
         const selected = selectFields(headerFields, this._requestedFields, this._path);
         const columnCount = selected.length;
-        const areaBytes = selected.map((field) => headerInteger(field["Length"]));
-        const symbolBytes = areaBytes.every((bytes) => Number.isSafeInteger(bytes) && bytes >= 0) ? Math.min(
-          symbolTableLength,
-          areaBytes.reduce((sum, bytes) => sum + bytes, 0)
-        ) : symbolTableLength;
-        const headerNumbersUsable = [symbolTableLength, recordSize, totalRows].every(
-          (value) => Number.isSafeInteger(value) && value >= 0
-        );
-        const { size: fileSize } = await handle.stat().catch(failed);
-        this._fileSize = fileSize;
-        this._headerMatchesFile = false;
-        if (headerNumbersUsable) {
-          this._headerMatchesFile = headerEndIndex + symbolTableLength + totalRows * recordSize <= fileSize;
-        }
+        const symbolBytes = symbolBytesOf(selected, symbolTableLength);
         const resolved = headerNumbersUsable ? resolveWindow(window, totalRows) : { offset: 0, limit: 0 };
         const windowRows = resolved.limit;
         if (headerNumbersUsable && this._headerMatchesFile) {
@@ -3858,7 +4002,14 @@ var init_QvdFileReader = __esm({
               recordSize,
               liveRows,
               this._analysisWouldRun(window, resolved, totalRows, symbolTableLength)
-            )
+            ),
+            // What it reads, which is not what it holds - the records go through one buffer and are not
+            // kept. Carried so that a refusal's `check` says everything the pre-flight would have said.
+            //
+            // Twice over where the symbol-usage pass is still ahead of it: that pass reads the window's
+            // records to find which symbols the rows use, and the decode then reads them again. Counted
+            // once, the figure understated the I/O of exactly the reads that do the most of it.
+            symbolBytes + readPasses(this._analysisWouldRun(window, resolved, totalRows, symbolTableLength)) * windowRows * recordSize
           );
         }
         if (window.offset === 0 && window.limit === null) {
@@ -3927,8 +4078,9 @@ var init_QvdFileReader = __esm({
        *
        * The areas are counted whole, although the read lets each range go once its fields are parsed, because
        * two ranges are both live when a field of one is parsed between two fields of the other - the order the
-       * caller asked for the fields decides it, so the sum is what holds in every order. The slice is what
-       * `_forEachSlice` will allocate: `sliceBytes` unless the records are fewer.
+       * caller asked for the fields decides it, so the sum is what holds in every order. The slice is the
+       * buffer `_forEachSlice` will allocate, sized by `_sliceRowsFor` so that the charge and the allocation
+       * are one expression rather than two that agree today.
        *
        * @param {number} symbolBytes Bytes of symbols the read will read.
        * @param {number} rows Records it will read.
@@ -3937,8 +4089,24 @@ var init_QvdFileReader = __esm({
        * @private
        */
       _bytesHeldBy(symbolBytes, rows, recordSize) {
-        const records = Number.isSafeInteger(rows) && Number.isSafeInteger(recordSize) ? rows * recordSize : 0;
-        return symbolBytes + Math.min(this._sliceBytes, Math.max(0, records));
+        const usable = Number.isSafeInteger(rows) && Number.isSafeInteger(recordSize) && rows > 0 && recordSize > 0;
+        return symbolBytes + (usable ? this._sliceRowsFor(rows, recordSize) * recordSize : 0);
+      }
+      /**
+       * Records the one buffer holds while a read of `rowCount` records goes through it.
+       *
+       * A slice is `sliceBytes` of records, rounded down to a whole record, or every record the read has left
+       * when that is fewer - and at least one, since a read of a record wider than `sliceBytes` still has to
+       * hold that record. The single definition: `_forEachSlice` allocates from it and the memory guard is
+       * charged from it, so a change to how a read slices cannot leave the guard pricing the old rule.
+       *
+       * @param {number} rowCount Records the read will read.
+       * @param {number} recordSize Bytes per record.
+       * @return {number} Records in one slice.
+       * @private
+       */
+      _sliceRowsFor(rowCount, recordSize) {
+        return Math.max(1, Math.min(rowCount, Math.floor(this._sliceBytes / Math.max(1, recordSize))));
       }
       /**
        * What a read holds in bytes of the file, for the memory guard: what it holds now, and what a read
@@ -4154,7 +4322,7 @@ var init_QvdFileReader = __esm({
           return;
         }
         assert4__default.default(this._indexTableOffset !== null, "The QVD file header has not been parsed before its records were read.");
-        const sliceRows = Math.max(1, Math.min(rowCount, Math.floor(this._sliceBytes / Math.max(1, recordSize))));
+        const sliceRows = this._sliceRowsFor(rowCount, recordSize);
         const slice = Buffer.alloc(sliceRows * recordSize);
         const requiredBytes = this._indexTableOffset + (firstRow + rowCount) * recordSize;
         for (let done = 0; done < rowCount; done += sliceRows) {
@@ -4407,7 +4575,10 @@ var init_QvdFileReader = __esm({
             fields.length,
             this._materialisesRows,
             liveRows,
-            this._bytesHeld(symbolBytes, rowsToLoad, recordSize, liveRows, false)
+            this._bytesHeld(symbolBytes, rowsToLoad, recordSize, liveRows, false),
+            // `symbolsToKeep` is non-null exactly when the symbol-usage pass has run, and a pass that has
+            // run has read the window's records once already - so the read's total is two passes over them.
+            symbolBytes + readPasses(symbolsToKeep !== null) * rowsToLoad * recordSize
           );
         }
         warnLargeSymbolTable(symbolBytes, rowsToLoad, totalRows, fields.length, this._materialisesRows);
@@ -4552,6 +4723,95 @@ var init_QvdFileReader = __esm({
           };
         });
       }
+      /**
+       * What a read of this file would cost, and whether it fits, without reading it.
+       *
+       * Reads the header and the file's size and nothing else, at the constant cost of `loadMetadata()`,
+       * then asks the same question a read asks before it allocates anything - through the same function,
+       * from the same numbers. That is the whole point: an answer computed a second way would be a second
+       * opinion, and a read this approves would still be refused.
+       *
+       * @param {number|null|{offset?: number, limit?: number|null, maxRows?: number|null}} [rawWindow]
+       *   The rows the read would cover, spelled any of the ways a read accepts.
+       * @param {{chunkSize?: number|null}} [options] `chunkSize` when the read would be an `iterate()`,
+       *   which holds two chunks of rows rather than the window.
+       * @return {Promise<any>} The answer - see `checkMemory`.
+       */
+      async checkRead(rawWindow, { chunkSize = null } = {}) {
+        const window = normaliseWindow(rawWindow, this._path);
+        return await this._closingAfter(async () => {
+          await this._readData({ offset: 0, limit: null }, true);
+          this._emitProgress("header", 0, 1);
+          await this._parseHeader();
+          this._emitProgress("header", 1, 1);
+          this._throwIfAborted();
+          assert4__default.default(
+            this._header && this._selectedFields && this._allFields && this._symbolTableOffset !== null,
+            "The QVD file header has not been parsed."
+          );
+          const header = this._header["QvdTableHeader"];
+          const totalRows = headerInteger(header["NoOfRecords"]);
+          const recordSize = headerInteger(header["RecordByteSize"]);
+          const symbolTableLength = headerInteger(header["Offset"]);
+          const selected = this._selectedFields;
+          validateRecordSize(recordSize, this._path, "checkRead");
+          validateRecordCount(totalRows, this._path, "checkRead");
+          if (!this._headerMatchesFile) {
+            throw new exports.QvdCorruptedError("The file is shorter than its header claims.", {
+              file: this._path,
+              fileSize: this._fileSize,
+              requiredBytes: this._symbolTableOffset + symbolTableLength + totalRows * recordSize,
+              stage: "checkRead"
+            });
+          }
+          const tableLength = this._symbolTableLength();
+          for (const field of this._allFields) {
+            validateFieldMetadata(field, tableLength, this._path);
+            validateFieldBitMetadata(field, recordSize, this._path);
+          }
+          validateSymbolAreas(this._allFields, this._path);
+          const resolved = resolveWindow(window, totalRows);
+          const windowRows = resolved.limit;
+          const liveRows = chunkSize === null ? null : { rows: chunkSize * 2, perChunk: 2 };
+          const analysisAhead = this._analysisWouldRun(window, resolved, totalRows, symbolTableLength);
+          const measured = getMemoryBudget();
+          const ask = /* @__PURE__ */ __name((fields, rows) => {
+            const bytes = symbolBytesOf(fields, symbolTableLength);
+            return checkMemory({
+              measured,
+              symbolTableSize: bytes,
+              maxRows: rows,
+              totalRows,
+              safetyFactor: this._memorySafetyFactor,
+              columnCount: fields.length,
+              materialisesRows: this._materialisesRows,
+              live: liveRows,
+              bytesHeld: this._bytesHeld(bytes, rows, recordSize, liveRows, analysisAhead),
+              // What it reads from the file, which is not what it holds: the symbol areas, and every record
+              // the window covers, read a slice at a time and not kept - twice over where the symbol-usage
+              // pass will run, since it reads them before the decode reads them again.
+              readBytes: bytes + readPasses(analysisAhead) * windowRows * recordSize
+            });
+          }, "ask");
+          const answer = ask(selected, windowRows);
+          if (!answer.fits && selected.length > 1) {
+            const bySize = [...selected].sort(
+              (a, b) => headerInteger(a["Length"]) - headerInteger(b["Length"])
+            );
+            for (let take = selected.length - 1; take >= 1; take -= 1) {
+              const fewer = bySize.slice(0, take);
+              if (ask(fewer, windowRows).fits) {
+                answer.suggestions.push({
+                  option: "fields",
+                  value: fewer.map((field) => field["FieldName"])
+                });
+                break;
+              }
+            }
+          }
+          return answer;
+        });
+      }
       /**
        * Loads the QVD file into memory and parses it.
        *
@@ -4641,13 +4901,7 @@ var init_QvdFileReader = __esm({
        * @return {AsyncGenerator<QvdDataFrame>} The chunks, in order.
        */
       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
-          });
-        }
+        requireChunkSize(chunkSize, this._path);
         const liveRows = { rows: chunkSize * 2, perChunk: 2 };
         const rows = normaliseWindow(window, this._path);
         this._startRead();
@@ -5562,6 +5816,68 @@ var init_QvdDataFrame = __esm({
         const { QvdFileReader: QvdFileReader2 } = await Promise.resolve().then(() => (init_QvdFileReader(), QvdFileReader_exports));
         return await new QvdFileReader2(path5, metadataOptionsFrom(options)).loadMetadata();
       }
+      /**
+       * Answers what a read would cost, and whether it fits, without doing it.
+       *
+       * Takes the options `fromQvd()` takes, plus `as` and `chunkSize` to say which read is being asked
+       * about. Reads the header and the file's size and nothing else, at a cost that does not grow with
+       * the file.
+       *
+       * The answer comes from the same function a read consults before it allocates anything, from the
+       * same numbers, so **a read this approves is not refused later for memory** - and every suggestion
+       * it carries has been read back through the check, so following one gives a read that fits.
+       *
+       * It answers about resources, so it answers only for a header it can trust. A header whose numbers
+       * are not usable, or that claims more than the file holds, is refused as a `QvdCorruptedError` rather
+       * than answered: sizing a read from numbers the file contradicts produced a memory verdict about a
+       * file whose real problem was structural, and it was wrong in both directions - approving a read the
+       * library then refused, and refusing another with advice that was refused too.
+       *
+       * That covers everything a reader can tell from the header: a field area past the end of the symbol
+       * table, two fields claiming one area, a `Bias` that is neither 0 nor -2, a `BitWidth` past 31. Damage
+       * that is not in the header - a value or an index the file has spoiled - is still found only by
+       * reading, and still refused as a `QvdCorruptedError` after this has said the read fits.
+       *
+       * ```js
+       * const answer = await QvdDataFrame.checkRead('huge.qvd', {as: 'columns', fields: ['Amount']});
+       *
+       * if (!answer.fits) {
+       *   console.log(answer.reason); // 'memory'
+       *   console.log(answer.suggestions); // [{option: 'limit', value: 1250000}, ...]
+       * }
+       * ```
+       *
+       * @param {string} path The QVD file.
+       * @param {object} [options] What `fromQvd()` takes, plus the two below.
+       * @param {'rows'|'columns'} [options.as='rows'] Which read is being asked about: `rows` builds row
+       *   arrays and `columns` does not, which is most of what a read costs.
+       * @param {number|null} [options.chunkSize=null] The chunk an `iterate()` would use, which holds two
+       *   chunks of rows rather than the whole window.
+       * @return {Promise<any>} The answer: `fits`, `reason` when it does not, `estimate`, `budget`,
+       *   `exact` and `suggestions`.
+       * @throws {QvdValidationError} If an option's value is not valid, with `context.reason` of `option`.
+       * @throws {QvdCorruptedError} If the header cannot be read, its numbers are not usable, or it claims
+       *   more than the file holds. The read refuses such a file too, though it may name the fault
+       *   differently - it gets there by planning the index table, where this gets there from the size.
+       */
+      static async checkRead(path5, options = {}) {
+        const { QvdFileReader: QvdFileReader2 } = await Promise.resolve().then(() => (init_QvdFileReader(), QvdFileReader_exports));
+        const { as = "rows", chunkSize = null } = options;
+        if (as !== "rows" && as !== "columns") {
+          throw new exports.QvdValidationError("as must be 'rows' or 'columns'", {
+            provided: as,
+            reason: "option",
+            option: "as",
+            value: as,
+            file: path5
+          });
+        }
+        if (chunkSize !== null) {
+          requireChunkSize(chunkSize, path5);
+        }
+        const reader = new QvdFileReader2(path5, { ...readerOptionsFrom(options), materialisesRows: as === "rows" });
+        return await reader.checkRead(windowFrom(options), { chunkSize });
+      }
       /**
        * Constructs a data frame from a dictionary.
        *