qvdjs 2.1.0 → 2.2.0

package/dist/index.cjs

@@ -2197,13 +2197,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;
@@ -2212,8 +2212,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;
   }
@@ -2232,11 +2232,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)) {
@@ -2257,8 +2265,9 @@ 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) {
   const answer = checkMemory({
+    wholeSymbols,
     symbolTableSize,
     maxRows,
     totalRows,
@@ -2290,7 +2299,8 @@ function checkMemory({
   live = null,
   bytesHeld = null,
   readBytes = null,
-  measured = null
+  measured = null,
+  wholeSymbols = false
 }) {
   if (typeof safetyFactor !== "number" || safetyFactor < 0 || safetyFactor > 1) {
     throw new exports.QvdValidationError("safetyFactor must be a number between 0.0 and 1.0", {
@@ -2305,7 +2315,15 @@ 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 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) => {
@@ -2351,7 +2369,8 @@ function checkMemory({
       totalRows,
       columnCount,
       materialisesRows,
-      includeExternal
+      includeExternal,
+      wholeSymbols
     ), "fitting");
     const firstGuess = fitting(liveRows);
     const over = fitting(firstGuess);
@@ -2377,7 +2396,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;
@@ -2467,13 +2487,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;
   }
@@ -3601,6 +3629,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 exports.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 exports.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; exports.QvdFileReader = void 0;
 var init_QvdFileReader = __esm({
   "src/QvdFileReader.js"() {
@@ -3625,6 +3673,7 @@ var init_QvdFileReader = __esm({
     __name(parseHeaderXml, "parseHeaderXml");
     __name(symbolBytesOf, "symbolBytesOf");
     __name(readPasses, "readPasses");
+    __name(validateWatchers, "validateWatchers");
     exports.QvdFileReader = class {
       static {
         __name(this, "QvdFileReader");
@@ -3705,20 +3754,7 @@ var init_QvdFileReader = __esm({
           });
         }
         this._sliceBytes = sliceBytes;
-        if (onProgress !== void 0 && typeof onProgress !== "function") {
-          throw new exports.QvdValidationError("onProgress must be a function", {
-            provided: onProgress,
-            type: typeof onProgress,
-            file: this._path
-          });
-        }
-        if (signal !== void 0 && (typeof signal !== "object" || signal === null || typeof signal.aborted !== "boolean")) {
-          throw new exports.QvdValidationError("signal must be an AbortSignal", {
-            provided: signal,
-            type: typeof signal,
-            file: this._path
-          });
-        }
+        validateWatchers(onProgress, signal, this._path);
         this._requestedFields = fields === void 0 ? null : fields;
         this._onProgress = onProgress;
         this._signal = signal;
@@ -3727,6 +3763,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;
@@ -3738,6 +3776,7 @@ var init_QvdFileReader = __esm({
         this._indexColumns = null;
         this._rowsDecoded = 0;
         this._fileSize = null;
+        this._fileIdentity = null;
         this._headerMatchesFile = false;
       }
       /**
@@ -3966,8 +4005,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
@@ -3983,7 +4023,8 @@ 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 resolved = headerNumbersUsable ? resolveWindow(window, totalRows) : { offset: 0, limit: 0 };
         const windowRows = resolved.limit;
         if (headerNumbersUsable && this._headerMatchesFile) {
@@ -3997,11 +4038,11 @@ 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.
@@ -4009,7 +4050,11 @@ 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
           );
         }
         if (window.offset === 0 && window.limit === null) {
@@ -4194,6 +4239,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__default.default(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
@@ -4222,7 +4452,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.
        *
@@ -4237,7 +4473,10 @@ var init_QvdFileReader = __esm({
         }
         assert4__default.default(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"]) };
@@ -4559,9 +4798,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);
@@ -4575,13 +4816,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.
-            symbolBytes + readPasses(symbolsToKeep !== null) * rowsToLoad * recordSize
+            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);
         }
@@ -4589,24 +4838,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);
         }
@@ -4701,28 +4962,39 @@ var init_QvdFileReader = __esm({
           await this._parseHeader();
           this._emitProgress("header", 1, 1);
           this._throwIfAborted();
-          assert4__default.default(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 exports.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__default.default(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 exports.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.
        *
@@ -4740,77 +5012,122 @@ 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__default.default(
-            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__default.default(
+          this._header && this._selectedFields && this._allFields && this._symbolTableOffset !== null,
+          "The QVD file header has not been parsed."
+        );
+        const header = this._header["QvdTableHeader"];
+        const totalRows = headerInteger(header["NoOfRecords"]);
+        const recordSize = headerInteger(header["RecordByteSize"]);
+        const symbolTableLength = headerInteger(header["Offset"]);
+        validateRecordSize(recordSize, this._path, "checkRead");
+        validateRecordCount(totalRows, this._path, "checkRead");
+        if (!this._headerMatchesFile) {
+          throw new exports.QvdCorruptedError("The file is shorter than its header claims.", {
+            file: this._path,
+            fileSize: this._fileSize,
+            requiredBytes: this._symbolTableOffset + symbolTableLength + totalRows * recordSize,
+            stage: "checkRead"
+          });
+        }
+        const tableLength = this._symbolTableLength();
+        for (const field of this._allFields) {
+          validateFieldMetadata(field, tableLength, this._path);
+          validateFieldBitMetadata(field, recordSize, this._path);
+        }
+        validateSymbolAreas(this._allFields, this._path);
+      }
+      /**
+       * 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__default.default(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"])
           );
-          const header = this._header["QvdTableHeader"];
-          const totalRows = headerInteger(header["NoOfRecords"]);
-          const recordSize = headerInteger(header["RecordByteSize"]);
-          const symbolTableLength = headerInteger(header["Offset"]);
-          const selected = this._selectedFields;
-          validateRecordSize(recordSize, this._path, "checkRead");
-          validateRecordCount(totalRows, this._path, "checkRead");
-          if (!this._headerMatchesFile) {
-            throw new exports.QvdCorruptedError("The file is shorter than its header claims.", {
-              file: this._path,
-              fileSize: this._fileSize,
-              requiredBytes: this._symbolTableOffset + symbolTableLength + totalRows * recordSize,
-              stage: "checkRead"
-            });
-          }
-          const tableLength = this._symbolTableLength();
-          for (const field of this._allFields) {
-            validateFieldMetadata(field, tableLength, this._path);
-            validateFieldBitMetadata(field, recordSize, this._path);
-          }
-          validateSymbolAreas(this._allFields, this._path);
-          const resolved = resolveWindow(window, totalRows);
-          const windowRows = resolved.limit;
-          const liveRows = chunkSize === null ? null : { rows: chunkSize * 2, perChunk: 2 };
-          const analysisAhead = this._analysisWouldRun(window, resolved, totalRows, symbolTableLength);
-          const measured = getMemoryBudget();
-          const ask = /* @__PURE__ */ __name((fields, rows) => {
-            const bytes = symbolBytesOf(fields, symbolTableLength);
-            return checkMemory({
-              measured,
-              symbolTableSize: bytes,
-              maxRows: rows,
-              totalRows,
-              safetyFactor: this._memorySafetyFactor,
-              columnCount: fields.length,
-              materialisesRows: this._materialisesRows,
-              live: liveRows,
-              bytesHeld: this._bytesHeld(bytes, rows, recordSize, liveRows, analysisAhead),
-              // What it reads from the file, which is not what it holds: the symbol areas, and every record
-              // the window covers, read a slice at a time and not kept - twice over where the symbol-usage
-              // pass will run, since it reads them before the decode reads them again.
-              readBytes: bytes + readPasses(analysisAhead) * windowRows * recordSize
-            });
-          }, "ask");
-          const answer = ask(selected, windowRows);
-          if (!answer.fits && selected.length > 1) {
-            const bySize = [...selected].sort(
-              (a, b) => headerInteger(a["Length"]) - headerInteger(b["Length"])
-            );
-            for (let take = selected.length - 1; take >= 1; take -= 1) {
-              const fewer = bySize.slice(0, take);
-              if (ask(fewer, windowRows).fits) {
-                answer.suggestions.push({
-                  option: "fields",
-                  value: fewer.map((field) => field["FieldName"])
-                });
-                break;
-              }
+          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.
@@ -4976,7 +5293,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);
         }
@@ -5068,6 +5385,224 @@ var init_QvdFileReader = __esm({
   }
 });
 
+// src/QvdFile.js
+var QvdFile_exports = {};
+__export(QvdFile_exports, {
+  QvdFile: () => exports.QvdFile
+});
+exports.QvdFile = void 0;
+var init_QvdFile = __esm({
+  "src/QvdFile.js"() {
+    init_QvdErrors();
+    init_readOptions();
+    exports.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 exports.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 exports.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 {
@@ -5878,6 +6413,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.
        *
@@ -6182,6 +6760,7 @@ __name(dateToQlikSerial, "dateToQlikSerial");
 // src/index.js
 init_QvdDataFrame();
 init_QvdColumnTable();
+init_QvdFile();
 init_QvdFileReader();
 init_QvdFileWriter();
 init_QvdErrors();