axiodb 22.27.0 → 22.27.1

package/benchmark/run.js

@@ -47,24 +47,42 @@ function parseArgs() {
     dir: DEFAULT_BENCHMARK_DIR
   };
 
-  for (const arg of args) {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
     if (arg.startsWith('--docs=')) {
       const val = parseInt(arg.split('=')[1], 10);
       if (!isNaN(val) && val > 0) options.docs = val;
+    } else if (arg === '--docs' && i + 1 < args.length) {
+      const val = parseInt(args[++i], 10);
+      if (!isNaN(val) && val > 0) options.docs = val;
     } else if (arg.startsWith('--batch=')) {
       const val = parseInt(arg.split('=')[1], 10);
       if (!isNaN(val) && val > 0) options.batchSize = val;
+    } else if (arg === '--batch' && i + 1 < args.length) {
+      const val = parseInt(args[++i], 10);
+      if (!isNaN(val) && val > 0) options.batchSize = val;
     } else if (arg.startsWith('--queries=')) {
       const val = parseInt(arg.split('=')[1], 10);
       if (!isNaN(val) && val > 0) options.queries = val;
+    } else if (arg === '--queries' && i + 1 < args.length) {
+      const val = parseInt(args[++i], 10);
+      if (!isNaN(val) && val > 0) options.queries = val;
     } else if (arg.startsWith('--unindexed=')) {
       const val = parseInt(arg.split('=')[1], 10);
       if (!isNaN(val) && val > 0) options.unindexedSamples = val;
+    } else if (arg === '--unindexed' && i + 1 < args.length) {
+      const val = parseInt(args[++i], 10);
+      if (!isNaN(val) && val > 0) options.unindexedSamples = val;
     } else if (arg.startsWith('--dir=')) {
       const customDir = arg.split('=')[1];
       if (customDir && customDir.trim()) {
         options.dir = path.resolve(customDir.trim());
       }
+    } else if (arg === '--dir' && i + 1 < args.length) {
+      const customDir = args[++i];
+      if (customDir && customDir.trim()) {
+        options.dir = path.resolve(customDir.trim());
+      }
     } else if (arg === '--keep') {
       options.keepData = true;
     } else if (arg === '--help' || arg === '-h') {
@@ -76,13 +94,13 @@ Usage:
   npm run benchmark -- [options]
 
 Options:
-  --docs=N         Total documents to insert (default: 15000, e.g. 10000, 50000, 100000)
-  --batch=N        Batch chunk size for insertMany (default: 3000)
-  --queries=N      Number of random indexed lookups to test (default: 500)
-  --unindexed=N    Number of unindexed full-scan operations to sample (default: 25)
-  --dir=PATH       Custom benchmark temp directory (default: ./benchmark/Benchmark_TempData)
-  --keep           Keep benchmark database files after run (default: auto-clean)
-  --help, -h       Show this help message
+  --docs=N, --docs N         Total documents to insert (default: 15000, e.g. 10000, 20000)
+  --batch=N, --batch N       Batch chunk size for insertMany (default: 3000)
+  --queries=N, --queries N   Number of random indexed lookups to test (default: 500)
+  --unindexed=N              Number of unindexed full-scan operations to sample (default: 25)
+  --dir=PATH                 Custom benchmark temp directory (default: ./benchmark/Benchmark_TempData)
+  --keep                     Keep benchmark database files after run (default: auto-clean)
+  --help, -h                 Show this help message
 `);
       process.exit(0);
     }
@@ -93,6 +111,7 @@ Options:
     options.batchSize = options.docs;
   }
 
+  options.batch = options.batchSize;
   return options;
 }
 
@@ -524,6 +543,8 @@ async function runBenchmark() {
   // Cache test
   let warmStats = calculatePercentiles([]);
   let cacheSpeedupLabel = 'N/A (insufficient remaining documents)';
+  let coldMs = 0;
+  let cacheSpeedup = null;
   const remainingForCache = totalInserted - indexedDeleteCount - unindexedDeleteCount;
 
   if (remainingForCache > 0) {
@@ -532,7 +553,7 @@ async function runBenchmark() {
 
     const coldStart = process.hrtime.bigint();
     await collection.query({ email: cacheSampleEmail }).exec();
-    const coldMs = nsToMs(process.hrtime.bigint() - coldStart);
+    coldMs = nsToMs(process.hrtime.bigint() - coldStart);
 
     const warmLatencies = [];
     for (let i = 0; i < 100; i++) {
@@ -541,7 +562,7 @@ async function runBenchmark() {
       warmLatencies.push(nsToMs(process.hrtime.bigint() - wStart));
     }
     warmStats = calculatePercentiles(warmLatencies);
-    const cacheSpeedup = (Number(coldMs) / Math.max(Number(warmStats.avg), 0.001)).toFixed(1);
+    cacheSpeedup = (Number(coldMs) / Math.max(Number(warmStats.avg), 0.001)).toFixed(1);
     cacheSpeedupLabel = `${cacheSpeedup}x faster`;
 
     console.log(`  ${c.green}✓ Cache Acceleration:${c.reset} Cold: ${coldMs.toFixed(3)} ms → Warm: ${warmStats.avg} ms (${c.bright}${cacheSpeedupLabel}${c.reset})`);
@@ -645,6 +666,109 @@ async function runBenchmark() {
   console.log(`  │ Raw JSON File           │ ${('~' + bytesToReadable(estRawJsonBytes)).padEnd(12)} │ Single Array │ No indexing; O(N) memory to parse  │`);
   console.log(`  └─────────────────────────┴──────────────┴──────────────┴────────────────────────────────────┘`);
 
+  // Dynamic Architectural Recommendations (computed directly from the run's metrics)
+  console.log(`\n  ${c.bright}${c.cyan}Dynamic Engineering Recommendations (Based on this Run):${c.reset}`);
+
+  const recommendations = [];
+
+  // 1. Query Indexing Strategy
+  const numIndexAdvantage = Number(indexAdvantage);
+  if (!isNaN(numIndexAdvantage) && numIndexAdvantage > 50) {
+    recommendations.push({
+      topic: "Indexing Crucial",
+      text: `Indexed lookups delivered ${numIndexAdvantage.toFixed(1)}x speedup (${indexedReadStats.p50}ms vs ${unindexedReadStats.p50}ms unindexed). Always index fields used in .query(); unindexed scans inspect all ${opts.docs.toLocaleString()} files on disk, causing heavy I/O wait.`
+    });
+  } else {
+    recommendations.push({
+      topic: "Indexing Status",
+      text: `Indexed lookups averaged ${indexedReadStats.p50}ms. As data volume scales beyond ${opts.docs.toLocaleString()} records, ensure query predicates have corresponding indexes.`
+    });
+  }
+
+  // 2. Targeted Mutations (Update & Delete)
+  const unindexedUpdateP50 = Number(unindexedUpdateStats.p50);
+  const indexedUpdateP50 = Number(indexedUpdateStats.p50);
+  const unindexedDeleteP50 = Number(unindexedDeleteStats.p50);
+  const indexedDeleteP50 = Number(indexedDeleteStats.p50);
+  const updateDiff = indexedUpdateP50 > 0 ? (unindexedUpdateP50 / indexedUpdateP50).toFixed(1) : "10+";
+  const deleteDiff = indexedDeleteP50 > 0 ? (unindexedDeleteP50 / indexedDeleteP50).toFixed(1) : "10+";
+
+  if (unindexedUpdateP50 > 150 || Number(updateDiff) >= 2) {
+    recommendations.push({
+      topic: "Targeted Mutations",
+      text: `Mutating via indexed fields is ${updateDiff}x faster for updates (${indexedUpdateStats.p50}ms vs ${unindexedUpdateStats.p50}ms) and ${deleteDiff}x faster for deletes (${indexedDeleteStats.p50}ms vs ${unindexedDeleteStats.p50}ms). Always target records by documentId or indexed keys in .UpdateOne() and .deleteOne().`
+    });
+  }
+
+  // 3. Storage Overhead & Index Pruning
+  const indexRatio = storageFootprint.totalBytes > 0 ? (storageFootprint.indexBytes / storageFootprint.totalBytes) : 0;
+  const indexPercent = (indexRatio * 100).toFixed(1);
+  if (indexRatio > 0.40) {
+    recommendations.push({
+      topic: "Index Pruning",
+      text: `Index files account for ${indexPercent}% (${bytesToReadable(storageFootprint.indexBytes)}) of total on-disk storage. Avoid indexing low-cardinality flags (e.g. isActive) or long text to conserve disk space and minimize multi-index update overhead.`
+    });
+  } else {
+    recommendations.push({
+      topic: "Storage Footprint",
+      text: `Index storage overhead is lean (${indexPercent}% of total directory size), delivering sub-millisecond point lookups without excessive disk usage.`
+    });
+  }
+
+  // 4. In-Memory Cache Optimization
+  const numCacheSpeedup = cacheSpeedup !== null ? Number(cacheSpeedup) : NaN;
+  if (!isNaN(numCacheSpeedup) && numCacheSpeedup > 10) {
+    recommendations.push({
+      topic: "InMemoryCache",
+      text: `Hot-path cache yielded ${numCacheSpeedup.toFixed(1)}x acceleration (${warmStats.avg}ms warm vs ${Number(coldMs).toFixed(2)}ms cold). Keep { Cache: true } enabled for read-heavy records (e.g. user sessions, profiles, configs) to bypass disk and index lookups completely.`
+    });
+  } else if (!isNaN(numCacheSpeedup)) {
+    recommendations.push({
+      topic: "InMemoryCache",
+      text: `Hot-path cache yielded ${numCacheSpeedup.toFixed(1)}x speedup (${warmStats.avg}ms warm vs ${Number(coldMs).toFixed(2)}ms cold). Leverage { Cache: true } for repeating query patterns.`
+    });
+  }
+
+  // 5. Bulk Ingestion & Batch Sizing
+  if (overallIngestRate > 0) {
+    const activeBatch = opts.batchSize || opts.batch || 3000;
+    recommendations.push({
+      topic: "Batch Ingestion",
+      text: `Ingestion sustained ${overallIngestRate.toLocaleString()} docs/sec in batches of ${activeBatch.toLocaleString()}. For large bulk workloads, keeping batch sizes between 2,500 and 5,000 amortizes fsync overhead while keeping memory usage stable.`
+    });
+  }
+
+  // 6. Memory & Host Headroom
+  const freeRamGB = os.freemem() / 1e9;
+  if (freeRamGB < 2.0) {
+    recommendations.push({
+      topic: "Host RAM Tuning",
+      text: `Host system has ${freeRamGB.toFixed(2)} GB free RAM. For heavy workloads, use moderate batch sizes (2,000–3,000) to keep Node RSS headroom safe (${bytesToMB(peakRss)} MB peak observed).`
+    });
+  } else {
+    recommendations.push({
+      topic: "RAM Headroom",
+      text: `Node process consumed ${bytesToMB(peakMemory)} MB peak heap (${bytesToMB(peakRss)} MB RSS) with ${freeRamGB.toFixed(2)} GB host RAM remaining. Memory scaling is well within safe operating limits.`
+    });
+  }
+
+  // 7. Architectural Workload Fit
+  if (opts.docs <= 30000) {
+    recommendations.push({
+      topic: "Workload Fit",
+      text: `At ${opts.docs.toLocaleString()} records, AxioDB is in its ideal sweet spot: pure JavaScript with zero C++ native compiler dependencies, instant cold starts, and sub-millisecond indexed queries make it ideal for CLI utilities, Electron/Tauri desktop apps, and embedded services.`
+    });
+  } else {
+    recommendations.push({
+      topic: "High Volume Scale",
+      text: `At ${opts.docs.toLocaleString()} records, always run on SSD/NVMe storage and use WAL-backed insertMany() for bulk operations, ensuring hot query paths have dedicated indexes.`
+    });
+  }
+
+  recommendations.forEach((rec, idx) => {
+    console.log(`  ${c.dim}[${idx + 1}]${c.reset} ${c.bright}${rec.topic}:${c.reset} ${rec.text}`);
+  });
+
   // Final cleanup of the temporary directory
   if (!opts.keepData) {
     cleanDirectory(opts.dir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "axiodb",
-  "version": "22.27.0",
+  "version": "22.27.1",
   "description": "The embedded database for Node.js. Replaces SQLite, LowDB, NeDB & raw JSON files with MongoDB-style queries, ACID transactions, zero native dependencies, and built-in InMemoryCache. No compilation, no platform issues. Perfect for desktop apps, CLI tools, and embedded systems.",
   "main": "./lib/config/DB.js",
   "types": "./lib/config/DB.d.ts",