@nmakarov/cli-toolkit 0.1.4 → 0.3.0

package/dist/index.js

@@ -390,7 +390,7 @@ var Args = class {
       command: this.commands[0] || "",
       flags: { ...this.flags },
       options: { ...this.options },
-      usedKeys: new Set(this.usedKeys)
+      usedKeys: Array.from(this.usedKeys)
     };
   }
   /**
@@ -606,8 +606,6 @@ var Params = class {
     } else if (str.match(/^boolean|^bool/i)) {
       type = Joi.boolean();
     } else if (str.match(/^date/i)) {
-      type = Joi.date();
-    } else if (str.match(/^edate/i)) {
       type = Joi.custom(joiEdateType);
     } else if (str.match(/^duration/i)) {
       type = Joi.string().isoDuration();
@@ -1603,11 +1601,11 @@ function buildBreadcrumb(parts) {
   if (parts.length === 1) return parts[0];
   return parts.slice(1).map((part) => `\u2190  ${part}`).join("  ");
 }
-function buildDetailBreadcrumb(path, suffix = "") {
-  if (path.length <= 1) {
-    return suffix ? `\u2190  ${suffix}` : path[0] || "";
+function buildDetailBreadcrumb(path4, suffix = "") {
+  if (path4.length <= 1) {
+    return suffix ? `\u2190  ${suffix}` : path4[0] || "";
   }
-  const breadcrumb = buildBreadcrumb(path);
+  const breadcrumb = buildBreadcrumb(path4);
   return suffix ? `${breadcrumb} ${suffix}` : breadcrumb;
 }
 
@@ -1715,9 +1713,899 @@ function organizeFooterMessages(messages) {
   lines.push(...others);
   return lines;
 }
+
+// src/filedatabase/index.ts
+import fs3 from "fs";
+import path3 from "path";
+
+// src/utils/os-utils.ts
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+function getFreeDiskSpace(targetPath) {
+  try {
+    let pathToCheck = targetPath;
+    if (!fs.existsSync(targetPath)) {
+      const parentDir = path.dirname(targetPath);
+      if (fs.existsSync(parentDir)) {
+        pathToCheck = parentDir;
+      } else {
+        pathToCheck = process.platform === "win32" ? "C:\\" : "/";
+      }
+    }
+    if (process.platform === "win32") {
+      return null;
+    } else {
+      const stdout = execSync(`df -k "${pathToCheck}"`, { encoding: "utf8" });
+      const lines = stdout.trim().split("\n");
+      const parts = lines[1].split(/\s+/);
+      const freeKb = parseInt(parts[3], 10);
+      return freeKb * 1024;
+    }
+  } catch (error) {
+    return null;
+  }
+}
+
+// src/utils/fs-utils.ts
+import fs2 from "fs";
+import path2 from "path";
+async function ensurePath(...pathParts) {
+  const fullPath = path2.resolve(...pathParts);
+  if (!fs2.existsSync(fullPath)) {
+    await fs2.promises.mkdir(fullPath, { recursive: true });
+  }
+  return fullPath;
+}
+function getFileExtension(dataType) {
+  switch (dataType) {
+    case "json-array":
+    case "json-object":
+      return "json";
+    case "text":
+      return "txt";
+    case "xml":
+      return "xml";
+    default:
+      return "json";
+  }
+}
+
+// src/utils/format-utils.ts
+function bytesToHumanReadable(bytes) {
+  if (bytes === 0) return "0 B";
+  const k = 1024;
+  const sizes = ["B", "KB", "MB", "GB", "TB", "PB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i];
+}
+
+// src/utils/date-utils.ts
+function isTimestampFolder(folderName) {
+  const isoRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|\.\d{3}Z)$/;
+  if (!isoRegex.test(folderName)) {
+    return false;
+  }
+  const date = new Date(folderName);
+  return !isNaN(date.getTime()) && date.getTime() > 0;
+}
+
+// src/filedatabase/serializers.ts
+function detectDataType(data) {
+  if (Array.isArray(data)) {
+    return "json-array";
+  } else if (typeof data === "object" && data !== null) {
+    return "json-object";
+  } else if (typeof data === "string") {
+    const trimmed = data.trim();
+    if (trimmed.startsWith("<?xml") || trimmed.startsWith("<")) {
+      return "xml";
+    }
+    return "text";
+  } else {
+    return "text";
+  }
+}
+function serializeData(data) {
+  const dataType = detectDataType(data);
+  if (dataType === "json-array" || dataType === "json-object") {
+    return JSON.stringify(data, null, 4);
+  } else {
+    return String(data);
+  }
+}
+function deserializeData(rawData, dataType) {
+  if (dataType === "json-array" || dataType === "json-object") {
+    return JSON.parse(rawData);
+  } else {
+    return rawData;
+  }
+}
+
+// src/filedatabase/synopsis-functions.ts
+function defaultFileSynopsisFunction(fileEntry, data) {
+  if (!Array.isArray(data) || data.length === 0) {
+    return { ...fileEntry };
+  }
+  const timestamps = [];
+  const statusCounts = {};
+  for (const item of data) {
+    let ts = null;
+    let status = null;
+    for (const [key, value] of Object.entries(item)) {
+      const k = key.toLowerCase();
+      if (k === "modificationtimestamp") {
+        ts = new Date(value).getTime();
+      }
+      if (k === "standardstatus") {
+        status = value;
+      }
+    }
+    if (ts && !isNaN(ts)) {
+      timestamps.push(ts);
+    }
+    if (status !== null && status !== void 0) {
+      statusCounts[status] = (statusCounts[status] || 0) + 1;
+    }
+  }
+  const result = { ...fileEntry };
+  if (timestamps.length) {
+    result.minModificationTimestamp = new Date(Math.min(...timestamps)).toISOString();
+    result.maxModificationTimestamp = new Date(Math.max(...timestamps)).toISOString();
+  }
+  if (Object.keys(statusCounts).length) {
+    result.StandardStatuses = statusCounts;
+  }
+  return result;
+}
+function defaultVersionSynopsisFunction(metadata) {
+  if (!metadata?.files || !Array.isArray(metadata.files)) {
+    return metadata;
+  }
+  const timestamps = [];
+  const statusCounts = {};
+  for (const file of metadata.files) {
+    if (file.minModificationTimestamp) {
+      const minTs = new Date(file.minModificationTimestamp).getTime();
+      if (!isNaN(minTs)) timestamps.push(minTs);
+    }
+    if (file.maxModificationTimestamp) {
+      const maxTs = new Date(file.maxModificationTimestamp).getTime();
+      if (!isNaN(maxTs)) timestamps.push(maxTs);
+    }
+    if (file.StandardStatuses && typeof file.StandardStatuses === "object") {
+      for (const [status, count] of Object.entries(file.StandardStatuses)) {
+        statusCounts[status] = (statusCounts[status] || 0) + count;
+      }
+    }
+  }
+  const result = { ...metadata };
+  if (timestamps.length) {
+    result.minModificationTimestamp = new Date(Math.min(...timestamps)).toISOString();
+    result.maxModificationTimestamp = new Date(Math.max(...timestamps)).toISOString();
+  }
+  if (Object.keys(statusCounts).length > 0) {
+    result.StandardStatuses = statusCounts;
+  }
+  return result;
+}
+
+// src/filedatabase/index.ts
+var FileDatabaseError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FileDatabaseError";
+  }
+};
+var FileDatabase = class {
+  basePath;
+  namespace;
+  tableName = null;
+  versioned;
+  maxVersions;
+  pageSize;
+  useMetadata;
+  freeSpaceThreshold;
+  logger;
+  // Current operation state
+  currentVersion = null;
+  currentVersionFolder = null;
+  currentFileNumber = 0;
+  currentRecord = 0;
+  hasReadFirstPage = false;
+  lastFileData = null;
+  metadata;
+  // Synopsis calculation functions
+  fileSynopsisFunction = null;
+  versionSynopsisFunction = null;
+  constructor(config2) {
+    if (!config2.basePath) {
+      throw new ParamError("[FileDatabase] basePath is required");
+    }
+    this.basePath = config2.basePath;
+    this.namespace = config2.namespace || "default";
+    this.tableName = config2.tableName || null;
+    this.versioned = config2.versioned ?? true;
+    this.maxVersions = config2.maxVersions || 5;
+    this.pageSize = config2.pageSize || 5e3;
+    this.useMetadata = config2.useMetadata !== false;
+    this.freeSpaceThreshold = config2.freeSpaceThreshold || 100 * 1024 * 1024;
+    this.logger = config2.logger || console;
+    this.metadata = this.getDefaultMetadata();
+  }
+  /**
+   * Get default metadata structure
+   */
+  getDefaultMetadata() {
+    return {
+      version: this.currentVersion || null,
+      files: [],
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      modifiedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      totalRecords: 0,
+      synopsis: null,
+      dataType: null
+    };
+  }
+  /**
+   * Get the destination path (basePath/namespace/tableName[/version])
+   */
+  getDestinationPath(version) {
+    const errors = ["basePath", "namespace", "tableName"].filter((prop) => !this[prop]).map((prop) => `${prop} is not set`);
+    if (errors.length) {
+      throw new FileDatabaseError(`[FileDatabase] ${errors.join("; ")}`);
+    }
+    let parts = [this.basePath, this.namespace];
+    if (this.tableName) {
+      parts.push(...this.tableName.split("/"));
+    }
+    if (this.versioned && version) {
+      parts.push(version);
+    }
+    return path3.resolve(...parts);
+  }
+  /**
+   * Set current version and version folder
+   */
+  async setCurrentVersion(version) {
+    this.currentVersion = version;
+    this.currentVersionFolder = await ensurePath(this.getDestinationPath(), version);
+  }
+  /**
+   * Create a new version folder with comprehensive timestamp logic
+   * Only works in versioned mode
+   */
+  async makeNewVersion() {
+    if (!this.versioned) {
+      throw new FileDatabaseError("makeNewVersion() only works in versioned mode");
+    }
+    this.metadata = this.getDefaultMetadata();
+    const existingVersions = await this.getVersions();
+    let versionName;
+    if (existingVersions.length > 0) {
+      const maxTimestamp = existingVersions.reduce((max, version) => {
+        const versionDate = new Date(version.replace("Z", ""));
+        const maxDate2 = new Date(max.replace("Z", ""));
+        return versionDate > maxDate2 ? version : max;
+      });
+      const maxDate = new Date(maxTimestamp.replace("Z", ""));
+      const nextDate = new Date(maxDate.getTime() + 1e3);
+      versionName = nextDate.toISOString().split(".")[0] + "Z";
+    } else {
+      const now = /* @__PURE__ */ new Date();
+      versionName = now.toISOString().split(".")[0] + "Z";
+    }
+    await this.setCurrentVersion(versionName);
+    this.currentFileNumber = 0;
+    const versions = await this.getVersions();
+    while (versions.length > this.maxVersions) {
+      const versionToDelete = path3.resolve(this.getDestinationPath(), versions.shift());
+      this.logger.debug?.(`[FileDatabase] Deleting old version: ${versionToDelete}`);
+      await fs3.promises.rm(versionToDelete, { recursive: true, force: true });
+    }
+    return versionName;
+  }
+  /**
+   * Get list of all versions (sorted chronologically)
+   * Only works in versioned mode
+   */
+  async getVersions() {
+    if (!this.versioned) {
+      return [];
+    }
+    const destPath = this.getDestinationPath();
+    try {
+      await ensurePath(destPath);
+      const items = await fs3.promises.readdir(destPath);
+      const versions = items.filter((item) => {
+        const itemPath = path3.join(destPath, item);
+        const stat = fs3.statSync(itemPath);
+        return stat.isDirectory() && isTimestampFolder(item);
+      });
+      return versions.sort();
+    } catch (error) {
+      return [];
+    }
+  }
+  /**
+   * Get the latest version (most recent timestamp)
+   * Only works in versioned mode
+   * @returns Latest version string or null if no versions
+   */
+  async getLatestVersion() {
+    if (!this.versioned) {
+      throw new FileDatabaseError("getLatestVersion() only works in versioned mode");
+    }
+    const versions = await this.getVersions();
+    if (versions.length === 0) {
+      return null;
+    }
+    return versions[versions.length - 1];
+  }
+  /**
+   * Check if any data exists in this table
+   * Works for both versioned and non-versioned modes
+   * @returns true if data exists
+   */
+  async hasData() {
+    const tablePath = this.getDestinationPath();
+    if (!fs3.existsSync(tablePath)) {
+      return false;
+    }
+    if (this.versioned) {
+      const versions = await this.getVersions();
+      return versions.length > 0;
+    } else {
+      const items = await fs3.promises.readdir(tablePath);
+      return items.some(
+        (item) => item === "metadata.json" || item.match(/^\d{6}\.(json|txt|xml)$/) || item.endsWith(".json")
+      );
+    }
+  }
+  /**
+   * Auto-detect the data format in this table
+   * Used when reading existing data
+   * @returns Format detection result
+   */
+  async detectDataFormat() {
+    const tablePath = this.getDestinationPath();
+    if (!fs3.existsSync(tablePath)) {
+      return { versioned: false, hasMetadata: false, dataType: null };
+    }
+    const items = await fs3.promises.readdir(tablePath);
+    if (items.includes("metadata.json")) {
+      const metadata = JSON.parse(
+        await fs3.promises.readFile(path3.join(tablePath, "metadata.json"), "utf8")
+      );
+      return {
+        versioned: false,
+        hasMetadata: true,
+        dataType: metadata.dataType || null
+      };
+    }
+    const versionFolders = items.filter((item) => {
+      const itemPath = path3.join(tablePath, item);
+      const stat = fs3.statSync(itemPath);
+      return stat.isDirectory() && isTimestampFolder(item);
+    });
+    if (versionFolders.length > 0) {
+      const latestVersion = versionFolders.sort().pop();
+      const versionMetadataPath = path3.join(tablePath, latestVersion, "metadata.json");
+      return {
+        versioned: true,
+        hasMetadata: fs3.existsSync(versionMetadataPath),
+        dataType: null
+      };
+    }
+    const dataFiles = items.filter((f) => f.match(/^\d{6}\.(json|txt|xml)$/));
+    if (dataFiles.length > 0) {
+      return {
+        versioned: false,
+        hasMetadata: false,
+        dataType: null
+      };
+    }
+    return { versioned: false, hasMetadata: false, dataType: null };
+  }
+  /**
+   * Load metadata from JSON file
+   */
+  async loadMetadataJson(version) {
+    const metadataFile = path3.join(this.getDestinationPath(), version, "metadata.json");
+    if (fs3.existsSync(metadataFile)) {
+      try {
+        const rawData = await fs3.promises.readFile(metadataFile, "utf8");
+        return JSON.parse(rawData);
+      } catch (e) {
+        throw new FileDatabaseError(`Failed to read metadata for version "${version}": ${e.message}`);
+      }
+    }
+    return null;
+  }
+  /**
+   * Build metadata by scanning files in a version folder (backward compatibility)
+   * Reads all files to get accurate counts - used when synopsis calculation is needed
+   */
+  async figureMetadataFromVersionFiles(version) {
+    const versionPath = path3.join(this.getDestinationPath(), version);
+    if (!fs3.existsSync(versionPath)) {
+      return this.getDefaultMetadata();
+    }
+    const files = (await fs3.promises.readdir(versionPath)).filter((file) => file !== "metadata.json" && !file.startsWith(".")).sort();
+    const metadata = this.getDefaultMetadata();
+    metadata.version = version;
+    metadata.files = [];
+    let totalRecords = 0;
+    let detectedDataType = null;
+    for (let i = 0; i < files.length; i++) {
+      const fileName = files[i];
+      const filePath = path3.join(versionPath, fileName);
+      try {
+        const rawData = await fs3.promises.readFile(filePath, "utf8");
+        const extension = path3.extname(fileName).toLowerCase();
+        let dataType = "text";
+        if (extension === ".json") {
+          dataType = "json-array";
+        } else if (extension === ".xml") {
+          dataType = "xml";
+        }
+        const fileData = deserializeData(rawData, dataType);
+        const recordsCount = Array.isArray(fileData) ? fileData.length : 1;
+        if (detectedDataType === null) {
+          detectedDataType = detectDataType(fileData);
+        }
+        const fileInfo = {
+          number: i + 1,
+          recordsCount,
+          fileName
+        };
+        metadata.files.push(fileInfo);
+        totalRecords += recordsCount;
+      } catch (error) {
+        this.logger.error?.(`[FileDatabase] Failed to read file ${fileName}: ${error.message}`);
+      }
+    }
+    metadata.totalRecords = totalRecords;
+    metadata.dataType = detectedDataType;
+    return metadata;
+  }
+  /**
+   * Build metadata optimized - only reads first and last files
+   * Assumes all middle files have the same record count as the first file
+   * Much faster for large datasets with many files
+   */
+  async buildMetadataOptimized(version) {
+    const versionPath = path3.join(this.getDestinationPath(), version);
+    if (!fs3.existsSync(versionPath)) {
+      return this.getDefaultMetadata();
+    }
+    const files = (await fs3.promises.readdir(versionPath)).filter((file) => file !== "metadata.json" && !file.startsWith(".")).sort();
+    if (files.length === 0) {
+      return this.getDefaultMetadata();
+    }
+    const metadata = this.getDefaultMetadata();
+    metadata.version = version;
+    metadata.files = files.map((fileName, index) => ({
+      number: index + 1,
+      recordsCount: 0,
+      fileName
+    }));
+    const firstFile = metadata.files[0];
+    const firstFilePath = path3.join(versionPath, firstFile.fileName);
+    const firstFileRaw = await fs3.promises.readFile(firstFilePath, "utf8");
+    let firstFileData;
+    try {
+      firstFileData = JSON.parse(firstFileRaw);
+    } catch (e) {
+      firstFileData = firstFileRaw;
+    }
+    metadata.dataType = detectDataType(firstFileData);
+    if (metadata.dataType === "json-array") {
+      const firstFileCount = Array.isArray(firstFileData) ? firstFileData.length : 1;
+      firstFile.recordsCount = firstFileCount;
+      for (let i = 1; i < metadata.files.length - 1; i++) {
+        metadata.files[i].recordsCount = firstFileCount;
+      }
+      if (files.length > 1) {
+        const lastFile = metadata.files[metadata.files.length - 1];
+        const lastFilePath = path3.join(versionPath, lastFile.fileName);
+        const lastFileRaw = await fs3.promises.readFile(lastFilePath, "utf8");
+        const lastFileData = deserializeData(lastFileRaw, metadata.dataType);
+        lastFile.recordsCount = Array.isArray(lastFileData) ? lastFileData.length : 1;
+      }
+      metadata.totalRecords = metadata.files.reduce((sum, file) => sum + file.recordsCount, 0);
+    } else {
+      metadata.files.forEach((file) => {
+        file.recordsCount = 1;
+      });
+      metadata.totalRecords = files.length;
+    }
+    return metadata;
+  }
+  /**
+   * Figure out metadata - tries JSON first, then builds from files
+   * Uses optimized building when no synopsis calculation is needed
+   */
+  async figureMetadata(version, useOptimized = true) {
+    if (this.useMetadata) {
+      const metadata = await this.loadMetadataJson(version);
+      if (metadata) {
+        return metadata;
+      }
+    }
+    if (useOptimized && !this.fileSynopsisFunction && !this.versionSynopsisFunction) {
+      return await this.buildMetadataOptimized(version);
+    }
+    return await this.figureMetadataFromVersionFiles(version);
+  }
+  /**
+   * Load version metadata (main entry point for loading)
+   */
+  async loadVersionMetadata(version) {
+    const metadata = await this.figureMetadata(version);
+    this.metadata = metadata;
+    return metadata;
+  }
+  /**
+   * Save version metadata to file
+   */
+  async saveVersionMetadata(metadata) {
+    if (!this.useMetadata) {
+      return;
+    }
+    const metadataToSave = metadata || this.metadata;
+    let metadataFile;
+    if (this.versioned) {
+      if (!this.currentVersion) {
+        return;
+      }
+      metadataFile = path3.join(this.getDestinationPath(), this.currentVersion, "metadata.json");
+    } else {
+      metadataFile = path3.join(this.getDestinationPath(), "metadata.json");
+    }
+    await fs3.promises.writeFile(metadataFile, JSON.stringify(metadataToSave, null, 4), "utf8");
+  }
+  /**
+   * Create a new file entry in metadata
+   */
+  makeNewFile() {
+    this.currentFileNumber = (this.currentFileNumber || 0) + 1;
+    const dataType = this.metadata.dataType || "json-array";
+    const fileEntry = {
+      number: this.currentFileNumber,
+      recordsCount: 0,
+      fileName: `${this.currentFileNumber.toString().padStart(6, "0")}.${getFileExtension(dataType)}`
+    };
+    this.metadata.files.push(fileEntry);
+    this.lastFileData = null;
+    this.logger.debug?.(`[FileDatabase] Created new file: ${fileEntry.fileName}, fileNumber: ${this.currentFileNumber}`);
+  }
+  /**
+   * Figure out what data to write and which file to use (for pagination)
+   */
+  figureOutDataAndFileToWrite(data) {
+    let dataToWrite;
+    let dataLeftOver;
+    const lastFile = this.metadata.files[this.metadata.files.length - 1];
+    const lastFileRecordsCount = lastFile.recordsCount;
+    if (Array.isArray(data)) {
+      if (lastFileRecordsCount < this.pageSize) {
+        dataToWrite = [...this.lastFileData || [], ...data.slice(0, this.pageSize - lastFileRecordsCount)];
+        dataLeftOver = data.slice(this.pageSize - lastFileRecordsCount);
+      } else {
+        this.makeNewFile();
+        dataToWrite = data.slice(0, this.pageSize);
+        dataLeftOver = data.slice(this.pageSize);
+      }
+      this.lastFileData = dataToWrite;
+    } else {
+      dataToWrite = data;
+      dataLeftOver = null;
+    }
+    const fileName = this.metadata.files[this.metadata.files.length - 1].fileName;
+    this.logger.debug?.(
+      `[FileDatabase] figureOutDataAndFileToWrite: filename=${fileName}, dataToWrite.length=${Array.isArray(dataToWrite) ? dataToWrite.length : "N/A"}, lastFileRecordsCount=${lastFileRecordsCount}`
+    );
+    return { dataToWrite, dataLeftOver, fileName };
+  }
+  /**
+   * Calculate file-level synopsis if function is set
+   */
+  calculateFileSynopsis(data, fileIndex = this.metadata.files.length - 1) {
+    if (!this.fileSynopsisFunction) {
+      return;
+    }
+    const fileInfo = this.metadata.files[fileIndex];
+    const enhancedFileInfo = this.fileSynopsisFunction(fileInfo, data);
+    this.metadata.files[fileIndex] = enhancedFileInfo;
+  }
+  /**
+   * Calculate version-level synopsis if function is set
+   */
+  calculateVersionSynopsis() {
+    if (!this.versionSynopsisFunction) {
+      return;
+    }
+    const enhancedMetadata = this.versionSynopsisFunction(this.metadata);
+    this.metadata = enhancedMetadata;
+  }
+  /**
+   * Update metadata after writing data
+   */
+  updateMetadata(dataToWrite, fileName) {
+    let currentFile;
+    if (fileName) {
+      const foundFile = this.metadata.files.find((file) => file.fileName === fileName);
+      if (!foundFile) {
+        this.logger.warn?.(`[FileDatabase] File ${fileName} not found in metadata, using last file`);
+        currentFile = this.metadata.files[this.metadata.files.length - 1];
+      } else {
+        currentFile = foundFile;
+      }
+    } else {
+      currentFile = this.metadata.files[this.metadata.files.length - 1];
+    }
+    const recordsCount = Array.isArray(dataToWrite) ? dataToWrite.length : 1;
+    currentFile.recordsCount = recordsCount;
+    const fileIndex = this.metadata.files.indexOf(currentFile);
+    if (fileIndex !== -1) {
+      this.calculateFileSynopsis(dataToWrite, fileIndex);
+    }
+    this.metadata.version = this.currentVersion;
+    this.metadata.modifiedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.metadata.dataType = detectDataType(dataToWrite);
+    this.metadata.totalRecords = this.metadata.files.reduce((sum, file) => sum + (file.recordsCount || 0), 0);
+    this.logger.debug?.(
+      `[FileDatabase] Updated metadata for file ${currentFile.fileName}: recordsCount=${recordsCount}, totalRecords=${this.metadata.totalRecords}`
+    );
+  }
+  /**
+   * Safe write with disk space check
+   */
+  async safeWrite(filePath, data) {
+    const serializedData = serializeData(data);
+    const dir = path3.dirname(filePath);
+    const requiredBytes = Buffer.byteLength(serializedData, "utf8");
+    const freeBytes = getFreeDiskSpace(dir);
+    if (freeBytes !== null) {
+      if (freeBytes < requiredBytes) {
+        throw new FileDatabaseError(
+          `Not enough disk space. Required: ${bytesToHumanReadable(requiredBytes)}, Free: ${bytesToHumanReadable(freeBytes)}`
+        );
+      }
+      if (freeBytes < this.freeSpaceThreshold) {
+        this.logger.warn?.(`Low disk space warning: only ${bytesToHumanReadable(freeBytes)} left`);
+      }
+    }
+    try {
+      await fs3.promises.writeFile(filePath, serializedData, "utf8");
+      this.logger.debug?.(`[FileDatabase] Wrote ${bytesToHumanReadable(requiredBytes)} to ${filePath}`);
+    } catch (error) {
+      throw new FileDatabaseError(`Failed to write file ${filePath}: ${error.message}`);
+    }
+  }
+  /**
+   * Prepare the instance for read or write operations
+   * This discovers state and sets up internal members based on mode and current data
+   */
+  async prepare({ write, read, version }) {
+    if (write) {
+      if (this.versioned) {
+        if (this.currentVersion === null) {
+          await this.makeNewVersion();
+          this.metadata = this.getDefaultMetadata();
+          this.metadata.version = this.currentVersion;
+          this.makeNewFile();
+        } else {
+          if (!this.metadata.files.length) {
+            this.metadata = await this.figureMetadata(this.currentVersion);
+          }
+        }
+      } else {
+        await ensurePath(this.getDestinationPath());
+        if (this.useMetadata === true) {
+          const metadataPath = path3.join(this.getDestinationPath(), "metadata.json");
+          if (fs3.existsSync(metadataPath)) {
+            try {
+              const rawData = await fs3.promises.readFile(metadataPath, "utf8");
+              this.metadata = JSON.parse(rawData);
+            } catch (e) {
+              this.metadata = this.getDefaultMetadata();
+            }
+          } else {
+            this.metadata = this.getDefaultMetadata();
+            this.makeNewFile();
+          }
+        } else {
+          this.metadata = this.getDefaultMetadata();
+          this.makeNewFile();
+        }
+      }
+    } else if (read) {
+      if (this.versioned) {
+        const versions = await this.getVersions();
+        if (versions.length === 0) {
+          throw new FileDatabaseError("[FileDatabase] No versions found, cannot read");
+        }
+        if (version) {
+          if (!versions.includes(version)) {
+            throw new FileDatabaseError(`[FileDatabase] Version "${version}" not found`);
+          }
+          await this.setCurrentVersion(version);
+        } else {
+          await this.setCurrentVersion(versions[versions.length - 1]);
+        }
+        if (!this.metadata.files.length) {
+          this.metadata = await this.figureMetadata(this.currentVersion);
+        }
+      } else {
+        this.currentVersion = null;
+        if (this.useMetadata === void 0) {
+          const format = await this.detectDataFormat();
+          this.useMetadata = format.hasMetadata;
+        }
+        if (this.useMetadata) {
+          const metadataPath = path3.join(this.getDestinationPath(), "metadata.json");
+          if (fs3.existsSync(metadataPath)) {
+            try {
+              const rawData = await fs3.promises.readFile(metadataPath, "utf8");
+              this.metadata = JSON.parse(rawData);
+            } catch (e) {
+              throw new FileDatabaseError(`Failed to read metadata: ${e.message}`);
+            }
+          } else {
+            throw new FileDatabaseError("[FileDatabase] No metadata found in non-versioned mode");
+          }
+        } else {
+          this.metadata = await this.figureMetadataFromVersionFiles("");
+        }
+      }
+    }
+  }
+  /**
+   * Write data to the file database
+   */
+  async write(data, options = {}) {
+    if (options.forceNewVersion && !this.versioned) {
+      throw new FileDatabaseError("Cannot use forceNewVersion in non-versioned mode");
+    }
+    await this.prepare({ write: true });
+    if (options.forceNewVersion) {
+      await this.makeNewVersion();
+      this.metadata = this.getDefaultMetadata();
+      this.metadata.version = this.currentVersion;
+      this.makeNewFile();
+    }
+    let { dataToWrite, dataLeftOver, fileName } = this.figureOutDataAndFileToWrite(data);
+    const destPath = this.getDestinationPath(this.currentVersion || void 0);
+    await this.safeWrite(path3.join(destPath, fileName), dataToWrite);
+    this.updateMetadata(dataToWrite, fileName);
+    while (dataLeftOver && dataLeftOver.length > 0) {
+      const writeContext = this.figureOutDataAndFileToWrite(dataLeftOver);
+      await this.safeWrite(path3.join(destPath, writeContext.fileName), writeContext.dataToWrite);
+      this.updateMetadata(writeContext.dataToWrite, writeContext.fileName);
+      dataLeftOver = writeContext.dataLeftOver;
+    }
+    this.calculateVersionSynopsis();
+    if (this.useMetadata) {
+      await this.saveVersionMetadata(this.metadata);
+    }
+  }
+  /**
+   * Read data from the file database
+   */
+  async read(options = {}) {
+    const { version, nextPage = false, pageSize } = options;
+    await this.prepare({ read: true, version });
+    const isNonPaginatedData = this.metadata.dataType === "text" || this.metadata.dataType === "xml" || this.metadata.dataType === "json-object";
+    if (isNonPaginatedData) {
+      const file = this.metadata.files[0];
+      const filePath = path3.join(this.getDestinationPath(this.currentVersion || void 0), file.fileName);
+      try {
+        const rawData = await fs3.promises.readFile(filePath, "utf8");
+        return deserializeData(rawData, this.metadata.dataType);
+      } catch (error) {
+        throw new FileDatabaseError(`Failed to read file ${file.fileName}: ${error.message}`);
+      }
+    }
+    let effectivePageSize;
+    if (nextPage && this.hasReadFirstPage) {
+      effectivePageSize = pageSize || this.pageSize;
+      this.currentRecord += effectivePageSize;
+    } else if (!nextPage) {
+      effectivePageSize = pageSize !== void 0 ? pageSize : this.metadata.totalRecords;
+      this.currentRecord = 0;
+    } else {
+      effectivePageSize = pageSize || this.pageSize;
+    }
+    if (this.currentRecord >= this.metadata.totalRecords) {
+      return [];
+    }
+    const result = [];
+    let recordsRead = 0;
+    let currentFileIndex = 0;
+    let currentFileOffset = 0;
+    let totalRecords = 0;
+    for (let i = 0; i < this.metadata.files.length; i++) {
+      const file = this.metadata.files[i];
+      if (this.currentRecord < totalRecords + file.recordsCount) {
+        currentFileIndex = i;
+        currentFileOffset = totalRecords;
+        break;
+      }
+      totalRecords += file.recordsCount;
+    }
+    let cumulativeRecords = currentFileOffset;
+    for (let i = currentFileIndex; i < this.metadata.files.length && recordsRead < effectivePageSize; i++) {
+      const file = this.metadata.files[i];
+      const filePath = path3.join(this.getDestinationPath(this.currentVersion || void 0), file.fileName);
+      try {
+        const rawData = await fs3.promises.readFile(filePath, "utf8");
+        const fileData = deserializeData(rawData, this.metadata.dataType);
+        let startIndex = 0;
+        if (i === currentFileIndex) {
+          startIndex = this.currentRecord - cumulativeRecords;
+        }
+        const endIndex = Math.min(startIndex + (effectivePageSize - recordsRead), fileData.length);
+        const recordsFromThisFile = fileData.slice(startIndex, endIndex);
+        result.push(...recordsFromThisFile);
+        recordsRead += recordsFromThisFile.length;
+        cumulativeRecords += file.recordsCount;
+      } catch (error) {
+        throw new FileDatabaseError(`Failed to read file ${file.fileName}: ${error.message}`);
+      }
+    }
+    if (result.length > 0) {
+      if (nextPage || pageSize !== void 0 && pageSize < this.metadata.totalRecords) {
+        this.hasReadFirstPage = true;
+      }
+    }
+    return result;
+  }
+  /**
+   * Set the starting record for pagination (1-based index)
+   */
+  setStartRecord(startRecord) {
+    this.currentRecord = startRecord - 1;
+    this.hasReadFirstPage = false;
+  }
+  /**
+   * Reset read pagination state
+   */
+  resetPagination() {
+    this.currentRecord = 0;
+    this.hasReadFirstPage = false;
+  }
+  /**
+   * Set file-level synopsis calculation function
+   */
+  setFileSynopsisFunction(fn) {
+    this.fileSynopsisFunction = fn;
+  }
+  /**
+   * Set version-level synopsis calculation function
+   */
+  setVersionSynopsisFunction(fn) {
+    this.versionSynopsisFunction = fn;
+  }
+  /**
+   * Get current version name
+   */
+  getCurrentVersion() {
+    return this.currentVersion;
+  }
+  /**
+   * Get current metadata
+   */
+  getMetadata() {
+    return { ...this.metadata };
+  }
+};
 export {
   Args,
   Divider,
+  FileDatabase,
+  FileDatabaseError,
   FooterPresets,
   GridCell,
   InputField,
@@ -1736,6 +2624,8 @@ export {
   buildBreadcrumb,
   buildDetailBreadcrumb,
   buildFooter,
+  defaultFileSynopsisFunction,
+  defaultVersionSynopsisFunction,
   getArgsInstance,
   getParamsInstance,
   joiEdateType,