qvdjs 2.0.6 → 2.2.0

package/dist/index.js

@@ -441,7 +441,9 @@ var init_optionTypes = __esm({
 function requireRowCount(value, name, filePath) {
   if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
     throw new QvdValidationError(`${name} must be a non-negative integer`, {
+      reason: "option",
       option: name,
+      value,
       provided: value,
       type: typeof value,
       file: filePath
@@ -458,6 +460,9 @@ function normaliseWindow(window, filePath) {
   }
   if (typeof window !== "object" || Array.isArray(window)) {
     throw new 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
@@ -468,6 +473,9 @@ function normaliseWindow(window, filePath) {
   const maxRowsGiven = maxRows !== void 0 && maxRows !== null;
   if (limitGiven && maxRowsGiven) {
     throw new 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
@@ -478,6 +486,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 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);
@@ -492,6 +513,9 @@ function selectFields(fields, requested, filePath) {
   }
   if (!Array.isArray(requested)) {
     throw new QvdValidationError("fields must be an array of field names", {
+      reason: "option",
+      option: "fields",
+      value: requested,
       provided: requested,
       type: typeof requested,
       file: filePath
@@ -500,6 +524,9 @@ function selectFields(fields, requested, filePath) {
   const available = fields.map((field) => field["FieldName"]);
   if (requested.length === 0) {
     throw new QvdValidationError("fields must name at least one field", {
+      reason: "option",
+      option: "fields",
+      value: requested,
       availableColumns: available,
       file: filePath
     });
@@ -508,6 +535,9 @@ function selectFields(fields, requested, filePath) {
   return requested.map((name) => {
     if (typeof name !== "string") {
       throw new QvdValidationError("Field names must be strings", {
+        reason: "option",
+        option: "fields",
+        value: name,
         provided: name,
         type: typeof name,
         availableColumns: available,
@@ -516,6 +546,9 @@ function selectFields(fields, requested, filePath) {
     }
     if (seen.has(name)) {
       throw new QvdValidationError(`Field '${name}' is listed twice`, {
+        reason: "option",
+        option: "fields",
+        value: name,
         column: name,
         fields: requested,
         file: filePath
@@ -525,6 +558,9 @@ function selectFields(fields, requested, filePath) {
     const index = available.indexOf(name);
     if (index === -1) {
       throw new QvdValidationError(`Column '${name}' does not exist`, {
+        reason: "option",
+        option: "fields",
+        value: name,
         column: name,
         availableColumns: available,
         file: filePath
@@ -539,7 +575,9 @@ function normaliseDuals(value, filePath) {
   }
   if (!DUAL_MODES.includes(value)) {
     throw new QvdValidationError(`duals must be one of ${DUAL_MODES.map((mode) => `'${mode}'`).join(", ")}`, {
+      reason: "option",
       option: "duals",
+      value,
       provided: value,
       file: filePath
     });
@@ -578,6 +616,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"]);
@@ -2146,13 +2185,13 @@ function estimateRowMemory(rows, columnCount) {
   }
   return BASE_BYTES + rows * (ROW_BASE_BYTES + PER_CELL_BYTES * columnCount);
 }
-function estimateMemoryUsage(symbolTableSize, maxRows, totalRows, columnCount = 0, materialisesRows = true, rowsLive = null) {
+function estimateMemoryUsage(symbolTableSize, maxRows, totalRows, columnCount = 0, materialisesRows = true, rowsLive = null, wholeSymbols = false) {
   const FULL_PARSE_OVERHEAD = 6;
   const MINIMAL_OVERHEAD = 0.01;
   const rowsToLoad = maxRows === null || maxRows >= totalRows ? totalRows : maxRows;
   const liveRows = rowsLive === null ? rowsToLoad : Math.min(rowsLive, rowsToLoad);
   const rowMemory = materialisesRows ? estimateRowMemory(liveRows, columnCount) : BASE_BYTES;
-  if (maxRows === null || maxRows >= totalRows) {
+  if (maxRows === null || maxRows >= totalRows || wholeSymbols) {
     return symbolTableSize * FULL_PARSE_OVERHEAD + rowMemory;
   }
   const rowPercentage = maxRows / totalRows;
@@ -2161,8 +2200,8 @@ 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, includeExternal = false) {
-  const costOf = /* @__PURE__ */ __name((rows) => estimateMemoryUsage(symbolTableSize, rows, totalRows, columnCount, materialisesRows) + (includeExternal ? estimateExternalMemory(Math.min(rows, totalRows), columnCount) : 0), "costOf");
+function recommendedRowsFor(budget, symbolTableSize, totalRows, columnCount, materialisesRows = true, includeExternal = false, wholeSymbols = false) {
+  const costOf = /* @__PURE__ */ __name((rows) => estimateMemoryUsage(symbolTableSize, rows, totalRows, columnCount, materialisesRows, null, wholeSymbols) + (includeExternal ? estimateExternalMemory(Math.min(rows, totalRows), columnCount) : 0), "costOf");
   if (costOf(totalRows) <= budget) {
     return totalRows;
   }
@@ -2181,11 +2220,19 @@ function recommendedRowsFor(budget, symbolTableSize, totalRows, columnCount, mat
   }
   return low;
 }
-function recommendedChunkFor(budget, symbolTableSize, windowRows, totalRows, columnCount, liveRowsPerChunk = 1, includeExternal = false) {
+function recommendedChunkFor(budget, symbolTableSize, windowRows, totalRows, columnCount, liveRowsPerChunk = 1, includeExternal = false, wholeSymbols = false) {
   const covered = windowRows === null || windowRows >= totalRows ? totalRows : windowRows;
   const fits = /* @__PURE__ */ __name((chunk) => {
     const live = Math.min(chunk * liveRowsPerChunk, covered);
-    const cost = estimateMemoryUsage(symbolTableSize, windowRows, totalRows, columnCount, true, chunk * liveRowsPerChunk) + (includeExternal ? estimateExternalMemory(live, columnCount) : 0);
+    const cost = estimateMemoryUsage(
+      symbolTableSize,
+      windowRows,
+      totalRows,
+      columnCount,
+      true,
+      chunk * liveRowsPerChunk,
+      wholeSymbols
+    ) + (includeExternal ? estimateExternalMemory(live, columnCount) : 0);
     return cost <= budget;
   }, "fits");
   if (fits(covered)) {
@@ -2206,22 +2253,66 @@ 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 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, wholeSymbols = false) {
+  const answer = checkMemory({
+    wholeSymbols,
+    symbolTableSize,
+    maxRows,
+    totalRows,
+    safetyFactor,
+    columnCount,
+    materialisesRows,
+    live,
+    bytesHeld,
+    readBytes
+  });
+  if (answer.fits) {
     return;
   }
-  const budget = getMemoryBudget();
+  const { message, context } = answer.refusal;
+  throw new 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,
+  wholeSymbols = false
+}) {
+  if (typeof safetyFactor !== "number" || safetyFactor < 0 || safetyFactor > 1) {
+    throw new 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 heapMemory = estimateMemoryUsage(
+    symbolTableSize,
+    maxRows,
+    totalRows,
+    columnCount,
+    materialisesRows,
+    rowsLive,
+    wholeSymbols
+  );
+  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";
@@ -2233,11 +2324,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;
@@ -2251,7 +2357,8 @@ function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePat
       totalRows,
       columnCount,
       materialisesRows,
-      includeExternal
+      includeExternal,
+      wholeSymbols
     ), "fitting");
     const firstGuess = fitting(liveRows);
     const over = fitting(firstGuess);
@@ -2277,7 +2384,8 @@ function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePat
       totalRows,
       columnCount,
       liveRowsPerChunk,
-      includeExternal
+      includeExternal,
+      wholeSymbols
     ), "chunkFitting");
     const callersChunk = chunked ? Math.max(1, Math.floor(rowsLive / Math.max(1, liveRowsPerChunk))) : 0;
     const firstChunk = chunked ? chunkFitting(callersChunk) : 0;
@@ -2294,42 +2402,94 @@ 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 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");
 }
-function warnLargeSymbolTable(symbolTableSize, maxRows, totalRows, columnCount = 0, materialisesRows = true) {
+function warnLargeSymbolTable(symbolTableSize, maxRows, totalRows, columnCount = 0, materialisesRows = true, wholeSymbols = false) {
   const LARGE_SYMBOL_TABLE_WARNING = usableOldSpaceLimit() * 0.125;
   if (symbolTableSize <= LARGE_SYMBOL_TABLE_WARNING) {
     return;
   }
   const rowsToLoad = maxRows === null || maxRows >= totalRows ? totalRows : maxRows;
-  const estimatedMemory = estimateMemoryUsage(symbolTableSize, maxRows, totalRows, columnCount, materialisesRows);
+  const estimatedMemory = estimateMemoryUsage(
+    symbolTableSize,
+    maxRows,
+    totalRows,
+    columnCount,
+    materialisesRows,
+    null,
+    wholeSymbols
+  );
   if (estimatedMemory <= LARGE_SYMBOL_TABLE_WARNING) {
     return;
   }
@@ -2340,7 +2500,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();
@@ -2358,7 +2518,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");
   }
@@ -3443,6 +3607,36 @@ 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;
+}
+function validateWatchers(onProgress, signal, path5) {
+  if (onProgress !== void 0 && typeof onProgress !== "function") {
+    throw new QvdValidationError("onProgress must be a function", {
+      provided: onProgress,
+      type: typeof onProgress,
+      reason: "option",
+      option: "onProgress",
+      file: path5
+    });
+  }
+  if (signal !== void 0 && (typeof signal !== "object" || signal === null || typeof signal.aborted !== "boolean")) {
+    throw new QvdValidationError("signal must be an AbortSignal", {
+      provided: signal,
+      type: typeof signal,
+      reason: "option",
+      option: "signal",
+      file: path5
+    });
+  }
+}
 var MAX_HEADER_SIZE, READ_CHUNK_SIZE, ANALYSIS_SLICE_ROWS, SLICE_BYTES, COUNT_SYMBOLS_PAST, QvdFileReader;
 var init_QvdFileReader = __esm({
   "src/QvdFileReader.js"() {
@@ -3465,6 +3659,9 @@ var init_QvdFileReader = __esm({
     COUNT_SYMBOLS_PAST = 65536;
     __name(chunksFrom, "chunksFrom");
     __name(parseHeaderXml, "parseHeaderXml");
+    __name(symbolBytesOf, "symbolBytesOf");
+    __name(readPasses, "readPasses");
+    __name(validateWatchers, "validateWatchers");
     QvdFileReader = class {
       static {
         __name(this, "QvdFileReader");
@@ -3545,20 +3742,7 @@ var init_QvdFileReader = __esm({
           });
         }
         this._sliceBytes = sliceBytes;
-        if (onProgress !== void 0 && typeof onProgress !== "function") {
-          throw new 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 QvdValidationError("signal must be an AbortSignal", {
-            provided: signal,
-            type: typeof signal,
-            file: this._path
-          });
-        }
+        validateWatchers(onProgress, signal, this._path);
         this._requestedFields = fields === void 0 ? null : fields;
         this._onProgress = onProgress;
         this._signal = signal;
@@ -3567,6 +3751,8 @@ var init_QvdFileReader = __esm({
         this._failed = null;
         this._reading = false;
         this._symbolAreas = null;
+        this._symbolCache = null;
+        this._cachedFor = null;
         this._headerOffset = null;
         this._symbolTableOffset = null;
         this._indexTableOffset = null;
@@ -3578,6 +3764,7 @@ var init_QvdFileReader = __esm({
         this._indexColumns = null;
         this._rowsDecoded = 0;
         this._fileSize = null;
+        this._fileIdentity = null;
         this._headerMatchesFile = false;
       }
       /**
@@ -3806,6 +3993,16 @@ var init_QvdFileReader = __esm({
         const indexTableOffset = symbolTableOffset + symbolTableLength;
         const recordSize = headerInteger(headerObj["QvdTableHeader"]["RecordByteSize"]);
         const totalRows = headerInteger(headerObj["QvdTableHeader"]["NoOfRecords"]);
+        const { size: fileSize, ino, dev, mtimeMs } = await handle.stat().catch(failed);
+        this._fileSize = fileSize;
+        this._fileIdentity = `${dev}:${ino}:${mtimeMs}:${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);
@@ -3814,20 +4011,8 @@ 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(this._fieldsHeldAfter(selected, headerFields), symbolTableLength);
+        const readSymbolBytes = symbolBytesOf(this._fieldsReadBy(selected), symbolTableLength);
         const resolved = headerNumbersUsable ? resolveWindow(window, totalRows) : { offset: 0, limit: 0 };
         const windowRows = resolved.limit;
         if (headerNumbersUsable && this._headerMatchesFile) {
@@ -3841,12 +4026,23 @@ var init_QvdFileReader = __esm({
             this._materialisesRows,
             liveRows,
             this._bytesHeld(
-              symbolBytes,
+              readSymbolBytes,
               windowRows,
               recordSize,
               liveRows,
-              this._analysisWouldRun(window, resolved, totalRows, symbolTableLength)
-            )
+              this._analysisAhead(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.
+            readSymbolBytes + readPasses(this._analysisAhead(window, resolved, totalRows, symbolTableLength)) * windowRows * recordSize,
+            // A paging read keeps whole columns, so the estimate must not discount its symbols as a window's
+            // sample of them - see `estimateMemoryUsage`. Under-charging is the direction that ends in a
+            // heap-limit abort rather than an error.
+            this._symbolCache !== null
           );
         }
         if (window.offset === 0 && window.limit === null) {
@@ -3915,8 +4111,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.
@@ -3925,8 +4122,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
@@ -4014,6 +4227,191 @@ var init_QvdFileReader = __esm({
         const chunkRows = liveRows === null ? windowRows : Math.max(1, Math.floor(liveRows.rows / Math.max(1, liveRows.perChunk)));
         return analysisAhead ? Math.max(windowRows, chunkRows) : chunkRows;
       }
+      /**
+       * The fields this reader will be holding the symbols of once this read has finished.
+       *
+       * The ones it selects, and - while paging - the ones it decoded for an earlier page and kept. That
+       * union is what the memory checks have to be sized by, because it is what is live: a reader four
+       * pages into a wide file holds four columns' values whether or not this page asks about them, and a
+       * check sized by this page alone would approve a fifth column that does not fit beside them.
+       *
+       * The same set for every check, so the ceilings, the guard and the pre-flight cannot disagree about
+       * what a paging read costs. Without a cache it is just the selection, which is what every one-shot
+       * read has always been sized by.
+       *
+       * @param {Array<any>} selected The fields this read selects.
+       * @param {Array<any>} all Every field in the header, to find a cached one by name.
+       * @return {Array<any>} The fields whose symbols will be live.
+       * @private
+       */
+      _fieldsHeldAfter(selected, all) {
+        if (this._symbolCache === null || this._symbolCache.size === 0) {
+          return selected;
+        }
+        const names = new Set(selected.map((field) => field["FieldName"]));
+        const cached = all.filter(
+          (field) => !names.has(field["FieldName"]) && this._symbolCache !== null && this._symbolCache.has(field["FieldName"])
+        );
+        return [...selected, ...cached];
+      }
+      /**
+       * The fields whose symbol areas this read will actually read.
+       *
+       * The selection, less anything already decoded and kept. `_fieldsHeldAfter` answers what the read will
+       * be *holding*, which is the right figure for the heap; this is the right one for the bytes it buffers
+       * while parsing and for the I/O it reports, because a cached column's area is left out of the plan
+       * entirely and never read.
+       *
+       * Sized by the wrong one of the two, a warm page was charged external bytes for buffers it never
+       * allocates - and external bytes bind against a container limit, so a page that fits could be refused -
+       * and `estimate.readBytes` claimed I/O it does not perform: on four columns with three cached it
+       * reported 3,155,600 bytes for a read of 788,930.
+       *
+       * @param {Array<any>} selected The fields this read selects.
+       * @return {Array<any>} The fields whose areas will be read.
+       * @private
+       */
+      _fieldsReadBy(selected) {
+        if (this._symbolCache === null || this._symbolCache.size === 0) {
+          return selected;
+        }
+        return selected.filter(
+          (field) => this._symbolCache !== null && !this._symbolCache.has(field["FieldName"])
+        );
+      }
+      /**
+       * Keeps what this reader decodes, so that a later read of the same file does not decode it again.
+       *
+       * For a caller reading one file many times over - a `QvdFile` and its pages - and off by default,
+       * because every other entry point is one read and would only be holding values nobody will ask for
+       * again. Decoding the symbols is 72% of a page of a hundred rows from a 300,000-row file; the rest is
+       * the open, the header, the records and the rows.
+       *
+       * It turns the two-pass symbol path off with it. That path decodes only the symbols a window's rows
+       * use, which is right for one read and wrong for a cache: a later page asking for a row that uses a
+       * skipped symbol would read `undefined` where the value is. So a cached field is always a whole
+       * field, walked and checked against its `NoOfSymbols` like any other.
+       *
+       * @return {void}
+       */
+      beginPaging() {
+        this._symbolCache = /* @__PURE__ */ new Map();
+      }
+      /**
+       * Reads with the fields the caller names for this read alone, rather than the reader's own.
+       *
+       * A `QvdFile` is opened once and its pages may each name a projection, so the selection cannot be
+       * fixed at construction as it is for every other entry point.
+       *
+       * It holds until the next call replaces it rather than being cleared by the read, so **every caller
+       * sets it before every read**, passing the file's own fields where the page named none. A caller that
+       * relied on it being empty would instead get the projection of whatever ran last: that is what made a
+       * `check()` naming no fields answer for the previous page's columns.
+       *
+       * @param {Array<string>|null|undefined} fields The fields, or undefined to use the reader's own.
+       * @return {void}
+       */
+      selectForNextRead(fields) {
+        if (fields !== void 0) {
+          this._requestedFields = fields;
+        }
+      }
+      /**
+       * Watches the next read with the caller's `onProgress` and `signal`, rather than the reader's own.
+       *
+       * Both belong to one call, and a reader is told them when it is built - so a `QvdFile` page that named
+       * either used to get a reader of its own. That made passing a progress callback change what the read
+       * did rather than only observing it: a fresh reader is not paging, so it took the two-pass symbol
+       * path, reported a different `loadStats.symbolFiltering`, and cached nothing. An observer must not
+       * change what it observes, and a caller must not have to choose between cancelling a page and paging
+       * cheaply.
+       *
+       * Like `selectForNextRead`, it holds until the next call replaces it rather than being cleared by the
+       * read, so a caller that sets it for one page and not the next is still watched on the next - pass the
+       * file's own watchers explicitly, as `QvdFile._page` does, rather than leaving them out.
+       *
+       * @param {{onProgress?: Function, signal?: AbortSignal}} [watchers] What this read is watched with.
+       * @return {void}
+       */
+      observeNextRead({ onProgress, signal } = {}) {
+        validateWatchers(onProgress, signal, this._path);
+        this._onProgress = onProgress;
+        this._signal = signal;
+      }
+      /**
+       * Whether the symbol-usage pass runs for this read, cache and all.
+       *
+       * `_analysisWouldRun` answers whether the window wants the pass; a paging read never takes it, because
+       * a column decoded in part cannot be kept. Asked in one place because it was asked in two and they
+       * disagreed: the pass was gated on the cache while the memory charge and `estimate.readBytes` were
+       * not, so every page of a file above the threshold was charged a slice of records it never buffered
+       * and reported twice the bytes it read.
+       *
+       * @param {QvdRowWindow} window The window as the caller spelled it.
+       * @param {{offset: number, limit: number}} resolved Where it lands in this file.
+       * @param {number} totalRows Rows the file declares.
+       * @param {number} symbolTableLength The symbol table's declared length.
+       * @return {boolean} Whether the pass will run.
+       * @private
+       */
+      _analysisAhead(window, resolved, totalRows, symbolTableLength) {
+        return this._symbolCache === null && this._analysisWouldRun(window, resolved, totalRows, symbolTableLength);
+      }
+      /**
+       * Empties the cache when the header in front of us is not the one it was decoded from.
+       *
+       * The fingerprint is what a rewrite moves: the file's identity on disk - device, inode, modification
+       * time and size - and then the header numbers, down to each cached field's own offset, length and
+       * symbol count.
+       *
+       * The header numbers alone were not enough, and the gap is not exotic. `QvdFileWriter` carries
+       * `CreateUtcTime` over from the metadata it is handed, so reading a QVD, changing one text to another
+       * of the same byte length and writing it back leaves `CreateUtcTime`, `NoOfRecords`, `Offset` and
+       * every field's `Offset`, `Length` and `NoOfSymbols` exactly as they were - a different file the
+       * fingerprint could not tell from the first. The filesystem sees it either way: an atomic write
+       * renames a new file into place, which changes the inode, and an in-place one moves `mtimeMs`.
+       *
+       * @return {void}
+       * @private
+       */
+      _forgetCacheIfFileChanged() {
+        if (this._symbolCache === null || this._symbolCache.size === 0) {
+          return;
+        }
+        if (this._cachedFor !== this._fileFingerprint()) {
+          this._symbolCache = /* @__PURE__ */ new Map();
+          this._cachedFor = null;
+        }
+      }
+      /**
+       * What identifies the file this reader's cache was decoded from.
+       *
+       * @return {string} The fingerprint.
+       * @private
+       */
+      _fileFingerprint() {
+        assert4(this._header && this._allFields, "The QVD file header has not been parsed.");
+        const header = this._header["QvdTableHeader"];
+        return [
+          // First, because it is the only part that moves when a rewrite preserves the header's numbers.
+          this._fileIdentity,
+          header["CreateUtcTime"],
+          header["NoOfRecords"],
+          header["Offset"],
+          ...this._allFields.map(
+            (field) => `${field["FieldName"]}:${field["Offset"]}:${field["Length"]}:${field["NoOfSymbols"]}`
+          )
+        ].join("|");
+      }
+      /**
+       * Drops everything this reader has decoded, so that nothing outlives the caller that wanted it.
+       *
+       * @return {void}
+       */
+      endPaging() {
+        this._symbolCache = null;
+        this._cachedFor = null;
+      }
       /**
        * The symbol table's length, as much of it as the file holds: what the header declares, cut short where
        * the file ends. Known before a byte of the table is read, so everything that can refuse the table is
@@ -4042,7 +4440,13 @@ var init_QvdFileReader = __esm({
        * order, so ranges that touch are merged: a read of every field is one range, and so is a read of fields
        * that happen to be neighbours. A read of one field of twenty reads that field's area alone.
        *
-       * Built once per read, from the fields the read selected, and each field's metadata is checked as it is
+       * A field whose symbols this reader already holds is left out, because its bytes are not wanted: the
+       * ranges are what gets read, and including a cached field's span had a page read every byte of every
+       * column it named, cached or not. Measured on four columns of 20,000 distinct texts, a page naming all
+       * four with three of them cached read all four columns' bytes - 1,155,600 of them, where 288,930 were
+       * needed. The decode was saved and the I/O was not, which on the files #122 is about is the whole cost.
+       *
+       * Built once per read, from the fields the read must read, and each field's metadata is checked as it is
        * added - a range is arithmetic on `Offset` and `Length`, and those have to be inside the table first.
        * `_parseSymbolTable` checks every field of the file, selected or not, before it parses any.
        *
@@ -4057,7 +4461,10 @@ var init_QvdFileReader = __esm({
         }
         assert4(this._selectedFields, "The QVD file fields have not been resolved before their symbols were read.");
         const tableLength = this._symbolTableLength();
-        const areas = this._selectedFields.map((field) => {
+        const toRead = this._selectedFields.filter(
+          (field) => this._symbolCache === null || !this._symbolCache.has(field["FieldName"])
+        );
+        const areas = toRead.map((field) => {
           validateFieldMetadata(field, tableLength, this._path);
           const start = headerInteger(field["Offset"]);
           return { field, start, end: start + headerInteger(field["Length"]) };
@@ -4142,7 +4549,7 @@ var init_QvdFileReader = __esm({
           return;
         }
         assert4(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) {
@@ -4379,9 +4786,11 @@ var init_QvdFileReader = __esm({
         }
         const allFields = this._allFields;
         const fields = this._selectedFields;
+        this._forgetCacheIfFileChanged();
         const symbolTableSize = this._symbolTableLength();
         const plan = this._symbolAreaPlan();
-        const symbolBytes = plan.ranges.reduce((sum, range) => sum + (range.end - range.start), 0);
+        const readSymbolBytes = plan.ranges.reduce((sum, range) => sum + (range.end - range.start), 0);
+        const symbolBytes = readSymbolBytes + symbolBytesOf(this._fieldsHeldAfter(fields, allFields).slice(fields.length), symbolTableSize);
         const totalRows = headerInteger(this._header["QvdTableHeader"]["NoOfRecords"]);
         const recordSize = headerInteger(this._header["QvdTableHeader"]["RecordByteSize"]);
         validateSymbolTableSize(symbolBytes, this._path, totalRows);
@@ -4395,10 +4804,21 @@ var init_QvdFileReader = __esm({
             fields.length,
             this._materialisesRows,
             liveRows,
-            this._bytesHeld(symbolBytes, rowsToLoad, recordSize, liveRows, false)
+            this._bytesHeld(readSymbolBytes, 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.
+            readSymbolBytes + readPasses(symbolsToKeep !== null) * rowsToLoad * recordSize,
+            this._symbolCache !== null
           );
         }
-        warnLargeSymbolTable(symbolBytes, rowsToLoad, totalRows, fields.length, this._materialisesRows);
+        warnLargeSymbolTable(
+          symbolBytes,
+          rowsToLoad,
+          totalRows,
+          fields.length,
+          this._materialisesRows,
+          this._symbolCache !== null
+        );
         for (const field of allFields) {
           validateFieldMetadata(field, symbolTableSize, this._path);
         }
@@ -4406,24 +4826,36 @@ var init_QvdFileReader = __esm({
         const symbolTable = [];
         for (const [position, field] of fields.entries()) {
           this._throwIfAborted();
+          const cached = this._symbolCache?.get(field["FieldName"]);
+          if (cached) {
+            symbolTable.push(cached);
+            this._emitProgress("symbol-table", position + 1, fields.length);
+            continue;
+          }
           const area = await this._symbolAreaOf(field);
-          symbolTable.push(
-            parseFieldSymbols(
-              area.buffer,
-              area.start,
-              area.end,
-              // Checked against the symbols the area holds, which is the one check that sees a terminator
-              // damaged in the middle of it (#124).
-              headerInteger(field["NoOfSymbols"]),
-              // By position, matching how `_analyzeIndexTableSymbolUsage` built it. Both walk
-              // `this._selectedFields`, so position is the one key that cannot collide.
-              symbolsToKeep ? symbolsToKeep[position] : null,
-              field["FieldName"],
-              this._path,
-              void 0,
-              area.base
-            )
+          const parsed = parseFieldSymbols(
+            area.buffer,
+            area.start,
+            area.end,
+            // Checked against the symbols the area holds, which is the one check that sees a terminator
+            // damaged in the middle of it (#124). A cached field was checked when it was decoded, which is
+            // why the cache may only hold a field a full walk produced.
+            headerInteger(field["NoOfSymbols"]),
+            // By position, matching how `_analyzeIndexTableSymbolUsage` built it. Both walk
+            // `this._selectedFields`, so position is the one key that cannot collide.
+            symbolsToKeep ? symbolsToKeep[position] : null,
+            field["FieldName"],
+            this._path,
+            void 0,
+            area.base
           );
+          symbolTable.push(parsed);
+          if (this._symbolCache && symbolsToKeep === null) {
+            if (this._symbolCache.size === 0) {
+              this._cachedFor = this._fileFingerprint();
+            }
+            this._symbolCache.set(field["FieldName"], parsed);
+          }
           this._releaseSymbolArea(field);
           this._emitProgress("symbol-table", position + 1, fields.length);
         }
@@ -4518,28 +4950,173 @@ var init_QvdFileReader = __esm({
           await this._parseHeader();
           this._emitProgress("header", 1, 1);
           this._throwIfAborted();
-          assert4(this._header && this._allFields, "The QVD file header has not been parsed.");
-          const header = this._header["QvdTableHeader"];
-          const columns = this._allFields.map((field) => field["FieldName"]);
-          const rowCount = headerInteger(header["NoOfRecords"]);
-          validateRecordCount(rowCount, this._path, "readMetadata");
-          const shape = new QvdDataFrame([], columns, header, {
-            symbolTableBytes: headerInteger(header["Offset"]),
-            totalRows: rowCount,
-            rowsLoaded: 0,
-            symbolFiltering: false,
-            symbolsKept: null
-          });
-          return {
-            columns,
-            rowCount,
-            columnCount: columns.length,
-            fields: columns.map((name) => shape.getFieldMetadata(name)),
-            fileMetadata: shape.fileMetadata,
-            metadata: header
-          };
+          return this.describeParsed();
         });
       }
+      /**
+       * The schema and header of the file this reader has parsed, as `readMetadata()` reports them.
+       *
+       * Built from the parsed header and nothing else, so a caller holding a header - a `QvdFile` - can have
+       * it without reading the file a second time.
+       *
+       * @return {any} The metadata.
+       */
+      describeParsed() {
+        assert4(this._header && this._allFields, "The QVD file header has not been parsed.");
+        const header = this._header["QvdTableHeader"];
+        const columns = this._allFields.map((field) => field["FieldName"]);
+        const rowCount = headerInteger(header["NoOfRecords"]);
+        validateRecordCount(rowCount, this._path, "readMetadata");
+        const shape = new QvdDataFrame([], columns, header, {
+          symbolTableBytes: headerInteger(header["Offset"]),
+          totalRows: rowCount,
+          rowsLoaded: 0,
+          symbolFiltering: false,
+          symbolsKept: null
+        });
+        return {
+          columns,
+          rowCount,
+          columnCount: columns.length,
+          fields: columns.map((name) => shape.getFieldMetadata(name)),
+          fileMetadata: shape.fileMetadata,
+          metadata: header
+        };
+      }
+      /**
+       * 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._parseHeaderChecked();
+          return this.checkParsed(window, { chunkSize });
+        });
+      }
+      /**
+       * Reads this file's header, and nothing else, leaving it parsed on the reader.
+       *
+       * What `checkRead` and `QvdFile` both start with: the second asks many questions of one header, so the
+       * read that produces it is separate from the questions. Every check a read makes before it trusts the
+       * header's numbers is made here, so that nothing downstream has to wonder whether they hold.
+       *
+       * @return {Promise<void>} When the header is parsed and checked.
+       */
+      async parseHeaderOnly() {
+        return await this._closingAfter(async () => await this._parseHeaderChecked());
+      }
+      /**
+       * `parseHeaderOnly`'s body, for a caller already inside a read session - `checkRead` is one.
+       *
+       * @return {Promise<void>} When the header is parsed and checked.
+       * @private
+       */
+      async _parseHeaderChecked() {
+        await this._readData({ offset: 0, limit: null }, true);
+        this._emitProgress("header", 0, 1);
+        await this._parseHeader();
+        this._emitProgress("header", 1, 1);
+        this._throwIfAborted();
+        assert4(
+          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"]);
+        validateRecordSize(recordSize, this._path, "checkRead");
+        validateRecordCount(totalRows, this._path, "checkRead");
+        if (!this._headerMatchesFile) {
+          throw new 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);
+      }
+      /**
+       * What a read of the parsed header's file would cost, with no I/O at all.
+       *
+       * Separate from `checkRead` because a `QvdFile` asks this of one header many times - once per page a
+       * viewer scrolls to - and the header is already in hand. `parseHeaderOnly` has to have run.
+       *
+       * @param {QvdRowWindow} window The rows the read would cover, normalised.
+       * @param {{chunkSize?: number|null, fields?: Array<string>|null, materialisesRows?: boolean}} [options]
+       *   `chunkSize` for an `iterate()`; `fields` and `materialisesRows` to ask about a read other than the
+       *   one this reader was built for, which is what a `QvdFile` does per call.
+       * @return {any} The answer - see `checkMemory`.
+       */
+      checkParsed(window, { chunkSize = null, fields = void 0, materialisesRows = void 0 } = {}) {
+        assert4(this._header && this._allFields, "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 builds = materialisesRows === void 0 ? this._materialisesRows : materialisesRows;
+        const selected = selectFields(this._allFields, fields === void 0 ? this._requestedFields : fields, this._path);
+        const resolved = resolveWindow(window, totalRows);
+        const windowRows = resolved.limit;
+        const liveRows = chunkSize === null ? null : { rows: chunkSize * 2, perChunk: 2 };
+        const analysisAhead = this._analysisAhead(window, resolved, totalRows, symbolTableLength);
+        const measured = getMemoryBudget();
+        const ask = /* @__PURE__ */ __name((asked, rows) => {
+          const bytes = symbolBytesOf(this._fieldsHeldAfter(asked, this._allFields), symbolTableLength);
+          const read = symbolBytesOf(this._fieldsReadBy(asked), symbolTableLength);
+          return checkMemory({
+            measured,
+            symbolTableSize: bytes,
+            maxRows: rows,
+            totalRows,
+            safetyFactor: this._memorySafetyFactor,
+            columnCount: asked.length,
+            materialisesRows: builds,
+            live: liveRows,
+            // A paging read keeps whole columns, so it is charged for whole columns - see `estimateMemoryUsage`.
+            wholeSymbols: this._symbolCache !== null,
+            bytesHeld: this._bytesHeld(read, rows, recordSize, liveRows, analysisAhead),
+            // What it reads from the file, which is not what it holds: the symbol areas it has still to read,
+            // 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: read + 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.
        *
@@ -4629,13 +5206,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 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();
@@ -4710,7 +5281,7 @@ var init_QvdFileReader = __esm({
         const rowsAvailable = resolved.limit;
         let symbolsToKeep = null;
         let symbolsKept = null;
-        if (this._analysisWouldRun(window, resolved, totalRows, symbolTableLength)) {
+        if (this._analysisAhead(window, resolved, totalRows, symbolTableLength)) {
           symbolsToKeep = await this._analyzeIndexTableSymbolUsage({ offset: resolved.offset, limit: rowsAvailable });
           symbolsKept = symbolsToKeep.reduce((sum, set) => sum + set.size, 0);
         }
@@ -4802,6 +5373,224 @@ var init_QvdFileReader = __esm({
   }
 });
 
+// src/QvdFile.js
+var QvdFile_exports = {};
+__export(QvdFile_exports, {
+  QvdFile: () => QvdFile
+});
+var QvdFile;
+var init_QvdFile = __esm({
+  "src/QvdFile.js"() {
+    init_QvdErrors();
+    init_readOptions();
+    QvdFile = class {
+      static {
+        __name(this, "QvdFile");
+      }
+      /**
+       * Not called directly - `QvdDataFrame.open()` is the way in, because a `QvdFile` is only ever a file
+       * whose header has been read, and a constructor cannot wait for that.
+       *
+       * @param {any} reader The reader holding the parsed header.
+       * @param {any} metadata What `readMetadata()` returns for this file.
+       * @param {any} options The options the file was opened with.
+       * @private
+       */
+      constructor(reader, metadata, options) {
+        this._reader = reader;
+        this._metadata = metadata;
+        this._options = options;
+        this._closed = false;
+        this._tail = Promise.resolve();
+        this._readers = { rows: null, columns: null };
+      }
+      /**
+       * The file's header and schema, as `QvdDataFrame.readMetadata()` returns them.
+       *
+       * Read when the file was opened, so this costs nothing and cannot fail.
+       *
+       * @return {any} The metadata.
+       */
+      get metadata() {
+        return this._metadata;
+      }
+      /**
+       * Whether `close()` has been called.
+       *
+       * @return {boolean} True once it has.
+       */
+      get closed() {
+        return this._closed;
+      }
+      /**
+       * What a read of this file would cost, and whether it fits - with no I/O at all.
+       *
+       * The same answer `QvdDataFrame.checkRead()` gives, from the header this file already holds, so a
+       * viewer can size a page before asking for it without touching the disk.
+       *
+       * @param {{offset?: number, limit?: number|null, maxRows?: number|null, fields?: Array<string>|null,
+       *   as?: 'rows'|'columns', chunkSize?: number|null}} [options] The read being asked about - the same
+       *   bag `rows()` takes, plus `as` and `chunkSize` to say which shape of read it is.
+       * @return {any} The answer - `fits`, `reason`, `estimate`, `budget`, `exact`, `suggestions`.
+       * @throws {QvdValidationError} If the file is closed, or an option's value is not valid.
+       */
+      check(options = {}) {
+        this._refuseWhenClosed("check");
+        const { as = "rows", chunkSize = null } = options;
+        if (as !== "rows" && as !== "columns") {
+          throw new QvdValidationError("as must be 'rows' or 'columns'", {
+            provided: as,
+            reason: "option",
+            option: "as",
+            value: as,
+            file: this._options.path
+          });
+        }
+        if (chunkSize !== null) {
+          requireChunkSize(chunkSize, this._options.path);
+        }
+        const reader = this._readers[as] ?? this._reader;
+        return reader.checkParsed(normaliseWindow(windowFrom(options), this._options.path), {
+          chunkSize,
+          // Resolved here rather than left to the reader, exactly as `_page` resolves it. A warm reader is
+          // still holding the last page's selection, and `checkParsed` falls back to it - so a `check()`
+          // naming no fields answered for whatever the previous page happened to name. On a four-column
+          // file after a page naming one of them, it reported 27,490 bytes for a read that costs 108,160:
+          // understating, which is the direction that approves a read the read then refuses.
+          fields: options.fields === void 0 ? this._options.fields ?? null : options.fields,
+          materialisesRows: as === "rows"
+        });
+      }
+      /**
+       * Reads a page of rows.
+       *
+       * @param {{offset?: number, limit?: number|null, maxRows?: number|null, fields?: Array<string>|null,
+       *   onProgress?: Function, signal?: AbortSignal}} [options] The page, and how to read it. One bag,
+       *   as every other entry point takes: `offset` and `limit` say which rows, `fields` names a projection
+       *   for this page alone, and anything left out falls back to what the file was opened with.
+       * @return {Promise<any>} The page, as a `QvdDataFrame`.
+       * @throws {QvdValidationError} If the file is closed.
+       */
+      async rows(options = {}) {
+        this._refuseWhenClosed("rows");
+        return await this._serialised(async () => await this._page(options, true, (reader, window) => reader.load(window)));
+      }
+      /**
+       * Reads a page as columns, building no rows.
+       *
+       * @param {{offset?: number, limit?: number|null, maxRows?: number|null, fields?: Array<string>|null,
+       *   onProgress?: Function, signal?: AbortSignal}} [options] The page, as `rows()` takes it.
+       * @return {Promise<any>} The page, as a `QvdColumnTable`.
+       * @throws {QvdValidationError} If the file is closed.
+       */
+      async columns(options = {}) {
+        this._refuseWhenClosed("columns");
+        return await this._serialised(
+          async () => await this._page(options, false, (reader, window) => reader.loadColumnar(window))
+        );
+      }
+      /**
+       * Closes the file.
+       *
+       * Every call after it is refused with `reason: 'closed'`. Calling it twice is not an error: a
+       * `finally` that closes and an `await using` that closes are both right, and both may run.
+       *
+       * @return {Promise<void>} When the pages already in flight have finished.
+       */
+      async close() {
+        if (this._closed) {
+          return;
+        }
+        this._closed = true;
+        await this._tail;
+        for (const reader of Object.values(this._readers)) {
+          reader?.endPaging();
+        }
+        this._readers = { rows: null, columns: null };
+        this._reader.endPaging();
+        this._reader = null;
+      }
+      /**
+       * `await using` support, where the runtime has it.
+       *
+       * @return {Promise<void>} When closed.
+       */
+      async [Symbol.asyncDispose]() {
+        await this.close();
+      }
+      /**
+       * Refuses a call on a closed file, in the vocabulary the rest of the API uses.
+       *
+       * @param {string} call The method the caller reached for, for the error.
+       * @private
+       */
+      _refuseWhenClosed(call) {
+        if (this._closed) {
+          throw new QvdValidationError("The file is closed: open it again to read from it", {
+            reason: "closed",
+            call,
+            file: this._options.path
+          });
+        }
+      }
+      /**
+       * Runs `work` after everything asked for before it, and before everything asked for after.
+       *
+       * @param {() => Promise<any>} work The page to read.
+       * @return {Promise<any>} Its result.
+       * @private
+       */
+      async _serialised(work) {
+        const run = this._tail.then(work, work);
+        this._tail = run.then(
+          () => void 0,
+          () => void 0
+        );
+        return await run;
+      }
+      /**
+       * Reads one page, through the reader that keeps what the pages before it decoded.
+       *
+       * One reader for every page rather than one per page, which is what makes the symbol cache possible:
+       * decoding the symbols is 72% of a page of a hundred rows from a 300,000-row file, and a reader built
+       * fresh each time did all of it again. Two readers, because a columnar page builds no rows and a row
+       * page does, and `materialisesRows` is fixed when a reader is constructed - so each shape keeps its
+       * own, and its own cache.
+       *
+       * Options that belong to one call rather than to the file - the fields this page alone wants, and the
+       * `onProgress` and `signal` watching it - are told to that shared reader for the next read and no
+       * further. A page naming one of them used to build a reader of its own instead, which quietly turned
+       * the cache off and the two-pass symbol path on: watching a page changed what the page did.
+       *
+       * @param {any} options What the call passed.
+       * @param {boolean} builds Whether the page materialises rows.
+       * @param {(reader: any, window: any) => Promise<any>} read The read to make.
+       * @return {Promise<any>} The page.
+       * @private
+       */
+      async _page(options, builds, read) {
+        const { QvdFileReader: QvdFileReader2 } = await Promise.resolve().then(() => (init_QvdFileReader(), QvdFileReader_exports));
+        const kept = builds ? "rows" : "columns";
+        if (!this._readers[kept]) {
+          const reader2 = new QvdFileReader2(this._options.path, {
+            ...readerOptionsFrom(this._options),
+            materialisesRows: builds
+          });
+          reader2.beginPaging();
+          this._readers[kept] = reader2;
+        }
+        const reader = this._readers[kept];
+        reader.selectForNextRead(options.fields === void 0 ? this._options.fields ?? null : options.fields);
+        reader.observeNextRead({
+          onProgress: options.onProgress ?? this._options.onProgress,
+          signal: options.signal ?? this._options.signal
+        });
+        return await read(reader, windowFrom(options));
+      }
+    };
+  }
+});
+
 // src/QvdDataFrame.js
 function defaultFieldHeader(fieldName) {
   return {
@@ -5550,6 +6339,111 @@ 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 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 });
+      }
+      /**
+       * Opens a QVD file for paging, reading its header and nothing else.
+       *
+       * Every other entry point is one read from start to finish. A viewer showing a hundred rows at a time
+       * pays the header again on every page, and `iterate()` goes forwards only - it cannot jump to row five
+       * million and it cannot go back. This holds the header so that `check()` costs nothing and a page can
+       * be asked for by position.
+       *
+       * ```js
+       * const qvd = await QvdDataFrame.open('sales.qvd', {allowedDir: '/data'});
+       *
+       * qvd.metadata;                                      // read once, when it opened
+       * const answer = qvd.check({offset: 0, limit: 100}); // no I/O at all
+       * const page = await qvd.rows({offset: 5_000_000, limit: 100});
+       * const cols = await qvd.columns({offset: 0, limit: 100, fields: ['Amount']});
+       *
+       * await qvd.close();
+       * ```
+       *
+       * The header is read once, and so is each column: a column decoded for one page is kept for the pages
+       * after it, so the first page costs about what a single read costs and the ones after it are cheap.
+       * What a file has decoded is charged to the memory check, so a page is refused rather than the process
+       * aborting, and `close()` releases it - close a file you have finished with.
+       *
+       * Each page still opens the file, and a first touch still decodes a whole column rather than only as
+       * far as the page needs.
+       *
+       * @param {string} path The QVD file.
+       * @param {object} [options] What `fromQvd()` takes - `allowedDir`, `fields`, `duals`,
+       *   `coerceNumericStrings`, `memorySafetyFactor` - describing the file and how its values read. A
+       *   window means nothing here: pages carry their own.
+       * @return {Promise<import('./QvdFile.js').QvdFile>} The open file.
+       * @throws {QvdValidationError} If an option's value is not valid, with `context.reason` of `option`.
+       * @throws {QvdCorruptedError} If the header cannot be read, or describes a file this is not.
+       */
+      static async open(path5, options = {}) {
+        const { QvdFileReader: QvdFileReader2 } = await Promise.resolve().then(() => (init_QvdFileReader(), QvdFileReader_exports));
+        const { QvdFile: QvdFile2 } = await Promise.resolve().then(() => (init_QvdFile(), QvdFile_exports));
+        const reader = new QvdFileReader2(path5, readerOptionsFrom(options));
+        reader.beginPaging();
+        await reader.parseHeaderOnly();
+        return new QvdFile2(reader, reader.describeParsed(), { ...options, path: path5 });
+      }
       /**
        * Constructs a data frame from a dictionary.
        *
@@ -5854,10 +6748,11 @@ __name(dateToQlikSerial, "dateToQlikSerial");
 // src/index.js
 init_QvdDataFrame();
 init_QvdColumnTable();
+init_QvdFile();
 init_QvdFileReader();
 init_QvdFileWriter();
 init_QvdErrors();
 
-export { QvdColumn, QvdColumnTable, QvdCorruptedError, QvdDataFrame, QvdDual, QvdError, QvdFileReader, QvdFileWriter, QvdIOError, QvdParseError, QvdSecurityError, QvdSymbol, QvdValidationError, dateToQlikSerial, qlikSerialToDate };
+export { QvdColumn, QvdColumnTable, QvdCorruptedError, QvdDataFrame, QvdDual, QvdError, QvdFile, QvdFileReader, QvdFileWriter, QvdIOError, QvdParseError, QvdSecurityError, QvdSymbol, QvdValidationError, dateToQlikSerial, qlikSerialToDate };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map