@nmakarov/cli-toolkit 0.2.0 → 0.4.0

package/dist/index.cjs

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   Args: () => Args,
+  Db: () => Db,
   Divider: () => Divider,
   FileDatabase: () => FileDatabase,
   FileDatabaseError: () => FileDatabaseError,
@@ -1777,7 +1778,7 @@ function organizeFooterMessages(messages) {
   return lines;
 }
 
-// src/filestore/index.ts
+// src/filedatabase/index.ts
 var import_fs4 = __toESM(require("fs"), 1);
 var import_path4 = __toESM(require("path"), 1);
 
@@ -1853,7 +1854,7 @@ function isTimestampFolder(folderName) {
   return !isNaN(date.getTime()) && date.getTime() > 0;
 }
 
-// src/filestore/serializers.ts
+// src/filedatabase/serializers.ts
 function detectDataType(data) {
   if (Array.isArray(data)) {
     return "json-array";
@@ -1885,7 +1886,7 @@ function deserializeData(rawData, dataType) {
   }
 }
 
-// src/filestore/synopsis-functions.ts
+// src/filedatabase/synopsis-functions.ts
 function defaultFileSynopsisFunction(fileEntry, data) {
   if (!Array.isArray(data) || data.length === 0) {
     return { ...fileEntry };
@@ -1953,7 +1954,7 @@ function defaultVersionSynopsisFunction(metadata) {
   return result;
 }
 
-// src/filestore/index.ts
+// src/filedatabase/index.ts
 var FileDatabaseError = class extends Error {
   constructor(message) {
     super(message);
@@ -1964,6 +1965,7 @@ var FileDatabase = class {
   basePath;
   namespace;
   tableName = null;
+  versioned;
   maxVersions;
   pageSize;
   useMetadata;
@@ -1987,6 +1989,7 @@ var FileDatabase = class {
     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;
@@ -2009,14 +2012,21 @@ var FileDatabase = class {
     };
   }
   /**
-   * Get the destination path (basePath/namespace/tableName)
+   * Get the destination path (basePath/namespace/tableName[/version])
    */
-  getDestinationPath() {
+  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("; ")}`);
     }
-    return import_path4.default.resolve(this.basePath, this.namespace, this.tableName);
+    let parts = [this.basePath, this.namespace];
+    if (this.tableName) {
+      parts.push(...this.tableName.split("/"));
+    }
+    if (this.versioned && version) {
+      parts.push(version);
+    }
+    return import_path4.default.resolve(...parts);
   }
   /**
    * Set current version and version folder
@@ -2027,8 +2037,13 @@ var FileDatabase = class {
   }
   /**
    * 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) {
@@ -2056,8 +2071,12 @@ var FileDatabase = class {
   }
   /**
    * 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);
@@ -2072,6 +2091,86 @@ var FileDatabase = class {
       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 (!import_fs4.default.existsSync(tablePath)) {
+      return false;
+    }
+    if (this.versioned) {
+      const versions = await this.getVersions();
+      return versions.length > 0;
+    } else {
+      const items = await import_fs4.default.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 (!import_fs4.default.existsSync(tablePath)) {
+      return { versioned: false, hasMetadata: false, dataType: null };
+    }
+    const items = await import_fs4.default.promises.readdir(tablePath);
+    if (items.includes("metadata.json")) {
+      const metadata = JSON.parse(
+        await import_fs4.default.promises.readFile(import_path4.default.join(tablePath, "metadata.json"), "utf8")
+      );
+      return {
+        versioned: false,
+        hasMetadata: true,
+        dataType: metadata.dataType || null
+      };
+    }
+    const versionFolders = items.filter((item) => {
+      const itemPath = import_path4.default.join(tablePath, item);
+      const stat = import_fs4.default.statSync(itemPath);
+      return stat.isDirectory() && isTimestampFolder(item);
+    });
+    if (versionFolders.length > 0) {
+      const latestVersion = versionFolders.sort().pop();
+      const versionMetadataPath = import_path4.default.join(tablePath, latestVersion, "metadata.json");
+      return {
+        versioned: true,
+        hasMetadata: import_fs4.default.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
    */
@@ -2215,11 +2314,19 @@ var FileDatabase = class {
    * Save version metadata to file
    */
   async saveVersionMetadata(metadata) {
-    if (!this.useMetadata || !this.currentVersion) {
+    if (!this.useMetadata) {
       return;
     }
     const metadataToSave = metadata || this.metadata;
-    const metadataFile = import_path4.default.join(this.getDestinationPath(), this.currentVersion, "metadata.json");
+    let metadataFile;
+    if (this.versioned) {
+      if (!this.currentVersion) {
+        return;
+      }
+      metadataFile = import_path4.default.join(this.getDestinationPath(), this.currentVersion, "metadata.json");
+    } else {
+      metadataFile = import_path4.default.join(this.getDestinationPath(), "metadata.json");
+    }
     await import_fs4.default.promises.writeFile(metadataFile, JSON.stringify(metadataToSave, null, 4), "utf8");
   }
   /**
@@ -2347,31 +2454,75 @@ var FileDatabase = class {
    */
   async prepare({ write, read, version }) {
     if (write) {
-      if (this.currentVersion === null) {
-        await this.makeNewVersion();
-        this.metadata = this.getDefaultMetadata();
-        this.metadata.version = this.currentVersion;
-        this.makeNewFile();
+      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 {
-        if (!this.metadata.files.length) {
-          this.metadata = await this.figureMetadata(this.currentVersion);
+        await ensurePath(this.getDestinationPath());
+        if (this.useMetadata === true) {
+          const metadataPath = import_path4.default.join(this.getDestinationPath(), "metadata.json");
+          if (import_fs4.default.existsSync(metadataPath)) {
+            try {
+              const rawData = await import_fs4.default.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) {
-      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`);
+      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);
         }
-        await this.setCurrentVersion(version);
       } else {
-        await this.setCurrentVersion(versions[versions.length - 1]);
-      }
-      if (!this.metadata.files.length) {
-        this.metadata = await this.figureMetadata(this.currentVersion);
+        this.currentVersion = null;
+        if (this.useMetadata === void 0) {
+          const format = await this.detectDataFormat();
+          this.useMetadata = format.hasMetadata;
+        }
+        if (this.useMetadata) {
+          const metadataPath = import_path4.default.join(this.getDestinationPath(), "metadata.json");
+          if (import_fs4.default.existsSync(metadataPath)) {
+            try {
+              const rawData = await import_fs4.default.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("");
+        }
       }
     }
   }
@@ -2379,6 +2530,9 @@ var FileDatabase = class {
    * 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();
@@ -2387,11 +2541,12 @@ var FileDatabase = class {
       this.makeNewFile();
     }
     let { dataToWrite, dataLeftOver, fileName } = this.figureOutDataAndFileToWrite(data);
-    await this.safeWrite(import_path4.default.join(this.currentVersionFolder, fileName), dataToWrite);
+    const destPath = this.getDestinationPath(this.currentVersion || void 0);
+    await this.safeWrite(import_path4.default.join(destPath, fileName), dataToWrite);
     this.updateMetadata(dataToWrite, fileName);
     while (dataLeftOver && dataLeftOver.length > 0) {
       const writeContext = this.figureOutDataAndFileToWrite(dataLeftOver);
-      await this.safeWrite(import_path4.default.join(this.currentVersionFolder, writeContext.fileName), writeContext.dataToWrite);
+      await this.safeWrite(import_path4.default.join(destPath, writeContext.fileName), writeContext.dataToWrite);
       this.updateMetadata(writeContext.dataToWrite, writeContext.fileName);
       dataLeftOver = writeContext.dataLeftOver;
     }
@@ -2409,7 +2564,7 @@ var FileDatabase = class {
     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 = import_path4.default.join(this.getDestinationPath(), this.currentVersion, file.fileName);
+      const filePath = import_path4.default.join(this.getDestinationPath(this.currentVersion || void 0), file.fileName);
       try {
         const rawData = await import_fs4.default.promises.readFile(filePath, "utf8");
         return deserializeData(rawData, this.metadata.dataType);
@@ -2447,7 +2602,7 @@ var FileDatabase = class {
     let cumulativeRecords = currentFileOffset;
     for (let i = currentFileIndex; i < this.metadata.files.length && recordsRead < effectivePageSize; i++) {
       const file = this.metadata.files[i];
-      const filePath = import_path4.default.join(this.getDestinationPath(), this.currentVersion, file.fileName);
+      const filePath = import_path4.default.join(this.getDestinationPath(this.currentVersion || void 0), file.fileName);
       try {
         const rawData = await import_fs4.default.promises.readFile(filePath, "utf8");
         const fileData = deserializeData(rawData, this.metadata.dataType);
@@ -2510,9 +2665,305 @@ var FileDatabase = class {
     return { ...this.metadata };
   }
 };
+
+// src/db/index.ts
+var import_knex = __toESM(require("knex"), 1);
+var Db = class {
+  knexInstance = null;
+  config;
+  logger;
+  queriesLog = [];
+  isConnected = false;
+  constructor(config2) {
+    if (!config2.connectionString) {
+      throw new ParamError("Db: connectionString is required");
+    }
+    this.config = {
+      testConnection: true,
+      profile: false,
+      pool: { min: 2, max: 10 },
+      acquireConnectionTimeout: 1e4,
+      ssl: { rejectUnauthorized: false },
+      logger: console,
+      name: "default",
+      ...config2
+    };
+    this.logger = this.config.logger;
+    const instance2 = this;
+    const callableWrapper = function(...args) {
+      throw new Error("This should never be called directly");
+    };
+    callableWrapper._instance = instance2;
+    return new Proxy(callableWrapper, {
+      // Intercept function calls: db('table')
+      apply: (target, thisArg, argumentsList) => {
+        const inst = target._instance;
+        if (!inst.knexInstance) {
+          throw new Error("Db: Not connected. Call connect() first.");
+        }
+        return inst.knexInstance(...argumentsList);
+      },
+      // Intercept property access: db.schema, db.raw, etc.
+      get: (target, prop) => {
+        if (prop === "_instance") {
+          return target._instance;
+        }
+        const instance3 = target._instance;
+        const ownMethods = [
+          "connect",
+          "disconnect",
+          "testConnection",
+          "tableExists",
+          "getQueryLog",
+          "getKnex",
+          "isConnectedToDb",
+          "getErrorMessage",
+          "detectClient",
+          "attachProfiler"
+        ];
+        if (prop in instance3) {
+          const value = instance3[prop];
+          if (typeof value === "function" && ownMethods.includes(prop)) {
+            return value.bind(instance3);
+          }
+          if (typeof value !== "function") {
+            return value;
+          }
+        }
+        if (instance3.knexInstance) {
+          const knexProp = instance3.knexInstance[prop];
+          if (typeof knexProp === "function") {
+            return knexProp.bind(instance3.knexInstance);
+          }
+          return knexProp;
+        }
+        if (prop in instance3) {
+          const method = instance3[prop];
+          if (typeof method === "function") {
+            return method.bind(instance3);
+          }
+          return method;
+        }
+        return void 0;
+      }
+    });
+  }
+  /**
+   * Detect database client type from connection string
+   */
+  detectClient(connectionString) {
+    if (connectionString.match(/^postgresql/)) {
+      return "pg";
+    }
+    if (connectionString.match(/^mysql/)) {
+      return "mysql2";
+    }
+    return null;
+  }
+  /**
+   * Connect to the database
+   */
+  async connect() {
+    if (this.isConnected && this.knexInstance) {
+      this.logger.warn?.("[Db] Already connected");
+      return;
+    }
+    const client = this.detectClient(this.config.connectionString);
+    if (!client) {
+      throw new ParamError(
+        `Db: Cannot determine client type from connection string. Expected postgresql:// or mysql://`
+      );
+    }
+    try {
+      const connectionConfig = {
+        connectionString: this.config.connectionString,
+        family: 4
+        // Force IPv4 only (disable IPv6)
+      };
+      this.knexInstance = (0, import_knex.default)({
+        client,
+        connection: connectionConfig,
+        pool: this.config.pool,
+        acquireConnectionTimeout: this.config.acquireConnectionTimeout,
+        ...this.config.ssl && { ssl: this.config.ssl }
+      });
+      if (this.config.profile) {
+        this.attachProfiler();
+      }
+      if (this.config.testConnection) {
+        await this.testConnection();
+      }
+      this.isConnected = true;
+      this.logger.debug?.(`[Db] Connected to database "${this.config.name || this.config.connectionString}"`);
+    } catch (error) {
+      if (error instanceof ParamError) {
+        throw error;
+      }
+      const errorMsg = this.getErrorMessage(error);
+      throw new ParamError(`Db: Connection failed - ${errorMsg}`);
+    }
+  }
+  /**
+   * Disconnect from the database
+   */
+  async disconnect() {
+    if (!this.knexInstance) {
+      return;
+    }
+    try {
+      await this.knexInstance.destroy();
+      this.knexInstance = null;
+      this.isConnected = false;
+      this.queriesLog = [];
+      this.logger.debug?.(`[Db] Disconnected from database "${this.config.name || this.config.connectionString}"`);
+    } catch (error) {
+      const errorMsg = this.getErrorMessage(error);
+      this.logger.error?.(`[Db] Error disconnecting: ${errorMsg}`);
+      throw error;
+    }
+  }
+  /**
+   * Extract error message from various error types
+   */
+  getErrorMessage(error) {
+    if (error instanceof AggregateError) {
+      const errors = error.errors || [];
+      if (errors.length > 0) {
+        const firstError = errors[0];
+        const firstErrorMsg = firstError instanceof Error ? firstError.message : String(firstError);
+        const allSimilar = errors.every((e) => {
+          const msg = e instanceof Error ? e.message : String(e);
+          const codeMatch = msg.match(/^(\w+)\s/);
+          const firstCodeMatch = firstErrorMsg.match(/^(\w+)\s/);
+          return codeMatch && firstCodeMatch && codeMatch[1] === firstCodeMatch[1];
+        });
+        if (allSimilar && errors.length > 1) {
+          const addresses = errors.map((e) => {
+            const msg = e instanceof Error ? e.message : String(e);
+            const addrMatch = msg.match(/([:\d.]+:\d+)/);
+            return addrMatch ? addrMatch[1] : null;
+          }).filter(Boolean);
+          if (addresses.length > 0) {
+            const codeMatch = firstErrorMsg.match(/^(\w+)\s/);
+            const code = codeMatch ? codeMatch[1] : "Connection error";
+            return `${code} (tried: ${addresses.join(", ")})`;
+          }
+        }
+        const uniqueMessages = [...new Set(errors.map((e) => {
+          return e instanceof Error ? e.message : String(e);
+        }))];
+        if (uniqueMessages.length === 1) {
+          return uniqueMessages[0];
+        }
+        return uniqueMessages.join("; ");
+      }
+      return error.message || "Multiple errors occurred";
+    }
+    if (error instanceof Error) {
+      const errorWithCode = error;
+      if (errorWithCode.code) {
+        return `${errorWithCode.code}: ${error.message || String(error)}`;
+      }
+      return error.message || String(error);
+    }
+    if (typeof error === "string") {
+      return error;
+    }
+    if (error?.message) {
+      const msg = String(error.message);
+      const errorWithCode = error;
+      if (errorWithCode.code) {
+        return `${errorWithCode.code}: ${msg}`;
+      }
+      return msg;
+    }
+    return String(error) || "Unknown error";
+  }
+  /**
+   * Test database connection
+   */
+  async testConnection() {
+    if (!this.knexInstance) {
+      throw new Error("Db: Not connected. Call connect() first.");
+    }
+    try {
+      const result = await this.knexInstance.raw("SELECT 2+3 AS result");
+      const isOk = result.rows?.[0]?.result === 5 || result[0]?.[0]?.result === 5;
+      this.logger.debug?.(`[Db] Connection test: ${isOk ? "OK" : "FAILED"}`);
+      return isOk;
+    } catch (error) {
+      const errorMsg = this.getErrorMessage(error);
+      this.logger.error?.(`[Db] Connection test failed: ${errorMsg}`);
+      throw new ParamError(`Db: Connection test failed - ${errorMsg}`);
+    }
+  }
+  /**
+   * Attach query profiler to log all queries
+   */
+  attachProfiler() {
+    if (!this.knexInstance) {
+      return;
+    }
+    this.queriesLog = [];
+    this.knexInstance.queriesLog = this.queriesLog;
+    this.knexInstance.on("query", (query) => {
+      query.__startTime = process.hrtime();
+    });
+    this.knexInstance.on("query-response", (response, query) => {
+      const [seconds, nanoseconds] = process.hrtime(query.__startTime);
+      const executionTimeMs = (seconds * 1e3 + nanoseconds / 1e6).toFixed(2);
+      const logEntry = {
+        sql: query.sql,
+        bindings: query.bindings || [],
+        executionTimeMs
+      };
+      this.queriesLog.push(logEntry);
+      this.logger.debug?.(`[Db] Query: ${query.sql} | Duration: ${executionTimeMs}ms`);
+    });
+    this.knexInstance.on("query-error", (error, query) => {
+      this.logger.error?.(`[Db] Query failed: ${query.sql}`, error);
+    });
+  }
+  /**
+   * Get query log (only available if profiling is enabled)
+   */
+  getQueryLog() {
+    return [...this.queriesLog];
+  }
+  /**
+   * Check if a table exists
+   */
+  async tableExists(tableName) {
+    if (!this.knexInstance) {
+      throw new Error("Db: Not connected. Call connect() first.");
+    }
+    try {
+      return await this.knexInstance.schema.hasTable(tableName);
+    } catch (error) {
+      this.logger.error?.(`[Db] Error checking table existence: ${error.message}`);
+      throw error;
+    }
+  }
+  /**
+   * Get the underlying Knex instance (for advanced usage)
+   */
+  getKnex() {
+    if (!this.knexInstance) {
+      throw new Error("Db: Not connected. Call connect() first.");
+    }
+    return this.knexInstance;
+  }
+  /**
+   * Get connection status
+   */
+  isConnectedToDb() {
+    return this.isConnected && this.knexInstance !== null;
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Args,
+  Db,
   Divider,
   FileDatabase,
   FileDatabaseError,