axiodb 22.27.1 → 22.28.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "axiodb",
-  "version": "22.27.1",
+  "version": "22.28.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",

package/benchmark/run.js

@@ -1,785 +0,0 @@
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const { execSync } = require('child_process');
-const DEFAULT_BENCHMARK_DIR = path.resolve(__dirname, './Benchmark_TempData');
-let activeBenchmarkDir = DEFAULT_BENCHMARK_DIR;
-
-// Auto-build if lib is missing
-const libEntry = path.resolve(__dirname, '../lib/config/DB.js');
-if (!fs.existsSync(libEntry)) {
-  console.log('\x1b[33m[Benchmark] Compiled lib/ not found. Running build first...\x1b[0m');
-  execSync('npm run build', {
-    stdio: 'inherit',
-    cwd: path.resolve(__dirname, '..')
-  });
-}
-
-const { AxioDB } = require('../lib/config/DB.js');
-
-// ANSI Color formatting
-const c = {
-  reset: '\x1b[0m',
-  bright: '\x1b[1m',
-  dim: '\x1b[2m',
-  green: '\x1b[32m',
-  yellow: '\x1b[33m',
-  blue: '\x1b[34m',
-  magenta: '\x1b[35m',
-  cyan: '\x1b[36m',
-  red: '\x1b[31m',
-  gray: '\x1b[90m'
-};
-
-// Parse command line arguments
-function parseArgs() {
-  const args = process.argv.slice(2);
-  const options = {
-    docs: 15000,           // Default set to 15k
-    batchSize: 3000,       // Default batch size set to 3k
-    queries: 500,          // Indexed read lookups
-    unindexedSamples: 25,  // Unindexed full-scan lookups (scan over dataset)
-    updateQueries: 100,    // Indexed updates
-    deleteQueries: 50,     // Indexed deletes
-    keepData: false,       // Auto-delete temp data by default
-    dir: DEFAULT_BENCHMARK_DIR
-  };
-
-  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') {
-      console.log(`
-AxioDB Performance & Scale Benchmark Suite
-
-Usage:
-  node benchmark/run.js [options]
-  npm run benchmark -- [options]
-
-Options:
-  --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);
-    }
-  }
-
-  // Adjust batch size if docs < batchSize
-  if (options.docs < options.batchSize) {
-    options.batchSize = options.docs;
-  }
-
-  options.batch = options.batchSize;
-  return options;
-}
-
-// Convert BigInt nanoseconds to milliseconds float
-function nsToMs(ns) {
-  return Number(ns) / 1e6;
-}
-
-// Format bytes into readable MB
-function bytesToMB(bytes) {
-  return (bytes / (1024 * 1024)).toFixed(2);
-}
-
-// Format bytes into readable string (B, KB, MB)
-function bytesToReadable(bytes) {
-  if (bytes < 1024) return `${bytes} B`;
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} KB`;
-  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
-}
-
-function safeRate(count, durationMs) {
-  if (count <= 0 || durationMs <= 0) return 0;
-  return Math.round((count / durationMs) * 1000);
-}
-
-function clampWorkload(requested, available, minimum = 0) {
-  if (available <= 0) return 0;
-  return Math.max(minimum, Math.min(requested, available));
-}
-
-// Calculate directory sizes recursively (Total vs Data-only vs Indexes)
-function calculateDirSizes(dirPath) {
-  let totalBytes = 0;
-  let withoutIndexBytes = 0;
-  let indexBytes = 0;
-  let docCount = 0;
-
-  function traverse(currentPath) {
-    if (!fs.existsSync(currentPath)) return;
-    const entries = fs.readdirSync(currentPath, { withFileTypes: true });
-    for (const entry of entries) {
-      const fullPath = path.join(currentPath, entry.name);
-      if (entry.isDirectory()) {
-        traverse(fullPath);
-      } else if (entry.isFile()) {
-        try {
-          const stats = fs.statSync(fullPath);
-          totalBytes += stats.size;
-          // Index files: inside "indexes" folder or ending in .jsonl
-          const isIndexFile = fullPath.includes(`${path.sep}indexes${path.sep}`) ||
-                              fullPath.endsWith('.jsonl') ||
-                              entry.name === 'index.meta.jsonl';
-          if (isIndexFile) {
-            indexBytes += stats.size;
-          } else {
-            withoutIndexBytes += stats.size;
-            if (entry.name.endsWith('.axiodb')) {
-              docCount++;
-            }
-          }
-        } catch (_) {}
-      }
-    }
-  }
-
-  traverse(dirPath);
-  return { totalBytes, withoutIndexBytes, indexBytes, docCount };
-}
-
-// Enhanced Percentile calculator (min, p25, p50, p75, p90, p95, p99, max, avg)
-function calculatePercentiles(latencies) {
-  if (!latencies || latencies.length === 0) {
-    return {
-      min: '0.000',
-      p25: '0.000',
-      p50: '0.000',
-      p75: '0.000',
-      p90: '0.000',
-      p95: '0.000',
-      p99: '0.000',
-      max: '0.000',
-      avg: '0.000'
-    };
-  }
-
-  const sorted = [...latencies].sort((a, b) => a - b);
-  const getP = (p) => sorted[Math.min(Math.floor((p / 100) * sorted.length), sorted.length - 1)];
-  const sum = sorted.reduce((acc, v) => acc + v, 0);
-
-  return {
-    min: Number(sorted[0]).toFixed(3),
-    p25: Number(getP(25)).toFixed(3),
-    p50: Number(getP(50)).toFixed(3),
-    p75: Number(getP(75)).toFixed(3),
-    p90: Number(getP(90)).toFixed(3),
-    p95: Number(getP(95)).toFixed(3),
-    p99: Number(getP(99)).toFixed(3),
-    max: Number(sorted[sorted.length - 1]).toFixed(3),
-    avg: (sum / sorted.length).toFixed(3)
-  };
-}
-
-// Helper to remove directory cleanly (robust recursive deletion)
-function cleanDirectory(dirPath) {
-  try {
-    if (fs.existsSync(dirPath)) {
-      fs.rmSync(dirPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
-    }
-  } catch (err) {
-    // Ignore cleanup race conditions
-  }
-}
-
-// Format percentiles output line
-function printPercentiles(stats, indent = '    ') {
-  console.log(`${indent}${c.dim}• Min:${c.reset}  ${stats.min.padStart(7)} ms | ${c.dim}p25:${c.reset}  ${stats.p25.padStart(7)} ms | ${c.dim}p50 (Med):${c.reset} ${stats.p50.padStart(7)} ms`);
-  console.log(`${indent}${c.dim}• p75:${c.reset}  ${stats.p75.padStart(7)} ms | ${c.dim}p90:${c.reset}  ${stats.p90.padStart(7)} ms | ${c.dim}p95:${c.reset}       ${stats.p95.padStart(7)} ms`);
-  console.log(`${indent}${c.dim}• p99:${c.reset}  ${stats.p99.padStart(7)} ms | ${c.dim}Max:${c.reset}  ${stats.max.padStart(7)} ms | ${c.dim}Avg:${c.reset}       ${stats.avg.padStart(7)} ms`);
-}
-
-// Fast document batch generator with both indexed and unindexed fields
-function generateBatch(startIdx, count) {
-  const batch = new Array(count);
-  for (let i = 0; i < count; i++) {
-    const id = startIdx + i;
-    batch[i] = {
-      // Indexed fields: email, age, score, name
-      name: `User_${id}`,
-      email: `user_${id}@bench.axiodb.org`,
-      age: 18 + (id % 62),
-      score: id % 1000,
-      // Unindexed fields: region, unindexedTag, metadata
-      region: ['us-east', 'us-west', 'eu-central', 'ap-south'][id % 4],
-      unindexedTag: `tag_${id}`,
-      metadata: {
-        loginCount: id % 50,
-        tier: id % 10 === 0 ? 'enterprise' : 'standard'
-      },
-      active: id % 2 === 0,
-      createdAt: new Date().toISOString()
-    };
-  }
-  return batch;
-}
-
-async function runBenchmark() {
-  const opts = parseArgs();
-  activeBenchmarkDir = opts.dir;
-  const initMem = process.memoryUsage();
-
-  console.log(`\n${c.bright}${c.cyan}╔═══════════════════════════════════════════════════════════════════╗${c.reset}`);
-  console.log(`${c.bright}${c.cyan}║             AxioDB Performance & Scale Benchmark Suite           ║${c.reset}`);
-  console.log(`${c.bright}${c.cyan}╚═══════════════════════════════════════════════════════════════════╝${c.reset}`);
-
-  console.log(`\n${c.bright}System Environment:${c.reset}`);
-  console.log(`  ${c.dim}• Platform:${c.reset}          ${os.type()} ${os.release()} (${os.arch()})`);
-  console.log(`  ${c.dim}• CPUs:${c.reset}              ${os.cpus().length} cores (${os.cpus()[0]?.model || 'Generic'})`);
-  console.log(`  ${c.dim}• Total RAM:${c.reset}         ${(os.totalmem() / 1e9).toFixed(2)} GB`);
-  console.log(`  ${c.dim}• Available RAM:${c.reset}     ${(os.freemem() / 1e9).toFixed(2)} GB`);
-  console.log(`  ${c.dim}• Process RAM Initial:${c.reset} RSS: ${bytesToMB(initMem.rss)} MB | Heap: ${bytesToMB(initMem.heapUsed)} MB`);
-  console.log(`  ${c.dim}• Node.js:${c.reset}           ${process.version} (V8: ${process.versions.v8})`);
-  console.log(`  ${c.dim}• Target Scale:${c.reset}      ${opts.docs.toLocaleString()} documents (Batch Size: ${opts.batchSize.toLocaleString()})`);
-
-  // Setup cleanup handler for interrupts
-  const cleanup = () => {
-    if (!opts.keepData) {
-      cleanDirectory(opts.dir);
-    }
-  };
-
-  process.on('SIGINT', () => {
-    console.log(`\n${c.yellow}Benchmark interrupted. Cleaning up test data...${c.reset}`);
-    cleanup();
-    process.exit(1);
-  });
-
-  process.on('SIGTERM', () => {
-    console.log(`\n${c.yellow}Benchmark terminated. Cleaning up test data...${c.reset}`);
-    cleanup();
-    process.exit(1);
-  });
-
-  // Ensure clean test directory before start
-  cleanDirectory(opts.dir);
-
-  let peakMemory = process.memoryUsage().heapUsed;
-  let peakRss = process.memoryUsage().rss;
-  let storageFootprint = { totalBytes: 0, withoutIndexBytes: 0, indexBytes: 0, docCount: 0 };
-
-  const trackMemory = () => {
-    const mem = process.memoryUsage();
-    if (mem.heapUsed > peakMemory) peakMemory = mem.heapUsed;
-    if (mem.rss > peakRss) peakRss = mem.rss;
-  };
-
-  console.log(`\n${c.bright}${c.blue}[1/6] Initializing Database & Indexes...${c.reset}`);
-  const db = new AxioDB({ GUI: false, RootName: 'BenchmarkDB', CustomPath: opts.dir });
-  const testDB = await db.createDB('BenchDB');
-  const collection = await testDB.createCollection('Users');
-
-  // Create multi-field indexes before bulk ingestion
-  console.log(`  ${c.dim}Creating indexes on (email, age, score, name)...${c.reset}`);
-  const idxStart = process.hrtime.bigint();
-  await collection.newIndex('email', 'age', 'score', 'name');
-  const idxDuration = nsToMs(process.hrtime.bigint() - idxStart);
-  console.log(`  ${c.green}✓ Indexes created in ${idxDuration.toFixed(2)}ms${c.reset}`);
-
-  // -------------------------------------------------------------
-  // PHASE 1: Bulk Ingestion (insertMany)
-  // -------------------------------------------------------------
-  console.log(`\n${c.bright}${c.blue}[2/6] Ingesting ${opts.docs.toLocaleString()} Documents in Batches of ${opts.batchSize.toLocaleString()}...${c.reset}`);
-  const totalBatches = Math.ceil(opts.docs / opts.batchSize);
-  let totalInserted = 0;
-
-  const ingestStartTime = process.hrtime.bigint();
-
-  for (let b = 0; b < totalBatches; b++) {
-    const currentBatchCount = Math.min(opts.batchSize, opts.docs - totalInserted);
-    const batch = generateBatch(totalInserted, currentBatchCount);
-
-    const batchStart = process.hrtime.bigint();
-    const res = await collection.insertMany(batch);
-    const batchDuration = nsToMs(process.hrtime.bigint() - batchStart);
-
-    if (res && (res.status === true || res.statusCode === 200)) {
-      totalInserted += currentBatchCount;
-    } else {
-      console.error(`${c.red}Failed inserting batch ${b + 1}: ${JSON.stringify(res)}${c.reset}`);
-      break;
-    }
-
-    trackMemory();
-    const currentMem = process.memoryUsage();
-    const rate = Math.round((currentBatchCount / (batchDuration / 1000)));
-    const percent = Math.round((totalInserted / opts.docs) * 100);
-    process.stdout.write(`  ${c.dim}Batch ${b + 1}/${totalBatches} (${percent}%): ${totalInserted.toLocaleString()} docs | ${rate.toLocaleString()} docs/sec | ${batchDuration.toFixed(0)}ms | RSS: ${bytesToMB(currentMem.rss)}MB | Heap: ${bytesToMB(currentMem.heapUsed)}MB\r${c.reset}`);
-  }
-
-  const totalIngestTimeMs = nsToMs(process.hrtime.bigint() - ingestStartTime);
-  const overallIngestRate = safeRate(totalInserted, totalIngestTimeMs);
-
-  console.log(`\n  ${c.green}✓ Ingestion Complete: ${totalInserted.toLocaleString()} docs in ${(totalIngestTimeMs / 1000).toFixed(2)}s (${c.bright}${overallIngestRate.toLocaleString()} docs/sec${c.reset}${c.green})${c.reset}`);
-
-  const countCheck = await collection.totalDocuments();
-  const confirmedTotal = countCheck?.data?.total ?? totalInserted;
-  console.log(`  ${c.dim}Verified physical document count: ${confirmedTotal.toLocaleString()} on disk${c.reset}`);
-
-  // Measure exact storage footprint on disk while all documents are present
-  storageFootprint = calculateDirSizes(opts.dir);
-  console.log(`  ${c.dim}Directory Size:${c.reset} Total: ${bytesToReadable(storageFootprint.totalBytes)} | Data only (no index): ${bytesToReadable(storageFootprint.withoutIndexBytes)} | Indexes: ${bytesToReadable(storageFootprint.indexBytes)}`);
-
-  const readQueryCount = clampWorkload(opts.queries, totalInserted, 1);
-  const unindexedReadSamples = clampWorkload(opts.unindexedSamples, totalInserted, 1);
-  const indexedUpdateCount = clampWorkload(opts.updateQueries, totalInserted, 1);
-  const indexedDeleteCount = clampWorkload(opts.deleteQueries, totalInserted, 0);
-  const remainingAfterIndexedDeletes = Math.max(totalInserted - indexedDeleteCount, 0);
-  const unindexedDeleteCount = clampWorkload(opts.unindexedSamples, remainingAfterIndexedDeletes, 0);
-
-  if (
-    readQueryCount !== opts.queries ||
-    unindexedReadSamples !== opts.unindexedSamples ||
-    indexedUpdateCount !== opts.updateQueries ||
-    indexedDeleteCount !== opts.deleteQueries ||
-    unindexedDeleteCount !== opts.unindexedSamples
-  ) {
-    console.log(`\n  ${c.yellow}⚠ Adjusted benchmark operation counts for current dataset size (${totalInserted.toLocaleString()} docs).${c.reset}`);
-    console.log(`  ${c.dim}Indexed reads:${c.reset} ${readQueryCount} | ${c.dim}Unindexed reads:${c.reset} ${unindexedReadSamples} | ${c.dim}Indexed updates:${c.reset} ${indexedUpdateCount} | ${c.dim}Indexed deletes:${c.reset} ${indexedDeleteCount} | ${c.dim}Unindexed deletes:${c.reset} ${unindexedDeleteCount}`);
-  }
-
-  // -------------------------------------------------------------
-  // PHASE 2: Read Latency: Indexed vs Unindexed
-  // -------------------------------------------------------------
-  console.log(`\n${c.bright}${c.blue}[3/6] Testing Read Latency (Indexed vs Unindexed)...${c.reset}`);
-
-  // 2A: Indexed Point Reads
-  console.log(`  ${c.dim}• Testing Indexed Point Reads (${readQueryCount.toLocaleString()} random exact matches)...${c.reset}`);
-  const indexedReadLatencies = [];
-  const readStart = process.hrtime.bigint();
-
-  for (let q = 0; q < readQueryCount; q++) {
-    const targetId = Math.floor(Math.random() * totalInserted);
-    const targetEmail = `user_${targetId}@bench.axiodb.org`;
-
-    const qStart = process.hrtime.bigint();
-    const result = await collection.query({ email: targetEmail }).exec();
-    const qDuration = nsToMs(process.hrtime.bigint() - qStart);
-
-    if (result && (result.status === true || result.statusCode === 200) && result.data?.documents?.length > 0) {
-      indexedReadLatencies.push(qDuration);
-    }
-  }
-
-  const totalReadTimeMs = nsToMs(process.hrtime.bigint() - readStart);
-  const readQPS = safeRate(readQueryCount, totalReadTimeMs);
-  const indexedReadStats = calculatePercentiles(indexedReadLatencies);
-
-  console.log(`  ${c.green}✓ Indexed Reads:${c.reset} ${indexedReadLatencies.length}/${readQueryCount} successful (${c.bright}${readQPS.toLocaleString()} QPS${c.reset})`);
-  printPercentiles(indexedReadStats);
-
-  // 2B: Unindexed Reads (Full Collection Scan)
-  console.log(`\n  ${c.dim}• Testing Unindexed Point Reads (${unindexedReadSamples} full-scan lookups on 'unindexedTag')...${c.reset}`);
-  const unindexedReadLatencies = [];
-  const unindexedReadStart = process.hrtime.bigint();
-
-  for (let q = 0; q < unindexedReadSamples; q++) {
-    const targetId = Math.floor(Math.random() * totalInserted);
-    const targetTag = `tag_${targetId}`;
-
-    const uStart = process.hrtime.bigint();
-    const result = await collection.query({ unindexedTag: targetTag }).exec();
-    const uDuration = nsToMs(process.hrtime.bigint() - uStart);
-
-    if (result && (result.status === true || result.statusCode === 200) && result.data?.documents?.length > 0) {
-      unindexedReadLatencies.push(uDuration);
-    }
-  }
-
-  const totalUnindexedReadTime = nsToMs(process.hrtime.bigint() - unindexedReadStart);
-  const unindexedReadQPS = safeRate(unindexedReadSamples, totalUnindexedReadTime);
-  const unindexedReadStats = calculatePercentiles(unindexedReadLatencies);
-
-  console.log(`  ${c.green}✓ Unindexed Reads:${c.reset} ${unindexedReadLatencies.length}/${unindexedReadSamples} successful (${unindexedReadQPS.toLocaleString()} QPS)`);
-  printPercentiles(unindexedReadStats);
-
-  const indexAdvantage = (Number(unindexedReadStats.avg) / Math.max(Number(indexedReadStats.avg), 0.001)).toFixed(1);
-  console.log(`  ${c.cyan}⚡ Index Advantage:${c.reset} Indexed reads are ${c.bright}${indexAdvantage}x faster${c.reset} than unindexed full scans`);
-
-  // -------------------------------------------------------------
-  // PHASE 3: Update Latency: Indexed vs Unindexed
-  // -------------------------------------------------------------
-  console.log(`\n${c.bright}${c.blue}[4/6] Testing Update Latency (UpdateOne: Indexed vs Unindexed)...${c.reset}`);
-
-  // 3A: Indexed Updates
-  console.log(`  ${c.dim}• Testing Indexed UpdateOne (${indexedUpdateCount} queries on indexed 'email')...${c.reset}`);
-  const indexedUpdateLatencies = [];
-
-  for (let u = 0; u < indexedUpdateCount; u++) {
-    const targetId = Math.floor(Math.random() * totalInserted);
-    const targetEmail = `user_${targetId}@bench.axiodb.org`;
-
-    const uStart = process.hrtime.bigint();
-    const res = await collection.update({ email: targetEmail }).UpdateOne({ score: 9999 });
-    const uDuration = nsToMs(process.hrtime.bigint() - uStart);
-
-    if (res && (res.status === true || res.statusCode === 200)) {
-      indexedUpdateLatencies.push(uDuration);
-    }
-  }
-
-  const indexedUpdateStats = calculatePercentiles(indexedUpdateLatencies);
-  console.log(`  ${c.green}✓ Indexed Updates:${c.reset} ${indexedUpdateLatencies.length}/${indexedUpdateCount} successful`);
-  printPercentiles(indexedUpdateStats);
-
-  // 3B: Unindexed Updates
-  console.log(`\n  ${c.dim}• Testing Unindexed UpdateOne (${unindexedReadSamples} queries on 'unindexedTag')...${c.reset}`);
-  const unindexedUpdateLatencies = [];
-
-  for (let u = 0; u < unindexedReadSamples; u++) {
-    const targetId = Math.floor(Math.random() * totalInserted);
-    const targetTag = `tag_${targetId}`;
-
-    const uStart = process.hrtime.bigint();
-    const res = await collection.update({ unindexedTag: targetTag }).UpdateOne({ score: 8888 });
-    const uDuration = nsToMs(process.hrtime.bigint() - uStart);
-
-    if (res && (res.status === true || res.statusCode === 200)) {
-      unindexedUpdateLatencies.push(uDuration);
-    }
-  }
-
-  const unindexedUpdateStats = calculatePercentiles(unindexedUpdateLatencies);
-  console.log(`  ${c.green}✓ Unindexed Updates:${c.reset} ${unindexedUpdateLatencies.length}/${unindexedReadSamples} successful`);
-  printPercentiles(unindexedUpdateStats);
-
-  // -------------------------------------------------------------
-  // PHASE 4: Delete Latency: Indexed vs Unindexed
-  // -------------------------------------------------------------
-  console.log(`\n${c.bright}${c.blue}[5/6] Testing Delete Latency (deleteOne: Indexed vs Unindexed)...${c.reset}`);
-
-  // 4A: Indexed Deletes
-  console.log(`  ${c.dim}• Testing Indexed deleteOne (${indexedDeleteCount} deletions by indexed 'email')...${c.reset}`);
-  const indexedDeleteLatencies = [];
-
-  for (let d = 0; d < indexedDeleteCount; d++) {
-    const targetId = totalInserted - 1 - d;
-    if (targetId < 0) break;
-    const targetEmail = `user_${targetId}@bench.axiodb.org`;
-
-    const dStart = process.hrtime.bigint();
-    const res = await collection.delete({ email: targetEmail }).deleteOne();
-    const dDuration = nsToMs(process.hrtime.bigint() - dStart);
-
-    if (res && (res.status === true || res.statusCode === 200)) {
-      indexedDeleteLatencies.push(dDuration);
-    }
-  }
-
-  const indexedDeleteStats = calculatePercentiles(indexedDeleteLatencies);
-  console.log(`  ${c.green}✓ Indexed Deletions:${c.reset} ${indexedDeleteLatencies.length}/${indexedDeleteCount} successful`);
-  printPercentiles(indexedDeleteStats);
-
-  // 4B: Unindexed Deletes
-  console.log(`\n  ${c.dim}• Testing Unindexed deleteOne (${unindexedDeleteCount} deletions by 'unindexedTag')...${c.reset}`);
-  const unindexedDeleteLatencies = [];
-
-  for (let d = 0; d < unindexedDeleteCount; d++) {
-    const targetId = totalInserted - 1 - indexedDeleteCount - d;
-    if (targetId < 0) break;
-    const targetTag = `tag_${targetId}`;
-
-    const dStart = process.hrtime.bigint();
-    const res = await collection.delete({ unindexedTag: targetTag }).deleteOne();
-    const dDuration = nsToMs(process.hrtime.bigint() - dStart);
-
-    if (res && (res.status === true || res.statusCode === 200)) {
-      unindexedDeleteLatencies.push(dDuration);
-    }
-  }
-
-  const unindexedDeleteStats = calculatePercentiles(unindexedDeleteLatencies);
-  console.log(`  ${c.green}✓ Unindexed Deletions:${c.reset} ${unindexedDeleteLatencies.length}/${unindexedDeleteCount} successful`);
-  printPercentiles(unindexedDeleteStats);
-
-  // -------------------------------------------------------------
-  // PHASE 5: In-Memory Cache & ACID Transactions
-  // -------------------------------------------------------------
-  console.log(`\n${c.bright}${c.blue}[6/6] Testing InMemoryCache & ACID Transaction Integrity...${c.reset}`);
-
-  // 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) {
-    const cacheSampleId = Math.floor(Math.random() * remainingForCache);
-    const cacheSampleEmail = `user_${cacheSampleId}@bench.axiodb.org`;
-
-    const coldStart = process.hrtime.bigint();
-    await collection.query({ email: cacheSampleEmail }).exec();
-    coldMs = nsToMs(process.hrtime.bigint() - coldStart);
-
-    const warmLatencies = [];
-    for (let i = 0; i < 100; i++) {
-      const wStart = process.hrtime.bigint();
-      await collection.query({ email: cacheSampleEmail }).exec();
-      warmLatencies.push(nsToMs(process.hrtime.bigint() - wStart));
-    }
-    warmStats = calculatePercentiles(warmLatencies);
-    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})`);
-  } else {
-    console.log(`  ${c.yellow}⚠ Cache Acceleration test skipped:${c.reset} no documents remained after delete phases.`);
-  }
-
-  // ACID Atomic Commit Test (1,000 documents)
-  console.log(`  ${c.dim}• Testing Atomic Commit (1,000 records in 1 transaction)...${c.reset}`);
-  const txCommitStart = process.hrtime.bigint();
-  const txCommit = collection.beginTransaction();
-  for (let i = 0; i < 1000; i++) {
-    txCommit.insert({
-      name: `TxCommit_${i}`,
-      email: `txcommit_${i}@bench.axiodb.org`,
-      age: 28,
-      score: 1000,
-      createdAt: new Date().toISOString()
-    });
-  }
-  const commitRes = await txCommit.commit();
-  const txCommitMs = nsToMs(process.hrtime.bigint() - txCommitStart);
-
-  if (commitRes && (commitRes.status === true || commitRes.statusCode === 200)) {
-    console.log(`  ${c.green}✓ Atomic Commit Verified:${c.reset} 1,000 records committed in ${txCommitMs.toFixed(2)} ms`);
-  } else {
-    console.log(`  ${c.red}✗ Atomic Commit Failed:${c.reset} ${JSON.stringify(commitRes)}`);
-  }
-
-  // ACID Atomic Rollback Test (1,000 documents, 0 data leakage)
-  console.log(`  ${c.dim}• Testing Atomic Rollback (1,000 records staged then rolled back)...${c.reset}`);
-  const countBeforeRollback = await collection.totalDocuments();
-  const docsBefore = countBeforeRollback?.data?.total || 0;
-
-  const txRollback = collection.beginTransaction();
-  for (let i = 0; i < 1000; i++) {
-    txRollback.insert({
-      name: `TxGhost_${i}`,
-      email: `txghost_${i}@bench.axiodb.org`,
-      age: 99,
-      score: 0,
-      createdAt: new Date().toISOString()
-    });
-  }
-  await txRollback.rollback();
-  const countAfterRollback = await collection.totalDocuments();
-  const docsAfter = countAfterRollback?.data?.total || 0;
-
-  if (docsBefore === docsAfter) {
-    console.log(`  ${c.green}✓ ACID Rollback Verified:${c.reset} 100% Consistent (0 leaked records: ${docsBefore.toLocaleString()} before == ${docsAfter.toLocaleString()} after)`);
-  } else {
-    console.log(`  ${c.red}✗ ACID Rollback Failed:${c.reset} Expected ${docsBefore} docs, found ${docsAfter}`);
-  }
-
-  // -------------------------------------------------------------
-  // SUMMARY REPORT
-  // -------------------------------------------------------------
-  trackMemory();
-  const finalMem = process.memoryUsage();
-
-  console.log(`\n${c.bright}${c.cyan}╔═══════════════════════════════════════════════════════════════════╗${c.reset}`);
-  console.log(`${c.bright}${c.cyan}║                    BENCHMARK RESULTS SUMMARY                      ║${c.reset}`);
-  console.log(`${c.bright}${c.cyan}╚═══════════════════════════════════════════════════════════════════╝${c.reset}`);
-
-  console.log(`  ${c.bright}Dataset Scale:${c.reset}                 ${opts.docs.toLocaleString()} Documents`);
-  console.log(`  ${c.bright}Ingestion Throughput:${c.reset}          ${c.green}${overallIngestRate.toLocaleString()} docs/sec${c.reset} (${totalInserted.toLocaleString()} docs in ${(totalIngestTimeMs / 1000).toFixed(2)}s)`);
-  console.log(`  ${c.bright}Indexed Point Read (QPS):${c.reset}      ${c.green}${readQPS.toLocaleString()} QPS${c.reset} (p50: ${indexedReadStats.p50}ms | p95: ${indexedReadStats.p95}ms | p99: ${indexedReadStats.p99}ms)`);
-  console.log(`  ${c.bright}Unindexed Read Scan (QPS):${c.reset}     ${unindexedReadQPS.toLocaleString()} QPS (p50: ${unindexedReadStats.p50}ms | p95: ${unindexedReadStats.p95}ms)`);
-  console.log(`  ${c.bright}Index Read Speedup:${c.reset}            ${c.green}${indexAdvantage}x faster${c.reset} than full scan`);
-  console.log(`  ${c.bright}Indexed Update (p50):${c.reset}          ${indexedUpdateStats.p50} ms (p95: ${indexedUpdateStats.p95}ms)`);
-  console.log(`  ${c.bright}Unindexed Update (p50):${c.reset}        ${unindexedUpdateStats.p50} ms (p95: ${unindexedUpdateStats.p95}ms)`);
-  console.log(`  ${c.bright}Indexed Delete (p50):${c.reset}          ${indexedDeleteStats.p50} ms (p95: ${indexedDeleteStats.p95}ms)`);
-  console.log(`  ${c.bright}Unindexed Delete (p50):${c.reset}        ${unindexedDeleteStats.p50} ms (p95: ${unindexedDeleteStats.p95}ms)`);
-  console.log(`  ${c.bright}Cache Acceleration:${c.reset}            ${cacheSpeedupLabel.includes('x faster') ? `${c.green}${cacheSpeedupLabel}${c.reset}` : cacheSpeedupLabel} (${warmStats.avg}ms warm cache)`);
-  console.log(`  ${c.bright}ACID Commit Latency:${c.reset}           ${txCommitMs.toFixed(2)} ms for 1,000 atomic documents`);
-  console.log(`  ${c.bright}ACID Rollback Integrity:${c.reset}      ${c.green}100% Consistent (0 data leakage)${c.reset}`);
-  console.log(`  ${c.bright}System Available RAM:${c.reset}         ${(os.freemem() / 1e9).toFixed(2)} GB / ${(os.totalmem() / 1e9).toFixed(2)} GB`);
-  console.log(`  ${c.bright}Node Process Peak RAM:${c.reset}        RSS: ${bytesToMB(peakRss)} MB | Heap: ${bytesToMB(peakMemory)} MB`);
-  console.log(`  ${c.bright}Node Process Final RAM:${c.reset}       RSS: ${bytesToMB(finalMem.rss)} MB | Heap: ${bytesToMB(finalMem.heapUsed)} MB`);
-
-  // Dynamic comparison estimation based on sample document
-  const sampleDoc = generateBatch(0, 1)[0];
-  const sampleDocBytes = Buffer.byteLength(JSON.stringify(sampleDoc));
-  const estRawJsonBytes = (sampleDocBytes + 1) * opts.docs + 2;
-  const estLowDBBytes = estRawJsonBytes + 30;
-  const estSQLiteBytes = Math.ceil(((sampleDocBytes * 0.85) + 48) * opts.docs / 4096) * 4096;
-
-  console.log(`\n  ${c.bright}${c.magenta}On-Disk Storage Footprint (${opts.docs.toLocaleString()} Documents):${c.reset}`);
-  console.log(`  ${c.dim}• Total Directory Size (With Indexes):${c.reset}    ${c.green}${bytesToReadable(storageFootprint.totalBytes)}${c.reset} (${bytesToMB(storageFootprint.totalBytes)} MB)`);
-  console.log(`  ${c.dim}• Data Only Size (Excluding Indexes):${c.reset}     ${c.green}${bytesToReadable(storageFootprint.withoutIndexBytes)}${c.reset} (${bytesToMB(storageFootprint.withoutIndexBytes)} MB)`);
-  console.log(`  ${c.dim}• Index Storage Overhead (JSONL / Meta):${c.reset}  ${bytesToReadable(storageFootprint.indexBytes)} (${((storageFootprint.indexBytes / Math.max(storageFootprint.totalBytes, 1)) * 100).toFixed(1)}% of total)`);
-
-  console.log(`\n  ${c.bright}Storage & Architecture Comparison (${opts.docs.toLocaleString()} Records):${c.reset}`);
-  console.log(`  ┌─────────────────────────┬──────────────┬──────────────┬────────────────────────────────────┐`);
-  console.log(`  │ Database Engine         │ Disk Size    │ Storage Type │ Trade-off / Advantage              │`);
-  console.log(`  ├─────────────────────────┼──────────────┼──────────────┼────────────────────────────────────┤`);
-  console.log(`  │ ${c.cyan}AxioDB (Data Only)${c.reset}      │ ${bytesToReadable(storageFootprint.withoutIndexBytes).padEnd(12)} │ File-per-doc │ Zero native C++ deps; atomic WAL   │`);
-  console.log(`  │ ${c.cyan}AxioDB (With Indexes)${c.reset}   │ ${bytesToReadable(storageFootprint.totalBytes).padEnd(12)} │ Data + JSONL │ Sub-ms indexed point reads & cache │`);
-  console.log(`  │ SQLite (Table + Indexes)│ ${('~' + bytesToReadable(estSQLiteBytes)).padEnd(12)} │ Single file  │ Requires C++ native build toolchain│`);
-  console.log(`  │ LowDB (JSON File)       │ ${('~' + bytesToReadable(estLowDBBytes)).padEnd(12)} │ Monolithic   │ Rewrites entire file on every write│`);
-  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);
-    console.log(`\n${c.dim}✓ Completely removed temporary benchmark folder at: ${opts.dir}${c.reset}\n`);
-  } else {
-    console.log(`\n${c.yellow}Preserved benchmark data at: ${opts.dir}${c.reset}\n`);
-  }
-}
-
-runBenchmark().catch((err) => {
-  console.error(`\n${c.red}Benchmark execution encountered an error:${c.reset}`, err);
-  cleanDirectory(activeBenchmarkDir);
-  process.exit(1);
-});

package/funding.json

@@ -1,61 +0,0 @@
-{
-  "version": "v1.1.0",
-  "entity": {
-    "type": "individual",
-    "role": "maintainer",
-    "name": "Ankan Saha",
-    "email": "connect@ankan.in",
-    "description": "Systems engineer and open-source maintainer based in West Bengal, India. Creator of AxioDB, an embedded ACID document database for Node.js and Bun with 27,000+ annual npm downloads.",
-    "webpageUrl": {
-      "url": "https://ankan.in"
-    }
-  },
-  "projects": [
-    {
-      "guid": "axiodb",
-      "name": "AxioDB",
-      "description": "Zero-dependency, pure TypeScript embedded ACID document database for Node.js and Bun. Eliminates native C++ compilation (node-gyp) overhead while providing durability, indexing, and high-concurrency document operations for local and edge environments.",
-      "webpageUrl": {
-        "url": "https://axiodb.in"
-      },
-      "repositoryUrl": {
-        "url": "https://github.com/nexoral/AxioDB"
-      },
-      "licenses": [
-        "spdx:MIT"
-      ],
-      "tags": [
-        "database",
-        "typescript",
-        "nodejs",
-        "embedded",
-        "acid",
-        "developer-tools"
-      ]
-    }
-  ],
-  "funding": {
-    "channels": [
-      {
-        "guid": "bank-transfer",
-        "type": "bank",
-        "address": "Indian Bank Account (Details provided upon grant approval)",
-        "description": "Direct NEFT/IMPS bank transfer for FOSS United grant disbursement."
-      }
-    ],
-    "plans": [
-      {
-        "guid": "axiodb-dev-grant",
-        "status": "active",
-        "name": "AxioDB Engine Scaling & Concurrency Benchmarks",
-        "description": "3-month milestone funding plan to support full-time open-source development: 1) In-memory B-Tree indexer for sub-millisecond query filters; 2) Automated ACID crash-recovery test suite testing process kill durability (SIGKILL resistance); 3) Zero-copy streaming JSON reader for bounded memory consumption under multi-gigabyte collections; 4) Public benchmark dashboard comparing AxioDB with LevelDB and SQLite.",
-        "amount": 75000,
-        "currency": "INR",
-        "frequency": "one-time",
-        "channels": [
-          "bank-transfer"
-        ]
-      }
-    ]
-  }
-}