qvdjs 0.2.0

package/dist/index.cjs

@@ -0,0 +1,1615 @@
+'use strict';
+
+var path2 = require('path');
+var fs2 = require('fs');
+var crypto = require('crypto');
+var xml2 = require('xml2js');
+var assert = require('assert');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var path2__default = /*#__PURE__*/_interopDefault(path2);
+var fs2__default = /*#__PURE__*/_interopDefault(fs2);
+var crypto__default = /*#__PURE__*/_interopDefault(crypto);
+var xml2__default = /*#__PURE__*/_interopDefault(xml2);
+var assert__default = /*#__PURE__*/_interopDefault(assert);
+
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/QvdErrors.js
+exports.QvdError = void 0; exports.QvdParseError = void 0; exports.QvdValidationError = void 0; exports.QvdIOError = void 0; exports.QvdCorruptedError = void 0; exports.QvdSecurityError = void 0;
+var init_QvdErrors = __esm({
+  "src/QvdErrors.js"() {
+    exports.QvdError = class extends Error {
+      /**
+       * Constructs a new QVD error.
+       *
+       * @param {string} message The error message.
+       * @param {string} code The error code.
+       * @param {Object} [context={}] Additional context about the error.
+       */
+      constructor(message, code, context = {}) {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = code;
+        this.context = context;
+        Error.captureStackTrace(this, this.constructor);
+      }
+    };
+    exports.QvdParseError = class extends exports.QvdError {
+      /**
+       * Constructs a new QVD parse error.
+       *
+       * @param {string} message The error message.
+       * @param {Object} [context={}] Additional context about the error.
+       */
+      constructor(message, context = {}) {
+        super(message, "QVD_PARSE_ERROR", context);
+      }
+    };
+    exports.QvdValidationError = class extends exports.QvdError {
+      /**
+       * Constructs a new QVD validation error.
+       *
+       * @param {string} message The error message.
+       * @param {Object} [context={}] Additional context about the error.
+       */
+      constructor(message, context = {}) {
+        super(message, "QVD_VALIDATION_ERROR", context);
+      }
+    };
+    exports.QvdIOError = class extends exports.QvdError {
+      /**
+       * Constructs a new QVD IO error.
+       *
+       * @param {string} message The error message.
+       * @param {Object} [context={}] Additional context about the error.
+       */
+      constructor(message, context = {}) {
+        super(message, "QVD_IO_ERROR", context);
+      }
+    };
+    exports.QvdCorruptedError = class extends exports.QvdError {
+      /**
+       * Constructs a new QVD corrupted error.
+       *
+       * @param {string} message The error message.
+       * @param {Object} [context={}] Additional context about the error.
+       */
+      constructor(message, context = {}) {
+        super(message, "QVD_CORRUPTED_ERROR", context);
+      }
+    };
+    exports.QvdSecurityError = class extends exports.QvdError {
+      /**
+       * Constructs a new QVD security error.
+       *
+       * @param {string} message The error message.
+       * @param {Object} [context={}] Additional context about the error.
+       */
+      constructor(message, context = {}) {
+        super(message, "QVD_SECURITY_ERROR", context);
+      }
+    };
+  }
+});
+
+// src/QvdSymbol.js
+exports.QvdSymbol = void 0;
+var init_QvdSymbol = __esm({
+  "src/QvdSymbol.js"() {
+    init_QvdErrors();
+    exports.QvdSymbol = class _QvdSymbol {
+      /**
+       * Constructs a new QVD symbol.
+       *
+       * @param {number|null} intValue The integer value.
+       * @param {number|null} doubleValue The double value.
+       * @param {string|null} stringValue The string value.
+       */
+      constructor(intValue, doubleValue, stringValue) {
+        this._intValue = intValue;
+        this._doubleValue = doubleValue;
+        this._stringValue = stringValue;
+      }
+      /**
+       * Returns the integer value of this symbol.
+       *
+       * @return {number|null} The integer value.
+       */
+      get intValue() {
+        return this._intValue;
+      }
+      /**
+       * Returns the double value of this symbol.
+       *
+       * @return {number|null} The double value.
+       */
+      get doubleValue() {
+        return this._doubleValue;
+      }
+      /**
+       * Returns the string value of this symbol.
+       *
+       * @return {string|null} The string value.
+       */
+      get stringValue() {
+        return this._stringValue;
+      }
+      /**
+       * Retrieves the primary value of this symbol. The primary value is descriptive raw value.
+       * It is either the string value, the integer value or the double value, prioritized in this order.
+       *
+       * @return {number|string|null} The primary value.
+       */
+      toPrimaryValue() {
+        if (null != this._stringValue) {
+          return this._stringValue;
+        } else if (null != this._intValue) {
+          return this._intValue;
+        } else if (null != this._doubleValue) {
+          return this._doubleValue;
+        } else {
+          return null;
+        }
+      }
+      /**
+       * Converts the symbol to its byte representation.
+       *
+       * @return {Buffer} The byte representation of the symbol.
+       */
+      toByteRepresentation() {
+        if (this._intValue !== null && this._stringValue !== null) {
+          const intBuffer = Buffer.alloc(4);
+          intBuffer.writeInt32LE(this._intValue);
+          const stringBuffer = Buffer.concat([Buffer.from(this._stringValue, "utf-8"), Buffer.from([0])]);
+          return Buffer.concat([Buffer.from([5]), intBuffer, stringBuffer]);
+        } else if (this._doubleValue !== null && this._stringValue !== null) {
+          const floatBuffer = Buffer.alloc(8);
+          floatBuffer.writeDoubleLE(this._doubleValue);
+          const stringBuffer = Buffer.concat([Buffer.from(this._stringValue, "utf-8"), Buffer.from([0])]);
+          return Buffer.concat([Buffer.from([6]), floatBuffer, stringBuffer]);
+        } else if (this._intValue !== null) {
+          const buffer = Buffer.alloc(4);
+          buffer.writeInt32LE(this._intValue);
+          return Buffer.concat([Buffer.from([1]), buffer]);
+        } else if (this._doubleValue !== null) {
+          const buffer = Buffer.alloc(8);
+          buffer.writeDoubleLE(this._doubleValue);
+          return Buffer.concat([Buffer.from([2]), buffer]);
+        } else if (this._stringValue !== null) {
+          const buffer = Buffer.concat([Buffer.from(this._stringValue, "utf-8"), Buffer.from([0])]);
+          return Buffer.concat([Buffer.from([4]), buffer]);
+        } else {
+          throw new exports.QvdValidationError("The symbol does not contain any value.", {
+            intValue: this._intValue,
+            doubleValue: this._doubleValue,
+            stringValue: this._stringValue
+          });
+        }
+      }
+      /**
+       * Checks if this symbol is equal to another symbol.
+       *
+       * @param {*} value The object to compare with.
+       * @return {boolean} True if the objects are equal, false otherwise.
+       */
+      equals(value) {
+        if (!(value instanceof _QvdSymbol)) {
+          return false;
+        }
+        return this._intValue === value.intValue && this._doubleValue === value.doubleValue && this._stringValue === value.stringValue;
+      }
+      /**
+       * Constructs a pure integer value symbol.
+       *
+       * @param {number} intValue The integer value.
+       * @return {QvdSymbol} The constructed value symbol.
+       */
+      static fromIntValue(intValue) {
+        return new _QvdSymbol(intValue, null, null);
+      }
+      /**
+       * Constructs a pure double value symbol.
+       *
+       * @param {number} doubleValue The double value.
+       * @return {QvdSymbol} The constructed value symbol.
+       */
+      static fromDoubleValue(doubleValue) {
+        return new _QvdSymbol(null, doubleValue, null);
+      }
+      /**
+       * Constructs a pure string value symbol.
+       *
+       * @param {string} stringValue The string value.
+       * @return {QvdSymbol} The constructed value symbol.
+       */
+      static fromStringValue(stringValue) {
+        return new _QvdSymbol(null, null, stringValue);
+      }
+      /**
+       * Constructs a dual value symbol from an integer and a string value.
+       *
+       * @param {number} intValue The integer value.
+       * @param {string} stringValue The string value.
+       * @return {QvdSymbol} The constructed value symbol.
+       */
+      static fromDualIntValue(intValue, stringValue) {
+        return new _QvdSymbol(intValue, null, stringValue);
+      }
+      /**
+       * Constructs a dual value symbol from a double and a string value.
+       *
+       * @param {number} doubleValue The double value.
+       * @param {string} stringValue The string value.
+       * @return {QvdSymbol} The constructed value symbol.
+       */
+      static fromDualDoubleValue(doubleValue, stringValue) {
+        return new _QvdSymbol(null, doubleValue, stringValue);
+      }
+    };
+  }
+});
+function validatePath(filePath, allowedDir) {
+  if (filePath.includes("\0")) {
+    throw new exports.QvdSecurityError("Path traversal detected: Null byte in path", {
+      path: filePath,
+      reason: "null_byte"
+    });
+  }
+  const baseDir = allowedDir || process.cwd();
+  const resolvedBaseDir = path2__default.default.resolve(baseDir);
+  const resolvedPath = path2__default.default.resolve(filePath);
+  const isCaseInsensitiveFS = process.platform === "win32" || process.platform === "darwin";
+  const baseForComparison = isCaseInsensitiveFS ? resolvedBaseDir.toLowerCase() : resolvedBaseDir;
+  const pathForComparison = isCaseInsensitiveFS ? resolvedPath.toLowerCase() : resolvedPath;
+  if (!pathForComparison.startsWith(baseForComparison + path2__default.default.sep) && pathForComparison !== baseForComparison) {
+    throw new exports.QvdSecurityError("Path traversal detected: Access denied", {
+      path: filePath,
+      resolvedPath,
+      allowedDir: resolvedBaseDir,
+      reason: "outside_allowed_directory"
+    });
+  }
+  return resolvedPath;
+}
+var init_validatePath = __esm({
+  "src/util/validatePath.js"() {
+    init_QvdErrors();
+  }
+});
+
+// src/QvdFileWriter.js
+var QvdFileWriter_exports = {};
+__export(QvdFileWriter_exports, {
+  QvdFileWriter: () => exports.QvdFileWriter
+});
+exports.QvdFileWriter = void 0;
+var init_QvdFileWriter = __esm({
+  "src/QvdFileWriter.js"() {
+    init_QvdSymbol();
+    init_validatePath();
+    exports.QvdFileWriter = class _QvdFileWriter {
+      /**
+       * Constructs a new QVD file writer.
+       *
+       * @param {string} filePath The path to the QVD file to write.
+       * @param {QvdDataFrame} df The data frame to write to the QVD file.
+       * @param {Object} [options={}] Options for the writer.
+       * @param {string} [options.allowedDir] Optional allowed directory path. If provided, the file
+       *   path must be within this directory. Defaults to current working directory.
+       * @param {Function} [options.onProgress] Optional progress callback function.
+       */
+      constructor(filePath, df, options = {}) {
+        const { allowedDir, onProgress } = options;
+        this._path = validatePath(filePath, allowedDir);
+        this._df = df;
+        this._onProgress = onProgress;
+        this._header = null;
+        this._symbolBuffer = null;
+        this._symbolTable = null;
+        this._symbolTableMetadata = null;
+        this._indexBuffer = null;
+        this._indexTable = null;
+        this._indexTableMetadata = null;
+        this._recordByteSize = null;
+      }
+      /**
+       * Emits a progress event if a callback is registered.
+       *
+       * @param {string} stage The current stage of the operation.
+       * @param {number} current The current progress value.
+       * @param {number} total The total progress value.
+       */
+      _emitProgress(stage, current, total) {
+        if (this._onProgress) {
+          const percent = total > 0 ? Math.round(current / total * 100) : 100;
+          this._onProgress({
+            stage,
+            current,
+            total,
+            percent
+          });
+        }
+      }
+      /**
+       * Writes the data to the QVD file.
+       */
+      async _writeData() {
+        assert__default.default(this._header, "The QVD file header has not been parsed.");
+        assert__default.default(this._symbolBuffer, "The QVD file symbol table has not been parsed.");
+        assert__default.default(this._indexBuffer, "The QVD file index table has not been parsed.");
+        this._emitProgress("write", 0, 1);
+        const headerBuffer = Buffer.concat([Buffer.from(this._header, "utf-8"), Buffer.from([0])]);
+        let fd;
+        try {
+          fd = await fs2__default.default.promises.open(this._path, "w");
+          await fd.write(headerBuffer, 0, headerBuffer.length, 0);
+          await fd.write(this._symbolBuffer, 0, this._symbolBuffer.length, headerBuffer.length);
+          await fd.write(this._indexBuffer, 0, this._indexBuffer.length, headerBuffer.length + this._symbolBuffer.length);
+          this._emitProgress("write", 1, 1);
+        } finally {
+          if (fd) {
+            await fd.close();
+          }
+        }
+      }
+      /**
+       * Builds the XML header of the QVD file.
+       */
+      _buildHeader() {
+        this._emitProgress("header", 0, 1);
+        const creationDate = (/* @__PURE__ */ new Date()).toISOString().replace(/T/, " ").replace(/\..+/, "");
+        const existingMetadata = this._df.metadata;
+        const baseMetadata = existingMetadata ? {
+          QvBuildNo: existingMetadata.QvBuildNo || 50667,
+          CreatorDoc: existingMetadata.CreatorDoc || crypto__default.default.randomUUID(),
+          CreateUtcTime: existingMetadata.CreateUtcTime || creationDate,
+          SourceCreateUtcTime: existingMetadata.SourceCreateUtcTime || "",
+          SourceFileUtcTime: existingMetadata.SourceFileUtcTime || "",
+          SourceFileSize: existingMetadata.SourceFileSize || -1,
+          StaleUtcTime: existingMetadata.StaleUtcTime || "",
+          TableName: existingMetadata.TableName || path2__default.default.basename(this._path, path2__default.default.extname(this._path)),
+          Compression: existingMetadata.Compression || "",
+          Comment: existingMetadata.Comment || "",
+          EncryptionInfo: existingMetadata.EncryptionInfo || "",
+          TableTags: existingMetadata.TableTags || "",
+          ProfilingData: existingMetadata.ProfilingData || "",
+          Lineage: existingMetadata.Lineage || {
+            LineageInfo: {
+              Discriminator: "INLINE;",
+              Statement: ""
+            }
+          }
+        } : {
+          QvBuildNo: 50667,
+          CreatorDoc: crypto__default.default.randomUUID(),
+          CreateUtcTime: creationDate,
+          SourceCreateUtcTime: "",
+          SourceFileUtcTime: "",
+          SourceFileSize: -1,
+          StaleUtcTime: "",
+          TableName: path2__default.default.basename(this._path, path2__default.default.extname(this._path)),
+          Compression: "",
+          Comment: "",
+          EncryptionInfo: "",
+          TableTags: "",
+          ProfilingData: "",
+          Lineage: {
+            LineageInfo: {
+              Discriminator: "INLINE;",
+              Statement: ""
+            }
+          }
+        };
+        let existingFields = [];
+        if (existingMetadata && existingMetadata.Fields && existingMetadata.Fields.QvdFieldHeader) {
+          existingFields = Array.isArray(existingMetadata.Fields.QvdFieldHeader) ? existingMetadata.Fields.QvdFieldHeader : [existingMetadata.Fields.QvdFieldHeader];
+        }
+        const xmlObject = {
+          QvdTableHeader: {
+            ...baseMetadata,
+            Fields: {
+              QvdFieldHeader: this._df.columns.map((column, index) => {
+                const existingField = existingFields.find((f) => f.FieldName === column);
+                return {
+                  FieldName: column,
+                  BitOffset: this._indexTableMetadata?.[index][0],
+                  BitWidth: this._indexTableMetadata?.[index][1],
+                  Bias: this._indexTableMetadata?.[index][2],
+                  NoOfSymbols: this._symbolTable?.[index].length,
+                  Offset: this._symbolTableMetadata?.[index][0],
+                  Length: this._symbolTableMetadata?.[index][1],
+                  Comment: existingField?.Comment || "",
+                  NumberFormat: existingField?.NumberFormat || {
+                    Type: "UNKNOWN",
+                    nDec: "0",
+                    UseThou: "0",
+                    Fmt: "",
+                    Dec: "",
+                    Thou: ""
+                  },
+                  Tags: existingField?.Tags || {}
+                };
+              })
+            },
+            NoOfRecords: this._indexTable?.length,
+            RecordByteSize: this._recordByteSize,
+            Offset: this._symbolTableMetadata && this._symbolTableMetadata.length > 0 ? this._symbolTableMetadata[this._symbolTableMetadata.length - 1][0] + this._symbolTableMetadata[this._symbolTableMetadata.length - 1][1] : 0,
+            Length: this._indexBuffer?.length
+          }
+        };
+        const builder = new xml2__default.default.Builder({
+          renderOpts: {
+            pretty: true,
+            newline: "\r\n",
+            indent: "  "
+          }
+        });
+        this._header = builder.buildObject(xmlObject) + "\r\n";
+        this._emitProgress("header", 1, 1);
+      }
+      /**
+       * Builds the symbol table of the QVD file.
+       * Optimized to build all columns in a single pass through the data.
+       */
+      _buildSymbolTable() {
+        this._symbolTable = [];
+        this._symbolTableMetadata = [];
+        this._symbolBuffer = Buffer.alloc(0);
+        const numColumns = this._df.columns.length;
+        this._emitProgress("symbol-table", 0, numColumns);
+        const uniqueValuesSets = this._df.columns.map(() => /* @__PURE__ */ new Set());
+        this._df.data.forEach((row) => {
+          this._df.columns.forEach((column, columnIndex) => {
+            const value = row[columnIndex];
+            uniqueValuesSets[columnIndex].add(value);
+          });
+        });
+        this._df.columns.forEach((column, columnIndex) => {
+          const uniqueValuesSet = uniqueValuesSets[columnIndex];
+          const uniqueValues = Array.from(uniqueValuesSet);
+          const containsNull = uniqueValues.includes(null) || uniqueValues.includes(void 0);
+          const symbols = uniqueValues.filter((value) => value !== null && value !== void 0).map((value) => _QvdFileWriter._convertRawToSymbol(value));
+          const currentSymbolBuffer = Buffer.concat(symbols.map((symbol) => symbol.toByteRepresentation()));
+          this._symbolBuffer = this._symbolBuffer ? Buffer.concat([this._symbolBuffer, currentSymbolBuffer]) : currentSymbolBuffer;
+          const symbolsLength = currentSymbolBuffer.length;
+          const symbolsOffset = this._symbolBuffer.length - symbolsLength;
+          this._symbolTableMetadata?.push([symbolsOffset, symbolsLength, containsNull]);
+          this._symbolTable?.push(symbols);
+          this._emitProgress("symbol-table", columnIndex + 1, numColumns);
+        });
+      }
+      /**
+       * Builds the index table of the QVD file.
+       * Optimized with Map-based lookups for O(1) symbol index retrieval.
+       */
+      _buildIndexTable() {
+        this._indexTable = [];
+        this._indexTableMetadata = [];
+        this._indexBuffer = Buffer.alloc(0);
+        const numRows = this._df.data.length;
+        this._emitProgress("index-table", 0, numRows);
+        const symbolIndexMaps = this._symbolTable?.map((symbols) => {
+          const map = /* @__PURE__ */ new Map();
+          symbols.forEach((symbol, idx) => {
+            const key = `${symbol.intValue}|${symbol.doubleValue}|${symbol.stringValue}`;
+            map.set(key, idx);
+          });
+          return map;
+        });
+        let processedRows = 0;
+        const progressInterval = Math.max(1, Math.floor(numRows / 100));
+        this._df.data.forEach((row) => {
+          const indices = this._df.columns.map((column, columnIndex) => {
+            const value = row[columnIndex];
+            const symbol = _QvdFileWriter._convertRawToSymbol(value);
+            const fieldContainsNull = this._symbolTableMetadata?.[columnIndex][2];
+            if (symbol === null) {
+              return 0;
+            } else {
+              const key = `${symbol.intValue}|${symbol.doubleValue}|${symbol.stringValue}`;
+              const symbolIndex = symbolIndexMaps?.[columnIndex].get(key);
+              return fieldContainsNull ? (symbolIndex ?? 0) + 2 : symbolIndex ?? 0;
+            }
+          });
+          const stringIndices = indices.map((index) => {
+            const bits = _QvdFileWriter._convertInt32ToBits(index, 32);
+            let bitString = bits.join("");
+            bitString = bitString.replace(/^0+/, "") || "0";
+            return bitString;
+          });
+          this._indexTable?.push(stringIndices);
+          processedRows++;
+          if (processedRows % progressInterval === 0 || processedRows === numRows) {
+            this._emitProgress("index-table", processedRows, numRows);
+          }
+        });
+        this._df.columns.forEach((column) => {
+          const bitOffset = this._indexTableMetadata?.slice(0, this._df.columns.indexOf(column)).reduce((sum, metadata) => sum + metadata[1], 0);
+          assert__default.default(this._indexTable, "The QVD file header has not been parsed.");
+          const bitWidth = this._indexTable.length > 0 ? Math.max(
+            ...this._indexTable.map(
+              (indices) => indices[this._df.columns.indexOf(column)].length
+            )
+          ) : 0;
+          const fieldContainsNull = this._symbolTableMetadata?.[this._df.columns.indexOf(column)][2];
+          const bias = fieldContainsNull ? -2 : 0;
+          this._indexTableMetadata?.push([bitOffset, bitWidth, bias]);
+          this._indexTable.forEach((indices) => {
+            const bitString = indices[this._df.columns.indexOf(column)];
+            const paddedBitString = bitString.padStart(bitWidth, "0");
+            indices[this._df.columns.indexOf(column)] = paddedBitString;
+          });
+        });
+        this._indexBuffer = Buffer.concat(
+          // @ts-ignore - Buffer array type compatibility
+          this._indexTable.map((indices) => {
+            indices.reverse();
+            const bits = indices.join("");
+            const paddingWidth = (8 - bits.length % 8) % 8;
+            const paddedBits = bits.padStart(bits.length + paddingWidth, "0");
+            const bytes = paddedBits.match(/.{1,8}/g)?.map((byte) => parseInt(byte, 2));
+            bytes?.reverse();
+            assert__default.default(bytes, "Byte conversion of bit indices failed.");
+            return Buffer.from(Uint8Array.from(bytes));
+          })
+        );
+        this._recordByteSize = this._indexTable.length > 0 ? this._indexBuffer.length / this._indexTable.length : 1;
+      }
+      /**
+       * Converts a raw value/literal to a QVD symbol.
+       *
+       * @param {any} raw The raw value/literal to convert.
+       * @return {QvdSymbol|null} The converted QVD symbol.
+       */
+      static _convertRawToSymbol(raw) {
+        if (raw === null || raw === void 0) {
+          return null;
+        }
+        const INT32_MIN = -2147483648;
+        const INT32_MAX = 2147483647;
+        const isInteger = typeof raw === "number" && Number.isInteger(raw);
+        const isFloat = typeof raw === "number" && !Number.isInteger(raw);
+        const isWithinInt32Range = typeof raw === "number" && raw >= INT32_MIN && raw <= INT32_MAX;
+        if (isInteger && isWithinInt32Range) {
+          return exports.QvdSymbol.fromDualIntValue(raw, raw.toString());
+        } else if (isFloat || isInteger && !isWithinInt32Range) {
+          return exports.QvdSymbol.fromDualDoubleValue(raw, raw.toString());
+        } else {
+          return exports.QvdSymbol.fromStringValue(raw);
+        }
+      }
+      /**
+       * Converts an integer to a list of bits.
+       *
+       * @param {number} value The integer value to convert.
+       * @param {number} width The width of the bit list.
+       * @return {Array<number>} The list of bits.
+       */
+      static _convertInt32ToBits(value, width) {
+        return value.toString(2).split("").map((bit) => parseInt(bit)).reverse().concat(new Array(width).fill(0)).slice(0, width).reverse();
+      }
+      /**
+       * Persists the data frame to a QVD file.
+       */
+      async save() {
+        this._buildSymbolTable();
+        this._buildIndexTable();
+        this._buildHeader();
+        await this._writeData();
+      }
+    };
+  }
+});
+
+// src/QvdFileReader.js
+var QvdFileReader_exports = {};
+__export(QvdFileReader_exports, {
+  QvdFileReader: () => exports.QvdFileReader
+});
+exports.QvdFileReader = void 0;
+var init_QvdFileReader = __esm({
+  "src/QvdFileReader.js"() {
+    init_QvdSymbol();
+    init_QvdDataFrame();
+    init_QvdErrors();
+    init_validatePath();
+    exports.QvdFileReader = class {
+      /**
+       * Constructs a new QVD file parser.
+       *
+       * @param {string} filePath The path to the QVD file to load.
+       * @param {Object} [options={}] Options for the reader.
+       * @param {string} [options.allowedDir] Optional allowed directory path. If provided, the file
+       *   path must be within this directory. Defaults to current working directory.
+       */
+      constructor(filePath, options = {}) {
+        const { allowedDir } = options;
+        this._path = validatePath(filePath, allowedDir);
+        this._buffer = null;
+        this._headerOffset = null;
+        this._symbolTableOffset = null;
+        this._indexTableOffset = null;
+        this._header = null;
+        this._symbolTable = null;
+        this._indexTable = null;
+      }
+      /**
+       * Reads the binary data of the QVD file. This method is part of the parsing process
+       * and should not be called directly.
+       *
+       * @param {number|null} maxRows The maximum number of rows to load. If null, all data is loaded.
+       */
+      async _readData(maxRows = null) {
+        if (maxRows === null) {
+          this._buffer = await fs2__default.default.promises.readFile(this._path);
+          return;
+        }
+        const HEADER_DELIMITER = "\r\n\0";
+        const CHUNK_SIZE = 64 * 1024;
+        const stream = fs2__default.default.createReadStream(this._path, {
+          highWaterMark: CHUNK_SIZE
+        });
+        let headerBuffer = Buffer.alloc(0);
+        let headerDelimiterIndex = -1;
+        try {
+          for await (const chunk of stream) {
+            headerBuffer = Buffer.concat([headerBuffer, chunk]);
+            headerDelimiterIndex = headerBuffer.indexOf(HEADER_DELIMITER);
+            if (headerDelimiterIndex !== -1) {
+              stream.destroy();
+              break;
+            }
+          }
+        } catch (error) {
+          if (error && typeof error === "object" && "code" in error && error.code !== "ERR_STREAM_PREMATURE_CLOSE") {
+            throw error;
+          }
+        }
+        if (headerDelimiterIndex === -1) {
+          throw new exports.QvdCorruptedError(
+            "The XML header section does not exist or is not properly delimited from the binary data.",
+            {
+              file: this._path,
+              stage: "readData"
+            }
+          );
+        }
+        const headerEndIndex = headerDelimiterIndex + HEADER_DELIMITER.length;
+        const headerXml = headerBuffer.subarray(0, headerEndIndex).toString();
+        const headerObj = await xml2__default.default.parseStringPromise(headerXml, { explicitArray: false });
+        if (!headerObj) {
+          throw new exports.QvdParseError("The XML header could not be parsed.", {
+            file: this._path,
+            stage: "readData"
+          });
+        }
+        const symbolTableOffset = headerEndIndex;
+        const symbolTableLength = parseInt(headerObj["QvdTableHeader"]["Offset"], 10);
+        const indexTableOffset = symbolTableOffset + symbolTableLength;
+        const recordSize = parseInt(headerObj["QvdTableHeader"]["RecordByteSize"], 10);
+        const totalRows = parseInt(headerObj["QvdTableHeader"]["NoOfRecords"], 10);
+        const rowsToLoad = Math.min(maxRows, totalRows);
+        const indexTableBytesToRead = rowsToLoad * recordSize;
+        const totalBytesToRead = indexTableOffset + indexTableBytesToRead;
+        const fd = await fs2__default.default.promises.open(this._path, "r");
+        try {
+          this._buffer = Buffer.allocUnsafe(totalBytesToRead);
+          await fd.read(this._buffer, 0, totalBytesToRead, 0);
+        } finally {
+          await fd.close();
+        }
+      }
+      /**
+       * Parses the XML header of the QVD file. This method is part of the parsing process
+       * and should not be called directly.
+       */
+      async _parseHeader() {
+        if (!this._buffer) {
+          throw new exports.QvdCorruptedError(
+            "The QVD file has not been loaded in the proper order or has not been loaded at all.",
+            {
+              file: this._path,
+              stage: "parseHeader"
+            }
+          );
+        }
+        const HEADER_DELIMITER = "\r\n\0";
+        const headerBeginIndex = 0;
+        const headerDelimiterIndex = this._buffer.indexOf(HEADER_DELIMITER, headerBeginIndex);
+        if (headerDelimiterIndex === -1) {
+          throw new exports.QvdCorruptedError(
+            "The XML header section does not exist or is not properly delimited from the binary data.",
+            {
+              file: this._path,
+              stage: "parseHeader"
+            }
+          );
+        }
+        const headerEndIndex = headerDelimiterIndex + HEADER_DELIMITER.length;
+        const headerBuffer = this._buffer.subarray(headerBeginIndex, headerEndIndex);
+        this._header = await xml2__default.default.parseStringPromise(headerBuffer.toString(), { explicitArray: false });
+        if (!this._header) {
+          throw new exports.QvdParseError("The XML header could not be parsed.", {
+            file: this._path,
+            stage: "parseHeader"
+          });
+        }
+        this._headerOffset = headerBeginIndex;
+        this._symbolTableOffset = headerEndIndex;
+        this._indexTableOffset = this._symbolTableOffset + parseInt(this._header["QvdTableHeader"]["Offset"], 10);
+      }
+      /**
+       * Parses the symbol table of the QVD file. This method is part of the parsing process
+       * and should not be called directly.
+       */
+      async _parseSymbolTable() {
+        if (!this._buffer || !this._header || !this._symbolTableOffset || !this._indexTableOffset) {
+          throw new exports.QvdCorruptedError(
+            "The QVD file has not been loaded in the proper order or has not been loaded at all.",
+            {
+              file: this._path,
+              stage: "parseSymbolTable"
+            }
+          );
+        }
+        let fields = this._header["QvdTableHeader"]["Fields"]["QvdFieldHeader"];
+        const symbolBuffer = this._buffer.subarray(this._symbolTableOffset, this._indexTableOffset);
+        if (!Array.isArray(fields)) {
+          fields = [fields];
+        }
+        for (const field of fields) {
+          const symbolsOffset = parseInt(field["Offset"], 10);
+          const symbolsLength = parseInt(field["Length"], 10);
+          if (isNaN(symbolsOffset) || !Number.isSafeInteger(symbolsOffset) || symbolsOffset < 0) {
+            throw new exports.QvdCorruptedError("Invalid symbol offset", {
+              field: field["FieldName"],
+              offset: symbolsOffset,
+              file: this._path,
+              stage: "parseSymbolTable"
+            });
+          }
+          if (isNaN(symbolsLength) || !Number.isSafeInteger(symbolsLength) || symbolsLength < 0) {
+            throw new exports.QvdCorruptedError("Invalid symbol length", {
+              field: field["FieldName"],
+              length: symbolsLength,
+              file: this._path,
+              stage: "parseSymbolTable"
+            });
+          }
+          if (symbolsOffset + symbolsLength > symbolBuffer.length) {
+            throw new exports.QvdCorruptedError("Symbol data extends beyond buffer", {
+              field: field["FieldName"],
+              offset: symbolsOffset,
+              length: symbolsLength,
+              bufferSize: symbolBuffer.length,
+              file: this._path,
+              stage: "parseSymbolTable"
+            });
+          }
+        }
+        this._symbolTable = fields.map((field) => {
+          const symbolsOffset = parseInt(field["Offset"], 10);
+          const symbolsLength = parseInt(field["Length"], 10);
+          const symbols = [];
+          for (let pointer = symbolsOffset; pointer < symbolsOffset + symbolsLength; pointer++) {
+            const typeByte = symbolBuffer[pointer++];
+            switch (typeByte) {
+              case 1: {
+                if (pointer + 4 > symbolBuffer.length) {
+                  throw new exports.QvdCorruptedError("Buffer overflow reading integer symbol", {
+                    field: field["FieldName"],
+                    pointer,
+                    bufferSize: symbolBuffer.length,
+                    file: this._path,
+                    stage: "parseSymbolTable"
+                  });
+                }
+                const byteData = new Int32Array(symbolBuffer.subarray(pointer, pointer + 4));
+                const value = Buffer.from(byteData).readIntLE(0, byteData.length);
+                pointer += 3;
+                symbols.push(exports.QvdSymbol.fromIntValue(value));
+                break;
+              }
+              case 2: {
+                if (pointer + 8 > symbolBuffer.length) {
+                  throw new exports.QvdCorruptedError("Buffer overflow reading double symbol", {
+                    field: field["FieldName"],
+                    pointer,
+                    bufferSize: symbolBuffer.length,
+                    file: this._path,
+                    stage: "parseSymbolTable"
+                  });
+                }
+                const byteData = new Int32Array(symbolBuffer.subarray(pointer, pointer + 8));
+                const value = Buffer.from(byteData).readDoubleLE(0);
+                pointer += 7;
+                symbols.push(exports.QvdSymbol.fromDoubleValue(value));
+                break;
+              }
+              case 4: {
+                const byteData = [];
+                const maxStringLength = 1048576;
+                while (pointer < symbolBuffer.length && symbolBuffer[pointer] !== 0) {
+                  if (byteData.length >= maxStringLength) {
+                    throw new exports.QvdCorruptedError("String symbol exceeds maximum length", {
+                      field: field["FieldName"],
+                      maxLength: maxStringLength,
+                      file: this._path,
+                      stage: "parseSymbolTable"
+                    });
+                  }
+                  byteData.push(symbolBuffer[pointer++]);
+                }
+                if (pointer >= symbolBuffer.length) {
+                  throw new exports.QvdCorruptedError("String symbol not null-terminated", {
+                    field: field["FieldName"],
+                    pointer,
+                    bufferSize: symbolBuffer.length,
+                    file: this._path,
+                    stage: "parseSymbolTable"
+                  });
+                }
+                const value = Buffer.from(byteData).toString("utf-8");
+                symbols.push(exports.QvdSymbol.fromStringValue(value));
+                break;
+              }
+              case 5: {
+                if (pointer + 4 > symbolBuffer.length) {
+                  throw new exports.QvdCorruptedError("Buffer overflow reading dual integer symbol", {
+                    field: field["FieldName"],
+                    pointer,
+                    bufferSize: symbolBuffer.length,
+                    file: this._path,
+                    stage: "parseSymbolTable"
+                  });
+                }
+                const intByteData = new Int32Array(symbolBuffer.subarray(pointer, pointer + 4));
+                const intValue = Buffer.from(intByteData).readIntLE(0, intByteData.length);
+                pointer += 4;
+                const stringByteData = [];
+                const maxStringLength = 1048576;
+                while (pointer < symbolBuffer.length && symbolBuffer[pointer] !== 0) {
+                  if (stringByteData.length >= maxStringLength) {
+                    throw new exports.QvdCorruptedError("Dual string symbol exceeds maximum length", {
+                      field: field["FieldName"],
+                      maxLength: maxStringLength,
+                      file: this._path,
+                      stage: "parseSymbolTable"
+                    });
+                  }
+                  stringByteData.push(symbolBuffer[pointer++]);
+                }
+                if (pointer >= symbolBuffer.length) {
+                  throw new exports.QvdCorruptedError("Dual string symbol not null-terminated", {
+                    field: field["FieldName"],
+                    pointer,
+                    bufferSize: symbolBuffer.length,
+                    file: this._path,
+                    stage: "parseSymbolTable"
+                  });
+                }
+                const stringValue = Buffer.from(stringByteData).toString("utf-8");
+                symbols.push(exports.QvdSymbol.fromDualIntValue(intValue, stringValue));
+                break;
+              }
+              case 6: {
+                if (pointer + 8 > symbolBuffer.length) {
+                  throw new exports.QvdCorruptedError("Buffer overflow reading dual double symbol", {
+                    field: field["FieldName"],
+                    pointer,
+                    bufferSize: symbolBuffer.length,
+                    file: this._path,
+                    stage: "parseSymbolTable"
+                  });
+                }
+                const doubleByteData = new Int32Array(symbolBuffer.subarray(pointer, pointer + 8));
+                const doubleValue = Buffer.from(doubleByteData).readDoubleLE(0);
+                pointer += 8;
+                const stringByteData = [];
+                const maxStringLength = 1048576;
+                while (pointer < symbolBuffer.length && symbolBuffer[pointer] !== 0) {
+                  if (stringByteData.length >= maxStringLength) {
+                    throw new exports.QvdCorruptedError("Dual string symbol exceeds maximum length", {
+                      field: field["FieldName"],
+                      maxLength: maxStringLength,
+                      file: this._path,
+                      stage: "parseSymbolTable"
+                    });
+                  }
+                  stringByteData.push(symbolBuffer[pointer++]);
+                }
+                if (pointer >= symbolBuffer.length) {
+                  throw new exports.QvdCorruptedError("Dual string symbol not null-terminated", {
+                    field: field["FieldName"],
+                    pointer,
+                    bufferSize: symbolBuffer.length,
+                    file: this._path,
+                    stage: "parseSymbolTable"
+                  });
+                }
+                const stringValue = Buffer.from(stringByteData).toString("utf-8");
+                symbols.push(exports.QvdSymbol.fromDualDoubleValue(doubleValue, stringValue));
+                break;
+              }
+              default: {
+                throw new exports.QvdParseError("Unknown symbol type byte", {
+                  typeByte: typeByte.toString(16),
+                  offset: pointer,
+                  file: this._path,
+                  stage: "parseSymbolTable"
+                });
+              }
+            }
+          }
+          return symbols;
+        });
+      }
+      /**
+       * Utility method to convert a bit array to an integer value.
+       *
+       * @param {Array<number>} bits The bit array
+       * @return {Number} The integer value
+       */
+      _convertBitsToInt32(bits) {
+        if (bits.length === 0) {
+          return 0;
+        }
+        return bits.reduce((value, bit, index) => value += bit * Math.pow(2, index), 0);
+      }
+      /**
+       * Parses the bit stuffed index table of the QVD file. This method is part of the parsing process
+       * and should not be called directly.
+       *
+       * @param {number|null} maxRows The maximum number of rows to parse. If null, all rows are parsed.
+       */
+      async _parseIndexTable(maxRows = null) {
+        if (!this._buffer || !this._header || !this._indexTableOffset) {
+          throw new exports.QvdCorruptedError(
+            "The QVD file has not been loaded in the proper order or has not been loaded at all.",
+            {
+              file: this._path,
+              stage: "parseIndexTable"
+            }
+          );
+        }
+        let fields = this._header["QvdTableHeader"]["Fields"]["QvdFieldHeader"];
+        if (!Array.isArray(fields)) {
+          fields = [fields];
+        }
+        const recordSize = parseInt(this._header["QvdTableHeader"]["RecordByteSize"], 10);
+        if (isNaN(recordSize) || !Number.isSafeInteger(recordSize) || recordSize < 0) {
+          throw new exports.QvdCorruptedError("Invalid record byte size", {
+            recordSize,
+            file: this._path,
+            stage: "parseIndexTable"
+          });
+        }
+        const totalRows = parseInt(this._header["QvdTableHeader"]["NoOfRecords"], 10);
+        if (isNaN(totalRows) || !Number.isSafeInteger(totalRows) || totalRows < 0) {
+          throw new exports.QvdCorruptedError("Invalid number of records", {
+            totalRows,
+            file: this._path,
+            stage: "parseIndexTable"
+          });
+        }
+        if (recordSize === 0 && totalRows > 0) {
+          throw new exports.QvdCorruptedError("Record byte size cannot be zero when records exist", {
+            recordSize,
+            totalRows,
+            file: this._path,
+            stage: "parseIndexTable"
+          });
+        }
+        if (recordSize > 1048576) {
+          throw new exports.QvdCorruptedError("Record byte size exceeds maximum", {
+            recordSize,
+            maxSize: 1048576,
+            file: this._path,
+            stage: "parseIndexTable"
+          });
+        }
+        const rowsToLoad = maxRows !== null ? Math.min(maxRows, totalRows) : totalRows;
+        const indexTableLength = parseInt(this._header["QvdTableHeader"]["Length"], 10);
+        if (isNaN(indexTableLength) || !Number.isSafeInteger(indexTableLength) || indexTableLength < 0) {
+          throw new exports.QvdCorruptedError("Invalid index table length", {
+            length: indexTableLength,
+            file: this._path,
+            stage: "parseIndexTable"
+          });
+        }
+        if (this._indexTableOffset > this._buffer.length) {
+          throw new exports.QvdCorruptedError("Index table offset beyond buffer", {
+            indexTableOffset: this._indexTableOffset,
+            bufferSize: this._buffer.length,
+            file: this._path,
+            stage: "parseIndexTable"
+          });
+        }
+        const maxReasonableOverage = 100 * 1024 * 1024;
+        if (indexTableLength > this._buffer.length + maxReasonableOverage) {
+          throw new exports.QvdCorruptedError("Index table length unreasonably large", {
+            indexTableLength,
+            bufferSize: this._buffer.length,
+            file: this._path,
+            stage: "parseIndexTable"
+          });
+        }
+        const requiredIndexBytes = rowsToLoad * recordSize;
+        if (indexTableLength < requiredIndexBytes) {
+          throw new exports.QvdCorruptedError("Index table length smaller than required", {
+            indexTableLength,
+            requiredBytes: requiredIndexBytes,
+            rowsToLoad,
+            recordSize,
+            file: this._path,
+            stage: "parseIndexTable"
+          });
+        }
+        const indexBuffer = this._buffer.subarray(this._indexTableOffset, this._indexTableOffset + indexTableLength + 1);
+        for (const field of fields) {
+          const bitOffset = parseInt(field["BitOffset"], 10);
+          const bitWidth = parseInt(field["BitWidth"], 10);
+          if (isNaN(bitOffset) || !Number.isSafeInteger(bitOffset) || bitOffset < 0) {
+            throw new exports.QvdCorruptedError("Invalid bit offset", {
+              field: field["FieldName"],
+              bitOffset,
+              file: this._path,
+              stage: "parseIndexTable"
+            });
+          }
+          if (isNaN(bitWidth) || !Number.isSafeInteger(bitWidth) || bitWidth < 0) {
+            throw new exports.QvdCorruptedError("Invalid bit width", {
+              field: field["FieldName"],
+              bitWidth,
+              file: this._path,
+              stage: "parseIndexTable"
+            });
+          }
+          const recordSizeInBits = recordSize * 8;
+          if (bitOffset + bitWidth > recordSizeInBits) {
+            throw new exports.QvdCorruptedError("Bit field extends beyond record size", {
+              field: field["FieldName"],
+              bitOffset,
+              bitWidth,
+              recordSizeInBits,
+              file: this._path,
+              stage: "parseIndexTable"
+            });
+          }
+        }
+        this._indexTable = [];
+        for (let pointer = 0, rowCount = 0; pointer < indexBuffer.length && rowCount < rowsToLoad; pointer += recordSize, rowCount++) {
+          if (pointer + recordSize > indexBuffer.length) {
+            throw new exports.QvdCorruptedError("Buffer overflow reading index table record", {
+              pointer,
+              recordSize,
+              bufferSize: indexBuffer.length,
+              file: this._path,
+              stage: "parseIndexTable"
+            });
+          }
+          const bytes = new Int32Array(indexBuffer.subarray(pointer, pointer + recordSize));
+          bytes.reverse();
+          const mask = bytes.reduce((bits, byte) => bits + ("00000000" + byte.toString(2)).slice(-8), "").split("").reverse().map((bit) => parseInt(bit));
+          const symbolIndices = [];
+          fields.forEach((field) => {
+            const bitOffset = parseInt(field["BitOffset"], 10);
+            const bitWidth = parseInt(field["BitWidth"], 10);
+            const bias = parseInt(field["Bias"], 10);
+            let symbolIndex;
+            if (bitWidth === 0) {
+              symbolIndex = 0;
+            } else {
+              symbolIndex = this._convertBitsToInt32(mask.slice(bitOffset, bitOffset + bitWidth));
+            }
+            symbolIndex += bias;
+            symbolIndices.push(symbolIndex);
+          });
+          this._indexTable.push(symbolIndices);
+        }
+      }
+      /**
+       * Loads the QVD file into memory and parses it.
+       *
+       * @param {number|null} maxRows The maximum number of rows to load. If null, all rows are loaded.
+       * @return {Promise<QvdDataFrame>} The loaded QVD file.
+       */
+      async load(maxRows = null) {
+        await this._readData(maxRows);
+        await this._parseHeader();
+        await this._parseSymbolTable();
+        await this._parseIndexTable(maxRows);
+        assert__default.default(this._header, "The QVD file header has not been parsed.");
+        assert__default.default(this._symbolTable, "The QVD file symbol table has not been parsed.");
+        assert__default.default(this._indexTable, "The QVD file index table has not been parsed.");
+        const getRow = (index) => {
+          if (!this._indexTable || index >= this._indexTable.length) {
+            throw new exports.QvdValidationError("Row index out of bounds", {
+              index,
+              max: this._indexTable ? this._indexTable.length - 1 : -1,
+              file: this._path
+            });
+          }
+          return this._indexTable?.[index].map((symbolIndex, fieldIndex) => {
+            if (symbolIndex < 0) {
+              return null;
+            }
+            const symbol = this._symbolTable?.[fieldIndex]?.[symbolIndex];
+            const value = symbol?.toPrimaryValue();
+            if (typeof value === "string") {
+              if (!isNaN(Number(value))) {
+                return Number(value);
+              }
+            }
+            return value;
+          });
+        };
+        let fields = this._header["QvdTableHeader"]["Fields"]["QvdFieldHeader"];
+        if (!Array.isArray(fields)) {
+          fields = [fields];
+        }
+        const columns = fields.map((field) => field["FieldName"]);
+        const data = this._indexTable.map((_, index) => getRow(index));
+        const metadata = this._header["QvdTableHeader"];
+        return new exports.QvdDataFrame(data, columns, metadata);
+      }
+    };
+  }
+});
+
+// src/QvdDataFrame.js
+exports.QvdDataFrame = void 0;
+var init_QvdDataFrame = __esm({
+  "src/QvdDataFrame.js"() {
+    init_QvdErrors();
+    exports.QvdDataFrame = class _QvdDataFrame {
+      /**
+       * Represents the data frame stored inside a QVD file.
+       * @param {Array<Array<any>>} data The data of the data frame.
+       * @param {Array<string>} columns The columns of the data frame.
+       * @param {QvdMetadata|null} metadata The metadata from the QVD file header (optional).
+       */
+      constructor(data, columns, metadata = null) {
+        this._data = data;
+        this._columns = columns;
+        this._metadata = metadata;
+      }
+      /**
+       * Returns the data of the data frame.
+       */
+      get data() {
+        return this._data;
+      }
+      /**
+       * Returns the columns of the data frame.
+       */
+      get columns() {
+        return this._columns;
+      }
+      /**
+       * Returns the shape of the data frame.
+       */
+      get shape() {
+        return [this._data.length, this._columns.length];
+      }
+      /**
+       * Returns the complete metadata object from the QVD file header.
+       * @return {Object|null} The complete metadata object or null if not available.
+       */
+      get metadata() {
+        return this._metadata;
+      }
+      /**
+       * Returns file-level metadata from the QVD header.
+       * @return {Object} File-level metadata properties.
+       */
+      get fileMetadata() {
+        if (!this._metadata) {
+          return {};
+        }
+        const header = this._metadata;
+        return {
+          qvBuildNo: header.QvBuildNo,
+          creatorDoc: header.CreatorDoc,
+          createUtcTime: header.CreateUtcTime,
+          sourceCreateUtcTime: header.SourceCreateUtcTime,
+          sourceFileUtcTime: header.SourceFileUtcTime,
+          sourceFileSize: header.SourceFileSize,
+          staleUtcTime: header.StaleUtcTime,
+          tableName: header.TableName,
+          noOfRecords: header.NoOfRecords,
+          recordByteSize: header.RecordByteSize,
+          offset: header.Offset,
+          length: header.Length,
+          compression: header.Compression,
+          comment: header.Comment,
+          encryptionInfo: header.EncryptionInfo,
+          tableTags: header.TableTags,
+          profilingData: header.ProfilingData,
+          lineage: header.Lineage
+        };
+      }
+      /**
+       * Returns field-level metadata for a specific field/column.
+       * @param {string} fieldName The name of the field.
+       * @return {Object|null} Field metadata or null if field not found.
+       */
+      getFieldMetadata(fieldName) {
+        if (!this._metadata || !this._metadata.Fields || !this._metadata.Fields.QvdFieldHeader) {
+          return null;
+        }
+        let fields = this._metadata.Fields.QvdFieldHeader;
+        if (!Array.isArray(fields)) {
+          fields = [fields];
+        }
+        const field = fields.find((f) => f.FieldName === fieldName);
+        if (!field) {
+          return null;
+        }
+        return {
+          fieldName: field.FieldName,
+          bitOffset: field.BitOffset,
+          bitWidth: field.BitWidth,
+          bias: field.Bias,
+          noOfSymbols: field.NoOfSymbols,
+          offset: field.Offset,
+          length: field.Length,
+          comment: field.Comment,
+          numberFormat: field.NumberFormat,
+          tags: field.Tags
+        };
+      }
+      /**
+       * Returns field-level metadata for all fields.
+       * @return {Array<Object>} Array of field metadata objects.
+       */
+      getAllFieldMetadata() {
+        if (!this._metadata || !this._metadata.Fields || !this._metadata.Fields.QvdFieldHeader) {
+          return [];
+        }
+        let fields = this._metadata.Fields.QvdFieldHeader;
+        if (!Array.isArray(fields)) {
+          fields = [fields];
+        }
+        return fields.map((field) => ({
+          fieldName: field.FieldName,
+          bitOffset: field.BitOffset,
+          bitWidth: field.BitWidth,
+          bias: field.Bias,
+          noOfSymbols: field.NoOfSymbols,
+          offset: field.Offset,
+          length: field.Length,
+          comment: field.Comment,
+          numberFormat: field.NumberFormat,
+          tags: field.Tags
+        }));
+      }
+      /**
+       * @typedef {Object} FileMetadataUpdate
+       * @property {string|number} [qvBuildNo] - QlikView build number
+       * @property {string} [creatorDoc] - Creator document
+       * @property {string} [createUtcTime] - Creation UTC time
+       * @property {string} [sourceCreateUtcTime] - Source creation UTC time
+       * @property {string} [sourceFileUtcTime] - Source file UTC time
+       * @property {string|number} [sourceFileSize] - Source file size
+       * @property {string} [staleUtcTime] - Stale UTC time
+       * @property {string} [tableName] - Table name
+       * @property {string} [compression] - Compression type
+       * @property {string} [comment] - Comment
+       * @property {string} [encryptionInfo] - Encryption info
+       * @property {string} [tableTags] - Table tags
+       * @property {string} [profilingData] - Profiling data
+       * @property {Object|string} [lineage] - Lineage
+       */
+      /**
+       * Sets modifiable file-level metadata. Immutable properties related to data storage are ignored.
+       * @param {FileMetadataUpdate} metadata Object containing metadata properties to update.
+       */
+      setFileMetadata(metadata) {
+        if (!this._metadata) {
+          this._metadata = {
+            QvBuildNo: 50667,
+            CreatorDoc: "",
+            CreateUtcTime: "",
+            SourceCreateUtcTime: "",
+            SourceFileUtcTime: "",
+            SourceFileSize: -1,
+            StaleUtcTime: "",
+            TableName: "",
+            Fields: {
+              QvdFieldHeader: this._columns.map((column) => ({
+                FieldName: column,
+                BitOffset: 0,
+                BitWidth: 0,
+                Bias: 0,
+                NoOfSymbols: 0,
+                Offset: 0,
+                Length: 0,
+                Comment: "",
+                NumberFormat: {
+                  Type: "UNKNOWN",
+                  nDec: "0",
+                  UseThou: "0",
+                  Fmt: "",
+                  Dec: "",
+                  Thou: ""
+                },
+                Tags: {}
+              }))
+            },
+            NoOfRecords: 0,
+            RecordByteSize: 0,
+            Offset: 0,
+            Length: 0,
+            Compression: "",
+            Comment: "",
+            EncryptionInfo: "",
+            TableTags: "",
+            ProfilingData: "",
+            Lineage: {}
+          };
+        }
+        const modifiableFields = [
+          "qvBuildNo",
+          "creatorDoc",
+          "createUtcTime",
+          "sourceCreateUtcTime",
+          "sourceFileUtcTime",
+          "sourceFileSize",
+          "staleUtcTime",
+          "tableName",
+          "compression",
+          "comment",
+          "encryptionInfo",
+          "tableTags",
+          "profilingData",
+          "lineage"
+        ];
+        const fieldMapping = {
+          qvBuildNo: "QvBuildNo",
+          creatorDoc: "CreatorDoc",
+          createUtcTime: "CreateUtcTime",
+          sourceCreateUtcTime: "SourceCreateUtcTime",
+          sourceFileUtcTime: "SourceFileUtcTime",
+          sourceFileSize: "SourceFileSize",
+          staleUtcTime: "StaleUtcTime",
+          tableName: "TableName",
+          compression: "Compression",
+          comment: "Comment",
+          encryptionInfo: "EncryptionInfo",
+          tableTags: "TableTags",
+          profilingData: "ProfilingData",
+          lineage: "Lineage"
+        };
+        modifiableFields.forEach((field) => {
+          if (metadata[field] !== void 0) {
+            this._metadata[fieldMapping[field]] = metadata[field];
+          }
+        });
+      }
+      /**
+       * @typedef {Object} FieldMetadataUpdate
+       * @property {string} [comment] - Field comment
+       * @property {QvdNumberFormat|string} [numberFormat] - Number format
+       * @property {Object|string} [tags] - Field tags
+       */
+      /**
+       * Sets modifiable field-level metadata for a specific field.
+       * Immutable properties related to data storage (Offset, Length, BitOffset, etc.) are ignored.
+       * @param {string} fieldName The name of the field.
+       * @param {FieldMetadataUpdate} metadata Object containing field metadata properties to update.
+       */
+      setFieldMetadata(fieldName, metadata) {
+        if (!this._metadata || !this._metadata.Fields || !this._metadata.Fields.QvdFieldHeader) {
+          return;
+        }
+        let fields = this._metadata.Fields.QvdFieldHeader;
+        if (!Array.isArray(fields)) {
+          fields = [fields];
+          this._metadata.Fields.QvdFieldHeader = fields;
+        }
+        const fieldIndex = fields.findIndex((f) => f.FieldName === fieldName);
+        if (fieldIndex === -1) {
+          return;
+        }
+        if (metadata.comment !== void 0) {
+          fields[fieldIndex].Comment = metadata.comment;
+        }
+        if (metadata.numberFormat !== void 0) {
+          fields[fieldIndex].NumberFormat = metadata.numberFormat;
+        }
+        if (metadata.tags !== void 0) {
+          fields[fieldIndex].Tags = metadata.tags;
+        }
+      }
+      /**
+       * Returns the first n rows of the data frame.
+       *
+       * @param {number} n The number of rows to return.
+       * @return {QvdDataFrame} The first n rows of the data frame.
+       * @throws {QvdValidationError} If n is not a non-negative integer.
+       */
+      head(n = 5) {
+        if (typeof n !== "number" || !Number.isInteger(n) || n < 0) {
+          throw new exports.QvdValidationError("head() requires a non-negative integer", {
+            provided: n,
+            type: typeof n
+          });
+        }
+        return new _QvdDataFrame(this._data.slice(0, n), this._columns, this._metadata);
+      }
+      /**
+       * Returns the last n rows of the data frame.
+       *
+       * @param {number} n The number of rows to return.
+       * @return {QvdDataFrame} The first n rows of the data frame.
+       * @throws {QvdValidationError} If n is not a non-negative integer.
+       */
+      tail(n = 5) {
+        if (typeof n !== "number" || !Number.isInteger(n) || n < 0) {
+          throw new exports.QvdValidationError("tail() requires a non-negative integer", {
+            provided: n,
+            type: typeof n
+          });
+        }
+        return new _QvdDataFrame(n === 0 ? [] : this._data.slice(-n), this._columns, this._metadata);
+      }
+      /**
+       * Returns the selected rows of the data frame.
+       *
+       * @param  {...number} args The indices of the rows to return.
+       * @return {QvdDataFrame} The selected rows of the data frame.
+       * @throws {QvdValidationError} If any index is not an integer or is out of bounds.
+       */
+      rows(...args) {
+        for (const index of args) {
+          if (typeof index !== "number" || !Number.isInteger(index)) {
+            throw new exports.QvdValidationError("rows() requires integer indices", {
+              provided: index,
+              type: typeof index
+            });
+          }
+          if (index < 0 || index >= this._data.length) {
+            throw new exports.QvdValidationError(`Row index ${index} out of bounds`, {
+              index,
+              validRange: [0, this._data.length - 1],
+              dataLength: this._data.length
+            });
+          }
+        }
+        return new _QvdDataFrame(
+          args.map((index) => this._data[index]),
+          this._columns,
+          this._metadata
+        );
+      }
+      /**
+       * Returns the value at the specified row and column.
+       *
+       * @param {number} row The index of the row.
+       * @param {string} column The name of the column.
+       * @return {any} The value at the specified row and column.
+       * @throws {QvdValidationError} If row is not an integer, out of bounds, or column does not exist.
+       */
+      at(row, column) {
+        if (typeof row !== "number" || !Number.isInteger(row)) {
+          throw new exports.QvdValidationError("Row index must be an integer", {
+            provided: row,
+            type: typeof row
+          });
+        }
+        if (row < 0 || row >= this._data.length) {
+          throw new exports.QvdValidationError(`Row index ${row} out of bounds`, {
+            index: row,
+            validRange: [0, this._data.length - 1],
+            dataLength: this._data.length
+          });
+        }
+        if (!this._columns.includes(column)) {
+          throw new exports.QvdValidationError(`Column '${column}' does not exist`, {
+            column,
+            availableColumns: this._columns
+          });
+        }
+        return this._data[row][this._columns.indexOf(column)];
+      }
+      /**
+       * Selects the specified columns from the data frame.
+       *
+       * @param  {...string} args The names of the columns to select.
+       * @return {QvdDataFrame} The selected columns of the data frame.
+       * @throws {QvdValidationError} If any column name does not exist.
+       */
+      select(...args) {
+        for (const column of args) {
+          if (!this._columns.includes(column)) {
+            throw new exports.QvdValidationError(`Column '${column}' does not exist`, {
+              column,
+              availableColumns: this._columns
+            });
+          }
+        }
+        const indices = args.map((arg) => this._columns.indexOf(arg));
+        const data = this._data.map((row) => indices.map((index) => row[index]));
+        const columns = indices.map((index) => this._columns[index]);
+        return new _QvdDataFrame(data, columns, this._metadata);
+      }
+      /**
+       * Returns the data frame as a dictionary.
+       *
+       * @return {Promise<{columns: Array<string>, data: Array<Array<any>>}>} The data frame as a dictionary.
+       */
+      async toDict() {
+        return { columns: this._columns, data: this._data };
+      }
+      /**
+       * Persists the data frame to a QVD file.
+       *
+       * @param {string} path The path to the QVD file.
+       * @param {Object} [options] Optional writing options.
+       * @param {string} [options.allowedDir] Optional allowed directory path. If provided, the file path must be within this directory.
+       * @param {Function} [options.onProgress] Optional progress callback function that receives progress updates during write operations.
+       */
+      async toQvd(path3, options = {}) {
+        const { QvdFileWriter: QvdFileWriter2 } = await Promise.resolve().then(() => (init_QvdFileWriter(), QvdFileWriter_exports));
+        const writerOptions = {
+          allowedDir: options.allowedDir,
+          onProgress: options.onProgress
+        };
+        await new QvdFileWriter2(path3, this, writerOptions).save();
+      }
+      /**
+       * Loads a QVD file and returns its data frame.
+       *
+       * @param {string} path The path to the QVD file.
+       * @param {Object} [options] Optional loading options.
+       * @param {number|null} [options.maxRows] The maximum number of rows to load. If not specified, all rows are loaded.
+       * @param {string} [options.allowedDir] Optional allowed directory path. If provided, the file path must be within this directory.
+       * @return {Promise<QvdDataFrame>} The data frame of the QVD file.
+       */
+      static async fromQvd(path3, options = {}) {
+        const { QvdFileReader: QvdFileReader2 } = await Promise.resolve().then(() => (init_QvdFileReader(), QvdFileReader_exports));
+        const readerOptions = { allowedDir: options.allowedDir };
+        return await new QvdFileReader2(path3, readerOptions).load(options.maxRows !== void 0 ? options.maxRows : null);
+      }
+      /**
+       * Constructs a data frame from a dictionary.
+       *
+       * @param {{columns: Array<string>, data: Array<Array<any>>}} data The dictionary to construct the data frame from.
+       * @return {Promise<QvdDataFrame>} The constructed data frame.
+       */
+      static async fromDict(data) {
+        if (!data.columns) {
+          throw new exports.QvdValidationError("The dictionary to construct the data frame from does not contain any columns.", {
+            data
+          });
+        }
+        if (!data.data) {
+          throw new exports.QvdValidationError("The dictionary to construct the data frame from does not contain any data.", {
+            data
+          });
+        }
+        return new _QvdDataFrame(data.data, data.columns);
+      }
+    };
+  }
+});
+
+// src/index.js
+init_QvdSymbol();
+init_QvdDataFrame();
+init_QvdFileReader();
+init_QvdFileWriter();
+init_QvdErrors();
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map