@nmakarov/cli-toolkit 0.2.0 → 0.3.0

package/README.md

@@ -4,11 +4,21 @@ A comprehensive TypeScript toolkit for building professional CLI applications wi
 
 [![npm version](https://img.shields.io/npm/v/@nmakarov/cli-toolkit.svg)](https://www.npmjs.com/package/@nmakarov/cli-toolkit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/nmakarov/cli-toolkit/workflows/CI/badge.svg)](https://github.com/nmakarov/cli-toolkit/actions)
+[![codecov](https://codecov.io/gh/nmakarov/cli-toolkit/branch/main/graph/badge.svg)](https://codecov.io/gh/nmakarov/cli-toolkit)
+[![Known Vulnerabilities](https://snyk.io/test/github/nmakarov/cli-toolkit/badge.svg)](https://snyk.io/test/github/nmakarov/cli-toolkit)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
+[![Node Version](https://img.shields.io/node/v/@nmakarov/cli-toolkit.svg)](https://nodejs.org)
+[![npm downloads](https://img.shields.io/npm/dm/@nmakarov/cli-toolkit.svg)](https://www.npmjs.com/package/@nmakarov/cli-toolkit)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@nmakarov/cli-toolkit)](https://bundlephobia.com/package/@nmakarov/cli-toolkit)
 
 ## Features
 
 - 🎯 **Args** - Powerful argument parser with config files, environment variables, and precedence rules
 - ✅ **Params** - Type-safe parameter validation with Joi schemas and cross-parameter references
+- 🌐 **HttpClient** - Resilient HTTP client with automatic retry, error classification, and unified responses
+- 🧪 **MockServer** - HTTP mock server with FileDatabase integration for API testing
+- 💾 **FileDatabase** - Versioned file storage with chunking, pagination, and legacy compatibility
 - 🖥️ **Screen** - Interactive terminal UIs with React/Ink (lists, menus, grids, navigation)
 - 📝 **Logger** - Structured logging with levels, progress tracking, and IPC routing
 - ⚡ **Errors** - Custom error classes for framework-specific error handling
@@ -52,7 +62,7 @@ node app.js --verbose --port=8080 build deploy
 
 [📖 Full Args Documentation](docs/ARGS.md)
 
-### Params - Validate Parameters
+### Params - Validate Parameters.
 
 ```typescript
 import { Params } from '@nmakarov/cli-toolkit/params';
@@ -80,6 +90,107 @@ node app.js --name="My App" --port=8080 --tags="api,web" --startDate="-7d"
 
 [📖 Full Params Documentation](docs/PARAMS.md)
 
+### HttpClient - Resilient HTTP Requests
+
+```typescript
+import { HttpClient } from '@nmakarov/cli-toolkit/http-client';
+
+const client = new HttpClient({
+    timeout: 10000,
+    retryCount: 3,
+    retryDelay: 1000
+});
+
+// Always returns unified response - never throws!
+const response = await client.get('https://api.example.com/users', {
+    params: { limit: 10 },
+    headers: { 'Authorization': 'Bearer token' }
+});
+
+if (response.status === 'success') {
+    console.log('Users:', response.data);
+} else {
+    console.log('Error:', response.error); // Human-readable: 'connectionFailed', 'timeout', etc.
+}
+```
+
+```bash
+# Features:
+# - Automatic retry with exponential backoff
+# - Human-readable error classification
+# - All HTTP methods (GET, POST, PUT, DELETE, PATCH, etc.)
+# - Per-request configuration overrides
+# - Comprehensive logging
+```
+
+[📖 Full HttpClient Documentation](docs/HTTP_CLIENT.md)
+
+### FileDatabase - Structured File Storage
+
+```typescript
+import { FileDatabase } from '@nmakarov/cli-toolkit/filedatabase';
+
+// Versioned mode (default) - creates timestamped folders
+const db = new FileDatabase({
+    basePath: './data',
+    namespace: 'api',
+    tableName: 'responses'
+});
+
+// Non-versioned mode - for single objects
+const db = new FileDatabase({
+    basePath: './data',
+    namespace: 'cache',
+    tableName: 'user-profile',
+    versioned: false
+});
+
+await db.write(userData);
+const data = await db.read(); // Auto-detects latest version
+const hasData = await db.hasData();
+```
+
+```bash
+# Features:
+# - Versioned/non-versioned storage modes
+# - Automatic chunking for large datasets
+# - Pagination for efficient reading
+# - Legacy format compatibility
+# - Custom synopsis functions
+```
+
+[📖 Full FileDatabase Documentation](docs/FILEDATABASE.md)
+
+### MockServer - HTTP Mock Server
+
+```typescript
+import { MockServer } from '@nmakarov/cli-toolkit/mock-server';
+
+const mockServer = new MockServer({
+    basePath: './mocks',
+    port: 5030
+});
+
+await mockServer.start();
+
+// Capture responses
+await mockServer.storeMock('https://api.example.com/users', null, response);
+
+// Use with HttpClient for testing
+const client = new HttpClient({ useTestServer: 'http://localhost:5030' });
+```
+
+```bash
+# Features:
+# - Express.js HTTP server with FileDatabase storage
+# - Request/response capture and replay
+# - Sensitive data masking
+# - Automatic catalog management
+# - Test server redirection support
+```
+
+[📖 Full MockServer Documentation](docs/MOCK_SERVER.md)
+
 ### Screen - Interactive Terminal UIs
 
 ```typescript

package/dist/{filestore.cjs → filedatabase.cjs}

@@ -27,17 +27,17 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// src/filestore.ts
-var filestore_exports = {};
-__export(filestore_exports, {
+// src/filedatabase.ts
+var filedatabase_exports = {};
+__export(filedatabase_exports, {
   FileDatabase: () => FileDatabase,
   FileDatabaseError: () => FileDatabaseError,
   defaultFileSynopsisFunction: () => defaultFileSynopsisFunction,
   defaultVersionSynopsisFunction: () => defaultVersionSynopsisFunction
 });
-module.exports = __toCommonJS(filestore_exports);
+module.exports = __toCommonJS(filedatabase_exports);
 
-// src/filestore/index.ts
+// src/filedatabase/index.ts
 var import_fs3 = __toESM(require("fs"), 1);
 var import_path3 = __toESM(require("path"), 1);
 
@@ -113,7 +113,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";
@@ -159,7 +159,7 @@ var ParamError = class extends FrameworkError {
   }
 };
 
-// src/filestore/synopsis-functions.ts
+// src/filedatabase/synopsis-functions.ts
 function defaultFileSynopsisFunction(fileEntry, data) {
   if (!Array.isArray(data) || data.length === 0) {
     return { ...fileEntry };
@@ -227,7 +227,7 @@ function defaultVersionSynopsisFunction(metadata) {
   return result;
 }
 
-// src/filestore/index.ts
+// src/filedatabase/index.ts
 var FileDatabaseError = class extends Error {
   constructor(message) {
     super(message);
@@ -238,6 +238,7 @@ var FileDatabase = class {
   basePath;
   namespace;
   tableName = null;
+  versioned;
   maxVersions;
   pageSize;
   useMetadata;
@@ -261,6 +262,7 @@ var FileDatabase = class {
     this.basePath = config.basePath;
     this.namespace = config.namespace || "default";
     this.tableName = config.tableName || null;
+    this.versioned = config.versioned ?? true;
     this.maxVersions = config.maxVersions || 5;
     this.pageSize = config.pageSize || 5e3;
     this.useMetadata = config.useMetadata !== false;
@@ -283,14 +285,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_path3.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_path3.default.resolve(...parts);
   }
   /**
    * Set current version and version folder
@@ -301,8 +310,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) {
@@ -330,8 +344,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);
@@ -346,6 +364,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_fs3.default.existsSync(tablePath)) {
+      return false;
+    }
+    if (this.versioned) {
+      const versions = await this.getVersions();
+      return versions.length > 0;
+    } else {
+      const items = await import_fs3.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_fs3.default.existsSync(tablePath)) {
+      return { versioned: false, hasMetadata: false, dataType: null };
+    }
+    const items = await import_fs3.default.promises.readdir(tablePath);
+    if (items.includes("metadata.json")) {
+      const metadata = JSON.parse(
+        await import_fs3.default.promises.readFile(import_path3.default.join(tablePath, "metadata.json"), "utf8")
+      );
+      return {
+        versioned: false,
+        hasMetadata: true,
+        dataType: metadata.dataType || null
+      };
+    }
+    const versionFolders = items.filter((item) => {
+      const itemPath = import_path3.default.join(tablePath, item);
+      const stat = import_fs3.default.statSync(itemPath);
+      return stat.isDirectory() && isTimestampFolder(item);
+    });
+    if (versionFolders.length > 0) {
+      const latestVersion = versionFolders.sort().pop();
+      const versionMetadataPath = import_path3.default.join(tablePath, latestVersion, "metadata.json");
+      return {
+        versioned: true,
+        hasMetadata: import_fs3.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
    */
@@ -489,11 +587,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_path3.default.join(this.getDestinationPath(), this.currentVersion, "metadata.json");
+    let metadataFile;
+    if (this.versioned) {
+      if (!this.currentVersion) {
+        return;
+      }
+      metadataFile = import_path3.default.join(this.getDestinationPath(), this.currentVersion, "metadata.json");
+    } else {
+      metadataFile = import_path3.default.join(this.getDestinationPath(), "metadata.json");
+    }
     await import_fs3.default.promises.writeFile(metadataFile, JSON.stringify(metadataToSave, null, 4), "utf8");
   }
   /**
@@ -621,31 +727,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_path3.default.join(this.getDestinationPath(), "metadata.json");
+          if (import_fs3.default.existsSync(metadataPath)) {
+            try {
+              const rawData = await import_fs3.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_path3.default.join(this.getDestinationPath(), "metadata.json");
+          if (import_fs3.default.existsSync(metadataPath)) {
+            try {
+              const rawData = await import_fs3.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("");
+        }
       }
     }
   }
@@ -653,6 +803,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();
@@ -661,11 +814,12 @@ var FileDatabase = class {
       this.makeNewFile();
     }
     let { dataToWrite, dataLeftOver, fileName } = this.figureOutDataAndFileToWrite(data);
-    await this.safeWrite(import_path3.default.join(this.currentVersionFolder, fileName), dataToWrite);
+    const destPath = this.getDestinationPath(this.currentVersion || void 0);
+    await this.safeWrite(import_path3.default.join(destPath, fileName), dataToWrite);
     this.updateMetadata(dataToWrite, fileName);
     while (dataLeftOver && dataLeftOver.length > 0) {
       const writeContext = this.figureOutDataAndFileToWrite(dataLeftOver);
-      await this.safeWrite(import_path3.default.join(this.currentVersionFolder, writeContext.fileName), writeContext.dataToWrite);
+      await this.safeWrite(import_path3.default.join(destPath, writeContext.fileName), writeContext.dataToWrite);
       this.updateMetadata(writeContext.dataToWrite, writeContext.fileName);
       dataLeftOver = writeContext.dataLeftOver;
     }
@@ -683,7 +837,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_path3.default.join(this.getDestinationPath(), this.currentVersion, file.fileName);
+      const filePath = import_path3.default.join(this.getDestinationPath(this.currentVersion || void 0), file.fileName);
       try {
         const rawData = await import_fs3.default.promises.readFile(filePath, "utf8");
         return deserializeData(rawData, this.metadata.dataType);
@@ -721,7 +875,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_path3.default.join(this.getDestinationPath(), this.currentVersion, file.fileName);
+      const filePath = import_path3.default.join(this.getDestinationPath(this.currentVersion || void 0), file.fileName);
       try {
         const rawData = await import_fs3.default.promises.readFile(filePath, "utf8");
         const fileData = deserializeData(rawData, this.metadata.dataType);
@@ -791,4 +945,4 @@ var FileDatabase = class {
   defaultFileSynopsisFunction,
   defaultVersionSynopsisFunction
 });
-//# sourceMappingURL=filestore.cjs.map
+//# sourceMappingURL=filedatabase.cjs.map