@nmakarov/cli-toolkit 0.14.2 → 0.18.0

package/dist/filedatabase.js

@@ -119,6 +119,12 @@ var ParamError = class extends FrameworkError {
     this.name = "ParamError";
   }
 };
+var FileDatabaseError = class extends FrameworkError {
+  constructor(message) {
+    super(message);
+    this.name = "FileDatabaseError";
+  }
+};
 
 // src/filedatabase/synopsis-functions.ts
 function defaultFileSynopsisFunction(fileEntry, data) {
@@ -189,13 +195,7 @@ function defaultVersionSynopsisFunction(metadata) {
 }
 
 // src/filedatabase/index.ts
-var FileDatabaseError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "FileDatabaseError";
-  }
-};
-var FileDatabase = class {
+var FileDatabase = class _FileDatabase {
   basePath;
   namespace;
   tableName = null;
@@ -232,18 +232,8 @@ var FileDatabase = class {
         maxVersions: "number default 5",
         pageSize: "number default 5000"
       };
-      const paramsConfig = context.params.getAll(defs);
-      config = {
-        basePath: opts.basePath ?? paramsConfig.basePath,
-        namespace: opts.namespace ?? paramsConfig.namespace,
-        tableName: opts.tableName ?? paramsConfig.tableName ?? null,
-        versioned: opts.versioned ?? true,
-        maxVersions: opts.maxVersions ?? paramsConfig.maxVersions,
-        pageSize: opts.pageSize ?? paramsConfig.pageSize,
-        useMetadata: opts.useMetadata ?? true,
-        freeSpaceThreshold: opts.freeSpaceThreshold ?? 100 * 1024 * 1024,
-        logger: context.logger
-      };
+      const discovered = context.params.getAllForModule(defs);
+      config = { ...discovered, ...opts, logger: context.logger };
     } else {
       config = contextOrConfig;
     }
@@ -261,6 +251,13 @@ var FileDatabase = class {
     this.logger = config.logger || console;
     this.metadata = this.getDefaultMetadata();
   }
+  /**
+   * Initialize FileDatabase from context and options.
+   * Params are read via getAllForModule("filedatabase", defs) for --showUsedParams grouping.
+   */
+  static init(context, options) {
+    return new _FileDatabase(context, options ?? {});
+  }
   /**
    * Get default metadata structure
    */
@@ -328,7 +325,7 @@ var FileDatabase = class {
     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}`);
+      this.logger.silly?.(`[FileDatabase] Deleting old version: ${versionToDelete}`);
       await fs3.promises.rm(versionToDelete, { recursive: true, force: true });
     }
     return versionName;
@@ -606,7 +603,7 @@ var FileDatabase = class {
     };
     this.metadata.files.push(fileEntry);
     this.lastFileData = null;
-    this.logger.debug?.(`[FileDatabase] Created new file: ${fileEntry.fileName}, fileNumber: ${this.currentFileNumber}`);
+    this.logger.silly?.(`[FileDatabase] Created new file: ${fileEntry.fileName}, fileNumber: ${this.currentFileNumber}`);
   }
   /**
    * Figure out what data to write and which file to use (for pagination)
@@ -639,7 +636,7 @@ var FileDatabase = class {
       const filesBeforeCreate = this.metadata.files.length;
       this.makeNewFile();
       newlyCreatedFileIndex = filesBeforeCreate;
-      this.logger.debug?.(`[FileDatabase] Creating new file for unique custom metadata combination, fileNumber: ${this.currentFileNumber}`);
+      this.logger.silly?.(`[FileDatabase] Creating new file for unique custom metadata combination, fileNumber: ${this.currentFileNumber}`);
     } else if (this.metadata.files.length === 0) {
       this.makeNewFile();
     }
@@ -688,7 +685,7 @@ var FileDatabase = class {
       dataLeftOver = null;
     }
     const fileName = this.metadata.files[this.metadata.files.length - 1].fileName;
-    this.logger.debug?.(
+    this.logger.silly?.(
       `[FileDatabase] figureOutDataAndFileToWrite: filename=${fileName}, forceNewFile=${forceNewFile}, targetFileIndex=${targetFileIndex}, dataToWrite.length=${Array.isArray(dataToWrite) ? dataToWrite.length : "N/A"}, lastFileRecordsCount=${lastFileRecordsCount}`
     );
     return { dataToWrite, dataLeftOver, fileName };
@@ -743,7 +740,7 @@ var FileDatabase = class {
     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?.(
+    this.logger.silly?.(
       `[FileDatabase] Updated metadata for file ${currentFile.fileName}: recordsCount=${recordsCount}, totalRecords=${this.metadata.totalRecords}`
     );
   }
@@ -767,7 +764,7 @@ var FileDatabase = class {
     }
     try {
       await fs3.promises.writeFile(filePath, serializedData, "utf8");
-      this.logger.debug?.(`[FileDatabase] Wrote ${bytesToHumanReadable(requiredBytes)} to ${filePath}`);
+      this.logger.silly?.(`[FileDatabase] Wrote ${bytesToHumanReadable(requiredBytes)} to ${filePath}`);
     } catch (error) {
       throw new FileDatabaseError(`Failed to write file ${filePath}: ${error.message}`);
     }
@@ -849,7 +846,8 @@ var FileDatabase = class {
           this.useMetadata = format.hasMetadata;
         }
         if (this.useMetadata) {
-          const metadataPath = path3.join(this.getDestinationPath(), "metadata.json");
+          const destPath = this.getDestinationPath();
+          const metadataPath = path3.join(destPath, "metadata.json");
           if (fs3.existsSync(metadataPath)) {
             try {
               const rawData = await fs3.promises.readFile(metadataPath, "utf8");
@@ -863,7 +861,9 @@ var FileDatabase = class {
               throw new FileDatabaseError(`Failed to read metadata: ${e.message}`);
             }
           } else {
-            throw new FileDatabaseError("[FileDatabase] No metadata found in non-versioned mode");
+            throw new FileDatabaseError(
+              `[FileDatabase] No metadata found in non-versioned mode. Looked for: ${metadataPath} (table path: ${destPath})`
+            );
           }
         } else {
           this.metadata = await this.figureMetadataFromVersionFiles("");
@@ -880,6 +880,13 @@ var FileDatabase = class {
    * Write data to the file database
    */
   async write(data, options = {}) {
+    if (options.filename) {
+      const destPath2 = this.getDestinationPath();
+      await ensurePath(destPath2);
+      const filePath = path3.join(destPath2, options.filename);
+      await this.safeWrite(filePath, data);
+      return;
+    }
     if (options.forceNewVersion && !this.versioned) {
       throw new FileDatabaseError("Cannot use forceNewVersion in non-versioned mode");
     }
@@ -903,17 +910,17 @@ var FileDatabase = class {
         });
         if (matches) {
           targetFileIndex = i;
-          this.logger.debug?.(`[FileDatabase] Found existing file with matching custom metadata: ${fileEntry.fileName}, metadata: ${JSON.stringify(options.customMetadata)}`);
+          this.logger.silly?.(`[FileDatabase] Found existing file with matching custom metadata: ${fileEntry.fileName}, metadata: ${JSON.stringify(options.customMetadata)}`);
           break;
         } else {
-          this.logger.debug?.(`[FileDatabase] File ${fileEntry.fileName} does not match custom metadata: ${JSON.stringify(options.customMetadata)}`);
+          this.logger.silly?.(`[FileDatabase] File ${fileEntry.fileName} does not match custom metadata: ${JSON.stringify(options.customMetadata)}`);
         }
       }
       if (targetFileIndex === null) {
-        this.logger.debug?.(`[FileDatabase] No existing file found with custom metadata: ${JSON.stringify(options.customMetadata)}, will create new file`);
+        this.logger.silly?.(`[FileDatabase] No existing file found with custom metadata: ${JSON.stringify(options.customMetadata)}, will create new file`);
       }
     } else {
-      this.logger.debug?.(`[FileDatabase] No custom metadata provided, will create new file`);
+      this.logger.silly?.(`[FileDatabase] No custom metadata provided, will create new file`);
     }
     if (targetFileIndex !== null) {
       const targetFile = this.metadata.files[targetFileIndex];
@@ -942,7 +949,17 @@ var FileDatabase = class {
    * Read data from the file database
    */
   async read(options = {}) {
-    const { version, nextPage = false, pageSize } = options;
+    const { version, nextPage = false, pageSize, filename } = options;
+    if (filename) {
+      const destPath = this.getDestinationPath(version);
+      const filePath = path3.join(destPath, filename);
+      try {
+        const rawData = await fs3.promises.readFile(filePath, "utf8");
+        return JSON.parse(rawData);
+      } catch (error) {
+        throw new FileDatabaseError(`Failed to read file ${filename}: ${error.message}`);
+      }
+    }
     await this.prepare({ read: true, version });
     const isNonPaginatedData = this.metadata.dataType === "text" || this.metadata.dataType === "xml" || this.metadata.dataType === "json-object";
     if (isNonPaginatedData) {
@@ -1023,6 +1040,67 @@ var FileDatabase = class {
     this.currentRecord = 0;
     this.hasReadFirstPage = false;
   }
+  /**
+   * List filenames in the table directory.
+   * For catalog/key-value usage (files written with { filename }).
+   * Returns data file names (.json, .txt, .xml) excluding metadata.json.
+   */
+  async listFilenames() {
+    const destPath = this.versioned && this.currentVersion ? path3.join(this.getDestinationPath(), this.currentVersion) : this.getDestinationPath();
+    try {
+      const entries = await fs3.promises.readdir(destPath, { withFileTypes: true });
+      return entries.filter((e) => e.isFile() && e.name !== "metadata.json" && /\.(json|txt|xml)$/i.test(e.name)).map((e) => e.name);
+    } catch (err) {
+      if (err?.code === "ENOENT") return [];
+      throw new FileDatabaseError(`Failed to list files: ${err.message}`);
+    }
+  }
+  /**
+   * Remove a file from the table directory (catalog mode).
+   * Use with listFilenames() to manage individual files.
+   */
+  async removeFile(filename) {
+    const destPath = this.versioned && this.currentVersion ? path3.join(this.getDestinationPath(), this.currentVersion) : this.getDestinationPath();
+    const filePath = path3.join(destPath, filename);
+    try {
+      await fs3.promises.unlink(filePath);
+    } catch (err) {
+      if (err?.code === "ENOENT") return;
+      throw new FileDatabaseError(`Failed to remove file ${filename}: ${err.message}`);
+    }
+  }
+  /**
+   * Remove a file and its metadata entry (non-versioned mode with useMetadata).
+   * Use with findData() to get fileName, then call removeFileEntry to delete.
+   */
+  async removeFileEntry(filename) {
+    if (this.versioned) {
+      throw new FileDatabaseError("removeFileEntry is only supported in non-versioned mode");
+    }
+    await this.prepare({ read: true });
+    const idx = this.metadata.files.findIndex((f) => f.fileName === filename);
+    if (idx === -1) {
+      throw new FileDatabaseError(`File entry ${filename} not found in metadata`);
+    }
+    const entry = this.metadata.files[idx];
+    const recordsCount = entry.recordsCount || 0;
+    this.metadata.files.splice(idx, 1);
+    this.metadata.totalRecords = Math.max(0, (this.metadata.totalRecords || 0) - recordsCount);
+    const destPath = this.getDestinationPath();
+    const filePath = path3.join(destPath, filename);
+    try {
+      await fs3.promises.unlink(filePath);
+    } catch (err) {
+      if (err?.code === "ENOENT") {
+        this.logger.warn?.(`[FileDatabase] File ${filename} already missing on disk`);
+      } else {
+        throw new FileDatabaseError(`Failed to remove file ${filename}: ${err.message}`);
+      }
+    }
+    if (this.useMetadata) {
+      await this.saveVersionMetadata(this.metadata);
+    }
+  }
   /**
    * Set file-level synopsis calculation function
    */
@@ -1126,15 +1204,11 @@ function listSources(basePath) {
     return [];
   }
 }
-function fileDatabaseInit(context, options = {}) {
-  return new FileDatabase(context, options);
-}
 export {
   FileDatabase,
   FileDatabaseError,
   defaultFileSynopsisFunction,
   defaultVersionSynopsisFunction,
-  fileDatabaseInit,
   listSources,
   listTables
 };