qvdjs 2.1.0 → 2.2.1

package/dist/index.js

@@ -2185,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;
@@ -2200,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;
   }
@@ -2220,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)) {
@@ -2245,8 +2253,10 @@ 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 = null, readBytes = null) {
+function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePath, safetyFactor = 0.8, columnCount = 0, materialisesRows = true, live = null, bytesHeld = null, readBytes = null, wholeSymbols = false, retainedBytes = 0) {
   const answer = checkMemory({
+    wholeSymbols,
+    retainedBytes,
     symbolTableSize,
     maxRows,
     totalRows,
@@ -2278,7 +2288,9 @@ function checkMemory({
   live = null,
   bytesHeld = null,
   readBytes = null,
-  measured = null
+  measured = null,
+  wholeSymbols = false,
+  retainedBytes = 0
 }) {
   if (typeof safetyFactor !== "number" || safetyFactor < 0 || safetyFactor > 1) {
     throw new QvdValidationError("safetyFactor must be a number between 0.0 and 1.0", {
@@ -2293,8 +2305,21 @@ function checkMemory({
   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, forRows: heldForRows, forChunk: heldForChunk } = bytesHeld ?? noBytesHeld;
+  const heapMemory = estimateMemoryUsage(
+    symbolTableSize,
+    maxRows,
+    totalRows,
+    columnCount,
+    materialisesRows,
+    rowsLive,
+    wholeSymbols
+  );
+  const {
+    held,
+    afterRelease: heldAfterRelease = null,
+    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";
@@ -2330,6 +2355,25 @@ function checkMemory({
   const availableMemory = binding ? binding.bytes : budget.bytes;
   const estimatedMemory = binding ? binding.needs : heapMemory;
   const maxAllowedMemory = binding ? binding.allowed : budget.bytes * safetyFactor;
+  const retainedIsTheReason = (() => {
+    if (binding === null || retainedBytes <= 0) {
+      return false;
+    }
+    const heapAfter = estimateMemoryUsage(
+      Math.max(0, symbolTableSize - retainedBytes),
+      maxRows,
+      totalRows,
+      columnCount,
+      materialisesRows,
+      rowsLive,
+      wholeSymbols
+    );
+    const externalAfter = estimateExternalMemory(liveRows, columnCount) + (heldAfterRelease ?? held);
+    return budget.candidates.every((candidate) => {
+      const heapOnly = candidate.source === "V8 heap limit";
+      return (heapOnly ? heapAfter : heapAfter + externalAfter) <= candidate.bytes * safetyFactor;
+    });
+  })();
   if (binding) {
     const includeExternal = !binding.heapOnly;
     const rowsHeldBudget = /* @__PURE__ */ __name((rows) => maxAllowedMemory - (includeExternal ? heldForRows(rows) : 0), "rowsHeldBudget");
@@ -2339,7 +2383,8 @@ function checkMemory({
       totalRows,
       columnCount,
       materialisesRows,
-      includeExternal
+      includeExternal,
+      wholeSymbols
     ), "fitting");
     const firstGuess = fitting(liveRows);
     const over = fitting(firstGuess);
@@ -2365,7 +2410,8 @@ function checkMemory({
       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;
@@ -2374,13 +2420,17 @@ function checkMemory({
     const knob = chunked ? "chunkSize" : "limit";
     const recommendedValue = chunked ? recommendedChunk : recommendedMaxRows;
     const nothingFits = recommendedValue === 0;
+    const held2 = retainedIsTheReason;
+    const fixedCost = held2 ? "the columns this file is holding exceed" : "the symbol table alone exceeds";
+    const release = held2 ? `Close the file and open it again to release them, or raise ` : `Raise `;
+    const releaseFirst = held2 ? `Close the file and open it again to release the columns it is holding, which is the direct remedy. ` : "";
     let advice;
     if (nothingFits) {
-      advice = `No row count fits this budget - the symbol table alone exceeds it, so ${knob} cannot help. ` + (containerBound ? `Raise the container's memory limit.` : `Raise the heap with --max-old-space-size, or raise memorySafetyFactor.`);
+      advice = `No row count fits this budget - ${fixedCost} it, so ${knob} cannot help. ` + (containerBound ? `${release}the container's memory limit.` : `${release}the heap with --max-old-space-size, or raise memorySafetyFactor.`);
     } else if (containerBound) {
-      advice = `The binding limit is the container's, so raising --max-old-space-size would let V8 grow past it and be killed by the OOM killer instead. Set it below the container limit, raise the limit, or hold fewer rows with ${knob} (recommended: ${formatCount(recommendedValue)} rows or less).`;
+      advice = releaseFirst + `The binding limit is the container's, so raising --max-old-space-size would let V8 grow past it and be killed by the OOM killer instead. Set it below the container limit, raise the limit, or hold fewer rows with ${knob} (recommended: ${formatCount(recommendedValue)} rows or less).`;
     } 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.`;
+      advice = releaseFirst + `Try holding fewer rows using the ${knob} parameter (recommended: ${formatCount(recommendedValue)} rows or less), or raise the heap with --max-old-space-size.`;
     }
     const suggestions = [];
     if (!nothingFits) {
@@ -2404,10 +2454,16 @@ function checkMemory({
       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,
+        message: `Insufficient memory to load file safely. ${retainedIsTheReason ? "Columns held" : "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,
+          // Whether that figure is the file's symbol table or what an open file is still holding. A
+          // paging read is charged for every column any of its pages decoded and kept, so a caller
+          // branching on the refusal needs to know which of the two it is looking at - the remedies
+          // differ, and for this one releasing is a remedy where raising the limit is only a workaround.
+          holdsDecodedColumns: retainedIsTheReason,
+          retainedSymbolBytes: retainedBytes,
           estimatedMemoryMB: estimatedMB,
           availableMemoryMB: availableMB,
           heapLimitMB,
@@ -2455,13 +2511,21 @@ function budgetOf(budget, tightest, safetyFactor) {
 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;
   }
@@ -2567,19 +2631,39 @@ function validateHeaderStructure(headerObj, filePath, stage) {
   });
   return fieldList;
 }
-function validateSymbolTableSizeEarly(symbolTableLength, filePath) {
+function validateSymbolTableSizeEarly(symbolTableLength, filePath, retainedBytes = 0) {
   const heapLimit = getHeapLimit();
   const MAX_SYMBOL_TABLE_SIZE = heapLimit * 0.125;
   if (symbolTableLength > MAX_SYMBOL_TABLE_SIZE) {
     const sizeMB = Math.round(symbolTableLength / 1024 / 1024);
     const maxMB = Math.round(MAX_SYMBOL_TABLE_SIZE / 1024 / 1024);
     const heapMB = Math.round(heapLimit / 1024 / 1024);
+    if (retainedBytes > 0 && symbolTableLength - retainedBytes <= MAX_SYMBOL_TABLE_SIZE) {
+      throw new QvdValidationError(
+        `Columns held too large (${sizeMB}MB exceeds ${maxMB}MB limit). This open file is holding the columns its pages have decoded, and they have grown past the ceiling rather than the file's own symbol table being large. Limit scales with heap size (current: ${heapMB}MB, limit: 12.5% = ${maxMB}MB). Consider: (1) closing the file and opening it again, which releases what the pages decoded, (2) paging over fewer columns with fields, or (3) increasing heap size with --max-old-space-size.`,
+        {
+          file: filePath,
+          symbolTableSize: symbolTableLength,
+          symbolTableSizeMB: sizeMB,
+          holdsDecodedColumns: true,
+          retainedSymbolBytes: retainedBytes,
+          maxAllowed: MAX_SYMBOL_TABLE_SIZE,
+          maxAllowedMB: maxMB,
+          heapLimitMB: heapMB,
+          reason: "memory"
+        }
+      );
+    }
     throw new QvdValidationError(
       `Symbol table too large (${sizeMB}MB exceeds ${maxMB}MB limit for lazy loading). This QVD file contains extremely high-cardinality fields. Limit scales with heap size (current: ${heapMB}MB, limit: 12.5% = ${maxMB}MB). Consider: (1) loading the full file without a row window - maxRows, limit or offset - since the symbol table is read in full either way, (2) increasing heap size with --max-old-space-size, or (3) aggregating high-cardinality fields.`,
       {
         file: filePath,
         symbolTableSize: symbolTableLength,
         symbolTableSizeMB: sizeMB,
+        // Present and false, not absent. A caller told it can branch on this has to find it on both
+        // refusals, or the branch reads `undefined` for the commoner of the two.
+        holdsDecodedColumns: false,
+        retainedSymbolBytes: retainedBytes,
         maxAllowed: MAX_SYMBOL_TABLE_SIZE,
         maxAllowedMB: maxMB,
         heapLimitMB: heapMB,
@@ -3589,6 +3673,26 @@ function symbolBytesOf(selected, 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"() {
@@ -3613,6 +3717,7 @@ var init_QvdFileReader = __esm({
     __name(parseHeaderXml, "parseHeaderXml");
     __name(symbolBytesOf, "symbolBytesOf");
     __name(readPasses, "readPasses");
+    __name(validateWatchers, "validateWatchers");
     QvdFileReader = class {
       static {
         __name(this, "QvdFileReader");
@@ -3693,20 +3798,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;
@@ -3715,6 +3807,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;
@@ -3726,6 +3820,7 @@ var init_QvdFileReader = __esm({
         this._indexColumns = null;
         this._rowsDecoded = 0;
         this._fileSize = null;
+        this._fileIdentity = null;
         this._headerMatchesFile = false;
       }
       /**
@@ -3954,8 +4049,9 @@ 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);
+        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
@@ -3971,7 +4067,12 @@ var init_QvdFileReader = __esm({
         this._headerBuffer = headerBuffer.subarray(0, headerEndIndex);
         const selected = selectFields(headerFields, this._requestedFields, this._path);
         const columnCount = selected.length;
-        const symbolBytes = symbolBytesOf(selected, symbolTableLength);
+        const symbolBytes = symbolBytesOf(this._fieldsHeldAfter(selected, headerFields), symbolTableLength);
+        const readSymbolBytes = symbolBytesOf(this._fieldsReadBy(selected), symbolTableLength);
+        const retainedBytes = symbolBytesOf(
+          this._fieldsHeldAfter(selected, headerFields).slice(selected.length),
+          symbolTableLength
+        );
         const resolved = headerNumbersUsable ? resolveWindow(window, totalRows) : { offset: 0, limit: 0 };
         const windowRows = resolved.limit;
         if (headerNumbersUsable && this._headerMatchesFile) {
@@ -3985,11 +4086,12 @@ 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),
+              symbolBytes - retainedBytes
             ),
             // 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.
@@ -3997,7 +4099,12 @@ var init_QvdFileReader = __esm({
             // 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
+            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,
+            retainedBytes
           );
         }
         if (window.offset === 0 && window.limit === null) {
@@ -4005,7 +4112,7 @@ var init_QvdFileReader = __esm({
           return;
         }
         const rowsToLoad = windowRows;
-        validateSymbolTableSizeEarly(symbolBytes, this._path);
+        validateSymbolTableSizeEarly(symbolBytes, this._path, retainedBytes);
         validateRecordSize(recordSize, this._path, "readData");
         validateRecordCount(totalRows, this._path, "readData");
         const fileBytesRequired = indexTableOffset + (resolved.offset + rowsToLoad) * recordSize;
@@ -4117,9 +4224,14 @@ var init_QvdFileReader = __esm({
        *   would hold.
        * @private
        */
-      _bytesHeld(symbolBytes, windowRows, recordSize, liveRows, analysisAhead) {
+      _bytesHeld(symbolBytes, windowRows, recordSize, liveRows, analysisAhead, freshSymbolBytes = null) {
         return {
           held: this._bytesHeldBy(symbolBytes, this._recordsAtOnce(windowRows, liveRows, analysisAhead), recordSize),
+          // What it would hold having closed the file and opened it again: every selected column read fresh,
+          // because nothing is cached any more. Higher than `held`, not lower - a cached column this read
+          // selects costs nothing to read now and would cost its area then. Without it the counterfactual
+          // that decides whether releasing helps was answered against the warm figure and said yes too often.
+          afterRelease: freshSymbolBytes === null ? null : this._bytesHeldBy(freshSymbolBytes, this._recordsAtOnce(windowRows, liveRows, analysisAhead), recordSize),
           // A window of so many rows reads so many records at a time, and the pass that reads it ahead of the
           // decode reads the same rows, so the buffer is sized from the rows either way.
           forRows: /* @__PURE__ */ __name((rows) => this._bytesHeldBy(symbolBytes, rows, recordSize), "forRows"),
@@ -4182,6 +4294,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
@@ -4210,7 +4507,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.
        *
@@ -4225,7 +4528,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"]) };
@@ -4547,9 +4853,12 @@ 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 retainedBytes = symbolBytesOf(this._fieldsHeldAfter(fields, allFields).slice(fields.length), symbolTableSize);
+        const symbolBytes = readSymbolBytes + retainedBytes;
         const totalRows = headerInteger(this._header["QvdTableHeader"]["NoOfRecords"]);
         const recordSize = headerInteger(this._header["QvdTableHeader"]["RecordByteSize"]);
         validateSymbolTableSize(symbolBytes, this._path, totalRows);
@@ -4563,13 +4872,22 @@ var init_QvdFileReader = __esm({
             fields.length,
             this._materialisesRows,
             liveRows,
-            this._bytesHeld(symbolBytes, rowsToLoad, recordSize, liveRows, false),
+            this._bytesHeld(readSymbolBytes, rowsToLoad, recordSize, liveRows, false, symbolBytes - retainedBytes),
             // `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
+            readSymbolBytes + readPasses(symbolsToKeep !== null) * rowsToLoad * recordSize,
+            this._symbolCache !== null,
+            retainedBytes
           );
         }
-        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);
         }
@@ -4577,24 +4895,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);
         }
@@ -4689,28 +5019,39 @@ 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.
        *
@@ -4728,77 +5069,127 @@ var init_QvdFileReader = __esm({
       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(
-            this._header && this._selectedFields && this._allFields && this._symbolTableOffset !== null,
-            "The QVD file header has not been parsed."
+          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);
+          const retained = symbolBytesOf(
+            this._fieldsHeldAfter(asked, this._allFields).slice(asked.length),
+            symbolTableLength
           );
-          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 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 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,
+            retainedBytes: retained,
+            bytesHeld: this._bytesHeld(read, rows, recordSize, liveRows, analysisAhead, bytes - retained),
+            // 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;
-        });
+        }
+        return answer;
       }
       /**
        * Loads the QVD file into memory and parses it.
@@ -4964,7 +5355,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);
         }
@@ -5056,6 +5447,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 {
@@ -5866,6 +6475,49 @@ var init_QvdDataFrame = __esm({
         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.
        *
@@ -6170,10 +6822,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